KOKURA

1　KOKURAとは

KOKURAはGB/CGB用のエミュレータと観測ツールです。ROMを動かすだけでなく、画面、音、CPU、メモリ、バンク、入力、診断イベントを記録します。コマンドラインの実行ファイルは kokura-cli.exe です。

2　ビルドと最初の実行

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

Rust/Cargoの環境が必要です。CLIだけが必要なら上記の対象crateをビルドします。ROMは第1巻のhelloで作れます。引数を省いたフレーム数の既定値は1なので、見たい場面まで進めるには --run-frames を指定します。これは待機する秒数ではなく、エミュレータが進めるフレーム数です。

3　DMGとCGBを選ぶ

--hardware auto が既定で、dmg / cgb を明示できます。両対応ROMを確認するときは両モードで実行します。CGB専用ROMをDMGで起動できないことを、エミュレータの故障と混同しないでください。

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

4　入力を与える

--input は同時押し、--input-seq は時間順です。ボタン名は A,B,START,SELECT,UP,DOWN,LEFT,RIGHT、何も押さない区間は NONE を使います。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

押下エッジを調べるには離す区間も必要です。単にAを120フレーム押す試験は、Aを120回押す試験とは違います。サンプル入力教材なら上の入力でカウンターが1回増えることを目標にします。

5　画面・動画・音

--png は最後の画面、--screenshot と --screenshot-frames は選択したフレームの連続画像です。--record-video は動画、--record-wav は音の記録です。音源を使わないhelloのWAVが無音でも異常ではありません。

.\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

範囲指定は 開始:終了 です。ロードした状態の通算フレームと実行区間の番号を混同しないよう、レポートも残します。音の有無、音程、途切れ、クリップは別々に確認します。エミュレータ録音と実機録音が完全一致するという保証にはなりません。

6　状態の保存と再開

.\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

同じROMと同じエミュレータ版を基本にします。セーブステートはゲーム内セーブデータとは別です。CLIのKQS形式とC APIのJSON状態は同じファイル形式ではありません。拡張子を書き換えて相互に使わないでください。

7　シンボルとメモリの観測

ROMと同じ場所に .map、.source_map.txt、.dbg2.json、.build_report.json があれば自動検出されます。別のビルドの情報を同じ名前で置くと観測が誤解を招くため、ROMとsidecarを一組で保存します。

.\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 は窓のラベル、0xC000は先頭アドレス、0x40は長さです。観測窓を小さくすると、ゲームのどの変数が変化したか読みやすくなります。--watch-baseline-mode は初期値・前フレーム・名前付き基準からの比較方法を選びます。

8　停止条件・リプレイ・逆解析

--breakpoint、--watchpoint、--run-until、--snapshot-at は条件で止める・保存するための窓口です。引数の小言語はそれぞれ異なるため、下の実装書式とヘルプを参照してください。

.\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

最初に違った位置を調べてから、その周辺を細かく観測します。--decompile-out は疑似コードや制御フロー、--disassemble-out はCPU命令の表示です。デコンパイルは元のCソースや変数名を完全復元する機能ではありません。

9　診断を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 は JSONLファイル名 を受け取ります。例えば out/gb_events.jsonl を指定します。通常の実行レポートJSONやCPUトレースJSONLを、診断イベントと取り違えないでください。

10　通信ジョブ

pairは2台、four_player_adapterはホストが相手を選ぶ論理方式、dmg07は物理DMG-07プロトコルのモデルです。--link-job にJSONを渡す方法と、--link-topology / --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

各ROMは通信を行うように作る必要があります。普通のhelloを2台動かしても通信ライブラリのテストにはなりません。セッションごとのROM、slot、入力、状態を残し、物理機器未確認の境界も記録します。

11　外部プログラムから使う

C ABIは kokura-capi、Pythonは同梱ブリッジから利用できます。まずCLIで最小の再現を作り、連携APIからの動作と比較してください。

12　レポートを読む順番

実行フレームと停止理由、画面、入力結果、音、エラーと警告、プロファイルの順に読みます。無入力のタイトル画面を長く観測すると、静止画面やPCループの警告が自然に出ることがあります。警告を機械的に故障と断定せず、意図した場面と照合します。

13　コマンドの使い分けと引数の書式

