@table-games-engine/game-kit 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,82 @@
+# @table-games-engine/game-kit
+
+Toolkit for building a turn-based multiplayer browser game (usually with an LLM such as Claude) and getting it ready for the [Logigra](https://logigra.ru) game store. It scaffolds a game package, ships the instructions your LLM follows, and gives you one command (`check`) that runs everything the store's CI runs.
+
+## Requirements
+
+- Node.js 20 or newer
+- Docker, only for `game-kit preview`
+
+## Quick start
+
+```sh
+npx @table-games-engine/game-kit create my-game     # scaffold + npm install
+cd my-game
+```
+
+Then build the game with your LLM. Point it at the skill shipped in the package:
+
+```
+node_modules/@table-games-engine/game-kit/skill/create-store-game.md
+```
+
+(the scaffold's `AGENTS.md` already says this). Give it your rules text, locales and player count. Iterate with:
+
+```sh
+npx game-kit test                 # your unit tests
+npx game-kit simulate -n 200      # random full matches, catches loops and illegal moves
+npx game-kit check                # everything CI runs; done when it prints "check: OK"
+npx game-kit preview              # play both seats locally (needs Docker)
+```
+
+## Commands
+
+| Command | Flags | What it does |
+|---|---|---|
+| `game-kit create <slug>` | `--no-install` | Scaffold a new game in `./<slug>`; installs dependencies unless `--no-install`. |
+| `game-kit test` | none | Runs the game's tests (vitest). |
+| `game-kit simulate` | `-n <matches>` (default 1000), `--seed <n>` (default 1), `--preset <id>`, `--players <n>` | Plays random matches to completion. By default covers every preset and every player count in `game.json`. |
+| `game-kit check` | none | Validates `game.json`, lints `logic/`, typechecks, runs tests, simulates, builds the client. |
+| `game-kit preview` | `--preset <id>`, `--locale <xx>` | Runs the game locally with both seats side by side. Needs Docker. |
+
+Numeric flags must be whole numbers (`-n` and `--players` at least 1).
+
+## What a game looks like
+
+```
+game.json          metadata: slug, name, players, locales, presets, rules files, client entry
+rules.md           rules text (rules.<locale>.md for more locales)
+logic/index.ts     server-side game logic: export default a GamePlugin
+client/            vite app (index.html, main.ts) shown to players
+tests/             vitest tests (the template drives a full match)
+```
+
+`game.json` is validated against `schema/game.schema.json` (referenced by `$schema` in the scaffold).
+
+**Logic.** `logic/index.ts` default-exports a `GamePlugin` from `@table-games-engine/core`: a manifest, `setup`, `actionHandlers`, `winConditionChecker`, and `legalMoves(state, playerId)`. `legalMoves` is optional in the core type but required by game-kit (`simulate` and `check` need it); it must list every concrete move that player may submit now (and `[]` when it is not their turn or the game is over). Logic must be deterministic and pure: no `Math.random`, `Date`, network or module-level mutable state. Use `ctx.random*` helpers for randomness. `check` enforces these rules.
+
+**Client.** The client runs in a sandboxed iframe with no network access. It talks to the store only through the bridge:
+
+```ts
+import { connectBridge, type StatePayload } from '@table-games-engine/game-kit/bridge';
+
+const bridge = connectBridge(
+  (s: StatePayload) => render(s),   // s.view, s.seat, s.legalMoves, s.status, s.result
+  (kind) => showNotice(kind),       // 'rejected' | 'reconnecting' | 'server-restart' | 'opponent-left'
+);
+// on a click: bridge.send(chosenMove)   // only moves from the latest s.legalMoves
+```
+
+The full contract, with common failures and fixes, is in the skill file above.
+
+## Publishing to the store
+
+Games are submitted by pull request to the curated Logigra catalog; request access at [logigra.ru](https://logigra.ru/en/docs/publishing/). Full docs: [logigra.ru/en/docs](https://logigra.ru/en/docs/quickstart/). A game must pass `game-kit check`.
+
+## Related packages
+
+[`@table-games-engine/core`](https://www.npmjs.com/package/@table-games-engine/core) (types and helpers your logic imports); the other `@table-games-engine/*` packages are installed for you.
+
+## Licence
+
+Apache-2.0. game-kit also depends on `@table-games-engine/nakama-adapter` and `@table-games-engine/persistence`, which are FSL-1.1-ALv2 (any use except a competing commercial service; each release becomes Apache-2.0 two years later). The games you build are yours.

package/package.json

@@ -1,16 +1,19 @@
 {
   "name": "@table-games-engine/game-kit",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "license": "Apache-2.0",
   "publishConfig": { "access": "public" },
   "description": "Build, check, simulate and preview store games on table-games-engine.",
+  "keywords": ["table-games", "turn-based", "multiplayer", "game-engine", "llm", "game-store"],
+  "homepage": "https://www.npmjs.com/package/@table-games-engine/game-kit",
   "type": "module",
   "bin": { "game-kit": "dist/cli.js" },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
     ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
-    "./bridge": { "types": "./dist/bridge.d.ts", "default": "./dist/bridge.js" }
+    "./bridge": { "types": "./dist/bridge.d.ts", "default": "./dist/bridge.js" },
+    "./package.json": "./package.json"
   },
   "files": ["dist", "schema", "template", "nakama", "host", "skill"],
   "scripts": {
@@ -20,9 +23,9 @@
   },
   "dependencies": {
     "@heroiclabs/nakama-js": "^2.7.0",
-    "@table-games-engine/core": "^0.1.0",
-    "@table-games-engine/nakama-adapter": "^0.1.0",
-    "@table-games-engine/persistence": "^0.1.0",
+    "@table-games-engine/core": "^0.1.1",
+    "@table-games-engine/nakama-adapter": "^0.1.1",
+    "@table-games-engine/persistence": "^0.1.1",
     "ajv": "^8.17.0",
     "esbuild": "^0.24.0",
     "eslint": "^9.0.0",

package/skill/create-store-game.md

@@ -4,15 +4,7 @@ Build a store game on table-games-engine in a standalone package created by
 `game-kit create`. You are done when `npx game-kit check` exits 0 and prints `check: OK`.
 Do not edit anything under `node_modules/`.
 
-> **Unpublished packages:** until `@table-games-engine/*` is on npm, you need the five
-> local tarballs (`core`, `persistence`, `nakama-adapter`, `client-sdk`, `game-kit`). Then:
-> ```sh
-> mkdir installer && (cd installer && npm init -y && npm install /path/to/tarballs/*.tgz)
-> npx --prefix ./installer game-kit create <slug> --no-install
-> cd <slug> && npm install /path/to/tarballs/*.tgz
-> ```
-> (`npx --package=<game-kit tgz>` alone fails: it cannot resolve the sibling packages.)
-> Once published, plain `npx @table-games-engine/game-kit create <slug>` installs for you.
+> **Install:** `npx @table-games-engine/game-kit create <slug>` scaffolds the game and installs its dependencies from public npm (add `--no-install` to skip the install).
 
 ## Inputs (ask the user if missing)
 

package/template/game.json

@@ -3,7 +3,7 @@
   "slug": "__SLUG__",
   "name": "__NAME__",
   "version": "0.1.0",
-  "engine": "^0.1.0",
+  "engine": "^0.1.1",
   "players": { "min": 2, "max": 2 },
   "locales": ["en"],
   "description": "Two wizards take turns casting Fire Bolt until one drops to 0 life.",

package/template/package.json

@@ -10,8 +10,8 @@
     "preview": "game-kit preview"
   },
   "devDependencies": {
-    "@table-games-engine/core": "^0.1.0",
-    "@table-games-engine/game-kit": "^0.1.0",
+    "@table-games-engine/core": "^0.1.1",
+    "@table-games-engine/game-kit": "^0.1.1",
     "typescript": "^5.4.0",
     "vite": "^5.4.0",
     "vitest": "^2.0.0"