Marbel — the cave game
A browser game of the classic Bangladeshi childhood marble game: lob your
marble at the cave, flick it in to win the power, then knock your rival's
marble away. Version 1 is single player against a computer opponent.
Built with three.js and a custom physics engine
(no physics library) so that marbles roll, slide, bounce, drop into the cave
and skip over it the way real glass marbles do on packed dirt.
Version 2 adds online rooms: one player creates a room, shares a
six-letter code (or a link), and up to ten friends join and play on the
same yard from their own phones. See Online play and
Hosting the room server.
Run it
npm install
npm run dev # then open http://localhost:5173
Other commands:
npm test # physics, rules, sync and room-server tests (node:test)
npm run build # production build into dist/
npm run preview # serve the production build
npm run server # the online room server (serves dist/ too, port 8787)
npm run e2e # three real browsers play a room end to end (needs a build)
For online play during development run npm run server in one terminal and
npm run dev in another: the dev server proxies /ws to the room server.
The end-to-end suite uses Playwright's Chromium; install it once with
npx playwright install chromium.
Add ?debug=1 to the URL for a debug panel (force a marble to break on the
next hit, teleport both marbles next to the cave, give yourself the power,
let the computer play both sides, slow motion).
Deploy to Vercel
The game is a static Vite site, so Vercel needs no configuration beyond the
included vercel.json (framework Vite, npm run build, output dist/).
- From GitHub: on vercel.com choose Add New → Project, import this
repository, keep the detected settings and press Deploy. Every push to
main then redeploys automatically.
- From the terminal:
npx vercel (first time: log in and accept the
defaults), then npx vercel --prod for the production URL.
Nothing else is required: there is no server, no database and no
environment variable. The Bangla/English auto-detection calls ipwho.is from
the browser over HTTPS, which works on a Vercel domain.
Online play
On the setup screen, under Play with friends, press Create room. The
lobby shows a six-letter code; friends type it into the Join box (or open
the link that Copy link gives, which fills the code in). The host picks
the marble size everyone plays, the game end and the yard; up to ten
players can sit in a room, and the host starts when at least two are there.
Rules are the same as against the computer, extended to a circle of
players:
- Opening — everyone lobs from the line in join order; the closest to
the cave starts. Hands are spread along the line so nobody throws from
the same spot.
- Victim — the player whose marble yours touches first. Points and the
power transfer exactly as in a two-player game; a chain of marbles after
that first contact changes nothing in the score.
- Next to move — a marble that entered the cave on the shot (anyone's);
otherwise the shooter again after a counted hit; otherwise the next
player in the circle. A lifted marble faces the nearest rival.
- Turn timer — 60 seconds to shoot; 20 seconds if the player's phone
lost its connection; a player who left is skipped at once.
Phones go dark, tabs reload: a player keeps their seat. The browser
remembers the room for the tab, reconnects by itself, and shows a red banner
in the meantime. Opening the game in a second tab moves the seat there.
How it stays in sync: the room server runs the very same rules and physics
(src/game.js, src/physics.js) as every browser. A shot is one small
message (direction, power, lob angle, position on the line). The server
simulates it the moment it arrives and broadcasts the shot together with
the resulting yard; each browser animates the shot itself with the same
seeded randomness and then snaps to the server's result, so ten phones
with ten different floating-point units always agree. Spectators also see
the active player's slingshot as they pull.
Hosting the room server
The room server is server/index.js: plain Node 20+, one dependency
(ws), no database, a few megabytes of memory. It serves the built game
from dist/ as well, so one machine can host everything. Static hosting
(Vercel) cannot keep a socket open, so the server runs somewhere else:
| Variable | Meaning |
|---|
PORT | listen port, default 8787 |
HOST | bind address, default 0.0.0.0 |
ALLOWED_ORIGINS | extra page origins allowed to open sockets, comma-separated (the server's own host and localhost are always allowed) |
STATIC_DIR | folder to serve, default dist; 0 disables |
TRUST_PROXY | 1 behind a tunnel or reverse proxy, so limits apply per real client address |
On a spare laptop at home
Home connections in Bangladesh sit behind carrier-grade NAT, so the laptop
has no public address of its own. A free tunnel gives it an HTTPS address
anyway (the game page is HTTPS, so the socket must be wss:// too):
여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗
