Ludo Base is a Next.js 16 App Router game with wallet authentication, offline
bot matches, team play, Supabase-backed multiplayer, PeerJS handshakes, and
Farcaster-ready presentation. The lobby, board, and spectator views are
states of the single-page shell in app/page.tsx.
- Engine and rules reference
- Game Design Document
- Multiplayer smoke checklist
- Betting-window protocol ADR
- GDD visual asset guide
| Area | Location | Responsibility |
|---|---|---|
| App shell | app/page.tsx |
Lobby, board, spectating, and top-level state transitions |
| UI | app/components/ |
Lobby, board, token, chat, settings, and status surfaces |
| Game hooks | hooks/ |
Engine orchestration, matchmaking, realtime sync, timers, and data loading |
| Pure rules | lib/gameLogic.ts, lib/engine/core.ts |
Movement, capture, teams, powers, and server-validatable transitions |
| Board geometry | lib/boardLayout.ts |
Shared path, corner assignment, home lanes, and grid metadata |
| Match trust | lib/matchProof.ts, lib/matchRecorder.ts |
Canonical signed payloads and progression-only match records |
| Secure DMs | lib/encryption.ts |
ECDH P-256 sealed boxes with decrypt-only legacy support |
| Edge functions | supabase/functions/ |
Server-side dice, move authorization, power actions, and bet settlement |
The host (or compute host) is authoritative for networked game state. Guest intents travel over both PeerJS and Supabase Broadcast and are deduplicated by intent/action IDs. Networked dice and moves are server-validated; offline matches keep the local engine path.
Themes are applied as classes on <body>:
theme-retro-futurism— default dark terminal-glass theme with cyan accents.theme-daybreak— light soft-UI theme.
The preference cookie is ludo-theme; theme tokens live in
app/styles/themes/default.css and shared styles live in app/globals.css.
Requirements: Node.js 20+ and npm.
npm install
npm run devOpen http://localhost:3000.
Production validation:
npm test
npx tsc -p tsconfig.json --noEmit
npm run build
npm startnpm run lint is not currently supported because Next.js 16 removed
next lint; use the TypeScript check and build as the validation gate.
Create a local, untracked .env.local with the values required by the
deployment environment, including Supabase, wallet-connect, Farcaster/Neynar,
and (when enabled) the Edge Server URL. Never commit credentials or keys.
- Keep
TEAM_PAIRINGSinlib/constants.tsas the single source of truth for 2v2 teams. - Use
calculateNextPositionandgetLegalTokenIndicesfor move legality; do not replace gate-crossing logic withposition + roll. - Power tile types are authority-only and must be stripped with
lib/wireSanitize.tsbefore state is sent to guests. - New migrations belong in
supabase/migrations/; older root-levelmigrations/files are retained for historical compatibility. - Run the multiplayer smoke checklist after changing networking, settlement, encryption, or server-authority code.