create-threenative 0.2.17 → 0.2.18

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 (310) hide show
  1. package/agent-docs/kit-mcp.md +1 -1
  2. package/agent-docs/kit-router.md +1 -1
  3. package/agent-docs/references/assertion-reference.md +54 -110
  4. package/agent-docs/references/capability-reference.md +580 -22
  5. package/agent-docs/references/conventions.md +28 -0
  6. package/agent-docs/references/performance-basics.md +8 -4
  7. package/agent-files/.agents/skills/ponytail/SKILL.md +1 -1
  8. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +7 -4
  9. package/agent-files/.claude/hooks/discovery-gate.mjs +2 -2
  10. package/dist/index.d.ts +97 -6
  11. package/dist/index.js +769 -277
  12. package/dist/threenative.js +96 -17
  13. package/dist/web-engine-ccd-ik-solver.js +127 -0
  14. package/dist/web-engine-gltf-loader.js +52 -14
  15. package/dist/web-engine-post-effects.js +5 -10
  16. package/dist/web-engine-runtime.js +3648 -546
  17. package/package.json +8 -7
  18. package/template-assets/clearwater/README.md +1 -1
  19. package/template-assets/patches/manifest.json +18 -0
  20. package/template-assets/terrain/alpine/assets.json +12 -0
  21. package/template-assets/terrain/alpine/bake.mjs +6 -0
  22. package/template-assets/terrain/alpine/credits.json +164 -0
  23. package/template-assets/terrain/alpine/heightmap.r16 +0 -0
  24. package/template-assets/terrain/alpine/recipe.json +119 -0
  25. package/template-assets/terrain/alpine/surface.json +53 -0
  26. package/template-assets/terrain/coastal/assets.json +11 -0
  27. package/template-assets/terrain/coastal/bake.mjs +6 -0
  28. package/template-assets/terrain/coastal/credits.json +117 -0
  29. package/template-assets/terrain/coastal/heightmap.r16 +0 -0
  30. package/template-assets/terrain/coastal/recipe.json +113 -0
  31. package/template-assets/terrain/coastal/surface.json +41 -0
  32. package/template-assets/terrain/desert/assets.json +12 -0
  33. package/template-assets/terrain/desert/bake.mjs +6 -0
  34. package/template-assets/terrain/desert/credits.json +164 -0
  35. package/template-assets/terrain/desert/heightmap.r16 +0 -0
  36. package/template-assets/terrain/desert/recipe.json +108 -0
  37. package/template-assets/terrain/desert/surface.json +54 -0
  38. package/template-assets/terrain/forest/assets.json +65 -0
  39. package/template-assets/terrain/forest/bake.mjs +8 -0
  40. package/template-assets/terrain/forest/credits.json +225 -0
  41. package/template-assets/terrain/forest/heightmap.r16 +0 -0
  42. package/template-assets/terrain/forest/recipe.json +350 -0
  43. package/template-assets/terrain/forest/surface.json +79 -0
  44. package/template-assets/terrain/tundra/assets.json +12 -0
  45. package/template-assets/terrain/tundra/bake.mjs +6 -0
  46. package/template-assets/terrain/tundra/credits.json +164 -0
  47. package/template-assets/terrain/tundra/heightmap.r16 +0 -0
  48. package/template-assets/terrain/tundra/recipe.json +277 -0
  49. package/template-assets/terrain/tundra/surface.json +54 -0
  50. package/templates/action-rpg/AGENTS.md +8 -4
  51. package/templates/action-rpg/CLAUDE.md +8 -4
  52. package/templates/action-rpg/package.json +7 -7
  53. package/templates/action-rpg/src/game.ts +1 -1
  54. package/templates/action-rpg/src/render/atmosphere.ts +6 -0
  55. package/templates/action-rpg/src/render/backlightControls.ts +10 -0
  56. package/templates/action-rpg/src/render/backlightMaterial.ts +4 -4
  57. package/templates/action-rpg/src/render/clouds.ts +13 -0
  58. package/templates/action-rpg/src/render/materialLighting.ts +5 -5
  59. package/templates/action-rpg/src/render/quality.ts +7 -32
  60. package/templates/action-rpg/src/scenes/Play.ts +4 -1
  61. package/templates/action-rpg/src/style.css +4 -0
  62. package/templates/action-rpg/vite.config.ts +2 -0
  63. package/templates/adventure/AGENTS.md +7 -2
  64. package/templates/adventure/CLAUDE.md +7 -2
  65. package/templates/adventure/kit.json +5 -1
  66. package/templates/adventure/package.json +7 -7
  67. package/templates/adventure/src/game.ts +1 -1
  68. package/templates/adventure/src/style.css +4 -0
  69. package/templates/adventure/tsconfig.json +1 -1
  70. package/templates/adventure/vite.config.ts +2 -0
  71. package/templates/collectathon/AGENTS.md +7 -2
  72. package/templates/collectathon/CLAUDE.md +7 -2
  73. package/templates/collectathon/package.json +7 -7
  74. package/templates/collectathon/src/game.ts +1 -1
  75. package/templates/collectathon/src/level/Course.ts +55 -9
  76. package/templates/collectathon/src/level/terrain.ts +27 -6
  77. package/templates/collectathon/src/main.ts +1 -0
  78. package/templates/collectathon/src/render/foliage.ts +359 -98
  79. package/templates/collectathon/src/render/sky.ts +76 -12
  80. package/templates/collectathon/src/render/water.ts +32 -10
  81. package/templates/collectathon/src/scenes/Play.ts +18 -5
  82. package/templates/collectathon/src/style.css +4 -0
  83. package/templates/collectathon/tsconfig.json +1 -1
  84. package/templates/collectathon/vite.config.ts +2 -0
  85. package/templates/kart/AGENTS.md +7 -2
  86. package/templates/kart/CLAUDE.md +7 -2
  87. package/templates/kart/package.json +6 -6
  88. package/templates/kart/src/game.ts +1 -1
  89. package/templates/kart/src/main.ts +1 -0
  90. package/templates/kart/src/style.css +4 -0
  91. package/templates/kart/tsconfig.json +1 -1
  92. package/templates/kart/vite.config.ts +2 -0
  93. package/templates/minimal/AGENTS.md +8 -3
  94. package/templates/minimal/CLAUDE.md +8 -3
  95. package/templates/minimal/package.json +6 -6
  96. package/templates/minimal/playtests/stands-still.playtest.json +30 -0
  97. package/templates/minimal/src/game.ts +1 -1
  98. package/templates/minimal/src/render/atmosphere.ts +6 -0
  99. package/templates/minimal/src/render/backlightControls.ts +10 -0
  100. package/templates/minimal/src/render/backlightMaterial.ts +4 -4
  101. package/templates/minimal/src/render/camera.ts +13 -2
  102. package/templates/minimal/src/render/clouds.ts +13 -0
  103. package/templates/minimal/src/render/lighting.ts +4 -2
  104. package/templates/minimal/src/render/materialLighting.ts +5 -5
  105. package/templates/minimal/src/render/materials.ts +10 -0
  106. package/templates/minimal/src/render/quality.ts +7 -32
  107. package/templates/minimal/src/scenes/Play.ts +4 -1
  108. package/templates/minimal/vite.config.ts +7 -1
  109. package/templates/platformer/AGENTS.md +9 -4
  110. package/templates/platformer/CLAUDE.md +9 -4
  111. package/templates/platformer/index.html +1 -1
  112. package/templates/platformer/main.html +12 -0
  113. package/templates/platformer/package.json +7 -7
  114. package/templates/platformer/playtests/gamepad-idle.playtest.json +21 -0
  115. package/templates/platformer/playtests/gamepad.playtest.json +30 -0
  116. package/templates/platformer/src/entities/Fox.ts +21 -6
  117. package/templates/platformer/src/game.ts +1 -1
  118. package/templates/platformer/src/main.ts +1 -0
  119. package/templates/platformer/src/render/backlightControls.ts +10 -0
  120. package/templates/platformer/src/render/backlightMaterial.ts +4 -4
  121. package/templates/platformer/src/render/materialLighting.ts +5 -5
  122. package/templates/platformer/src/render/quality.ts +7 -32
  123. package/templates/platformer/src/scenes/Play.ts +2 -1
  124. package/templates/platformer/src/style.css +4 -0
  125. package/templates/platformer/src/worker-page.ts +29 -0
  126. package/templates/platformer/src/worker.ts +5 -0
  127. package/templates/platformer/tsconfig.json +1 -1
  128. package/templates/platformer/vite.config.ts +4 -0
  129. package/templates/puzzle/AGENTS.md +7 -2
  130. package/templates/puzzle/CLAUDE.md +7 -2
  131. package/templates/puzzle/package.json +7 -7
  132. package/templates/puzzle/src/game.ts +1 -1
  133. package/templates/puzzle/src/render/backlightControls.ts +10 -0
  134. package/templates/puzzle/src/render/backlightMaterial.ts +4 -4
  135. package/templates/puzzle/src/render/materialLighting.ts +5 -5
  136. package/templates/puzzle/src/render/quality.ts +7 -32
  137. package/templates/puzzle/src/scenes/Play.ts +1 -1
  138. package/templates/puzzle/src/style.css +4 -0
  139. package/templates/puzzle/tsconfig.json +1 -1
  140. package/templates/puzzle/vite.config.ts +2 -0
  141. package/templates/racing/AGENTS.md +7 -2
  142. package/templates/racing/CLAUDE.md +7 -2
  143. package/templates/racing/package.json +7 -7
  144. package/templates/racing/src/game.ts +1 -1
  145. package/templates/racing/src/render/atmosphere.ts +6 -0
  146. package/templates/racing/src/render/backlightControls.ts +10 -0
  147. package/templates/racing/src/render/backlightMaterial.ts +4 -4
  148. package/templates/racing/src/render/clouds.ts +13 -0
  149. package/templates/racing/src/render/materialLighting.ts +5 -5
  150. package/templates/racing/src/render/quality.ts +7 -32
  151. package/templates/racing/src/scenes/Race.ts +4 -1
  152. package/templates/racing/src/style.css +4 -0
  153. package/templates/racing/tsconfig.json +1 -1
  154. package/templates/racing/vite.config.ts +2 -0
  155. package/templates/rain/AGENTS.md +6 -2
  156. package/templates/rain/CLAUDE.md +6 -2
  157. package/templates/rain/package.json +6 -6
  158. package/templates/rain/src/game.ts +1 -1
  159. package/templates/rain/vite.config.ts +6 -0
  160. package/templates/rts/AGENTS.md +6 -2
  161. package/templates/rts/CLAUDE.md +6 -2
  162. package/templates/rts/package.json +6 -6
  163. package/templates/rts/src/game.ts +1 -1
  164. package/templates/rts/src/render/backlightControls.ts +10 -0
  165. package/templates/rts/src/render/backlightMaterial.ts +4 -4
  166. package/templates/rts/src/render/materialLighting.ts +5 -5
  167. package/templates/rts/src/render/quality.ts +7 -31
  168. package/templates/rts/src/scenes/Play.ts +1 -1
  169. package/templates/rts/src/style.css +4 -0
  170. package/templates/rts/vite.config.ts +2 -0
  171. package/templates/runner/AGENTS.md +7 -2
  172. package/templates/runner/CLAUDE.md +7 -2
  173. package/templates/runner/package.json +7 -7
  174. package/templates/runner/src/game.ts +1 -1
  175. package/templates/runner/src/render/atmosphere.ts +6 -0
  176. package/templates/runner/src/render/backlightControls.ts +10 -0
  177. package/templates/runner/src/render/backlightMaterial.ts +4 -4
  178. package/templates/runner/src/render/clouds.ts +13 -0
  179. package/templates/runner/src/render/materialLighting.ts +5 -5
  180. package/templates/runner/src/render/quality.ts +7 -32
  181. package/templates/runner/src/scenes/Run.ts +4 -1
  182. package/templates/runner/src/style.css +4 -0
  183. package/templates/runner/tsconfig.json +1 -1
  184. package/templates/runner/vite.config.ts +2 -0
  185. package/templates/sailing/AGENTS.md +7 -2
  186. package/templates/sailing/CLAUDE.md +7 -2
  187. package/templates/sailing/package.json +7 -7
  188. package/templates/sailing/src/game.ts +1 -1
  189. package/templates/sailing/src/render/backlightControls.ts +10 -0
  190. package/templates/sailing/src/render/backlightMaterial.ts +4 -4
  191. package/templates/sailing/src/render/environmentSetup.ts +1 -1
  192. package/templates/sailing/src/render/materialLighting.ts +5 -5
  193. package/templates/sailing/src/render/quality.ts +7 -32
  194. package/templates/sailing/src/style.css +5 -0
  195. package/templates/sailing/vite.config.ts +6 -0
  196. package/templates/shooter/AGENTS.md +6 -2
  197. package/templates/shooter/CLAUDE.md +6 -2
  198. package/templates/shooter/package.json +7 -7
  199. package/templates/shooter/src/game.ts +3 -2
  200. package/templates/shooter/src/render/atmosphere.ts +6 -0
  201. package/templates/shooter/src/render/backlightControls.ts +10 -0
  202. package/templates/shooter/src/render/backlightMaterial.ts +4 -4
  203. package/templates/shooter/src/render/clouds.ts +13 -0
  204. package/templates/shooter/src/render/materialLighting.ts +5 -5
  205. package/templates/shooter/src/render/quality.ts +7 -32
  206. package/templates/shooter/src/scenes/Play.ts +4 -1
  207. package/templates/shooter/src/style.css +4 -0
  208. package/templates/shooter/vite.config.ts +2 -0
  209. package/templates/snow/AGENTS.md +7 -2
  210. package/templates/snow/CLAUDE.md +7 -2
  211. package/templates/snow/package.json +7 -7
  212. package/templates/snow/src/game.ts +1 -1
  213. package/templates/snow/src/render/backlightControls.ts +10 -0
  214. package/templates/snow/src/render/backlightMaterial.ts +4 -4
  215. package/templates/snow/src/render/materialLighting.ts +5 -5
  216. package/templates/snow/src/render/quality.ts +7 -32
  217. package/templates/snow/src/style.css +5 -0
  218. package/templates/snow/vite.config.ts +6 -0
  219. package/templates/starter/AGENTS.md +8 -3
  220. package/templates/starter/CLAUDE.md +8 -3
  221. package/templates/starter/package.json +7 -7
  222. package/templates/starter/src/entities/Crate.ts +5 -2
  223. package/templates/starter/src/game.ts +4 -3
  224. package/templates/starter/src/render/adaptiveQuality.ts +17 -0
  225. package/templates/starter/src/render/atmosphere.ts +6 -0
  226. package/templates/starter/src/render/backlightControls.ts +10 -0
  227. package/templates/starter/src/render/backlightMaterial.ts +4 -4
  228. package/templates/starter/src/render/clouds.ts +13 -0
  229. package/templates/starter/src/render/contactShadow.ts +1 -1
  230. package/templates/starter/src/render/materialLighting.ts +5 -5
  231. package/templates/starter/src/render/postprocessing.ts +11 -10
  232. package/templates/starter/src/render/quality.ts +14 -1
  233. package/templates/starter/src/scenes/Play.ts +12 -3
  234. package/templates/starter/src/state.ts +2 -0
  235. package/templates/starter/src/style.css +4 -0
  236. package/templates/starter/src/ui/Menu.tsx +5 -1
  237. package/templates/starter/vite.config.ts +2 -0
  238. package/templates/tower-defense/AGENTS.md +7 -2
  239. package/templates/tower-defense/CLAUDE.md +7 -2
  240. package/templates/tower-defense/package.json +7 -7
  241. package/templates/tower-defense/src/game.ts +1 -1
  242. package/templates/tower-defense/src/render/backlightControls.ts +10 -0
  243. package/templates/tower-defense/src/render/backlightMaterial.ts +4 -4
  244. package/templates/tower-defense/src/render/materialLighting.ts +5 -5
  245. package/templates/tower-defense/src/render/quality.ts +7 -32
  246. package/templates/tower-defense/src/scenes/Battle.ts +1 -1
  247. package/templates/tower-defense/src/style.css +4 -0
  248. package/templates/tower-defense/tsconfig.json +1 -1
  249. package/templates/tower-defense/vite.config.ts +2 -0
  250. package/templates/action-rpg/src/render/environmentContribution.ts +0 -188
  251. package/templates/action-rpg/src/render/environmentRadiance.ts +0 -36
  252. package/templates/action-rpg/src/render/environmentSampleCache.ts +0 -43
  253. package/templates/action-rpg/src/render/environmentSampling.ts +0 -193
  254. package/templates/action-rpg/src/render/environmentSnapshot.ts +0 -53
  255. package/templates/minimal/src/render/environmentContribution.ts +0 -188
  256. package/templates/minimal/src/render/environmentRadiance.ts +0 -36
  257. package/templates/minimal/src/render/environmentSampleCache.ts +0 -43
  258. package/templates/minimal/src/render/environmentSampling.ts +0 -193
  259. package/templates/minimal/src/render/environmentSnapshot.ts +0 -53
  260. package/templates/platformer/src/render/environmentContribution.ts +0 -188
  261. package/templates/platformer/src/render/environmentRadiance.ts +0 -36
  262. package/templates/platformer/src/render/environmentSampleCache.ts +0 -43
  263. package/templates/platformer/src/render/environmentSampling.ts +0 -193
  264. package/templates/platformer/src/render/environmentSnapshot.ts +0 -53
  265. package/templates/puzzle/src/render/environmentContribution.ts +0 -188
  266. package/templates/puzzle/src/render/environmentRadiance.ts +0 -36
  267. package/templates/puzzle/src/render/environmentSampleCache.ts +0 -43
  268. package/templates/puzzle/src/render/environmentSampling.ts +0 -193
  269. package/templates/puzzle/src/render/environmentSnapshot.ts +0 -53
  270. package/templates/racing/src/render/environmentContribution.ts +0 -188
  271. package/templates/racing/src/render/environmentRadiance.ts +0 -36
  272. package/templates/racing/src/render/environmentSampleCache.ts +0 -43
  273. package/templates/racing/src/render/environmentSampling.ts +0 -193
  274. package/templates/racing/src/render/environmentSnapshot.ts +0 -53
  275. package/templates/rts/src/render/environmentContribution.ts +0 -188
  276. package/templates/rts/src/render/environmentRadiance.ts +0 -36
  277. package/templates/rts/src/render/environmentSampleCache.ts +0 -43
  278. package/templates/rts/src/render/environmentSampling.ts +0 -193
  279. package/templates/rts/src/render/environmentSnapshot.ts +0 -53
  280. package/templates/runner/src/render/environmentContribution.ts +0 -188
  281. package/templates/runner/src/render/environmentRadiance.ts +0 -36
  282. package/templates/runner/src/render/environmentSampleCache.ts +0 -43
  283. package/templates/runner/src/render/environmentSampling.ts +0 -193
  284. package/templates/runner/src/render/environmentSnapshot.ts +0 -53
  285. package/templates/sailing/src/render/environmentContribution.ts +0 -188
  286. package/templates/sailing/src/render/environmentRadiance.ts +0 -36
  287. package/templates/sailing/src/render/environmentSampleCache.ts +0 -43
  288. package/templates/sailing/src/render/environmentSampling.ts +0 -193
  289. package/templates/sailing/src/render/environmentSnapshot.ts +0 -53
  290. package/templates/shooter/src/render/environmentContribution.ts +0 -188
  291. package/templates/shooter/src/render/environmentRadiance.ts +0 -36
  292. package/templates/shooter/src/render/environmentSampleCache.ts +0 -43
  293. package/templates/shooter/src/render/environmentSampling.ts +0 -193
  294. package/templates/shooter/src/render/environmentSnapshot.ts +0 -53
  295. package/templates/snow/src/render/environmentContribution.ts +0 -188
  296. package/templates/snow/src/render/environmentRadiance.ts +0 -36
  297. package/templates/snow/src/render/environmentSampleCache.ts +0 -43
  298. package/templates/snow/src/render/environmentSampling.ts +0 -193
  299. package/templates/snow/src/render/environmentSnapshot.ts +0 -53
  300. package/templates/starter/src/render/environmentContribution.ts +0 -188
  301. package/templates/starter/src/render/environmentRadiance.ts +0 -36
  302. package/templates/starter/src/render/environmentSampleCache.ts +0 -43
  303. package/templates/starter/src/render/environmentSampling.ts +0 -193
  304. package/templates/starter/src/render/environmentSnapshot.ts +0 -53
  305. package/templates/starter/src/render/rendererGate.ts +0 -36
  306. package/templates/tower-defense/src/render/environmentContribution.ts +0 -188
  307. package/templates/tower-defense/src/render/environmentRadiance.ts +0 -36
  308. package/templates/tower-defense/src/render/environmentSampleCache.ts +0 -43
  309. package/templates/tower-defense/src/render/environmentSampling.ts +0 -193
  310. package/templates/tower-defense/src/render/environmentSnapshot.ts +0 -53
