create-threenative 0.2.14 → 0.2.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (251) hide show
  1. package/agent-docs/kit-mcp.md +10 -0
  2. package/agent-docs/kit-router.md +14 -0
  3. package/agent-docs/kit-stuck.md +7 -0
  4. package/agent-docs/references/capability-reference.md +958 -30
  5. package/agent-docs/references/conventions.md +271 -0
  6. package/agent-docs/references/kit-action-rpg.md +40 -0
  7. package/agent-docs/references/kit-adventure.md +40 -0
  8. package/agent-docs/references/kit-collectathon.md +38 -0
  9. package/agent-docs/references/kit-kart.md +31 -0
  10. package/agent-docs/references/kit-minimal.md +29 -0
  11. package/agent-docs/references/kit-platformer.md +34 -0
  12. package/agent-docs/references/kit-puzzle.md +22 -0
  13. package/agent-docs/references/kit-racing.md +26 -0
  14. package/agent-docs/references/kit-rain.md +31 -0
  15. package/agent-docs/references/kit-rts.md +34 -0
  16. package/agent-docs/references/kit-runner.md +32 -0
  17. package/agent-docs/references/kit-sailing.md +41 -0
  18. package/agent-docs/references/kit-shooter.md +33 -0
  19. package/agent-docs/references/kit-snow.md +33 -0
  20. package/agent-docs/references/kit-starter.md +55 -0
  21. package/agent-docs/references/kit-tower-defense.md +27 -0
  22. package/agent-docs/references/terrain-authoring.md +2 -1
  23. package/agent-files/.agents/skills/ponytail/SKILL.md +1 -1
  24. package/agent-files/.agents/skills/prd-creator/SKILL.md +3 -2
  25. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +81 -59
  26. package/agent-files/.claude/hooks/discovery-gate.mjs +125 -0
  27. package/agent-files/.claude/hooks/ponytail-context.mjs +1 -1
  28. package/agent-files/.claude/settings.json +25 -0
  29. package/agent-files/.codex/hooks.json +18 -1
  30. package/dist/index.js +256 -120
  31. package/dist/terrain-kit.d.ts +7 -0
  32. package/dist/terrain-kit.js +82 -0
  33. package/dist/threenative.js +23 -4
  34. package/dist/web-engine-gltf-loader.js +20 -7
  35. package/dist/web-engine-post-effects.js +34 -4
  36. package/dist/web-engine-runtime.js +6119 -3311
  37. package/package.json +13 -8
  38. package/template-assets/patches/three@0.187.0.patch +2004 -407
  39. package/templates/action-rpg/AGENTS.md +99 -84
  40. package/templates/action-rpg/CLAUDE.md +99 -84
  41. package/templates/action-rpg/kit.json +1 -0
  42. package/templates/action-rpg/package.json +7 -7
  43. package/templates/action-rpg/playtests/spells.playtest.json +20 -0
  44. package/templates/action-rpg/src/game.ts +1 -0
  45. package/templates/action-rpg/src/render/atmosphere.ts +5 -16
  46. package/templates/action-rpg/src/render/gpuSky.ts +4 -7
  47. package/templates/action-rpg/src/render/quality.ts +3 -1
  48. package/templates/action-rpg/src/scenes/Play.ts +26 -0
  49. package/templates/action-rpg/src/ui/AbilityBar.tsx +1 -1
  50. package/templates/action-rpg/threenative.config.ts +0 -3
  51. package/templates/adventure/AGENTS.md +87 -44
  52. package/templates/adventure/CLAUDE.md +87 -44
  53. package/templates/adventure/package.json +7 -7
  54. package/templates/collectathon/AGENTS.md +88 -42
  55. package/templates/collectathon/CLAUDE.md +88 -42
  56. package/templates/collectathon/package.json +7 -7
  57. package/templates/kart/AGENTS.md +82 -42
  58. package/templates/kart/CLAUDE.md +82 -42
  59. package/templates/kart/package.json +6 -6
  60. package/templates/minimal/AGENTS.md +100 -84
  61. package/templates/minimal/CLAUDE.md +100 -84
  62. package/templates/minimal/package.json +6 -6
  63. package/templates/minimal/src/render/atmosphere.ts +5 -16
  64. package/templates/minimal/src/render/gpuSky.ts +4 -7
  65. package/templates/platformer/AGENTS.md +90 -46
  66. package/templates/platformer/CLAUDE.md +90 -46
  67. package/templates/platformer/package.json +7 -7
  68. package/templates/puzzle/AGENTS.md +92 -80
  69. package/templates/puzzle/CLAUDE.md +92 -80
  70. package/templates/puzzle/package.json +7 -7
  71. package/templates/racing/AGENTS.md +95 -82
  72. package/templates/racing/CLAUDE.md +95 -82
  73. package/templates/racing/package.json +7 -7
  74. package/templates/racing/src/render/atmosphere.ts +5 -16
  75. package/templates/racing/src/render/gpuSky.ts +4 -7
  76. package/templates/rain/AGENTS.md +92 -84
  77. package/templates/rain/CLAUDE.md +92 -84
  78. package/templates/rain/native-playtests/lightning.playtest.json +85 -10
  79. package/templates/rain/package.json +6 -6
  80. package/templates/rain/playtests/reduced-motion.playtest.json +6 -0
  81. package/templates/rain/src/scenes/Boot.ts +1 -0
  82. package/templates/rain/src/state.ts +7 -0
  83. package/templates/rain/src/ui/GameUi.tsx +7 -1
  84. package/templates/rts/AGENTS.md +96 -85
  85. package/templates/rts/CLAUDE.md +96 -85
  86. package/templates/rts/package.json +6 -6
  87. package/templates/runner/AGENTS.md +92 -80
  88. package/templates/runner/CLAUDE.md +92 -80
  89. package/templates/runner/package.json +7 -7
  90. package/templates/runner/playtests/performance.playtest.json +1 -1
  91. package/templates/runner/src/render/atmosphere.ts +5 -16
  92. package/templates/runner/src/render/gpuSky.ts +4 -7
  93. package/templates/runner/src/render/lighting.ts +53 -11
  94. package/templates/runner/src/scenes/Run.ts +4 -3
  95. package/templates/runner/threenative.config.ts +0 -3
  96. package/templates/sailing/AGENTS.md +91 -79
  97. package/templates/sailing/CLAUDE.md +91 -79
  98. package/templates/sailing/package.json +7 -7
  99. package/templates/sailing/playtests/sails.playtest.json +1 -0
  100. package/templates/sailing/src/render/sky.ts +4 -0
  101. package/templates/sailing/threenative.config.ts +0 -3
  102. package/templates/shooter/AGENTS.md +93 -68
  103. package/templates/shooter/CLAUDE.md +93 -68
  104. package/templates/shooter/package.json +7 -7
  105. package/templates/shooter/src/render/atmosphere.ts +5 -16
  106. package/templates/shooter/src/render/gpuSky.ts +4 -7
  107. package/templates/shooter/src/render/quality.ts +3 -1
  108. package/templates/snow/AGENTS.md +90 -76
  109. package/templates/snow/CLAUDE.md +90 -76
  110. package/templates/snow/package.json +7 -7
  111. package/templates/snow/threenative.config.ts +0 -3
  112. package/templates/starter/AGENTS.md +104 -88
  113. package/templates/starter/CLAUDE.md +104 -88
  114. package/templates/starter/native-playtests/render-chain.playtest.json +24 -24
  115. package/templates/starter/native-playtests/smooth-motion.playtest.json +3 -3
  116. package/templates/starter/package.json +7 -7
  117. package/templates/starter/src/entities/Player.ts +10 -22
  118. package/templates/starter/src/render/atmosphere.ts +5 -16
  119. package/templates/starter/src/render/gpuSky.ts +4 -7
  120. package/templates/starter/src/render/lighting.ts +54 -4
  121. package/templates/starter/src/render/temporalAA.ts +8 -7
  122. package/templates/starter/src/render/temporalAAFrame.ts +30 -9
  123. package/templates/starter/src/render/temporalAAResolve.ts +15 -1
  124. package/templates/starter/src/render/temporalClampRelease.ts +183 -0
  125. package/templates/starter/src/render/temporalHistoryResolve.ts +90 -0
  126. package/templates/starter/src/render/temporalMoire.ts +190 -0
  127. package/templates/starter/src/render/temporalResolve.ts +75 -16
  128. package/templates/starter/src/render/temporalResolveDepth.ts +2 -0
  129. package/templates/starter/src/scenes/Play.ts +41 -29
  130. package/templates/tower-defense/AGENTS.md +92 -81
  131. package/templates/tower-defense/CLAUDE.md +92 -81
  132. package/templates/tower-defense/package.json +7 -7
  133. package/capabilities.json +0 -9197
  134. package/templates/AGENTS.md +0 -21
  135. package/templates/CLAUDE.md +0 -23
  136. package/templates/action-rpg/.codex/config.toml +0 -23
  137. package/templates/action-rpg/.cursor/mcp.json +0 -38
  138. package/templates/action-rpg/.gemini/settings.json +0 -38
  139. package/templates/action-rpg/.mcp.json +0 -38
  140. package/templates/action-rpg/.vscode/mcp.json +0 -43
  141. package/templates/action-rpg/.zed/settings.json +0 -43
  142. package/templates/action-rpg/opencode.json +0 -49
  143. package/templates/adventure/.codex/config.toml +0 -23
  144. package/templates/adventure/.cursor/mcp.json +0 -38
  145. package/templates/adventure/.gemini/settings.json +0 -38
  146. package/templates/adventure/.mcp.json +0 -38
  147. package/templates/adventure/.vscode/mcp.json +0 -43
  148. package/templates/adventure/.zed/settings.json +0 -43
  149. package/templates/adventure/opencode.json +0 -49
  150. package/templates/collectathon/.codex/config.toml +0 -23
  151. package/templates/collectathon/.cursor/mcp.json +0 -38
  152. package/templates/collectathon/.gemini/settings.json +0 -38
  153. package/templates/collectathon/.mcp.json +0 -38
  154. package/templates/collectathon/.vscode/mcp.json +0 -43
  155. package/templates/collectathon/.zed/settings.json +0 -43
  156. package/templates/collectathon/opencode.json +0 -49
  157. package/templates/kart/.codex/config.toml +0 -23
  158. package/templates/kart/.cursor/mcp.json +0 -38
  159. package/templates/kart/.gemini/settings.json +0 -38
  160. package/templates/kart/.mcp.json +0 -38
  161. package/templates/kart/.vscode/mcp.json +0 -43
  162. package/templates/kart/.zed/settings.json +0 -43
  163. package/templates/kart/opencode.json +0 -49
  164. package/templates/minimal/.codex/config.toml +0 -23
  165. package/templates/minimal/.cursor/mcp.json +0 -38
  166. package/templates/minimal/.gemini/settings.json +0 -38
  167. package/templates/minimal/.mcp.json +0 -38
  168. package/templates/minimal/.vscode/mcp.json +0 -43
  169. package/templates/minimal/.zed/settings.json +0 -43
  170. package/templates/minimal/opencode.json +0 -49
  171. package/templates/platformer/.codex/config.toml +0 -23
  172. package/templates/platformer/.cursor/mcp.json +0 -38
  173. package/templates/platformer/.gemini/settings.json +0 -38
  174. package/templates/platformer/.mcp.json +0 -38
  175. package/templates/platformer/.vscode/mcp.json +0 -43
  176. package/templates/platformer/.zed/settings.json +0 -43
  177. package/templates/platformer/opencode.json +0 -49
  178. package/templates/puzzle/.codex/config.toml +0 -23
  179. package/templates/puzzle/.cursor/mcp.json +0 -38
  180. package/templates/puzzle/.gemini/settings.json +0 -38
  181. package/templates/puzzle/.mcp.json +0 -38
  182. package/templates/puzzle/.vscode/mcp.json +0 -43
  183. package/templates/puzzle/.zed/settings.json +0 -43
  184. package/templates/puzzle/opencode.json +0 -49
  185. package/templates/racing/.codex/config.toml +0 -23
  186. package/templates/racing/.cursor/mcp.json +0 -38
  187. package/templates/racing/.gemini/settings.json +0 -38
  188. package/templates/racing/.mcp.json +0 -38
  189. package/templates/racing/.vscode/mcp.json +0 -43
  190. package/templates/racing/.zed/settings.json +0 -43
  191. package/templates/racing/opencode.json +0 -49
  192. package/templates/rain/.codex/config.toml +0 -23
  193. package/templates/rain/.cursor/mcp.json +0 -38
  194. package/templates/rain/.gemini/settings.json +0 -38
  195. package/templates/rain/.mcp.json +0 -38
  196. package/templates/rain/.vscode/mcp.json +0 -43
  197. package/templates/rain/.zed/settings.json +0 -43
  198. package/templates/rain/opencode.json +0 -49
  199. package/templates/rts/.codex/config.toml +0 -23
  200. package/templates/rts/.cursor/mcp.json +0 -38
  201. package/templates/rts/.gemini/settings.json +0 -38
  202. package/templates/rts/.mcp.json +0 -38
  203. package/templates/rts/.vscode/mcp.json +0 -43
  204. package/templates/rts/.zed/settings.json +0 -43
  205. package/templates/rts/opencode.json +0 -49
  206. package/templates/runner/.codex/config.toml +0 -23
  207. package/templates/runner/.cursor/mcp.json +0 -38
  208. package/templates/runner/.gemini/settings.json +0 -38
  209. package/templates/runner/.mcp.json +0 -38
  210. package/templates/runner/.vscode/mcp.json +0 -43
  211. package/templates/runner/.zed/settings.json +0 -43
  212. package/templates/runner/README.md +0 -43
  213. package/templates/runner/opencode.json +0 -49
  214. package/templates/sailing/.codex/config.toml +0 -23
  215. package/templates/sailing/.cursor/mcp.json +0 -38
  216. package/templates/sailing/.gemini/settings.json +0 -38
  217. package/templates/sailing/.mcp.json +0 -38
  218. package/templates/sailing/.vscode/mcp.json +0 -43
  219. package/templates/sailing/.zed/settings.json +0 -43
  220. package/templates/sailing/README.md +0 -28
  221. package/templates/sailing/opencode.json +0 -49
  222. package/templates/shooter/.codex/config.toml +0 -23
  223. package/templates/shooter/.cursor/mcp.json +0 -38
  224. package/templates/shooter/.gemini/settings.json +0 -38
  225. package/templates/shooter/.mcp.json +0 -38
  226. package/templates/shooter/.vscode/mcp.json +0 -43
  227. package/templates/shooter/.zed/settings.json +0 -43
  228. package/templates/shooter/opencode.json +0 -49
  229. package/templates/snow/.codex/config.toml +0 -23
  230. package/templates/snow/.cursor/mcp.json +0 -38
  231. package/templates/snow/.gemini/settings.json +0 -38
  232. package/templates/snow/.mcp.json +0 -38
  233. package/templates/snow/.vscode/mcp.json +0 -43
  234. package/templates/snow/.zed/settings.json +0 -43
  235. package/templates/snow/README.md +0 -26
  236. package/templates/snow/opencode.json +0 -49
  237. package/templates/starter/.codex/config.toml +0 -23
  238. package/templates/starter/.cursor/mcp.json +0 -38
  239. package/templates/starter/.gemini/settings.json +0 -38
  240. package/templates/starter/.mcp.json +0 -38
  241. package/templates/starter/.vscode/mcp.json +0 -43
  242. package/templates/starter/.zed/settings.json +0 -43
  243. package/templates/starter/opencode.json +0 -49
  244. package/templates/tower-defense/.codex/config.toml +0 -23
  245. package/templates/tower-defense/.cursor/mcp.json +0 -38
  246. package/templates/tower-defense/.gemini/settings.json +0 -38
  247. package/templates/tower-defense/.mcp.json +0 -38
  248. package/templates/tower-defense/.vscode/mcp.json +0 -43
  249. package/templates/tower-defense/.zed/settings.json +0 -43
  250. package/templates/tower-defense/README.md +0 -16
  251. package/templates/tower-defense/opencode.json +0 -49
