PCSX-Redux automation

At a glance

Where

scripts/pcsx-redux/ - Lua autorun probes, the shared lib/probe/ library, declarative probes/*.probe.toml specs, Python analysers

Harness

run_probe.sh (every probe runs through it); run_probe.ps1 on Windows

Input

A PCSX-Redux .sstate named by scenario label in scripts/scenarios.toml, or a cold boot; the disc image and BIOS stay local

Output

captures/<probe>/<timestamp>/: CSV rows, call-context dumps, RAM / screen snapshots. Gitignored - never Sony bytes in the repo

Needs

-interpreter -debugger for breakpoints; the recompiler (--fast) runs them past silently

Used by

overlay capture, playthrough coverage, spine flag-writers capture, the engine's audio / VRAM parity oracles

Sibling

Mednafen automation answers "what changed" offline from save states; this page answers "who did it" live

What this solves

Most of Legaia's logic lives in overlays - code the game streams into RAM on demand - so a static search of the executable often finds no caller at all. A live probe sidesteps that: it lets the game run and records the program counter and return address at the moment of interest. Every probe is the same short lifecycle, factored into a shared library so a new one is a few dozen lines.

Quick start

The first resolves a catalogued save state by label and runs a breakpoint probe on the interpreter; the second cold-boots for a title-screen question. Output lands in a fresh captures/<probe-stem>/<timestamp>/ directory and the wrapper echoes the probe's own hit summary when the emulator exits. Wrap long runs in timeout --kill-after=10s - PCSX.quit(0) does not always end the process, and the data is already on disk by then.

Setup and save states

Quicksave slots (<TITLE_ID>.sstate<N>, F-keys in the emulator) are ephemeral: the next save in that slot erases the state a probe was written against. Back up anything worth keeping into the fingerprint-named library and reference it by label.

• Library copies are immutable - saves/library/<emulator>/<sha256>.<ext>, gitignored; the manifest carries only the backup_fingerprint.
• A mednafen-only backup cannot run here. library --audit says which scenarios have a PCSX-Redux state; it is the usual answer to "but it is backed up".
• Two .sstate shapes exist. Quicksaves are gzipped; states a probe writes are bare protobuf (~19 MB). legaia_pcsxr::SaveState opens both; a gzip-only reader silently drops most of the corpus.
• Check identity before blaming the probe. autorun_identify_state.lua reports the mode, scene and ticking overlay of any state.

Which CPU core fires breakpoints

Lua breakpoints reach the CPU only through the interpreter's debug hook. The wrapper forces the core explicitly in every mode and exports LEGAIA_CORE; breakpoint probes refuse to arm on the wrong core, and the provenance probe adds a liveness canary for hand launches.

--fast also isolates the config: a minimal profile (dynarec on, debugger off, ship-default renderer, absolute memory-card paths) is written to captures/.pcsx-profile and launched with -portable, so a volunteer's saved settings cannot ride in. --no-isolate-config opts out. Always confirm the emulator's top bar reads CPU: Dynarec.

Probe catalogue

Grouped by the kind of question a probe answers. Each Lua file's header comment carries its full invocation; a probe marked superseded is kept for provenance only. Longer write-ups are in the per-probe detail disclosure.

Whole-playthrough capture: two tiers

"Which story flag, item or party change happens where" over a long play session needs a human at the pad. Two probes split the cost: a full-speed poll that says what changed and where, then a slow breakpoint run aimed only at the flags the poll fingered.

• Version guard. Both tiers fingerprint six code words at each flag helper and refuse a non-USA or wrong-revision disc (LEGAIA_FP_RECORD=1 prints the fingerprint for relocking).
• The flag window is exactly 0x200 bytes - the largest span that is pure story flags, with the character records ending at its base and the inventory starting at its end.
• Self-test before any volunteer handoff: run_state_poll_selftest.sh pokes every watched cell and asserts every stream fired. The volunteer runbook is scripts/pcsx-redux/COMMUNITY-CAPTURE.md.
• The poll cannot see the battle-id staging byte - it is written and consumed within one frame; Tier 2 catches its writer.

Patched discs: the memory-card tier

A save state replays the RAM of the disc that produced it, so anything the loader builds at load time - battle meshes, staged records, rebased modules - comes from the old disc until the game reloads it. To observe what a patched disc really loads, cold-boot it, load a save from a memory card, force the battle and dump RAM: capture_battle_mesh.sh chains this and decode_battle_mesh.py decodes the result.

• PCSX-Redux auto-applies a sibling .ppf next to the image it is handed. Point --iso at a scratch copy in a directory you control.
• Cards are env-only (LEGAIA_MCD1/2); isolate_card_save.py copies one save onto an otherwise blank card.
• Bridge SCUS mismatches with legaia-patcher scus-pokes output (LEGAIA_POKES) when a retail state must resume on a patched disc.

One-shot queries: the GDB bridge

PCSX-Redux also exposes a GDB remote stub on TCP 3333. gdb_probe.py speaks it directly for ad-hoc reads, register dumps and single "break here, read there" questions - no scenario, no state machine. Use a .probe.toml instead when the capture must be repeatable and gated.

Authoring a new probe

Two shapes, in order of preference. A declarative spec covers "arm N breakpoints, log K columns" and "settle then dump"; a Lua autorun covers per-hit logic that depends on register state or dynamic arming.

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
path = "my_probe.detail.txt"

[[breakpoint]]
addr  = "FUN_801DD35C"              # int or symbol name
kind  = "Exec"                      # "Exec" | "Read" | "Write"
width = 4
name  = "title_tick"

[[breakpoint_range]]                # fan out N adjacent breakpoints
base     = 0x80076AF4
length   = 196
stride   = 4
kind     = "Read"
name_fmt = "xp+0x%03X"

Things that catch people out

How we know

See also