huajishe-tts/CODEBUDDY.md

CODEBUDDY.md

This file provides guidance to CodeBuddy Code when working with code in this repository.

Overview

tts-like is a Tabletop Simulator-like board game platform built on boardgame.io (rules engine + relay server) with a React/SVG web client. The desktop shell uses Tauri (not yet started). The product name shown in the UI is 滑稽社TTS (hxs TTS).

The architecture is a strict 4-layer separation: game definitions (pure boardgame.io Game objects) ← rules engine (@tts-like/engine, pure functions, no UI/network) → network relay (@tts-like/server, server-authoritative) → UI (@tts-like/ui primitives rendered by apps/web).

Repository / Workspace layout

pnpm workspace (pnpm-workspace.yaml globs packages/* and apps/*). Each package/app has its own package.json with scripts; run them via pnpm --filter @tts-like/<name> <script> or pnpm -r <script> (recursive).

• packages/engine — Re-exports boardgame.io, the TTSGame type (boardgame.io Game + custom ui field), and the createLobbyClient lobby SDK. Holds all game definitions in src/games/*.ts (drag-test, war, mill/Nine Men's Morris, holdem/Texas Hold'em, pig/拱猪). Game logic has vitest unit tests (*.test.ts).
• packages/protocol — Types only (no runtime). Defines UISchema, ZoneDef, CardTemplate, ActionDef, and the resolveZoneEntities helper used by the UI to map game.ui.zones to entities in G.
• packages/ui — React UI primitives (Board, Zone, Card, Token, ActionButton, LobbyRoomList). Thin wrappers driven declaratively by game.ui.
• packages/server — Node/Koa server wrapping boardgame.io's Server with: /api-prefixed lobby routes, custom /api/rooms/* room management (delete/heartbeat/kick), an auth system (SQLite + JWT-style tokens), and static file serving of apps/web/dist in production.
• apps/web — Vite + React SPA. src/App.tsx is the single entry; it registers games in the GAMES map, handles local vs online modes, login modal, and mounts per-game Board components (src/*Board.tsx for Mill/Holdem/Pig; generic Board from @tts-like/ui for DragTest/War). Has Playwright E2E in e2e/.
• apps/desktop — Tauri shell scaffold (not yet active — only package.json scripts exist).
• docs/ — impl.md (high-level plan), ui-primitives.md (UI API spec), dev-log/ (chronological build log: README.md index, decisions.md, lessons-learned.md).

Common commands

Requires Node ≥ 22.12 and pnpm ≥ 10.16 (enable via corepack enable).

pnpm install                              # install workspace deps

# Dev: two processes (terminal 1 + terminal 2), or use run.sh for one-shot:
./run.sh                                 # starts server (:8000) + vite (:5173) via nvm
pnpm --filter @tts-like/server dev       # terminal 1: tsx watch relay server
pnpm dev                                 # terminal 2: vite web (:5173); proxy → :8000

# Build
pnpm -r build                            # build all packages + web (vite build → apps/web/dist)
pnpm --filter @tts-like/server build     # tsc → packages/server/dist

# Type check / tests / lint
pnpm -r ts                               # type-check every package
pnpm -r test                             # vitest run (engine + server unit tests)
pnpm --filter @tts-like/engine test      # single package test (vitest run)
pnpm lint                               # eslint .

# E2E (Playwright, auto-starts server + web)
pnpm test:e2e                           # = pnpm --filter @tts-like/web test:e2e
npx playwright install                  # first-time Chromium download
pnpm verify                             # ts && test && test:e2e

# Production
docker compose up --build               # server image (packages/server/Dockerfile)

To run a single unit test file: pnpm --filter @tts-like/engine exec vitest run src/games/war.test.ts. To run a single E2E spec: pnpm --filter @tts-like/web exec playwright test e2e/war-multiplayer.spec.ts.

Key architectural concepts

Game definitions = boardgame.io Game + ui field

Each game in packages/engine/src/games/*.ts exports a TTSGame (a boardgame.io Game plus a custom ui field that the UI consumes — boardgame.io ignores it). ui declares zones, cards template (SVG front/back), actions (buttons → moves), and optional overrides. The DragTest game is the minimal reference for this pattern (drag a card between zones via the transferCards move).

Adding a game requires three coordinated edits: (1) create packages/engine/src/games/<name>.ts, (2) register it in packages/server/src/index.ts (both the Server({ games: [...] }) array and the GAMES_ENTRIES array — these are separate and both needed), and (3) add an entry to the GAMES map in apps/web/src/App.tsx (with engineName matching the boardgame.io name, maxSeats, optional seatChoices/setupOptions).

UI is data-driven by game.ui

packages/ui/src/Board.tsx iterates game.ui.zones, resolves each zone's entities from G via resolveZoneEntities (protocol package; reads zone.collection for the ID array, zone.entityField for the ID→object map, defaulting to 'drawPile'), and renders <Zone>/<Card>. Drag-drop calls zone.dropMove with dropArgs. Player-view filtering (hiding opponents' cards) is handled entirely by boardgame.io's playerView server-side — the UI must NOT re-implement it. Holdem/Mill/Pig use bespoke Board components in apps/web/src/*Board.tsx instead of the generic Board.

Unified-port networking (dev-log #12)

The web (:5173) is the only port the browser/LAN sees. Vite proxies /api (→ :8000/api, rewritten to strip /api by mountApiPrefix) and /socket.io (ws) to the server (:8000). In production the server serves apps/web/dist itself, so a single port works. createLobbyClient('') uses same-origin /api automatically. ALLOWED_ORIGINS defaults to LAN ranges when unset (dev); set it explicitly in production.

Server is server-authoritative relay, not just boardgame.io

packages/server/src/index.ts mounts, in order: /healthz → room management (/api/rooms/*, must be registered before mountApiPrefix so raw /api/rooms paths are handled) → auth (/api/auth/*) → a gateway forcing login for create/join → mountApiPrefix (rewrites /api/* → boardgame.io router) → static serve. Room state, presence, and the single-room-per-user constraint are all in-memory maps in rooms.ts (lost on restart). Auth uses Node 22 built-in node:sqlite (auth-db.ts).

Player accounts & single-room constraint (dev-log #8/#12)

Create/join require a JWT-style token (HMAC-signed, 30-day TTL) from /api/auth/login or /api/auth/register. A logged-in user can only be in one room at a time (409 if already in another). rooms.ts enforces this and tracks userRoom/roomPlayers; /api/auth/me returns the current room so the client auto-reconnects. Admin users (preset e2hang/evan1115, overridable via env) can delete/kick in any room.

Conventions & gotchas

• TypeScript strict with noUncheckedIndexedAccess; target ES2022, moduleResolution: Bundler. packages/* are consumed via source (exports point to src/*.ts), so no build step is needed to use them — just pnpm install.
• boardgame.io version is pinned at 0.50.2 everywhere — keep it in sync across packages.
• packages/server uses ESM ("type": "module") with .js import specifiers (e.g. import './rooms.js') even though source is .ts — required for tsx/node --import tsx.
• Do not copy node_modules between machines; native deps (esbuild, Playwright browsers) are OS/arch-specific.
• Game moves mutate G directly (no Immer) — drag-test.ts notes a past bug where local-variable aliasing caused duplicate card inserts; always create new arrays when moving entities.
• GAME_ORDER in App.tsx controls the game dropdown order and default selection — edit there, not hardcoded elsewhere.
• Detailed historical decisions and pitfalls live in docs/dev-log/decisions.md and docs/dev-log/lessons-learned.md — consult before non-trivial changes.