SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsgame-rules-engine

game-rules-engine

Coding & development

View repository

Updated 10-18 19:02

About this skill

Game rules engine

Makes every game's rules a pure, deterministic TypeScript engine behind one game contract: the same seed and moves give the same states on iOS, Android, Jest and Node, so bots, solvers, saves, undo, replays and the daily level can all trust it. The skill ships the kit (src/core/game/: the contract types, the difficulty scale and the test helpers), a complete template game (the public-domain puzzle Lights Out) and a checker that proves the kit, the seeded RNG against its golden values and each game's rules, by running them.

Rules that must hold

  1. The engine functions are pure and live in src/games/<game-id>/rules/, one per file: create.ts, list-moves.ts, apply-move.ts, outcome.ts, importing only src/core and the game's own rules/, levels/ and geom/. Why: bots, solvers, goldens and save replays call them headless thousands of times; one React Native, store or app import breaks all of that.
  2. Rules follow the determinism policy: only + - * /, %, bitwise operators and Math.sqrt/imul/floor/round/abs/min/max/PI; no **, no other Math.*, no Math.random, Date, performance.now, Intl, toLocale* or localeCompare (tests: no clock, no randomness either). Why: Hermes uses each platform's libm and locale data while Jest uses V8's, so replays and daily levels would diverge between an iPhone, an Android phone and CI (seeded-determinism-and-golden-vectors owns the policy).
  3. All randomness comes from src/core/rng/sfc32.ts, threaded as state. A game that draws after create() keeps rng: RngState in its state and every draw advances it; never re-seed from the move count. Why: same seed, same level, same daily and same replay on every device, and a continue or an undo cannot re-roll.
  4. sfc32.ts and its golden values never change: seedRng(1) draws 1828152527, 3394835397, 2967886022, 2251045104, 4148684523 and hashSeed('tasks:2026-09-26') is 2847463752. Why: they are the compatibility contract of every generated level, daily and saved run; a different generator is a new module under a new name, and a question for the developer.
  5. Copy the kit verbatim from templates/src/core/game/ and never rename a member (create, listMoves, applyMove, outcome, panMode, selectRegions, intentToMove, hud, undo, hints, continueRun; identity is { id, nameId }). Why: the session host, the bots, the solver, the canvas skills and the checker all call these exact names and shapes.
  6. The input is declared as data next to its intent function: panMode ('none' taps only, 'swipe', 'drag', 'aim') and selectRegions are literals in the module, and intentToMove (in src/games/<game-id>/canvas/) returns only moves listMoves lists and only for the intents that pan mode sends. Why: the screen enables exactly that gesture; a game expecting swipes on a 'none' surface is unplayable, and legality decided anywhere but listMoves lets bots and players disagree.
  7. Difficulty is one scale, whole numbers 0..100 (difficulty.ts): create clamps to it, tuning rows come from rowFor, levels and the daily use 0..99, and 100 (ENDLESS_DIFFICULTY) is the endless run of a game with an endless mode, which is never won. Why: the curve, the tuning, the daily and the saved runs must mean the same numbers, and there is no mode argument to tell an endless run apart.
  8. A selection is UI state, never a move. Tap-then-tap games list their selecting regions in selectRegions ([] for most); intentToMove returns null for a tap there and reads intent.selected on the next tap. Why: a select move would be seen by bots, the solver, par, undo and the counters.
  9. State, moves and events are JSON-safe: plain objects, arrays, finite numbers, strings, booleans, null; no Map, Set, Date, classes, undefined or typed arrays. Why: runs are saved as JSON after every move and replayed; anything JSON drops corrupts a save.
  10. applyMove never changes its input and throws RangeError for an illegal move. Why: the undo history keeps old states by reference, and a loud failure beats a silently corrupted save.
  11. **listMoves is empty exactly when outcome is not playing, in a fixed order; each way of losing has its own <game-id>.lose.<reason> key in every catalog of the app; win scores are whole numbers

    = 0.** Why: bots, solvers and the host's end-of-run logic rely on it, and every visible sentence is a translated message.

  12. Events are past tense, kebab-case, and carry every id and from/to value the animation and the counters need. Why: the surface only receives the final state; the events alone explain how it got there.
  13. Every rules folder has example tests, fast-check properties (determinism, invariants, end state, JSON round trip) and one pinned GOLDEN_* value, at 95/95/95/90 coverage. Why: the tests are the specification, and properties alone let real bugs survive.
  14. A saved run parses back to exactly itself. parseState / parseMove rebuild a fresh typed value with explicit checks (never json as State) and return null otherwise; stateVersion and migrateState handle older shapes. Why: a damaged or old save must drop only the run, not crash the app later.
  15. The testing spec plays fair: the bot picks only offered moves and returns its own seeded stream, and the start, middle, win, lose examples have exactly the outcome their names promise. Why: balance runs, hints, screenshots and E2E setup are built on them.
  16. Once the canvas exists, the game is one typed GameModule in src/games/<game-id>/<game-id>-game.ts whose identity.id is the folder name, with a test that runs the contract with its input. Why: the host binds games only through this value, and the id names the folder, the catalog namespace and every saved run.

