Troubleshooting

npm run setup:assets says the GitHub CLI is missing or not signed in. Install gh and run gh auth login (GitHub.com, HTTPS, browser). The engine repository is private, so the CLI must be signed in to the account that has access.

A 404 from gh on pinionfall/engine. Check that you accepted the repository invitation (github.com/pinionfall/engine/invitations) and that gh auth status shows the same account.

setup:assets reports a checksum mismatch. The download was corrupted or interrupted. Delete the named file from .asset-cache/<tag>/ and run it again.

The page stays black, or says WebGPU is not supported. WebGPU is unavailable in this browser. Check chrome://gpu; on a laptop, make sure the browser runs on the discrete GPU.

Textures, models or props are missing, or the dev server logs 404s under public/. An asset bundle is missing or was only partly extracted. Run npm run setup:assets -- --force.

The game starts on lower graphics than expected, or says it lowered them. Open the GRAPHICS window: it shows what the detection measured and anything the game changed by itself after a session that did not end cleanly. Picking a preset there overrides both.

The page crashes or the GPU device is lost while loading. Load once with ?gfx=safe added to the address. If that works, pick Low in the GRAPHICS window and raise settings from there.

Nothing appears in the browser console. A production build is silent by design. Add ?diag to the URL to turn logging on.

Written by release:site-sync from SETUP.md at v2026.10.05. Edit the engine document, not this page.