KOKURA

Prebuilt Windows CLI

The repository now includes kokura-cli.exe at its root. Download the repository ZIP and keep the license notices with the executable. This Windows x64 CLI needs no Rust, Python or .NET installation to run. The build steps below are for rebuilding from source. The independent project code is licensed by DAISUKE OBA under MIT; dependency terms are preserved in BINARY_NOTICES.md and licenses/.

1. What KOKURA does

KOKURA emulates GB/CGB software and records observations of pictures, audio, CPU execution, memory, banks, input and diagnostic events. The command-line executable is kokura-cli.exe.

2. Build and run your first ROM

Push-Location .\kokura
.\scripts\build.ps1
Pop-Location
.\kokura\kokura-cli.exe .\out\hello.gb --run-frames 120 --png .\out\hello.png --dump-report .\out\hello.json

Install Rust and Cargo. Build the named crate when you need only the CLI. Use the hello ROM from Volume 1. The default frame count is one; set --run-frames to reach the scene you want. This counts emulated frames, not seconds of waiting.

3. Choose DMG or CGB

--hardware auto is the default; dmg and cgb are explicit alternatives. Test dual-mode ROMs in both modes. A CGB-only ROM refusing to start as DMG is not, by itself, an emulator failure.

.\kokura\kokura-cli.exe .\out\game.gbc --hardware cgb --run-frames 180 --png .\out\cgb.png

4. Provide input

--input holds a simultaneous button combination; --input-seq supplies a sequence over time. Button names are A,B,START,SELECT,UP,DOWN,LEFT,RIGHT; use NONE for released intervals. Quote sequences containing semicolons in PowerShell.

.\kokura\kokura-cli.exe .\out\game.gb --run-frames 120 --input-seq "NONE:30;A:1;NONE:89" --png .\out\after_a.png --dump-report .\out\after_a.json

Include a released interval when testing press edges. Holding A for 120 frames is different from pressing A 120 times. With the input-counter lesson, the sequence above should increment the count once.

5. Pictures, video and audio

--png saves the final screen. --screenshot with --screenshot-frames captures selected frames. --record-video records video and --record-wav records audio. A silent WAV from a hello program that does not use the APU is expected.

.\kokura\kokura-cli.exe .\out\sound.gb --run-frames 180 --record-wav .\out\sound.wav --record-wav-frames 1:180 --png .\out\sound.png
.\kokura\kokura-cli.exe .\out\game.gb --run-frames 180 --record-video .\out\play.gif --record-video-frames 30:120

Ranges use start:end. Keep the report to distinguish accumulated frame numbers in a loaded state from positions in the current run. Check audible output, pitch, interruptions and clipping separately. Emulator recording does not establish sample-for-sample equality with physical hardware.

6. Save and resume state

.\kokura\kokura-cli.exe .\out\game.gb --run-frames 120 --save-state .\out\title.kqs
.\kokura\kokura-cli.exe .\out\game.gb --load-state .\out\title.kqs --input START --run-frames 30 --save-state .\out\started.kqs --png .\out\started.png

Normally use the same ROM and emulator version. Emulator state is different from a game's own save data. CLI KQS files and the C API's JSON state are different formats; renaming their extensions does not make them interchangeable.

7. Observe symbols and memory

Sidecars named .map, .source_map.txt, .dbg2.json and .build_report.json can be detected beside the ROM. Keep a ROM with its matching sidecars: files from another build can produce misleading observations.

.\kokura\kokura-cli.exe .\out\game.gb --symbols .\out\game.map --watch-window wram:0xC000:0x40 --run-frames 60 --dump-report .\out\watch.json

wram is the observation-window label, 0xC000 is its starting address and 0x40 its length. Small windows make changed variables easier to identify. --watch-baseline-mode selects comparison against initial values, the previous frame or a named baseline.

8. Stop conditions, replay and reverse analysis

--breakpoint, --watchpoint, --run-until and --snapshot-at stop or save on conditions. Their argument mini-languages differ; use the reference and captured help below.

.\kokura\kokura-cli.exe .\out\game.gb --run-frames 120 --replay-interval 1 --replay-max-checkpoints 120 --dump-replay-tape .\out\baseline.replay.json --dump-report .\out\baseline.json
.\kokura\kokura-cli.exe .\out\game.gb --run-frames 120 --replay-interval 1 --compare-replay-tape .\out\baseline.replay.json --dump-report .\out\compare.json

