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

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, and symbols. A new probe doesn't reimplement the state machine, the memory readers, 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).

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.
• 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 (probably a heavyweight Lua GC pass disrupts the event loop). One-shot full-RAM dumps work because the script transitions to a quit-soon state after the single read; multi-snapshot probes break. Workarounds: keep individual reads small (64 KiB at a time is safe), or take one dump per emulator launch (chained single-shots).
• 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.

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)

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.
bash scripts/pcsx-redux/run_probe.sh --scenario cold_boot_pre_init \
    --lua scripts/pcsx-redux/autorun_countdown_trigger.lua

# Fast (recompiler) mode - drops `-interpreter -debugger`. Lua **BPs do
# NOT fire** under the recompiler, so this is only useful for
# vsync-event-only probes (e.g. autorun_dump_full_ram.lua).
bash scripts/pcsx-redux/run_probe.sh --fast \
    --lua scripts/pcsx-redux/autorun_dump_full_ram.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