Files

137 lines
6.6 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.