6.6 KiB
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, version1.0.0- Lafayette orientation: the board is shown from your own side (white sees
a8top-left, black seesh1top-left);a1is 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 = trueand 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|nin the move command (default queen; bots and timeout auto-moves always queen). Anything else →chess.invalid_promotion. - Timers: every turn has a
turn_msdeadline (table option, default 60 s); timeout plays the first legal move.$leaveabandons,$bot_replacesubs a bot. - Determinism (GS-610): time only via
ctx.now, randomness only viactx.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.