Initial Commit
This commit is contained in:
@@ -0,0 +1,136 @@
|
||||
# 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:
|
||||
|
||||
```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.
|
||||
Reference in New Issue
Block a user