PCSX-Redux automation

Why PCSX-Redux

Three properties make it the right tool for runtime probes:

• Open-source + scriptable. The Lua API exposes the CPU register file, main RAM as a file-like object, and a breakpoint manager.
• Interpreter CPU + debug mode. The interpreter (-interpreter) is the only CPU back-end that hits Lua breakpoints, and the interpreter only invokes the debug-process hook when DebugSettings::Debug is set (-debugger). Both flags are required; silently neither alone fires Lua breakpoints. (Source: psxinterpreter.cc:1652 - if constexpr (debug).)
• Save-state load from Lua. PCSX.loadSaveState(zReader(file)) loads a .sstate file at runtime, which lets the autorun script reach any captured game state without driving the GUI.

Mednafen's binary save-state format is supported for offline RAM scans via the mednafen-state crate, but its runtime debugger is GUI-only; PCSX-Redux is where the breakpoint probes run.

Setup

The expected on-disk layout (matches the run-script defaults):

~/Tools/pcsx-redux/pcsx-redux                  # locally-built binary
~/Tools/pcsx-redux/<TITLE_ID>.sstate<N>        # PCSX-Redux quicksave (F1..F10 in-emulator)
~/.mednafen/firmware/SCPH1001.BIN              # PSX BIOS, reused from mednafen
~/Downloads/Legend of Legaia (USA)/            # disc image

The <TITLE_ID> is the PSX disc's product code (e.g. SCUS94254 for the USA release of Legaia); PCSX-Redux writes one file per quicksave slot when you press the assigned F-key in the running emulator. Each probe's documentation calls out which game state the save needs to be in - pick a save you've prepared locally that matches.

Override any of these via env vars (PCSX_REDUX, LEGAIA_BIOS, LEGAIA_SSTATE, LEGAIA_ISO). The repo doesn't ship the binary or BIOS or disc; those stay local.

Save-state library (immutable backups)

PCSX-Redux quicksave slots (<TITLE_ID>.sstate<N>) and mednafen mc{N} cards are ephemeral - the next time you save in that slot, the bytes are gone, and a save you reverse-engineered against has to be recaptured from scratch. To stop that, back interesting states up into a fingerprint-named library:

scripts/manage-states.py backup pcsx-redux ~/Tools/pcsx-redux/SCUS94254.sstate6 \
    --label field_walled_collision_pin
scripts/manage-states.py library          # list what's backed up + catalogue status
scripts/manage-states.py library --audit  # scenario-centric: emulator-aware catalogue
                                          # status + PCSX-probe-usability + orphan/missing gaps

library --audit is the inverse view: it walks every manifest scenario and classifies it as CATALOGED (for which emulator), EPHEMERAL-ONLY (a live-slot pointer never backed up), BACKUP-MISSING (fingerprint recorded but the file is gone), or NO-SAVE (a pure phase marker), and flags which scenarios are usable for a PCSX-Redux breakpoint probe - a mednafen-only backup is catalogued but cannot be loaded by run_probe.sh (PCSX-Redux needs a pcsx-redux .sstate).

backup copies the file to saves/library/<emulator>/<sha256>.<ext> (immutable; the sha256 is the filename, so it never collides or gets overwritten) and records the fingerprint on the named scripts/scenarios.toml scenario as backup_fingerprint. The library directory is gitignored (it holds Sony game RAM); the committed pointer is the manifest's backup_fingerprint field. When a scenario has one, both scripts/manage-states.py and run_probe.sh --scenario resolve the library copy in preference to the live slot - so probes keep working after you've saved over the original slot. See the field schema + workflow at the top of scripts/scenarios.toml.

The harness

scripts/pcsx-redux/run_probe.sh is the canonical wrapper. Despite the name, every other Lua autorun re-uses it via the LEGAIA_LUA override:

LEGAIA_SSTATE=$HOME/Tools/pcsx-redux/<your-saved-state>.sstate \
LEGAIA_LUA=scripts/pcsx-redux/autorun_world_map_fog_probe.lua \
LEGAIA_OUT=/tmp/fog_probe.csv \
LEGAIA_FRAMES=600 \
    bash scripts/pcsx-redux/run_probe.sh

The wrapper:

1. Verifies the binary / BIOS / save state / Lua file all exist (fails early with a clear error if any one is missing).
2. Launches PCSX-Redux with -interpreter -debugger -run -bios <SCPH> -iso <bin> -dofile <lua> -stdout and pipes the emulator log to logs/pcsx_<probe>.log.
3. Tails the log for a === summary === block on exit.

The -stdout flag is what makes the autorun's PCSX.log(...) calls visible to the parent shell.

The probe pattern

Every autorun script under scripts/pcsx-redux/ follows the same state machine:

1. WAIT_BOOT - vsync listener counts up while the emulator boots the BIOS to a known state (typically 60 vsyncs = 1s).
2. ARMED_LOADED - load the save state, read the register file, compute breakpoint addresses (often GP-relative), arm the probes, write an initial snapshot. Capture for LEGAIA_FRAMES vsyncs while breakpoints log hits to the CSV.
3. DONE - disarm breakpoints, write a final snapshot, PCSX.quit(0).

