sometimestroubleshooting
the following checks address common installation, connection, playback and upload errors.
node or npm does not run
install Node.js, reopen the terminal, and check node --version and npm --version. if PowerShell blocks npm.ps1, use npm.cmd in place of npm for these commands; you do not need to weaken the execution policy. if package.json is missing, use cd to enter the project folder. if init says the folder exists, choose a new folder name rather than overwriting your work.
blank screen or connection timeout
open the simulator URL printed by npm run dev, not a source file or an HTML file directly. keep the terminal running. check its error output and the browser developer console. read session and environment only after connected resolves; call ready after mounting. after saving code, stop with Ctrl+C, restart and reload the new URL.
a click fails or the state looks old
show the action's error message. on conflict, refresh and let the player retry with the new revision. after a timeout, the action may already have committed: refresh or retry the same action ID, not a new ID. do not award points in the client or use a client timer to decide a winner. signals can be dropped, so use actions for updates that affect scores or other stored state.
a feature is unavailable
declare the needed capability in game.json: signals, previews, audio, haptics or saves. package assets locally; external fetches and arbitrary URLs are blocked. audio needs a player gesture and can be muted or suppressed while hidden. unlock it inside an input handler, handle playback errors, and keep visual feedback available. the host already plays start/join/stop cues.
build or upload fails
read the first build error and check the named file and import. upload output/game.sometimes.json. its ID must match your registration, and its version must be unused for that game. open the dashboard's verification report for capability, asset, size or rule errors. a successful local build is not approval; fix review feedback in a new version and resubmit.