KITAQ ENTWICKLUNGSSYSTEM
BENUTZERHANDBUCH 2026.09

KITAQ SERIES • REFERENZAUSGABE

KOKURA

Ausführen, beobachten und aufzeichnen

Von der ersten Codezeile zur Ausführung, Beobachtung und erneuten Prüfung.
Quellenstand: 14. September 2026 · Englische Referenzausgabe: 14. September 2026

Fertige Windows-Version

Im Hauptverzeichnis des Repositorys liegt kokura-cli.exe. Laden Sie das Repository als ZIP herunter und bewahren Sie die Lizenzhinweise zusammen mit der ausführbaren Datei auf. Für diese Windows-x64-Version müssen weder Rust noch Python oder .NET installiert sein. Die folgenden Build-Schritte benötigen Sie nur, wenn Sie das Programm selbst aus den Quellen erstellen möchten. Der eigenständige Projektcode steht unter der MIT-Lizenz von DAISUKE OBA; die Lizenzbedingungen der Abhängigkeiten finden Sie in BINARY_NOTICES.md und licenses/.

1. Was KOKURA macht

KOKURA emuliert GB- und CGB-Software und zeichnet Bild, Ton, CPU-Ausführung, Speicher, Banken, Eingaben und Diagnoseereignisse auf. Die ausführbare Datei für die Kommandozeile heißt kokura-cli.exe.

2. Kompilieren und die erste ROM starten

powershell
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

Installieren Sie Rust und Cargo. Wenn Sie nur die Kommandozeilenversion benötigen, bauen Sie gezielt das angegebene Crate. Verwenden Sie zunächst die Hello-ROM aus Band 1. Standardmäßig wird ein Frame ausgeführt; mit --run-frames erreichen Sie die gewünschte Szene. Gemeint sind emulierte Frames, keine Sekunden Wartezeit.

3. DMG oder CGB auswählen

--hardware auto ist die Voreinstellung. Mit dmg oder cgb wählen Sie die Hardware ausdrücklich aus. Testen Sie ROMs, die beide Modi unterstützen, in beiden Einstellungen. Wenn eine reine CGB-ROM im DMG-Modus nicht startet, ist das allein noch kein Fehler des Emulators.

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

4. Eingaben vorgeben

--input hält eine Kombination gleichzeitig gedrückter Tasten. Mit --input-seq geben Sie dagegen einen zeitlichen Ablauf vor. Die Tastennamen lauten A,B,START,SELECT,UP,DOWN,LEFT,RIGHT; NONE steht für einen Abschnitt ohne gedrückte Tasten. Setzen Sie Folgen mit Semikolons in PowerShell in Anführungszeichen.

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

Planen Sie einen Abschnitt mit losgelassenen Tasten ein, wenn Sie neue Tastendrücke testen. A für 120 Frames gedrückt zu halten ist etwas anderes, als A 120-mal zu drücken. Beim Beispiel mit dem Eingabezähler sollte die obige Folge den Zähler einmal erhöhen.

5. Bilder, Video und Ton aufnehmen

--png speichert das letzte Bild. --screenshot zusammen mit --screenshot-frames nimmt ausgewählte Frames auf. --record-video zeichnet Video auf, --record-wav den Ton. Eine lautlose WAV-Datei ist bei einem Hello-Programm ohne APU-Nutzung zu erwarten.

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

Bereiche werden als start:end angegeben. Bewahren Sie den Bericht auf, damit Sie den fortlaufenden Frame-Zähler eines geladenen Zustands von den Positionen innerhalb des aktuellen Laufs unterscheiden können. Prüfen Sie Hörbarkeit, Tonhöhe, Unterbrechungen und Übersteuerung getrennt. Eine Emulatoraufnahme belegt keine Übereinstimmung jedes einzelnen Samples mit echter Hardware.

6. Zustand speichern und fortsetzen

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