@@ -11,7 +11,7 @@ Detail for each step: `threenative-capabilities` skill. Do the steps in order. A
11
11
 
12
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
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/`.
14
+ 3. **Built-ins**: per mechanic, system or symptom, `engine_search_capabilities {situation, scope: "mechanic"}`; rows answer; `engine_capability_detail` only for omitted symbols. Constraints are binding. `verdict: "none"` means the game writes it in `src/`.
15
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
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
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.
@@ -30,7 +30,7 @@ A change to an existing game repeats steps 2-3 for that change, then steps 5-8.
30
30
  - `threenative-assets`: a texture, HDRI, sound or model. `asset_search_sources`, `asset_download_file`, `audio_search_assets`, `mesh_optimize`.
31
31
  - `threenative-sculpt`: a bespoke mesh or character from a reference image. `sculpt_plan`, `sculpt_spec_gate`, `sculpt_compare`, `sculpt_pass_gate`.
32
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`.
33
+ - `threenative-terrain`: any terrain, from words. `terrain_generate`.
34
34
  - `threenative-devtools`: after `npx @threenative/playtest trace` names no cause. `performance_start_trace`, `performance_analyze_insight`.
35
35
  <!-- /shared -->
36
36
 
@@ -55,6 +55,7 @@ pnpm test # typecheck, lint, format, then every playtest
55
55
  pnpm build --target desktop # also: web, android, ios