@@ -1,95 +1,103 @@
1
- # AGENTS.md — __PROJECT_NAME__ rain
2
- Instructions for the AI agent in this game. `CLAUDE.md` mirrors this file; edit `AGENTS.md`.
1
+ <!-- shared: kit-identity -->
2
+ # AGENTS.md — __PROJECT_NAME__ (Rain, the rain kit)
3
3
 
4
- ## Ownership
5
- ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, audio lifetimes, and the state bridge. This repository owns the coastal storm: weather presets and easing, the fly camera, the shaders, lightning, sound design and the interface; `src/game.ts` is portable and React mounts from `src/main.ts`. The render camera also skips an object that projects under **0.5 px** in it; `renderer.minimumProjectedPixels` raises that threshold (`false` disables the cut, not the count) and `alwaysRender(object)` exempts an object, while camera-attached objects and shadow casters are kept. The engine also owns the per-frame world-matrix walk, and by default it does not descend into a hidden subtree — so a game that reads a hidden object's `matrixWorld` directly must use `getWorldPosition` (or call `object.updateWorldMatrix(true, false)`) first; `renderer.matrixWorld: "all"` restores three's every-node walk, and `TN_PROJECTION` reports the visited-node count either way. Physics bodies and `ctx.camera` interpolate between fixed ticks by default; `physicsInterpolation: false` disables it globally, `body.interpolate = false` disables one body, `ctx.interpolate(object)` opts in another transform, and `ctx.resetInterpolation(object)` resets game-driven teleports (`TN_PHYSICS_INTERPOLATION` reports the setting and tracked count).
4
+ A real-time coastal weather study: shape rain, cloud, wind, fog and wetness, and watch a coastline answer. Routing words: rain. `CLAUDE.md` is a copy of this file.
5
+ <!-- /shared -->
6
6
 
7
- ## Start every change
8
- 1. **Critical authoring gate:** invoke `threenative-capabilities` to choose the route. New games: steps 1-8. Existing games: steps 5-7 only, using existing context. Follow the `ponytail` ladder. References borrow mechanics only: no code, level layouts, character names or art. A session started outside this folder has no `mcp__threenative-*` tools: call them with `node node_modules/@threenative/core/mcp/call.mjs <server> <tool> '<json>'`.
9
- 2. **New game only:** run discovery in `threenative-capabilities` before `prd-creator`. Draft the core-mechanics plan from the kit, both discovery passes and binding constraints,
10
- direct the user to review it, and wait for explicit approval plus an instruction to implement it.
11
- 3. Treat returned constraints as binding. This kit needs no navmesh and imports none, so it runs
12
- on every target; adding `@threenative/physics/navigation` would make it web and desktop only.
13
- 4. If a build, import, device, or blank frame fails, run `npx threenative doctor` and
14
- `npx @threenative/playtest doctor`; missing observations are not zero.
7
+ <!-- shared: kit-router -->
8
+ ## Authoring flow
15
9
 
