PS2 browser player troubleshooting

Launch is disabled or browser checks fail

Read the named missing capability in the launcher’s browser check. Open the HTTPS site in an updated desktop browser and run the check again. Missing JSPI or Wasm features require a browser that implements them; rebuilding a game cannot add browser support.

Shared memory requires cross-origin isolation. A downloaded HTML page or a host missing the site’s COOP / COEP headers will not work. WebGPU is a separate check: when unavailable, the upstream software renderer may display menus but can be too slow for 3D.

Play!.js is blank or still loading

1. Wait for the file chooser inside the player. The outer page can observe the frame loading, but cannot confirm the third-party runtime has initialized.
2. If the frame remains blank, use the official player in a new tab. This also avoids the in-page credentialless-frame requirement.
3. Check your connection and whether a browser extension blocks the official player. A slow-load message is not proof of a network failure or incompatible game.
4. Close and reopen the embedded player to retry. Closing discards the temporary session, so export any saves first if that player offers export.

The official Play!.js page describes an experimental runtime. Desktop emulator reports do not establish browser compatibility.

Missing build file or invalid ISO

Select ps2web.html, ps2web.js, ps2web.wasm, ps2web.data and all generated worker scripts from one completed build. Source templates and files from different builds cannot be substituted.

The recompilation launcher accepts an uncompressed PS2 ISO. Renaming a CHD or archive does not convert it. Use the exact disc region and revision used to compile the build. The launcher checks file structure; it cannot prove that build and disc match. See the illustrated loading steps.

The local file bridge timed out

Keep the launcher tab open while playing. If registration or file attachment times out, reload this HTTPS page, select both file groups again and retry. Check that your browser allows service workers for this site. A lost session or an unselected worker file can cause local file requests to fail.

Export memory cards before reloading or clearing site data. Clearing browser storage can remove saves; it is not the first troubleshooting step.

The build opens but the game fails or runs slowly

Opening the build document does not mean Wasm initialization or gameplay succeeded. Use its Start button and read its own progress or error log. Check the matching ISO and complete build first.

For slow 3D, check the WebGPU result, browser hardware acceleration and GPU drivers, then try the build’s native resolution. Errors such as [sys] unhandled syscall or [iop] missing can indicate unfinished engine functionality. See the evidence for your game before assuming a supported configuration.

No live-user LCP, INP or CLS measurements are published here yet. A loading delay alone does not establish a Core Web Vitals failure. Compare real mobile and desktop field data separately when enough samples are available.

Compilation fails before “Build complete”

Keep the first terminal error and follow the OS-specific build fixes. On Windows, run the build inside Ubuntu / WSL2. On macOS, use Homebrew Bash 4+. A failed download or incomplete build needs to be resolved before selecting output files.

Report a website issue with the failed stage, OS, browser version and a redacted error excerpt. Include the engine revision for runtime errors. Do not publish game files or generated game code.