56
56
  pnpm test:native # native proof
57
57
  npx threenative doctor # build, import, device or blank-frame failure
58
+ npx threenative doctor --fix # refresh agent files
58
59
  ```
59
60
  <!-- /shared -->
60
61
 
@@ -64,6 +65,7 @@ npx threenative doctor # build, import, device or blank-frame failure
64
65
  Each is on by default with a named override. Detail: `node_modules/create-threenative/agent-docs/references/conventions.md#<id>`.
65
66
 
66
67
  - **Look** `#look`: filmic curve, metered auto exposure. Override: `tonemapMode: "aces"`; `autoExposureEnabled: false` + `exposure`. Marker: `TN_WORLD_ENVIRONMENT`.
68
+ - **Ambient occlusion** `#ao-indirect`: darkens indirect light only, not the sun. Override: `gtaoIndirectOnly: false`; `gtaoEnabled: false`. Marker: `TN_WORLD_ENVIRONMENT`.
67
69
  - **Quality tier (`src/render/quality.ts`)** `#quality`: GPU class picks `high`, `medium` or `low`. Override: `setupPost(..., { tier: "low" })`. Marker: `TN_QUALITY_TIER`.
68
70
  - **Resolution scale** `#resolution`: `"auto"`, 0.85 on mobile-low. Override: numeric `resolutionScale`. Marker: `TN_FRAME_BUDGET`.
