137 lines
6.6 KiB
Markdown
137 lines
6.6 KiB
Markdown
# 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`
|
||
- 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.
|