Verwenden Sie normalerweise dieselbe ROM und dieselbe Emulatorversion. Ein Emulatorzustand ist etwas anderes als der Spielstand, den ein Spiel selbst speichert. Die KQS-Dateien der CLI und die JSON-Zustände der C-API haben unterschiedliche Formate. Durch Umbenennen der Dateiendung werden sie nicht austauschbar.

7. Symbole und Speicher beobachten

Begleitdateien mit den Endungen .map, .source_map.txt, .dbg2.json und .build_report.json können neben der ROM automatisch erkannt werden. Halten Sie eine ROM und ihre zugehörigen Begleitdateien zusammen. Dateien aus einem anderen Build können zu irreführenden Beobachtungen führen.

powershell
.\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 ist hier der Name des Beobachtungsfensters, 0xC000 seine Startadresse und 0x40 seine Länge. Kleine Fenster erleichtern es, veränderte Variablen zu erkennen. --watch-baseline-mode legt fest, ob mit den Anfangswerten, dem vorherigen Frame oder einer benannten Referenz verglichen wird.

8. Stoppbedingungen, Wiedergabe und Rückanalyse

--breakpoint, --watchpoint, --run-until und --snapshot-at halten bei bestimmten Bedingungen an oder speichern einen Zustand. Die jeweiligen Argumentformate unterscheiden sich. Nutzen Sie die Referenz und die unten wiedergegebene Hilfe.

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

Suchen Sie zunächst die erste Abweichung und untersuchen Sie anschließend ein kleineres Zeitfenster darum herum. --decompile-out erzeugt Pseudocode und Informationen zum Kontrollfluss, --disassemble-out zeigt CPU-Befehle. Eine Dekompilierung stellt weder den ursprünglichen C-Code noch die ursprünglichen Variablennamen vollständig wieder her.

9. Diagnosen an SARAKURA übergeben

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

KOKURAs --emit-diagnostics erwartet einen JSONL-Dateinamen, zum Beispiel out/gb_events.jsonl. Ein gewöhnlicher Laufbericht im JSON-Format und eine CPU-Trace-Datei im JSONL-Format sind keine gleichwertigen Eingaben für Diagnoseereignisse.

10. Kommunikationsaufträge

pair bildet zwei Geräte ab. four_player_adapter beschreibt eine logische Anordnung, in der der Host den Kommunikationspartner auswählt. dmg07 bildet das Protokoll des physischen DMG-07 ab. Übergeben Sie einen Auftrag als JSON mit --link-job oder richten Sie Sitzungen mit --link-topology und --link-session ein.

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

Jede ROM muss die Kommunikation selbst implementieren. Zwei gewöhnliche Hello-Programme testen die Link-Bibliothek nicht. Halten Sie für jede Sitzung ROM, Steckplatz, Eingaben und Zustand fest und benennen Sie, welches Verhalten des realen Geräts noch nicht getestet wurde.

11. Einbindung in andere Anwendungen

Die veröffentlichte C-ABI liegt in kokura-capi. Für Python stehen die mitgelieferte Bridge und das Python-Crate bereit. Stellen Sie zuerst einen minimalen reproduzierbaren CLI-Aufruf her, bevor Sie ein Problem bei der Einbindung untersuchen.

12. Berichte sinnvoll lesen

Prüfen Sie zuerst die ausgeführten Frames und den Grund für das Anhalten. Danach folgen Bild, Eingabeergebnis, Ton, Fehler und Warnungen sowie das Profil. Ein lange beobachteter Titelbildschirm ohne Eingaben kann durchaus Warnungen über ein unverändertes Bild oder einen wiederholten Programmzähler auslösen. Beurteilen Sie solche Meldungen anhand der vorgesehenen Szene.

13. Befehlsbeispiele und genaue Argumentsyntax