69
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`.
@@ -87,12 +89,15 @@ Each is on by default with a named override. Detail: `node_modules/create-threen
87
89
  - **Frame spans** `#spans`: off. Override: `TN_FRAME_SPANS=1`. Marker: `TN_FRAME_SPANS`.
88
90
  - **Multiplayer** `#net`: none; unsupported transport rejects. Override: `connect` from `@threenative/core/net` with four limits. Marker: `TN_NET_UNAVAILABLE`.
89
91
  - **Desktop window** `#desktop-mode`: CLI, then `display.fullscreen`, then `window.maximized`. Override: `--windowed`; `--maximized`; `--fullscreen`.
92
+ - **CPU priority** `#cpu-priority`: game threads first. Override: `display.priority: "normal"`. Marker: `TN_PROCESS_PRIORITY`.
90
93
  - **Terrain** `#terrain`: authored in the game. Override: optional `@threenative/terrain`; `references/terrain-authoring.md`.
91
94
  - **Navigation** `#navigation`: none; browser-only WASM. Override: import `@threenative/physics/navigation` on purpose.
95
+ - **Controller** `#gamepad`: W3C standard mapping on every pad, radial dead zone `0.2`, and a button press or a decisive stick move claims which pad is read. Override: `gamepadDeadZone: 0` for raw axes. Marker: `TN_GAMEPAD`.
92
96
  - **Move input** `#move-axis`: `input.vector("move").y` is +up. Override: one explicit `-move.y` conversion.
93
97
  - **Scene change** `#scene-change`: `ctx.goto(name)` keeps state. Override: `game.goto(name)` resets state.
94
98
  - **Randomness** `#seed`: unseeded. Override: `defineGame({ seed })`.
95
99
  - **Engine** `#engine`: owned C++ engine. Override: `engine: "threejs"` only when the user asks. Marker: `TN_NATIVE_ENGINE_UNBOUND`.
100
+ - **Refused imports** `#engine-catalog`: refused `three` imports fail at their line. Override: `createEngineCatalogPlugin({ mode: "warn" })`. Marker: `TN_ENGINE_CATALOG`.
96
101
  <!-- /shared -->
97
102
 
98
103
  <!-- shared: kit-stuck -->
@@ -13,7 +13,7 @@ Detail for each step: `threenative-capabilities` skill. Do the steps in order. A
13
13
 
14
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
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/`.
16
+ 3. **Built-ins**: per mechanic, system or symptom, `engine_search_capabilities {situation, scope: "mechanic"}`; rows answer; `engine_capability_detail` only for omitted symbols. Constraints are binding. `verdict: "none"` means the game writes it in `src/`.
17
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
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
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.
@@ -32,7 +32,7 @@ A change to an existing game repeats steps 2-3 for that change, then steps 5-8.
32
32
  - `threenative-assets`: a texture, HDRI, sound or model. `asset_search_sources`, `asset_download_file`, `audio_search_assets`, `mesh_optimize`.
33
33
  - `threenative-sculpt`: a bespoke mesh or character from a reference image. `sculpt_plan`, `sculpt_spec_gate`, `sculpt_compare`, `sculpt_pass_gate`.
34
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`.
35
+ - `threenative-terrain`: any terrain, from words. `terrain_generate`.
36
36
  - `threenative-devtools`: after `npx @threenative/playtest trace` names no cause. `performance_start_trace`, `performance_analyze_insight`.
37
37
  <!-- /shared -->
38
38
 
@@ -57,6 +57,7 @@ pnpm test # typecheck, lint, format, then every playtest
57
57
  pnpm build --target desktop # also: web, android, ios
58
58
  pnpm test:native # native proof
59
59
  npx threenative doctor # build, import, device or blank-frame failure
60
+ npx threenative doctor --fix # refresh agent files
60
61
  ```
61
62
  <!-- /shared -->
62
63
 
@@ -66,6 +67,7 @@ npx threenative doctor # build, import, device or blank-frame failure
66
67
  Each is on by default with a named override. Detail: `node_modules/create-threenative/agent-docs/references/conventions.md#<id>`.
67
68
 
68
69
  - **Look** `#look`: filmic curve, metered auto exposure. Override: `tonemapMode: "aces"`; `autoExposureEnabled: false` + `exposure`. Marker: `TN_WORLD_ENVIRONMENT`.
70
+ - **Ambient occlusion** `#ao-indirect`: darkens indirect light only, not the sun. Override: `gtaoIndirectOnly: false`; `gtaoEnabled: false`. Marker: `TN_WORLD_ENVIRONMENT`.
69
71
  - **Quality tier (`src/render/quality.ts`)** `#quality`: GPU class picks `high`, `medium` or `low`. Override: `setupPost(..., { tier: "low" })`. Marker: `TN_QUALITY_TIER`.
70
72
  - **Resolution scale** `#resolution`: `"auto"`, 0.85 on mobile-low. Override: numeric `resolutionScale`. Marker: `TN_FRAME_BUDGET`.
71
73
  - **Budget real time for the look** `#frame-budget`: frame meter and scene verdict on. Override: `frameBudget: false`. Marker: `TN_FRAME_BUDGET`, `TN_SCENE_WARNING`.
@@ -89,12 +91,15 @@ Each is on by default with a named override. Detail: `node_modules/create-threen
89
91
  - **Frame spans** `#spans`: off. Override: `TN_FRAME_SPANS=1`. Marker: `TN_FRAME_SPANS`.
90
92
  - **Multiplayer** `#net`: none; unsupported transport rejects. Override: `connect` from `@threenative/core/net` with four limits. Marker: `TN_NET_UNAVAILABLE`.
91
93
  - **Desktop window** `#desktop-mode`: CLI, then `display.fullscreen`, then `window.maximized`. Override: `--windowed`; `--maximized`; `--fullscreen`.
94
+ - **CPU priority** `#cpu-priority`: game threads first. Override: `display.priority: "normal"`. Marker: `TN_PROCESS_PRIORITY`.
92
95
  - **Terrain** `#terrain`: authored in the game. Override: optional `@threenative/terrain`; `references/terrain-authoring.md`.
93
96
  - **Navigation** `#navigation`: none; browser-only WASM. Override: import `@threenative/physics/navigation` on purpose.
97
+ - **Controller** `#gamepad`: W3C standard mapping on every pad, radial dead zone `0.2`, and a button press or a decisive stick move claims which pad is read. Override: `gamepadDeadZone: 0` for raw axes. Marker: `TN_GAMEPAD`.
94
98
  - **Move input** `#move-axis`: `input.vector("move").y` is +up. Override: one explicit `-move.y` conversion.
95
99
  - **Scene change** `#scene-change`: `ctx.goto(name)` keeps state. Override: `game.goto(name)` resets state.
96
100
  - **Randomness** `#seed`: unseeded. Override: `defineGame({ seed })`.
97
101
  - **Engine** `#engine`: owned C++ engine. Override: `engine: "threejs"` only when the user asks. Marker: `TN_NATIVE_ENGINE_UNBOUND`.
102
+ - **Refused imports** `#engine-catalog`: refused `three` imports fail at their line. Override: `createEngineCatalogPlugin({ mode: "warn" })`. Marker: `TN_ENGINE_CATALOG`.
98
103
  <!-- /shared -->