16
- ## When the framework blocks you, write plain Three.js
10
+ Detail for each step: `threenative-capabilities` skill. Do the steps in order. A step with no result records `none: <reason>`. A blank step blocks the next. A hook blocks the first new file under `src/` until step 3 ran for the current prompt (`TN_DISCOVERY_GATE=off` opts out; Codex needs `/hooks` trust).
11
+
12
+ 1. **Kit** (new game only): `engine_search_capabilities {situation: "<the whole request>", scope: "request"}` returns the matching starter kit first. This folder is already a kit.
13
+ 2. **Mechanics**: per mechanic, `engine_search_references {situation}`, then `engine_reference_detail` on each hit for pinned constants and feel. To see a mechanic move, `engine_watch_reference {query: "<game> <mechanic>"}` returns a contact sheet of real gameplay. Borrow mechanics only: no code, level layouts, character names or art. Cite `file:line`.
14
+ 3. **Built-ins**: per mechanic, system or symptom, `engine_search_capabilities {situation, scope: "mechanic"}`, then `engine_capability_detail {symbol, importPath}` on every hit. Constraints are binding. `verdict: "none"` means the game writes it in `src/`.
15
+ 4. **Plan** (new game, or a change to several systems): `prd-creator` with the kit, references and built-ins. With a user, wait for explicit approval, then implement. With no user (`claude -p`, a script), record the plan and assumptions, then continue.
16
+ 5. **Assets**: `asset_search_sources`, the source's search tool, then `asset_download_file`; record source and licence in `CREDITS.md`. Nothing fits: `sculpt_plan`. A rigged GLB: `animation_inspect` (`threenative-assets` skill).
17
+ 6. **Build**: gameplay in `src/`, look in `src/render/` (`threenative-context` and `threenative-ui` skills). For parallel work, give each subagent one area and its files, then integrate.
18
+ 7. **Prove**: one fail-closed playtest per mechanic, then `pnpm test` (`threenative-playtest` skill). A fresh judge compares a `--browser-recipe webgpu --headed` capture to the reference image (`threenative-visuals` skill; `node_modules/create-threenative/agent-docs/references/dream-loop.md`).
19
+ 8. **Report**: the `pnpm dev` URL, `TN_FRAME_BUDGET`, `TN_SCENE_WARNING`, `TN_RENDER_PROJECTION`, and each skipped step with its reason.
20
+
21
+ A change to an existing game repeats steps 2-3 for that change, then steps 5-8.
22
+ <!-- /shared -->
23
+
24
+ <!-- shared: kit-mcp -->
25
+ ## MCP servers
26
+
27
+ `.mcp.json` wires six servers, and a session started in this folder loads them. Their tools can show as deferred: load them with `ToolSearch` `select:` plus the exact names, for example `select:mcp__threenative-engine__engine_search_capabilities,mcp__threenative-engine__engine_capability_detail,mcp__threenative-engine__engine_search_references,mcp__threenative-engine__engine_reference_detail,mcp__threenative-engine__engine_watch_reference`. A session started outside this folder runs `node node_modules/@threenative/core/mcp/call.mjs <server> <tool> '<json>'`; `call.mjs <server>` lists that server's tools.
17
28
 
18
- When an `@threenative/*` API is broken, missing, or does not do what you need, replace only that
19
- piece with portable Three.js/plain code. Keep the loop, scenes, input, registry, and playtest
20
- bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report what blocked you**
21
- (API, expectation, result, replacement); never stall the game.
29
+ - `threenative-engine`: before any new mechanic, helper or render stage, and on a slow frame or a wrong image. `engine_search_capabilities`, `engine_capability_detail`, `engine_search_references`, `engine_reference_detail`, `engine_watch_reference`.
30
+ - `threenative-assets`: a texture, HDRI, sound or model. `asset_search_sources`, `asset_download_file`, `audio_search_assets`, `mesh_optimize`.
31
+ - `threenative-sculpt`: a bespoke mesh or character from a reference image. `sculpt_plan`, `sculpt_spec_gate`, `sculpt_compare`, `sculpt_pass_gate`.
32
+ - `threenative-animation`: a rigged GLB with a held prop, foot slide or loop seam. `animation_inspect`, `animation_attach`, `animation_verify`.
33
+ - `threenative-terrain`: a starter terrain kit. `terrain_generate`.
34
+ - `threenative-devtools`: after `npx @threenative/playtest trace` names no cause. `performance_start_trace`, `performance_analyze_insight`.
35
+ <!-- /shared -->
22
36
 
23
- ## Workflow skills
37
+ ## This kit
24
38
 
25
- - `.agents/skills/prd-creator/SKILL.md` / `.claude/skills/prd-creator/SKILL.md` — game plan and approval gate.
26
- - `.agents/skills/threenative-capabilities/SKILL.md` / `.claude/skills/threenative-capabilities/SKILL.md` — capability search and classic-game mechanics references.
27
- - `.agents/skills/threenative-playtest/SKILL.md` / `.claude/skills/threenative-playtest/SKILL.md` — diagnosis and proof.
28
- - `.agents/skills/threenative-assets/SKILL.md` / `.claude/skills/threenative-assets/SKILL.md` — assets and sculpting.
29
- - `.agents/skills/threenative-visuals/SKILL.md` / `.claude/skills/threenative-visuals/SKILL.md` — captures and look.
30
- - `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets; read it first when the game is slow or stutters: `playtest trace`, then the `threenative-devtools` MCP server.
31
- - `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
32
- - `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
33
- - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro. A game-side `patches/` fix is temporary: once it is settled, it moves into the engine in one PR. Lazy-first: `.agents/skills/ponytail/SKILL.md` / `.claude/skills/ponytail/SKILL.md` — smallest correct change, and its reuse rung is the capability search above. Engine: The owned C++ engine is the default for a new game: the Wasm engine on web and the engine player on desktop. This template runs on it: `threenative.config.ts` names no `engine`. `engine: "threejs"` switches to upstream Three.js only when the user asks for it; it is never a fix for a build error. A native build names each unbound import with `TN_NATIVE_ENGINE_UNBOUND`. Android and iOS use the legacy host.
39
+ <!-- shared: kit-files -->
40
+ Source in `src/`: `audio/`, `game.ts`, `main.ts`, `render/`, `scenes/`, `state.ts`, `ui/`.
41
+ 16 scenarios in `playtests/`; `playtests/survives.playtest.json` is the smoke proof.
42
+ Exposure policy: `src/render/exposure.ts` (`node_modules/create-threenative/agent-docs/references/auto-exposure.md`).
43
+ Kit notes: `node_modules/create-threenative/agent-docs/references/kit-rain.md`.
44
+ <!-- /shared -->
34
45
 
35
- ## Commands and map
46
+ `src/state.ts` owns weather validation, the four presets, easing (tau 0.67 s) and the `distance / 343` thunder delay; `src/scenes/Boot.ts` runs the simulation clock and auto-strikes.
47
+ This repository owns the coastal storm, fly camera, shaders, lightning, sound and interface.
48
+
49
+ <!-- shared: kit-commands -->
50
+ ## Commands
36
51
 
37
52
  ```sh
38
- pnpm dev
39
- pnpm typecheck
40
- pnpm build:web
41
- pnpm build:desktop
42
- pnpm test # runs `pnpm check` first: typecheck, ESLint, Biome format
53
+ pnpm dev # play in the browser
54
+ pnpm test # typecheck, lint, format, then every playtest
55
+ pnpm build --target desktop # also: web, android, ios
56
+ npx threenative doctor # build, import, device or blank-frame failure
43
57
  ```
58
+ <!-- /shared -->
59
+
60
+ <!-- shared: kit-conventions -->
61
+ ## Conventions
62
+
63
+ Each is on by default with a named override. Detail: `node_modules/create-threenative/agent-docs/references/conventions.md#<id>`.
64
+
65
+ - **Look** `#look`: filmic curve, metered auto exposure. Override: `tonemapMode: "aces"`; `autoExposureEnabled: false` + `exposure`. Marker: `TN_WORLD_ENVIRONMENT`.
66
+ - **Quality tier (`src/render/quality.ts`)** `#quality`: GPU class picks `high`, `medium` or `low`. Override: `setupPost(..., { tier: "low" })`. Marker: `TN_QUALITY_TIER`.
67
+ - **Resolution scale** `#resolution`: `"auto"`, 0.85 on mobile-low. Override: numeric `resolutionScale`. Marker: `TN_FRAME_BUDGET`.
68
+ - **Budget real time for the look** `#frame-budget`: frame meter and scene verdict on. Override: `frameBudget: false`. Marker: `TN_FRAME_BUDGET`, `TN_SCENE_WARNING`.
69
+ - **Anti-aliasing** `#aa`: 4x MSAA on `high`, else SMAA. Override: `temporalAA: true`.
70
+ - **World-matrix walk** `#matrix-world`: visible subtrees only. Override: `renderer.matrixWorld: "all"`. Marker: `TN_PROJECTION`.
71
+ - **Projected-pixel cull** `#projected-cull`: under 0.5 px. Override: `minimumProjectedPixels`; `alwaysRender(obj)`. Marker: `TN_RENDER_PROJECTION`.
72
+ - **Physics interpolation** `#interpolation`: on for bodies and `ctx.camera`. Override: `physicsInterpolation: false`. Marker: `TN_PHYSICS_INTERPOLATION`.
73
+ - **Loading** `#loading`: `loadAll` keeps order; `addInSlices` attaches in 8 ms slices. Override: `concurrency`, `sliceSize`, `marker: false`. Marker: `TN_LOAD_ALL`.
74
+ - **Loading curtain** `#startup`: `ctx.startup.hold(label, () => ready)`. Override: reveal on measured readiness only.
75
+ - **Asset cache** `#asset-cache`: on, with idle fill. Override: `assets: { cache: false, backgroundFill: false }`. Marker: `ctx.assets.cache`.
76
+ - **Asset cook** `#asset-cook`: compact, shared images. Override: `compact: false`; `assets.exclude`; `assets.budget`. Marker: `TN_ASSETS_CONFIG`.
77
+ - **Animation rate** `#animation-rate`: `updateRate: "auto"`. Override: `updateRate: 1`. Marker: `updateRateReport`.
78
+ - **Rigged assets** `#rigged`: `.glb` in `assets/`; `AnimationPlayer` drives clips. Override: `ctx.assets.model("hero.glb")` in `Scene.load()`.
79
+ - **Clip conformance** `#clip-conformance`: measure a clip before rewriting it. Override: `clipPoseError`; `clipTrackBindings`; `clipBoneCoverage`. Marker: `boneContact`.
80
+ - **Unlit foliage** `#unlit-foliage`: warns. Override: `material.userData.tnUnlitOk = true`. Marker: `TN_UNLIT_FOLIAGE`.
81
+ - **Material backlight** `#backlight`: none, as in stock Unreal. Override: `rimGain`; `fillGain`.
82
+ - **Pointer look** `#pointer-look`: captures the canvas on click. Override: `captureOnClick: false` + `ctx.input.captureMouse()`.
83
+ - **Static scenery** `#static`: unwritten transforms stay cheap. Override: `markStatic(root)`; `invalidateStatic(obj)`. Marker: `TN_RENDERLIST_VALIDATE`.
84
+ - **Frame spans** `#spans`: off. Override: `TN_FRAME_SPANS=1`. Marker: `TN_FRAME_SPANS`.
85
+ - **Multiplayer** `#net`: none; unsupported transport rejects. Override: `connect` from `@threenative/core/net` with four limits. Marker: `TN_NET_UNAVAILABLE`.
86
+ - **Desktop window** `#desktop-mode`: CLI, then `display.fullscreen`, then `window.maximized`. Override: `--windowed`; `--maximized`; `--fullscreen`.
87
+ - **Terrain** `#terrain`: authored in the game. Override: optional `@threenative/terrain`; `references/terrain-authoring.md`.
88
+ - **Navigation** `#navigation`: none; browser-only WASM. Override: import `@threenative/physics/navigation` on purpose.
89
+ - **Move input** `#move-axis`: `input.vector("move").y` is +up. Override: one explicit `-move.y` conversion.
90
+ - **Scene change** `#scene-change`: `ctx.goto(name)` keeps state. Override: `game.goto(name)` resets state.
91
+ - **Randomness** `#seed`: unseeded. Override: `defineGame({ seed })`.
92
+ - **Engine** `#engine`: owned C++ engine. Override: `engine: "threejs"` only when the user asks. Marker: `TN_NATIVE_ENGINE_UNBOUND`.
93
+ <!-- /shared -->
94
+
95
+ <!-- shared: kit-stuck -->
96
+ ## When the framework blocks you, write plain Three.js
97
+
98
+ When an `@threenative/*` API is broken, missing, or does not do what you need, replace only that piece with portable Three.js/plain code. Keep the loop, scenes, input, registry, and playtest bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report what blocked you** (API, expectation, result, replacement); do not stall the game.
99
+
100
+ ## Stuck
44
101
 