Find the first divergence, then observe a narrower interval around it. --decompile-out produces pseudocode and control-flow information; --disassemble-out displays CPU instructions. Decompilation does not perfectly restore original C code or variable names.

9. Send diagnostics to SARAKURA

.\kokura\kokura-cli.exe .\out\game.gb --run-frames 300 --emit-diagnostics .\out\gb_events.jsonl --dump-report .\out\run.json
.\sarakura\target\debug\sarakura.exe gb analyze --metadata .\out\build.json --events .\out\gb_events.jsonl --out .\out\gb_report --fail-on error

KOKURA --emit-diagnostics takes a JSONL filename, such as out/gb_events.jsonl. An ordinary run-report JSON file or a CPU-trace JSONL file is not the same as diagnostic-event input.

10. Communication jobs

pair models two machines. four_player_adapter is a logical host-selected-peer arrangement. dmg07 models the physical DMG-07 protocol. Supply job JSON with --link-job or configure sessions through --link-topology and --link-session.

.\kokura\kokura-cli.exe --link-topology pair --run-frames 120 --link-session "name=p1|slot=0|rom=out/host.gb|input=NONE" --link-session "name=p2|slot=1|rom=out/peer.gb|input=NONE" --dump-report .\out\pair.json

Each ROM must implement communication. Running two ordinary hello programs does not test the link library. Record each session's ROM, slot, input and state, and identify which physical-device behavior remains untested.

11. External applications

The published C ABI is in kokura-capi; Python access is available through the supplied bridge and Python crate. Establish a minimal CLI reproduction before investigating integration behavior.

12. Read reports in order

Check the executed frames and stop reason first, then the screen, input result, sound, errors and warnings, and profile. A long observation of a title screen with no input can naturally produce static-screen or repeated-PC warnings. Compare warnings with the intended scene rather than mechanically treating every warning as a malfunction.

13. Command recipes and exact argument syntax

Run these PowerShell commands from the directory containing the sibling repositories. Create the output directory first with New-Item -ItemType Directory -Force out. Replace out/game.gb with your own ROM. KOKURA uses options after the ROM path; it does not use KUROSAKI's run subcommand. --help lists the options in the installed executable.

13.1 Choose an operation and a frame budget

Choose one operation per invocation. Dispatch precedence is decompilation, disassembly, regression matrix, link job, inline link sessions, then an ordinary run. Combining modes does not make them run in sequence.

.\kokura\kokura-cli.exe out/game.gb --hardware dmg --run-frames 120 --png out/game.png --dump-report out/run.json

This advances up to 120 emulated frames and saves a final screen and report. Check the report's actual frame count and stop reason before interpreting the picture.

13.2 Hold buttons or supply a timed sequence

Button names are RIGHT,LEFT,UP,DOWN,A,B,SELECT,START. Hexadecimal masks use RIGHT=0x01, LEFT=0x02, UP=0x04, DOWN=0x08, A=0x10, B=0x20, SELECT=0x40, START=0x80. These are KOKURA's input masks; do not reuse NES pad masks. Quote the full sequence in PowerShell. Supply released intervals when testing a new press, and make the sequence cover the intended observation interval.

.\kokura\kokura-cli.exe out/game.gb --run-frames 120 --input-seq "NONE:30;A:1;NONE:89" --png out/after-a.png --dump-report out/after-a.json

For the button-counter sample, this should increase the counter once. A static picture alone cannot establish whether a held button repeats correctly; compare a held interval with separate presses.

13.3 Capture pictures, motion and sound

Capture ranges are decimal and one-based: 30 selects one frame and 30:32 includes frames 30, 31 and 32. Zero and reversed ranges are rejected. Capture indices refer to the current run, so retain the report when resuming an older state. Create parent directories before capture.

.\kokura\kokura-cli.exe out/game.gb --run-frames 180 --record-wav out/audio.wav --record-wav-frames 1:180 --record-video out/motion.gif --record-video-frames 30:120

Use several frames to assess scrolling or animation. Use the WAV to assess sound; a visible completion number does not prove that the intended channel played.

13.4 Save and resume machine state

Use a state matching the ROM and emulator version. KQS is machine state, not cartridge save RAM and not the C API's JSON serialization.