99
104
 
100
105
  <!-- shared: kit-stuck -->
@@ -19,9 +19,9 @@
19
19
  "format:check": "biome format src"
20
20
  },
21
21
  "dependencies": {
22
- "@threenative/core": "0.3.12",
23
- "@threenative/physics": "0.3.12",
24
- "@threenative/ui": "0.3.12",
22
+ "@threenative/core": "0.3.13",
23
+ "@threenative/physics": "0.3.13",
24
+ "@threenative/ui": "0.3.13",
25
25
  "react": "19.2.0",
26
26
  "react-dom": "19.2.0",
27
27
  "react-reconciler": "0.33.0",
@@ -29,13 +29,13 @@
29
29
  },
30
30
  "devDependencies": {
31
31
  "@tailwindcss/vite": "4.3.3",
32
- "@threenative/assets": "0.3.13",
33
- "@threenative/playtest": "0.3.12",
32
+ "@threenative/assets": "0.3.14",
33
+ "@threenative/playtest": "0.3.13",
34
34
  "@types/react": "19.2.0",
35
35
  "@types/react-dom": "19.2.0",
36
36
  "@types/three": "0.187.0",
37
37
  "@vitejs/plugin-react": "6.0.5",
38
- "create-threenative": "0.2.17",
38
+ "create-threenative": "0.2.18",
39
39
  "esbuild": "0.27.0",
40
40
  "playwright": "1.62.1",
41
41
  "tailwindcss": "4.3.3",
@@ -46,7 +46,7 @@
46
46
  "eslint": "10.13.0"
47
47
  },
48
48
  "optionalDependencies": {
49
- "@threenative/runtime-native": "0.3.12"
49
+ "@threenative/runtime-native": "0.3.13"
50
50
  },