45
- `src/state.ts` owns weather validation, the four presets, easing (τ 0.67 s), the flash envelope and
46
- the `distance / 343` thunder delay; `src/scenes/Boot.ts` runs the simulation clock, auto-strikes
47
- (gated on cloud cover above 0.35) and publishes everything the UI reads. The coast, clouds, rain
48
- and bloom/grade are shaders generated from `tools/tempest-*.frag` by `node tools/generate-shaders.mjs`;
49
- edit the `.frag`, never a generated `*-shader.ts`. Their named colours and lights live in
50
- `src/render/palette.ts`, `sky.ts`, `lighting.ts` and `materials.ts`, the bolt in `lightning.ts`. Imported foliage (Fab/Megascans cutouts) draws with its own albedo, normal map and alpha cutoff under the scene's environment light — never tint it, fake its emission or flatten its normals to make up for missing light; `TN_UNLIT_FOLIAGE` names cutout materials drawn with no environment.
51
- The coast is one ray-marched screen quad, so it is marked with `alwaysRender`; so are the rain and
52
- the bolt, whose quads are projected by their own vertex stage. Sound is three clips baked by
53
- `tools/make-storm-audio.mjs` and played through `AudioBus` in `src/audio/storm.ts`; audio starts on a
54
- gesture, and pause, mute and tab visibility each hold it. `safe` gates every strike at one door,
55
- and `prefers-reduced-motion` turns it on at boot. Keep `playtests/survives.playtest.json` as smoke
56
- proof, and `storm`, `lightning`, `reduced-motion` and `tiers` honest when you change what they assert.
57
- To build a game on the storm, keep its rules in a plain module and wire them in `src/scenes/Boot.ts`: `strike()` is the one door every strike passes (its distance and thunder delay are in scope), the frame function runs per-step rules after the camera moves, and the round's state is a `GameState` field the UI reads; `Billboard3D` turns world markers to the camera.
58
-
59
- ## Portable authoring contracts
60
-
61
- Leave `assets` absent: the cook selects target-decodable passes, with `models.sharedImages: true` deduplicating images. `sharedImages: false` embeds duplicate copies; `models.compact` (default `{ flatten: true, join: true, instance: true }`) flattens the scene graph, merges primitives by material and batches a mesh shared by several nodes as `EXT_mesh_gpu_instancing` — all lossless, keeping any node matching `protectedPattern` (or named in `protectedNames`), an animation target, or a skin joint individually addressable; `compact: false` ships the scene graph as authored. `models: "none"` / `textures: "none"` / `audio: "none"` skip those passes and report uncooked bytes. Android/iOS currently skip compression and model dedupe. `assets.exclude` defaults to `[]`; source-relative globs (for example `["unused/**"]`) omit matching files and report saved bytes. `assets.budget` accepts `{ uncooked?: number | "none", total?: number | "none" }`, default `{ uncooked: 64_000_000, total: "none" }`: only bytes left uncooked where cooking was possible count toward `uncooked`. A number sets that ceiling; `"none"` disables both gates. Either disabled gate still reports bytes. Automatic texture cooking retains unaligned source images unchanged and reports `block-size`; those bytes still count toward the uncooked budget. An explicit compression codec override must satisfy four-pixel block alignment; `codec: "none"` opts out. Cooking never silently resizes an image to fix alignment.
62
-
63
- Relative look capture: a binding with `pointerRelative: true` captures the canvas on click by default; set `captureOnClick: false` and call `ctx.input.captureMouse()` from your own gesture to opt out. Desktop mode precedence is CLI (`--windowed`, `--maximized`, `--fullscreen`) over `display.fullscreen` over `window.maximized`; with both false, `window.width`/`height` size the normal window.
64
- Scenes use `load`, `enter`, `update`, `exit`, `render`. One world unit is one metre; the camera starts at `(1.8, 2.85, 18)` and `src/render/camera.ts` owns its clamps and speeds; manual input cancels the cinematic orbit. There is no walking actor, weapon or agent here to ground, bind or navigate.
65
- `input.vector("move").y` is +up and means forward; use one explicit `-move.y` conversion.
66
- Rigged assets: put a `.glb` in `assets/`, await `ctx.assets.model("hero.glb")` in `Scene.load()`, then drive `AnimationPlayer` beside its entity. `ctx.goto(name)` rebuilds without resetting game
67
- state; from a frame function `goto` and then `return`; `ctx.state.set({ /* copy this game's initial-state shape */ })`
68
- is a partial patch. `game.goto("<scene-name>")` also rebuilds the scene, but it resets the game's
69
- state. Seeded randomness is deterministic only when `defineGame({ seed })` is configured.
70
-
71
- WebGPU reports `TN_GPU_CLASS` once per launch. Automatic `render.resolutionScale` starts at 0.85 for `mobile-low`, otherwise 1; a numeric value pins it. `TN_FRAME_BUDGET` reports the actual scale under both policies. `src/render/quality.ts` owns `low`, `medium`, `high` (the engine chain: no built-in stage at any tier); the GPU family from `ctx.renderer.gpuClass` sets the start (`discrete` `high`, `integrated` and `mobile-high` `medium`, other phones `low`); `isMobile()` chooses `low`, otherwise `high` when the family is `unknown`; override with `setupPost(..., { tier: "low" })`. Unknown tiers throw and `TN_QUALITY_TIER` reports
72
- the source. Rain keeps 4x multisampling: `temporalAA` is off in `quality.ts`, because the study draws its own single post pass. The player's four tiers are `STUDY_TIERS` in the same file. The bridge flushes about 100 ms; a control flushes it at once.
73
-
74
- When an animation looks wrong, measure it before rewriting it. `clipPoseError` scores a
75
- retargeted clip against its source per bone in degrees — whole quaternions relative to each rig's
76
- own bind pose, so the two rigs' bind conventions cancel and a limb rolled about its own axis is
77
- caught where a bone-direction check reads zero. `clipTrackBindings` names tracks that bind nothing
78
- (the `<bone>.undefined` failure that plays the bind pose instead of the animation),
79
- `clipBoneCoverage` names bones the clip does not drive and which therefore keep the previous
80
- clip's pose, and `boneContact` reports in metres whether a named bone reaches the prop it is
81
- supposed to be touching. Two loading conventions come from `@threenative/core`, not from your own loops: `loadAll(items, load)` fetches six at a time and returns results **in the input's order** (a pool that pushes returns completion order, so a positional pick lands a different asset every load), and `addInSlices(objects, (object) => ctx.add(object))` attaches in 8 ms slices so hundreds of objects never land in one long frame; override `concurrency`/`sliceSize`, pass `while: () => alive` to stop a torn-down scene without throwing, and `marker: false` silences `TN_LOAD_ALL`/`TN_ADD_SLICES` but never the measurement. Gate the loading curtain on a measured readiness with `ctx.startup.hold(label, () => ready)`: core polls it every rendered frame, so it settles without a physics step.
82
- `updateRate: "auto"` is the default and follows measured camera policy; `updateRate: 1` is full evaluation, another positive safe integer names a frame interval, and `updateRateReport` shows the effective rate, override status and latest evaluation; one-shots/fades, public mixer listeners/speed overrides, root-motion `AnimationComposer`, automatic camera-ray targets and camera-parented rigs stay full-rate. Assets download on demand and stay on disk between web visits: await everything the spawn camera sees before the reveal, and `await ctx.assets.prefetch(["next-level.glb"])` before `ctx.goto` only for what is out of view (a reveal before the visible content loads shows a half-built world); the idle fill downloads the rest after the reveal. Overrides on `defineGame`'s `assets`: `cache: false`, `backgroundFill: false`, both reported on `ctx.assets.cache`; native hosts read installed files.
83
- ## Budget real time for the look
84
-
85
- Reference-driven authoring starts at `node_modules/create-threenative/agent-docs/references/dream-loop.md`.
86
-
87
- Open a capture after visual changes. A scenario with no assertions or missing observations fails. The engine warns you before a human does: `TN_SCENE_WARNING` fires when the GPU used under a third of the frame while the JS render phase ran longer than the display's own period, and names the census behind it — objects considered, draws per pass, triangles per draw, shadow-exempt casters. It is a scene-shape verdict, so answer it by moving the draw and object counts, not the engine: read the bucket census before promising a merge. `npx threenative doctor` repeats the last verdict and the `DEV_MODE=true` chip shows it beside the frame rate; `TN_FRAME_SPANS=1` adds the render phase's own span tree when you need to know which part costs the milliseconds. The cheapest static object is one whose transform you never write: measured on 1,561 objects, leaving them alone costs 10.10 ms of render phase against 17.45 ms when the game rewrites every transform each frame, because three skips the per-object binding update when nothing changed. So do not touch a transform you do not need to — that is worth ~7 ms where `markStatic(root)`, which additionally composes a never-moving subtree once, measured 0.009 ms. Use it for scenery you are sure of, and `invalidateStatic(object)` to announce a write inside one; it deletes matrix arithmetic, not the walk. `TN_RENDERLIST_VALIDATE=1` recomputes every world matrix the long way each frame and throws on the first that disagrees, which is how you prove a freeze did not leave something stale on screen.
88
-
89
- For terrain generation or editing, read `node_modules/create-threenative/agent-docs/references/terrain-authoring.md`; install optional `@threenative/terrain`, bake before play, and own its appearance in `src/render/`; test water proximity with its `createSegmentIndex` and steep ground with `slopeQuantile`, never a per-point scan or fixed degrees. Recipes in the installed create-threenative: `node_modules/create-threenative/agent-docs/references/assertion-reference.md`, `node_modules/create-threenative/agent-docs/references/build-profiles.md`, `node_modules/create-threenative/agent-docs/references/capability-reference.md`, `node_modules/create-threenative/agent-docs/references/capture-the-frame.md`, `node_modules/create-threenative/agent-docs/references/creating-creatures.md`, `node_modules/create-threenative/agent-docs/references/ctx-cookbook.md`, `node_modules/create-threenative/agent-docs/references/debug-surface.md`, `node_modules/create-threenative/agent-docs/references/finding-assets.md`, `node_modules/create-threenative/agent-docs/references/gameplay-recipes.md`, `node_modules/create-threenative/agent-docs/references/menu-screens.md`, `node_modules/create-threenative/agent-docs/references/mobile-memory-budget.md`, `node_modules/create-threenative/agent-docs/references/performance-basics.md`, `node_modules/create-threenative/agent-docs/references/rigging-characters.md`, `node_modules/create-threenative/agent-docs/references/sculpt-from-a-reference.md`, `node_modules/create-threenative/agent-docs/references/trace-a-slow-frame.md`, `node_modules/create-threenative/agent-docs/references/visual-baseline.md`, and `node_modules/create-threenative/agent-docs/references/webview-ui.md`.
90
- ## Optional multiplayer transport
91
- For online play only, import `connect` from `@threenative/core/net` with an HTTPS URL and nonempty identity credential; configure `connectTimeoutMs`, `maxReliableMessageBytes`, `maxQueuedReliableBytes`, and `maxQueuedDatagrams` (10s/65,536/1 MiB/256), use `reliable-ordered` for ordered reliable messages and bounded `unreliable` datagrams that may drop, and keep serialization, replication, prediction, interpolation, snapshots and rejoin in this game's `src/` and server. There is no fallback: unsupported WebTransport/native rejects with `TN_NET_UNAVAILABLE`; reference Go server: `packages/runtime-native/examples/webtransport/server`.
92
- Backlight exception: this storm raymarches custom shader lighting in `src/render/lighting.ts`; standard-material `rimGain`/`fillGain` conversion is unqualified. Preserve its authored flash rim and sky fill. The cloud render-target radiance is unknown until sampled; do not claim an environment contribution from `scene.environment`.
93
- `src/render/exposure.ts` is optional game policy; pass it as `exposurePolicy` in `quality.ts` to use it. Core owns adaptation and its readback. Recipe: `node_modules/create-threenative/agent-docs/references/auto-exposure.md`.
94
-
95
- Core supplies Unreal filmic and metered defaults through `WorldEnvironment` and `qualityPreset`. This kit keeps both: the storm's own post pass draws bloom, grade, vignette, lens beads and dither (every built-in stage is off, named in `quality.ts`), and the core filmic curve and metered exposure do the tone map. `exposure.ts` caps the meter at +0.8 stop so the storm stays dark, and `postprocessing.ts` scales the weather exposure by 0.85 and `clouds.ts` the flash light on the clouds by 0.3 so the filmic shoulder keeps the bolt visible.
102
+ `npx threenative doctor`, then `npx @threenative/playtest doctor`; a missing observation is not zero. A confirmed engine bug: `file-engine-bug` skill. Smallest correct change: `ponytail` skill. Slow frame: `threenative-performance` skill.
103
+ <!-- /shared -->
@@ -1,97 +1,105 @@
1
1
  <!-- Generated mirror of AGENTS.md. Do not edit; edit AGENTS.md. -->