以下は各リポジトリが横に並ぶフォルダーから実行するPowerShellの例です。先に New-Item -ItemType Directory -Force out で出力先を作り、out/game.gb を自分のROMへ置き換えます。KOKURAはROMの後ろにオプションを指定します。KUROSAKIのような run サブコマンドは付けません。手元の実行ファイルが受け付ける一覧は --help で確認できます。

13.1　実行方式とフレーム数を決める

1回の呼び出しでは1つの方式を選びます。複数指定時の優先順は、デコンパイル、逆アセンブル、検証行列、通信ジョブ、直接指定の通信セッション、通常実行です。複数の処理を順番に実行する指定にはなりません。

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

最大120フレームを進め、最後の画面とレポートを保存します。まず実際に進んだフレーム数と停止理由を読み、その後で画面を判断します。

13.2　同時押しと時間順の入力

ボタン名は RIGHT,LEFT,UP,DOWN,A,B,SELECT,START です。16進マスクではRIGHT=0x01、LEFT=0x02、UP=0x04、DOWN=0x08、A=0x10、B=0x20、SELECT=0x40、START=0x80です。NESのパッド値とは並びが違います。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

ボタン回数のサンプルなら、カウンターが1回増えることを期待します。押し続けたときの連射判定を調べる場合は、長押しと押し直しを別々に試します。

13.3　画面・動画・音を保存する

記録範囲は1から始まる十進数で、30 は1フレーム、30:32 は30・31・32の3フレームです。0や逆順の範囲はエラーになります。記録番号は今回の実行区間に対する番号なので、保存状態から再開するときはレポートも残します。保存先の親フォルダーは先に作成してください。

.\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

スクロールは複数フレームの位置の変化で、音はWAVで確認します。画面に終了を示す数値が出ても、狙ったチャンネルの発音まで証明したことにはなりません。

13.4　状態を保存して再開する

ROMとエミュレータの版が合った状態を使います。KQSは本体の状態であり、カートリッジのセーブRAMやC APIのJSON状態とは別形式です。

.\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　名前を付けてメモリを観測する

アドレスと長さは十進数、または0x付きの16進数です。変数の位置は現在のビルドのシンボルで調べてください。例の0xC700は固定のプレイヤー領域という意味ではありません。

.\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　実行位置やハードウェアイベントで止める

ブレークポイントの pc:、symbol:、@bank: は大文字・小文字を区別します。アドレスとバンクは十進数または0x付き16進数です。条件に達しない場合に備えてフレーム数も指定してください。

観測条件は && で結ぶAND条件です。指定できる項目は frame=、ly=、pc=、bank=、bank_pc=バンク:PC、symbol=、source=、event=、ppu_mode=（または mode=）、basis= です。frameとlyは十進数、symbol・source・eventは文字列で照合します。basisにはframe_start、frame_end、step、event、trace、snapshot、stopを指定できます。単独のframe_start、frame_end、stop、vblankも使えます。hp<10 のようなCの式を評価する機能ではありません。

.\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

前者は開始位置、後者は横スクロールを書き換える処理を調べる例です。指定した理由で実際に停止したかをレポートで確認します。

13.7　観測点を記録し、実行結果を比較する

.\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

比較レポートの一致結果と最初の不一致位置を確認します。ファイルが2つ作れたことだけでは比較成功になりません。

13.8　診断と再現用の資料を残す

.\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

命令や書き込みの瞬間に止めるには13.6の停止条件を使います。無入力で待つタイトル画面などは意図した挙動でも診断が出るため、観測内容とゲームの設計を照合します。

13.9　CPU命令と疑似コードを調べる

.\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

生成された命令列の確認には逆アセンブル、制御の流れの把握には疑似コードを使います。元のCをそのまま復元する機能ではありません。ROMと同じビルドのシンボルを組み合わせます。

13.10　複数台の通信を動かす

各セッションにはname、slot、rom、symbols、source_map、toolchain_metadata、load_state、save_state、input、input_sequence、audio_buffer_frames、watch_windowを指定できます。romは必須です。観測窓は a:0xC700:4,b:0xC710:4 のようにカンマで複数指定できます。実際にシリアル通信するROMを使い、2画面が動いただけで通信成功とは判断しないでください。

コマンド書式辞典

下記のヘルプは本版で実行して採取しました。省略可能な引数、既定値、列挙値は採取結果に従ってください。説明用コマンドの入力ファイルは自分の出力名に合わせます。

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