coreif

type BIOSOption struct {
	Key      string        // Unique key, e.g. "main_bios"
	Label    string        // Display label, e.g. "System BIOS"
	Required bool          // true = core cannot run without it
	Variants []BIOSVariant // Known BIOS dumps
}

type BIOSVariant struct {
	Label    string // Display name, e.g. "US v1.0"
	SHA256   string // Expected SHA256 hex
	Filename string // Default filename for system directory lookup
}

type BatterySaver interface {
	// HasSRAM reports whether the loaded ROM uses battery-backed save.
	HasSRAM() bool

	// GetSRAM returns a copy of the current SRAM contents.
	GetSRAM() []byte

	// SetSRAM loads SRAM contents into the emulator.
	SetSRAM(data []byte)
}

type Button struct {
	Name       string
	ID         int    // Bit position in the uint32 bitmask (4+)
	DefaultKey string // Default keyboard key for desktop UI (e.g., "J", "Enter")
	DefaultPad string // Default gamepad button for desktop UI (e.g., "A", "Start")
}

type CoreFactory interface {
	// SystemInfo returns system metadata for UI configuration.
	SystemInfo() SystemInfo

	// CreateEmulator creates a new emulator instance with the given ROM.
	CreateEmulator(rom []byte) (Emulator, error)
}

type CoreOption struct {
	Key         string
	Label       string
	Description string
	Type        CoreOptionType
	Default     string
	Values      []string           // Options for Select type
	Min         int                // Minimum for Range type
	Max         int                // Maximum for Range type
	Step        int                // Step size for Range type
	Category    CoreOptionCategory // Settings section routing
	PerGame     bool               // Whether this can be overridden per game
}

type CoreOptionCategory int

type CoreOptionType int

type Emulator interface {
	// RunFrame executes one frame of emulation.
	RunFrame()

	// GetFramebuffer returns the current frame as RGBA pixel data.
	GetFramebuffer() []byte

	// GetFramebufferStride returns bytes per row in the framebuffer.
	GetFramebufferStride() int

	// GetActiveHeight returns the current active display height in pixels.
	GetActiveHeight() int

	// GetAudioSamples returns stereo 16-bit PCM audio samples for the frame.
	GetAudioSamples() []int16

	// SetInput sets controller state as a button bitmask for the given player.
	SetInput(player int, buttons uint32)

	// GetTiming returns FPS and scanline count for the current region.
	GetTiming() Timing

	// SetOption applies a core option change identified by key.
	SetOption(key string, value string)

	// SetBIOS provides BIOS data for the given key. Called after
	// CreateEmulator and before Start(). Cores without BIOS ignore this.
	SetBIOS(key string, data []byte)

	// Start finalizes emulator state after all options are applied.
	// Must be called after SetOption and before the first RunFrame.
	Start()

	// Close releases any resources held by the emulator.
	Close()
}

type MemoryInspector interface {
	// ReadMemory reads from a flat address into buf and returns the number
	// of bytes read. The core adapter maps flat addresses to internal memory.
	ReadMemory(addr uint32, buf []byte) uint32
}

type MemoryMapper interface {
	// MemoryMap returns a list of available memory regions with sizes.
	MemoryMap() []MemoryRegion

	// ReadRegion returns a copy of the specified memory region.
	ReadRegion(regionType int) []byte

	// WriteRegion writes data to the specified memory region.
	WriteRegion(regionType int, data []byte)
}

type MemoryRegion struct {
	Type int
	Size int
}

type MetadataVariant struct {
	Name          string // Display name, e.g. "Neo Geo Pocket"
	RDBName       string // e.g. "SNK - Neo Geo Pocket"
	ThumbnailRepo string // e.g. "SNK_-_Neo_Geo_Pocket"
	ConsoleID     int    // RetroAchievements console ID override; 0 = use SystemInfo.ConsoleID
}

type SaveStater interface {
	// Serialize captures the complete emulator state.
	Serialize() ([]byte, error)

	// Deserialize restores emulator state from previously serialized data.
	Deserialize(data []byte) error
}

type SystemInfo struct {
	Name             string
	ConsoleName      string
	Extensions       []string
	ScreenWidth      int
	MaxScreenHeight  int
	PixelAspectRatio float64
	SampleRate       int
	Buttons          []Button
	Players          int
	CoreOptions      []CoreOption
	MetadataVariants []MetadataVariant
	DataDirName      string
	ConsoleID        int
	CoreName         string
	CoreVersion      string
	SerializeSize    int
	BigEndianMemory  bool // true for big-endian CPUs (e.g. 68K)
	BIOSOptions      []BIOSOption
}

type Timing struct {
	FPS       int
	Scanlines int
}