2
2
 
3
- # AGENTS.md — __PROJECT_NAME__ rain
4
- Instructions for the AI agent in this game. `CLAUDE.md` mirrors this file; edit `AGENTS.md`.
3
+ <!-- shared: kit-identity -->
4
+ # AGENTS.md — __PROJECT_NAME__ (Rain, the rain kit)
5
5
 
6
- ## Ownership
7
- ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, audio lifetimes, and the state bridge. This repository owns the coastal storm: weather presets and easing, the fly camera, the shaders, lightning, sound design and the interface; `src/game.ts` is portable and React mounts from `src/main.ts`. The render camera also skips an object that projects under **0.5 px** in it; `renderer.minimumProjectedPixels` raises that threshold (`false` disables the cut, not the count) and `alwaysRender(object)` exempts an object, while camera-attached objects and shadow casters are kept. The engine also owns the per-frame world-matrix walk, and by default it does not descend into a hidden subtree — so a game that reads a hidden object's `matrixWorld` directly must use `getWorldPosition` (or call `object.updateWorldMatrix(true, false)`) first; `renderer.matrixWorld: "all"` restores three's every-node walk, and `TN_PROJECTION` reports the visited-node count either way. Physics bodies and `ctx.camera` interpolate between fixed ticks by default; `physicsInterpolation: false` disables it globally, `body.interpolate = false` disables one body, `ctx.interpolate(object)` opts in another transform, and `ctx.resetInterpolation(object)` resets game-driven teleports (`TN_PHYSICS_INTERPOLATION` reports the setting and tracked count).
6
+ A real-time coastal weather study: shape rain, cloud, wind, fog and wetness, and watch a coastline answer. Routing words: rain. `CLAUDE.md` is a copy of this file.
7
+ <!-- /shared -->
8
8
 
9
- ## Start every change
10
- 1. **Critical authoring gate:** invoke `threenative-capabilities` to choose the route. New games: steps 1-8. Existing games: steps 5-7 only, using existing context. Follow the `ponytail` ladder. References borrow mechanics only: no code, level layouts, character names or art. A session started outside this folder has no `mcp__threenative-*` tools: call them with `node node_modules/@threenative/core/mcp/call.mjs <server> <tool> '<json>'`.
11
- 2. **New game only:** run discovery in `threenative-capabilities` before `prd-creator`. Draft the core-mechanics plan from the kit, both discovery passes and binding constraints,
12
- direct the user to review it, and wait for explicit approval plus an instruction to implement it.
13
- 3. Treat returned constraints as binding. This kit needs no navmesh and imports none, so it runs
14
- on every target; adding `@threenative/physics/navigation` would make it web and desktop only.
15
- 4. If a build, import, device, or blank frame fails, run `npx threenative doctor` and
16
- `npx @threenative/playtest doctor`; missing observations are not zero.
9
+ <!-- shared: kit-router -->
10
+ ## Authoring flow
17
11
 