.\kokura\kokura-cli.exe out/game.gb --run-frames 120 --save-state out/title.kqs
.\kokura\kokura-cli.exe out/game.gb --resume-state out/title.kqs --input START --run-frames 30 --png out/started.png --snapshot out/started.kqs

13.5 Inspect named memory windows

Addresses and sizes accept decimal or 0x hexadecimal. Use the current build's symbols to find a variable; 0xC700 below is only an example address, not a standard player location.

.\kokura\kokura-cli.exe out/game.gb --run-frames 60 --watch-window "player:0xC700:16" --watch-fields preview,diff --report-sections cpu,watched_memory --dump-report out/watch.json

13.6 Stop on execution or hardware events

Breakpoint markers pc:, symbol: and @bank: are case-sensitive. Memory addresses and banks use decimal or 0x hexadecimal. Keep a frame budget even when requesting a stop that might never occur.

Observation conditions use && for AND, not C expressions. Supported terms are frame=, ly=, pc=, bank=, bank_pc=bank:pc, symbol=, source=, event=, ppu_mode= (or mode=), and basis=. Frame and LY values are decimal. Symbol, source and event terms match text. Basis values include frame_start, frame_end, step, event, trace, snapshot, stop; bare frame_start, frame_end, stop and vblank are also accepted. Comparisons such as hp<10 are not part of this grammar.

.\kokura\kokura-cli.exe out/game.gb --run-frames 120 --breakpoint "pc:0x0150" --snapshot out/entry.kqs --dump-report out/entry.json
.\kokura\kokura-cli.exe out/game.gb --run-frames 120 --stop-on-mmio "scroll@0xFF43" --dump-report out/scroll-write.json

Use the first command to examine the entry point, and the second to identify the code that changes horizontal scrolling. Check whether the requested stop actually occurred.

13.7 Record observation points and compare runs

.\kokura\kokura-cli.exe out/game.gb --run-frames 60 --replay-interval 1 --replay-max-checkpoints 60 --dump-replay-tape out/baseline.json --dump-report out/baseline-report.json
.\kokura\kokura-cli.exe out/game.gb --run-frames 60 --replay-interval 1 --replay-max-checkpoints 60 --compare-replay-tape out/baseline.json --dump-report out/compare.json

Check the comparison result and the first mismatch in the report. Merely producing both files is not a passing comparison.

13.8 Diagnostics and a reproducible investigation

.\kokura\kokura-cli.exe out/game.gb --run-frames 180 --emit-diagnostics out/events.jsonl --dump-report out/run.json --break-on-diagnostic all --png-on-diagnostic out/diagnostic-images --snapshot-on-diagnostic out/diagnostic-states --repro-bundle out/repro.zip

To stop at a particular instruction or write, use the debugger options in 13.6. Read diagnostics in context: a deliberately idle title screen can produce observations that are not game defects.

13.9 Disassemble instructions or inspect pseudocode

.\kokura\kokura-cli.exe out/game.gb --disassemble-range "0:0100-0150" --disassemble-out out/entry.txt --disassemble-format text
.\kokura\kokura-cli.exe out/game.gb --symbols out/game.map --decompile-function main --decompile-out out/main.md --decompile-format markdown

Disassembly is useful for checking generated instructions; pseudocode helps navigate control flow. Neither recovers the exact original C program. Keep symbols and metadata from the same ROM build.

13.10 Run multiple linked machines

Session fields include name, slot, rom, symbols, source_map, toolchain_metadata, load_state, save_state, input, input_sequence, audio_buffer_frames and watch_window. rom is required. A watch field can contain comma-separated windows such as a:0xC700:4,b:0xC710:4. Use programs that actually exchange serial data; two running screens alone do not prove communication.

Command syntax reference

The following help was captured for the source edition. Consult it for optional arguments, defaults and accepted values. Replace the illustrative input filenames with your own outputs. Captured tool responses retain their original wording.

Usage: kokura-cli.exe [OPTIONS] [ROM]

Arguments:
  [ROM]  

