create-threenative 0.2.15 → 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,86 +1,111 @@
1
1
  <!-- Generated mirror of AGENTS.md. Do not edit; edit AGENTS.md. -->
2
2
 
3
- # AGENTS.md — __PROJECT_NAME__ first-person town firefight
3
+ <!-- shared: kit-identity -->
4
+ # AGENTS.md — __PROJECT_NAME__ (First-person shooter, the shooter kit)
4
5
 
5
- Instructions for the AI agent in this game. `CLAUDE.md` mirrors this file; edit `AGENTS.md`.
6
+ Mouse look, a weapon in your hands, aim down the sights, reload, and targets that hunt you. Routing words: shooter. `CLAUDE.md` is a copy of this file.
7
+ <!-- /shared -->
6
8
 
7
- ## Ownership
9
+ <!-- shared: kit-router -->
10
+ ## Authoring flow
8
11
 
9
- ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, and the state bridge. This repository owns the town, the soldiers, the rifle, the HUD and the look; `src/game.ts` is
10
- portable, `src/main.ts` is the web-only React mount. 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).
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).
11
13
 
12
- ## Start every change
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.
13
22
 
14
- 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>'`.
15
- 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,
16
- direct the user to review it, and wait for explicit approval plus an instruction to implement.
17
- 3. Treat returned constraints as binding. `@threenative/physics/navigation` is browser-only WASM;
18
- use the direct physics queries already in this kit instead of a navmesh or distance scan.
19
- 4. If a build, import, device, or blank frame fails, run `npx threenative doctor` and
20
- `npx @threenative/playtest doctor`; missing observations are not zero.
21
- For *"a bullet passes through a wall"*, `RigidBody3D` defaults to continuous collision; `continuousCollision` is the named per-body override, and `body.continuousCollision` reports the effective setting on web/native.
23
+ A change to an existing game repeats steps 2-3 for that change, then steps 5-8.
24
+ <!-- /shared -->
22
25
 
23
- ## When the framework blocks you, write plain Three.js
24
-
25
- When an `@threenative/*` API is broken, missing, or does not do what you need, replace only that
26
- piece with portable Three.js. Keep the loop, scenes, input, registry, and playtest bridge; avoid DOM
27
- globals, dynamic `import()`, and raw physics handles. **Report what blocked you** (API, expectation,
28
- result, replacement); never stall the game.
29
-
30
- ## Workflow skills
31
-
32
- - `.agents/skills/prd-creator/SKILL.md` / `.claude/skills/prd-creator/SKILL.md` — game plan and approval gate.
33
- - `.agents/skills/threenative-capabilities/SKILL.md` / `.claude/skills/threenative-capabilities/SKILL.md` — capability search and classic-game mechanics references.
34
- - `.agents/skills/threenative-playtest/SKILL.md` / `.claude/skills/threenative-playtest/SKILL.md` — diagnosis and proof.
35
- - `.agents/skills/threenative-assets/SKILL.md` / `.claude/skills/threenative-assets/SKILL.md` — assets and sculpting.
36
- - `.agents/skills/threenative-visuals/SKILL.md` / `.claude/skills/threenative-visuals/SKILL.md` — captures and look.
37
- - `.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.
38
- - `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
39
- - `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
40
- - 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
-
42
- ## Commands and map
26
+ <!-- shared: kit-mcp -->
27
+ ## MCP servers
43
28
 
44
- ```sh
45
- pnpm dev
46
- pnpm build
47
- pnpm build --target desktop
48
- pnpm test # runs `pnpm check` first: typecheck, ESLint, Biome format
49
- pnpm typecheck
50
- ```
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.
51
30
 
52
- Contract: a 105-second round in a procedurally built 84 m waterfront town; 12 hits completes it, zero
53
- health or an expired clock fails it, Enter restarts. Mouse looks, WASD or arrows move, Space or left
54
- click fires, F or right click aims, R reloads, shift sprints, ctrl/C crouches. `src/render/town.ts`
55
- owns the layout — blocks, quay, pier, raised decks, routes, spawns — and every solid in it is both a
56
- collider and a raycast target. `src/entities/` owns the fight: `FpsPlayer` moves, `Rifle` fires and
57
- zeroes, `Enemy` patrols, hears, sees and shoots back, `Target` scores the plates. `src/scenes/Play.ts`
58
- wires them and `src/ui/Hud.tsx` is the only HUD. `index.html` runs `game.ts` in a web
59
- worker (`src/worker.ts`, page side `src/worker-page.ts`), so a busy page cannot stall its frames; `main.html` is the named override that runs it on the page thread. `playtests/survives.playtest.json` is the durable
60
- smoke proof. The soldiers are `assets/mannequin-combat.glb` (Quaternius UAL, CC0); the hands in
61
- `assets/player-viewmodel.glb` are "Animated FPS hands (rifle animation pack)" by Cransh,
62
- CC-BY-4.0 — https://sketchfab.com/3d-models/animated-fps-hands-rifle-animation-pack-5f2d0ed780a94724b36ab505f7564057.
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 -->
63
38
 
64
- ## Portable authoring contracts
39
+ ## This kit
65
40
 
66
- Leave `assets` absent: the cook selects target-decodable passes, and `models.compact` (default `{ flatten: true, join: true, instance: true }`) flattens the scene graph losslessly while keeping any node matching `protectedPattern` or `protectedNames`, an animation target, or a skin joint individually addressable; `compact: false` ships it as authored. `models`/`textures`/`audio`: `"none"` skip those passes and report uncooked bytes, and a codec override must satisfy four-pixel block alignment — `codec: "none"` opts out. `assets.exclude` (source-relative globs) omits files and reports 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, an unaligned source image is retained unchanged and still counted, and cooking never resizes one to fix alignment. Android/iOS skip compression and dedupe.
67
- 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.
68
- First person, four rules: place the camera in the plugin hook after the physics step, never at the end of the frame function, or the eye sits one step behind the body and shots land in the floor on the deck stairs; start every shot at `player.aimRay()`, where the crosshair is, and let `Rifle.converge` lean the weapon to meet it; the trigger takes `pressed` and `justPressed`, because the cooldown makes the cadence and the edge catches a click the harness delivers no other way; `src/render/scale.ts` is the only size table.
41
+ <!-- shared: kit-files -->
42
+ Source in `src/`: `entities/`, `game.ts`, `main.ts`, `postPhysics.ts`, `render/`, `scenes/`, `state.ts`, `surfaces.ts`, `ui/`, `worker-page.ts`, `worker.ts`.
43
+ 38 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-shooter.md`.
46
+ <!-- /shared -->
69
47
 
