[finger563]

The Phantom Menace and Metal Gear Solid can now save to a memory card in port 1. Each card is a raw 128 KB image on the SD card:

• saves/tpm_card1.mcd
• saves/mgs_card1.mcd

These are the same files PC emulators like DuckStation and ePSXe use, and the game makes one the first time it looks for a card.

Save states hold raw memory full of addresses, so they only load into the firmware build that wrote them (TPM) or one with the same layout (MGS). Card saves are the game's own data, so they survive any rebuild.

Changes

• TPM (tpm-decomp fea7648, d51af21):
  • The memory card functions TPM calls (Psy-Q's libmcrd) now use the card image instead of reporting "no card".
  • recomp.py now treats a jr to the function's own return address as a return. The save screen's bit packer (0x80054D44) keeps its return address in $a3, and that path ended in a fatal "not a function" error.
  • The desktop runner gains --memcard FILE and RT_PRESS_HOLD; the menus need holds of about 20 vblanks.
• psyz (3245d54 on tpm): mcd, a card image layer (format, list, create, delete, read, write) plus the BIOS's buXX: file device.
• MGS (mgs_reversing 6d58e9f on esp32p4):
  • The port's file calls route bu00: to the card.
  • memcard.c's card hardware calls are answered at once, through the handlers the BIOS events would have called.
  • An empty port still means "no card".
• tab5-emu:
  • Cart::get_memory_card_path() names the file after the game's folder.
  • The TPM and MGS configs take the path.
  • The READMEs are updated.

Testing

• Card layer: unit tests on the Mac with ASan and UBSan cover format, create, write, read, delete, name patterns, and the bu00: device in the way memcard.c uses it.
• TPM on the desktop:
  • Saved from the pause menu (Save Game) in level 1.
  • The game wrote a standard save: an SC header with the title "PM00:02:Trade Federation Ship".
  • A fresh run listed the saves under Load Game, loaded one, and resumed in that room.
• TPM on the board:
  • A scripted test build saved, and a second, different build loaded that save and played the level at about 28 game fps.
  • That second build is what shows saves surviving a rebuild.
• MGS on the board: at boot the game finds the card ("this memcard is OK") and reads its empty directory.
• Not yet tested: an actual MGS save and load through Mei Ling's codec on the board.

🤖 Generated with Claude Code

https://claude.ai/code/session_01SFCMzomCZ5wRHJN4sxwkvY

[github-actions]

ESP-IDF Size Report for 'Tab5 Emu'

Metric	Base	PR	Delta
FLASH	0 bytes (0.00%)	0 bytes (0.00%)	0 bytes (0.00%)
DRAM	267,182 bytes (60.54%)	267,206 bytes (60.55%)	🔺 +24 bytes (+0.01%)
IRAM	0 bytes	0 bytes	0 bytes
RAM (DRAM+IRAM)	267,182 bytes	267,206 bytes	🔺 +24 bytes (+0.01%)

_{FLASH uses app .bin size or json2 flash sum. RAM sums DRAM+IRAM via idf_size. Percentages shown when totals are available.
DRAM/IRAM usage does not include memory used by the heap allocator at runtime.
This report was generated by esp-idf-size-delta.}

[Copilot]

🟡 Changes recommended

The unconditional psyz/mcd.h include breaks engine-disabled builds because its include directory is added only when CONFIG_MGS_ENGINE is enabled.

1 open issue

• Guard psyz include when MGS engine is disabled · New

What changed in this PR

This PR connects TPM and MGS to persistent PlayStation memory-card images on the SD card, allowing in-game saves to survive firmware updates independently of save states.

Changes:

• Derives card-image paths from each game’s folder and passes them through the game configs.
• Connects TPM and MGS to memory-card support and adds the TPM card-image source to its build.
• Documents card locations, image format, and save-state compatibility.

File	Description
README.md	Documents memory-card images in the SD-card layout.
main/​tpm_cart.hpp	Passes the card path to TPM.
main/​mgs_cart.hpp	Passes the card path to MGS.
main/​cart.hpp	Generates per-game memory-card paths.
components/​tpm/​src/​tpm.cpp	Forwards the card path to the engine.
components/​tpm/​src/​tpm_engine.hpp	Extends engine initialization to accept a card path.
components/​tpm/​src/​tpm_engine.cpp	Stores and exposes the port-1 card path.
components/​tpm/​README.md	Documents card saves and firmware compatibility.
components/​tpm/​include/​tpm.hpp	Adds the memory-card configuration field.
components/​tpm/​CMakeLists.txt	Includes the card-image implementation in the runtime build.
components/​mgs/​src/​mgs.cpp	Configures the port-1 card image through psyz.
components/​mgs/​README.md	Documents card saves and their location.
components/​mgs/​include/​mgs.hpp	Adds the memory-card configuration field.

_{Review effort: Balanced}