Options:
      --hardware <HARDWARE>
          [default: auto] [possible values: auto, dmg, cgb]
      --job <JOB>
          
      --link-job <LINK_JOB>
          
      --link-topology <LINK_TOPOLOGY>
          
      --link-initial-peer-slot <LINK_INITIAL_PEER_SLOT>
          
      --link-session <LINK_SESSIONS>
          
      --regression-matrix <REGRESSION_MATRIX>
          
      --run-frames <RUN_FRAMES>
          [default: 1]
      --input <INPUT>
          
      --input-seq <INPUT_SEQ>
          
      --load-state <LOAD_STATE>
          
      --resume-state <RESUME_STATE>
          
      --save-state <SAVE_STATE>
          
      --dump-report <DUMP_REPORT>
          
      --dump-replay-tape <DUMP_REPLAY_TAPE>
          
      --compare-replay-tape <COMPARE_REPLAY_TAPE>
          
      --snapshot-on-replay-mismatch <SNAPSHOT_ON_REPLAY_MISMATCH>
          
      --screenshot <SCREENSHOT>
          
      --png <PNG>
          
      --snapshot <SNAPSHOT>
          
      --trace-jsonl <TRACE_JSONL>
          
      --diagnostics-jsonl <DIAGNOSTICS_JSONL>
          
      --repro-bundle <REPRO_BUNDLE>
          
      --png-on-diagnostic <PNG_ON_DIAGNOSTIC>
          
      --snapshot-on-diagnostic <SNAPSHOT_ON_DIAGNOSTIC>
          
      --break-on-diagnostic <BREAK_ON_DIAGNOSTIC>
          
      --input-script <INPUT_SCRIPT>
          
      --screenshot-frames <SCREENSHOT_FRAMES>
          
      --record-wav <RECORD_WAV>
          
      --record-wav-frames <RECORD_WAV_FRAMES>
          
      --record-video <RECORD_VIDEO>
          
      --record-video-frames <RECORD_VIDEO_FRAMES>
          
      --audio-buffer-frames <AUDIO_BUFFER_FRAMES>
          
      --symbols <SYMBOLS>
          
      --source-map <SOURCE_MAP>
          
      --toolchain-metadata <TOOLCHAIN_METADATA>
          
      --watch-window <WATCH_WINDOWS>
          
      --watch-baseline-mode <WATCH_BASELINE_MODE>
          [default: initial] [possible values: initial, previous-frame, named]
      --watch-baseline-tag <WATCH_BASELINE_TAG>
          
      --capture-watch-baseline <CAPTURE_WATCH_BASELINE>
          
      --watch-fields <WATCH_FIELDS>
          
      --report-sections <REPORT_SECTIONS>
          
      --report-minimal <REPORT_MINIMAL>
          
      --snapshot-at <SNAPSHOT_AT>
          
      --run-until <RUN_UNTIL>
          
      --trace-point <TRACE_POINTS>
          
      --timeline-out <TIMELINE_OUT>
          
      --timeline-format <TIMELINE_FORMAT>
          [default: jsonl] [possible values: jsonl, csv]
      --breakpoint <BREAKPOINTS>
          
      --watchpoint <WATCHPOINTS>
          
      --stop-on-mmio <STOP_ON_MMIO>
          
      --stop-on-irq <STOP_ON_IRQ>
          
      --stop-on-dma <STOP_ON_DMA>
          
      --replay-interval <REPLAY_INTERVAL>
          
      --replay-max-checkpoints <REPLAY_MAX_CHECKPOINTS>
          
      --rewind-on-stop-frames <REWIND_ON_STOP_FRAMES>
          
      --stop-on-divergence
          
      --compare-replay-watch-only
          
      --decompile-out <DECOMPILE_OUT>
          
      --decompile-format <DECOMPILE_FORMAT>
          [default: json] [possible values: json, markdown, text]
      --decompile-function <DECOMPILE_FUNCTIONS>
          
      --decompile-all
          
      --decompile-annotations <DECOMPILE_ANNOTATIONS>
          
      --decompile-trace <DECOMPILE_TRACE>
          
      --disassemble-out <DISASSEMBLE_OUT>
          
      --disassemble-format <DISASSEMBLE_FORMAT>
          [default: text] [possible values: json, markdown, text]
      --disassemble-range <DISASSEMBLE_RANGES>
          
      --emit-diagnostics <EMIT_DIAGNOSTICS>
          
      --diagnostic-pack <DIAGNOSTIC_PACK>
          
      --diagnostic-rule <DIAGNOSTIC_RULES>
          
      --diagnostic-summary-limit <DIAGNOSTIC_SUMMARY_LIMIT>
          
  -h, --help
          Print help