70
- 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. Scenes use `load`, `enter`, `update`, `exit`, `render`; physics nodes are Godot-named and disposable. Rigged assets: put a `.glb` in `assets/`, await `ctx.assets.model("hero.glb")` in `Scene.load()`, size it with `normaliseToMetres` at a named joint, drive `AnimationPlayer` beside its entity, and reach a held prop with `attachToBone`. `input.vector("move").y` is +up, so forward uses one explicit `-move.y`. `ctx.goto(name)` rebuilds without resetting game state (from a frame function, `goto` then `return`); `ctx.state.set({ … })` is a partial patch; `game.goto()` rebuilds and resets. Seeded randomness needs `defineGame({ seed })`.
71
- `src/render/sky.ts` draws Unreal's default sky (an atmosphere with clouds: `atmosphere.ts`, `clouds.ts`, `gpuSky.ts`) as background, environment light and height-fog colour, and `lighting.ts` tints the sun at `SUN_DIRECTION` by the air it crosses; `SKY_OPTIONS` takes `sky: "photo"` for `assets/sky.jpg` (Poly Haven, CC0) or `clouds: false`, and `ground: false` once the game has its own global illumination (the sunlit ground under the horizon stands in for the bounce); `src/render/quality.ts` owns `low`, `medium`, `high`; 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, `TN_QUALITY_TIER` reports the source, and the bridge flushes about 100 ms — keep score/phase in state, feedback in Three.js. The shared look comes from core through `src/render/quality.ts`; the filmic curve and metered auto exposure are enabled by default. `src/render/exposure.ts` holds this game's meter policy (`key` 0.14, `maxStops` 0.5, `minStops` -2). Set `tonemapMode: "aces"` to choose ACES, or `autoExposureEnabled: false` with a fixed `exposure` to choose manual exposure, on the same quality preset; the render log reports the override. It has Unreal's bloom with no threshold (`unrealBloomEnabled`), local exposure (`localExposureEnabled`, off on `low`), a cosine-fourth vignette (`vignetteAmount: 0.4`) and no motion blur on any tier: a mouse turn smeared the whole frame and the hands (`motionBlurEnabled: true` brings it back). Anti-aliasing is core's: 4x MSAA on `high`, SMAA on `medium` and `low`; `temporalAA: true` is the named opt-in. The grade is neutral and the frame has no film grain. Each stage has a named override: `unrealBloomEnabled: false` returns to Three's `BloomNode` (`bloomStrength`, `bloomRadius`, `bloomThreshold`), and `vignetteAmount: 0` removes the vignette. For a colour grade or grain, add the starter's `grade.ts` and `public/grade.cube`, then set `gradeIntensity` and `grainIntensity`. Imported foliage (Fab/Megascans cutouts) draws with its own albedo, normal map and alpha cutoff under the environment light `sky.ts` makes — 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.
48
+ A 105-second round in a procedurally built 84 m waterfront town: 12 hits complete it, zero health or an expired clock fails it, Enter restarts. Mouse looks; WASD or arrows move.
49
+ This repository owns the town, soldiers, rifle, HUD and look.
72
50
 
