Troubleshooting

#The page is stuck on "Loading the island…"

• Check the console. IslandGame.create() reports each stage (Shaping the island, Building the sky, …) on the loading screen. The last one shown is the stage that failed.
• WebGL2 is required. All four libraries need a WebGL2RenderingContext.
• lib/ is empty or missing a library. Vite fails to resolve naturegl-sky and friends. Run npm run sync-libs with the four library packages next to this one. See sync-libs and lib/.

#The keys don't do anything

• Click the canvas first. Keyboard input goes to the page, but in the embedded demo on these docs the iframe needs focus. Click inside it, or open the game in its own tab.
• A panel has focus. Keys are ignored while a slider, checkbox or dropdown in a HUD panel has focus. Click the canvas.
• Boarding needs you close. E only boards the boat within 7.5 m of it; watch the prompt at the bottom of the screen change to E Board boat.

#The mouse doesn't look around

Click the canvas to lock the pointer. Without pointer lock, drag to look. Opening a HUD panel releases the pointer; press Esc to release it yourself.

#Photos don't download

P saves a PNG through a download link. Some browsers ask for permission for repeated downloads from one page, and in the embedded demo on these docs the iframe may block downloads: open the game in its own tab.

#The boat won't turn

The rudder needs way on: it has no effect when the boat is stopped and full effect above 4 m/s. Open the throttle with W first.

#The boat bounces back

It hit the shallows (land within 0.85 m of the surface) or the pier. Reverse (S) and steer away.

#I can't get out of the water

Swim to the beach or to the pier head and hold Space at the surface. You climb out when the ledge is within 1.9 m of your eyes. The pier's sides have railings; the open side is the east side of the head, where the boat is moored.

#Low frame rate

• Use ?quality=medium or ?quality=low, or the Settings panel. See Performance and quality.
• The drone views are among the heaviest; setSkyPost(true) / ?skypost adds more.
• Make sure nothing else is using the GPU. The smoke-test numbers drop sharply with another GPU job running.

#Nights look too bright or too dark

Use the Exposure slider in the Sky & sea panel (0.5–1.8). It multiplies the sky's capped display exposure; the caps themselves are the maxExposure: 2.4 and nightExposure: 5 options in IslandGame._init().

#npm test fails

• No Chromium. The scripts look for a Playwright Chromium in ~/Library/Caches/ms-playwright. For npm test, set CHROMIUM_PATH to use another one, or install one with npx playwright-core install chromium.
• A console error. The smoke test fails on any console.error, page error or HTTP error. The output lists them.
• Timeout waiting for __pro.ready. The GPU is busy, or WebGL2 is not available headless. Run with --headed to watch.

#The built site shows a blank page from a sub-folder

It shouldn't: the Vite base is ./. If you moved dist/demo/ without dist/assets/ and dist/models/, move them together. The game loads the Kenney props from ../models/pirate-kit/ relative to the page.