new-game-scaffold
Starts a new game by script - contracts/games.json entry, catalog keys, a white-label app when multi-package - and proves it complete. Use when adding or starting a new game or checking one is complete. Not for rules (game-rules-engine).
- License 许可
- MIT
- 最近更新
- 2026-10-22
- Stars
- ★ 13
- Forks
- 2
01 前言 Front Matter
- name
- new-game-scaffold
- description
- Starts a new game by script - contracts/games.json entry, catalog keys, a white-label app when multi-package - and proves it complete. Use when adding or starting a new game or checking one is complete. Not for rules (game-rules-engine).
02 资源文件 78
- 资产文件assets/shared.json249 B
- 参考文档examples/developer-request.md2.5 KB
- 参考文档examples/lights-out/games.json637 B
- 参考文档examples/lights-out/scaffold-plan.txt1.5 KB
- 脚本examples/white-label/app-settings.ts1.3 KB
- 参考文档examples/white-label/games.json840 B
- 参考文档references/checker.md12.2 KB
- 参考文档references/ids-and-names.md5.3 KB
- 参考文档references/new-game-checklist.md10.8 KB
- 参考文档references/white-label-apps.md10.4 KB
- 脚本scripts/check-game-scaffold.mjs10.2 KB
- 脚本scripts/check-lib.mjs117.1 KB
- 脚本scripts/lib/app-checks.mjs16.5 KB
- 脚本scripts/lib/app-modules.mjs8.7 KB
- 脚本scripts/lib/app-skeleton.mjs9.0 KB
- 脚本scripts/lib/game-catalogs.mjs4.0 KB
- 脚本scripts/lib/game-checks.mjs30.9 KB
- 脚本scripts/lib/games-contract.mjs13.2 KB
- 脚本scripts/lib/json-text.mjs1.8 KB
- 脚本scripts/lib/scaffold-plan.mjs8.2 KB
- 脚本scripts/lib/ship-placeholders.mjs8.0 KB
- 脚本scripts/scaffold-game.mjs16.6 KB
- 脚本scripts/selftest.mjs7.9 KB
- 参考文档templates/contracts/games.json307 B
- 参考文档templates/contracts/games.schema.json6.0 KB
- 脚本templates/scripts/games/find-generator.test.ts1022 B
- 脚本templates/scripts/games/find-generator.ts1.0 KB
- 脚本templates/scripts/games/new-game.ts1.2 KB
- 参考文档tests/bases/app/package.json163 B
- 参考文档tests/bases/app/src/i18n/catalogs/ar.json66 B
- 参考文档tests/bases/app/src/i18n/catalogs/en.json55 B
- 参考文档tests/bases/app/tsconfig.json77 B
- 参考文档tests/bases/complete-game/.maestro/games/lights-out.yaml158 B
- 参考文档tests/bases/complete-game/contracts/levels.json368 B
- 其他tests/bases/complete-game/src/app/_layout.tsx207 B
- 脚本tests/bases/complete-game/src/games/game-registry.ts767 B
- 脚本tests/bases/complete-game/src/games/lights-out/canvas/intent-to-move.ts219 B
- 其他tests/bases/complete-game/src/games/lights-out/canvas/lights-out-board.tsx284 B
- 脚本tests/bases/complete-game/src/games/lights-out/canvas/lights-out-surface.ts227 B
- 脚本tests/bases/complete-game/src/games/lights-out/levels/lights-out-levels.ts544 B
- 脚本tests/bases/complete-game/src/games/lights-out/lights-out-game.test.ts237 B
- 脚本tests/bases/complete-game/src/games/lights-out/lights-out-game.ts1004 B
- 脚本tests/bases/complete-game/src/games/lights-out/lights-out-hosted.ts450 B
- 脚本tests/bases/complete-game/src/games/lights-out/rules/apply-move.ts505 B
- 脚本tests/bases/complete-game/src/games/lights-out/rules/create.ts432 B
- 脚本tests/bases/complete-game/src/games/lights-out/rules/lights-out-engine.ts714 B
- 脚本tests/bases/complete-game/src/games/lights-out/rules/lights-out-persistence.ts229 B
- 脚本tests/bases/complete-game/src/games/lights-out/rules/lights-out-stats.ts214 B
- 脚本tests/bases/complete-game/src/games/lights-out/rules/lights-out-tuning.ts229 B
- 脚本tests/bases/complete-game/src/games/lights-out/rules/lights-out-types.ts425 B
- 脚本tests/bases/complete-game/src/games/lights-out/rules/list-moves.ts423 B
- 脚本tests/bases/complete-game/src/games/lights-out/rules/outcome.ts480 B
- 脚本tests/bases/complete-game/src/games/lights-out/testing/lights-out-testing.ts220 B
- 脚本tests/bases/complete-game/test/goldens/canvas/lights-out.golden.test.ts214 B
- 脚本tests/bases/complete-game/test/sims/lights-out/balance.sim.test.ts237 B
- 参考文档tests/bases/monorepo/apps/sliding-puzzle/package.json201 B
- 参考文档tests/bases/monorepo/contracts/games.json539 B
- 参考文档tests/bases/monorepo/package.json175 B
- 参考文档tests/bases/monorepo/packages/brand/fonts/BrandSans-OFL.txt80 B
- 资产文件tests/bases/monorepo/packages/brand/fonts/BrandSans-Regular.ttf80 B
- 参考文档tests/bases/monorepo/tsconfig.base.json50 B
- 参考文档tests/fixtures/check-example-lights-out/CASES.json320 B
- 参考文档tests/fixtures/check-example-lights-out/good/EXPECT.txt49 B
- 参考文档tests/fixtures/check-example-white-label/CASES.json476 B
- 参考文档tests/fixtures/check-example-white-label/good/EXPECT.txt49 B
- 参考文档tests/fixtures/check-game-app-complete/CASES.json6.4 KB
- 参考文档tests/fixtures/check-game-app-complete/good/EXPECT.txt49 B
- 参考文档tests/fixtures/check-game-app-complete/good/mutation.json1.2 KB
- 参考文档tests/fixtures/check-game-app/CASES.json7.8 KB
- 参考文档tests/fixtures/check-game-app/good/EXPECT.txt49 B
- 参考文档tests/fixtures/check-game-complete/CASES.json16.4 KB
- 参考文档tests/fixtures/check-game-complete/good/EXPECT.txt49 B
- 参考文档tests/fixtures/check-game-scaffold/CASES.json9.7 KB
- 参考文档tests/fixtures/check-game-scaffold/good/EXPECT.txt49 B
- 参考文档tests/fixtures/scaffold-game-app/CASES.json2.8 KB
- 参考文档tests/fixtures/scaffold-game-app/good/EXPECT.txt377 B
- 参考文档tests/fixtures/scaffold-game/CASES.json4.1 KB
- 参考文档tests/fixtures/scaffold-game/good/EXPECT.txt654 B
03 SKILL.md 正文
New game scaffold
Turns "the next game is chosen" into a declared, named, translated starting point written by a script,
then walks the game through the build order of the games skills and proves, with a second script, that
the finished game has every part, agrees with its declaration and (when it is its own white-label app)
carries no placeholder a store would see. The game lives in src/games/<game-id>/ of the one Expo
app; when multi-package, one game can also be one app in apps/<game-id>/.
Rules that must hold
- Start every game with
scaffold-game.mjs, never by copying another game's folder. Why: a copied game keeps the other game's ids, catalog keys, saved-run namespace and settings in corners; the script fills every id form from one id and never overwrites a file. - The game id is kebab-case, starts with a letter, and never changes after release; every
identifier derives from it by one rule (folder,
identity.id, catalog namespace<id>., saved runs,<Pascal>types,<CONST>_constants). Why: the id is inside every saved run on every device, and a leading digit is not a valid Android package part. - The game's design notes are data in
contracts/games.json, and the code must agree with them: class, pan mode, levels and pack layout, daily, endless, hints, continue, every way of losing. Hints and continue have no default; a daily-only or endless-only game declareslevels: null(itscontracts/levels.jsonentry haspackCount0). Why: a declaration that promises a hint or a continue the rules lack ships a dead button; the complete check loads the module and compares it with the entry, and holdscontracts/levels.json(level-generation-and-solvers) to the same pack layout. - Every catalog of the app carries the game's keys:
<id>.name, one<id>.lose.<reason>per declared way of losing and every<id>.*key the game's code names, the same keys in every locale, no empty text; approved copy (contracts/copy-source.json) wins and retired keys are gone. Why: a missing key is a broken screen in one language, found by a player. - Never overwrite.
--writewrites nothing when any value conflicts; a game or app that exists is completed with--add-missing, which adds absent files, keys and entries and never changes a value. Why: an existing game holds decisions nobody wants silently reset. - No template placeholder is left (
__GAME_ID__,__GAME_PASCAL__,__GAME_CAMEL__,__GAME_CONST__, any__UPPER_SNAKE__) in the game folder or its app, nor in the game's sims, board golden and E2E flows; generated native folders, build output and Pods are never scanned. Why: a placeholder compiles in a string and ships. - Build the parts in the documented order, each with its own skill, and finish with
check-game-scaffold.mjs . --game <id> --stage complete. It never skips: every part, the evidence (sims, a pixel golden, an E2E flow), the hosted binding<id>-hosted.tsregistered ascreateGameHost(<CONST>_HOSTED, ...)in<gamesDir>/game-registry.ts, the declared ways of losing and, for a white-label app, its real root and entry (polyfills, thenexpo-router/entry) instead of the placeholder entry. Why: nobody reads every file of a game; the gate proves nothing is missing and names the skill for each missing part. - The game module loads headless (pure TypeScript through
<id>-game.ts). Why: bots, solvers, goldens and this check run it in Node; a React Native import in its graph breaks all of them. npm run new-gameand the skill write identical bytes (scripts/games/new-game.tsforwards to the installed generator); a declarednew-gamescript runs a file that exists. Why: two generators drift.- When multi-package, every white-label app lists the same dependency set at the same versions.
Why: native modules autolink per app and
expo install --checksees only the app's own list; a drift crashes at launch or compiles two copies of one native module. - When multi-package, an app's config is one composer statement, its per-app values live in
app-settings.ts(read only byapp.config.ts, nevernull), its native folders are ignored anchored, its Metro cache is keyed onEXPO_PUBLIC_*, and its fonts are byte-for-byte copies. Why: native settings come only from the composer and plugins;nullreached the device as{}; an unkeyed cache shipped development transforms in a production export (verified on SDK 57). - When multi-package, store ids derive from one prefix and account-bound values stay documented
placeholders until a human supplies them; the complete stage fails
ship-placeholderon each by name, and no option turns one into a pass. Why: a placeholder bundle id, privacy link or sample ad id in a store build is a rejected review or ads nobody is paid for.
Workflow
- Design notes first. Read references/new-game-checklist.md ("Before code"). Agree with the developer: the id (references/ids-and-names.md), the name, class, pan mode, levels and packs, daily, endless, hints, continue, the ways of losing. Ask for hints and continue; never assume them.
- Plan the start:
node ${CLAUDE_SKILL_DIR}/scripts/scaffold-game.mjs . --game <id> --name "<Name>" --hints none|solver --continue none|once [--levels 3x30] [--daily] [--endless] [--pan-mode swipe] [--class realtime] [--lose-reason <slug>]...Read the plan (compare examples/lights-out/scaffold-plan.txt). Aconflictmeans the game exists: use--add-missing. When multi-package and the game is its own app, add--appafter reading references/white-label-apps.md; adeps-lockstepfailure is fixed first with dependency-management. - Write it: the same command with
--write(white-label: thennpm install). Once per repo, copytemplates/scripts/games/and add"new-game": "node scripts/games/new-game.ts"topackage.json. - Check the start:
node ${CLAUDE_SKILL_DIR}/scripts/check-game-scaffold.mjs . --game <id>untilRESULT: PASS; for a white-label app alsonpx expo config --jsoninapps/<id>per variant,npx tsc --noEmit -p apps/<id>andnpx eslint --max-warnings 0 apps/<id>. Commit on its own. - Build the game in order (the table in the checklist): kit and rules (game-rules-engine, using the placeholder table the scaffold printed), real-time sim (realtime-game-loop), bot sims (game-balance-and-bots), levels (level-generation-and-solvers), canvas surface and golden (skia-canvas-rendering), intent function (canvas-gestures-and-hit-testing), the module, texts (i18n-strings-and-catalogs), the hosted binding and its registry factory (game-session-host), how-to-play, sounds and haptics (optional), for a white-label app its icon and splash (icons-app-icon-and-splash) and root (app-startup-and-bootstrap), the E2E flow on a named iOS simulator and a named Android emulator (e2e-maestro), screen parity (design-visual-parity). Each step test-first with its own check.
- Prove it complete:
node ${CLAUDE_SKILL_DIR}/scripts/check-game-scaffold.mjs . --game <id> --stage complete; fix every line (references/checker.md) and rerun untilRESULT: PASS, thennpm run verify. A white-label app before the human steps ends with exactly itsship-placeholderlines: that is the finished state before those steps, never a pass. - Report and hand over: what a player can now do, the open human steps with the placeholder each replaces (one message shaped like examples/developer-request.md), the non-blocking ones (play-test, native review), what could not be verified without a device. Uploads and store-console changes are outward-facing: stop and ask first.
Definition of done
- [ ] The game was started by
scaffold-game.mjswith its real hints and continue, and its entry incontracts/games.jsonsays what the rules do. - [ ]
check-game-scaffold.mjs . --game <id>passed before any game code was written. - [ ] Every part exists and was built test-first by its skill;
npm run verifyis green. - [ ] White-label: the app type-checks, lints and
npx expo config --jsonworks for every variant; the open placeholders are listed in the report as human steps. - [ ]
node ${CLAUDE_SKILL_DIR}/scripts/check-game-scaffold.mjs . --game <id> --stage completeprintsRESULT: PASS(white-label before the human steps: onlyship-placeholderlines, reported as open steps).
The scaffold stage may print SKIP src/i18n/catalogs [catalog-missing-key] not yet created (i18n-strings-and-catalogs creates it) in an app without catalogs; an app with no game prints
NOT APPLICABLE: the app has no game (...). The complete stage never skips.
Anti-patterns
cp -R src/games/<other> src/games/<new>and search-and-replace. Old ids, keys and tuning survive; scaffold, then copy the rules template with the printed placeholder table.- Declaring
hints: solverorcontinue: once"for later". The complete check fails the mismatch; declare what the rules do today and change both together. - Renaming a game id after release. Every saved run and statistic is keyed on it; keep the id and change only the display name.
- Moving files aside so
--writeworks. Use--add-missing; it lists what it keeps. - A lose reason only in code (
'<id>.lose.board-full'with no declaration and no catalog text). Declare it, then add its text to every catalog. - Importing a screen, a store or
react-nativeinto<id>-game.ts. The module stops loading headless; the session host attaches the surface. - Treating the scaffold stage as done. It proves the start only; the game is done at
--stage complete. - White-label: installing a package in one app only, editing
ios/orandroid/, importingapp-settings.tsfrom app code, or writingnullinto it. Install in every app; change the composer or a plugin; readexpo.extrathrough the typed reader; leave the key out. - White-label: inventing a real-looking ad id or privacy link "for now", or calling the
ship-placeholderlines a pass. Keep the documented placeholders; report them as open steps.
Files in this skill
| File | What it is | Read/run when |
|---|---|---|
| references/new-game-checklist.md | Design notes, step 0, the build order with skills and proofs, proving completion, human steps, release | Workflow steps 1, 5 and 6 |
| references/ids-and-names.md | The id and its four forms, identifiers inside and outside the game, store ids | Step 1 |
| references/white-label-apps.md | When multi-package: the apps block, every skeleton file and why, lockstep, store ids and placeholders | Step 2 with --app, or when an app rule fails |
| references/checker.md | Both scripts: options, config keys, every rule with its fix, SKIP and NOT APPLICABLE, troubleshooting | Steps 4 and 6 |
templates/contracts/games.json |
The declaration file with no game yet; the generator starts a new one from it | Step 3 (the generator writes it) |
templates/contracts/games.schema.json |
The declaration's JSON schema, every field explained | When editing an entry by hand |
templates/scripts/games/ |
new-game.ts (the npm script), find-generator.ts and its test |
Step 3, once per repo |
| examples/lights-out/scaffold-plan.txt | A real dry run for Lights Out (levels, a daily, one way of losing) | Step 2 |
| examples/lights-out/games.json | The declaration that run writes | Step 2 |
| examples/white-label/games.json | A white-label declaration: the apps block and a real-time game with an endless run | Step 2 with --app |
| examples/white-label/app-settings.ts | The settings file the generator writes for that app, placeholders included | Step 2 with --app |
| examples/developer-request.md | The one message asking for the human-only steps, each with its default | Steps 1 and 7 |
scripts/scaffold-game.mjs |
Generator: plan (default), --write, --add-missing, --app; never changes an existing value |
Steps 2 and 3 |
scripts/check-game-scaffold.mjs |
Checker: --stage scaffold (default) and --stage complete |
Steps 4 and 6, and at the end |
scripts/lib/ |
games-contract.mjs (id, layout, declaration), game-catalogs.mjs, json-text.mjs, scaffold-plan.mjs, app-skeleton.mjs (the white-label renderer), game-checks.mjs, app-checks.mjs; app-modules.mjs and ship-placeholders.mjs are synced (do not edit here) |
When changing a script |
scripts/selftest.mjs |
Proves both scripts on the fixtures, building each base with the generator itself | After changing a script or a template |
scripts/check-lib.mjs |
Shared script library, synced (do not edit here) | Never by hand |
assets/shared.json |
Declares the synced files | When adding a shared file |
tests/bases/ |
app/ (a small app), monorepo/ (white-label: an existing app, shared fonts, the apps block), complete-game/ (loadable stand-ins of every part of a finished game) |
When a base changes |
tests/fixtures/ |
scaffold-game/, scaffold-game-app/, check-game-scaffold/, check-game-complete/, check-game-app/, check-game-app-complete/: good, pass-, bad- (one per rule) and error-* cases; check-example-lights-out/ and check-example-white-label/ hold the examples to the checker |
When adding a rule or changing an example |
Related skills
game-rules-engine- the kit, the rules, the bot and the module the scaffold's id names.level-generation-and-solvers- solvers, packs and the daily level the declaration announces.game-balance-and-bots- the bot simulations the complete stage requires.realtime-game-loop- thesim/and the<id>-realtime.tsspec of a real-time game.skia-canvas-renderingandcanvas-gestures-and-hit-testing- the surface, its golden and the intent function.game-session-host- the hosted binding<id>-hosted.tsand its factory ingame-registry.ts.i18n-strings-and-catalogs- writing and translating the game's texts; the approved copy.e2e-maestro- the game's flow on iOS and Android.dependency-management- lockstep installs across white-label apps.app-variants-and-environment- the single app's identity, variants and Metro cache key.app-startup-and-bootstrap- a white-label app's root layout, which replaces the placeholder entry.icons-app-icon-and-splash,audio-and-haptics-feedback,design-visual-parity- per-app icon and splash, game feedback, screen parity.privacy-and-store-declarations- audits, the privacy answers, age rating and app-ads.txt.ios-release-testflight,android-release-play,eas-build-and-submit- shipping once the human steps are done.
04 同仓库更多 Skills
demo
Planted skill folder (never scanned).
demo
Planted installed skill (its files must never be scanned).
web-support
Ships the web build of an Expo app: platform files, APIs missing in react-native-web, expo-sqlite headers. Use when adding web, a .web.tsx file or expo export --platform web. Not for responsive layout (adaptive-layout).
value-objects-money-and-units
Stores money as ISO 4217 minor units, quantities in canonical units, instants as epoch ms. Use when adding a price, currency, tax, split, unit or timestamp, or a total is a cent off. Not for calendar days (dates-streaks-and-statistics).
unit-and-component-tests
Sets up Jest, checks unit, component and route tests (RNTL 14, renderWithProviders, SDK mocks, fakes, fast-check, Stryker). Use when writing a test or mock, or Jest fails or flakes. Not for goldens (golden-and-snapshot-tests).
ui-states-and-feedback
Builds loading, empty, failed and offline states, delayed skeletons, toasts, banners, confirms, Undo. Use when a screen loads data, shows a spinner, toast, retry or delete prompt. Not for failure values (error-handling-typed-results).