73
- When an animation looks wrong, measure it before rewriting it: `clipPoseError` scores a retargeted clip per bone in degrees relative to each rig's own bind pose, `clipTrackBindings` names tracks that bind nothing (the `<bone>.undefined` failure that plays the bind pose), `clipBoneCoverage` names bones the clip does not drive, and `boneContact` reports whether a bone reaches its prop. A soldier reads as a soldier only when every AI state picks a clip that names the action — patrol and chase `Rifle_Walk`, standing aim `Rifle_Idle`, firing `Rifle_Shoot`, crouch `Rifle_Crouch_To_Idle`/`Rifle_Crouch_Walk` (the six `Rifle_*` clips are Mixamo rifle clips retargeted onto the mannequin, and `RIFLE_HOLD` in `Enemy.ts` turns the rifle to each; the soldier's `rightHandContact`/`leftHandContact` are `boneContact` metres, held under 0.05), hit `Rifle_Hit`, dead `Death01` — crossfaded, feet snapped to the floor, body turned into the direction of travel or aim, and tinted so he does not vanish into the white first-person hands.
74
- 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. 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.
51
+ <!-- shared: kit-commands -->
52
+ ## Commands
75
53
 
76
- `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.
54
+ ```sh
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
+ pnpm test:native # native proof
59
+ npx threenative doctor # build, import, device or blank-frame failure
60
+ ```
61
+ <!-- /shared -->
62
+
63
+ <!-- shared: kit-conventions -->
64
+ ## Conventions
65
+
66
+ Each is on by default with a named override. Detail: `node_modules/create-threenative/agent-docs/references/conventions.md#<id>`.
67
+
68
+ - **Look** `#look`: filmic curve, metered auto exposure. Override: `tonemapMode: "aces"`; `autoExposureEnabled: false` + `exposure`. Marker: `TN_WORLD_ENVIRONMENT`.
69
+ - **Quality tier (`src/render/quality.ts`)** `#quality`: GPU class picks `high`, `medium` or `low`. Override: `setupPost(..., { tier: "low" })`. Marker: `TN_QUALITY_TIER`.
70
+ - **Resolution scale** `#resolution`: `"auto"`, 0.85 on mobile-low. Override: numeric `resolutionScale`. Marker: `TN_FRAME_BUDGET`.
71
+ - **Budget real time for the look** `#frame-budget`: frame meter and scene verdict on. Override: `frameBudget: false`. Marker: `TN_FRAME_BUDGET`, `TN_SCENE_WARNING`.
72
+ - **Anti-aliasing** `#aa`: 4x MSAA on `high`, else SMAA. Override: `temporalAA: true`.
73
+ - **World-matrix walk** `#matrix-world`: visible subtrees only. Override: `renderer.matrixWorld: "all"`. Marker: `TN_PROJECTION`.
74
+ - **Projected-pixel cull** `#projected-cull`: under 0.5 px. Override: `minimumProjectedPixels`; `alwaysRender(obj)`. Marker: `TN_RENDER_PROJECTION`.
75
+ - **Physics interpolation** `#interpolation`: on for bodies and `ctx.camera`. Override: `physicsInterpolation: false`. Marker: `TN_PHYSICS_INTERPOLATION`.
76
+ - **Continuous collision** `#continuous`: on for `RigidBody3D`. Override: `continuousCollision: false`. Marker: `body.continuousCollision`.
77
+ - **Loading** `#loading`: `loadAll` keeps order; `addInSlices` attaches in 8 ms slices. Override: `concurrency`, `sliceSize`, `marker: false`. Marker: `TN_LOAD_ALL`.
78
+ - **Loading curtain** `#startup`: `ctx.startup.hold(label, () => ready)`. Override: reveal on measured readiness only.
79
+ - **Asset cache** `#asset-cache`: on, with idle fill. Override: `assets: { cache: false, backgroundFill: false }`. Marker: `ctx.assets.cache`.
80
+ - **Asset cook** `#asset-cook`: compact, shared images. Override: `compact: false`; `assets.exclude`; `assets.budget`. Marker: `TN_ASSETS_CONFIG`.
81
+ - **Animation rate** `#animation-rate`: `updateRate: "auto"`. Override: `updateRate: 1`. Marker: `updateRateReport`.
82
+ - **Feet on the floor** `#ground-snap`: `GroundSnap`. Override: `enabled: false`.
83
+ - **Held prop** `#attach`: `attachToBone`. Override: a portable `Bone` named `RightHand`.
84
+ - **One metre is one metre** `#scale`: `normaliseToMetres`. Override: per-call options.
85
+ - **Rigged assets** `#rigged`: `.glb` in `assets/`; `AnimationPlayer` drives clips. Override: `ctx.assets.model("hero.glb")` in `Scene.load()`.
86
+ - **Clip conformance** `#clip-conformance`: measure a clip before rewriting it. Override: `clipPoseError`; `clipTrackBindings`; `clipBoneCoverage`. Marker: `boneContact`.
87
+ - **Unlit foliage** `#unlit-foliage`: warns. Override: `material.userData.tnUnlitOk = true`. Marker: `TN_UNLIT_FOLIAGE`.
88
+ - **Material backlight** `#backlight`: none, as in stock Unreal. Override: `rimGain`; `fillGain`.
89
+ - **Environment contribution** `#env-contribution`: reported even at zero. Override: `environmentSampling`. Marker: `TN_ENVIRONMENT_CONTRIBUTION`.
90
+ - **Pointer look** `#pointer-look`: captures the canvas on click. Override: `captureOnClick: false` + `ctx.input.captureMouse()`.
91
+ - **Static scenery** `#static`: unwritten transforms stay cheap. Override: `markStatic(root)`; `invalidateStatic(obj)`. Marker: `TN_RENDERLIST_VALIDATE`.
92
+ - **Frame spans** `#spans`: off. Override: `TN_FRAME_SPANS=1`. Marker: `TN_FRAME_SPANS`.
93
+ - **Multiplayer** `#net`: none; unsupported transport rejects. Override: `connect` from `@threenative/core/net` with four limits. Marker: `TN_NET_UNAVAILABLE`.
94
+ - **Desktop window** `#desktop-mode`: CLI, then `display.fullscreen`, then `window.maximized`. Override: `--windowed`; `--maximized`; `--fullscreen`.
95
+ - **Terrain** `#terrain`: authored in the game. Override: optional `@threenative/terrain`; `references/terrain-authoring.md`.
96
+ - **Navigation** `#navigation`: none; browser-only WASM. Override: import `@threenative/physics/navigation` on purpose.
97
+ - **Move input** `#move-axis`: `input.vector("move").y` is +up. Override: one explicit `-move.y` conversion.
98
+ - **Scene change** `#scene-change`: `ctx.goto(name)` keeps state. Override: `game.goto(name)` resets state.
99
+ - **Randomness** `#seed`: unseeded. Override: `defineGame({ seed })`.
100
+ - **Engine** `#engine`: owned C++ engine. Override: `engine: "threejs"` only when the user asks. Marker: `TN_NATIVE_ENGINE_UNBOUND`.
101
+ <!-- /shared -->
102
+
103
+ <!-- shared: kit-stuck -->
104
+ ## When the framework blocks you, write plain Three.js
77
105
 
