emucore

package module
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 24, 2026 License: GPL-3.0 Imports: 0 Imported by: 6

README

eblitui-api

Shared API interfaces for the eblitui emulator UI framework. This module defines the contract between emulator cores and UI implementations, allowing each to be developed independently.

Emulator cores implement these interfaces to describe their capabilities. UI implementations consume them to drive rendering, audio, input, save management, and settings without knowing the details of any specific system.

Package

package emucore

import "github.com/user-none/eblitui/api"

Interfaces

CoreFactory

Entry point for the UI. Provides system metadata and creates emulator instances.

  • SystemInfo() SystemInfo - Returns system metadata used by the UI to configure screens, input mapping, settings menus, and data paths.
  • CreateEmulator(rom []byte, region Region) (Emulator, error) - Creates a new emulator instance from ROM data and a video region.
  • DetectRegion(rom []byte) (Region, bool) - Auto-detects the region from ROM data. The bool indicates whether the region was found in a database versus falling back to a default.
Emulator (required)

The core interface every emulator adapter must implement. Covers the per-frame emulation loop: run a frame, read video and audio output, set input, and manage region and timing.

Method Description
RunFrame() Execute one frame of emulation
GetFramebuffer() []byte Current frame as RGBA pixel data
GetFramebufferStride() int Bytes per row in the framebuffer
GetActiveHeight() int Current active display height in pixels
GetAudioSamples() []int16 Stereo 16-bit PCM audio samples for the frame
SetInput(player int, buttons uint32) Set controller state as a button bitmask
GetRegion() Region Current video region
SetRegion(region Region) Change the video region
GetTiming() Timing FPS and scanline count for the current region
SetOption(key string, value string) Apply a core option change by key
SaveStater (optional)

Enables save states, rewind, and auto-save. Implement on the Emulator struct to opt in.

  • Serialize() ([]byte, error) - Capture the complete emulator state.
  • Deserialize(data []byte) error - Restore from previously serialized data.
  • SerializeSize() int - Size of a serialized state in bytes.
BatterySaver (optional)

Enables SRAM persistence for battery-backed saves.

  • HasSRAM() bool - Whether the loaded ROM uses battery-backed save.
  • GetSRAM() []byte - Copy of the current SRAM contents.
  • SetSRAM(data []byte) - Load SRAM contents into the emulator.
MemoryInspector (optional)

Flat address-based memory reads. Used by RetroAchievements to inspect emulator memory without knowing the internal memory map.

  • ReadMemory(addr uint32, buf []byte) uint32 - Read from a flat address into buf. Returns the number of bytes actually read. The core adapter is responsible for mapping flat addresses to internal memory regions.
MemoryMapper (optional)

Named memory region access following the libretro memory model.

  • MemoryMap() []MemoryRegion - List available memory regions with sizes.
  • ReadRegion(regionType int) []byte - Read a copy of the specified region.
  • WriteRegion(regionType int, data []byte) - Write to the specified region.

Region type constants:

Constant Description
MemorySaveRAM Battery-backed save RAM (RETRO_MEMORY_SAVE_RAM)
MemorySystemRAM Main system RAM (RETRO_MEMORY_SYSTEM_RAM)

Types

Region

Video region enumeration. Affects frame rate and scanline count.

Value Description
RegionNTSC NTSC (60 Hz)
RegionPAL PAL (50 Hz)

Implements String() returning "NTSC", "PAL", or "Unknown".

Timing

Frame rate and scanline configuration returned by Emulator.GetTiming().

Field Type Description
FPS int Frames per second
Scanlines int Scanlines per frame

CPU clocks are core-internal and not exposed through this type.

Button

Describes a system-specific button for input mapping.

Field Type Description
Name string Display name (e.g. "A", "Start")
ID int Bit position in the uint32 bitmask

D-pad directions always occupy bits 0-3 via the constants ButtonUp, ButtonDown, ButtonLeft, and ButtonRight. System-specific buttons start at bit 4.

CoreOption

Describes a configurable core setting for use in settings menus.

