Files

137 lines
6.6 KiB
Markdown
Raw Permalink Normal View History

2026-10-09 16:46:29 +03:30
# 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.1.0`
2026-10-09 16:46:29 +03:30
- 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=<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.