game-rules-engine
Builds a game's pure rules - GameModule contract, create/listMoves/applyMove/outcome, events, sfc32 RNG goldens, determinism, persistence, counters, property tests. Use when writing rules, moves, scoring or randomness. Not for levels (level-generation-and-solvers) or wiring (game-host-integration).
- License 许可
- MIT
- 最近更新
- 2026-11-05
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- game-rules-engine
- description
- Builds a game's pure rules - GameModule contract, create/listMoves/applyMove/outcome, events, sfc32 RNG goldens, determinism, persistence, counters, property tests. Use when writing rules, moves, scoring or randomness. Not for levels (level-generation-and-solvers) or wiring (game-host-integration).
02 资源文件 181
- 资产文件assets/shared.json1.8 KB
- 资产文件assets/template-catalog-keys.json1.6 KB
- 参考文档examples/line-siege/i18n/ckb.json2.4 KB
- 参考文档examples/line-siege/i18n/de.json1.8 KB
- 参考文档examples/line-siege/i18n/en.json1.6 KB
- 参考文档examples/line-siege/i18n/fa.json2.3 KB
- 脚本examples/line-siege/rules/apply-move.test.ts10.3 KB
- 脚本examples/line-siege/rules/apply-move.ts4.2 KB
- 脚本examples/line-siege/rules/board-lines.test.ts3.2 KB
- 脚本examples/line-siege/rules/board-lines.ts1.9 KB
- 脚本examples/line-siege/rules/continue-run.test.ts6.7 KB
- 脚本examples/line-siege/rules/continue-run.ts2.9 KB
- 脚本examples/line-siege/rules/create.test.ts3.8 KB
- 脚本examples/line-siege/rules/create.ts1.3 KB
- 脚本examples/line-siege/rules/intent-to-move.test.ts4.6 KB
- 脚本examples/line-siege/rules/intent-to-move.ts2.4 KB
- 脚本examples/line-siege/rules/line-siege-engine.test.ts3.4 KB
- 脚本examples/line-siege/rules/line-siege-engine.ts2.3 KB
- 脚本examples/line-siege/rules/line-siege-evaluate.test.ts1.1 KB
- 脚本examples/line-siege/rules/line-siege-evaluate.ts971 B
- 脚本examples/line-siege/rules/line-siege-persistence.test.ts4.1 KB
- 脚本examples/line-siege/rules/line-siege-persistence.ts4.7 KB
- 脚本examples/line-siege/rules/line-siege-stats.test.ts2.0 KB
- 脚本examples/line-siege/rules/line-siege-stats.ts1.3 KB
- 脚本examples/line-siege/rules/line-siege-tuning.test.ts1.6 KB
- 脚本examples/line-siege/rules/line-siege-tuning.ts5.3 KB
- 脚本examples/line-siege/rules/line-siege-types.ts4.1 KB
- 脚本examples/line-siege/rules/list-moves.test.ts1.2 KB
- 脚本examples/line-siege/rules/list-moves.ts428 B
- 脚本examples/line-siege/rules/monster-attack.test.ts5.6 KB
- 脚本examples/line-siege/rules/monster-attack.ts3.1 KB
- 脚本examples/line-siege/rules/monster-march.test.ts5.3 KB
- 脚本examples/line-siege/rules/monster-march.ts3.7 KB
- 脚本examples/line-siege/rules/opening.test.ts3.2 KB
- 脚本examples/line-siege/rules/opening.ts4.0 KB
- 脚本examples/line-siege/rules/outcome.test.ts2.6 KB
- 脚本examples/line-siege/rules/outcome.ts1.5 KB
- 脚本examples/line-siege/rules/pieces.test.ts1.6 KB
- 脚本examples/line-siege/rules/pieces.ts1.7 KB
- 脚本examples/line-siege/rules/placement.test.ts1.5 KB
- 脚本examples/line-siege/rules/placement.ts1.6 KB
- 参考文档references/determinism-and-rng.md8.1 KB
- 参考文档references/engine-contract.md16.8 KB
- 参考文档references/testing-rules.md9.3 KB
- 参考文档references/writing-rules.md16.1 KB
- 脚本scripts/check-lib.mjs44.4 KB
- 脚本scripts/check-rules-engine.mjs6.8 KB
- 脚本scripts/lib/app-modules.mjs2.8 KB
- 脚本scripts/lib/assemble-fixtures.mjs3.6 KB
- 脚本scripts/lib/engine-run.mjs13.5 KB
- 脚本scripts/lib/kit-checks.mjs9.9 KB
- 脚本scripts/lib/rules-checks.mjs20.6 KB
- 脚本scripts/lib/ts-scan.mjs3.0 KB
- 脚本scripts/selftest.mjs2.4 KB
- 脚本templates/apps/__GAME_ID__/src/rules/__GAME_ID__-engine.test.ts2.1 KB
- 脚本templates/apps/__GAME_ID__/src/rules/__GAME_ID__-engine.ts1.8 KB
- 脚本templates/apps/__GAME_ID__/src/rules/__GAME_ID__-persistence.test.ts1.6 KB
- 脚本templates/apps/__GAME_ID__/src/rules/__GAME_ID__-persistence.ts2.1 KB
- 脚本templates/apps/__GAME_ID__/src/rules/__GAME_ID__-stats.test.ts1.1 KB
- 脚本templates/apps/__GAME_ID__/src/rules/__GAME_ID__-stats.ts1.2 KB
- 脚本templates/apps/__GAME_ID__/src/rules/__GAME_ID__-tuning.test.ts1.4 KB
- 脚本templates/apps/__GAME_ID__/src/rules/__GAME_ID__-tuning.ts2.6 KB
- 脚本templates/apps/__GAME_ID__/src/rules/__GAME_ID__-types.ts1.2 KB
- 脚本templates/apps/__GAME_ID__/src/rules/apply-move.test.ts4.1 KB
- 脚本templates/apps/__GAME_ID__/src/rules/apply-move.ts1.4 KB
- 脚本templates/apps/__GAME_ID__/src/rules/create.test.ts2.0 KB
- 脚本templates/apps/__GAME_ID__/src/rules/create.ts1.6 KB
- 脚本templates/apps/__GAME_ID__/src/rules/flip-cells.test.ts1.4 KB
- 脚本templates/apps/__GAME_ID__/src/rules/flip-cells.ts921 B
- 脚本templates/apps/__GAME_ID__/src/rules/list-moves.ts613 B
- 脚本templates/apps/__GAME_ID__/src/rules/outcome.test.ts1.5 KB
- 脚本templates/apps/__GAME_ID__/src/rules/outcome.ts747 B
- 脚本templates/apps/__GAME_ID__/src/testing/__GAME_ID__-testing.test.ts1.6 KB
- 脚本templates/apps/__GAME_ID__/src/testing/__GAME_ID__-testing.ts1.6 KB
- 脚本templates/packages/game-kit/src/contract/difficulty.test.ts1.8 KB
- 脚本templates/packages/game-kit/src/contract/difficulty.ts1.6 KB
- 脚本templates/packages/game-kit/src/contract/game-engine.ts2.2 KB
- 脚本templates/packages/game-kit/src/contract/game-identity.ts740 B
- 脚本templates/packages/game-kit/src/contract/game-module.ts1.8 KB
- 脚本templates/packages/game-kit/src/contract/game-rules.ts1.6 KB
- 脚本templates/packages/game-kit/src/contract/input-intent.ts1.7 KB
- 脚本templates/packages/game-kit/src/contract/levels.ts2.8 KB
- 脚本templates/packages/game-kit/src/contract/messages.ts759 B
- 脚本templates/packages/game-kit/src/contract/persistence.ts1.2 KB
- 脚本templates/packages/game-kit/src/contract/realtime.ts1.1 KB
- 脚本templates/packages/game-kit/src/contract/stats.ts867 B
- 脚本templates/packages/game-kit/src/contract/teaching.ts1.4 KB
- 脚本templates/packages/game-kit/src/contract/testing.ts506 B
- 脚本templates/packages/game-kit/src/geom/board-layout-edges.test.ts1.4 KB
- 脚本templates/packages/game-kit/src/geom/board-layout.test.ts3.9 KB
- 脚本templates/packages/game-kit/src/geom/board-layout.ts5.9 KB
- 脚本templates/packages/game-kit/src/geom/classify-swipe.test.ts999 B
- 脚本templates/packages/game-kit/src/geom/classify-swipe.ts1.8 KB
- 脚本templates/packages/game-kit/src/rng/pick-at.test.ts341 B
- 脚本templates/packages/game-kit/src/rng/pick-at.ts428 B
- 脚本templates/packages/game-kit/src/rng/sfc32.test.ts3.0 KB
- 脚本templates/packages/game-kit/src/rng/sfc32.ts2.8 KB
- 脚本templates/packages/game-kit/src/testing/contract-intents.test.ts2.6 KB
- 脚本templates/packages/game-kit/src/testing/contract-intents.ts4.6 KB
- 脚本templates/packages/game-kit/src/testing/engine-contract.test.ts10.6 KB
- 脚本templates/packages/game-kit/src/testing/engine-contract.ts9.1 KB
- 脚本templates/packages/game-kit/src/testing/json-shape.test.ts870 B
- 脚本templates/packages/game-kit/src/testing/json-shape.ts1.6 KB
- 脚本templates/packages/game-kit/src/testing/play-bot.test.ts3.1 KB
- 脚本templates/packages/game-kit/src/testing/play-bot.ts3.5 KB
- 脚本templates/packages/game-kit/src/testing/play-choices.test.ts722 B
- 脚本templates/packages/game-kit/src/testing/play-choices.ts1.2 KB
- 脚本templates/packages/game-kit/src/testing/teaching-contract.test.ts4.2 KB
- 脚本templates/packages/game-kit/src/testing/teaching-contract.ts2.3 KB
- 脚本templates/packages/game-kit/src/timeline/track.test.ts1.1 KB
- 脚本templates/packages/game-kit/src/timeline/track.ts1.9 KB
- 参考文档tests/fixtures/check-rules-engine/bad-assembled-no-stats/EXPECT.txt58 B
- 参考文档tests/fixtures/check-rules-engine/bad-assembled-no-stats/mutation.json257 B
- 参考文档tests/fixtures/check-rules-engine/bad-catalog-key-missing/EXPECT.txt127 B
- 参考文档tests/fixtures/check-rules-engine/bad-catalog-key-missing/mutation.json161 B
- 参考文档tests/fixtures/check-rules-engine/bad-create-finished/EXPECT.txt62 B
- 参考文档tests/fixtures/check-rules-engine/bad-create-finished/mutation.json403 B
- 参考文档tests/fixtures/check-rules-engine/bad-endless-won/EXPECT.txt55 B
- 参考文档tests/fixtures/check-rules-engine/bad-endless-won/mutation.json471 B
- 参考文档tests/fixtures/check-rules-engine/bad-event-tense/EXPECT.txt74 B
- 参考文档tests/fixtures/check-rules-engine/bad-event-tense/mutation.json137 B
- 参考文档tests/fixtures/check-rules-engine/bad-example-state/EXPECT.txt107 B
- 参考文档tests/fixtures/check-rules-engine/bad-example-state/mutation.json175 B
- 参考文档tests/fixtures/check-rules-engine/bad-fast-check-missing/EXPECT.txt105 B
- 参考文档tests/fixtures/check-rules-engine/bad-fast-check-missing/mutation.json150 B
- 参考文档tests/fixtures/check-rules-engine/bad-fast-check-range/EXPECT.txt68 B
- 参考文档tests/fixtures/check-rules-engine/bad-fast-check-range/mutation.json121 B
- 参考文档tests/fixtures/check-rules-engine/bad-fractional-score/EXPECT.txt74 B
- 参考文档tests/fixtures/check-rules-engine/bad-fractional-score/mutation.json212 B
- 参考文档tests/fixtures/check-rules-engine/bad-impure-import/EXPECT.txt75 B
- 参考文档tests/fixtures/check-rules-engine/bad-impure-import/mutation.json289 B
- 参考文档tests/fixtures/check-rules-engine/bad-kit-missing/EXPECT.txt65 B
- 参考文档tests/fixtures/check-rules-engine/bad-kit-missing/mutation.json64 B
- 参考文档tests/fixtures/check-rules-engine/bad-kit-old-intent/EXPECT.txt110 B
- 参考文档tests/fixtures/check-rules-engine/bad-kit-old-intent/mutation.json257 B
- 参考文档tests/fixtures/check-rules-engine/bad-list-after-end/EXPECT.txt32 B
- 参考文档tests/fixtures/check-rules-engine/bad-list-after-end/mutation.json146 B
- 参考文档tests/fixtures/check-rules-engine/bad-math-pow/EXPECT.txt63 B
- 参考文档tests/fixtures/check-rules-engine/bad-math-pow/mutation.json217 B
- 参考文档tests/fixtures/check-rules-engine/bad-math-random/EXPECT.txt65 B
- 参考文档tests/fixtures/check-rules-engine/bad-math-random/mutation.json190 B
- 参考文档tests/fixtures/check-rules-engine/bad-mutating-apply/EXPECT.txt52 B
- 参考文档tests/fixtures/check-rules-engine/bad-mutating-apply/mutation.json203 B
- 参考文档tests/fixtures/check-rules-engine/bad-no-golden/EXPECT.txt16 B
- 参考文档tests/fixtures/check-rules-engine/bad-no-golden/mutation.json138 B
- 参考文档tests/fixtures/check-rules-engine/bad-no-property-test/EXPECT.txt45 B
- 参考文档tests/fixtures/check-rules-engine/bad-no-property-test/mutation.json234 B
- 参考文档tests/fixtures/check-rules-engine/bad-no-throw/EXPECT.txt22 B
- 参考文档tests/fixtures/check-rules-engine/bad-no-throw/mutation.json130 B
- 参考文档tests/fixtures/check-rules-engine/bad-pan-mode/EXPECT.txt109 B
- 参考文档tests/fixtures/check-rules-engine/bad-pan-mode/mutation.json130 B
- 参考文档tests/fixtures/check-rules-engine/bad-parse-state/EXPECT.txt75 B
- 参考文档tests/fixtures/check-rules-engine/bad-parse-state/mutation.json193 B
- 参考文档tests/fixtures/check-rules-engine/bad-placeholder-left/EXPECT.txt35 B
- 参考文档tests/fixtures/check-rules-engine/bad-placeholder-left/mutation.json170 B
- 参考文档tests/fixtures/check-rules-engine/bad-reason-key/EXPECT.txt80 B
- 参考文档tests/fixtures/check-rules-engine/bad-reason-key/mutation.json154 B
- 参考文档tests/fixtures/check-rules-engine/bad-rng-after-create/EXPECT.txt19 B
- 参考文档tests/fixtures/check-rules-engine/bad-rng-after-create/mutation.json553 B
- 参考文档tests/fixtures/check-rules-engine/bad-rng-golden/EXPECT.txt82 B
- 参考文档tests/fixtures/check-rules-engine/bad-rng-golden/mutation.json140 B
- 参考文档tests/fixtures/check-rules-engine/bad-rng-helper-extensionless/EXPECT.txt19 B
- 参考文档tests/fixtures/check-rules-engine/bad-rng-helper-extensionless/mutation.json1.1 KB
- 参考文档tests/fixtures/check-rules-engine/bad-rng-helper-in-play/EXPECT.txt19 B
- 参考文档tests/fixtures/check-rules-engine/bad-rng-helper-in-play/mutation.json1.1 KB
- 参考文档tests/fixtures/check-rules-engine/bad-rng-no-worklet/EXPECT.txt14 B
- 参考文档tests/fixtures/check-rules-engine/bad-rng-no-worklet/mutation.json102 B
- 参考文档tests/fixtures/check-rules-engine/bad-rng-play-engine-called-by-create/EXPECT.txt19 B
- 参考文档tests/fixtures/check-rules-engine/bad-rng-play-engine-called-by-create/mutation.json976 B
- 参考文档tests/fixtures/check-rules-engine/bad-rng-test-edited/EXPECT.txt37 B
- 参考文档tests/fixtures/check-rules-engine/bad-rng-test-edited/mutation.json115 B
- 参考文档tests/fixtures/check-rules-engine/bad-select-regions/EXPECT.txt102 B
- 参考文档tests/fixtures/check-rules-engine/bad-select-regions/mutation.json120 B
- 参考文档tests/fixtures/check-rules-engine/bad-state-set/EXPECT.txt59 B
- 参考文档tests/fixtures/check-rules-engine/bad-state-set/mutation.json204 B
- 参考文档tests/fixtures/check-rules-engine/pass-draws-in-create-helper/EXPECT.txt13 B
- 参考文档tests/fixtures/check-rules-engine/pass-draws-in-create-helper/mutation.json659 B
- 参考文档tests/fixtures/check-rules-engine/pass-irregular-past-event/EXPECT.txt13 B
- 参考文档tests/fixtures/check-rules-engine/pass-irregular-past-event/mutation.json413 B
- 参考文档tests/fixtures/check-rules-engine/pass-rng-in-create-helper/EXPECT.txt13 B
- 参考文档tests/fixtures/check-rules-engine/pass-rng-in-create-helper/mutation.json855 B
03 SKILL.md 正文
Game rules engine
Makes every Pocket Arcade game's rules a pure, deterministic TypeScript engine behind the GameModule contract: the same seed and moves give the same states on every phone, in Jest and in Node, so bots, solvers, saves, undo, replays and daily challenges can all trust it. A script proves the contract files, the seeded RNG against its golden values, and each game's rules, by running them.
Rules that must hold
- The engine functions are pure and live in
apps/<game-id>/src/rules/, one per file:create.ts,list-moves.ts,apply-move.ts,outcome.ts, importing only@e07/game-kitand their own files. Why: bots, solvers, goldens and the save replay call them headlessly thousands of times; one React Native import breaks all of that. - Determinism policy: only
+ - * /,%, bitwise operators andMath.sqrt/imul/floor/round/abs/min/max/PI; no**, no otherMath.*, noMath.random,Date,performance.noworIntl(tests too: no clock, no random). Why: Hermes and V8 compute transcendental maths differently, so replays and daily levels would diverge between phones. - All randomness comes from the seeded sfc32 RNG, and a game that draws after
create()keepsrng: RngStatein its state and threads it through every draw. Why: same seed, same level, same daily, same replay on every device (spec 8.3, 8.13). sfc32.tsand its golden values never change:seedRng(1)draws1828152527, 3394835397, 2967886022, 2251045104, 4148684523andhashSeed('line-siege:2026-09-26')is2224665572. Why: they are the compatibility contract of every generated level, daily challenge and saved replay; a change is a new RNG and a question for the owner.- Copy the contract files verbatim from
templates/packages/game-kit/src/contract/and never rename a member (create,listMoves,applyMove,outcome,panMode,selectRegions,intentToMove,buildTimeline,hud,undo,hints,continueRun;identityis{ id, nameId, winTitleId, taglineId }). Why: the Shell, the board skills and the checks all depend on these exact names and shapes. - The engine declares the board's pan gesture as
panMode('none'taps only,'swipe','drag','aim'; real-time games'none'), andintentToMoveturns only the intents that mode sends into moves. Why: the Shell's board host enables exactly that gesture; a game expecting swipes on a'none'board is unplayable, andengineContractProblemsreports it. - Difficulty is one scale, whole numbers 0..100 (
contract/difficulty.ts):createclamps to it, 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 rows, the daily and the save schema must mean the same numbers, and there is no mode argument to tell an endless run apart. - A selection is UI state, never a move. Tap-then-tap games list their selecting regions in
selectRegions([]for most,['tray']for Line Siege);intentToMovereturnsnullfor a tap there and readsintent.selectedon the next tap. Why: aselectmove would be seen by bots, the witness solver, par, undo and the counters. - State, moves and events are JSON-safe: plain objects, arrays, finite numbers, strings, booleans,
null; noMap,Set,Date, classes orundefined. Why: runs are saved as JSON after every move and replayed; anything JSON drops corrupts a save. applyMovenever changes its input and throwsRangeErrorfor an illegal move. Why: the undo history keeps old states by reference, and a loud failure beats a silently corrupted save.listMovesis empty exactly whenoutcomeis notplaying, in a fixed order; each way of losing has its own<game-id>.lose.<reason>catalog key; win scores are whole numbers >= 0. Why: bots, solvers and the Shell's end-of-run logic rely on it, and every visible sentence is a translated message.- Events are past tense, kebab-case, and carry every id and from/to value the animation and counters need. Why: the board only receives the final state; the events alone explain how it got there.
- Every rules module 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 owner never reads code; tests are the specification, and properties alone let real bugs survive.
Workflow
- Classify and plan. Read references/engine-contract.md. Classify the game (turn-based, simulate-then-replay, real-time), write down moves, win, each way of losing, score, undo, hints, continue, whether it has an endless mode (difficulty 100) and the input (taps only, swipe, drag or aim: the engine's
panMode; tap-then-tap: itsselectRegions) in plain words, and ask the owner if the design notes do not say (defaults: unlimited undo, no hints, no continue). - Install the game-kit contract once per repo. First install fast-check, which the kit's and the rules' tests import and the bootstrap leaves out (without it
tscandeslintfail with TS2307 on every copied test):npm install -D -E fast-check@4.10.2at the repo root (skip it when the rootdevDependenciesalready pin it), thennpm approve-scripts --allow-scripts-pendingand, if it listsfsevents(the macOS file watcher of jest-haste-map),npm approve-scripts fsevents. Then runnode ${CLAUDE_SKILL_DIR}/scripts/check-rules-engine.mjs .; for eachkit-file-missingcopytemplates/packages/game-kit/src/<path>topackages/game-kit/src/<path>verbatim (with its test).geom/board-layout.ts,geom/classify-swipe.ts,timeline/track.tsandcontract/input-intent.tsare shared with the board skills: copy them only when missing, they are the same text. Akit-member-missingline names an older contract copy (noselectRegions, no tapselected, no solverfinal): replace that file with the template and fix whattscthen reports. Read references/determinism-and-rng.md before touching anything random. - Copy the rules templates.
templates/apps/__GAME_ID__/src/rules/toapps/<game-id>/src/rules/andtemplates/apps/__GAME_ID__/src/testing/toapps/<game-id>/src/testing/, renaming files and replacing__GAME_ID__(kebab-case),__GAME_PASCAL__and__GAME_CONST__(UPPER_SNAKE). The template is a complete small game (Tap Flip); keep its structure and replace its logic test by test. Its balance numbers live in<game-id>-tuning.ts(board side by tuning row, scramble presses, moves per press, points, continue moves); keep every new balance number there too. - Add these keys to
apps/<game-id>/src/i18n/{en,de,fa,ckb}.json: every catalog key the templates name, with its four texts, is in assets/template-catalog-keys.json (__GAME_ID__.hud.moves,.continue.more-moves,.lose.out-of-moves,.stats.cells-flipped,.stats.boards-cleared,.stats.biggest-flip), with__GAME_ID__replaced. When a key is renamed for the game (a new lose reason, hud line or counter), add the new key in all four languages instead (a game scaffolded with--lose-reason <slug>already has<game-id>.lose.<slug>in its catalogs: rename thelose.out-of-moveskey in the copiedoutcome.tsand its test to it), put fa and ckb on the native review list, and keep the catalogs sorted. Without them the contract test andcheck-rules-engine.mjs(catalog-key-missing) fail. - Write the rules test-first, in this order, following references/writing-rules.md and references/testing-rules.md: types,
create(with its pinned golden),outcomeandlistMoves,applyMove, then persistence, statistics counters, and 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/line-siege/rules/ (Line Siege v1: tray refills and spawns drawn fromrngin the state, two ways of losing, an endless row, a continue for both losses) for a game that draws during play. - Assemble the engine (
<game-id>-engine.ts) once the board skills have writtenrules/intent-to-move.tsandboard/build-timeline.ts: setpanModeandselectRegionsfrom the input chosen in step 1, then write its contract test (<game-id>-engine.test.ts) with the game's real intents (taps withselected: null, taps on the select regions, plus the swipes, drags or aims its pan mode sends) and, with an endless mode,endless: <CONST>_LEVELS.endless(examples/line-siege/rules/line-siege-engine.test.ts). The pilot (Line Siege, Shell step 3) is copied, not written: its rules come from this example, and becauseline-siege-engine.tsnamesbuildTimeline, the same step copies the three board files the timeline needs from board-rendering-skia's Line Siege example (board/build-timeline.ts,board/board-ids.tsandboard/monster-tracks.ts, with their tests); the rest ofboard/waits for the board kit at Shell step 7. - Format and lint the new files:
npx eslint --fix apps/<game-id>andnpx prettier --write apps/<game-id>/src(import order and wrapping depend on the game id), thennpx tsc --noEmit -p apps/<game-id>andnpx tsc --noEmit -p packages/game-kit. - Run the tests with coverage:
npx jest apps/<game-id>/src/rules apps/<game-id>/src/testing --ci --selectProjects unit --coverage --collectCoverageFrom='apps/<game-id>/src/rules/**/*.ts' --collectCoverageFrom='apps/<game-id>/src/testing/**/*.ts' --coverageThreshold='{}'(paths first:--selectProjectstakes every following word as a project name;--coverageThreshold='{}'because a subset run cannot meet the global numbers) and read the table: the rules stay at 95/95/95/90. Onlynpm run test:coveragejudges the thresholds. When a module is finished, run Stryker on it (break threshold 75 %). - Run the check
node ${CLAUDE_SKILL_DIR}/scripts/check-rules-engine.mjs . --game <game-id>; fix everyFAILline (each names the file, the rule and the fix) and rerun until it printsRESULT: PASS. Anengine-contractline names the seed and difficulty: add that case as an example test first, then fix the engine.
Definition of done
- [ ] The root
package.jsonpinsfast-checkexactly indevDependencies(nokit-test-dependencyline). - [ ]
packages/game-kit/src/contract/holds the thirteen contract files (withdifficulty.tsand its test),rng/sfc32.tswith its golden test,pick-at.ts, and the six testing helpers (play-choices,play-bot,json-shape,engine-contract,contract-intents,teaching-contract), all passing their tests. - [ ]
apps/<game-id>/src/rules/has<game-id>-types.ts,create.ts,list-moves.ts,apply-move.ts,outcome.ts, persistence and stats files, each with tests;apps/<game-id>/src/testing/<game-id>-testing.tshas a bot and the four example states. - [ ] Every rules test file follows the loop: examples, fast-check properties, one
GOLDEN_*value; coverage of the rules folder is at least 95/95/95/90. - [ ] Every catalog key the rules name (hud, stats, continue, each
.lose.<reason>) is in all four catalogs. - [ ] Once assembled, the engine sets
panModeandselectRegions, and<game-id>-engine.test.tsrunsengineContractProblemswith the game's intents (andendlesswhen the game has an endless mode) and returns[]. - [ ]
npx tsc --noEmit,npx eslint --max-warnings 0andnpx prettier --checkpass forpackages/game-kitandapps/<game-id>; no__GAME_placeholder is left. - [ ]
node ${CLAUDE_SKILL_DIR}/scripts/check-rules-engine.mjs . --game <game-id>printsRESULT: PASS
Anti-patterns
Math.random()"just for a quick shuffle", or a seed from the clock. Replays and daily levels break silently; threadnextInt(state.rng, n)and keep the RNG in the state.- Re-seeding inside
applyMovefrom the move count to avoid storing the RNG. Two runs that reach the same position by different paths then draw different futures; carry the stream in the state. - Mutating the state in place for speed (
state.cells[i] = 1). The undo stack and the saved snapshot share references; build new arrays withmapand spreads. - Returning the old state for an illegal move. The bug hides until a save is corrupted; throw a
RangeError. - Legality in the gesture code or in the Shell. Bots and solvers would disagree with players; only
listMovesandintentToMovedecide. - Choosing the pan mode in the Shell or in
game.config.ts. It belongs to the engine next tointentToMove, where the contract test can prove the two agree. - A
selectmove for tap-then-tap. It pollutes bots, the witness, par, undo and the counters; list the region inselectRegionsand readintent.selected. - A
modeargument, or a tuning table indexed 0..3. Difficulty is one 0..100 scale; pick tuning rows withrowForand mark the endless run with difficulty 100. - Casting
json as StateinparseState. A damaged or old save then crashes later; rebuild the typed value with explicit checks and returnnullotherwise. - 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.atan2for a direction or**for a square. Use dot products, committed direction tables andx * x.
Files in this skill
| File | What it is | Read/run when |
|---|---|---|
| references/engine-contract.md | GameModule members, engine semantics, rules members, persistence, stats, testing spec, contract tests, game classes | Workflow step 1 |
| references/determinism-and-rng.md | The determinism policy and why, sfc32, its API and golden values, randomness in rules | Step 2, and before anything random |
| references/writing-rules.md | Types, create, listMoves, outcome, applyMove, hud/undo/hints/continue, persistence, counters, bot, assembly, size limits | Steps 3, 5 and 6 |
| references/testing-rules.md | The loop, examples, property checklist, pinned goldens, the contract test, gates, commands, traps | Steps 5 and 8 |
templates/packages/game-kit/src/contract/ |
The thirteen contract files (canonical, copy verbatim): the types, input-intent.ts (shared with the board skills; tap carries selected) and difficulty.ts (ENDLESS_DIFFICULTY, MAX_LEVEL_DIFFICULTY, clampDifficulty, isEndlessDifficulty, rowFor) with its test |
Step 2 |
templates/packages/game-kit/src/rng/ |
sfc32.ts with its golden test, pick-at.ts with its test |
Step 2 |
templates/packages/game-kit/src/testing/ |
play-choices, play-bot, json-shape, engine-contract, contract-intents (pan mode, select regions, tap selections, endless never won) and teaching-contract (tutorialSaveProblems: every tutorial state reads back through parseState), each with its test |
Step 2 |
templates/packages/game-kit/src/geom/ |
board-layout.ts (+ two tests), classify-swipe.ts (+ test): types the contract imports; copy only when missing |
Step 2 |
templates/packages/game-kit/src/timeline/ |
track.ts (+ test): Track and Motion for buildTimeline; copy only when missing |
Step 2 |
templates/apps/__GAME_ID__/src/rules/ |
The template game's types, create, list-moves, apply-move, outcome, flip-cells, engine, persistence, stats, and their tests, plus its tuning (__GAME_ID__-tuning.ts and test: every balance number, rows picked with rowFor; synced from the library, the same file game-balance-and-bots ships) |
Step 3 |
templates/apps/__GAME_ID__/src/testing/ |
Greedy bot and example states, with a test | Step 3 |
examples/line-siege/rules/ |
Line Siege v1, the whole verified rules folder (types, tuning with the endless row, create and opening, placement, board lines, monster attack and march, outcome, continue, intent-to-move with tap-then-tap, engine, persistence, stats, the evaluation the bot and witness use) with example, property and golden tests | Step 5, for games that draw during play |
examples/line-siege/i18n/ |
Line Siege's four catalogs: every key its rules name (line-siege.lose.broke-through, .lose.board-full, .progress, .progress.endless, .continue.push-back, the stats labels) |
Step 4, as a model of complete game catalogs |
assets/template-catalog-keys.json |
Every catalog key the Tap Flip templates name, with its en, de, fa and ckb text | Step 4 |
scripts/check-rules-engine.mjs |
Checker: kit files and current contract members, the exact fast-check pin its tests need, RNG goldens (run for real), purity, determinism, JSON state, events, throws, reason keys, catalog keys, tests, assembly with panMode and selectRegions, a seeded run of the rules, endless never won |
Steps 2 and 9, and at the end |
scripts/lib/ |
app-modules.mjs (loads the repo's TypeScript), ts-scan.mjs, kit-checks.mjs, rules-checks.mjs, engine-run.mjs, assemble-fixtures.mjs |
When changing the checker |
scripts/selftest.mjs |
Proves the checker: the templates installed as a game must pass, 31 planted bugs must fail, and each pass-* change must still pass (a draw in a helper only create.ts imports) |
After changing the checker or a template |
scripts/check-lib.mjs |
Shared script helper, synced from the library (do not edit here) | Never by hand |
assets/shared.json |
Declares the shared files this skill copies in | When adding a shared file |
tests/fixtures/ |
check-rules-engine/bad-*/: one planted bug each (mutation.json) and the expected output (EXPECT.txt) |
When adding a rule to the checker |
Related skills
level-generation-and-solvers- generators, solvers and par, packs, stars and the daily level built oncreate.game-host-integration-ShellGameModule,src/index.tsassembly and the Game screen session.board-gestures-and-input-intentToMoveand the intents the contract test feeds in.board-rendering-skia-buildTimeline,toViewand the board that shows the events.realtime-game-loop- sims for real-time games and simulate-then-replay physics.game-balance-and-bots- bot policies,*.sim.test.tsand difficulty curves.tdd-workflow- the red-green loop and evidence for every change.new-game-scaffold- creatingapps/<game-id>before the rules.
04 同仓库更多 Skills
unit-and-component-tests
Sets up Jest and writes Pocket Arcade test code - three projects, RNTL 14 async via renderWithShell, root SDK mocks, fakes, fast-check, coverage, Stryker. Use when a test needs the Shell wrapper, a mock or a fake, or Jest fails. Not for the red-green loop (tdd-workflow) or goldens (golden-tests).
typescript-and-lint-rules
Enforces Pocket Arcade's strict TypeScript 6 tsconfigs, ESLint 9 flat config, Prettier and size limits. Use when writing or splitting .ts/.tsx or fixing a tsc or lint error. Not for gate wiring (quality-gates), names (naming-conventions) or import zones (architecture-and-boundaries).
demo-skill
Builds a demo. Use when testing the pitfall checker.
demo-skill
Builds a demo. Use when testing the pitfall checker.
troubleshooting-playbook
Diagnoses and fixes Pocket Arcade failures with a catalogue of 300+ known ones (symptom, cause, fix). Use when something errors, crashes, hangs or renders wrong, or an error or log needs explaining. Not for gate setup (quality-gates) or running builds (ios-simulator-build, ios-release-testflight).
toybox-visual-parity
Proves a built Pocket Arcade screen matches its Toybox design screenshot (light/dark, en/fa) and drives the fixes: capture, element gates, sheets, sign-off. Use when any screen is built or changed, or for visual parity, design match, screenshot compare. Not for building screens (toybox-screens).