emoemu 0.1.0

package/src/core/core.ts

@@ -0,0 +1,300 @@
+/**
+ * Core Interface Definitions
+ *
+ * Defines the interface that all system emulator cores must implement.
+ * This enables a multi-core architecture similar to libretro where
+ * different gaming systems can share common infrastructure.
+ */
+
+/**
+ * Button definition for input mapping
+ */
+export interface ButtonDefinition {
+  /** Button ID (0-based index used in setButtonState) */
+  id: number;
+
+  /** Display name (e.g., "A", "Start", "L") */
+  name: string;
+
+  /** Suggested keyboard key */
+  defaultKey: string;
+
+  /** Suggested gamepad button */
+  defaultGamepad: string;
+}
+
+/**
+ * System information describing a core's capabilities and requirements.
+ * This is used by the frontend to configure rendering, audio, and input.
+ */
+export interface SystemInfo {
+  /** Unique identifier (e.g., "nes", "gba") */
+  id: string;
+
+  /** Human-readable name (e.g., "Nintendo Entertainment System") */
+  name: string;
+
+  /** File extensions this core handles (e.g., [".nes", ".unf"]) */
+  extensions: string[];
+
+  /** Native framebuffer width in pixels */
+  width: number;
+
+  /** Native framebuffer height in pixels */
+  height: number;
+
+  /** Target frames per second (e.g., 60.0988 for NES NTSC) */
+  fps: number;
+
+  /** Preferred audio sample rate in Hz */
+  sampleRate: number;
+
+  /** Pixel aspect ratio for correct display (e.g., 8/7 for NES) */
+  pixelAspectRatio: number;
+
+  /** Maximum number of controller ports */
+  maxPlayers: number;
+
+  /** Button definitions for this system */
+  buttons: ButtonDefinition[];
+
+  /**
+   * Framebuffer color format:
+   * - 'rgb15': Uint16Array of 15-bit RGB (xBBBBBGGGGGRRRRR)
+   * - 'rgb24': Uint8Array of RGB triplets
+   */
+  colorSpace: 'rgb15' | 'rgb24';
+
+  /** Core name for netplay (e.g., "PicoDrive") - defaults to name if not set */
+  coreName?: string;
+
+  /** Core version for netplay (e.g., "2.05-3365b17") */
+  coreVersion?: string;
+}
+
+/**
+ * Audio configuration returned by the core
+ */
+export interface AudioConfig {
+  /** Sample rate in Hz */
+  sampleRate: number;
+
+  /** Number of audio channels (1 = mono, 2 = stereo) */
+  channels: 1 | 2;
+}
+
+/**
+ * Severity/importance of a user-facing message.
+ * Values align with libretro SET_MESSAGE_EXT severity levels.
+ */
+export type MessageSeverity = 'debug' | 'info' | 'warn' | 'error';
+
+/**
+ * Message from core to frontend for display to user
+ */
+export interface CoreMessage {
+  /** Message text */
+  msg: string;
+
+  /** Duration in milliseconds (0 = use default) */
+  duration: number;
+
+  /** Priority (higher = more important, displaces lower priority messages) */
+  priority: number;
+
+  /** Message type: 'notification' | 'status' | 'progress' */
+  type: 'notification' | 'status' | 'progress';
+
+  /** Progress value: -1 = indeterminate, 0-100 = percentage (for type='progress') */
+  progress: number;
+
+  /** Severity/importance of the message (default: 'info') */
+  severity: MessageSeverity;
+}
+
+/** Callback for receiving core messages */
+export type CoreMessageCallback = (message: CoreMessage) => void;
+
+/**
+ * Main Core interface that all system emulators must implement.
+ *
+ * The lifecycle is:
+ * 1. Construct the core
+ * 2. Call getSystemInfo() to get capabilities
+ * 3. Call loadRom() to load a game
+ * 4. Optionally call setState() to restore a save state
+ * 5. Call reset() if starting fresh (skipped if restoring state)
+ * 6. Main loop: runFrame(), getFramebuffer(), render
+ * 7. Call destroy() when done
+ */
+export interface Core {
+  //==========================================================================
+  // Lifecycle
+  //==========================================================================
+
+  /**
+   * Get system information describing the core's capabilities.
+   * Can be called before loadRom() to determine if this core handles a ROM.
+   */
+  getSystemInfo(): SystemInfo;
+
+  /**
+   * Load a ROM/game file.
+   * @param romPath Path to the ROM file
+   * @throws Error if ROM is invalid or unsupported
+   */
+  loadRom(romPath: string): void;
+
+  /**
+   * Reset the emulated system to power-on state.
+   * Should be called after loadRom() unless restoring a save state.
+   */
+  reset(): void;
+
+  /**
+   * Clean up resources (close files, release audio, etc.).
+   * Called before destroying the core instance.
+   */
+  destroy(): void;
+
+  //==========================================================================
+  // Emulation
+  //==========================================================================
+
+  /**
+   * Run emulation for one frame.
+   * Updates the framebuffer and generates audio samples via callback.
+   */
+  runFrame(): void;
+
+  /**
+   * Check if the core completed a frame.
+   * Useful for cores with variable-rate timing.
+   */
+  isFrameComplete(): boolean;
+
+  //==========================================================================
+  // Video Output
+  //==========================================================================
+
+  /**
+   * Get the current framebuffer.
+   * Format depends on SystemInfo.colorSpace:
+   * - 'rgb15': Uint16Array of 15-bit RGB values
+   * - 'rgb24': Uint8Array of RGB triplets
+   */
+  getFramebuffer(): Uint8Array | Uint16Array;
+
+  //==========================================================================
+  // Audio Output
+  //==========================================================================
+
+  /**
+   * Get audio configuration (sample rate, channels).
+   */
+  getAudioConfig(): AudioConfig;
+
+  /**
+   * Set callback for audio sample output.
+   * The core calls this callback when audio samples are ready.
+   * @param callback Function to receive Float32Array of samples, or null to disable
+   */
+  setAudioCallback(callback: ((samples: Float32Array) => void) | null): void;
+
+  /**
+   * Set audio enable flag (optional).
+   * Tells the core whether to generate audio samples, allowing cores to
+   * skip audio processing when muted. Not all cores implement this.
+   * @param enabled Whether audio generation is enabled
+   */
+  setAudioEnabled?(enabled: boolean): void;
+
+  /**
+   * Set message callback for core notifications (optional).
+   * Receives messages like "State saved", "Disk inserted", etc.
+   * @param callback Function to receive messages, or null to disable
+   */
+  setMessageCallback?(callback: CoreMessageCallback | null): void;
+
+  //==========================================================================
+  // Input
+  //==========================================================================
+
+  /**
+   * Set button state for a controller.
+   * @param port Controller port (0-based, up to maxPlayers-1)
+   * @param button Button ID from SystemInfo.buttons
+   * @param pressed Whether the button is currently pressed
+   */
+  setButtonState(port: number, button: number, pressed: boolean): void;
+
+  /**
+   * Get current button state for a controller (for status display).
+   * @param port Controller port (0-based)
+   * @returns Map of button ID to pressed state
+   */
+  getButtonState(port: number): Map<number, boolean>;
+
+  /**
+   * Set analog stick axis value (optional - only for cores that support analog input).
+   * @param port Controller port (0-based)
+   * @param index Analog stick (0=left, 1=right)
+   * @param axis Axis (0=X, 1=Y)
+   * @param value Normalized value from -1.0 to 1.0 (or raw int16)
+   */
+  setAnalogState?(port: number, index: number, axis: number, value: number): void;
+
+  //==========================================================================
+  // State Management
+  //==========================================================================
+
+  /**
+   * Serialize the current emulation state for saving.
+   * Returns raw binary data that can be written directly to a file.
+   */
+  getState(): Buffer | null;
+
+  /**
+   * Restore emulation state from a previous save.
+   * @param state Raw binary state data
+   * @throws Error if state is invalid
+   */
+  setState(state: Buffer): void;
+
+  //==========================================================================
+  // Battery/SRAM (Optional - for games with save functionality)
+  //==========================================================================
+
+  /**
+   * Check if the current game has battery-backed save data.
+   * @returns true if the game supports saving to SRAM
+   */
+  hasBatterySave(): boolean;
+
+  /**
+   * Get battery-backed RAM contents for saving to disk.
+   * @returns SRAM data or null if not supported
+   */
+  getBatteryRam(): Uint8Array | null;
+
+  /**
+   * Load battery-backed RAM from disk.
+   * @param data SRAM data to restore
+   */
+  setBatteryRam(data: Uint8Array): void;
+}
+
+/** Type alias for framebuffer data */
+export type FrameBuffer = Uint8Array | Uint16Array;
+
+/** Narrows a framebuffer to Uint16Array when colorSpace is 'rgb15' */
+export const isRgb15Buffer = (
+  colorSpace: 'rgb15' | 'rgb24',
+  _buffer: FrameBuffer,
+): _buffer is Uint16Array => colorSpace === 'rgb15';
+
+/** Narrows a framebuffer to Uint8Array when colorSpace is 'rgb24' */
+export const isRgb24Buffer = (
+  colorSpace: 'rgb15' | 'rgb24',
+  _buffer: FrameBuffer,
+): _buffer is Uint8Array => colorSpace === 'rgb24';