18
- ## When the framework blocks you, write plain Three.js
12
+ Detail for each step: `threenative-capabilities` skill. Do the steps in order. A step with no result records `none: <reason>`. A blank step blocks the next. A hook blocks the first new file under `src/` until step 3 ran for the current prompt (`TN_DISCOVERY_GATE=off` opts out; Codex needs `/hooks` trust).
13
+
14
+ 1. **Kit** (new game only): `engine_search_capabilities {situation: "<the whole request>", scope: "request"}` returns the matching starter kit first. This folder is already a kit.
15
+ 2. **Mechanics**: per mechanic, `engine_search_references {situation}`, then `engine_reference_detail` on each hit for pinned constants and feel. To see a mechanic move, `engine_watch_reference {query: "<game> <mechanic>"}` returns a contact sheet of real gameplay. Borrow mechanics only: no code, level layouts, character names or art. Cite `file:line`.
16
+ 3. **Built-ins**: per mechanic, system or symptom, `engine_search_capabilities {situation, scope: "mechanic"}`, then `engine_capability_detail {symbol, importPath}` on every hit. Constraints are binding. `verdict: "none"` means the game writes it in `src/`.
17
+ 4. **Plan** (new game, or a change to several systems): `prd-creator` with the kit, references and built-ins. With a user, wait for explicit approval, then implement. With no user (`claude -p`, a script), record the plan and assumptions, then continue.
18
+ 5. **Assets**: `asset_search_sources`, the source's search tool, then `asset_download_file`; record source and licence in `CREDITS.md`. Nothing fits: `sculpt_plan`. A rigged GLB: `animation_inspect` (`threenative-assets` skill).
19
+ 6. **Build**: gameplay in `src/`, look in `src/render/` (`threenative-context` and `threenative-ui` skills). For parallel work, give each subagent one area and its files, then integrate.
20
+ 7. **Prove**: one fail-closed playtest per mechanic, then `pnpm test` (`threenative-playtest` skill). A fresh judge compares a `--browser-recipe webgpu --headed` capture to the reference image (`threenative-visuals` skill; `node_modules/create-threenative/agent-docs/references/dream-loop.md`).
21
+ 8. **Report**: the `pnpm dev` URL, `TN_FRAME_BUDGET`, `TN_SCENE_WARNING`, `TN_RENDER_PROJECTION`, and each skipped step with its reason.
22
+
23
+ A change to an existing game repeats steps 2-3 for that change, then steps 5-8.
24
+ <!-- /shared -->
25
+
26
+ <!-- shared: kit-mcp -->
27
+ ## MCP servers
28
+
29
+ `.mcp.json` wires six servers, and a session started in this folder loads them. Their tools can show as deferred: load them with `ToolSearch` `select:` plus the exact names, for example `select:mcp__threenative-engine__engine_search_capabilities,mcp__threenative-engine__engine_capability_detail,mcp__threenative-engine__engine_search_references,mcp__threenative-engine__engine_reference_detail,mcp__threenative-engine__engine_watch_reference`. A session started outside this folder runs `node node_modules/@threenative/core/mcp/call.mjs <server> <tool> '<json>'`; `call.mjs <server>` lists that server's tools.
19
30
 
20
- When an `@threenative/*` API is broken, missing, or does not do what you need, replace only that
21
- piece with portable Three.js/plain code. Keep the loop, scenes, input, registry, and playtest
22
- bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report what blocked you**
23
- (API, expectation, result, replacement); never stall the game.
31
+ - `threenative-engine`: before any new mechanic, helper or render stage, and on a slow frame or a wrong image. `engine_search_capabilities`, `engine_capability_detail`, `engine_search_references`, `engine_reference_detail`, `engine_watch_reference`.
32
+ - `threenative-assets`: a texture, HDRI, sound or model. `asset_search_sources`, `asset_download_file`, `audio_search_assets`, `mesh_optimize`.
33
+ - `threenative-sculpt`: a bespoke mesh or character from a reference image. `sculpt_plan`, `sculpt_spec_gate`, `sculpt_compare`, `sculpt_pass_gate`.
34
+ - `threenative-animation`: a rigged GLB with a held prop, foot slide or loop seam. `animation_inspect`, `animation_attach`, `animation_verify`.
35
+ - `threenative-terrain`: a starter terrain kit. `terrain_generate`.
36
+ - `threenative-devtools`: after `npx @threenative/playtest trace` names no cause. `performance_start_trace`, `performance_analyze_insight`.
37
+ <!-- /shared -->
24
38
 
25
- ## Workflow skills
39
+ ## This kit
26
40
 
27
- - `.agents/skills/prd-creator/SKILL.md` / `.claude/skills/prd-creator/SKILL.md` — game plan and approval gate.
28
- - `.agents/skills/threenative-capabilities/SKILL.md` / `.claude/skills/threenative-capabilities/SKILL.md` — capability search and classic-game mechanics references.
29
- - `.agents/skills/threenative-playtest/SKILL.md` / `.claude/skills/threenative-playtest/SKILL.md` — diagnosis and proof.
30
- - `.agents/skills/threenative-assets/SKILL.md` / `.claude/skills/threenative-assets/SKILL.md` — assets and sculpting.
31
- - `.agents/skills/threenative-visuals/SKILL.md` / `.claude/skills/threenative-visuals/SKILL.md` — captures and look.
32
- - `.agents/skills/threenative-performance/SKILL.md` / `.claude/skills/threenative-performance/SKILL.md` — measured budgets; read it first when the game is slow or stutters: `playtest trace`, then the `threenative-devtools` MCP server.
33
- - `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
34
- - `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
35
- - Confirmed framework bugs: use `file-engine-bug` in `.agents/skills/` or `.claude/skills/` after a minimal repro. A game-side `patches/` fix is temporary: once it is settled, it moves into the engine in one PR. Lazy-first: `.agents/skills/ponytail/SKILL.md` / `.claude/skills/ponytail/SKILL.md` — smallest correct change, and its reuse rung is the capability search above. Engine: The owned C++ engine is the default for a new game: the Wasm engine on web and the engine player on desktop. This template runs on it: `threenative.config.ts` names no `engine`. `engine: "threejs"` switches to upstream Three.js only when the user asks for it; it is never a fix for a build error. A native build names each unbound import with `TN_NATIVE_ENGINE_UNBOUND`. Android and iOS use the legacy host.
41
+ <!-- shared: kit-files -->
42
+ Source in `src/`: `audio/`, `game.ts`, `main.ts`, `render/`, `scenes/`, `state.ts`, `ui/`.
43
+ 16 scenarios in `playtests/`; `playtests/survives.playtest.json` is the smoke proof.
44
+ Exposure policy: `src/render/exposure.ts` (`node_modules/create-threenative/agent-docs/references/auto-exposure.md`).
45
+ Kit notes: `node_modules/create-threenative/agent-docs/references/kit-rain.md`.
46
+ <!-- /shared -->
36
47
 
37
- ## Commands and map
48
+ `src/state.ts` owns weather validation, the four presets, easing (tau 0.67 s) and the `distance / 343` thunder delay; `src/scenes/Boot.ts` runs the simulation clock and auto-strikes.
49
+ This repository owns the coastal storm, fly camera, shaders, lightning, sound and interface.
50
+
51
+ <!-- shared: kit-commands -->
52
+ ## Commands
38
53
 
39
54
  ```sh
40
- pnpm dev
41
- pnpm typecheck
42
- pnpm build:web
43
- pnpm build:desktop
44
- pnpm test # runs `pnpm check` first: typecheck, ESLint, Biome format
55
+ pnpm dev # play in the browser
56
+ pnpm test # typecheck, lint, format, then every playtest
57
+ pnpm build --target desktop # also: web, android, ios
58
+ npx threenative doctor # build, import, device or blank-frame failure
45
59
  ```
60
+ <!-- /shared -->
61
+
62
+ <!-- shared: kit-conventions -->
63
+ ## Conventions
64
+
65
+ Each is on by default with a named override. Detail: `node_modules/create-threenative/agent-docs/references/conventions.md#<id>`.
66
+
67
+ - **Look** `#look`: filmic curve, metered auto exposure. Override: `tonemapMode: "aces"`; `autoExposureEnabled: false` + `exposure`. Marker: `TN_WORLD_ENVIRONMENT`.
68
+ - **Quality tier (`src/render/quality.ts`)** `#quality`: GPU class picks `high`, `medium` or `low`. Override: `setupPost(..., { tier: "low" })`. Marker: `TN_QUALITY_TIER`.
69
+ - **Resolution scale** `#resolution`: `"auto"`, 0.85 on mobile-low. Override: numeric `resolutionScale`. Marker: `TN_FRAME_BUDGET`.
70
+ - **Budget real time for the look** `#frame-budget`: frame meter and scene verdict on. Override: `frameBudget: false`. Marker: `TN_FRAME_BUDGET`, `TN_SCENE_WARNING`.
71
+ - **Anti-aliasing** `#aa`: 4x MSAA on `high`, else SMAA. Override: `temporalAA: true`.
72
+ - **World-matrix walk** `#matrix-world`: visible subtrees only. Override: `renderer.matrixWorld: "all"`. Marker: `TN_PROJECTION`.
73
+ - **Projected-pixel cull** `#projected-cull`: under 0.5 px. Override: `minimumProjectedPixels`; `alwaysRender(obj)`. Marker: `TN_RENDER_PROJECTION`.
74
+ - **Physics interpolation** `#interpolation`: on for bodies and `ctx.camera`. Override: `physicsInterpolation: false`. Marker: `TN_PHYSICS_INTERPOLATION`.
75
+ - **Loading** `#loading`: `loadAll` keeps order; `addInSlices` attaches in 8 ms slices. Override: `concurrency`, `sliceSize`, `marker: false`. Marker: `TN_LOAD_ALL`.
76
+ - **Loading curtain** `#startup`: `ctx.startup.hold(label, () => ready)`. Override: reveal on measured readiness only.
77
+ - **Asset cache** `#asset-cache`: on, with idle fill. Override: `assets: { cache: false, backgroundFill: false }`. Marker: `ctx.assets.cache`.
78
+ - **Asset cook** `#asset-cook`: compact, shared images. Override: `compact: false`; `assets.exclude`; `assets.budget`. Marker: `TN_ASSETS_CONFIG`.
79
+ - **Animation rate** `#animation-rate`: `updateRate: "auto"`. Override: `updateRate: 1`. Marker: `updateRateReport`.
80
+ - **Rigged assets** `#rigged`: `.glb` in `assets/`; `AnimationPlayer` drives clips. Override: `ctx.assets.model("hero.glb")` in `Scene.load()`.
81
+ - **Clip conformance** `#clip-conformance`: measure a clip before rewriting it. Override: `clipPoseError`; `clipTrackBindings`; `clipBoneCoverage`. Marker: `boneContact`.
82
+ - **Unlit foliage** `#unlit-foliage`: warns. Override: `material.userData.tnUnlitOk = true`. Marker: `TN_UNLIT_FOLIAGE`.
83
+ - **Material backlight** `#backlight`: none, as in stock Unreal. Override: `rimGain`; `fillGain`.
84
+ - **Pointer look** `#pointer-look`: captures the canvas on click. Override: `captureOnClick: false` + `ctx.input.captureMouse()`.
85
+ - **Static scenery** `#static`: unwritten transforms stay cheap. Override: `markStatic(root)`; `invalidateStatic(obj)`. Marker: `TN_RENDERLIST_VALIDATE`.
86
+ - **Frame spans** `#spans`: off. Override: `TN_FRAME_SPANS=1`. Marker: `TN_FRAME_SPANS`.
87
+ - **Multiplayer** `#net`: none; unsupported transport rejects. Override: `connect` from `@threenative/core/net` with four limits. Marker: `TN_NET_UNAVAILABLE`.
88
+ - **Desktop window** `#desktop-mode`: CLI, then `display.fullscreen`, then `window.maximized`. Override: `--windowed`; `--maximized`; `--fullscreen`.
89
+ - **Terrain** `#terrain`: authored in the game. Override: optional `@threenative/terrain`; `references/terrain-authoring.md`.
90
+ - **Navigation** `#navigation`: none; browser-only WASM. Override: import `@threenative/physics/navigation` on purpose.
91
+ - **Move input** `#move-axis`: `input.vector("move").y` is +up. Override: one explicit `-move.y` conversion.
92
+ - **Scene change** `#scene-change`: `ctx.goto(name)` keeps state. Override: `game.goto(name)` resets state.
93
+ - **Randomness** `#seed`: unseeded. Override: `defineGame({ seed })`.
94
+ - **Engine** `#engine`: owned C++ engine. Override: `engine: "threejs"` only when the user asks. Marker: `TN_NATIVE_ENGINE_UNBOUND`.
95
+ <!-- /shared -->
96
+
97
+ <!-- shared: kit-stuck -->
98
+ ## When the framework blocks you, write plain Three.js
99
+
100
+ When an `@threenative/*` API is broken, missing, or does not do what you need, replace only that piece with portable Three.js/plain code. Keep the loop, scenes, input, registry, and playtest bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report what blocked you** (API, expectation, result, replacement); do not stall the game.
101
+
102
+ ## Stuck
46
103
 