Führen Sie diese PowerShell-Befehle im übergeordneten Verzeichnis der nebeneinanderliegenden Repositories aus. Erstellen Sie zuerst mit New-Item -ItemType Directory -Force out das Ausgabeverzeichnis. Ersetzen Sie out/game.gb durch Ihr eigenes ROM. Bei KOKURA stehen die Optionen hinter dem ROM-Pfad; der KUROSAKI-Unterbefehl run wird nicht verwendet. --help zeigt die Optionen der installierten Programmdatei.

13.1 Operation und Frame-Obergrenze wählen

ArgumentZweck und Verhalten
ROMROM-Datei für einen normalen Lauf. Ein Auftrag oder eine Testmatrix kann stattdessen ein eigenes ROM angeben.
--hardware auto, dmg, cgbHardwareauswahl. Standard ist auto; testen Sie bei Spielen für beide Geräte ausdrücklich beide Modi.
--run-frames 120Maximale Framezahl bei direkter Ausführung, standardmäßig 1. Stoppbedingungen können den Lauf früher beenden. Eingabesequenzen haben zusätzlich ihre eigenen Zeitspannen.
--job out/test.jsonFührt einen JSON-Auftrag aus. Seine Frame-Obergrenze steht in run.frames; ROM, Zustand, Eingaben und Aufzeichnungseinstellungen stammen aus dem Auftrag. Relative Pfade darin beziehen sich auf die Auftragsdatei.
--dump-report out/run.jsonSpeichert den entstandenen JSON-Bericht. Ohne Ausgabepfad schreibt ein normaler Lauf den Bericht auf die Standardausgabe.
--regression-matrix out/matrix.jsonFührt Aufträge mit erwarteten Beobachtungen aus. Prüfen Sie die einzelnen Ergebnisse im JSON: Eine erfolgreich ausgeführte Matrix bedeutet nicht, dass jeder Testfall bestanden wurde.

Wählen Sie pro Aufruf eine Operation. Die Auswahl erfolgt in dieser Prioritätsreihenfolge: Dekompilierung, Disassemblierung, Regressionsmatrix, Verbindungsauftrag, direkt in der Befehlszeile definierte Verbindungssitzungen, normaler Lauf. Mehrere angegebene Modi werden nicht nacheinander ausgeführt.

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

Dieser Befehl führt höchstens 120 emulierte Frames aus und speichert das abschließende Bild sowie einen Bericht. Prüfen Sie darin die tatsächliche Framezahl und den Stoppgrund, bevor Sie das Bild bewerten.

13.2 Tasten halten oder eine zeitgesteuerte Eingabesequenz angeben

OptionSyntax und Verwendung
--input "A,RIGHT"Hält während eines direkten Laufs beide Tasten gedrückt. Groß- und Kleinschreibung ist bei den Namen unerheblich. NONE lässt alle Tasten los.
--input-seq "NONE:30;A:1;NONE:89"Durch Semikolons getrennte Abschnitte im Format BUTTONS:FRAMES, die der Reihe nach ausgeführt werden. Hier: 30 Frames loslassen, A einen Frame drücken, danach 89 Frames loslassen.
--input-script "NONE:30;A:1;NONE:89"Akzeptiert denselben Sequenztext, keinen Dateinamen. Sind beide Sequenzoptionen angegeben, hat --input-script Vorrang.

Die Tastennamen lauten RIGHT,LEFT,UP,DOWN,A,B,SELECT,START. Die Hexadezimalmasken sind RIGHT=0x01, LEFT=0x02, UP=0x04, DOWN=0x08, A=0x10, B=0x20, SELECT=0x40 und START=0x80. Das sind KOKURAs Eingabemasken; verwenden Sie dafür keine NES-Controller-Masken. Setzen Sie in PowerShell die gesamte Sequenz in Anführungszeichen. Für Tests neuer Tastendrücke müssen auch Abschnitte mit losgelassenen Tasten enthalten sein. Die Sequenz sollte den gesamten vorgesehenen Beobachtungszeitraum abdecken.

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

