gbf-debug-usage

name	gbf-debug-usage
description	Drive the gbf-debug agent CLI to inspect, step, and script Game Boy ROM execution. Use when working with .gbsess files, gbf-debug, the gb JS object, breakpoints, watchpoints, symbols, or Game Boy ROM debugging in this workspace.
license	Proprietary. LICENSE.txt has complete terms
compatibility	Requires the gbf-debug binary built from this workspace
metadata	{"feature":"F-A8","bead":"bd-1aaz"}

gbf-debug Usage

Use this skill when you need to debug a Game Boy ROM through the workspace's agent-facing CLI. The normal loop is: create a session with init, write a small JavaScript script, run it with exec, read the JSON envelope, then repeat with the new .gbsess.

Agent Loop

gbf-debug init --rom target/rom.gb --sym target/rom.sym --out s0.gbsess
gbf-debug exec --in s0.gbsess --script run.js --out s1.gbsess
gbf-debug inspect s1.gbsess

Each command emits exactly one JSON object. Success writes to stdout; failure writes an ErrorEnvelope to stderr. Do not scrape prose output.

For a smoke test in this workspace, use gbf-emu/tests/fixtures/tiny_rom.gb with docs/review/f-a1/artifacts/tiny_rom.sym.

Five Rules

• Set globalThis.result = ...; a lexical let result = ... is not captured.
• Use gb.read / gb.write for side-effect-free debugger access and gb.bus_read / gb.bus_write when you intentionally want CPU-bus side effects.
• Closure predicates are invocation-local and emit a warning; string predicates persist in the session.
• Use gb.snapshot() / gb.restore(handle) for in-script branching. Copy the .gbsess file for cross-invocation forks.
• Every run_until* has a deterministic M-cycle cap. Pass an explicit cap when a script may run long.

Common Script

const entry = gb.symbol("gbf_runtime_dtiny_dentry");
gb.run_until(entry, 100000);
log("at-entry", { regs: gb.regs });
globalThis.result = { pc: gb.regs.pc, a: gb.regs.a };

Symbols

gb.symbol(name) returns an address or null, but raises on banked ambiguity. Use gb.symbol_in_bank(name, bank) or gb.symbol_at_in_bank(addr, bank) when a name or address appears in more than one bank.

Determinism

Date.now() is virtual emulator time, Math.random() is fixed-seeded, and console is unavailable. Use log(message, data) for structured logs; log timestamps use the same virtual clock as Date.now().

References

• references/ENVELOPE.md has the JSON envelope shapes.
• references/GB_OBJECT.md lists the gb.* methods.
• references/PREDICATES.md explains closure vs string predicates.
• references/DETERMINISM.md covers virtual time, budgets, and watchdog behavior.
• assets/recipes/ contains reusable JavaScript snippets.