78
- ## Budget real time for the look — see `node_modules/create-threenative/agent-docs/references/dream-loop.md`
106
+ 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.
79
107
 
80
- 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; `TN_FRAME_SPANS=1` adds the render phase's own span tree. 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.
108
+ ## Stuck
81
109
 
82
- 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`. On a touch-primary device, `src/entities/TouchControls.ts` adds a movement stick, a look stick, and fire, aim, reload and crouch pads; the stick pushed to its rim sprints.
83
- ## Optional multiplayer transport
84
- 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`.
85
- Material backlighting lives in `src/render/lighting.ts`: named `rimGain` and `fillGain` controls preserve the authored palette; `materialLighting.ts` reports `TN_ENVIRONMENT_CONTRIBUTION`. Admission is limited to high hardware desktop WebGPU; mobile/software/WebGL/native retain original materials. Existing authored fill stays authoritative.
86
- `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`. Fog is height fog: `HEIGHT_FOG` in `src/render/heightFog.ts` (`density`, `heightFalloff`, `fogHeight`, `maxOpacity`, `startDistance`, `sunExponent`, `sunStartDistance`, `cutoffDistance`) is added to the `FogExp2` distance term on `scene.fogNode` and never replaces it, so a streaming fog `far` still holds.
110
+ `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.
111
+ <!-- /shared -->
@@ -19,9 +19,9 @@
19
19
  "format:check": "biome format src"
20
20
  },
21
21
  "dependencies": {
22
- "@threenative/core": "0.3.11",
23
- "@threenative/physics": "0.3.11",
24
- "@threenative/ui": "0.3.11",
22
+ "@threenative/core": "0.3.12",
23
+ "@threenative/physics": "0.3.12",
24
+ "@threenative/ui": "0.3.12",
25
25
  "react": "19.2.0",
26
26
  "react-dom": "19.2.0",
27
27
  "three": "0.187.0"
@@ -30,12 +30,12 @@
30
30
  "@tailwindcss/vite": "4.3.3",
31
31
  "@types/three": "0.187.0",
32
32
  "@vitejs/plugin-react": "6.0.5",
33
- "@threenative/assets": "0.3.12",
34
- "@threenative/playtest": "0.3.11",
33
+ "@threenative/assets": "0.3.13",
34
+ "@threenative/playtest": "0.3.12",
35
35
  "@types/react": "19.2.0",
36
36
  "@types/react-dom": "19.2.0",
37
37
  "playwright": "1.62.1",
38
- "create-threenative": "0.2.15",
38
+ "create-threenative": "0.2.17",
39
39
  "esbuild": "0.27.0",
40
40
  "tailwindcss": "4.3.3",
41
41
  "typescript": "7.0.2",
@@ -45,7 +45,7 @@
45
45
  "eslint": "10.13.0"
46
46
  },
47
47
  "optionalDependencies": {
48
- "@threenative/runtime-native": "0.3.11"
48
+ "@threenative/runtime-native": "0.3.12"
49
49
  },
50
50
  "overrides": {
51
51
  "sharp": ">=0.35.4",
@@ -396,23 +396,12 @@ const SUN_LUX = 6;
396
396
  export const SUN_KELVIN = 6500;
397
397
 
398
398
  /**
399
- * The sun in three's light units. Unreal renders a lit diffuse surface as albedo x lux x cos(theta);
400
- * three's Lambert BRDF carries a 1/pi, so the same lux is pi times as large here. Measured on the
401
- * Unreal L1 cells (no atmosphere, scene-linear EXR): a 0.18 floor under the 60 degree sun reads
402
- * 0.874 luminance, within 7% of 0.18 x 6 x sin(60 deg) = 0.935 (the residual is checked on the
403
- * engine's own L1 capture).
399
+ * The sun in three's light units, which are Unreal's: both shade a diffuse surface as
400
+ * albedo / pi x lux x cos(theta) (Diffuse_Lambert, Engine/Shaders/Private/BRDF.ush:157), and the
401
+ * sky is radiance in the same units. The frame's brightness is the exposure's job, not the light's:
402
+ * with its meter off Unreal exposes by 2.4 (`qualityPreset`), and the L1 cells match at that value.
404
403
  */
405
- export const SUN_ILLUMINANCE = SUN_LUX * Math.PI;
406
-
407
- /**
408
- * Sky radiance relative to the sun, as Unreal renders it. TEMPORARY, measured and not derived: with
409
- * the sun at 6 lux the model above is 1.3x too bright against the Unreal L2 frames, flat across
410
- * channels and across the 15 and 4 degree suns (1.30 / 1.30 / 1.35 at 19 degrees elevation), so
411
- * the sky is scaled by 1/1.3. The lens attenuation constant 0.78 (PostProcessEyeAdaptation.cpp,
412
- * r.EyeAdaptation.LensAttenuation) has the right size but the path that would apply it to the
413
- * atmosphere and not to the sun is not found in the source yet.
414
- */
415
- export const SKY_TO_SUN = 0.78;
404
+ export const SUN_ILLUMINANCE = SUN_LUX;
416
405
 
417
406
  /**
418
407
  * Colour of a black-body-like light at `kelvin` as linear sRGB with unit luminance: the Planckian
@@ -53,7 +53,6 @@ import {
53
53
  MIE_SCATTER,
54
54
  OZONE,
55
55
  RAYLEIGH,
56
- SKY_TO_SUN,
57
56
  SUN_ILLUMINANCE,
58
57
  SUN_KELVIN,
59
58
  TOP_KM,
@@ -273,7 +272,7 @@ class GpuSkyNode extends Node<"vec3"> {
273
272
  readonly #quad = new QuadMesh(new NodeMaterial());
274
273
  readonly #noise = cloudNoise();
275
274
  readonly #fog = uniform(new Color());
276
- readonly #scale = vec3(...temperatureColour(SUN_KELVIN)).mul(SUN_ILLUMINANCE * SKY_TO_SUN);
275
+ readonly #scale = vec3(...temperatureColour(SUN_KELVIN)).mul(SUN_ILLUMINANCE);
277
276
  readonly #light = uniform(new Vector3());
278
277
  readonly #ambient = uniform(new Vector3());
279
278
  #last = new Vector3(Number.NaN, 0, 0);
@@ -587,9 +586,7 @@ class GpuSkyNode extends Node<"vec3"> {
587
586
  .greaterThanEqual(Math.cos(SUN_RADIUS))
588
587
  .and(skyDisc.greaterThan(0.5))
589
588
  .select(
590
- this.#light
591
- .mul(this.clouds ? cloud.a : float(1))
592
- .div(PI * Math.sin(SUN_RADIUS) ** 2 * SKY_TO_SUN),
589
+ this.#light.mul(this.clouds ? cloud.a : float(1)).div(PI * Math.sin(SUN_RADIUS) ** 2),
593
590
  vec3(0),
594
591
  );
595
592
  const colour = sky.add(disc).mul(this.#scale);
@@ -665,7 +662,7 @@ function distantFogColour(sun: Vector3): Color {
665
662
  const tint = temperatureColour(SUN_KELVIN);
666
663
  const light = viewDistanceSkyLight(sun);
667
664
  return new Color(
668
- ...([0, 1, 2].map((c) => (light[c] ?? 0) * (tint[c] ?? 1) * SUN_ILLUMINANCE * SKY_TO_SUN) as [
665
+ ...([0, 1, 2].map((c) => (light[c] ?? 0) * (tint[c] ?? 1) * SUN_ILLUMINANCE) as [
669
666
  number,
670
667
  number,
671
668
  number,
@@ -720,7 +717,7 @@ export function createGpuSky(
720
717
  const refresh = () => {
721
718
  const start = performance.now();
722
719
  const data = bakedRadiance(sun, w, h, ground, clouds);
723
- const scale = temperatureColour(SUN_KELVIN).map((v) => v * SUN_ILLUMINANCE * SKY_TO_SUN) as [
720
+ const scale = temperatureColour(SUN_KELVIN).map((v) => v * SUN_ILLUMINANCE) as [
724
721
  number,
725
722
  number,
726
723
  number,
@@ -52,7 +52,9 @@ export const neutralLook: IWorldEnvironmentOptions = {
52
52
  // ACES at a fixed exposure: core's filmic curve and metered exposure read yellowish on this town.
53
53
  tonemapMode: "aces",
54
54
  autoExposureEnabled: false,
55
- exposure: 0.62,
55
+ // 0.62 was chosen under a sun of 6 x pi; the sun is Unreal's 6 lux now (PRD-632), so pi keeps the sunlit
56
+ // surfaces where the owner picked them.
57
+ exposure: 0.62 * Math.PI,
56
58
  // The kit's bloom: a low threshold that lifts the sunlit whitewash a little.
57
59
  bloomRadius: 0.5,
58
60
  bloomStrength: 0.7,
@@ -1,92 +1,106 @@
1
- # AGENTS.md — __PROJECT_NAME__ snow
1
+ <!-- shared: kit-identity -->
2
+ # AGENTS.md — __PROJECT_NAME__ (Snow glade, the snow kit)
2
3
 
3
- Instructions for the AI agent in this game. `CLAUDE.md` mirrors this file; edit `AGENTS.md`.
4
+ Deformable snow that remembers every footstep, a ball that carves its own track, and weather you can turn into a blizzard. Routing words: snow. `CLAUDE.md` is a copy of this file.
5
+ <!-- /shared -->
4
6
 
5
- ## Ownership
7
+ <!-- shared: kit-router -->
8
+ ## Authoring flow
6
9
 
7
- ThreeNative owns bootstrap, renderer, fixed-step loop, input, loading, physics bindings, and the state bridge. This repository owns the explorer, the boot print, the glade, the weather, the HUD and the
8
- look; `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).
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).
9
11
 