Beim Tastenzähler-Beispiel sollte der Zähler dadurch einmal steigen. Ein einzelnes Standbild belegt nicht, ob die Wiederholung beim Halten einer Taste stimmt. Vergleichen Sie einen längeren Tastendruck mit mehreren getrennten Tastendrücken.

13.3 Bilder, Bewegung und Ton aufzeichnen

OptionSyntax und Verwendung
--png out/final.pngSpeichert das letzte Bild; hat bei gleichzeitiger Angabe Vorrang vor --screenshot.
--screenshot out/frame.pngAlternatives Ziel für Bildschirmaufnahmen. PNG und BMP werden unterstützt; ohne Dateiendung wird .png ergänzt.
--screenshot-frames 30:32Speichert jeden gewählten Frame mit seiner Nummer im Dateinamen. Ein Ziel für die Bildschirmaufnahmen muss angegeben sein.
--record-wav out/audio.wavZeichnet Ton als WAV auf. Verwenden Sie ein ROM und einen Zeitraum, in dem tatsächlich Ton gespielt wird.
--record-wav-frames 1:180Wählt den Aufnahmebereich einschließlich beider Grenzen. Die Werte sind Framenummern, keine Samplezahlen.
--record-video out/motion.gifZeichnet Bewegung als GIF oder Y4M auf. Ohne Dateiendung wird .gif ergänzt; MP4 ist kein unterstütztes Format.
--record-video-frames 30:120Wählt den Videobereich einschließlich beider Grenzen.
--audio-buffer-frames 8192Legt die Audiopufferkapazität in Stereo-Sampleframes fest, nicht in emulierten Videoframes oder einzelnen Links-/Rechts-Samples.

Aufnahmebereiche werden dezimal angegeben und beginnen bei 1: 30 wählt einen Frame, 30:32 die Frames 30, 31 und 32. Null und umgekehrte Bereiche werden abgelehnt. Die Indizes beziehen sich auf den aktuellen Lauf. Bewahren Sie beim Fortsetzen eines älteren Zustands daher den Bericht auf. Erstellen Sie die übergeordneten Verzeichnisse vor der Aufnahme.

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

Bewerten Sie Scrollen und Animation anhand mehrerer Frames. Prüfen Sie den Ton anhand der WAV-Datei: Eine sichtbare Abschlussnummer belegt nicht, dass der vorgesehene Kanal gespielt hat.

13.4 Maschinenzustand speichern und fortsetzen

OptionZweck und Vorrang
--save-state out/checkpoint.kqsSpeichert den Maschinenzustand am Ende des Laufs.
--snapshot out/checkpoint.kqsGleiche Ausgabefunktion; hat Vorrang vor --save-state.
--load-state out/checkpoint.kqsLädt vor der Ausführung einen KQS-Zustand.
--resume-state out/checkpoint.kqsHat Vorrang vor --load-state und kann den Eingabezustand eines Auftrags überschreiben.
--snapshot-at "frame=60&&frame_end=>out/frame60.kqs"Speichert, sobald eine Beobachtungsbedingung erfüllt ist. Für mehrere Anforderungen wiederholt angeben. Ohne =>path wird im aktuellen Verzeichnis aus dem ROM-Namen ein nummerierter Dateiname gebildet.

Verwenden Sie einen Zustand, der zum ROM und zur Emulatorversion passt. KQS ist ein Maschinenzustand, weder das Speicher-RAM der Spielkassette noch die JSON-Serialisierung der C-API.

powershell
.\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 Benannte Speicherbereiche beobachten

