@orkosinha/gb-emu-devtools 0.2.0

package/README.md

@@ -0,0 +1,44 @@
+# gb-emu
+
+A cycle-accurate Game Boy and Game Boy Color emulator. Targets WebAssembly (via wasm-pack) and native platforms (via C FFI).
+
+## Packages
+
+| Package | Features | Use case |
+|---|---|---|
+| `@orkosinha/gb-emu` | Core emulator | Production apps |
+| `@orkosinha/gb-emu-devtools` | + Introspection API | Debuggers, dev tools |
+
+## 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
+mise run setup:secrets      # push NPM_TOKEN to GitHub (first time only)
+mise run release -- 0.2.0   # bump version, tag, push → CI publishes both packages
+```

package/gb_emu.d.ts

@@ -0,0 +1,474 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * Game Boy joypad buttons.
+ */
+export enum Button {
+    A = 0,
+    B = 1,
+    Select = 2,
+    Start = 3,
+    Right = 4,
+    Left = 5,
+    Up = 6,
+    Down = 7,
+}
+
+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;
+    apu_ch1_midi_note(): number;
+    /**
+     * CH1 shadow frequency register (internal sweep calculation state).
+     */
+    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;
+    apu_frame_seq_step(): number;
+    /**
+     * NR50: master volume and VIN panning register.
+     */
+    apu_nr50(): number;
+    /**
+     * NR51: left/right channel output routing mask.
+     */
+    apu_nr51(): number;
+    /**
+     * NR52: APU power and channel-active status bits.
+     */
+    apu_nr52(): number;
+    apu_powered(): boolean;
+    /**
+     * Pointer to the per-channel visualization ring buffer.
+     * Layout: 4 channels × 512 bytes; channel c starts at byte c × 512.
+     */
+    apu_viz_ptr(): number;
+    /**
+     * Current write index within each channel's 512-byte slot (0–511).
+     */
+    apu_viz_wp(): number;
+    /**
+     * Discard all samples from the buffer. Call once per frame after consuming.
+     */
+    audio_clear_samples(): void;
+    /**
+     * Number of f32 values in the sample buffer (pairs × 2).
+     */
+    audio_sample_buffer_len(): number;
+    /**
+     * Pointer to the interleaved stereo f32 sample buffer (L, R, L, R, …).
+     * Valid until the next `step_frame` or `step_samples` call.
+     */
+    audio_sample_buffer_ptr(): number;
+    /**
+     * Target sample rate in Hz (44 100).
+     */
+    audio_sample_rate(): number;
+    /**
+     * Current contrast level derived from the dither matrix (0–15, or −1 if unknown).
+     */
+    camera_contrast(): number;
+    camera_live_len(): number;
+    /**
+     * Pointer to the camera live-view RGBA buffer (128×112×4 bytes).
+     */
+    camera_live_ptr(): number;
+    /**
+     * Read a camera hardware register (index 0x00–0x7F → addresses 0xA000–0xA07F).
+     */
+    camera_reg(index: number): number;
+    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 saved photo slot (1–30) to RGBA. Returns empty if unoccupied.
+     */
+    decode_camera_photo(slot: number): Uint8Array;
+    frame_buffer_len(): number;
+    /**
+     * Pointer to the front frame buffer (160×144 RGBA pixels).
+     * Valid until the next `step_frame` call.
+     */
+    frame_buffer_ptr(): number;
+    /**
+     * Colour of `color` (0–3) in BG palette `palette` (0–7) as 0xRRGGBB.
+     */
+    get_bg_palette_color(palette: number, color: number): number;
+    get_cartridge_ram(): Uint8Array;
+    get_cartridge_ram_len(): number;
+    get_cartridge_ram_ptr(): number;
+    /**
+     * Lightweight status string: MBC type, ROM banks, LCDC, LY.
+     */
+    get_debug_info(): string;
+    get_frame_count(): number;
+    get_instruction_count(): bigint;
+    /**
+     * Colour of `color` (0–3) in OBJ palette `palette` (0–7) as 0xRRGGBB.
+     */
+    get_obj_palette_color(palette: number, color: number): number;
+    /**
+     * Serial output as a string (useful for test ROM output on 0xFF01/0xFF02).
+     */
+    get_serial_output(): string;
+    /**
+     * BCPS: BG palette index (bit 7 = auto-increment, bits 5–0 = byte address).
+     */
+    io_bcps(): number;
+    io_bgp(): number;
+    io_div(): number;
+    /**
+     * HDMA5: 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 (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 (same layout as BCPS).
+     */
+    io_ocps(): number;
+    /**
+     * OPRI: Object priority mode (bit 0: 0 = CGB coordinate, 1 = DMG OAM order).
+     */
+    io_opri(): number;
+    io_scx(): number;
+    io_scy(): number;
+    io_stat(): number;
+    /**
+     * SVBK: current WRAM bank (1–7; 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;
+    is_camera(): boolean;
+    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(msg: string): void;
+    log_vram_info(): void;
+    /**
+     * Convert a MIDI note number (0–127) to a 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 `len` bytes from VRAM bank `bank` (0 or 1) at `addr` (0x8000–0x9FFF).
+     * Does not modify VBK — safe to call at any time.
+     */
+    read_vram_bank(bank: number, addr: number, len: number): Uint8Array;
+    /**
+     * Power-cycle: resets CPU, PPU, APU, timer, and MBC banking state.
+     * Save RAM is cleared; call `load_cartridge_ram` afterwards to restore it.
+     */
+    reset(): void;
+    /**
+     * Deliver one byte as if sent by an external device on the serial link.
+     * Fires the serial interrupt (IF bit 3).
+     */
+    serial_receive(byte: number): void;
+    /**
+     * Return and consume the oldest byte transmitted on the serial port,
+     * or `undefined` if nothing was sent.
+     */
+    serial_take_output(): number | undefined;
+    /**
+     * Feed a tilt reading to the MBC7 accelerometer.
+     * `x`/`y` are signed offsets from flat; ±0x1000 ≈ ±1g.
+     */
+    set_accelerometer(x: number, y: number): void;
+    set_button(button: Button, pressed: boolean): void;
+    /**
+     * Set camera image data from a live capture source.
+     * Expects 128×112 pixels as raw 8-bit grayscale (0 = black, 255 = white).
+     */
+    set_camera_image(data: Uint8Array): void;
+    /**
+     * Run one full frame of emulation (~16.74 ms of Game Boy time).
+     */
+    step_frame(): void;
+    /**
+     * Execute a single CPU instruction. Returns T-cycles consumed.
+     */
+    step_instruction(): number;
+    /**
+     * Run until at least `n` stereo sample pairs are in the audio buffer.
+     * Returns the number of pairs actually generated.
+     */
+    step_samples(n: number): number;
+    /**
+     * Update the camera live-view buffer. Returns true if the buffer changed.
+     */
+    update_camera_live(): boolean;
+    /**
+     * Write one byte to cartridge SRAM at flat `.sav` offset `offset`,
+     * bypassing MBC bank selection.
+     */
+    write_cartridge_ram(offset: number, value: number): void;
+    /**
+     * Write a contiguous slice to cartridge SRAM starting at flat offset `offset`.
+     */
+    write_cartridge_ram_range(offset: number, data: Uint8Array): void;
+}
+
+/**
+ * Initialize panic hook for better error messages in WASM.
+ * Called automatically 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_apu_viz_ptr: (a: number) => number;
+    readonly gameboy_apu_viz_wp: (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_cartridge_ram_len: (a: number) => number;
+    readonly gameboy_get_cartridge_ram_ptr: (a: 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_reset: (a: number) => void;
+    readonly gameboy_serial_receive: (a: number, b: number) => void;
+    readonly gameboy_serial_take_output: (a: 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_step_samples: (a: number, b: number) => number;
+    readonly gameboy_update_camera_live: (a: number) => number;
+    readonly gameboy_write_cartridge_ram: (a: number, b: number, c: number) => void;
+    readonly gameboy_write_cartridge_ram_range: (a: number, b: number, c: number, d: number) => void;
+    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>;