PS2 Web Recomp Setup Guide

Use the original project’s tools to turn a disc image you own into a local browser build. This walkthrough explains the prerequisites, commands, output files, and first-run checks for the source revision listed above. It combines the author’s documentation and script review with a short YouTube background guide. We have not independently performed a game build or tested gameplay.

Before you begin

PS2 Web Recomp translates a game’s Emotion Engine code to C++, then compiles it to WebAssembly. A runtime handles the remaining console systems. You build each game on your own machine; this website provides guides and an author recording.

The two documented game records cover Gran Turismo 4 races and God of War II combat. Another title can stop at an unimplemented runtime function. Neither a completed build nor a title screen establishes full compatibility.

Watch the project explained

PS2 no navegador: como essa recompilação funciona, by Calma, dev!, published 14 October 2026, is a Portuguese explainer with captions. These links jump to useful background for the steps below:

• 0:39 — What runs on your machine: the local-build model and your own disc image.
• 4:51 — Browser requirements: graphics support and hosting prerequisites.
• 6:23 — The local workflow: tools, analysis, discovery passes, and a local page.

This video explains the workflow; it does not record a complete installation. The commands and expected files below are checked against the pinned upstream README and scripts, which remain the primary sources. The video supplies background, not independent performance or compatibility evidence.

1. Check your build tools

In a terminal, check that these programs are available:

git --version
cmake --version
ninja --version
python3 --version
c++ --version
bash --version

Each command should print its installed version. A version response only confirms that the tool exists; the compiler still needs C++20 support. Install any missing tools using your platform’s package manager before continuing.

Apple silicon macOS: the scripts need Bash 4 or later; macOS’s built-in Bash 3.2 is too old. In a terminal with Homebrew already installed, the README lists:

brew install bash cmake ninja sevenzip

Make Homebrew’s executables available first in this terminal, then check which Bash the scripts will find:

export PATH="$(brew --prefix)/bin:$PATH"
command -v bash
bash --version

Confirm that the version is 4 or later. Git, Python 3, and a suitable compiler are separate prerequisites. Windows browser support does not establish a Windows build workflow.

2. Download the source code

Clone the author’s repository and select the revision used for this walkthrough:

git clone https://github.com/snuri00/ps2-web-recomp.git
cd ps2-web-recomp
git checkout ebf86d3b8fa915d38cb070bfd70b6b41669816d5

You can confirm the checkout with:

git rev-parse HEAD

It should print the commit above. This guide downloads source code; there is no game included. If you use a newer revision, follow its current README and record that commit when reporting a problem.

3. Build a game from your disc image

Run this from the repository directory. Replace the quoted path with the actual path to your own image, preserving the quotes if it contains spaces:

scripts/port.sh mygame "/absolute/path/My Game.iso"

mygame is a local identifier, not a game title to download. It determines the output paths used throughout this guide. Use a different identifier for a different disc: the script retains a disc already present under an existing identifier.

The first browser build installs Emscripten into tools/emsdk, unless EMSDK already points to an installation, and downloads wgpu-native. Initial setup therefore needs network access. Build duration depends on the machine and game; no fixed completion time is promised.

After tool setup, the script labels six stages:

Discovery uses automated button presses to explore a limited path. The script can finish while a game still has unresolved runtime or graphics problems.

After a successful browser build, these paths help you check the result:

The completion message prints the serve command for your chosen identifier. If a build fails, retain the terminal error and inspect the named log before rerunning. The troubleshooting guide explains runtime gaps separately from browser startup problems.

4. Start the local server

For the mygame identifier used above, run:

python3 scripts/serve.py build/web-mygame games/mygame/disc.iso

Keep this terminal running, then open http://localhost:8620/ in a browser on the same machine. The supplied server provides the headers needed for shared memory and supports HTTP Range requests for disc streaming. Double-clicking the generated HTML or substituting a generic file server can leave required features unavailable.

If port 8620 is already occupied, stop the conflicting local process or choose another port using the server’s optional third argument:

python3 scripts/serve.py build/web-mygame games/mygame/disc.iso 8621

That command uses http://localhost:8621/. Browser saves belong to the address you play from, so keep a consistent address and export your memory card before moving between setups.

Press Ctrl+C in the server terminal when you finish. Follow the author’s instruction to keep generated game code and builds on your own machine.

5. Check the first run

1. Read any startup capability message before pressing Start. The runtime checks cross-origin isolation, WebAssembly JSPI, exception handling, tail calls, and SIMD. WebGPU support alone does not satisfy every check.
2. Check that the GPU renderer has a usable WebGPU adapter. The author describes software rendering as useful for menus and too slow for 3D gameplay. Consult the browser guide for the source revision’s platform guidance.
3. Begin at 1× native internal resolution. Record a successful scene before comparing higher resolutions.
4. Check input. Enter maps to Start and Z to Cross. Use the controls and gamepads reference for the rest of the mappings.
5. Record what you actually reach: startup, menus, a race, or combat. Include the game region/revision, project commit, browser version, operating system, CPU, GPU, and resolution with any report.

For context, the author’s Gran Turismo 4 record reaches races and the God of War II record reaches combat. These are author-documented milestones, with the conditions and unknowns listed on each page.

Common setup problems

These are source-based checks, not independently reproduced fixes. Run the browser check to identify missing browser features. For a useful troubleshooting record, keep the exact error, environment, source revision, and scene reached.