OptionSyntax und Verwendung
--symbols out/game.mapLädt Symbole aus der passenden Compilerausgabe.
--source-map out/game.source_map.txtOrdnet der Ausführung Quellcodestellen zu.
--toolchain-metadata out/game.dbg2.jsonLädt strukturierte Toolchain-Metadaten. Passende Begleitdateien können auch neben dem ROM automatisch erkannt werden.
--watch-window "player:0xC700:16"Beobachtet 16 Bytes ab 0xC700 unter dem Namen player. Für weitere Bereiche wiederholt angeben. Diese Option beobachtet Speicher, hält die Ausführung aber nicht selbst an.
--watch-baseline-mode initialVergleicht mit den Anfangswerten. previous-frame vergleicht aufeinanderfolgende Frames; named wählt eine ausdrücklich aufgezeichnete Referenz.
--watch-baseline-tag readyWählt den Referenznamen bei einem Vergleich mit benannter Referenz.
--capture-watch-baseline "ready=>frame=30&&frame_end"Zeichnet bei erfüllter Bedingung eine benannte Referenz auf. Für weitere Referenzen wiederholt angeben.
--watch-fields preview,diffWählt Gruppen von Beobachtungsfeldern: hash, activity, preview, baseline, diff, insights oder all. Die Vorschaubytes sind nur ein begrenzter Ausschnitt, kein unbegrenzter Speicherauszug.
--report-sections cpu,watched_memoryBehält die genannten Berichtsabschnitte bei. meta und schema_version bleiben stets enthalten. Unbekannte Namen erzeugen keine neuen Abschnitte.
--report-minimal cpu,watched_memoryAlternative Eingabe der Abschnittsliste mit Vorrang vor --report-sections. Erfordert durch Kommas getrennte Werte und ist kein boolescher Schalter.

Adressen und Größen akzeptieren Dezimalzahlen oder Hexadezimalzahlen mit 0x. Ermitteln Sie Variablenadressen anhand der Symbole des aktuellen Builds. 0xC700 ist unten nur eine Beispieladresse, kein festgelegter Speicherort für den Spieler.

powershell
.\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 Bei Ausführungsbedingungen oder Hardwareereignissen anhalten

OptionSyntax und Zweck
--breakpoint "pc:0x0150"Hält an einer CPU-Adresse an. symbol:main verwendet Symbole; mit angehängtem @bank:2 wird die Bank eingeschränkt.
--watchpoint "player@0xC700+4"Hält bei Schreibzugriffen auf einen vier Byte großen Speicherbereich an. Das optionale Präfix benennt den Watchpoint; ohne +size wird ein Byte überwacht.
--stop-on-mmio "scroll@0xFF43"Hält bei einem Schreibzugriff auf das angegebene MMIO-Register an, hier SCX.
--stop-on-irq "vblank:serviced"Wählt Interruptquelle und Phase: requested, serviced, blocked oder any. Eine allein angegebene Phase gilt für jede Quelle.
--stop-on-dma oam_startWählt ein DMA-Ereignis. Gültige Namen: oam_start, oam_complete, hdma_start, hdma_block, hdma_complete, hdma_cancel, gdma_stall, hdma_deferred, hdma_ignored.
--run-until "frame=60&&frame_end"Hält an, wenn alle Terme einer Beobachtungsbedingung zutreffen. Für zusätzliche Anforderungen wiederholt angeben.

Die Breakpoint-Markierungen pc:, symbol: und @bank: unterscheiden Groß- und Kleinschreibung. Speicheradressen und Banken werden dezimal oder hexadezimal mit 0x angegeben. Behalten Sie eine Frame-Obergrenze bei, auch wenn Sie auf ein Ereignis warten, das möglicherweise nie eintritt.

Beobachtungsbedingungen verwenden && für UND; es sind keine C-Ausdrücke. Unterstützt werden frame=, ly=, pc=, bank=, bank_pc=bank:pc, symbol=, source=, event=, ppu_mode= (oder mode=) und basis=. Frame- und LY-Werte sind dezimal. Symbol-, Quell- und Ereignisterme vergleichen Text. Zu den basis-Werten gehören frame_start, frame_end, step, event, trace, snapshot, stop; auch die alleinstehenden Terme frame_start, frame_end, stop und vblank sind zulässig. Vergleiche wie hp<10 gehören nicht zu dieser Grammatik.

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

