@orkosinha/gb-emu 0.1.0

package/README.md

@@ -0,0 +1,38 @@
+# gb-emu
+
+A cycle accurate Game Boy and Game Boy Color emulator. Targets WebAssembly (via wasm-pack) and native platforms (via C FFI).
+
+## Usage
+
+### WASM
+
+```bash
+npm install @orkosinha/gb-emu
+```
+
+API: [`src/wasm.rs`](https://github.com/orkosinha/gb-emu/blob/main/src/wasm.rs)
+
+### C FFI
+
+```bash
+cargo build --features ios --no-default-features --release
+# outputs: target/release/libgb_emu.a + include/gb_emu.h
+```
+
+API: [`include/gb_emu.h`](https://github.com/orkosinha/gb-emu/blob/main/include/gb_emu.h)
+
+### Rust
+
+```toml
+gb-emu = { git = "https://github.com/orkosinha/gb-emu" }
+```
+
+API: [`src/core.rs`](https://github.com/orkosinha/gb-emu/blob/main/src/core.rs)
+
+## Release
+
+```bash
+# add NPM_TOKEN
+mise run setup:secrets      # push token to GitHub
+mise run release -- 0.2.0   # tag + push → CI publishes to npm
+```

package/gb_emu.d.ts

@@ -0,0 +1,425 @@
+/* tslint:disable */
+/* eslint-disable */
+
+export class GameBoy {
+    free(): void;
+    [Symbol.dispose](): void;
+    apu_ch1_dac(): boolean;
+    apu_ch1_duty(): number;
+    apu_ch1_duty_pos(): number;
+    apu_ch1_enabled(): boolean;
+    apu_ch1_env_add(): boolean;
+    apu_ch1_env_period(): number;
+    apu_ch1_freq_hz(): number;
+    apu_ch1_freq_reg(): number;
+    apu_ch1_len_en(): boolean;
+    apu_ch1_length(): number;
+    /**
+     * MIDI note number for CH1 frequency (255 = unknown/out of range).
+     */
+    apu_ch1_midi_note(): number;
+    apu_ch1_shadow_freq(): number;
+    apu_ch1_sweep_neg(): boolean;
+    apu_ch1_sweep_period(): number;
+    apu_ch1_sweep_shift(): number;
+    apu_ch1_volume(): number;
+    apu_ch2_dac(): boolean;
+    apu_ch2_duty(): number;
+    apu_ch2_duty_pos(): number;
+    apu_ch2_enabled(): boolean;
+    apu_ch2_env_add(): boolean;
+    apu_ch2_env_period(): number;
+    apu_ch2_freq_hz(): number;
+    apu_ch2_freq_reg(): number;
+    apu_ch2_len_en(): boolean;
+    apu_ch2_length(): number;
+    apu_ch2_midi_note(): number;
+    apu_ch2_volume(): number;
+    apu_ch3_dac(): boolean;
+    apu_ch3_enabled(): boolean;
+    apu_ch3_freq_hz(): number;
+    apu_ch3_freq_reg(): number;
+    apu_ch3_len_en(): boolean;
+    apu_ch3_length(): number;
+    apu_ch3_midi_note(): number;
+    apu_ch3_vol_code(): number;
+    apu_ch3_wave_pos(): number;
+    /**
+     * Raw wave RAM as 16 bytes (32 × 4-bit nibbles).
+     */
+    apu_ch3_wave_ram(): Uint8Array;
+    apu_ch4_clock_div(): number;
+    apu_ch4_clock_shift(): number;
+    apu_ch4_dac(): boolean;
+    apu_ch4_enabled(): boolean;
+    apu_ch4_env_add(): boolean;
+    apu_ch4_env_period(): number;
+    apu_ch4_freq_hz(): number;
+    apu_ch4_len_en(): boolean;
+    apu_ch4_length(): number;
+    apu_ch4_lfsr(): number;
+    apu_ch4_lfsr_short(): boolean;
+    apu_ch4_volume(): number;
+    /**
+     * Current frame sequencer step (0–7).  Drives length/sweep/envelope clocks.
+     */
+    apu_frame_seq_step(): number;
+    apu_nr50(): number;
+    apu_nr51(): number;
+    apu_nr52(): number;
+    apu_powered(): boolean;
+    /**
+     * Clear the sample buffer after the host has consumed it.
+     */
+    audio_clear_samples(): void;
+    /**
+     * Number of f32 values in the sample buffer (pairs of L/R samples).
+     */
+    audio_sample_buffer_len(): number;
+    /**
+     * Pointer to the interleaved stereo f32 sample buffer (L, R, L, R, …).
+     * Valid until the next call to `step_frame`.
+     */
+    audio_sample_buffer_ptr(): number;
+    /**
+     * Target sample rate in Hz (44 100).
+     */
+    audio_sample_rate(): number;
+    /**
+     * Derive the contrast level (0-15) from the current dither matrix, or -1 if unknown.
+     */
+    camera_contrast(): number;
+    /**
+     * Length of the camera live view buffer.
+     */
+    camera_live_len(): number;
+    /**
+     * Pointer to the camera live view RGBA buffer (128x112x4 bytes).
+     */
+    camera_live_ptr(): number;
+    /**
+     * Read a camera hardware register (0x00-0x7F, corresponding to A000-A07F).
+     */
+    camera_reg(index: number): number;
+    /**
+     * Clear the serial output buffer.
+     */
+    clear_serial_output(): void;
+    cpu_a(): number;
+    cpu_bc(): number;
+    cpu_de(): number;
+    cpu_f(): number;
+    cpu_halted(): boolean;
+    cpu_hl(): number;
+    cpu_ime(): boolean;
+    cpu_pc(): number;
+    cpu_sp(): number;
+    /**
+     * Decode a GB Camera saved photo slot to RGBA pixel data.
+     * Slots 1-30 = saved photos. Returns empty if slot is unoccupied.
+     */
+    decode_camera_photo(slot: number): Uint8Array;
+    frame_buffer_len(): number;
+    frame_buffer_ptr(): number;
+    /**
+     * Colour of `color` (0–3) in BG `palette` (0–7) as 0xRRGGBB.
+     */
+    get_bg_palette_color(palette: number, color: number): number;
+    get_cartridge_ram(): Uint8Array;
+    /**
+     * Get debug info about the emulator state and log to console.
+     */
+    get_debug_info(): string;
+    /**
+     * Get frame count for debugging.
+     */
+    get_frame_count(): number;
+    /**
+     * Get total instruction count for debugging.
+     */
+    get_instruction_count(): bigint;
+    /**
+     * Colour of `color` (0–3) in OBJ `palette` (0–7) as 0xRRGGBB.
+     */
+    get_obj_palette_color(palette: number, color: number): number;
+    /**
+     * Get serial output as a string (for test ROM debugging).
+     */
+    get_serial_output(): string;
+    /**
+     * BCPS: BG palette index register (bit 7 = auto-increment, bits 5–0 = byte address).
+     */
+    io_bcps(): number;
+    io_bgp(): number;
+    io_div(): number;
+    /**
+     * HDMA5: DMA status — 0xFF = idle; otherwise H-blank DMA active, bits 6–0 = remaining blocks − 1.
+     */
+    io_hdma5(): number;
+    io_ie(): number;
+    io_if(): number;
+    io_joypad(): number;
+    /**
+     * KEY1: speed-switch register (bit 7 = current speed, bit 0 = armed).
+     */
+    io_key1(): number;
+    io_lcdc(): number;
+    io_ly(): number;
+    io_lyc(): number;
+    io_obp0(): number;
+    io_obp1(): number;
+    /**
+     * OCPS: OBJ palette index register (same layout as BCPS).
+     */
+    io_ocps(): number;
+    /**
+     * OPRI: Object priority mode (bit 0: 0 = CGB coordinate order, 1 = DMG OAM order).
+     */
+    io_opri(): number;
+    io_scx(): number;
+    io_scy(): number;
+    io_stat(): number;
+    /**
+     * SVBK: current WRAM bank (1–7; bank 0 maps to 1).
+     */
+    io_svbk(): number;
+    io_tac(): number;
+    io_tima(): number;
+    io_tma(): number;
+    /**
+     * VBK: current VRAM bank (0 or 1).
+     */
+    io_vbk(): number;
+    io_wx(): number;
+    io_wy(): number;
+    /**
+     * Check if the loaded ROM is a Game Boy Camera cartridge.
+     */
+    is_camera(): boolean;
+    /**
+     * Check if camera image is ready for capture.
+     */
+    is_camera_ready(): boolean;
+    is_cgb_mode(): boolean;
+    is_mbc7(): boolean;
+    load_cartridge_ram(data: Uint8Array): void;
+    load_rom(rom_data: Uint8Array, cgb_mode: boolean): void;
+    /**
+     * Log a message to the browser console.
+     */
+    log(msg: string): void;
+    /**
+     * Log detailed VRAM tile data for debugging.
+     */
+    log_vram_info(): void;
+    /**
+     * Convert a MIDI note number (0–127) to a note name string like "C-4" or "A#3".
+     */
+    static midi_to_note_name(note: number): string;
+    constructor();
+    ppu_cycles(): number;
+    ppu_line(): number;
+    ppu_mode(): number;
+    read_byte(addr: number): number;
+    read_range(addr: number, len: number): Uint8Array;
+    /**
+     * Read bytes from VRAM at address `addr` (0x8000–0x9FFF) from an explicit bank (0 or 1).
+     * Does not modify the emulator's VBK register — safe to call at any time.
+     */
+    read_vram_bank(bank: number, addr: number, len: number): Uint8Array;
+    /**
+     * Feed a new tilt reading for MBC7 (Kirby's Tilt 'n' Tumble).
+     *
+     * `x` and `y` are signed offsets from flat (0 = no tilt).
+     * Scale: ±0x1000 ≈ ±1g. The WASM host converts DeviceMotion m/s² to this unit.
+     */
+    set_accelerometer(x: number, y: number): void;
+    set_button(button: number, pressed: boolean): void;
+    /**
+     * Set camera image data from webcam.
+     * Expects 128x112 pixels as raw 8-bit grayscale (0=black, 255=white).
+     */
+    set_camera_image(data: Uint8Array): void;
+    step_frame(): void;
+    /**
+     * Execute a single CPU instruction, return cycles consumed.
+     */
+    step_instruction(): number;
+    /**
+     * Update the camera live view buffer if the capture has changed.
+     * Returns true if the buffer was updated.
+     */
+    update_camera_live(): boolean;
+}
+
+/**
+ * Initialize panic hook for better error messages in WASM.
+ * This is called once when the WASM module is instantiated.
+ */
+export function init_panic_hook(): void;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly __wbg_gameboy_free: (a: number, b: number) => void;
+    readonly gameboy_apu_ch1_dac: (a: number) => number;
+    readonly gameboy_apu_ch1_duty: (a: number) => number;
+    readonly gameboy_apu_ch1_duty_pos: (a: number) => number;
+    readonly gameboy_apu_ch1_enabled: (a: number) => number;
+    readonly gameboy_apu_ch1_env_add: (a: number) => number;
+    readonly gameboy_apu_ch1_env_period: (a: number) => number;
+    readonly gameboy_apu_ch1_freq_hz: (a: number) => number;
+    readonly gameboy_apu_ch1_freq_reg: (a: number) => number;
+    readonly gameboy_apu_ch1_len_en: (a: number) => number;
+    readonly gameboy_apu_ch1_length: (a: number) => number;
+    readonly gameboy_apu_ch1_midi_note: (a: number) => number;
+    readonly gameboy_apu_ch1_shadow_freq: (a: number) => number;
+    readonly gameboy_apu_ch1_sweep_neg: (a: number) => number;
+    readonly gameboy_apu_ch1_sweep_period: (a: number) => number;
+    readonly gameboy_apu_ch1_sweep_shift: (a: number) => number;
+    readonly gameboy_apu_ch1_volume: (a: number) => number;
+    readonly gameboy_apu_ch2_dac: (a: number) => number;
+    readonly gameboy_apu_ch2_duty: (a: number) => number;
+    readonly gameboy_apu_ch2_duty_pos: (a: number) => number;
+    readonly gameboy_apu_ch2_enabled: (a: number) => number;
+    readonly gameboy_apu_ch2_env_add: (a: number) => number;
+    readonly gameboy_apu_ch2_env_period: (a: number) => number;
+    readonly gameboy_apu_ch2_freq_hz: (a: number) => number;
+    readonly gameboy_apu_ch2_freq_reg: (a: number) => number;
+    readonly gameboy_apu_ch2_len_en: (a: number) => number;
+    readonly gameboy_apu_ch2_length: (a: number) => number;
+    readonly gameboy_apu_ch2_midi_note: (a: number) => number;
+    readonly gameboy_apu_ch2_volume: (a: number) => number;
+    readonly gameboy_apu_ch3_dac: (a: number) => number;
+    readonly gameboy_apu_ch3_enabled: (a: number) => number;
+    readonly gameboy_apu_ch3_freq_hz: (a: number) => number;
+    readonly gameboy_apu_ch3_freq_reg: (a: number) => number;
+    readonly gameboy_apu_ch3_len_en: (a: number) => number;
+    readonly gameboy_apu_ch3_length: (a: number) => number;
+    readonly gameboy_apu_ch3_midi_note: (a: number) => number;
+    readonly gameboy_apu_ch3_vol_code: (a: number) => number;
+    readonly gameboy_apu_ch3_wave_pos: (a: number) => number;
+    readonly gameboy_apu_ch3_wave_ram: (a: number) => [number, number];
+    readonly gameboy_apu_ch4_clock_div: (a: number) => number;
+    readonly gameboy_apu_ch4_clock_shift: (a: number) => number;
+    readonly gameboy_apu_ch4_dac: (a: number) => number;
+    readonly gameboy_apu_ch4_enabled: (a: number) => number;
+    readonly gameboy_apu_ch4_env_add: (a: number) => number;
+    readonly gameboy_apu_ch4_env_period: (a: number) => number;
+    readonly gameboy_apu_ch4_freq_hz: (a: number) => number;
+    readonly gameboy_apu_ch4_len_en: (a: number) => number;
+    readonly gameboy_apu_ch4_length: (a: number) => number;
+    readonly gameboy_apu_ch4_lfsr: (a: number) => number;
+    readonly gameboy_apu_ch4_lfsr_short: (a: number) => number;
+    readonly gameboy_apu_ch4_volume: (a: number) => number;
+    readonly gameboy_apu_frame_seq_step: (a: number) => number;
+    readonly gameboy_apu_nr50: (a: number) => number;
+    readonly gameboy_apu_nr51: (a: number) => number;
+    readonly gameboy_apu_nr52: (a: number) => number;
+    readonly gameboy_apu_powered: (a: number) => number;
+    readonly gameboy_audio_clear_samples: (a: number) => void;
+    readonly gameboy_audio_sample_buffer_len: (a: number) => number;
+    readonly gameboy_audio_sample_buffer_ptr: (a: number) => number;
+    readonly gameboy_audio_sample_rate: (a: number) => number;
+    readonly gameboy_camera_contrast: (a: number) => number;
+    readonly gameboy_camera_live_len: (a: number) => number;
+    readonly gameboy_camera_live_ptr: (a: number) => number;
+    readonly gameboy_camera_reg: (a: number, b: number) => number;
+    readonly gameboy_clear_serial_output: (a: number) => void;
+    readonly gameboy_cpu_a: (a: number) => number;
+    readonly gameboy_cpu_bc: (a: number) => number;
+    readonly gameboy_cpu_de: (a: number) => number;
+    readonly gameboy_cpu_f: (a: number) => number;
+    readonly gameboy_cpu_halted: (a: number) => number;
+    readonly gameboy_cpu_hl: (a: number) => number;
+    readonly gameboy_cpu_ime: (a: number) => number;
+    readonly gameboy_cpu_pc: (a: number) => number;
+    readonly gameboy_cpu_sp: (a: number) => number;
+    readonly gameboy_decode_camera_photo: (a: number, b: number) => [number, number];
+    readonly gameboy_frame_buffer_len: (a: number) => number;
+    readonly gameboy_frame_buffer_ptr: (a: number) => number;
+    readonly gameboy_get_bg_palette_color: (a: number, b: number, c: number) => number;
+    readonly gameboy_get_cartridge_ram: (a: number) => [number, number];
+    readonly gameboy_get_debug_info: (a: number) => [number, number];
+    readonly gameboy_get_frame_count: (a: number) => number;
+    readonly gameboy_get_instruction_count: (a: number) => bigint;
+    readonly gameboy_get_obj_palette_color: (a: number, b: number, c: number) => number;
+    readonly gameboy_get_serial_output: (a: number) => [number, number];
+    readonly gameboy_io_bcps: (a: number) => number;
+    readonly gameboy_io_bgp: (a: number) => number;
+    readonly gameboy_io_div: (a: number) => number;
+    readonly gameboy_io_hdma5: (a: number) => number;
+    readonly gameboy_io_ie: (a: number) => number;
+    readonly gameboy_io_if: (a: number) => number;
+    readonly gameboy_io_joypad: (a: number) => number;
+    readonly gameboy_io_key1: (a: number) => number;
+    readonly gameboy_io_lcdc: (a: number) => number;
+    readonly gameboy_io_ly: (a: number) => number;
+    readonly gameboy_io_lyc: (a: number) => number;
+    readonly gameboy_io_obp0: (a: number) => number;
+    readonly gameboy_io_obp1: (a: number) => number;
+    readonly gameboy_io_ocps: (a: number) => number;
+    readonly gameboy_io_opri: (a: number) => number;
+    readonly gameboy_io_scx: (a: number) => number;
+    readonly gameboy_io_scy: (a: number) => number;
+    readonly gameboy_io_stat: (a: number) => number;
+    readonly gameboy_io_svbk: (a: number) => number;
+    readonly gameboy_io_tac: (a: number) => number;
+    readonly gameboy_io_tima: (a: number) => number;
+    readonly gameboy_io_tma: (a: number) => number;
+    readonly gameboy_io_vbk: (a: number) => number;
+    readonly gameboy_io_wx: (a: number) => number;
+    readonly gameboy_io_wy: (a: number) => number;
+    readonly gameboy_is_camera: (a: number) => number;
+    readonly gameboy_is_camera_ready: (a: number) => number;
+    readonly gameboy_is_cgb_mode: (a: number) => number;
+    readonly gameboy_is_mbc7: (a: number) => number;
+    readonly gameboy_load_cartridge_ram: (a: number, b: number, c: number) => void;
+    readonly gameboy_load_rom: (a: number, b: number, c: number, d: number) => [number, number];
+    readonly gameboy_log: (a: number, b: number, c: number) => void;
+    readonly gameboy_log_vram_info: (a: number) => void;
+    readonly gameboy_midi_to_note_name: (a: number) => [number, number];
+    readonly gameboy_new: () => number;
+    readonly gameboy_ppu_cycles: (a: number) => number;
+    readonly gameboy_ppu_line: (a: number) => number;
+    readonly gameboy_ppu_mode: (a: number) => number;
+    readonly gameboy_read_byte: (a: number, b: number) => number;
+    readonly gameboy_read_range: (a: number, b: number, c: number) => [number, number];
+    readonly gameboy_read_vram_bank: (a: number, b: number, c: number, d: number) => [number, number];
+    readonly gameboy_set_accelerometer: (a: number, b: number, c: number) => void;
+    readonly gameboy_set_button: (a: number, b: number, c: number) => void;
+    readonly gameboy_set_camera_image: (a: number, b: number, c: number) => void;
+    readonly gameboy_step_frame: (a: number) => void;
+    readonly gameboy_step_instruction: (a: number) => number;
+    readonly gameboy_update_camera_live: (a: number) => number;
+    readonly init_panic_hook: () => void;
+    readonly __wbindgen_free: (a: number, b: number, c: number) => void;
+    readonly __wbindgen_malloc: (a: number, b: number) => number;
+    readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_externrefs: WebAssembly.Table;
+    readonly __externref_table_dealloc: (a: number) => void;
+    readonly __wbindgen_start: () => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;