Files
chess-3miz/README.md
T
2026-10-09 16:46:29 +03:30

6.6 KiB
Raw Blame History

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:

{ "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).

# 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=<shim re-exporting sdk/game-server-ts/src/{engine,seating,rng}.ts> \
  --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.