Overlay capture

At a glance

The window

0x801C0000-0x80200000, 256 KB, shared by every overlay; only one is resident at a time

Slot A

Field (PROT 0897), battle (0898) and menu (0899) all load at base 0x801CE818; smaller overlays load elsewhere in the window

One-command tool

scripts/ghidra-analysis/auto-name-overlay.py - slices, fingerprints the resident overlay, writes a stub dump script

Emulators

PCSX-Redux (recommended), mednafen (gzip states), Duckstation (.sav, zstd) - equivalent dumps

Output

Function dumps ghidra/scripts/funcs/overlay_<label>_<addr>.txt (gitignored, Sony-derived)

Static complement

Static overlay pipeline - clean bytes with disc-pinned identity, no emulator; this page stays authoritative for runtime values

What this solves

Disassembling SCUS_942.54 alone gives you the loader, the renderer wrappers and the sound driver - and a wall of jal 0x801Dxxxx calls into code that is not on the disc as a file Ghidra can open. Overlay capture is the dynamic answer. Reach for it when a function you are tracing lives at 0x801C0000+ and no static image contains it, when you need the runtime values around that code (initialised globals, filled tables), or when you want the exact list of archive entries a scene requested from the loader (the asset-loader CSV).

Quick start

auto-name-overlay.py detects the save-state format from the magic bytes (mednafen gzip+MDFNSVST or Duckstation DUCCS+zstd), extracts the overlay window, fingerprints which overlay is loaded against an anchor-function table, and emits both the binary slice and a stub dump_<label>_overlay.py Ghidra script with the largest function entry points pre-seeded.

# [info] format: mednafen; sliced 262,144 bytes
# [info] auto-detected label: world_map  (world_map=4, field=3)
# [ok]   /tmp/overlay_world_map.bin
# [ok]   ghidra/scripts/dump_world_map_overlay.py

Then import the slice (slice path first, label second - both required) and run the stub:

When the auto-detection picks the wrong label (the anchor table has no function exclusive to the shop, cutscene or level-up subset), pass --label name; an existing stub is preserved (--force overwrites). To grow the anchor table, add any function you confirm exclusive to one overlay to ANCHOR_FUNCTIONS in the same script.

What's in the overlay window

Two terms recur. Overlays that load at the same virtual address VA-alias: one address names different code depending on which overlay is resident, so a bare FUN_801xxxxx is ambiguous until you say which overlay you mean. Slot A is the primary shared slot the runtime streams the active overlay into - field, battle and menu are VA-alias siblings there, and the mode-24 minigame overlays stream into the same slot.

Capture status

Committed function dumps land under ghidra/scripts/funcs/ as overlay_<label>_<addr>.txt. Several rows share one on-disc source: the save screen and the shop are the menu overlay (0899) captured in different states; the world map and scripted dialogue are the field overlay (0897) resident in different modes.

Capturing with PCSX-Redux

Boot with the disc, play to the scene, open File → Show Lua Console, and run ghidra/scripts/dump_overlay.lua - it writes 0x801C0000-0x801EFFFF to /tmp/legaia_overlay_<TIMESTAMP>.bin. Then ghidra/scripts/import_overlay.sh <dump> copies the file into the container and imports it at base 0x801C0000 (MIPS LE, auto-analysed). Copy dumps to a writable container path: /data is bind-mounted read-only; /tmp is what the committed importers use.

For closed-loop probing (breakpoints, watch addresses, per-VSync CSV) rather than a one-off slice, see PCSX-Redux automation.

Mednafen pipeline with asset-loader CSV

scripts/ghidra-analysis/analyze-overlay.sh is the older mednafen flow; use it when you specifically need the asset-loader CSV. It slices the state, re-imports it as overlay.bin (overwriting the previous import - keep separate labels per scene), then scans every jal to a known SCUS asset loader and const-tracks the $a0 argument into /tmp/overlay_loads_<label>.csv.

The CSV gives the exact PROT entries the runtime loader requests for that scene - it replaces the iterative --vram-extra-dir guesswork in the asset viewer. For the broader save-state toolkit (diff, bisect, scenario manifest), see mednafen automation.

Capturing with Duckstation

Duckstation .sav states are DUCCS magic plus a zstd stream. scripts/ghidra-analysis/extract-duckstation-overlay.py decompresses with the system zstd and locates main RAM by the same anchor-string approach; default slice is the full 256 KB.

Capture protocol per overlay

The rule everywhere: the overlay is only resident while its screen is on - a dialog box, a level-up banner, a cutscene - so save during it, not after.

Extracting TIMs from a RAM snapshot

A captured RAM dump often contains transient textures (TIMs) staged in main RAM before upload to video memory. When the on-disc source is uncompressed, the staged copy is byte-identical except the RECT fields (VRAM target coordinates), so a texture can be traced back to its source PROT entry: sweep the dump for the TIM magic plus valid flags, decode each hit to PNG to identify it visually, fingerprint 16 bytes of the first CLUT row (skipping the runtime-relocated RECT), and grep the PROT corpus for that fingerprint.

Bulk import of static overlay candidates

The find-overlay heuristic ranks PROT entries by likelihood-of-being-overlay-code via addiu sp, sp, -X prologue density (see MIPS overlay detection). scripts/ghidra-analysis/bulk-import-overlays.sh --score 3.5 imports the top candidates at base 0x801C0000 and runs auto-analysis + the inventory dumper; per-overlay function inventories land in ghidra/scripts/inventory_overlay_<stem>.bin.csv. Bulk import only gives function lists - the static overlay pipeline is the successor, importing each overlay at its recovered base with the PROT entry as identity.

See also