Recomp differential oracle

At a glance

Retail side

psxrecomp static recomp of SCUS_942.54, driven over its JSON-over-TCP debug server by scripts/recomp/probe.py

Engine side

legaia-engine sim-trace (crates/engine-shell/src/sim_trace.rs) ticking a BootSession

Trace shape

One JSON object per frame; angles 12-bit (4096 = full turn), positions in retail world units, mode = the retail game-mode word

Diff

trace_diff.py (state), note_diff.py (BGM key-ons); non-zero exit on any divergence

Environment

LEGAIA_RECOMP_DIR, LEGAIA_RECOMP_BIOS, LEGAIA_RECOMP_PORT - each overridable per call

Never committed

Captured traces carry retail RAM values; only the synthetic fixtures in scripts/recomp/test_*.py are tracked

Used by

cutscene camera parity, audio sequencer parity, the arts-voice pins in battle action

What this solves

The emulator harnesses (PCSX-Redux, mednafen) observe retail through breakpoints and save-state diffs: precise, but slow and one address at a time. The recomp path reads a dozen retail globals every frame at full speed, so hundreds of aligned frames from both sides cost seconds. Reach for it when a scene plays differently in the engine and you need the first diverging quantity and frame.

Quick start

Each divergent channel prints its first divergent frame with a ±5-frame window of both sides' values. Always pass --expect-scene / --expect-mode to a load: a stale slot loads "successfully" into the wrong state.

Moving parts

Trace shape and channels

One JSON object per line; every field except frame is optional (absent = not captured that frame):

{"frame": 32915, "scene": "jou ene", "mode": 21,
 "cam": {"pitch": 32, "yaw": 2408, "roll": 0, "h": 256,
         "eye": [0, 1280, 7920], "focus": [0, 0, 0]},
 "player": {"x": 100, "z": 200, "heading": 0},
 "actors": [{"i": 1, "x": -40, "z": 80, "heading": 1024}]}

Channels present on only one side are reported and skipped, never counted as divergence.

Capturing and diffing

Two capture engines

Alignment

• Default: the first camera change on each side - the two sides boot from unrelated frame counters, but the first scripted cut is the same event. --offset N overrides; first frames are the fallback when neither side has a cut.
• sim-trace's first record is a pre-tick boot sample, so the engine camera always "changes" between its first two lines; --skip-lead-b (default 1) drops it.
• A first divergence with no context rows above it is the first frame of the overlap, not the end of a matching run.
• Right after a savestate load the camera can sit static for a settle window; capture longer and let alignment find the first change.

Reading a camera divergence

Over the opening chain the angle channels, cam.roll, scene and mode match retail exactly. The remaining position gap is a timeline-phase difference: sim-trace boots a scene cold at frame 0, while a retail capture arrives through the prologue chain several beats in, so the engine's beat 0 is compared against retail's beat 5. A scene where the cold-booted engine runs no camera script at all reads the same way - a beat gated on arrival story flags. Distinguishing either from a pose error needs the engine driven through the chain.

Note-level audio differential

The same shape applied to music: instead of camera channels per frame it compares the stream of key-ons a sequencer asked the SPU for. Both sides snapshot the same instant (sample start address, pitch, per-voice volumes, ADSR words), so a divergence localises directly - a missing key-on means the sequencer never asked, a wrong start address means tone selection diverged, a wrong pitch means the note or its bend resolved differently.

python3 scripts/recomp/audio_note_capture.py --port 4472 --seconds 30 --out /tmp/scratch/recomp_notes.jsonl --summary
./target/release/note-trace --extracted extracted --track 0 --frames 1800 --out /tmp/scratch/engine_notes.jsonl
python3 scripts/recomp/note_diff.py /tmp/scratch/recomp_notes.jsonl /tmp/scratch/engine_notes.jsonl

CD-XA cue capture

xa_cue_capture.py applies the snapshot ring to the streamed-voice layer (arts shouts, grunts, fanfares): every cue fire stages its parameters in a cluster of SCUS globals before arming the CD filter, and the tool records those globals per frame, detects an edge on the play-state write, and resolves the staged disc location against the clip table to name the XA<n>.XA file. It is the instrument behind the arts-voice channel pins in legaia_art::arts_voice.

How we know

See also