Troubleshooting

The project is an early porting and runtime effort. At the reviewed commit, the author has brought up two games. This checklist draws on the public README and a review of the pinned browser runtime source; we have not independently reproduced the problems or verified remedies.

Start is marked unsupported

The startup gate in web/shell.html checks more than WebGPU. It requires cross-origin isolation (window.crossOriginIsolated), WebAssembly JSPI (WebAssembly.Suspending), exception handling using try_table, tail calls, and SIMD. The last three are checked by validating small WebAssembly modules. These are source-code-derived checks, not a browser certification established by our own testing.

When any check fails, the runtime lists the missing conditions and marks its Start action as unsupported. Capture that exact message before changing anything:

1. If cross-origin isolation is named, use the project server and check the game page’s response headers as described below.
2. If a WebAssembly feature is named, record the browser’s full version and check that specific capability. WebGPU support alone is not enough, and changing server headers does not add a missing WebAssembly implementation.
3. If you retry in another browser or release, record both results with the same project commit and game build.

The README’s Chrome and Edge guidance is tied to its source snapshot. It does not establish that every version works. We have no independently tested support matrix for Safari, Firefox, or phone browsers.

The page has no usable WebGPU adapter

The GPU renderer needs WebGPU. The author documents Chrome and Edge on Windows and macOS, plus additional experimental flags for the Linux setup described in the README. Check the browser guide and record your browser version, operating system, GPU, and any flags you change.

Without a usable adapter, the page switches to software rendering. The author describes it as adequate for menus and too slow for 3D. If a menu works but gameplay is very slow, establish which renderer is active before calling the result a game compatibility failure.

On a dual-GPU laptop, the source also describes a display problem when the discrete GPU draws a canvas that cannot be presented. The project tries both adapters and includes a 2D-canvas copy fallback. Their existence does not verify every hardware configuration; include exact adapter details when reporting a blank output.

Startup fails under a generic file server

Use the project server from Getting Started. The threaded runtime requires cross-origin isolation, with these response headers:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

The disc reader also depends on HTTP Range requests. scripts/serve.py supplies both the headers and Range support. Opening a generated page as a local file or using a server without those features is not the documented startup path. The runtime’s isolation check concerns the generated game page, not the static community site you are reading.

Keep this game-serving endpoint private, as the author’s hosting section instructs: anyone who can reach it can load the game.

A different game stops during discovery or gameplay

Building a page does not establish support for an arbitrary ISO. The author expects other titles to expose unimplemented system calls, missing I/O-processor library functions, or unsupported Graphics Synthesizer behavior.

Two log patterns specifically documented upstream are:

[sys] unhandled syscall
[iop] missing <library> #<n>

Preserve the actual library name or syscall detail and the surrounding log. Repeating the build is not a documented universal fix for missing runtime behavior.

The porting script’s discovery runs use automated Start and Cross inputs. Inspect games/mygame/shots to establish how far those runs reached. A different input sequence may exercise another path; the README exposes --press and --frames for controlling discovery. Record any custom values with the observed result.

Saves disappear after a setup change

The documented memory card is stored by the browser for the address you play from. First confirm the address and browser, and whether an exported card exists. Follow the save guide for the author’s export and import features. The source provides no recovery guarantee for deleted browser data.

If ?nocard is present in the URL, the page intentionally starts with no card inserted. Include that condition in any report about a missing card.

Graphics or audio resemble an old development bug

The README’s God of War II story includes silence, corrupted geometry, and a crash before combat. The author describes fixes for the timer, branch handling, and vector-unit timing that caused those symptoms. Keep them in historical context: they are not established present-day failures at this commit.

For a new occurrence, record the exact game release, project revision, scene, and logs. Describe the visible symptom first; do not assume its root cause. The God of War II record lists what the author now reports working.

Build a report someone can use

Capture the game region and revision; project commit; operating system; browser version; CPU and GPU; internal resolution; input method; steps to reproduce; furthest progress; and evidence links. Mark anything unavailable as unknown. State whether you reproduced the issue yourself or are citing someone else’s record.

The browser check can identify missing WebGPU or WebAssembly capabilities and copy the results for your setup notes. Compare your conditions with the published game records before drawing a broader compatibility conclusion.