{"path":"README.md","content":"# Orbit Duel\n\nReal-time multiplayer space dogfight for 2-8 pilots: ships with inertia orbit a central planet in a wrap-around 1600x1600 world. One Cloudflare Worker with static assets, Durable Objects and D1.\n\n## How to play\n- Keyboard: A/D or arrows rotate, W or Up thrust, Space fire, Tab scoreboard, F3 debug.\n- Touch: left stick aims and thrusts, right button fires. Landscape is best.\n- 3 hits destroy a ship; the planet kills too. Respawn after 3 s with 2 s invulnerability. Power-ups: shield, triple shot, rapid fire.\n- First to 10 kills or 4 minutes wins; results show kills, deaths and accuracy, then a rematch starts.\n- Quick play joins the fullest open room; Create private room gives a link like `/r/ABC234`. Opening that link shows a join sheet over a live view of the room.\n\n## Run\n```\nnpm install\nnpx wrangler d1 migrations apply DB --local   # optional: local leaderboard table\nnpm run dev\nnpm test\nnpm run bots -- http://localhost:8787 --bots 3 --seconds 20\n```\nThe leaderboard also creates its table on first use (`CREATE TABLE IF NOT EXISTS`, same schema as `migrations/0001_init.sql`) and degrades to \"unavailable\" without a DB.\n\n## Architecture\n- `src/index.ts` routes: `/health`, `POST /api/rooms`, `/api/quickplay`, `/api/leaderboard?mode=duel`, `/ws/<CODE>`; everything else is static assets (SPA fallback for `/r/<CODE>`).\n- `src/room.ts` Room Durable Object: 30 Hz alarm loop, hibernation WebSockets, token-bucket rate limit, per-client delta snapshots. `src/lobby.ts` tracks rooms (players = connected player slots) for quick play and live counts.\n- `public/shared/` sim, rng and protocol shared by server, browser and tests. Bullets are never in snapshots: clients simulate them from `fire` events.\n\n## Protocol (compact JSON arrays)\nClient: `[\"j\",name,token|null,tick|null,_,watch?]`, `[\"i\",seq,rotate,thrust,fire,ackTick]`, `[\"a\",tick]`, `[\"p\",ms]`.\nServer: `[\"w\",...]` welcome, `[\"s\",tick,baseTick,lastInputSeq,delta]`, `[\"o\",ms,tick]`, `[\"v\",tick,...events]`, `[\"e\",code,msg]`.\n\n## File map\n- `public/app.js`, `index.html`, `style.css`, `_headers`: landing, join sheet, HUD, CSP.\n- `public/net.js`, `render.js`, `input.js`, `fx.js`, `audio.js`: client networking, canvas, input, particles, sound.\n- `scripts/bots.mjs`: load-test bots. `tests/`: node:test suites.\n\n## How to play\n\nDuel in orbit around a planet. 3 hits destroy a ship; the planet is lethal. First to 10 kills (or most after 4 min) wins; a results screen shows a podium and accuracy, then a new match starts.\n\n**Controls:** A/D or ←/→ rotate, W/↑ thrust, Space fire, Tab scoreboard, mute button in the HUD. Touch: left stick aims and thrusts, right button fires, Scores button toggles the scoreboard.\n\n## Architecture (text)\n\n```\nbrowser: input.js -> app.js -> net.js <== WebSocket ==> Worker (src/index.ts)\n            render.js/fx.js/audio.js              \\-> Durable Object room (src/room.ts)\n                                                       runs shared/sim.js at 30 Hz\n```\n\n## Protocol summary\n\nClient sends inputs `{rotate,thrust,fire}` with seq and snapshot-tick ack. Server sends welcome, full/delta snapshots and `[\"v\", tick, ...events]` (fire, hit, kill, crash, respawn, power, pickup, phase, results). Bullets are simulated client-side from fire events.\n\n## Measured performance\n\n| Metric | Value |\n|---|---|\n| Client fps | _TBD_ |\n| Server tick ms | _TBD_ |\n| Bandwidth per client | _TBD_ |\n","commitSha":"0413e5647b20f20529d6e6e08e1b756ac149f558"}