10
- ## Start every change
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.
11
20
 
12
- 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>'`.
13
- 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,
14
- direct the user to review it, and wait for explicit approval plus an instruction to implement it.
15
- 3. Treat returned constraints as binding. This kit needs no navmesh and imports none, so it runs
16
- on every target; adding `@threenative/physics/navigation` would make it web and desktop only.
17
- 4. If a build, import, device, or blank frame fails, run `npx threenative doctor` and
18
- `npx @threenative/playtest doctor`; missing observations are not zero.
19
- For *"a bullet passes through a wall"*, `RigidBody3D` defaults to continuous collision; `continuousCollision` is the named per-body override, and `body.continuousCollision` reports the effective setting on web/native.
21
+ A change to an existing game repeats steps 2-3 for that change, then steps 5-8.
22
+ <!-- /shared -->
20
23
 
21
- ## When the framework blocks you, write plain Three.js
22
-
23
- When an `@threenative/*` API is broken, missing, or does not do what you need, replace only that
24
- piece with portable Three.js/plain code. Keep the loop, scenes, input, registry, and playtest
25
- bridge; avoid DOM globals, dynamic `import()`, and raw physics handles. **Report what blocked you**
26
- (API, expectation, result, replacement); never stall the game.
27
-
28
- ## Workflow skills
29
-
30
- - `.agents/skills/prd-creator/SKILL.md` / `.claude/skills/prd-creator/SKILL.md` — game plan and approval gate.
31
- - `.agents/skills/threenative-capabilities/SKILL.md` / `.claude/skills/threenative-capabilities/SKILL.md` — capability search and classic-game mechanics references.
32
- - `.agents/skills/threenative-playtest/SKILL.md` / `.claude/skills/threenative-playtest/SKILL.md` — diagnosis and proof.
33
- - `.agents/skills/threenative-assets/SKILL.md` / `.claude/skills/threenative-assets/SKILL.md` — assets and sculpting.
34
- - `.agents/skills/threenative-visuals/SKILL.md` / `.claude/skills/threenative-visuals/SKILL.md` — captures and look.
35
- - `.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.
36
- - `.agents/skills/threenative-ui/SKILL.md` / `.claude/skills/threenative-ui/SKILL.md` — native-safe UI.
37
- - `.agents/skills/threenative-context/SKILL.md` / `.claude/skills/threenative-context/SKILL.md` — portable ctx APIs.
38
- - 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 pins `engine: "threejs"` in `threenative.config.ts` because the native engine does not bind some of its imports yet. The pin keeps upstream Three.js on web and the legacy host on desktop. A native build names each unbound import with `TN_NATIVE_ENGINE_UNBOUND`. Android and iOS use the legacy host.
24
+ <!-- shared: kit-mcp -->
25
+ ## MCP servers
39
26
 
40
- ## Commands and map
41
-
42
- ```sh
43
- pnpm dev
44
- pnpm build
45
- pnpm test # runs `pnpm check` first: typecheck, ESLint, Biome format
46
- pnpm test:native
47
- ```
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.
48
28
 
49
- The snow is one `SnowField` (`@threenative/core/world`) over one `Heightfield` built in `src/terrain.ts`: indentation, bank, compaction and disturbance composed into the canonical surface that queries, the drawn mesh and the collider all read. Never keep a second height grid.
50
- `attachSnowPhysics` (`@threenative/physics`) owns the snow collider: each fixed step it reads the solver's contacts for the ball, crate and log, presses each body's own shape with its solved load, and installs the changed surface before the next step. Call `step` from `afterPhysics`, once; `observe()` reports `colliderError` and `loadProvenance` (load is a solver estimate). A kinematic `CharacterBody3D` makes no contact load, so `src/entities/Explorer.ts` plants `src/render/bootPrint.ts` itself with `snow.stamp`, only while `grounded`. Its capsule stands on a coarse walk surface (`walkSurface` in `src/terrain.ts`), not the 6 cm snow collider: Rapier sweeps a character against every triangle under it, which cost ~0.9 ms a step there.
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 -->
51
36
 
52
- Look lives in `src/render/`: `snowSurface.ts` (TSL material, compaction view, redraws each `takeDirtyRegions` window, one upload range per row), `weather.ts` (`GPUParticles3D` snowfall and powder), `explorer.ts`, `scenery.ts`, `props.ts`. Tune response with `depth`/`hardness` and the refill in `src/scenes/Snow.ts`. The React HUD reads `GameState` and sends intents; `src/commands.ts` routes panel verbs into the same functions as the keys. Keep `playtests/survives.playtest.json` as smoke proof and `playtests/snow-physics.playtest.json` honest: it proves drop, settle and rolling track.
53
- On a touch-primary device (`isMobile() && isTouchscreenAvailable()`), `src/render/touch-controls.ts` adds a left movement stick; keyboard is the desktop fallback.
37
+ ## This kit
54
38
 
55
- ## Portable authoring contracts
39
+ <!-- shared: kit-files -->
40
+ Source in `src/`: `audio.ts`, `commands.ts`, `entities/`, `game.ts`, `main.ts`, `render/`, `scenes/`, `state.ts`, `terrain.ts`, `ui/`.
41
+ 6 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-snow.md`.
44
+ <!-- /shared -->
56
45
 