47
- `src/state.ts` owns weather validation, the four presets, easing (τ 0.67 s), the flash envelope and
48
- the `distance / 343` thunder delay; `src/scenes/Boot.ts` runs the simulation clock, auto-strikes
49
- (gated on cloud cover above 0.35) and publishes everything the UI reads. The coast, clouds, rain
50
- and bloom/grade are shaders generated from `tools/tempest-*.frag` by `node tools/generate-shaders.mjs`;
51
- edit the `.frag`, never a generated `*-shader.ts`. Their named colours and lights live in
52
- `src/render/palette.ts`, `sky.ts`, `lighting.ts` and `materials.ts`, the bolt in `lightning.ts`. Imported foliage (Fab/Megascans cutouts) draws with its own albedo, normal map and alpha cutoff under the scene's environment light — never tint it, fake its emission or flatten its normals to make up for missing light; `TN_UNLIT_FOLIAGE` names cutout materials drawn with no environment.
53
- The coast is one ray-marched screen quad, so it is marked with `alwaysRender`; so are the rain and
54
- the bolt, whose quads are projected by their own vertex stage. Sound is three clips baked by
55
- `tools/make-storm-audio.mjs` and played through `AudioBus` in `src/audio/storm.ts`; audio starts on a
56
- gesture, and pause, mute and tab visibility each hold it. `safe` gates every strike at one door,
57
- and `prefers-reduced-motion` turns it on at boot. Keep `playtests/survives.playtest.json` as smoke
58
- proof, and `storm`, `lightning`, `reduced-motion` and `tiers` honest when you change what they assert.
59
- To build a game on the storm, keep its rules in a plain module and wire them in `src/scenes/Boot.ts`: `strike()` is the one door every strike passes (its distance and thunder delay are in scope), the frame function runs per-step rules after the camera moves, and the round's state is a `GameState` field the UI reads; `Billboard3D` turns world markers to the camera.
60
-
61
- ## Portable authoring contracts
62
-
63
- Leave `assets` absent: the cook selects target-decodable passes, with `models.sharedImages: true` deduplicating images. `sharedImages: false` embeds duplicate copies; `models.compact` (default `{ flatten: true, join: true, instance: true }`) flattens the scene graph, merges primitives by material and batches a mesh shared by several nodes as `EXT_mesh_gpu_instancing` — all lossless, keeping any node matching `protectedPattern` (or named in `protectedNames`), an animation target, or a skin joint individually addressable; `compact: false` ships the scene graph as authored. `models: "none"` / `textures: "none"` / `audio: "none"` skip those passes and report uncooked bytes. Android/iOS currently skip compression and model dedupe. `assets.exclude` defaults to `[]`; source-relative globs (for example `["unused/**"]`) omit matching files and report saved bytes. `assets.budget` accepts `{ uncooked?: number | "none", total?: number | "none" }`, default `{ uncooked: 64_000_000, total: "none" }`: only bytes left uncooked where cooking was possible count toward `uncooked`. A number sets that ceiling; `"none"` disables both gates. Either disabled gate still reports bytes. Automatic texture cooking retains unaligned source images unchanged and reports `block-size`; those bytes still count toward the uncooked budget. An explicit compression codec override must satisfy four-pixel block alignment; `codec: "none"` opts out. Cooking never silently resizes an image to fix alignment.
64
-
65
- Relative look capture: a binding with `pointerRelative: true` captures the canvas on click by default; set `captureOnClick: false` and call `ctx.input.captureMouse()` from your own gesture to opt out. Desktop mode precedence is CLI (`--windowed`, `--maximized`, `--fullscreen`) over `display.fullscreen` over `window.maximized`; with both false, `window.width`/`height` size the normal window.
66
- Scenes use `load`, `enter`, `update`, `exit`, `render`. One world unit is one metre; the camera starts at `(1.8, 2.85, 18)` and `src/render/camera.ts` owns its clamps and speeds; manual input cancels the cinematic orbit. There is no walking actor, weapon or agent here to ground, bind or navigate.
67
- `input.vector("move").y` is +up and means forward; use one explicit `-move.y` conversion.
68
- Rigged assets: put a `.glb` in `assets/`, await `ctx.assets.model("hero.glb")` in `Scene.load()`, then drive `AnimationPlayer` beside its entity. `ctx.goto(name)` rebuilds without resetting game
69
- state; from a frame function `goto` and then `return`; `ctx.state.set({ /* copy this game's initial-state shape */ })`
70
- is a partial patch. `game.goto("<scene-name>")` also rebuilds the scene, but it resets the game's
71
- state. Seeded randomness is deterministic only when `defineGame({ seed })` is configured.
72
-
73
- WebGPU reports `TN_GPU_CLASS` once per launch. Automatic `render.resolutionScale` starts at 0.85 for `mobile-low`, otherwise 1; a numeric value pins it. `TN_FRAME_BUDGET` reports the actual scale under both policies. `src/render/quality.ts` owns `low`, `medium`, `high` (the engine chain: no built-in stage at any tier); the GPU family from `ctx.renderer.gpuClass` sets the start (`discrete` `high`, `integrated` and `mobile-high` `medium`, other phones `low`); `isMobile()` chooses `low`, otherwise `high` when the family is `unknown`; override with `setupPost(..., { tier: "low" })`. Unknown tiers throw and `TN_QUALITY_TIER` reports
74
- the source. Rain keeps 4x multisampling: `temporalAA` is off in `quality.ts`, because the study draws its own single post pass. The player's four tiers are `STUDY_TIERS` in the same file. The bridge flushes about 100 ms; a control flushes it at once.
75
-
76
- When an animation looks wrong, measure it before rewriting it. `clipPoseError` scores a
77
- retargeted clip against its source per bone in degrees — whole quaternions relative to each rig's
78
- own bind pose, so the two rigs' bind conventions cancel and a limb rolled about its own axis is
79
- caught where a bone-direction check reads zero. `clipTrackBindings` names tracks that bind nothing
80
- (the `<bone>.undefined` failure that plays the bind pose instead of the animation),
81
- `clipBoneCoverage` names bones the clip does not drive and which therefore keep the previous
82
- clip's pose, and `boneContact` reports in metres whether a named bone reaches the prop it is
83
- supposed to be touching. Two loading conventions come from `@threenative/core`, not from your own loops: `loadAll(items, load)` fetches six at a time and returns results **in the input's order** (a pool that pushes returns completion order, so a positional pick lands a different asset every load), and `addInSlices(objects, (object) => ctx.add(object))` attaches in 8 ms slices so hundreds of objects never land in one long frame; override `concurrency`/`sliceSize`, pass `while: () => alive` to stop a torn-down scene without throwing, and `marker: false` silences `TN_LOAD_ALL`/`TN_ADD_SLICES` but never the measurement. Gate the loading curtain on a measured readiness with `ctx.startup.hold(label, () => ready)`: core polls it every rendered frame, so it settles without a physics step.
84
- `updateRate: "auto"` is the default and follows measured camera policy; `updateRate: 1` is full evaluation, another positive safe integer names a frame interval, and `updateRateReport` shows the effective rate, override status and latest evaluation; one-shots/fades, public mixer listeners/speed overrides, root-motion `AnimationComposer`, automatic camera-ray targets and camera-parented rigs stay full-rate. Assets download on demand and stay on disk between web visits: await everything the spawn camera sees before the reveal, and `await ctx.assets.prefetch(["next-level.glb"])` before `ctx.goto` only for what is out of view (a reveal before the visible content loads shows a half-built world); the idle fill downloads the rest after the reveal. Overrides on `defineGame`'s `assets`: `cache: false`, `backgroundFill: false`, both reported on `ctx.assets.cache`; native hosts read installed files.
85
- ## Budget real time for the look
86
-
87
- Reference-driven authoring starts at `node_modules/create-threenative/agent-docs/references/dream-loop.md`.
88
-
89
- Open a capture after visual changes. A scenario with no assertions or missing observations fails. The engine warns you before a human does: `TN_SCENE_WARNING` fires when the GPU used under a third of the frame while the JS render phase ran longer than the display's own period, and names the census behind it — objects considered, draws per pass, triangles per draw, shadow-exempt casters. It is a scene-shape verdict, so answer it by moving the draw and object counts, not the engine: read the bucket census before promising a merge. `npx threenative doctor` repeats the last verdict and the `DEV_MODE=true` chip shows it beside the frame rate; `TN_FRAME_SPANS=1` adds the render phase's own span tree when you need to know which part costs the milliseconds. The cheapest static object is one whose transform you never write: measured on 1,561 objects, leaving them alone costs 10.10 ms of render phase against 17.45 ms when the game rewrites every transform each frame, because three skips the per-object binding update when nothing changed. So do not touch a transform you do not need to — that is worth ~7 ms where `markStatic(root)`, which additionally composes a never-moving subtree once, measured 0.009 ms. Use it for scenery you are sure of, and `invalidateStatic(object)` to announce a write inside one; it deletes matrix arithmetic, not the walk. `TN_RENDERLIST_VALIDATE=1` recomputes every world matrix the long way each frame and throws on the first that disagrees, which is how you prove a freeze did not leave something stale on screen.
90
-
91
- For terrain generation or editing, read `node_modules/create-threenative/agent-docs/references/terrain-authoring.md`; install optional `@threenative/terrain`, bake before play, and own its appearance in `src/render/`; test water proximity with its `createSegmentIndex` and steep ground with `slopeQuantile`, never a per-point scan or fixed degrees. Recipes in the installed create-threenative: `node_modules/create-threenative/agent-docs/references/assertion-reference.md`, `node_modules/create-threenative/agent-docs/references/build-profiles.md`, `node_modules/create-threenative/agent-docs/references/capability-reference.md`, `node_modules/create-threenative/agent-docs/references/capture-the-frame.md`, `node_modules/create-threenative/agent-docs/references/creating-creatures.md`, `node_modules/create-threenative/agent-docs/references/ctx-cookbook.md`, `node_modules/create-threenative/agent-docs/references/debug-surface.md`, `node_modules/create-threenative/agent-docs/references/finding-assets.md`, `node_modules/create-threenative/agent-docs/references/gameplay-recipes.md`, `node_modules/create-threenative/agent-docs/references/menu-screens.md`, `node_modules/create-threenative/agent-docs/references/mobile-memory-budget.md`, `node_modules/create-threenative/agent-docs/references/performance-basics.md`, `node_modules/create-threenative/agent-docs/references/rigging-characters.md`, `node_modules/create-threenative/agent-docs/references/sculpt-from-a-reference.md`, `node_modules/create-threenative/agent-docs/references/trace-a-slow-frame.md`, `node_modules/create-threenative/agent-docs/references/visual-baseline.md`, and `node_modules/create-threenative/agent-docs/references/webview-ui.md`.
92
- ## Optional multiplayer transport
93
- For online play only, import `connect` from `@threenative/core/net` with an HTTPS URL and nonempty identity credential; configure `connectTimeoutMs`, `maxReliableMessageBytes`, `maxQueuedReliableBytes`, and `maxQueuedDatagrams` (10s/65,536/1 MiB/256), use `reliable-ordered` for ordered reliable messages and bounded `unreliable` datagrams that may drop, and keep serialization, replication, prediction, interpolation, snapshots and rejoin in this game's `src/` and server. There is no fallback: unsupported WebTransport/native rejects with `TN_NET_UNAVAILABLE`; reference Go server: `packages/runtime-native/examples/webtransport/server`.
94
- Backlight exception: this storm raymarches custom shader lighting in `src/render/lighting.ts`; standard-material `rimGain`/`fillGain` conversion is unqualified. Preserve its authored flash rim and sky fill. The cloud render-target radiance is unknown until sampled; do not claim an environment contribution from `scene.environment`.
95
- `src/render/exposure.ts` is optional game policy; pass it as `exposurePolicy` in `quality.ts` to use it. Core owns adaptation and its readback. Recipe: `node_modules/create-threenative/agent-docs/references/auto-exposure.md`.
96
-
97
- Core supplies Unreal filmic and metered defaults through `WorldEnvironment` and `qualityPreset`. This kit keeps both: the storm's own post pass draws bloom, grade, vignette, lens beads and dither (every built-in stage is off, named in `quality.ts`), and the core filmic curve and metered exposure do the tone map. `exposure.ts` caps the meter at +0.8 stop so the storm stays dark, and `postprocessing.ts` scales the weather exposure by 0.85 and `clouds.ts` the flash light on the clouds by 0.3 so the filmic shoulder keeps the bolt visible.
104
+ `npx threenative doctor`, then `npx @threenative/playtest doctor`; a missing observation is not zero. A confirmed engine bug: `file-engine-bug` skill. Smallest correct change: `ponytail` skill. Slow frame: `threenative-performance` skill.
105
+ <!-- /shared -->
@@ -11,25 +11,38 @@
11
11
  "screenshots": "after"
