One island, one beach ball, and everyone who has the page open.
Boogle is a small multiplayer browser game built with three.js and Rapier (physics, WASM). It is bundled with Vite.
Contributing? Start with CONTRIBUTING.md, then read DESIGN.md (the principles that decide design arguments), docs/decisions.md (the owner's decisions) and docs/plans/find-the-fun.md (what we're prototyping now).
npm ci
npm run dev
# then open the URL Vite prints (http://localhost:5173)Use Node 26 (.nvmrc). Installation also installs the server dependencies and pre-push hook. Other scripts: npm run check (lint, typecheck, unit tests, registry, asset checks and build), npm run build (production bundle in dist/), npm run preview (serve the build), npm run ship (ship your commits to main through a PR that merges itself; see CONTRIBUTING.md). Pick a room with /?room=my-friends (letters, digits and dashes; defaults to beach).
index.html holds only the markup; the game lives in src/:
main.ts: boot and the frame loop.loop.ts:onFrame/onStarthooks.features/: self-contained features (splashes, the Boogler, mushrooms, ...), each auto-loaded with its own CSS and DOM.constants.ts,math.ts: shared tuning values, math and noise helpers.style.css: base styles.render/: renderer, camera, lights, sky, sea shader, props (palms/rocks/clouds), particles, splashes and the shared audio context.physics/: the physics facade over Rapier (engine.ts), materials and step hooks; the ball and its ownership rules; thrown-item flights.player/: the local player and camera, avatar meshes, hands and what you hold, input and the control registry, HUD.netplay/:net.ts(presence, remote players and interpolation) and its pure helpers.net/ws-room.tsis the room, one WebSocket to our server (see src/net/README.md).adapters/: game-side halves of the lockstep rules (gifts, mushroom garden, piles).boogler/: The Boogler NPC, his talk and friendship.world/: shared deterministic state, edit sync and snapshots (see src/world/README.md).sim/: pure simulation logic (mushrooms, gifts, RNG) with unit tests intest/.atlas/: the internal architecture explainer at /atlas (facts fromdev/atlas/, narrative indocs/atlas/).- src/README.md maps every folder.
- Local:
npm run devruns our server in-process too (every room, saves in.boogle-data/): open two tabs on the same?room=to play together. Add?netdebug=1to the URL for connection logs. - Online: the deployed game uses our server (
VITE_BOOGLE_SERVER, see server/README.md), which hosts every room.
Our server hosts every room: each tab opens one WebSocket to it, and it runs the island's world (history: PLAN.md, "Key decision"). npm run test:net plays 3 headless browsers against a local server.
- Each client publishes one presence object about 20 times a second (
SEND_MS = 50): name, color, position, yaw, movement state. - Remote players are drawn 120 ms in the past (
INTERP_MS) and interpolated between snapshots. - The ball has a single owner at a time. The owner simulates it and adds it to their presence. Ownership uses an epoch counter: the highest epoch wins, and ties go to the larger peer ID. Grabbing the ball or walking into a slow ball claims it.
WASD move · Space jump · Mouse look · Click use what you hold (hold to charge a throw) · E interact. H, Esc or the menu button: menu and all controls; Menu on a gamepad. Touch devices get a stick and buttons. It is generated from the control registry in src/player/controls.ts, so a new control describes itself there.
Every merge to main builds and deploys to GitHub Pages at https://boogle.club/ (custom domain, set in the repo's Pages settings) via .github/workflows/deploy.yml, which runs lint, then npm run build (base /; a fork without a custom domain sets BASE: /<repo>/). You can also run it by hand from the Actions tab. The repo's Pages source must be set to "GitHub Actions".
To point the game at our server, set a repo variable named VITE_BOOGLE_SERVER (Settings, Secrets and variables, Actions, Variables) to the server URL, or run gh variable set VITE_BOOGLE_SERVER --body https://your-app.fly.dev, then re-run the workflow. A production build without it cannot connect to multiplayer; there is no PeerJS fallback. Local development supplies its own server automatically.
The one roadmap is docs/direction.md. See DESIGN.md for principles and docs/decisions.md for the owner's decisions.