Untersuchen Sie mit dem ersten Befehl den Einsprungpunkt und mit dem zweiten den Code, der das horizontale Scrollen ändert. Prüfen Sie, ob der angeforderte Stopp tatsächlich eingetreten ist.

13.7 Beobachtungspunkte aufzeichnen und Läufe vergleichen

OptionZweck
--trace-point "frame=30&&frame_end"Zeichnet bei erfüllter Bedingung eine Beobachtung auf. Für mehrere Punkte wiederholt angeben.
--timeline-out out/timeline.jsonlSpeichert den zeitlichen Verlauf der Beobachtungen.
--trace-jsonl out/timeline.jsonlAlternatives Ziel für den zeitlichen Verlauf mit Vorrang vor --timeline-out. Fordert keine lückenlose Aufzeichnung aller ausgeführten Befehle an.
--timeline-format jsonlWählt jsonl (Standard) oder csv; die passende Dateiendung müssen Sie selbst angeben.
--replay-interval 1Aktiviert Replay-Checkpoints und legt das Intervall in Frames fest.
--replay-max-checkpoints 120Begrenzt die Anzahl aufbewahrter Checkpoints. Standardmäßig werden 16 bei einem Intervall von 1 gespeichert.
--rewind-on-stop-frames 10Fordert nach einem Stopp ein Zurückspulen anhand des aufbewahrten Replay-Verlaufs an.
--stop-on-divergenceAktiviert das Anhalten bei Abweichungen im Replay-Controller.
--dump-replay-tape out/baseline.jsonExportiert aufgezeichnete Replay-Daten. Zu ihrer Erzeugung muss die Replay-Aufzeichnung aktiviert sein.
--compare-replay-tape out/baseline.jsonVergleicht mit exportierten Replay-Daten. Verwenden Sie für einen deterministischen Vergleich dasselbe ROM, dieselben Eingaben und denselben Anfangszustand.
--compare-replay-watch-onlyBeschränkt den Vergleich auf Beobachtungen überwachter Speicherbereiche; dies ist kein vollständiger Vergleich der Maschine.
--snapshot-on-replay-mismatch out/mismatchLegt ein Präfix für Untersuchungsdateien fest, die bei einer festgestellten Abweichung erzeugt werden.
powershell
.\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

Prüfen Sie das Vergleichsergebnis und die erste Abweichung im Bericht. Dass beide Dateien erzeugt wurden, bedeutet allein noch keinen bestandenen Vergleich.

13.8 Diagnosen und reproduzierbare Untersuchungen

OptionTatsächliches Verhalten
--emit-diagnostics out/events.jsonlExportiert Diagnoseereignisse für SARAKURA.
--diagnostics-jsonl out/events.jsonlAlternatives Diagnoseziel für direkte Läufe; --emit-diagnostics hat Vorrang.
--repro-bundle out/repro.zipBündelt einen Bericht, Diagnoseereignisse und ein Manifest. ROM und Metadaten werden per Pfad referenziert, nicht eingebettet. Bildschirmaufnahmen, Zustände und Traces werden nicht automatisch aufgenommen.
--break-on-diagnostic allPrüft Diagnosen im abschließenden Bericht, um Untersuchungsdateien aufzunehmen. Dies hält die CPU nicht an der ersten problematischen Instruktion an. Bei jedem nicht leeren Filter kann jede abschließende Diagnose den Aufnahmepfad auslösen.
--png-on-diagnostic out/diagnostic-imagesZielverzeichnis für das abschließende Diagnosebild bei aktivierter Diagnoseaufnahme. Die Datei heißt diagnostic_000001.png.
--snapshot-on-diagnostic out/diagnostic-statesZielverzeichnis für diagnostic_000001.kqs. Diese Aufnahmen zeigen den aktuellen Endzustand, nicht den ursprünglichen Zeitpunkt jedes Ereignisses.
--diagnostic-pack NAMEAkzeptiertes Argument; der Ausführungspfad wendet kein Diagnosepaket an.
--diagnostic-rule RULEAkzeptiertes, wiederholbares Argument; der Ausführungspfad wendet diese Regelauswahl nicht an.
--diagnostic-summary-limit NAkzeptiertes Argument; der Ausführungspfad wendet diese Begrenzung der Zusammenfassung nicht an.
powershell
.\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

