Metal Gear Solid on the Tab5 (mgs_reversing + psyz, native)

[finger563]

Summary

Runs Metal Gear Solid natively on the Tab5 (ESP32-P4) as a cart, from the extracted US disc (SLUS-00594) on the microSD card. The game code is the mgs_reversing decompilation compiled to RISC-V with psyz standing in for the PSY-Q SDK, GPU, GTE and SPU, both on esp32p4 branches of new esp-cpp forks (same pattern as esp-cpp/OpenJKDF2).

What works: the retail boot chain (Konami, title, opening cutscene, dock, topside), cutscenes with correct cameras and the frame-buffer feedback effects (zoom blur, underwater refraction), codec calls with portraits and text, sound effects, music and streamed speech, save and load states, pause, reset and quit from the emulator menu, item and weapon menus on L2/R2.

Gameplay runs at about 28 fps at the dock against the game's own 30 fps cap (up from 16 to 18 when the PR was opened); cutscenes and audio are smooth.

Video: (to be added)

Port layer (this repo)

• components/mgs: cart integration, lifecycle (launch, pause at idle, resume, reset, quit without reboot), LCD present, audio task, hang detector that samples each game thread's saved PC and stack.
• Linker fragment placing the game's statics in PSRAM (bss) and the PSRAM-XIP rodata (data), reset on relaunch. The game's own .sbss/.sdata/.bss sections are renamed .mgs.* so they land in the same regions. Needs CONFIG_ESP_SYSTEM_MEMPROT=n for the writable rodata.
• Save states: the game's static regions, the main task's stack and every mts thread's stack and saved context, 4.2 MB per slot, keyed on a layout signature rather than the ELF hash so a rebuild that leaves the game code in place keeps old states loadable. OS handles that live inside the snapshotted regions are registered and preserved across a restore.
• Two rasterizer workers, one per core, each drawing a band of rows of the same command stream; the split row adapts every frame from the two workers' times. Audio mixer on core 0; virtual CD read-ahead ring on core 1, also pumped from the vblank tick.
• Gamepad: the shared GamepadState gains l2/r2 so a cart can tell triggers from shoulders (USB pads and the keyboard's E/R).

Notable fixes along the way (in the submodules)

• mts cooperative scheduler on FreeRTOS: vsync and SPU interrupts delivered under the game's critical-section gate, never while a thread holds the stdio lock, one SPU interrupt per sound-task pass; the tick's own prints go through a logger task.
• SPU emulation: voice attributes, IRQ address catch-up, 44.1 kHz pull.
• Packet layouts for psyz's two-word tags (merged, priority and mask packets).
• GTE: depth-cue, overflowed square roots, 16-bit camera wrap in cutscenes.
• Rasterizer: PSX mask bit, blended textured pixels keep the texel's STP bit (feedback effects), exact integer DDA edges, a per-triangle modulation table for flat spans, FPU gradients corrected to the exactly rounded quotient (a one-unit error picked the neighbouring texel row for whole triangles), workers rendezvous before frame-buffer feedback primitives and VRAM block moves so cutscenes also use both cores.
• The decompilation targets MGS Integral; the US disc's RADIO.DAT addressing differs and the codec loader handles it.
• Scanout presents only the rows the display environment declares (a 256-line codec screen left a stuck tile in the 224-line view).

Measuring

The pause menu writes the last five frames' GPU batches next to a VRAM dump. The next cart start replays them: each frame rendered by the exact single-worker path to the card, the newest compared pixel for pixel under every optimisation, then timed. Dock frame: 35 ms single worker, 21 ms two workers. Opening sub scene: 89 ms and 74 ms. Serial telemetry every 120 frames covers both workers' raster time, the split row, the display-list walk, CD and audio counters.

What did not pay off and is left switched off: an 8x8-tiled shadow of VRAM for texture fetches and decimated copies for minified textures. The game's triangles are small and touch fresh cache lines either way, and a new line costs about 125 cycles on this board.

Known open items

• One ordering-table link per frame reads as a texpage word in some scenes (logged, dropped safely).
• Occasional bad object chain links on topside (skipped, logged).
• Memory-card game saves are not implemented (use save states).
• Full-motion video (MDEC) is not implemented; movies are skipped.
• States are tied to the game-code layout; a port-layer change that shifts it invalidates them.

Testing

Played on a Tab5 through the opening, the dock, the elevator and topside, with save and load states across resets, pause, reset and quit from the emulator menu. The replay comparison reports 0 differing pixels for every optimisation on the recorded frames. Serial telemetry reviewed for audio starvation (none) and frame pacing.

MGS:

tab5-mgs.mp4

JK:

tab5-jk.mp4

GBA:

tab5-gba.mp4

🤖 Generated with Claude Code

https://claude.ai/code/session_01BAeyJSuzVyqvSe4mffGUZo

[Copilot]

🟡 Changes recommended

Lifecycle races, failure handling, a disabled-configuration build break, and stale documentation remain unresolved.

8 open findings

• Abort initialization when snapshot creation fails · New
• Recheck scheduler after suspending vblank · New
• Guard GPU diagnostic for disabled engine builds · New
• Use an atomic flag for cross-task access · New
• Avoid unconditional 1 MiB VRAM dumps on pause · New
• Handle audio task creation failure · New
• Update status block to reflect implemented features · New
• Update plan status and quit lifecycle description · New

What changed in this PR

Adds Metal Gear Solid as a native Tab5 cart using mgs_reversing and psyz.

Changes:

• Integrates MGS discovery, cart lifecycle, video, audio, input, and diagnostics.
• Places game state in PSRAM and adds reset support.
• Adds build configuration, dependencies, and documentation.

File	Description
.gitmodules	Adds MGS and psyz forks.
CMakeLists.txt	Enables the MGS component.
sdkconfig.defaults	Configures writable PSRAM-XIP and console speed.
tools/​bss_to_psram.py	Adds initialized-data relocation support.
docs/​PLAN.md	Documents the MGS port plan.
main/​mgs_cart.hpp	Implements the MGS cart.
main/​carts.hpp	Registers MGS cart creation.
components/​rom_info/​src/​rom_info.cpp	Detects MGS metadata entries.
components/​rom_info/​include/​rom_info.hpp	Defines the MGS emulator type.
components/​mgs/​CMakeLists.txt	Builds the game, SDK, and port.
components/​mgs/​Kconfig	Adds MGS build and stage options.
components/​mgs/​README.md	Documents setup and status.
components/​mgs/​linker.lf	Places and brackets game statics.
components/​mgs/​psyq_sources.cmake	Lists PSY-Q source units.
components/​mgs/​include/​mgs.hpp	Exposes the MGS lifecycle API.
components/​mgs/​src/​mgs.cpp	Implements lifecycle and diagnostics.
components/​mgs/​src/​mgs_platform.hpp	Declares platform hooks.
components/​mgs/​src/​mgs_platform.cpp	Implements audio, video, storage, and input.
components/​mgs/​shim/​gtemac.h	Supplies GTE compatibility macros.
components/​mgs/​shim/​libpad.h	Supplies controller declarations.
components/​mgs/​shim/​libsn.h	Supplies the required stub header.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[finger563]

Added since opening: save states from the pause menu (the game's PSRAM regions, the game threads' stacks at fixed addresses and their saved contexts; validated against the build's ELF hash), the fix for the opening's submarine shot (blended textured pixels keep the texel's STP bit, which the zoom blur and water refraction depend on), and the relaunch fixes that fell out of testing (read-ahead task teardown, the game's small-data sections now inside the reset and the snapshot).

[Copilot]

🟡 Changes recommended

Incorrect MGS button mapping and unsafe save-state and low-memory failure paths can cause wrong controls or crashes.

7 open findings

• Unconditionally referenced MGS symbol breaks disabled builds · New
• Truncated state load corrupts live memory before read failure · New
• Face buttons are mapped to the wrong PlayStation buttons · New
• Null memory pointer causes crash during initialization cleanup · New
• Keyboard triggers fail to set shoulder-button state · New
• State compatibility documentation contradicts implementation · New
• Mixer scheduling comment has incorrect core and latency · New

8 resolved since last review

• Guard GPU diagnostic for disabled engine builds
• Recheck scheduler after suspending vblank
• Abort initialization when snapshot creation fails
• Handle audio task creation failure
• Avoid unconditional 1 MiB VRAM dumps on pause
• Use an atomic flag for cross-task access
• Update plan status and quit lifecycle description
• Update status block to reflect implemented features

🧠 Review effort: Balanced