57
- 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.
46
+ The snow is one `SnowField` (`@threenative/core/world`) over one `Heightfield` in `src/terrain.ts`; queries, mesh and collider all read it. Keep no second height grid.
47
+ `attachSnowPhysics` owns the snow collider; call `step` from `afterPhysics`, once.
58
48
 
59
- 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.
60
- Scenes use `load`, `enter`, `update`, `exit`, `render`; physics nodes are Godot-named and disposable. The fixed step is the snow's clock: deposition, footsteps and contacts never read the frame rate.
61
- `input.vector("move").y` is +up and means forward; `Snow.ts` turns it into a camera-relative direction.
62
- Rigged assets: put a `.glb` in `assets/`, await `ctx.assets.model("hero.glb")` in `Scene.load()`, then drive `AnimationPlayer` beside its entity. 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. `ctx.goto(name)` rebuilds without resetting game
63
- state; from a frame function `goto` and then `return`; `ctx.state.set({ /* copy this game's initial-state shape */ })`
64
- is a partial patch. `game.goto("<scene-name>")` also rebuilds the scene, but it resets the game's
65
- state. Seeded randomness is deterministic only when `defineGame({ seed })` is configured.
49
+ <!-- shared: kit-commands -->
50
+ ## Commands
66
51
 
67
- 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 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
68
- the source. Snow keeps 4x multisampling: `temporalAA` is off in `quality.ts`, because the engine draws no velocity for the sprite flakes, and tens of thousands of them could trail. The bridge flushes about 100 ms; keep readouts in state and frame feedback in Three.js.
69
-
70
- When an animation looks wrong, measure it before rewriting it. `clipPoseError` scores a
71
- retargeted clip against its source per bone in degrees — whole quaternions relative to each rig's
72
- own bind pose, so the two rigs' bind conventions cancel and a limb rolled about its own axis is
73
- caught where a bone-direction check reads zero. `clipTrackBindings` names tracks that bind nothing
74
- (the `<bone>.undefined` failure that plays the bind pose instead of the animation),
75
- `clipBoneCoverage` names bones the clip does not drive and which therefore keep the previous
76
- clip's pose, and `boneContact` reports in metres whether a named bone reaches the prop it is
77
- 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.
78
- `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.
79
-
80
- ## Budget real time for the look
81
-
82
- Reference-driven authoring starts at `node_modules/create-threenative/agent-docs/references/dream-loop.md`.
52
+ ```sh
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
+ pnpm test:native # native proof
57
+ npx threenative doctor # build, import, device or blank-frame failure
58
+ ```
59
+ <!-- /shared -->
60
+
61
+ <!-- shared: kit-conventions -->
62
+ ## Conventions
63
+
64
+ Each is on by default with a named override. Detail: `node_modules/create-threenative/agent-docs/references/conventions.md#<id>`.
65
+
66
+ - **Look** `#look`: filmic curve, metered auto exposure. Override: `tonemapMode: "aces"`; `autoExposureEnabled: false` + `exposure`. Marker: `TN_WORLD_ENVIRONMENT`.
67
+ - **Quality tier (`src/render/quality.ts`)** `#quality`: GPU class picks `high`, `medium` or `low`. Override: `setupPost(..., { tier: "low" })`. Marker: `TN_QUALITY_TIER`.
68
+ - **Resolution scale** `#resolution`: `"auto"`, 0.85 on mobile-low. Override: numeric `resolutionScale`. Marker: `TN_FRAME_BUDGET`.
69
+ - **Budget real time for the look** `#frame-budget`: frame meter and scene verdict on. Override: `frameBudget: false`. Marker: `TN_FRAME_BUDGET`, `TN_SCENE_WARNING`.
70
+ - **Anti-aliasing** `#aa`: 4x MSAA on `high`, else SMAA. Override: `temporalAA: true`.
71
+ - **World-matrix walk** `#matrix-world`: visible subtrees only. Override: `renderer.matrixWorld: "all"`. Marker: `TN_PROJECTION`.
72
+ - **Projected-pixel cull** `#projected-cull`: under 0.5 px. Override: `minimumProjectedPixels`; `alwaysRender(obj)`. Marker: `TN_RENDER_PROJECTION`.
73
+ - **Physics interpolation** `#interpolation`: on for bodies and `ctx.camera`. Override: `physicsInterpolation: false`. Marker: `TN_PHYSICS_INTERPOLATION`.
74
+ - **Continuous collision** `#continuous`: on for `RigidBody3D`. Override: `continuousCollision: false`. Marker: `body.continuousCollision`.
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
+ - **Environment contribution** `#env-contribution`: reported even at zero. Override: `environmentSampling`. Marker: `TN_ENVIRONMENT_CONTRIBUTION`.
85
+ - **Pointer look** `#pointer-look`: captures the canvas on click. Override: `captureOnClick: false` + `ctx.input.captureMouse()`.
86
+ - **Static scenery** `#static`: unwritten transforms stay cheap. Override: `markStatic(root)`; `invalidateStatic(obj)`. Marker: `TN_RENDERLIST_VALIDATE`.
87
+ - **Frame spans** `#spans`: off. Override: `TN_FRAME_SPANS=1`. Marker: `TN_FRAME_SPANS`.
88
+ - **Multiplayer** `#net`: none; unsupported transport rejects. Override: `connect` from `@threenative/core/net` with four limits. Marker: `TN_NET_UNAVAILABLE`.
89
+ - **Desktop window** `#desktop-mode`: CLI, then `display.fullscreen`, then `window.maximized`. Override: `--windowed`; `--maximized`; `--fullscreen`.
90
+ - **Terrain** `#terrain`: authored in the game. Override: optional `@threenative/terrain`; `references/terrain-authoring.md`.
91
+ - **Navigation** `#navigation`: none; browser-only WASM. Override: import `@threenative/physics/navigation` on purpose.
92
+ - **Move input** `#move-axis`: `input.vector("move").y` is +up. Override: one explicit `-move.y` conversion.
93
+ - **Scene change** `#scene-change`: `ctx.goto(name)` keeps state. Override: `game.goto(name)` resets state.
94
+ - **Randomness** `#seed`: unseeded. Override: `defineGame({ seed })`.
95
+ - **Engine** `#engine`: owned C++ engine. Override: `engine: "threejs"` only when the user asks. Marker: `TN_NATIVE_ENGINE_UNBOUND`.
96
+ <!-- /shared -->
97
+
98
+ <!-- shared: kit-stuck -->
99
+ ## When the framework blocks you, write plain Three.js
83
100
 