This pattern is factored out as a shared library at scripts/pcsx-redux/lib/probe.lua, which is an umbrella that re-exports the per-concern submodules under scripts/pcsx-redux/lib/probe/ - env, mem, sstate, pad, bp, csv, snapshot, sm, watch, step, and symbols (the umbrella's submodule list must include step for the tracing helpers below to resolve). A new probe doesn't reimplement the state machine, the memory readers + writers, the save-state loader, the pad-override helpers, the CSV writer, or the live-snapshot writer - it imports them:

package.path = package.path .. ";scripts/pcsx-redux/lib/?.lua"
local probe = require("probe")

local csv = probe.csv_open("/tmp/x.csv", "addr,pc,ra")

probe.run({
    sstate         = probe.getenv("LEGAIA_SSTATE", DEFAULT),
    capture_frames = probe.getenv_num("LEGAIA_FRAMES", 600),
    snapshot_path  = "/tmp/x.hits.txt",
    on_arm = function()
        local descs = {}
        for _, addr in ipairs({ 0x801E76D4 }) do
            local d = { addr = addr, name = string.format("0x%08X", addr),
                        hits_ref = { n = 0 } }
            probe.arm_breakpoint(addr, "Exec", 4, d.name, function()
                d.hits_ref.n = d.hits_ref.n + 1
                local r = PCSX.getRegisters()
                csv:row("0x%08X,0x%08X,0x%08X",
                    addr, tonumber(r.pc), tonumber(r.GPR.n.ra))
            end)
            descs[#descs + 1] = d
        end
        return descs
    end,
    on_done = function() csv:close() end,
})

probe.ram_offset(addr) is bit.band(addr, 0x1FFFFFFF) - strips the KSEG segment selector so KSEG0 (0x80xxxxxx) and KSEG1 (0xA0xxxxxx) map to the same physical byte. Always work in absolute PSX virtual addresses on input; convert at the boundary.

Call-context capture

probe.capture_call_context(label) returns a multi-line text snapshot of the CPU at the moment of a breakpoint hit:

• All 32 GPRs by MIPS name (zero, at, v0, …, ra), four per row.
• The 8 instruction words straddling PC (pc-0x20..pc+0x60), one row per 16 bytes, with a <- pc marker on the row containing PC. Lets the reader see the calling instruction context without round-tripping through Ghidra.
• The 32 stack words at sp (sp..sp+0x80), 4 per row. The MIPS calling convention saves ra into a sp-relative prologue slot for any non-leaf function, so this captures the visible ra-chain without DWARF unwind info. Walking the chain still requires reading the prologue offsets out of the disassembly post-hoc, but the bytes you need to do that are already in the snapshot.

probe.append_call_context(path, snap) is the matching writer; it opens the file in append mode so multi-shot probes can stack snapshots without overwriting earlier ones. The slot-4 reader and the XP-table probe both use this for first-hit detail dumps.

Write-watchpoint logging (probe.watch)

The recurring “what writes this address?” probe arms a Write breakpoint and, in the callback, logs (elapsed, label, addr, pc, ra, new_value) to a CSV plus a first-N call-context dump. probe.watch factors that closure out (it composes bp + mem + snapshot, adding no new emulator interaction): probe.watch.new{ csv=…, detail_path=…, elapsed=… } then w:arm(addr, width, label).

Instruction tracing + write attribution (probe.step)

PCSX-Redux's Lua FFI exposes no native single-step (only pauseEmulator / resumeEmulator and non-pausing breakpoints - the internal m_debug->stepIn() is not bound). probe.step reconstructs the two things single-stepping is used for, on top of breakpoints, so fine-grained RE stays scriptable instead of needing the GUI debugger:

-- Observational single-step over a code region: an Exec BP on every 4-byte
-- instruction in [lo, hi); each fires in execution order with LIVE
-- pre-execution registers. opts.gate() restricts recording to a window.
local tr = probe.step.trace(0x801de840, 0x801df000, { gate = on_door_frame })

-- Width-correct range write-finder: arms width-`unit` (default 2) Write BPs
-- across [addr, addr+len) so a store of unknown width/alignment to a struct
-- is caught with the correct faulting PC + live registers + post-store bytes.
local fw = probe.step.find_writer(player + 0x10, 0x10, { on_write = log })
-- ... fw:count() / fw:records() / fw:dump(path)

Two gotchas these encode:

• Watch width matters as much as address. A Write BP only matches accesses overlapping [addr, addr+width), and PCSX supports widths 1/2/4 only - a width-2 watch at exactly +0x14 misses a wider/offset store into the same struct. find_writer covers a range by arming a unit BP per slot. (This is what hid the Mei's-house door reposition behind a 2-byte no-op re-store; the range watch found the real writer - a field-VM 0x23 MOVE_TO - in one run.)
• A Write BP fires at the store with live registers (not after the function returns); read getRegisters() directly in the callback.

Early-quit signal

probe.run polls ctx.request_quit each vsync and exits the capture loop on the next tick if it's set. Probes use this to bail as soon as their stop condition is met (e.g. every probe in a sweep has hit at least once), instead of waiting for LEGAIA_FRAMES to elapse:

on_capture = function(ctx, _elapsed)
    if every_probe_hit() then
        ctx.request_quit = true
    end
end,

Symbolic breakpoint addresses

Hard-coded 0x801DA51C-style breakpoint targets break across overlay re-imports that shift function entry points. The symbol resolver accepts Ghidra-canonical names from two sources:

• Function entry points (FUN_801DA51C, slot-4 k10_shared labels, named overlays). Source: per-function dump headers under ghidra/scripts/funcs/*.txt.
• Global data labels (DAT_8007078C / _DAT_8007BCD0, both case forms accepted). Source: the same dump-header walk, plus a regex harvest of DAT_xxxxxxxx references from the decomp body content (so DAT names show up even before dump_globals.py has been run for a given program), plus a dedicated dump_globals.py Jython script for authoritative names + lengths.

Three ways to use it:

-- Bespoke autorun:
local symbols = require("probe.symbols").load()
probe.arm_breakpoint(symbols.FUN_801DA51C, "Exec", 4, "world_map_sm", cb)

# .probe.toml: addr/base accept either an int or a symbol-name string.
[[breakpoint]]
addr = "FUN_801DD35C"     # resolves at spec-load time
kind = "Exec"
[[breakpoint]]
addr  = "_DAT_801EF16C"
kind  = "Read"
width = 4

# Regenerate after adding new dumps (covers funcs/* dumps and globals_*).
python3 scripts/pcsx-redux/build-symbols.py

# Authoritative globals (one-time per program; optional but lossless):
docker compose exec ghidra /ghidra/support/analyzeHeadless /projects legaia \
    -process SCUS_942.54 -noanalysis -postScript /scripts/dump_globals.py
# ... or pass `-process overlay_<name>.bin` for per-overlay globals.
python3 scripts/pcsx-redux/build-symbols.py

The resolver fails loudly on a typo'd symbol name - arming a breakpoint at nil otherwise silently captures zero hits and the probe runs to completion with no diagnostic. The hex portion of the name is case-insensitive: docs use FUN_801DD35C, Ghidra emits FUN_801dd35c, both resolve identically.

scripts/pcsx-redux/probes/_check_specs.py cross-validates every .probe.toml spec's symbol references against symbols.json so a typo'd symbol fails CI rather than the probe run.

Things that catch people out

• Breakpoint width matters. lbu from a watched word triggers only when the width-1 byte falls inside the breakpoint's range. Arming a width-4 probe at an LW target works; arming a width-1 probe at an LBU target works; mismatches silently miss hits.
• GP-relative addresses are decided at runtime. A naive hard-coded address can be wrong across overlay swaps. Read gp from PCSX.getRegisters() after the save-state load, then compute breakpoint addresses from there.
• Sign-extended u64s in Lua. PCSX-Redux returns CPU register values as signed Lua numbers (64-bit doubles). gp = 0xFFFFFFFF8007B318 is the sign-extended display of 0x8007B318. Use bit.band(v, 0xFFFFFFFF) to normalise before formatting.
• In-RAM guard predicates. Pure bitwise comparisons against literals like 0x80000000 interact with Lua's 32-bit signed return shape from bit.band - the literal is the unsigned 2147483648 while the bit-result is the signed -2147483648, so ~= returns true even when the addresses match. Use the explicit bit.band(addr, 0x1FFFFFFF) < RAM_SIZE form from the existing helpers; don't reinvent it.
• GPU::Vsync events fire on game-driven VSync(0) calls, not 60 Hz hardware. PCSX-Redux delivers GPU::Vsync when the game calls libcd's VSync(0) syscall, which is sparse during boot init / CD-DMA phases. A probe waiting on vsync_count >= 600 to fire during boot can sit for minutes of wall time even when emulator-time has advanced past the target. For boot-phase timing use a memory watchpoint at a known transition register (e.g. _DAT_801EF16C title countdown) instead of a vsync-count target - the watchpoint fires precisely when the game writes the state transition.
• Keep the createEventListener return value alive - a GC'd handle silently kills the listener. PCSX.Events.createEventListener returns a proxy object whose __gc deletes the underlying C++ listener (see src/core/eventslua.cc). Discard it and the listener dies at the next Lua GC cycle: the probe goes silent mid-session with no error, exactly when allocation churn (event bursts, string formatting, big reads) triggers a collect. A forced-collectgarbage A/B test kills an unanchored listener on the first pass while an anchored one survives indefinitely. GC of the proxy from inside an event dispatch can also corrupt the event bus and segfault the emulator (the eventslua.cc nested-GC comment). The shared probes anchor every handle in the global PROBE_LISTENER_ANCHORS table - follow that pattern in new probes.
• Unpatched PCSX-Redux caps every Lua listener session at ~32.7k vsync events. The event dispatch in src/core/eventslua.cc pushes the EVENT_LISTENERS table + the listener-info table per event and never pops them - 2 leaked Lua stack slots per dispatch, hitting LuaJIT's ~65500-slot ceiling at almost exactly tick 32716 (the error dump is a wall of N: (Table) lines, then a fatal escaped exception; on a live display it takes the whole app down). Deterministic and content-independent - any long-running probe dies there. The local build carries a rebalance patch (int base = L.gettop() before dispatch, pop back to base after; verified alive past tick 33500 by a forced counter probe). Rebuilding PCSX-Redux from clean upstream REINTRODUCES the cap until the patch is upstreamed - re-apply it after any emulator update.
• Don't readAt(2 MiB, 0) inside a vsync callback. A single 2 MiB PCSX.getMemoryAsFile():readAt(...) call permanently degrades subsequent GPU::Vsync event delivery in the same emulator launch - subsequent callbacks fire rarely or not at all. This is the listener-GC trap above wearing a different hat: the multi-MiB garbage burst triggers the collect that kills an unanchored listener. With the handle anchored, prefer small reads anyway (64 KiB at a time is safe) - full-RAM materialisation per vsync still stalls the frame.
• PCSX.quit(0) doesn't always exit the process. Wrap every probe invocation with timeout --kill-after=10s <budget> so a hung emulator gets reliably killed. The captured data is already on disk by the time PCSX.quit fires - the timeout-kill is purely cleanup.
• --fast must FORCE -dynarec, not just omit -interpreter. PCSX-Redux persists CPU + debugger choice in pcsx.json ("Dynarec": false, "Debug": true once the debugger has ever been used). With no CPU flag on the command line those saved values win, so a run launched --fast still comes up on the interpreter with the debugger enabled - the top bar reads CPU: Interpreted and fps stays at the slow-core rate. run_probe.sh --fast therefore passes -dynarec explicitly per-run. Always confirm the top bar reads CPU: Dynarec. The dynarec runs happily with the debugger window still open (no BPs = nothing to single-step); leaving the debugger unchecked is cleaner and drops it out of the sporadic scene-transition crash surface, and is safe because the exec-bp probes re-enable it per-run.
• Config isolation makes the community kit config-independent. The -dynarec override above pins the CPU, but a volunteer's persisted pcsx.json still rides in for everything else - a broken hardware-GPU pick, a low frame limit, leftover debugger windows - because PCSX-Redux reads its whole profile (settings + memcards + imgui layout) from getPersistentDir() (src/core/system.cc): $HOME/.config/pcsx-redux on Linux, %APPDATA%\pcsx-redux on Windows. It does not honour XDG_CONFIG_HOME. The override hook is the -portable <PATH> flag, which repoints getPersistentDir() at any dir (src/core/arguments.cc: the flag's value sets both m_portable and m_portablePath). So run_probe.sh --fast (and run_probe.ps1 -Fast) default to isolation: they write a minimal fast profile - Dynarec on, Debug off, ship-default renderer, Scaler 100, auto-update off; every unset key falls back to the emulator's compile-time ship default (src/core/psxemulator.h) - into LEGAIA_PCSX_PROFILE_DIR (default captures/.pcsx-profile) and launch -portable at it. Memory cards are pointed at the real config dir via absolute Mcd1/Mcd2 paths (memorycard.cc only prepends the persistent dir to relative names), so card saves still load and save. Opt out with --no-isolate-config / -NoIsolateConfig (or LEGAIA_NO_ISOLATE=1); force the OpenGL renderer with LEGAIA_PCSX_HARDWARE_GPU=1.

Fast whole-playthrough capture (two-tier model)

Some questions - "which story flag/item/party change happens in which scene" across a long play session - are answered by a human playing the game, the one thing the harness can't automate. Two probes split that work by cost:

• Tier 1 - autorun_state_poll.lua (fast, --fast/dynarec, ~full speed): arms no breakpoints. Every GPU::Vsync it diffs a fixed set of progression cells against the previous frame - the story-flag bank (0x80085758, idx space identical to the exec-bp writer's a0), the battle-id staging byte (0x8007B7FC), gold (0x8008459C), item inventory (0x80085958, consumables + start of the key-item page), party count/ids (0x80084594/0x80084598) - plus scene (0x8007050C) and mode (0x8007B83C) transitions. On each field->battle mode edge it also emits one battle row carrying the formation table (0x8007BD0C[4], the first-monster ids that identify boss vs random, sampled once the battle scene is active) plus a best-effort staging id. Per-frame diffing naturally filters intra-frame churn. The staging byte, unlike everything else, is written and consumed within one frame, so the battleid diff comes up empty and the battle row's staging field usually reads 0 - the writer needs the exec-bp firehose (Tier 2); the poll's win here is the formation identity. No breakpoints means it runs under the recompiler at full speed (dynarec even sustains 3x), so it is the probe to hand to community volunteers. Output state_poll.csv carries no Sony bytes - only flag/item ids, scene names, ticks. Trade-off: it captures what changed and where, not the writer. Maintainer cruise knob (off by default, so volunteer runs stay pure read-only): LEGAIA_POINT_CARD_MAX=1 pins the Point Card counter _DAT_800845B4 at its cap every vsync (ported from the firehose), so a Point Card (item 0xFE) strike one-shots any boss when you want to blow through fights on your own capture pass. It writes only that counter, none of the CSV cells.
• The poll also captures, per frame, several context streams (all default-on, each toggleable) so a single playthrough answers more at once: a pos row on every player tile-crossing in field mode (player ptr 0x8007C364, X +0x14 / Z +0x18 s16, tile = (pos-0x40)>>7) - which pins each flag beat to where it fired (door/trigger attribution with no second pass); a bgm row on each global BGM-id change (0x8007BAC8, the music_labels census join); an fmv row on each FMV-trigger-id change (0x8007BA78, the field-VM op 0x4C 0xE2 target - live-confirms the disc-mined per-scene trigger assignment man_field_scripts::scene_fmv_triggers); input rows for pad press/release edges (0x8007B850) and a pick row sampling the dialogue picker cursor (*(0x801C6EA4)+0x0C) at a confirm press (branch/answer attribution). It tags a flag frame note=bulkload when it flips >= LEGAIA_BULK_FLAGS flags (a save-load/init dump, not a beat) so the analyzer filters the noise. And it auto-snapshots a fingerprinted save state on rare events - a never-seen scene, a lone-boss formation, a first-time target-set flag (LEGAIA_SNAP_FLAGS, default the known spine gates plus the open writer-less gates 0x50A/0x5D6 (a non-bulk organic SET of either brackets a code-path-writer hunt) and the statically-resolved 0x370 (writer pinned: the doman variant P1[15] Usha self-latch - the autosnap here is a play-order confirmation of the known writer, not a writer hunt)), a first nonzero battle-id staging byte (which would settle the open "does any retail battle write DAT_8007B7FC?" question), a first-run 0x400 status set, or a first-per-slot arts-input press (an arts-command-input-open bracket on whatever card the volunteer plays) - capped at LEGAIA_SNAP_MAX, so every volunteer run grows the mid-beat state library for free (LEGAIA_AUTOSNAP=0 to disable). Character-progression cells beyond level/spell are diffed too: per-roster-slot cumulative xp (record +0x0) and equip bytes (+0x196..0x19D, one row per changed equip slot), plus persistent counter cells on change (fishing points 0x8008444C, casino coins 0x800845A4, Point Card 0x800845B4). While a battle scene is active a battle-detail stream diffs each battle-actor slot (pointer table 0x801C9370, 0..2 party / 3..7 monsters): a status row on each +0x16E mechanical-status-word change (Venom / Toxic / Stone / Rot / AI-delegation / Curse timelines; a first-run raise of the 0x400 guard-disable bit auto-snapshots - the exact before/after bracket the open applier hunt needs), an hp row on each +0x14C current-HP change (a per-hit damage/heal/DoT timeline), and an aq row on each change of a party actor's action-parameter queue window (+0x1DF..+0x1F2, slots 0..2; note = the full 20-byte window hex). Arts inputs land there as raw direction bytes 0x0C..0x0F and a commit rewrites the window into starter form (0x19 art starter / 0x1A Super-Art special starter), so any Super Art the player performs hands back its committed queue bytes - the byte-exact replace-string validation the Super-Art capture batch otherwise needs dedicated sessions for. Baselines drop on battle exit so cross-fight pointer reuse can't fake rows. On the kingdom overworld scenes (mapNN, field mode) a wmcam row captures the walk-view camera tuple - rotation trio 0x8007B790/92/94, projection H 0x8007B6F4, eye-space TR trio 0x800840B8/BC/C0 (low s16 halves), view-mode flag 0x801F2B94 - once on entry, then on any change (min 10-frame gap, so a held zoom logs a ~6/s trajectory). The retail pitch/TR zoom dynamics are pinned at only two save-state anchors; any volunteer zoom/rotate fills in the path between them. A dt row logs the scratchpad frame-step byte 0x1F800393 (the multiplier every dt-scaled timer/animation consumes: world-map CLUT cadence, fishing tension, battle-action waits) - one baseline row per run, then whenever a new value holds 30 consecutive frames. Toggles: LEGAIA_TRACE_POS/_BGM/_INPUT/_BATTLE (0 = off). Regression self-test: bash scripts/pcsx-redux/run_state_poll_selftest.sh - a wrapper lua dofile()s the real probe on a field state, pokes every watched RAM cell, walks via pad override for organic pos rows, then loads a battle state mid-run and pokes the battle-actor streams; check_state_poll_selftest.py asserts every CSV stream and every autosnap trigger fired. Minutes end to end, no human at the pad - run it after any edit to the poll probe or lib/probe/*, before volunteer handoff.
• Tier 2 - autorun_flag_firehose.lua (slow, interpreter+debugger, ~10 fps): exec-breakpoints on FUN_8003CE08/_CE34 capture the writer ra for the specific flags Tier 1 fingered. Run in short targeted bursts, not a full playthrough.
• Tier 2 provenance - autorun_flag_reader_watch.lua (slow, interpreter+debugger): the full story-flag provenance probe, superseding the firehose. Arms all three flag helpers unfiltered - FUN_8003CE64 (TEST, reader ra) plus FUN_8003CE08/_CE34 (SET/CLEAR, writer ra) - deduped per (kind, flag, ra), so one interpreter trek banks reader+writer provenance for every flag the segment touches. (The static census cannot backstop runtime reads: its bytecode walker desyncs in dialogue-heavy MANs.) LEGAIA_FLAG takes a comma list of targets, which additionally get per-byte read-watches, prioritized call-context detail, and first-hit auto-snapshots. Riding the same session: a write-watch allowlist for non-flag globals (LEGAIA_WATCH_WRITES, default battle-id staging + formation table; rows carry the pre-store value at the hit and the committed value re-read at the vsync drain, since the bp fires mid-store); a VRAM upload log (exec-bps on LoadImage FUN_800583C8 / MoveImage FUN_80058490, deduped per (ra, rect), auto-disarmed across the STR/FMV modes 0x1A/0x1B where a hot LoadImage bp segfaults the emulator); per-fight battle identity rows with the last field tile before the mode left field (the encounter spawn spot; boss-shaped lone formations auto-snapshot); overlay-residency checksums (512-byte FNV-1a at slot A 0x801CE818 and slot B 0x801F69D8, re-taken on scene/mode changes - names which VA-aliased sibling was resident when each hit fired); and field-VM script-PC capture - when a flag helper's caller is overlay-resident, the probe scans the saved registers for a pointer whose bytes decode as the very op being executed (at the primary flag-op cluster s0 = the opcode VA, s8 = the dispatcher's pc_offset), so hits carry the exact script-buffer VA + byte offset of the bytecode op - runtime hits map directly to man-scripts disassembly lines. New-scene auto-snapshots bank a resume state at the mouth of every area reached, and manifest.txt records each run's config + source sstate.

The flag window is capped at 0x200 bytes (idx 0..4095) deliberately: the char-record slot-3 tail ends exactly at the flag base and the item inventory begins exactly 0x200 above it, so 0x200 is the largest window that is pure story-flag bytes with no overlap onto volatile record/inventory cells.

Version guard (lib/probe/version.lua). Every probe hard-codes USA-SCUS_942.54 addresses; a JP/EU/PAL or wrong-revision disc would arm on the wrong code and log silent garbage. Both tiers call version.check(), which fingerprints 6 always-resident code words at each of 0x8003CE08/_CE34/_CE64. Residency is gated on the fingerprinted code being loaded (not merely a boot-time anchor string), so it never latches on the all-zero partial-load window. Modes: locked (shipped default; mismatch = hard refusal), unlocked (warns but fail-closes on a non-Legaia anchor), record (LEGAIA_FP_RECORD=1 - prints the fingerprint for relocking after a rebuild). Volunteer runbook: scripts/pcsx-redux/COMMUNITY-CAPTURE.md.

# Tier 1 - fast community sweep (verify top bar = CPU: Dynarec):
LEGAIA_NO_SSTATE=1 timeout --kill-after=15s 14400s \
  bash scripts/pcsx-redux/run_probe.sh --fast \
    --lua scripts/pcsx-redux/autorun_state_poll.lua

# Relock the version fingerprint after an emulator/disc change:
LEGAIA_FP_RECORD=1 LEGAIA_NO_SSTATE=1 \
  bash scripts/pcsx-redux/run_probe.sh --fast \
    --lua scripts/pcsx-redux/autorun_state_poll.lua
# -> paste [state_poll] fingerprint = <hex> into version.USA_FINGERPRINT

Offline analysis (analyze_state_poll.py). A state_poll.csv is a raw per-frame event log; scripts/pcsx-redux/analyze_state_poll.py <csv-or-dir> turns it into the timelines a reverse-engineer actually reads: a scene timeline (contiguous occupancy windows), battle windows (the frames the game-mode byte sat in the battle-orbit modes 0x14/0x15) annotated with the per-fight battle identity rows (formation ids, with a * on lone-enemy fights = the likely bosses), a story-flag census that separates one-off story beats from the bulk flag dumps a save-load / scene-init writes in a single frame (any tick flipping >= 20 flags or carrying the probe's note=bulkload tag is treated as a load frame and reported separately, not as a beat), and the item / gold / party change lists. Each story-flag beat is annotated with the player tile it fired at (joined from the pos stream, scene-scoped) and a known-flag label - a sticky beat with no label is surfaced as a [lead] (a candidate unmapped gate; extend the label map with --labels FILE). Extra sections cover the BGM timeline, picker choices, auto-snapshots, XP grants + equipment changes, the counters (fishing points / casino coins / Point Card), the FMV triggers (fmv-id changes joined to the firing scene - the live confirmation column for the disc-mined trigger corpus), the battle status timeline (each +0x16E word decoded to its named bits, with any raise of the open 0x400 guard-disable bit called out as a report-this lead), the arts commits (aq-stream rows whose queue window is in starter form, Super Arts flagged for tail-matching against crates/art/src/super_art.rs), and (opt-in) the per-scene walk track, raw input edges, and the per-hit HP timeline. --json emits the same structure for downstream tooling; --only scenes,battles,flags,status,counters,... selects sections. The analysis functions are pure and importable, exercised by test_analyze_state_poll.py on synthetic rows (no capture or disc needed).

Core contract (dynarec vs interpreter). Lua breakpoints fire only under -interpreter -debugger; the recompiler runs them past silently. Enforced in three layers so a mismatch can never produce a silently-empty capture: (1) run_probe.sh forces the core explicitly in both directions and exports LEGAIA_CORE; (2) the breakpoint probes hard-refuse to arm when LEGAIA_CORE=dynarec, and the poll tier logs an advisory when launched on the interpreter; (3) hand launches with no LEGAIA_CORE hit the provenance probe's liveness canary - with the unfiltered TEST bp armed, field-mode gate tests fire every frame, so a long post-arm silence triggers loud repeating relaunch warnings. Every run's manifest.txt records the core it actually used.

Offline analysis (analyze_reader_watch.py). Aggregates a provenance capture into per-flag site tables - each distinct (kind, flag, pc, ra) with suppression-aware counts - and labels every site against the already-cataloged functions (the flag helpers, the field-VM flag-op handler returns, the walk-on tile-trigger dispatch, the bulk save-scan memcpy); anything uncataloged prints [NEW] with its region. Watched writes, VRAM uploads (single-row narrow rects tagged [CLUT?]), battles, and captured script-ops get their own sections. Pass several csvs or run directories and the sites merge into one cumulative provenance map - counts sum per run, every site lists the runs that saw it, --merged-out persists the JSON. The committed overlay-map.txt (FNV-1a32 of each raw overlay's first 512 as-loaded bytes - derived checksums only, no Sony bytes) resolves the probe's residency checksums to labels, so overlay-region hits print resident=[menu (PROT 899 ...)]; regenerate with --gen-overlay-map <extracted-dir>. Pure functions, exercised by test_analyze_reader_watch.py on synthetic rows.

Catalogue

The committed scripts live in scripts/pcsx-redux/. Each Lua file documents its purpose in a header comment block; the catalogue here is the high-level index.

Runtime probes (Lua autorun)

One line per script - each Lua file documents its full probe set + invocation in a header comment block. The important families are unpacked in the disclosures below the table.

Save-state to Python (offline analysis)

One-shot wrappers

run_probe.sh is the single canonical shell harness for every probe. It accepts both env vars (LEGAIA_LUA, LEGAIA_SSTATE, LEGAIA_OUT, …) and matching --lua / --sstate / --out / --scenario / --fast flags. Output defaults to captures/<probe-stem>/<iso-timestamp>/ so each run gets a fresh per-run subtree.

# Default world-map probe (interpreter mode, Lua BPs fire).
bash scripts/pcsx-redux/run_probe.sh

# Pick a different probe.
bash scripts/pcsx-redux/run_probe.sh --lua scripts/pcsx-redux/autorun_dump_slot4.lua

# Resolve the save state via a named scenario from scripts/scenarios.toml
# (a PCSX-Redux-backed scenario; mednafen-only backups can't load here -
# see `manage-states.py library --audit` for which scenarios qualify).
bash scripts/pcsx-redux/run_probe.sh --scenario party_basic_attack_vs_gobu_gobu \
    --lua scripts/pcsx-redux/autorun_battle_state_stream.lua

# Cold-boot a title/boot probe (no save state - runs from power-on).
LEGAIA_NO_SSTATE=1 bash scripts/pcsx-redux/run_probe.sh \
    --lua scripts/pcsx-redux/autorun_countdown_trigger.lua

# Fast (recompiler) mode - FORCES `-dynarec` (overriding the persisted
# interpreter+debugger config; confirm top bar = CPU: Dynarec). Lua **BPs
# do NOT fire** under the recompiler, so this is for vsync-event-only
# probes: full-RAM dumps and the poll-diff progression capture below.
bash scripts/pcsx-redux/run_probe.sh --fast \
    --lua scripts/pcsx-redux/autorun_state_poll.lua

The earlier run_world_map_probe.sh / run_fast_probe.sh / run_dump_slot4.sh wrappers were folded into this one runner.

GDB-stub bridge (gdb_probe.py)

gdb_probe.py is the one-shot escape hatch. PCSX-Redux exposes a GDB Remote Serial Protocol stub on TCP port 3333 (settings: Emulator → GDB server port); this script speaks the protocol directly. Use it when the .probe.toml state machine is overkill - ad-hoc reads, single-shot "break-here-read-there" investigations, register dumps.

When to use this vs .probe.toml:

• .probe.toml for repeatable captures that produce a CSV which probe.py regress can gate on.
• gdb_probe.py for one-shot ad-hoc queries - no schema, no scenario, no state machine to author.

# Read 512 bytes of the kingdom slot-4 region in-flight:
scripts/pcsx-redux/gdb_probe.py read-mem 0x8011A624 512

# Dump registers right now:
scripts/pcsx-redux/gdb_probe.py read-regs

# One-shot break-and-read: when the title overlay tick fires, dump the
# attract-countdown register:
scripts/pcsx-redux/gdb_probe.py when-pc-hits FUN_801DD35C \
    --read-mem _DAT_801EF16C,16

Symbol names resolve via the same ghidra/scripts/symbols.json the Lua probe layer uses; misses raise with the regenerate-via hint. Hex (0x801DE840, 801de840) is always accepted.

Analysing probe outputs (probe.py)

probe.py is the Python-side companion to a .probe.toml run. It operates on the CSV outputs and provides four operations the Lua side intentionally doesn't try to do in-emulator:

--ignore COL[,COL...] drops named columns before comparison / hashing. Use it for fields that naturally vary between runs without representing a regression - most commonly tick (the per-bp hit counter is order-dependent) and sometimes pc (when the same code path gets reached via different inlining decisions across overlay rebuilds).

# Re-run a probe spec, compare against a committed baseline:
bash scripts/pcsx-redux/run_probe.sh --spec scripts/pcsx-redux/probes/xp_table_readers.probe.toml
scripts/pcsx-redux/probe.py regress \
    captures/baselines/xp_table_readers.csv \
    captures/xp_table_readers/<latest>/xp_table_readers.csv \
    --ignore tick

Authoring a new probe

Two shapes are supported, in order of preference:

Declarative .probe.toml (simple probes)

For "arm N breakpoints, dump K columns to CSV" or "settle then dump a RAM region", the probe is a single TOML file under scripts/pcsx-redux/probes/ with no Lua code at all. The shared probes/_runner.lua parses the spec via lib/probe/toml.lua and dispatches into lib/probe/spec.lua.

Schema (see probes/xp_table_readers.probe.toml for the breakpoint-fan-out case and probes/dump_full_ram.probe.toml for the RAM-dump case):

scenario        = "title_attract"   # informational; LEGAIA_SSTATE wins
capture_frames  = 600
output_path     = "my_probe.csv"
capture_columns = ["tick", "addr", "pc", "ra", "value_u32"]

[detail]                            # optional: first N hits get full
hits = 8                            # register/code/stack snapshots in a
path = "my_probe.detail.txt"        # .detail.txt sidecar

[[breakpoint]]                      # individual breakpoint
addr  = 0x80017EC8
kind  = "Exec"                      # "Exec" | "Read" | "Write"
width = 4
name  = "world_map_tick"

[[breakpoint_range]]                # fan out N adjacent breakpoints
base     = 0x8007123C
length   = 196                      # bytes
stride   = 4                        # bytes per bp
kind     = "Read"
name_fmt = "xp+0x%03X"              # %X / %x / %d = byte offset from base

Capture-column vocab (built into lib/probe/spec.lua): tick, addr, offset, pc, ra, sp, width, value_u8 / value_u16 / value_u32.

Run it:

bash scripts/pcsx-redux/run_probe.sh \
    --spec scripts/pcsx-redux/probes/my_probe.probe.toml \
    --scenario title_attract     # or --sstate /path/to/state.sstate

Validate the schema (without launching PCSX-Redux):

python3 scripts/pcsx-redux/probes/_check_specs.py

If lua5.1 is available, the validator also parses each spec via lib/probe/toml.lua and asserts the structural output matches Python's tomllib - catches divergence between the Lua TOML reader and the canonical TOML spec.

Lua autorun (bespoke probes)

For anything more elaborate (per-hit logic that depends on register state, multi-state-machine probes, dynamic breakpoint arming, etc.), write a Lua autorun. The fastest path:

1. Start from scripts/pcsx-redux/autorun_slot4_consumer_pcs.lua - the canonical thin probe (~145 lines) that uses the shared library for everything except the per-probe breakpoint body.
2. Edit the PROBE_OFFSETS (or your own probe-address list), the CSV header, and the per-hit row written from inside the breakpoint callback. The boot-delay / capture-vsync / disarm state machine comes from probe.run({...}) - don't reimplement it.
3. Run with the harness:

   LEGAIA_LUA=scripts/pcsx-redux/autorun_your_thing.lua \
   LEGAIA_OUT=/tmp/your_probe.csv \
       bash scripts/pcsx-redux/run_probe.sh

4. Iterate on the live CSV. The harness re-launches the emulator per run; the CSV is overwritten each time. While the probe is running, the snapshot file (<probe>.hits.txt next to the CSV) is rewritten every 60 vsyncs - tail it from another shell to watch hit counts climb live.

When the probe surfaces a useful signal, commit the Lua file under scripts/pcsx-redux/ and update the catalogue table above. The CSV output itself is gitignored - it's a per-run artifact, not a project state.

See also