# Chess — 3miz game bundle Standard 8×8 chess for two players, packaged as a 3miz game bundle (contract 36). Built from `templates/game-bundle` (the Tic-Tac-Toe sample) and adapted to this monorepo: deterministic TypeScript game server on the `@3miz/game-server-sdk` (contract 40) plus a sandboxed iframe client (contract 43). - `game_id`: `chess`, version `1.0.0` - Lafayette orientation: the board is shown from your own side (white sees `a8` top-left, black sees `h1` top-left); `a1` is always dark. ## Layout ``` games/chess/ game.json bundle descriptor (kind "source", server/client entries, catalog block) manifest.json game manifest, contract 30 (players, modes, options, bots, client/server …) README.md this file (also packed into the ZIP by tools/gamezip/zip.mjs) server/ main.ts entry point: runGameServer(chess) game.ts rules: state, init, apply, views/snapshot, timers, results bot.ts bot move choice (random legal move, queen on promotion) package.json @3miz/chess-server (deps: @3miz/game-server-sdk, @3miz/common) tsconfig.json extends the repo tsconfig.base.json client-src/ Vite + TypeScript browser client (source of truth for the UI) index.html iframe entry src/main.ts rendering, select→target picking, promotion picker, host bridge src/style.css board theme (square colours are assigned per square in JS) vite.config.ts relative base + alias for @3miz/game-client/iframe (see below) sdk-src/ iframe bridge copied from sdk/game-client.zip (build-time only) node_modules/ build-time only, never packed into the ZIP dist/ throwaway Vite output, synced into ../client/ before zipping client/ generated: the last good Vite build (what goes into the ZIP) tests/ game.test.ts rule tests, run against the real engine (see Testing) docs/ TIPS.md reviewer/developer notes ``` ## Rules implemented - All six pieces with standard movement, captures, alternating turns (white first). - **Check**: any move leaving your own king attacked is rejected (`chess.invalid_move`), so check is answered by king flight, capture, or block. - **Checkmate** (no legal reply) wins; **stalemate** (no legal move while safe) draws. No threefold-repetition, fifty-move, or insufficient-material draws. - **Castling**: rights start `wk/wq/bk/bq = true` and decay on king/rook moves and corner-rook captures. No castling out of, through, or into check. - **En passant**: a one-move window (`ep`) opens behind a double-stepping pawn. - **Promotion**: `promotion: q|r|b|n` in the move command (default queen; bots and timeout auto-moves always queen). Anything else → `chess.invalid_promotion`. - Timers: every turn has a `turn_ms` deadline (table option, default 60 s); timeout plays the first legal move. `$leave` abandons, `$bot_replace` subs a bot. - Determinism (GS-610): time only via `ctx.now`, randomness only via `ctx.rng`, no module-level mutable state — replays and failover stay exact. ## Wire protocol (client ⇄ server) One player command: ```jsonc { "type": "move", "payload": { "from": "e2", "to": "e4", "promotion": "q" } } // promotion: only "q" | "r" | "b" | "n", only when a pawn reaches the last rank ``` Snapshots (per view) carry `me`, `board: [{ square, type, color } × 64]` in `a1…h8` index order (the client re-orients for display), `turn`, `phase`, `winner`, `result_reason` (`"" | "checkmate" | "stalemate" | "abandoned"`), `check` (side to move is in check), `players`, `moves_played`, `captures`. No hidden information: all views see the same board. Error codes are `chess.not_a_player | chess.invalid_move | chess.invalid_square | chess.invalid_promotion | chess.unknown_type | chess.unknown_mode`. ## Build & ZIP Prerequisites: Node.js. All commands run from the repo root (`3miz-platform/`); PowerShell users should run `npm`/`npx` via `cmd /c` (execution policy blocks `npm.ps1`). ```powershell # 1. Build the client (resolves the game-client bridge via client-src/sdk-src) cmd /c "cd /d games\chess\client-src && npm install" # first time only cmd /c "cd /d games\chess\client-src && node_modules\.bin\vite.cmd build --base ./ --outDir dist --emptyOutDir" # 2. Sync the build output into client/ Remove-Item -Recurse -Force games\chess\client Copy-Item -Recurse -Force games\chess\client-src\dist games\chess\client # 3. ZIP it. zip.mjs prefers client-src/ and shells out to `npx` (absent on some # machines), so hide client-src/ while zipping and restore it afterwards: Move-Item games\chess\client-src C:\Temp\chess-client-src node tools/gamezip/zip.mjs games/chess chess-1.0.0.zip Move-Item C:\Temp\chess-client-src games\chess\client-src ``` Why `sdk-src/`? The client imports `@3miz/game-client/iframe`, which is not a published npm package — it lives in `sdk/game-client.zip`. `sdk-src/` is that zip's `src/` extracted, wired up by the `resolve.alias` in `client-src/vite.config.ts`, so a standalone `npm install` + `vite build` works. It is build tooling only: the ZIP packs `server/`, `client/`, `tests/`, `docs/`, `game.json`, `manifest.json`, `README.md` — never `client-src/`, `node_modules/`, or `dist/`. Upload: admin panel → *Games & deployments* → **Upload ZIP**, then raise the version's instances (suggested: 2). Play as admin; publish when ready. ## Testing Canonical (inside a full repo checkout with dev dependencies): ``` node --test --import tsx games/chess/tests/game.test.ts ``` The suite covers init layout, pawn direction both colours, knight jumps, bad squares, kingside castling + rights decay, en passant (window open/close), promotion to queen/knight (+ invalid piece rejected), fool's mate ending the game, answering `Qxf7+` (sideline rejected, `Kxf7` accepted), and a stalemate position. If `tsx` is unavailable, the same file can be run by bundling it with esbuild and aliasing the two workspace packages (this is how it was verified here): ``` esbuild --bundle --platform=node --format=esm --loader:.ts=ts \ --alias:@3miz/game-server-sdk= \ --alias:@3miz/common=packages/ts/common/src/jcs.ts \ games/chess/tests/game.test.ts --outfile=/tmp/chess-test.bundle.mjs node --test /tmp/chess-test.bundle.mjs ``` ## New versions Bump `version` in **both** `game.json` and `manifest.json` for every upload (versions are immutable). Keep PATCH/MINOR backward compatible per contract 35 (no removed modes/options, no narrowed bounds); breaking changes need a new MAJOR. `client.entry` / `server.image` URLs must match the new version.