51
51
  "overrides": {
52
52
  "sharp": ">=0.35.4",
@@ -29,7 +29,7 @@ const game = defineGame<GameState, IPhysicsContext>({
29
29
  },
30
30
  plugins: [rapier({ gravity: { x: 0, y: -9.81, z: 0 } }), playtest()],
31
31
  display: config.display,
32
- render: config.renderer,
32
+ renderer: config.renderer,
33
33
  scenes: { boot: Boot, snow: Snow },
34
34
  seed: 2_024,
35
35
  start: "boot",
@@ -10,6 +10,11 @@ function finiteColor(color: Color) {
10
10
  color.b >= 0
11
11
  );
12
12
  }
13
+ /**
14
+ * Throws when a `IBacklightControls` is missing a light or names a non-finite gain.
15
+ *
16
+ * @situation fail loudly instead of drawing an unlit material when a backlight has no key light
17
+ */
13
18
  export function validateControls(controls: IBacklightControls) {
14
19
  if (
15
20
  !Number.isFinite(controls.rimGain) ||
@@ -30,6 +35,11 @@ export function validateControls(controls: IBacklightControls) {
30
35
  "Backlight controls require finite nonnegative gains, a direction and angular size in (0, 1.5].",
31
36
  );
32
37
  }
38
+ /**
39
+ * The light and camera a backlit material reads its key direction from.
40
+ *
41
+ * @situation point the backlight at the sun the scene actually has
42
+ */
33
43
  export function resolveKey(
34
44
  controls: IBacklightControls,
35
45
  direction: Vector3,
@@ -48,10 +48,10 @@ export interface IBacklightControls {
48
48
  const graphs = new WeakMap<IBacklightControls, ReturnType<typeof createGraph>>();
49
49
 
50
50
  /**
51
- * Preserve the upstream standard PBR/normal/skinning paths and original material emissive.
52
- * This is an additive artistic convention, not a physical subsurface model or IBL replacement.
53
- * Cache at the caller to preserve shared source-material relationships; dispose only conversions
54
- * it owns, never maps/source materials borrowed from a loaded model.
51
+ * The game's material, wrapped in a node twin that adds the backlit sheen it was given.
52
+ *
53
+ * @situation give a material a launcher's glow without editing its colour, texture or roughness
54
+ * @constraint every colour, gain and angular size is the caller's; this copies the game's material and adds light
55
55
  */
56
56
  export function backlightMaterial(source: MeshStandardMaterial, controls: IBacklightControls) {
57
57
  if (
@@ -1,16 +1,16 @@
1
- // Generated for you. Scene-owned material assignments; no engine appearance hooks.
2
- import type { Camera, DirectionalLight, Object3D, Scene, Texture } from "three";
3
- import type { IBacklightControls } from "./backlightMaterial.js";
4
1
  import {
5
2
  type IEnvironmentMeasurement,
6
3
  measureEnvironment,
7
4
  reportEnvironmentContribution,
8
- } from "./environmentContribution.js";
5
+ } from "@threenative/core/render/environment";
9
6
  import {
10
7
  type IEnvironmentSourceSnapshot,
11
8
  captureEnvironmentSnapshot,
12
9
  environmentSnapshotCurrent,
13
- } from "./environmentSnapshot.js";
10
+ } from "@threenative/core/render/environment";
11
+ // Generated for you. Scene-owned material assignments; no engine appearance hooks.
12
+ import type { Camera, DirectionalLight, Object3D, Scene, Texture } from "three";
13
+ import type { IBacklightControls } from "./backlightMaterial.js";
14
14
  import { type ILightingConvention, createLightingConvention } from "./lighting.js";
15
15
  import { createMaterialAssignments } from "./materialAssignments.js";
16
16
  import { type IMaterialLightingEnvironment, materialLightingEnabled } from "./quality.js";
@@ -34,7 +34,6 @@ import {
34
34
  } from "@threenative/core";
35
35
  import { exposureSettings } from "./exposure.js";
36
36
  export type { QualityTier } from "@threenative/core";
37
- import type { QualityTier } from "@threenative/core";
38
37
 
39
38
  /**
40
39
  * The three names this game's look comes in.
@@ -80,34 +79,10 @@ export function qualityPreset(tier: string): IWorldEnvironmentOptions {
80
79
  };
81
80
  }
82
81
 
83
- export interface IMaterialLightingEnvironment {
84
- readonly web: boolean;
85
- readonly rendererKind: string;
86
- readonly mobile?: boolean;
87
- readonly software?: boolean;
88
- readonly webglFallback?: boolean;
89
- }
90
- export function materialLightingEnabled(
91
- tier: QualityTier,
92
- environment: IMaterialLightingEnvironment,
93
- ): boolean {
94
- return (
95
- tier === "high" &&
96
- environment.web &&
97
- environment.rendererKind === "webgpu" &&
98
- environment.mobile !== true &&
99
- environment.software !== true &&
100
- environment.webglFallback !== true
101
- );
102
- }
103
-
104
- /** A WebGPURenderer wrapper may run an ordinary WebGL fallback backend. */
105
- export function isWebGLFallbackRenderer(renderer: unknown): boolean {
106
- if (renderer === null || typeof renderer !== "object") return false;
107
- const backend = Reflect.get(renderer, "backend");
108
- return (
109
- backend !== null &&
110
- typeof backend === "object" &&
111
- Reflect.get(backend, "isWebGLBackend") === true
112
- );
113
- }
82
+ // The material lane's admission rule and the WebGL-fallback probe are the engine's: twelve kits
83
+ // held a copy each, so a fix to one left eleven admitting what it refused.
84
+ export {
85
+ type IMaterialLightingEnvironment,
86
+ isWebGLFallbackRenderer,
87
+ materialLightingEnabled,
88
+ } from "@threenative/core/render/environment";
@@ -1,5 +1,10 @@
1
1
  @import "tailwindcss";
2
2
 
3
+ /* `src/render/` is shader and material source: a word in its comments ("blur", "filter",
4
+ "table") became a real utility rule, which is what made a clean HUD look like a native-css
5
+ profile failure. Tailwind scans what it is told to scan. */
6
+ @source not "./render";
7
+
3
8
  @theme {
4
9
  --font-sans: Inter, ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
5
10
  --color-ink: #0c1c28;
@@ -2,6 +2,7 @@ import tailwindcss from "@tailwindcss/vite";
2
2
  import { watchAssets } from "@threenative/assets";
3
3
  import react from "@vitejs/plugin-react";
4
4
  import {
5
+ createEngineCatalogPlugin,
5
6
  createEngineFreshnessPlugin,
6
7
  createWebBrandPlugin,
7
8
  webRuntimeDecoders,
@@ -10,6 +11,10 @@ import { defineConfig } from "vite";
10
11
  import type { Plugin } from "vite";
11
12
  import config from "./threenative.config.js";
12
13
 
14
+ /**
15
+ * Recompiles assets/ into public/ while the dev server runs, so editing a texture does not
16
+ * need a rebuild. Serve-only by declaration: builds compile through `threenative build`.
17
+ */
13
18
  function assetsWatchPlugin(): Plugin {
14
19
  return {
15
20
  name: "threenative-assets-watch",
@@ -32,6 +37,7 @@ export default defineConfig({
32
37
  plugins: [
33
38
  createEngineFreshnessPlugin(),
34
39
  createWebBrandPlugin(),
40
+ createEngineCatalogPlugin(),
35
41
  react(),
36
42
  tailwindcss(),
37
43
  assetsWatchPlugin(),
@@ -11,7 +11,7 @@ Detail for each step: `threenative-capabilities` skill. Do the steps in order. A
11
11
 
12
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
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/`.
14
+ 3. **Built-ins**: per mechanic, system or symptom, `engine_search_capabilities {situation, scope: "mechanic"}`; rows answer; `engine_capability_detail` only for omitted symbols. Constraints are binding. `verdict: "none"` means the game writes it in `src/`.
15
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
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
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.
@@ -30,7 +30,7 @@ A change to an existing game repeats steps 2-3 for that change, then steps 5-8.
30
30
  - `threenative-assets`: a texture, HDRI, sound or model. `asset_search_sources`, `asset_download_file`, `audio_search_assets`, `mesh_optimize`.
31
31
  - `threenative-sculpt`: a bespoke mesh or character from a reference image. `sculpt_plan`, `sculpt_spec_gate`, `sculpt_compare`, `sculpt_pass_gate`.
32
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`.
33
+ - `threenative-terrain`: any terrain, from words. `terrain_generate`.
34
34
  - `threenative-devtools`: after `npx @threenative/playtest trace` names no cause. `performance_start_trace`, `performance_analyze_insight`.
35
35
  <!-- /shared -->
36
36
 
@@ -43,7 +43,7 @@ Exposure policy: `src/render/exposure.ts` (`node_modules/create-threenative/agen
43
43
  Kit notes: `node_modules/create-threenative/agent-docs/references/kit-starter.md`.
44
44
  <!-- /shared -->
45
45
 
46
- The game boots into `Play`: a test arena (`src/render/arena.ts`) drawn as a grid, holding a pickup, a crate, a gap to jump and a spawn. `platform()` builds both ends of the course.
46
+ `Play`: a grid test arena (`src/render/arena.ts`) with a pickup, crate, jump gap and spawn; `platform()` builds both course ends.
47
47
  React mounts from `src/main.ts`; `src/game.ts` is portable. This repository owns gameplay and every visible choice in `src/render/`.
48
48
 
49
49
  <!-- shared: kit-commands -->
@@ -56,6 +56,7 @@ pnpm build --target desktop # also: web, android, ios
56
56
  pnpm studio # open the game in Studio
57
57
  pnpm test:native # native proof
58
58
  npx threenative doctor # build, import, device or blank-frame failure
59
+ npx threenative doctor --fix # refresh agent files
59
60
  ```
60
61
  <!-- /shared -->
61
62
 
@@ -65,6 +66,7 @@ npx threenative doctor # build, import, device or blank-frame failure
65
66
  Each is on by default with a named override. Detail: `node_modules/create-threenative/agent-docs/references/conventions.md#<id>`.
66
67
 
67
68
  - **Look** `#look`: filmic curve, metered auto exposure. Override: `tonemapMode: "aces"`; `autoExposureEnabled: false` + `exposure`. Marker: `TN_WORLD_ENVIRONMENT`.
69
+ - **Ambient occlusion** `#ao-indirect`: darkens indirect light only, not the sun. Override: `gtaoIndirectOnly: false`; `gtaoEnabled: false`. Marker: `TN_WORLD_ENVIRONMENT`.
68
70
  - **Quality tier (`src/render/quality.ts`)** `#quality`: GPU class picks `high`, `medium` or `low`. Override: `setupPost(..., { tier: "low" })`. Marker: `TN_QUALITY_TIER`.
69
71
  - **Resolution scale** `#resolution`: `"auto"`, 0.85 on mobile-low. Override: numeric `resolutionScale`. Marker: `TN_FRAME_BUDGET`.
70
72
  - **Budget real time for the look** `#frame-budget`: frame meter and scene verdict on. Override: `frameBudget: false`. Marker: `TN_FRAME_BUDGET`, `TN_SCENE_WARNING`.
@@ -92,12 +94,15 @@ Each is on by default with a named override. Detail: `node_modules/create-threen
92
94
  - **Frame spans** `#spans`: off. Override: `TN_FRAME_SPANS=1`. Marker: `TN_FRAME_SPANS`.
93
95
  - **Multiplayer** `#net`: none; unsupported transport rejects. Override: `connect` from `@threenative/core/net` with four limits. Marker: `TN_NET_UNAVAILABLE`.
94
96
  - **Desktop window** `#desktop-mode`: CLI, then `display.fullscreen`, then `window.maximized`. Override: `--windowed`; `--maximized`; `--fullscreen`.
97
+ - **CPU priority** `#cpu-priority`: game threads first. Override: `display.priority: "normal"`. Marker: `TN_PROCESS_PRIORITY`.
95
98
  - **Terrain** `#terrain`: authored in the game. Override: optional `@threenative/terrain`; `references/terrain-authoring.md`.
96
99
  - **Navigation** `#navigation`: none; browser-only WASM. Override: import `@threenative/physics/navigation` on purpose.
100
+ - **Controller** `#gamepad`: W3C standard mapping on every pad, radial dead zone `0.2`, and a button press or a decisive stick move claims which pad is read. Override: `gamepadDeadZone: 0` for raw axes. Marker: `TN_GAMEPAD`.
97
101
  - **Move input** `#move-axis`: `input.vector("move").y` is +up. Override: one explicit `-move.y` conversion.
98
102
  - **Scene change** `#scene-change`: `ctx.goto(name)` keeps state. Override: `game.goto(name)` resets state.
99
103
  - **Randomness** `#seed`: unseeded. Override: `defineGame({ seed })`.
100
104
  - **Engine** `#engine`: owned C++ engine. Override: `engine: "threejs"` only when the user asks. Marker: `TN_NATIVE_ENGINE_UNBOUND`.
105
+ - **Refused imports** `#engine-catalog`: refused `three` imports fail at their line. Override: `createEngineCatalogPlugin({ mode: "warn" })`. Marker: `TN_ENGINE_CATALOG`.
101
106
  <!-- /shared -->
102
107
 
103
108
  <!-- shared: kit-stuck -->
@@ -13,7 +13,7 @@ Detail for each step: `threenative-capabilities` skill. Do the steps in order. A
13
13
 
14
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
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/`.
16
+ 3. **Built-ins**: per mechanic, system or symptom, `engine_search_capabilities {situation, scope: "mechanic"}`; rows answer; `engine_capability_detail` only for omitted symbols. Constraints are binding. `verdict: "none"` means the game writes it in `src/`.
17
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
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
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.
@@ -32,7 +32,7 @@ A change to an existing game repeats steps 2-3 for that change, then steps 5-8.
32
32
  - `threenative-assets`: a texture, HDRI, sound or model. `asset_search_sources`, `asset_download_file`, `audio_search_assets`, `mesh_optimize`.
33
33
  - `threenative-sculpt`: a bespoke mesh or character from a reference image. `sculpt_plan`, `sculpt_spec_gate`, `sculpt_compare`, `sculpt_pass_gate`.
34
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`.
35
+ - `threenative-terrain`: any terrain, from words. `terrain_generate`.
36
36
  - `threenative-devtools`: after `npx @threenative/playtest trace` names no cause. `performance_start_trace`, `performance_analyze_insight`.
37
37
  <!-- /shared -->
38
38
 
@@ -45,7 +45,7 @@ Exposure policy: `src/render/exposure.ts` (`node_modules/create-threenative/agen
45
45
  Kit notes: `node_modules/create-threenative/agent-docs/references/kit-starter.md`.
46
46
  <!-- /shared -->
47
47
 
48
- The game boots into `Play`: a test arena (`src/render/arena.ts`) drawn as a grid, holding a pickup, a crate, a gap to jump and a spawn. `platform()` builds both ends of the course.
48
+ `Play`: a grid test arena (`src/render/arena.ts`) with a pickup, crate, jump gap and spawn; `platform()` builds both course ends.
49
49
  React mounts from `src/main.ts`; `src/game.ts` is portable. This repository owns gameplay and every visible choice in `src/render/`.
50
50
 
51
51
  <!-- shared: kit-commands -->
@@ -58,6 +58,7 @@ pnpm build --target desktop # also: web, android, ios
58
58
  pnpm studio # open the game in Studio
59
59
  pnpm test:native # native proof
60
60
  npx threenative doctor # build, import, device or blank-frame failure
61
+ npx threenative doctor --fix # refresh agent files
61
62
  ```
62
63
  <!-- /shared -->
63
64
 
@@ -67,6 +68,7 @@ npx threenative doctor # build, import, device or blank-frame failure
67
68
  Each is on by default with a named override. Detail: `node_modules/create-threenative/agent-docs/references/conventions.md#<id>`.
68
69
 
69
70
  - **Look** `#look`: filmic curve, metered auto exposure. Override: `tonemapMode: "aces"`; `autoExposureEnabled: false` + `exposure`. Marker: `TN_WORLD_ENVIRONMENT`.
71
+ - **Ambient occlusion** `#ao-indirect`: darkens indirect light only, not the sun. Override: `gtaoIndirectOnly: false`; `gtaoEnabled: false`. Marker: `TN_WORLD_ENVIRONMENT`.
70
72
  - **Quality tier (`src/render/quality.ts`)** `#quality`: GPU class picks `high`, `medium` or `low`. Override: `setupPost(..., { tier: "low" })`. Marker: `TN_QUALITY_TIER`.
71
73
  - **Resolution scale** `#resolution`: `"auto"`, 0.85 on mobile-low. Override: numeric `resolutionScale`. Marker: `TN_FRAME_BUDGET`.
72
74
  - **Budget real time for the look** `#frame-budget`: frame meter and scene verdict on. Override: `frameBudget: false`. Marker: `TN_FRAME_BUDGET`, `TN_SCENE_WARNING`.
@@ -94,12 +96,15 @@ Each is on by default with a named override. Detail: `node_modules/create-threen
94
96
  - **Frame spans** `#spans`: off. Override: `TN_FRAME_SPANS=1`. Marker: `TN_FRAME_SPANS`.
95
97
  - **Multiplayer** `#net`: none; unsupported transport rejects. Override: `connect` from `@threenative/core/net` with four limits. Marker: `TN_NET_UNAVAILABLE`.
96
98
  - **Desktop window** `#desktop-mode`: CLI, then `display.fullscreen`, then `window.maximized`. Override: `--windowed`; `--maximized`; `--fullscreen`.
99
+ - **CPU priority** `#cpu-priority`: game threads first. Override: `display.priority: "normal"`. Marker: `TN_PROCESS_PRIORITY`.
97
100
  - **Terrain** `#terrain`: authored in the game. Override: optional `@threenative/terrain`; `references/terrain-authoring.md`.
98
101
  - **Navigation** `#navigation`: none; browser-only WASM. Override: import `@threenative/physics/navigation` on purpose.
102
+ - **Controller** `#gamepad`: W3C standard mapping on every pad, radial dead zone `0.2`, and a button press or a decisive stick move claims which pad is read. Override: `gamepadDeadZone: 0` for raw axes. Marker: `TN_GAMEPAD`.
99
103
  - **Move input** `#move-axis`: `input.vector("move").y` is +up. Override: one explicit `-move.y` conversion.
100
104
  - **Scene change** `#scene-change`: `ctx.goto(name)` keeps state. Override: `game.goto(name)` resets state.
101
105
  - **Randomness** `#seed`: unseeded. Override: `defineGame({ seed })`.
102
106
  - **Engine** `#engine`: owned C++ engine. Override: `engine: "threejs"` only when the user asks. Marker: `TN_NATIVE_ENGINE_UNBOUND`.
107
+ - **Refused imports** `#engine-catalog`: refused `three` imports fail at their line. Override: `createEngineCatalogPlugin({ mode: "warn" })`. Marker: `TN_ENGINE_CATALOG`.
103
108
  <!-- /shared -->
104
109
 
105
110
  <!-- shared: kit-stuck -->
@@ -20,9 +20,9 @@
20
20
  "format:check": "biome format src"
21
21
  },
22
22
  "dependencies": {
23
- "@threenative/core": "0.3.12",
24
- "@threenative/physics": "0.3.12",
25
- "@threenative/ui": "0.3.12",
23
+ "@threenative/core": "0.3.13",
24
+ "@threenative/physics": "0.3.13",
25
+ "@threenative/ui": "0.3.13",
26
26
  "react": "19.2.0",
27
27
  "react-dom": "19.2.0",
28
28
  "react-reconciler": "0.33.0",
@@ -30,13 +30,13 @@
30
30
  },
31
31
  "devDependencies": {
32
32
  "@tailwindcss/vite": "4.3.3",
33
- "@threenative/assets": "0.3.13",
34
- "@threenative/playtest": "0.3.12",
33
+ "@threenative/assets": "0.3.14",
34
+ "@threenative/playtest": "0.3.13",
35
35
  "@types/react": "19.2.0",
36
36
  "@types/react-dom": "19.2.0",
37
37
  "@types/three": "0.187.0",
38
38
  "@vitejs/plugin-react": "6.0.5",
39
- "create-threenative": "0.2.17",
39
+ "create-threenative": "0.2.18",
40
40
  "esbuild": "0.27.0",
41
41
  "playwright": "1.62.1",
42
42
  "tailwindcss": "4.3.3",
@@ -47,7 +47,7 @@
47
47
  "eslint": "10.13.0"
48
48
  },
49
49
  "optionalDependencies": {
50
- "@threenative/runtime-native": "0.3.12"
50
+ "@threenative/runtime-native": "0.3.13"
51
51
  },
52
52
  "overrides": {
53
53
  "sharp": ">=0.35.4",
@@ -16,6 +16,9 @@ export class Crate {
16
16
  y: number,
17
17
  z: number,
18
18
  material: Material,
19
+ // On a tier with a sun shadow sharp enough to ground it, the blob is a second, blurred shadow
20
+ // beside the sun's; Play.ts draws it only on `low`, which has no ambient occlusion pass.
21
+ contactShadow: () => boolean = () => true,
19
22
  ) {
20
23
  this.mesh = new Mesh(roundedBox(1, 1, 1), material);
21
24
  this.mesh.position.set(x, y, z);
@@ -31,8 +34,8 @@ export class Crate {
31
34
  from.set(x, y, z);
32
35
  to.set(x, y - 6, z);
33
36
  const gap = ctx.physics.directSpaceState.intersectRay({ from, to })?.distance;
34
- this.#shadow.object.visible = gap !== undefined;
35
- if (gap === undefined) return;
37
+ this.#shadow.object.visible = gap !== undefined && contactShadow();
38
+ if (!this.#shadow.object.visible || gap === undefined) return;
36
39
  this.#shadow.object.position.set(x, y - gap + 0.03, z);
37
40
  this.#shadow.fade(Math.max(0, 1 - (gap - 0.5) / 1.5));
38
41
  });
@@ -19,17 +19,18 @@ const game = defineGame<GameState, IPhysicsContext>({
19
19
  right: ["ArrowRight", "KeyD"],
20
20
  up: ["ArrowUp", "KeyW"],
21
21
  },
22
- run: { keys: ["ShiftLeft", "ShiftRight"] },
22
+ // Pad buttons use the W3C standard numbers: 0 is ✕ on a DualShock, 7 is R2, 9 is OPTIONS.
23
+ run: { buttons: [7], keys: ["ShiftLeft", "ShiftRight"] },
23
24
  jump: { buttons: [0], keys: ["Space"] },
24
25
  flagGust: { keys: ["KeyG"] },
25
- restart: { keys: ["KeyR"] },
26
+ restart: { buttons: [9], keys: ["KeyR"] },
26
27
  // Wheel, pinch and the right stick share one portable camera intent. Negative DOM deltaY
27
28
  // (toward-user) is positive scroll intent on browser and native; the scene owns the framing.
28
29
  zoom: { gamepadAxes: [3], pinch: true, scroll: true },
29
30
  },
30
31
  plugins: [rapier(), replay(), playtest()],
31
32
  display: config.display,
32
- render: config.renderer,
33
+ renderer: config.renderer,
33
34
  scenes: { play: Play },
34
35
  seed: 90210,
35
36
  start: "play",
@@ -66,6 +66,11 @@ export function createAdaptiveQuality(
66
66
  let lastChange = Number.NEGATIVE_INFINITY;
67
67
  let overloaded = 0;
68
68
  let healthy = 0;
69
+ // What a raise that failed cost, as a ratio of the cost before it, by the tier it fell back to. A raise from that
70
+ // tier waits until the predicted cost fits: retrying on headroom alone switched medium's shadows on and off every
71
+ // few seconds where low fits only without them (PRD-871).
72
+ const raiseCost = new Map<QualityTier, number>();
73
+ let raisedFrom: { tier: QualityTier; costMs: number } | undefined;
69
74
  const finite = (value: number | undefined): value is number =>
70
75
  value !== undefined && Number.isFinite(value);
71
76
  return {
@@ -156,6 +161,15 @@ export function createAdaptiveQuality(
156
161
  if (direction === 0) return report("steady");
157
162
  const next = QUALITY_TIERS[QUALITY_TIERS.indexOf(tier) + direction];
158
163
  if (next === undefined) return report(direction < 0 ? "at-floor" : "at-ceiling");
164
+ const ratio = raiseCost.get(tier);
165
+ if (
166
+ direction > 0 &&
167
+ ratio !== undefined &&
168
+ costMs * ratio > budgetMs * (1 - policy.headroom)
169
+ ) {
170
+ healthy = 0;
171
+ return report("predicted");
172
+ }
159
173
  const time = now();
160
174
  if (!Number.isFinite(time)) throw new Error("quality clock must return finite milliseconds.");
161
175
  if (time - lastChange < policy.cooldownMs) {
@@ -163,6 +177,9 @@ export function createAdaptiveQuality(
163
177
  healthy = 0;
164
178
  return report("cooldown");
165
179
  }
180
+ if (direction < 0 && raisedFrom?.tier === next)
181
+ raiseCost.set(next, costMs / raisedFrom.costMs);
182
+ raisedFrom = direction > 0 ? { tier, costMs } : undefined;
166
183
  tier = next;
167
184
  lastChange = time;
168
185
  overloaded = 0;
@@ -235,7 +235,13 @@ function march(
235
235
  * approximation in RenderMultiScatteredLuminanceLutCS); the full sphere gather overestimated the
236
236
  * ground bounce against the Unreal frames by up to 1.6x, so this uses the same two rays.
237
237
  */
238
+ // The table depends on no input: build it once a run, not once a sky refresh.
239
+ let multipleScattering: Multi | undefined;
238
240
  function multipleScatteringTable(): Multi {
241
+ multipleScattering ??= buildMultipleScatteringTable();
242
+ return multipleScattering;
243
+ }
244
+ function buildMultipleScatteringTable(): Multi {
239
245
  const nh = 12;
240
246
  const nc = 16;
241
247
  const dirs: Vec3[] = [
@@ -10,6 +10,11 @@ function finiteColor(color: Color) {
10
10
  color.b >= 0
11
11
  );
12
12
  }
13
+ /**
14
+ * Throws when a `IBacklightControls` is missing a light or names a non-finite gain.
15
+ *
16
+ * @situation fail loudly instead of drawing an unlit material when a backlight has no key light
17
+ */
13
18
  export function validateControls(controls: IBacklightControls) {
14
19
  if (
15
20
  !Number.isFinite(controls.rimGain) ||
@@ -30,6 +35,11 @@ export function validateControls(controls: IBacklightControls) {
30
35
  "Backlight controls require finite nonnegative gains, a direction and angular size in (0, 1.5].",
31
36
  );
32
37
  }
38
+ /**
39
+ * The light and camera a backlit material reads its key direction from.
40
+ *
41
+ * @situation point the backlight at the sun the scene actually has
42
+ */
33
43
  export function resolveKey(
34
44
  controls: IBacklightControls,
35
45
  direction: Vector3,
@@ -48,10 +48,10 @@ export interface IBacklightControls {
48
48
  const graphs = new WeakMap<IBacklightControls, ReturnType<typeof createGraph>>();
49
49
 
50
50
  /**
51
- * Preserve the upstream standard PBR/normal/skinning paths and original material emissive.
52
- * This is an additive artistic convention, not a physical subsurface model or IBL replacement.
53
- * Cache at the caller to preserve shared source-material relationships; dispose only conversions
54
- * it owns, never maps/source materials borrowed from a loaded model.
51
+ * The game's material, wrapped in a node twin that adds the backlit sheen it was given.
52
+ *
53
+ * @situation give a material a launcher's glow without editing its colour, texture or roughness
54
+ * @constraint every colour, gain and angular size is the caller's; this copies the game's material and adds light
55
55
  */
56
56
  export function backlightMaterial(source: MeshStandardMaterial, controls: IBacklightControls) {
57
57
  if (
@@ -282,6 +282,19 @@ export interface ICloudTextures {
282
282
  }
283
283
  const textureCache = new Map<number, ICloudTextures>();
284
284
 
285
+ /**
286
+ * Hand back the textures an earlier run generated, so `cloudTextures(seed)` skips ~0.6 s of noise
287
+ * on the main thread. The scene keeps them between runs with `ctx.assets.memo`.
288
+ */
289
+ export function primeCloudTextures(textures: ICloudTextures, seed = 631): void {
290
+ if (
291
+ textures.pattern.length !== PATTERN_SIZE ** 2 * 4 ||
292
+ textures.volume.length !== VOLUME_SIZE ** 3 * 2
293
+ )
294
+ throw new Error("cloud textures do not match PATTERN_SIZE and VOLUME_SIZE.");
295
+ textureCache.set(seed, textures);
296
+ }
297
+
285
298
  export function cloudTextures(seed = 631): ICloudTextures {
286
299
  const cached = textureCache.get(seed);
287
300
  if (cached) return cached;