Source download
I downloaded the ZIP. How do I start?
The ZIP contains source code. To reach browser playback, you still need a build environment, your own game image and a completed game-specific build.
- Extract the archive and open its README. If Git is not recognized, installing Git or using the ZIP solves the download step; neither installs the build toolchain.
- Continue in a documented Linux or Apple silicon macOS build environment. On an extracted archive, restore executable permissions to scripts/*.sh before running the build script.
Build environment
A build tool is missing, or a shell script will not run
Check the failing command before rebuilding. A download of the source is separate from installing the tools that compile it.
- Run the version checks in Quick Start for Git, CMake, Ninja, Python 3 and your C++20 compiler. Run Bash scripts in the documented build environment, not directly in PowerShell.
- On Apple silicon macOS, use a newer Bash than the system 3.2, as described upstream. If a script says permission denied after ZIP extraction, restore its executable permission. Keep the exact error if the next attempt fails.
Build output
The build stopped, or the web output is missing
A partial output folder is not a successful build. Locate the first failing step and keep its error rather than starting the browser server against incomplete files.
- Check that the quoted disc-image path exists and that mygame is the same local name in both build and serve commands. Review the final build output for a failure.
- If the output names an unhandled syscall or missing IOP library, continue to the unsupported-game section. If it names a missing tool, return to prerequisites.
Browser and graphics
No WebGPU adapter is available, or 3D is very slow
The project relies on a usable WebGPU adapter for its GPU renderer. The software fallback is not a practical substitute for normal 3D gameplay.
- Use a current Chrome or Edge browser on a platform covered by the upstream browser notes. Check browser graphics acceleration and the browser's graphics diagnostics if an adapter is unavailable.
- For Linux, follow the upstream Linux-specific browser settings. If graphics work but performance is poor, try native resolution before increasing the scale. Report the device, browser and resolution with any performance issue.
Local browser playback
The HTML file fails to load, or shared memory is unavailable
Serve the generated build with scripts/serve.py. It supplies the isolation headers and disc-image range requests the browser build requires.
- Run the command below from the repository folder after a successful build, adjusting both mygame paths if you chose another name. Open the printed address on that same machine.
- Keep the terminal running. A plain file:// page or generic static server may lack required behavior. If using another server, check COOP/COEP headers and HTTP range support. Cross-origin isolation describes the page's hosting, not whether your computer is capable.
python3 scripts/serve.py build/web-mygame games/mygame/disc.isoGame support
Unhandled syscall, missing IOP library, or a game stops at menus
A game can require console functionality that the experimental runtime does not implement. Changing a browser setting is not a documented fix for a missing syscall or IOP function.
- Compare the exact game release and the stage reached with the documented game records. Record the unhandled syscall or [iop] missing message and your project commit.
- Search the upstream issue tracker for the same error. If no report matches, submit reproducible details. Do not label a game fully compatible just because it boots or reaches a menu.
Input
Keyboard or gamepad input is not responding
The upstream page supports keyboard controls and the browser gamepad API. First separate input focus from a game that has stopped progressing.
- Focus the game canvas. Try Enter for Start and Z for Cross. The D-pad uses arrow keys; I/J/K/L control the left stick. Check Quick Start for the other mappings.
- For a gamepad, check that the browser detects it and try keyboard input for comparison. Include browser, controller and the exact control that failed in an issue report.
Memory cards
A save disappeared, or I want to move it to another browser
The project stores its memory card in browser storage for the address used to play. Changing browser profiles or origins does not automatically transfer that storage.
- Return to the browser profile and address used for the save. Before clearing site data, use Export card to keep a .ps2 backup; Import card restores a card through the project's UI.
- Keep the same local address where possible. Check whether ?nocard was used, which starts with an empty slot. A shared memory-card feature is not evidence that every title's save system has been tested.
Prepare a useful issue report
If the checks do not explain the problem, give the upstream maintainer enough detail to reproduce it:
- Project commit, operating system, browser version, graphics hardware and game release or serial.
- The command or action, expected behavior, actual behavior and a short relevant error excerpt.
- The point reached, resolution and whether the same issue occurs with keyboard input or another documented setting.
Remove personal paths and identifiers from excerpts. Keep disc images and generated game files on your device; they are not needed in a public issue.
Check existing issues or file a report ↗