Mednafen automation

At a glance

Input

Mednafen .mc{0..9} save states under ~/.mednafen/mcs/; PCSX-Redux .sstate where marked

Library + CLI

crates/mednafen (legaia_mednafen) and the mednafen-state binary; orchestrators in scripts/mednafen/

Manifest

scripts/scenarios.toml - names each state by label, never slot number; shared with the PCSX-Redux harness

Unit of analysis

A sister pair of states bracketing one gameplay event

Beyond RAM

The GPU section holds VRAM, main RAM holds the frame's display list, the SPU section feeds the audio oracle

Cannot do

Name a writer's return address - for that use the live PCSX-Redux probes

Used by

overlay capture, the engine's VRAM / mode-trace oracles, save record field pinning

What this solves

You have played to a moment - an item pickup, a level-up, the step before an encounter - and want to know which bytes of RAM that moment changed. Save a state before, a state after, diff them: every differing byte was written by code that ran in the gap. Cluster the changes into regions and you have a ranked list of structures to look up writers for in Ghidra.

Quick start

[diff] window 0x801C0000..0x80200000  merge_gap=16  min_changed=4
[diff] 20 regions, 10029 bytes changed total
[diff] top 8 by bytes_changed:
       start           end     changed   left -> right (16 bytes)
    0x801F69D8  0x801F8F02   8631       90FFBD27... -> 147B1F80...
    0x801FFC28  0x801FFFBE    542       C42B0880... -> FFFFFFFF...
    ...

For a pair bracketing a field → battle transition, the 9 KB region is the overlay window the area-load wrote into; the small regions are scattered global-state updates. Then find the writer in Ghidra (Search → For Direct References, or find_lui_writers.py for LUI+ADDIU pairs - see Ghidra in Docker).

Capture conventions

• One event per pair. A state that captures both an encounter trigger and a level-up forces the reader to disentangle two write streams.
• Keep one state per game mode - town, field, battle-intro, battle-active each hold a distinct RAM layout.
• Save before and after any one-shot event (item use, rank-up, level-up, scene transition).
• Label, not slot. Live slots are overwritten every play; the manifest keys scenarios by label and fingerprint.

Command reference

Workflow patterns

The scenarios manifest

scripts/scenarios.toml declares every scenario: its slot or library backup, overlay slice, watchpoint regions and diff_against sisters. mednafen-state watch <label> runs one scenario's watchpoints against each sister and writes a JSON report.

[[scenarios]]
slot = 1
label = "pre_encounter"
description = "Walking the field, one step before an encounter triggers"
diff_against = [2, 3]
expected_game_mode = 0x03            # asserted at load
expected_active_scene = "map01"
backup_fingerprint = "<sha256>"      # immutable saves/library copy, preferred over the live slot
ram_fingerprint_sha256 = "<sha256>"  # first 64 KiB of main RAM

[scenarios.overlay_slice]
start = 0x801C0000
end = 0x80200000

[[scenarios.watchpoints]]
label = "battle_overlay_window"
start = 0x801CE808
end = 0x801F3818

To add a scenario: capture a state (F5), add a [[scenarios]] block with label and description, optional watchpoints and diff_against, then mednafen-state watch <label>. Optional pins (phase, pcsx_redux_sstate, duckstation_sav) are listed in the manifest's own header comment.

How we know

See also