Before you build
The browser project is snuri00/ps2-web-recomp. The repository supplies the recompiler and runtime, while you supply a disc image you own. A generated web build contains translated game code; keep it private as the upstream README instructs. This site has no disc upload or game download step.
The maintainer documents running the workflow on Linux x86-64 and building on Apple silicon macOS. The shell scripts use Bash and a C++ toolchain. Native Windows and WSL are not confirmed build paths in the reviewed instructions; a browser running on Windows is a separate matter from building there.
| Requirement | Why it is needed |
|---|---|
| Git | Fetch the original project and its build tooling. |
| CMake + Ninja | Configure and compile the recompiler, generated game code and runtime. |
| C++20 compiler | Clang is preferred and detected by the scripts. |
| Python 3 | Disc inspection and the local HTTP server. |
| 7-Zip / sevenzip | Needed for a disc image distributed in a .7z archive. |
| Emscripten | Compiles the browser build. The first web run installs the SDK under tools/emsdk, or uses EMSDK. |
| Local storage | The README estimates roughly 300 MB per game for code and builds, in addition to the disc image. |
Build your first local page
Use a short, unique slug for the game directory and quote the actual path to your own image. The upstream script accepts ISO files and ZIP or 7z archives containing an ISO. The first invocation can download build dependencies, so it needs an internet connection as well as a working compiler.
git clone https://github.com/snuri00/ps2-web-recomp.git
cd ps2-web-recomp
scripts/port.sh mygame "My Game.iso"
python3 scripts/serve.py build/web-mygame games/mygame/disc.isoOpen http://localhost:8620/ after the local server starts. Do not double-click the generated HTML file: the threaded runtime needs HTTP headers, and the disc is streamed through Range requests. The supplied server handles both.
Local command builder
Prepare commands for your file
Text stays in your browser. This prepares Bash commands; it does not run them or inspect an ISO.
Choose a slug and image path, then build commands.Apple silicon notes
The macOS build path needs a Bash newer than the operating system’s bundled Bash 3.2. The README lists brew install bash cmake ninja sevenzip. Check which Bash launches the script; installing another shell does not necessarily change the interpreter used by an existing terminal. The native runner uses wgpu-native with Metal on Apple silicon. These are upstream build notes, not a claim that this guide independently tested a Mac.
What the port script actually does
port.sh reads the boot executable named in SYSTEM.CNF, translates it and explores execution in a headless native runner. Those runs collect function addresses that static analysis missed and record vector microprograms. It then translates again and builds the browser and native outputs. The default exploration sends Start and Cross periodically, which may not take every title through its menus.
Inspect games/mygame/shots to see where exploration reached. --frames changes the run length, while --press supplies explicit input timing. A completed build is not proof that the game is playable: evaluate boot, menus, sound, gameplay and saving separately.
Rebuilds and the native option
scripts/build_web.sh mygame rebuilds just the browser output. To build only the native runner, append --native-only to the port invocation; this skips the browser build and Emscripten installation. The windowed native runner requires SDL2 development files. Use the native route for diagnosis only if you have the relevant toolchain, rather than assuming it proves browser support.
Source: Upstream project documentation · reviewed 15 October 2026.