PS2 games in the browser: static recompilation to WebAssembly with a native runtime
Gran Turismo 3 bring-up (experimental)
This work builds on snuri00/ps2-web-recomp, retaining its history, MIT license and attribution. It contributes runtime/tooling prerequisites identified while bringing up Gran Turismo 3; it is not a separate graphics implementation or a claim of complete GT3 compatibility.
Scope
- Recognize
CORE.GT3as well asCORE.GT4in the port pipeline, using the existing CORE-to-ELF converter. Cachedcore.elfand ordinary BOOT2 executable fallback behavior are preserved. Selection consumes the full directory listing to avoid producer SIGPIPE underset -o pipefail. - Read SIF EE descriptor words through the memory resolver, including scratchpad. This does not implement scratchpad DMA payload sources.
- Enter idle and unwind when
ExitDeleteThreadleaves no runnable thread. - Minimal local i.Link identification, serial-clock-ready and PHY-access completion/register storage, completion status/interrupt and write-one-to-clear behavior. This is sufficient to exercise initialization with no attached peer; it is not complete IEEE 1394 hardware, packet transfer or GT3 network play.
- Regression coverage for the existing upstream guest-visible INTC latch. Current upstream already retains status after HLE handler delivery; that behavior is preserved, not replaced. The retained latch is additionally saved/restored.
- Zero-length snapshot reader/writer guards for empty container data pointers.
No projection/FOV patch, independent render scaling, camera override, SIMD optimization, benchmark harness or LAN streaming code is included. Stock rendering, controls and launch defaults otherwise remain in place.
Snapshot compatibility
Runtime snapshot version 7 adds the retained INTC latch and i.Link PHY
registers on top of upstream version 6. Upstream versions 2–6 remain loadable;
fields absent from those layouts reset to zero. Versions 0, 1 and newer than 7
are rejected at the header gate before CPU/RAM mutation. Older builds cannot
load version 7 snapshots. Preserve old snapshots before upgrading. This does
not change or delete memory-card .ps2 files, disc images or previous builds.
Snapshot formats from separate experimental forks (including the original
PR's version 3 layout) are not interchangeable merely because their version
numbers happen to match.
Validation and limits
Rebased onto upstream e026b97. Five native CTest groups pass on Linux x86-64,
Clang 23.1.3, in Release and Debug with ASan/UBSan (leak detection and
halt-on-UB enabled). The existing tail-call discovery, executable BSS and
codegen fallthrough regressions also pass:
- SIF scratchpad descriptor list, conflicting RAM descriptors and five RAM aliases.
- Deleted-thread idle/unwind, dormant-thread and ready-worker control cases.
- INTC polling/delivery/W1C, latch restoration, local i.Link initialization, masked/enabled completion IRQs, PHY register restoration and reset, and hardware-section compatibility/defaults for upstream snapshot versions 2–6.
- Full synthetic runtime snapshot round-trip, version gate and zero-length serialization. Generated temporary files contain no game data and are removed.
- Synthetic GT3/GT4 CORE conversion, actual port-script selection, cached-core precedence, normal-executable fallback and a long directory listing.
Tests added to unmodified upstream fail in the corresponding missing behaviors.
The existing live INTC polling behavior already passes upstream; its snapshot
retention is the new fix. Full snapshot sanitizer testing also exposed the
previous zero-length/null memcpy issue. A separate full synthetic snapshot
written by an unmodified upstream-v6 runtime also loads successfully here:
CPU, RAM and pending interrupts restore, while the newly added latch and PHY
storage reset to zero. This checks an actual old layout, not a new snapshot
with its version header relabeled.
Fresh native validation on this rebased branch, using a local GT3 USA v1.10 disc image and newly generated game code, reached boot, the title screen, Arcade Single Race menus, track/car selection, countdown and driving through 4,800 frames. Captures were inspected: the car accelerates through 42, 67 and 85 mph, and R1 switches from bumper to chase camera while driving. A version 7 race snapshot saved at frame 4,200 resumes successfully; frames 4,500 and 4,800 match the uninterrupted run byte-for-byte.
A fresh port.sh --native-only run from the original disc detects CORE.GT3,
translates the executable, explores 3,600 frames with zero missing entry points,
records/compiles 91 VU1 programs and produces the final native runner. That
runner also loads the frame-4,200 race snapshot and advances 600 frames;
its frame-4,500 and frame-4,800 captures match the uninterrupted run byte-for-byte.
Browser validation uses Chrome for Testing 156.0.8078.4 on Linux with an AMD
RDNA 4 WebGPU adapter and cross-origin isolation enabled. Both direct WebGPU
presentation and the existing ?copy fallback reach boot, menus and driving
through 4,800 frames. Canvas captures pass nonblank-pixel checks and were
inspected visually. Both paths save/load a version 7 snapshot and advance at
least 120 more frames after loading.
For headless Chromium checks, use --enable-unsafe-webgpu --enable-features=Vulkan --use-angle=vulkan without
--disable-vulkan-surface. The latter caused blank captures/timeouts even on a
standalone solid-color WebGPU probe; this was a harness issue, not a GT3 fix.
GT4 gameplay, other revisions/regions and universal black-screen fixes are not claimed. GCC remains blocked by pre-existing Clang-specific vector builtins upstream. These checks do not establish complete game compatibility.
Reproduce the synthetic tests
No game, generated translation, SDL window or GPU setup is needed in a fresh clone. Tests default OFF and are native-only. Python 3 and Bash are needed for CORE/tooling tests; CMake registers that group when Python is available.
cmake -S . -B build/gt3-tests -G Ninja \
-DCMAKE_CXX_COMPILER=clang++ -DCMAKE_BUILD_TYPE=Release -DPS2_BUILD_TESTS=ON
cmake --build build/gt3-tests --target \
sif_scratchpad_test kernel_exit_delete_thread_test gt3_initialization_test gt3_state_test
ctest --test-dir build/gt3-tests --output-on-failure
Try with a disc you own
Follow the repository's existing toolchain setup instructions, then:
bash scripts/port.sh gt3 /path/to/your/gt3.iso --native-only
build/native-gt3/ps2run games/gt3/core.elf --disc games/gt3/disc.iso --ntsc --window
# Browser build (requires the documented Emscripten setup):
bash scripts/port.sh gt3 /path/to/your/gt3.iso
python3 scripts/serve.py build/web-gt3 games/gt3/disc.iso
For a repeatable native race/snapshot check after building, run the following
from Bash. This uses the USA disc's NTSC rate and stores private artifacts under
build/gt3-check; inspect captures as well as the exit status.
mkdir -p build/gt3-check/continuous build/gt3-check/resumed
presses=(--press 300:start)
for ((f = 600; f <= 3300; f += 300)); do presses+=(--press "$f:cross"); done
build/native-gt3/ps2run games/gt3/core.elf --disc games/gt3/disc.iso --ntsc \
--memcard build/gt3-check/card.ps2 --frames 4800 "${presses[@]}" \
--press 3600:cross:1200 --press 4000:select \
--save-state 4200:build/gt3-check/race.state \
--frames-dir build/gt3-check/continuous --frame-every 300
build/native-gt3/ps2run games/gt3/core.elf --disc games/gt3/disc.iso --ntsc \
--load-state build/gt3-check/race.state --run 600 --press 4200:cross:600 \
--frames-dir build/gt3-check/resumed --frame-every 300
for f in 04500 04800; do
cmp "build/gt3-check/continuous/frame_$f.ppm" "build/gt3-check/resumed/frame_$f.ppm"
done
The window command requires an SDL-enabled native build; omit --window for
headless diagnostics. Use the appropriate region's video standard, rather than
forcing NTSC for a PAL disc. Exploration reaching its frame limit is not proof
that boot or rendering succeeded: inspect the exploration log and frames.
These are reproduction entry points, not guarantees of a complete port.
Keep disc contents, CORE/ELF files, generated game C++, built game libraries and binaries, snapshots, memory dumps, game-derived assembly/decompilation and captures local. None are shipped here. Prefer sanitized runtime diagnostics rather than posting game material in issues or PRs.