Field Type Description
Key string Unique identifier passed to SetOption
Label string UI display name
Description string Help text
Type CoreOptionType CoreOptionBool, CoreOptionSelect, or CoreOptionRange
Default string Default value
Values []string Choices (Select type only)
Min int Minimum (Range type only)
Max int Maximum (Range type only)
Step int Step size (Range type only)
Category CoreOptionCategory Settings section: CoreOptionCategoryAudio, CoreOptionCategoryVideo, CoreOptionCategoryInput, CoreOptionCategoryCore
PerGame bool Whether the option can be overridden per game
SystemInfo

System metadata returned by CoreFactory.SystemInfo(). The UI uses this to configure display, input, audio, settings, data paths, and RetroAchievements integration.

Field Type Description
Name string Emulator name (e.g. "emmd")
ConsoleName string Full console name (e.g. "Sega Genesis")
Extensions []string Supported ROM file extensions
ScreenWidth int Native screen width in pixels
MaxScreenHeight int Maximum screen height in pixels
AspectRatio float64 Display aspect ratio
SampleRate int Audio sample rate in Hz
Buttons []Button System-specific buttons
Players int Number of supported players
CoreOptions []CoreOption Configurable core settings
RDBName string RetroAchievements database name
ThumbnailRepo string Thumbnail repository name
DataDirName string Data directory name for saves and config
ConsoleID int Console identifier for RetroAchievements
CoreName string Core implementation name
CoreVersion string Core version string

Implementing a Core

A core implementation consists of two parts:

  1. A factory that implements CoreFactory to provide system metadata and create emulator instances.
  2. An emulator struct that implements Emulator and whichever optional interfaces the core supports.

Optional interfaces are detected at runtime via type assertion, so cores only need to implement what they support.

Documentation

Index

Constants

View Source 
const (
	MemorySaveRAM   = iota // Maps to RETRO_MEMORY_SAVE_RAM
	MemorySystemRAM        // Maps to RETRO_MEMORY_SYSTEM_RAM
)

Memory region type constants for MemoryMapper.

View Source 
const (
	ButtonUp    = 0
	ButtonDown  = 1
	ButtonLeft  = 2
	ButtonRight = 3
)

Standard d-pad button bit positions (always bits 0-3).

Variables

This section is empty.

Functions

This section is empty.

Types

type BatterySaver 

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)
}

BatterySaver enables SRAM persistence for battery-backed saves.

type Button 

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

Button describes a system-specific button with its display name and bit position in the input bitmask.

type CoreFactory 

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

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

	// DetectRegion auto-detects the region from ROM data.
	// The bool return indicates whether the region was found in the database.
	DetectRegion(rom []byte) (Region, bool)
}

CoreFactory creates emulator instances and provides system metadata.

type CoreOption 

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
}

CoreOption describes a configurable core setting.

type CoreOptionCategory added in v0.2.0 

type CoreOptionCategory int

CoreOptionCategory identifies the settings section for a core option. 

const (
	CoreOptionCategoryAudio CoreOptionCategory = iota
	CoreOptionCategoryVideo
	CoreOptionCategoryInput
	CoreOptionCategoryCore
)

type CoreOptionType 

type CoreOptionType int

CoreOptionType identifies the kind of core option. 

const (
	CoreOptionBool CoreOptionType = iota
	CoreOptionSelect
	CoreOptionRange
)

type Emulator 

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)

	// GetRegion returns the current video region.
	GetRegion() Region

	// SetRegion changes the video region.
	SetRegion(region Region)

	// 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)

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

Emulator is the core interface that every emulator adapter must implement.

type MemoryInspector 

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
}

MemoryInspector enables flat address-based memory reads for RetroAchievements.

type MemoryMapper 

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)
}

MemoryMapper enables libretro-style named memory region access.

type MemoryRegion 

type MemoryRegion struct {
	Type int
	Size int
}

MemoryRegion describes a named memory region and its size.

type Region 

type Region int

Region represents a console video region. 

const (
	RegionNTSC Region = iota
	RegionPAL
)

func (Region) String 

func (r Region) String() string

String returns the display name of the region.

type SaveStater 

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

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

SaveStater enables save states, rewind, and auto-save.

type SystemInfo 

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

SystemInfo describes an emulator system for UI configuration.

type Timing 

type Timing struct {
	FPS       int
	Scanlines int
}

Timing holds the frame rate and scanline count for the current region. CPU clocks are core-internal and not exposed here.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.