84
- 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.
101
+ 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.
85
102
 
86
- 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`.
87
- ## Optional multiplayer transport
88
- 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`.
89
- Material backlighting lives in `src/render/lighting.ts`: named `rimGain` and `fillGain` controls preserve the authored palette; `materialLighting.ts` reports `TN_ENVIRONMENT_CONTRIBUTION`. Admission is limited to high hardware desktop WebGPU; mobile/software/WebGL/native retain original materials. Existing authored fill stays authoritative.
90
- `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`. Fog is height fog: `HEIGHT_FOG` in `src/render/heightFog.ts` (`density`, `heightFalloff`, `fogHeight`, `maxOpacity`, `startDistance`, `sunExponent`, `sunStartDistance`, `cutoffDistance`) is added to the `FogExp2` distance term on `scene.fogNode` and never replaces it, so a streaming fog `far` still holds.
103
+ ## Stuck
91
104
 
92
- Core supplies Unreal filmic and metered defaults through `WorldEnvironment` and `qualityPreset`. The filmic curve and metered auto exposure are on by default here. `quality.ts` names one cost override, reported as `TN_RENDER_CHAIN_COST_OVERRIDE`: no final gather, SSGI or SSR, no temporal AA or motion blur, no bloom and no local exposure, because the core gather took the performance scenario to 38.8 ms GPU p95 against 16.7 ms, the GPU-computed flakes carry no velocity for either temporal stage, bloom veils the white glade, and local exposure lifts the explorer's shadows and flattens it against the snow. `exposure.ts` keeps core's meter and sets its exposure compensation per weather (`EXPOSURE_BIAS`: +2 stops clear, none in the blizzard, blended on the eased storm level). `Snow.ts` passes `exposureBias(weather.storm)` to `setExposureBias` on the meter that `setupPost` returns each frame, so the snowfield meters white instead of middle grey and the uniform blizzard fog does not wash out. Set `tonemapMode: "aces"` or `autoExposureEnabled: false` with a fixed `exposure` on the same preset to override the curve or the meter.
105
+ `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.
106
+ <!-- /shared -->