package/src/core/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Core Module Exports
+ *
+ * Re-exports all core interface definitions and button utilities.
+ */
+
+export type {
+  ButtonDefinition,
+  SystemInfo,
+  AudioConfig,
+  Core,
+} from './core';
+
+export {
+  StandardButton,
+  getButtonName,
+  DEFAULT_KEYBOARD_MAP,
+  areOppositeDirections,
+} from './button';

package/src/cores/libretro/api/index.ts

@@ -0,0 +1,334 @@
+/**
+ * Libretro API FFI bindings using koffi
+ */
+
+import koffi from "koffi";
+import type { RetroSystemInfo, RetroSystemAVInfo } from "..";
+import {
+  isPartialRetroSystemInfo,
+  isPartialRetroSystemAVInfo,
+} from "./types";
+
+export * from './types';
+
+// Define koffi struct types for libretro API
+// These are used by koffi internally when binding functions
+koffi.struct("retro_game_geometry", {
+  base_width: "unsigned int",
+  base_height: "unsigned int",
+  max_width: "unsigned int",
+  max_height: "unsigned int",
+  aspect_ratio: "float",
+});
+
+koffi.struct("retro_system_timing", {
+  fps: "double",
+  sample_rate: "double",
+});
+
+koffi.struct("retro_system_av_info", {
+  geometry: "retro_game_geometry",
+  timing: "retro_system_timing",
+});
+
+koffi.struct("retro_system_info", {
+  library_name: "const char*",
+  library_version: "const char*",
+  valid_extensions: "const char*",
+  need_fullpath: "bool",
+  block_extract: "bool",
+});
+
+koffi.struct("retro_game_info", {
+  path: "const char*",
+  data: "const void*",
+  size: "size_t",
+  meta: "const char*",
+});
+
+export const retro_variable = koffi.struct("retro_variable", {
+  key: "const char*",
+  value: "const char*",
+});
+
+// Callback type definitions
+export const retro_environment_t = koffi.proto(
+  "bool retro_environment_t(unsigned int cmd, void* data)"
+);
+// Use const uint8_t* for the framebuffer pointer so koffi can properly decode it
+export const retro_video_refresh_t = koffi.proto(
+  "void retro_video_refresh_t(const uint8_t* data, unsigned int width, unsigned int height, size_t pitch)"
+);
+export const retro_audio_sample_t = koffi.proto(
+  "void retro_audio_sample_t(int16_t left, int16_t right)"
+);
+export const retro_audio_sample_batch_t = koffi.proto(
+  "size_t retro_audio_sample_batch_t(_Inout_ int16_t* data, size_t frames)"
+);
+export const retro_input_poll_t = koffi.proto("void retro_input_poll_t()");
+export const retro_input_state_t = koffi.proto(
+  "int16_t retro_input_state_t(unsigned int port, unsigned int device, unsigned int index, unsigned int id)"
+);
+// Log callback - variadic args not supported in koffi callbacks, so we capture level + format string only.
+// Extra printf args passed by C are ignored (cdecl convention handles stack cleanup on caller side).
+export const retro_log_printf_t = koffi.proto(
+  "void retro_log_printf_t(int level, const char* fmt)"
+);
+
+// Type for koffi registered callback
+export type KoffiCallback = ReturnType<typeof koffi.register>;
+
+ 
+type AnyFunction = (...args: any[]) => any;
+
+/**
+ * LibretroAPI class wraps the native libretro core functions via FFI
+ */
+export class LibretroAPI {
+  private lib: koffi.IKoffiLib;
+
+  // Core lifecycle functions
+  retro_init!: () => void;
+  retro_deinit!: () => void;
+  retro_api_version!: () => number;
+  retro_get_system_info!: AnyFunction;
+  retro_get_system_av_info!: AnyFunction;
+  retro_set_controller_port_device!: (port: number, device: number) => void;
+  retro_reset!: () => void;
+  retro_run!: () => void;
+  retro_load_game!: AnyFunction;
+  retro_unload_game!: () => void;
+  retro_get_region!: () => number;
+
+  // Serialization functions
+  retro_serialize_size!: () => number;
+  retro_serialize!: (data: Buffer, size: number) => boolean;
+  retro_unserialize!: (data: Buffer, size: number) => boolean;
+
+  // Memory access functions
+  retro_get_memory_data!: (id: number) => Buffer | null;
+  retro_get_memory_size!: (id: number) => number;
+
+  // Callback setters
+  retro_set_environment!: (cb: KoffiCallback) => void;
+  retro_set_video_refresh!: (cb: KoffiCallback) => void;
+  retro_set_audio_sample!: (cb: KoffiCallback) => void;
+  retro_set_audio_sample_batch!: (cb: KoffiCallback) => void;
+  retro_set_input_poll!: (cb: KoffiCallback) => void;
+  retro_set_input_state!: (cb: KoffiCallback) => void;
+
+  constructor(corePath: string) {
+    this.lib = koffi.load(corePath);
+    this.bindFunctions();
+  }
+
+  private bindFunctions(): void {
+    // Core lifecycle
+    this.retro_init = this.lib.func("void retro_init()");
+    this.retro_deinit = this.lib.func("void retro_deinit()");
+    this.retro_api_version = this.lib.func("unsigned int retro_api_version()");
+    this.retro_get_system_info = this.lib.func(
+      "void retro_get_system_info(retro_system_info* info)"
+    );
+    this.retro_get_system_av_info = this.lib.func(
+      "void retro_get_system_av_info(retro_system_av_info* info)"
+    );
+    this.retro_set_controller_port_device = this.lib.func(
+      "void retro_set_controller_port_device(unsigned int port, unsigned int device)"
+    );
+    this.retro_reset = this.lib.func("void retro_reset()");
+    this.retro_run = this.lib.func("void retro_run()");
+    this.retro_load_game = this.lib.func(
+      "bool retro_load_game(const retro_game_info* game)"
+    );
+    this.retro_unload_game = this.lib.func("void retro_unload_game()");
+    this.retro_get_region = this.lib.func("unsigned int retro_get_region()");
+
+    // Serialization
+    this.retro_serialize_size = this.lib.func("size_t retro_serialize_size()");
+    this.retro_serialize = this.lib.func(
+      "bool retro_serialize(void* data, size_t size)"
+    );
+    this.retro_unserialize = this.lib.func(
+      "bool retro_unserialize(const void* data, size_t size)"
+    );
+
+    // Memory access
+    this.retro_get_memory_data = this.lib.func(
+      "void* retro_get_memory_data(unsigned int id)"
+    );
+    this.retro_get_memory_size = this.lib.func(
+      "size_t retro_get_memory_size(unsigned int id)"
+    );
+
+    // Callback setters - use koffi pointer() to create proper callback pointer types
+    this.retro_set_environment = this.lib.func(
+      "retro_set_environment",
+      "void",
+      [koffi.pointer(retro_environment_t)]
+    );
+    this.retro_set_video_refresh = this.lib.func(
+      "retro_set_video_refresh",
+      "void",
+      [koffi.pointer(retro_video_refresh_t)]
+    );
+    this.retro_set_audio_sample = this.lib.func(
+      "retro_set_audio_sample",
+      "void",
+      [koffi.pointer(retro_audio_sample_t)]
+    );
+    this.retro_set_audio_sample_batch = this.lib.func(
+      "retro_set_audio_sample_batch",
+      "void",
+      [koffi.pointer(retro_audio_sample_batch_t)]
+    );
+    this.retro_set_input_poll = this.lib.func(
+      "retro_set_input_poll",
+      "void",
+      [koffi.pointer(retro_input_poll_t)]
+    );
+    this.retro_set_input_state = this.lib.func(
+      "retro_set_input_state",
+      "void",
+      [koffi.pointer(retro_input_state_t)]
+    );
+  }
+
+  /**
+   * Get system info from the loaded core
+   */
+  getSystemInfo(): RetroSystemInfo {
+    // Allocate a buffer for the struct
+    const infoType = koffi.resolve("retro_system_info");
+    const infoBuf = Buffer.alloc(koffi.sizeof(infoType));
+
+    // Call the function with the buffer as output
+    this.retro_get_system_info(infoBuf);
+
+    // Decode the result and validate with type guard
+    const decoded: unknown = koffi.decode(infoBuf, infoType);
+    if (!isPartialRetroSystemInfo(decoded)) {
+      return {
+        library_name: "",
+        library_version: "",
+        valid_extensions: "",
+        need_fullpath: false,
+        block_extract: false,
+      };
+    }
+
+    return {
+      library_name: decoded.library_name ?? "",
+      library_version: decoded.library_version ?? "",
+      valid_extensions: decoded.valid_extensions ?? "",
+      need_fullpath: decoded.need_fullpath ?? false,
+      block_extract: decoded.block_extract ?? false,
+    };
+  }
+
+  /**
+   * Get audio/video info from the loaded core (call after loading a game)
+   */
+  getSystemAVInfo(): RetroSystemAVInfo {
+    // Allocate a buffer for the struct
+    const infoType = koffi.resolve("retro_system_av_info");
+    const infoBuf = Buffer.alloc(koffi.sizeof(infoType));
+
+    // Call the function with the buffer as output
+    this.retro_get_system_av_info(infoBuf);
+
+    // Decode the result and validate with type guard
+    const decoded: unknown = koffi.decode(infoBuf, infoType);
+    const defaultResult: RetroSystemAVInfo = {
+      geometry: { base_width: 0, base_height: 0, max_width: 0, max_height: 0, aspect_ratio: 0 },
+      timing: { fps: 0, sample_rate: 0 },
+    };
+
+    if (!isPartialRetroSystemAVInfo(decoded)) {
+      return defaultResult;
+    }
+
+    const { geometry, timing } = decoded;
+
+    return {
+      geometry: {
+        base_width: geometry?.base_width ?? 0,
+        base_height: geometry?.base_height ?? 0,
+        max_width: geometry?.max_width ?? 0,
+        max_height: geometry?.max_height ?? 0,
+        aspect_ratio: geometry?.aspect_ratio ?? 0,
+      },
+      timing: {
+        fps: timing?.fps ?? 0,
+        sample_rate: timing?.sample_rate ?? 0,
+      },
+    };
+  }
+
+  /**
+   * Load a game into the core
+   */
+  loadGame(
+    path: string | null,
+    data: Buffer | null,
+    meta: string | null = null
+  ): boolean {
+    const gameInfo = {
+      path: path,
+      data: data,
+      size: data ? data.length : 0,
+      meta: meta,
+    };
+    return this.retro_load_game(gameInfo) as boolean;
+  }
+
+  /**
+   * Read data from a memory region by ID
+   * Uses koffi.view to get a direct ArrayBuffer view of native memory
+   */
+  getMemoryData(id: number): Uint8Array | null {
+    const size = this.retro_get_memory_size(id);
+    if (size === 0) {return null;}
+
+    const ptr = this.retro_get_memory_data(id);
+    if (!ptr) {return null;}
+
+    // Use koffi.view to get an ArrayBuffer view of native memory
+    const arrayBuffer = koffi.view(ptr, size) as ArrayBuffer;
+    const view = new Uint8Array(arrayBuffer);
+
+    // Copy to a new buffer (don't return the direct view to native memory)
+    const result = new Uint8Array(size);
+    result.set(view);
+    return result;
+  }
+
+  /**
+   * Write data to a memory region by ID
+   * Uses koffi.view to get a writable ArrayBuffer view of native memory
+   */
+  setMemoryData(id: number, data: Uint8Array): void {
+    const size = this.retro_get_memory_size(id);
+    if (size === 0) {return;}
+
+    const ptr = this.retro_get_memory_data(id);
+    if (!ptr) {return;}
+
+    const copySize = Math.min(data.length, size);
+
+    // Use koffi.view to get a writable ArrayBuffer view of native memory
+    const arrayBuffer = koffi.view(ptr, copySize) as ArrayBuffer;
+    const target = new Uint8Array(arrayBuffer);
+
+    // Copy data to the memory region
+    target.set(data.subarray(0, copySize));
+  }
+
+  /**
+   * Unload the library
+   */
+  destroy(): void {
+    // Note: koffi doesn't have a direct unload method for modern versions
+    // The library will be garbage collected when all references are released
+  }
+}