12
12
  },
13
13
  "steps": [
14
+ {
15
+ "kind": "wait",
16
+ "label": "boot",
17
+ "waitTicks": 30,
18
+ "release": true
19
+ },
14
20
  {
15
21
  "kind": "input",
16
- "press": "KeyL",
17
- "label": "suppressed",
18
- "waitTicks": 6,
22
+ "press": "KeyM",
23
+ "label": "sound",
24
+ "waitTicks": 10,
19
25
  "release": true
20
26
  },
21
27
  {
22
28
  "kind": "input",
23
29
  "press": "KeyX",
24
- "label": "flashes-on",
30
+ "label": "safe",
25
31
  "waitTicks": 4,
26
32
  "release": true
27
33
  },
28
34
  {
29
35
  "kind": "input",
30
- "press": "KeyM",
31
- "label": "sound",
32
- "waitTicks": 10,
36
+ "press": "KeyL",
37
+ "label": "safe-strike",
38
+ "waitTicks": 6,
39
+ "release": true
40
+ },
41
+ {
42
+ "kind": "input",
43
+ "press": "KeyX",
44
+ "label": "flashes-on",
45
+ "waitTicks": 4,
33
46
  "release": true
34
47
  },
35
48
  {
@@ -55,21 +68,55 @@
55
68
  ],
56
69
  "assert": {
57
70
  "resources": [
71
+ {
72
+ "id": "state",
73
+ "path": "reducedMotion",
74
+ "allowTrivial": "the branch this run takes: the UI page answers its own prefers-reduced-motion query and this private display has no reduced-motion setting, so WebKit answers no-preference and the storm boots flashing. The suppressed branch is the web reduced-motion scenario's (it emulates reduce). If a host ever answers reduce, this assertion names it instead of the run failing later on `safe`.",
75
+ "atSteps": [
76
+ {
77
+ "equals": false,
78
+ "label": "boot"
79
+ }
80
+ ],
81
+ "equals": false
82
+ },
58
83
  {
59
84
  "id": "state",
60
85
  "path": "safe",
61
- "allowTrivial": "this desktop web view reports prefers-reduced-motion: reduce, so the storm boots with flashes suppressed; the scenario proves a strike is suppressed until the player turns flashes back on",
62
86
  "atSteps": [
87
+ {
88
+ "equals": false,
89
+ "label": "boot"
90
+ },
63
91
  {
64
92
  "equals": true,
65
- "label": "suppressed"
93
+ "label": "safe"
94
+ },
95
+ {
96
+ "equals": true,
97
+ "label": "safe-strike"
66
98
  },
67
99
  {
68
100
  "equals": false,
69
101
  "label": "flashes-on"
102
+ },
103
+ {
104
+ "equals": false,
105
+ "label": "strike"
70
106
  }
71
107
  ]
72
108
  },
109
+ {
110
+ "id": "state",
111
+ "path": "autoLightning",
112
+ "atSteps": [
113
+ {
114
+ "equals": false,
115
+ "label": "safe"
116
+ }
117
+ ],
118
+ "equals": false
119
+ },
73
120
  {
74
121
  "id": "state",
75
122
  "path": "audioEnabled",
@@ -81,13 +128,23 @@
81
128
  ],
82
129
  "equals": true
83
130
  },
131
+ {
132
+ "id": "state",
133
+ "path": "flash",
134
+ "atSteps": [
135
+ {
136
+ "equals": 0,
137
+ "label": "safe-strike"
138
+ }
139
+ ]
140
+ },
84
141
  {
85
142
  "id": "state",
86
143
  "path": "strikes",
87
144
  "atSteps": [
88
145
  {
89
146
  "equals": 0,
90
- "label": "suppressed"
147
+ "label": "safe-strike"
91
148
  },
92
149
  {
93
150
  "equals": 1,
@@ -104,6 +161,10 @@
104
161
  "id": "state",
105
162
  "path": "status",
106
163
  "atSteps": [
164
+ {
165
+ "equals": "steady",
166
+ "label": "safe-strike"
167
+ },
107
168
  {
108
169
  "equals": "flashing",
109
170
  "label": "strike"
@@ -116,10 +177,20 @@
116
177
  "gte": 0.7,
117
178
  "lte": 1.6
118
179
  },
180
+ {
181
+ "id": "state",
182
+ "path": "lastStrike.metres",
183
+ "gte": 250,
184
+ "lte": 520
185
+ },
119
186
  {
120
187
  "id": "state",
121
188
  "path": "pendingThunderAt",
122
189
  "atSteps": [
190
+ {
191
+ "equals": -1,
192
+ "label": "safe-strike"
193
+ },
123
194
  {
124
195
  "equals": -1,
125
196
  "label": "heard"
@@ -132,6 +203,10 @@
132
203
  "entity": "storm-audio",
133
204
  "component": "pendingThunder",
134
205
  "atSteps": [
206
+ {
207
+ "equals": 0,
208
+ "label": "safe-strike"
209
+ },
135
210
  {
136
211
  "equals": 1,
137
212
  "label": "strike"