Workflow

  1. Classify and plan. Read references/engine-contract.md. Classify the game (turn-based, simulate-then-replay, real-time) and write down in plain words: moves, win, each way of losing, score, undo, hints, continue, an endless mode (difficulty 100), the input (panMode, tap-then-tap selectRegions). If the design does not say, ask the developer (defaults: unlimited undo, or none when the game draws during play; no hints; no continue; no endless mode; taps only).
  2. Install the kit once per app. Pin fast-check exactly in the root devDependencies (the kit's, the RNG's and the rules' tests import it; without it tsc fails with TS2307 on every copied test): npm install -D -E fast-check@4.10.2 (verified on 2026-10-03; re-verify: npm view fast-check version). Run node ${CLAUDE_SKILL_DIR}/scripts/check-rules-engine.mjs .; for each kit-file-missing copy the file from templates/src/core/ to src/core/ verbatim (with its test). src/core/rng/sfc32.ts is canonical: if seeded-determinism-and-golden-vectors already put it there, keep that copy. A kit-member-missing line names an older copy: replace it and fix what tsc reports. Read references/determinism-and-rng.md before anything random.
  3. Copy the rules templates. templates/src/games/__GAME_ID__/ to src/games/<game-id>/, renaming files and replacing __GAME_ID__ (kebab case), __GAME_PASCAL__ and __GAME_CONST__ (UPPER_SNAKE). The template is a complete small game (Lights Out with a move budget); keep its structure and replace its logic test by test. Every balance number lives in <game-id>-tuning.ts.
  4. Add the catalog keys the templates name to every catalog of the app (src/i18n/catalogs/<locale>.json, i18n-strings-and-catalogs): assets/template-catalog-keys.json holds each key with an English and an RTL text (.name, .hud.moves, .continue.more-moves, .lose.out-of-moves, .stats.*). A renamed or new key (a lose reason, a hud line, a counter) goes into every catalog too, and translations go through the app's review queue.
  5. Write the rules test-first, in this order, following references/writing-rules.md and references/testing-rules.md: types, tuning and create (with its pinned golden), outcome and listMoves, applyMove, the rules members, persistence, counters, then the bot and example states. For each behaviour: one failing test, read the failure (an assertion, not an import error), minimum code, green. Imitate examples/pig/ for a game that draws during play, has an endless run or more than one way of losing.
  6. Assemble the engine (rules/<game-id>-engine.ts: <CONST>_ENGINE and <CONST>_RULES) and keep its contract test (<game-id>-engine.test.ts; add endless for a game with an endless mode).
  7. Assemble the module once the canvas exists. When canvas-gestures-and-hit-testing has written src/games/<game-id>/canvas/intent-to-move.ts, write <game-id>-game.ts and <game-id>-game.test.ts from examples/lights-out-module/, with panMode and selectRegions from step 1 and the intents the surface really sends. Until then the checker prints one SKIP for the module.
  8. Format, lint and type-check: npx eslint --fix src/games/<game-id> src/core/game, npx prettier --write src/games/<game-id> (import order depends on the game id), npm run typecheck.
  9. Run the tests with coverage: npx jest src/games/<game-id> --ci --selectProjects unit --coverage --collectCoverageFrom='src/games/<game-id>/rules/**/*.ts' --coverageThreshold='{}' (paths first; --coverageThreshold='{}' because a subset run cannot meet the global numbers) and read the table: rules stay at 95/95/95/90. When a module is finished, run Stryker on it (break threshold 75 %).
  10. Run the check node ${CLAUDE_SKILL_DIR}/scripts/check-rules-engine.mjs . --game <game-id>; fix every FAIL line (file, rule, fix) and rerun until RESULT: PASS. An engine-contract line names the seed and difficulty: add that case as an example test first, then fix the engine. Rules, options and troubleshooting: references/checker.md.

Definition of done

  • The root package.json pins fast-check exactly in devDependencies (no kit-test-dependency).
  • src/core/game/ holds the kit (ten contract files, difficulty.test.ts, the five testing helpers with their tests) and src/core/rng/sfc32.ts with its golden test, all passing.
  • src/games/<game-id>/rules/ has the types, tuning, create, list-moves, apply-move, outcome, engine, persistence and stats files, each with tests; testing/<game-id>-testing.ts has a bot and the four example states.
  • Every rules test file follows the loop: examples, fast-check properties, one GOLDEN_* value; the rules folder is at 95/95/95/90.
  • Every catalog key the rules and the module name (hud, stats, continue, each .lose.<reason>, .name) is in every catalog of the app.
  • Once the canvas exists, <game-id>-game.ts sets panMode and selectRegions, and its test runs engineContractProblems with the input (and endless when the game has an endless mode) and returns [].
  • npm run typecheck, npx eslint --max-warnings 0 and npx prettier --check pass for src/core/game and src/games/<game-id>; no __GAME_ placeholder is left.
  • node ${CLAUDE_SKILL_DIR}/scripts/check-rules-engine.mjs . --game <game-id> prints RESULT: PASS

A passing run may print SKIP src/games/<game-id>/canvas/intent-to-move.ts [module-missing] not yet created (canvas-gestures-and-hit-testing creates it) before the canvas surface exists, and SKIP src/i18n/catalogs [catalog-key-missing] not yet created (i18n-strings-and-catalogs creates it) before the app has catalogs. An app with no game prints NOT APPLICABLE: the app has no game (...).

Anti-patterns

  • Math.random() "just for a quick shuffle", or a seed from the clock. Replays and daily levels break silently; draw from state.rng (or drawOne/shuffle from src/core/rng/seeded-draws.ts).
  • Re-seeding inside applyMove from the move count to avoid storing the stream. Two runs that reach the same position by different paths then draw different futures, and a continue re-rolls.
  • Mutating the state in place for speed (state.cells[i] = 1). The undo stack and the saved snapshot share references; build new arrays with map and spreads.
  • Returning the old state for an illegal move. The bug hides until a save is corrupted; throw.
  • Legality in the gesture code, the screen or the store. Bots and solvers would disagree with players; only listMoves decides, and intentToMove asks it.
  • Choosing the pan mode in the screen. It belongs to the module next to intentToMove, where the contract test proves the two agree.
  • A select move for tap-then-tap. It pollutes bots, par, undo and the counters; list the region in selectRegions and read intent.selected.
  • A mode argument, or a tuning table indexed 0..3. Difficulty is one 0..100 scale; pick rows with rowFor and mark the endless run with difficulty 100.
  • Casting json as State in parseState. A damaged or old save then crashes later; rebuild the typed value with explicit checks and return null otherwise.
  • Sentences in rules (reasonKey: 'Out of moves!'). Return <game-id>.lose.<reason> keys; the app's i18n layer formats them in the user's language, left to right or right to left.
  • Editing a golden to make a test pass. A changed golden means shipped levels changed: change it only on purpose, with a Gate-Change: trailer, and never the RNG goldens.
  • Math.atan2 for a direction or ** for a square. Use dot products, committed direction tables and x * x.

Files in this skill

File What it is Read/run when
references/engine-contract.md The contract member by member, where code lives, difficulty and endless, input and selection, rules, persistence, stats, testing, the module, contract tests, game classes, multi-package Workflow step 1
references/determinism-and-rng.md The determinism policy applied to rules and why, the RNG API and goldens, randomness in create and during play, sims, particles, bots, the daily level Step 2, and before anything random
references/writing-rules.md Types, tuning and create, outcome and listMoves, applyMove, rules members, persistence, counters, bot, engine and module assembly, size limits Steps 3, 5, 6 and 7
references/testing-rules.md The loop, names, examples, the property checklist, pinned goldens, both contract tests, gates, commands, traps Steps 5 and 9
references/checker.md The checker's options, config keys, every rule, expected SKIP and NOT APPLICABLE lines, multi-package, troubleshooting Step 10, when a line is unclear
templates/src/core/game/ The kit: ten contract files (copy verbatim) and difficulty.test.ts. This skill owns them; their canonical copy is synced into level-generation-and-solvers, game-session-host and game-balance-and-bots, so a change here reaches all four Step 2
templates/src/core/game/testing/ play-choices, play-bot, json-shape, engine-contract, contract-intents, each with its test Step 2
templates/src/core/rng/ sfc32.ts and its golden test (synced; seeded-determinism-and-golden-vectors owns them) Step 2
templates/src/games/__GAME_ID__/rules/ The template game (Lights Out): types, tuning, create, toggle-cells, list-moves, apply-move, outcome, engine, persistence, stats, and their tests Step 3
templates/src/games/__GAME_ID__/testing/ Greedy bot and example states, with a test Step 3
examples/lights-out-module/ The module assembly with its contract test and the shape of the canvas intent function (canvas-gestures-and-hit-testing owns that file) Step 7
examples/pig/ Pig, a dice game that draws during play: the stream in the state, two ways of losing, an endless row, a continue, persistence of the stream, the hold-at-20 policy in rules/ (level-generation-and-solvers' witness uses the same file) re-exported as the bot, tests that read every knob from TUNING, and catalog-keys.json Step 5, for games that draw during play
assets/template-catalog-keys.json Every catalog key the templates name, with an English and an RTL (Arabic) text Step 4
assets/template-placeholders.json The values the self-test and the template verification fill in (lights-out) When adding a placeholder
assets/shared.json Declares the synced files (check-lib, app-modules, the canonical RNG, and this skill's own kit, template rules and Pig hold policy, whose canonical copies other games skills sync) When adding a shared file
scripts/check-rules-engine.mjs Checker: kit files and members, the fast-check pin, RNG goldens (run for real), purity, determinism, JSON state, events, throws, reason and catalog keys, tests, engine and module assembly, a seeded run with random play and the bot, endless never won Steps 2 and 10, and at the end
scripts/lib/ game-layout.mjs (folders and options), kit-checks.mjs, rules-checks.mjs, engine-run.mjs, ts-scan.mjs; app-modules.mjs is synced (do not edit here) When changing the checker
scripts/selftest.mjs Proves the checker: the templates and the module example must pass, the Pig example must pass, every planted bug must fail under its rule After changing the checker, a template or an example
scripts/check-lib.mjs Shared script library, synced (do not edit here) Never by hand
tests/bases/app/ The minimal app (package.json, tsconfig, catalogs) the fixtures lay the templates on When the fixture base changes
tests/fixtures/ check-rules-engine/: good/, one bad-* per rule, pass-* (before the canvas, before the catalogs, no game, kit only, the Pig example, installed skills, a custom games folder) and error-* cases When adding a rule to the checker

Related skills

  • seeded-determinism-and-golden-vectors - the determinism policy, sfc32, seeds, salts and golden vectors.
  • level-generation-and-solvers - generators, solvers, par, packs, stars and the daily level built on create.
  • game-session-host - hosting the module: the game screen, undo, hints, continue, saves and results.
  • canvas-gestures-and-hit-testing - intentToMove, the intents and the selection in the screen.
  • skia-canvas-rendering - the surface that draws the state and plays the events.
  • realtime-game-loop - real-time sims and simulate-then-replay physics.
  • game-balance-and-bots - bot policies, simulations and the tuning file.
  • new-game-scaffold - declaring the game and its catalog keys before the rules.
  • unit-and-component-tests - Jest projects, fast-check, coverage and mutation thresholds.
  • tdd-workflow - the red-green loop and evidence for every change.