Verwenden Sie für einen Stopp an einer bestimmten Instruktion oder einem Schreibzugriff die Debugger-Optionen aus 13.6. Bewerten Sie Diagnosen im jeweiligen Zusammenhang: Ein absichtlich untätiger Titelbildschirm kann Beobachtungen erzeugen, die keine Spielfehler darstellen.

13.9 Instruktionen disassemblieren oder Pseudocode untersuchen

OptionSyntax und Zweck
--disassemble-out out/code.txtDekodiert ROM-Instruktionen, ohne den normalen Emulationslauf auszuführen.
--disassemble-range "0:0100-0150"Wählt BANK:START-END; für weitere Bereiche wiederholt angeben. Alle drei Zahlen sind hexadezimal, auch ohne 0x.
--disassemble-format texttext (Standard), markdown oder json.
--decompile-out out/functions.jsonErzeugt Pseudocode und Informationen zum Kontrollfluss.
--decompile-format jsonjson (Standard), markdown oder text.
--decompile-function mainWählt eine Funktion; für weitere Funktionen wiederholt angeben. Passende Symbole verbessern die Identifizierung.
--decompile-allSchließt alle dem Dekompilierer bekannten benannten Funktionen ein.
--decompile-annotations out/annotations.jsonLiest Annotationen im JSON-Format des Dekompilierers.
--decompile-trace out/trace.jsonLiest Trace-Metadaten des Dekompilierers; ein beliebiges JSONL-Diagnoseprotokoll ist kein Ersatz.
powershell
.\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

Disassemblierung hilft beim Prüfen der erzeugten Instruktionen; Pseudocode erleichtert das Nachvollziehen des Kontrollflusses. Beides stellt das ursprüngliche C-Programm nicht exakt wieder her. Bewahren Sie Symbole und Metadaten desselben ROM-Builds auf.

13.10 Mehrere verbundene Maschinen ausführen

OptionSyntax und Zweck
--link-job out/pair.jsonLiest Topologie und Sitzungen aus einem JSON-Verbindungsauftrag. Relative Pfade beziehen sich auf dessen Verzeichnis.
--link-topology pairWählt für direkt angegebene Sitzungen pair, four_player_adapter oder dmg07.
--link-session SPECFügt eine Sitzung hinzu. Mindestens zwei Sitzungen sind erforderlich. Setzen Sie in PowerShell die gesamte, durch senkrechte Striche getrennte Zeichenfolge in Anführungszeichen.
--link-initial-peer-slot 1Wählt den anfänglichen Kommunikationspartner, wenn die Topologie eine Partnerauswahl verwendet.

Zu den Sitzungsfeldern gehören name, slot, rom, symbols, source_map, toolchain_metadata, load_state, save_state, input, input_sequence, audio_buffer_frames und watch_window. rom ist erforderlich. Ein Beobachtungsfeld kann mehrere kommagetrennte Bereiche wie a:0xC700:4,b:0xC710:4 enthalten. Verwenden Sie Programme, die tatsächlich serielle Daten austauschen. Zwei laufende Bildschirme allein belegen keine funktionierende Kommunikation.

Referenz der Befehlssyntax

Die folgende Hilfe wurde für diese Quellenausgabe aufgezeichnet. Sie erläutert optionale Argumente, Standardwerte und zulässige Werte. Ersetzen Sie die beispielhaften Eingabedateinamen durch Ihre eigenen Ausgaben. Aufgezeichnete Werkzeugantworten behalten ihren ursprünglichen Wortlaut.

kokura
help
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