create-threenative 0.2.17 → 0.2.20

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 (387) 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 +790 -24
  5. package/agent-docs/references/conventions.md +28 -0
  6. package/agent-docs/references/kit-racing.md +4 -2
  7. package/agent-docs/references/performance-basics.md +10 -5
  8. package/agent-docs/references/terrain-authoring.md +21 -7
  9. package/agent-files/.agents/skills/ponytail/SKILL.md +1 -1
  10. package/agent-files/.agents/skills/prd-creator/SKILL.md +24 -0
  11. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +7 -4
  12. package/agent-files/.claude/hooks/discovery-gate.mjs +2 -2
  13. package/dist/index.d.ts +97 -6
  14. package/dist/index.js +1040 -529
  15. package/dist/quality.d.ts +5 -1
  16. package/dist/quality.js +75 -6
  17. package/dist/terrain-kit.js +1 -1
  18. package/dist/threenative.js +98 -17
  19. package/dist/web-engine-ccd-ik-solver.js +127 -0
  20. package/dist/web-engine-gltf-loader.js +52 -14
  21. package/dist/web-engine-post-effects.js +11 -10
  22. package/dist/web-engine-runtime.js +3638 -361
  23. package/package.json +8 -7
  24. package/template-assets/assets/floor-fern-0.glb +0 -0
  25. package/template-assets/assets/floor-litter-0.glb +0 -0
  26. package/template-assets/assets/floor-log-0.glb +0 -0
  27. package/template-assets/assets/floor-log-1.glb +0 -0
  28. package/template-assets/assets/floor-stump-0.glb +0 -0
  29. package/template-assets/assets/floor-twig-0.glb +0 -0
  30. package/template-assets/clearwater/README.md +1 -1
  31. package/template-assets/patches/manifest.json +18 -0
  32. package/template-assets/quality/eslint.config.js +1 -1
  33. package/templates/action-rpg/AGENTS.md +8 -4
  34. package/templates/action-rpg/CLAUDE.md +8 -4
  35. package/templates/action-rpg/package.json +7 -7
  36. package/templates/action-rpg/src/game.ts +1 -1
  37. package/templates/action-rpg/src/loot/drops.ts +3 -7
  38. package/templates/action-rpg/src/render/atmosphere.ts +6 -0
  39. package/templates/action-rpg/src/render/backlightControls.ts +10 -0
  40. package/templates/action-rpg/src/render/backlightMaterial.ts +4 -4
  41. package/templates/action-rpg/src/render/camera.ts +2 -2
  42. package/templates/action-rpg/src/render/clouds.ts +16 -1
  43. package/templates/action-rpg/src/render/materialLighting.ts +5 -5
  44. package/templates/action-rpg/src/render/materials.ts +3 -2
  45. package/templates/action-rpg/src/render/quality.ts +7 -32
  46. package/templates/action-rpg/src/render/touch-controls.ts +7 -6
  47. package/templates/action-rpg/src/scenes/Play.ts +5 -16
  48. package/templates/action-rpg/src/style.css +4 -0
  49. package/templates/action-rpg/vite.config.ts +2 -0
  50. package/templates/adventure/AGENTS.md +10 -5
  51. package/templates/adventure/CLAUDE.md +10 -5
  52. package/templates/adventure/kit.json +5 -1
  53. package/templates/adventure/native-playtests/survives.playtest.json +12 -0
  54. package/templates/adventure/native-playtests/woodland-floor.playtest.json +61 -0
  55. package/templates/adventure/package.json +7 -7
  56. package/templates/adventure/playtests/grass.playtest.json +61 -0
  57. package/templates/adventure/playtests/performance.playtest.json +1 -1
  58. package/templates/adventure/playtests/survives.playtest.json +2 -2
  59. package/templates/adventure/playtests/woodland-floor.playtest.json +61 -0
  60. package/templates/adventure/src/entities/LockOn.ts +42 -4
  61. package/templates/adventure/src/entities/Warden.ts +4 -1
  62. package/templates/adventure/src/game.ts +1 -1
  63. package/templates/adventure/src/level/Vale.ts +241 -16
  64. package/templates/adventure/src/render/camera.ts +2 -2
  65. package/templates/adventure/src/render/foliage.ts +64 -20
  66. package/templates/adventure/src/render/grass.ts +325 -0
  67. package/templates/adventure/src/render/materials.ts +3 -2
  68. package/templates/adventure/src/render/palette.ts +3 -0
  69. package/templates/adventure/src/render/touch-controls.ts +4 -1
  70. package/templates/adventure/src/scenes/Play.ts +96 -1
  71. package/templates/adventure/src/style.css +4 -0
  72. package/templates/adventure/tsconfig.json +1 -1
  73. package/templates/adventure/vite.config.ts +2 -0
  74. package/templates/collectathon/AGENTS.md +7 -2
  75. package/templates/collectathon/CLAUDE.md +7 -2
  76. package/templates/collectathon/package.json +7 -7
  77. package/templates/collectathon/src/game.ts +1 -1
  78. package/templates/collectathon/src/level/Course.ts +55 -14
  79. package/templates/collectathon/src/level/terrain.ts +29 -7
  80. package/templates/collectathon/src/main.ts +1 -0
  81. package/templates/collectathon/src/render/camera.ts +2 -2
  82. package/templates/collectathon/src/render/foliage.ts +359 -98
  83. package/templates/collectathon/src/render/ground.ts +4 -4
  84. package/templates/collectathon/src/render/hero.ts +1 -1
  85. package/templates/collectathon/src/render/materials.ts +0 -1
  86. package/templates/collectathon/src/render/sky.ts +80 -15
  87. package/templates/collectathon/src/render/water.ts +32 -10
  88. package/templates/collectathon/src/scenes/Play.ts +18 -5
  89. package/templates/collectathon/src/style.css +4 -0
  90. package/templates/collectathon/tsconfig.json +1 -1
  91. package/templates/collectathon/vite.config.ts +2 -0
  92. package/templates/kart/AGENTS.md +7 -2
  93. package/templates/kart/CLAUDE.md +7 -2
  94. package/templates/kart/package.json +6 -6
  95. package/templates/kart/src/entities/Kart.ts +2 -1
  96. package/templates/kart/src/game.ts +1 -1
  97. package/templates/kart/src/main.ts +1 -0
  98. package/templates/kart/src/render/course.ts +2 -1
  99. package/templates/kart/src/style.css +4 -0
  100. package/templates/kart/src/track/Course.ts +3 -1
  101. package/templates/kart/tsconfig.json +1 -1
  102. package/templates/kart/vite.config.ts +2 -0
  103. package/templates/minimal/AGENTS.md +8 -3
  104. package/templates/minimal/CLAUDE.md +8 -3
  105. package/templates/minimal/package.json +6 -6
  106. package/templates/minimal/playtests/stands-still.playtest.json +30 -0
  107. package/templates/minimal/src/game.ts +1 -1
  108. package/templates/minimal/src/render/atmosphere.ts +6 -0
  109. package/templates/minimal/src/render/backlightControls.ts +10 -0
  110. package/templates/minimal/src/render/backlightMaterial.ts +4 -4
  111. package/templates/minimal/src/render/camera.ts +14 -3
  112. package/templates/minimal/src/render/clouds.ts +16 -1
  113. package/templates/minimal/src/render/lighting.ts +4 -2
  114. package/templates/minimal/src/render/materialLighting.ts +5 -5
  115. package/templates/minimal/src/render/materials.ts +13 -2
  116. package/templates/minimal/src/render/quality.ts +7 -32
  117. package/templates/minimal/src/render/touch-controls.ts +7 -6
  118. package/templates/minimal/src/scenes/Play.ts +4 -1
  119. package/templates/minimal/vite.config.ts +7 -1
  120. package/templates/platformer/AGENTS.md +9 -4
  121. package/templates/platformer/CLAUDE.md +9 -4
  122. package/templates/platformer/index.html +1 -1
  123. package/templates/platformer/main.html +12 -0
  124. package/templates/platformer/package.json +7 -7
  125. package/templates/platformer/playtests/collect.playtest.json +4 -1
  126. package/templates/platformer/playtests/gamepad-idle.playtest.json +21 -0
  127. package/templates/platformer/playtests/gamepad.playtest.json +30 -0
  128. package/templates/platformer/src/entities/Fox.ts +21 -6
  129. package/templates/platformer/src/game.ts +1 -1
  130. package/templates/platformer/src/level/Stage.ts +2 -6
  131. package/templates/platformer/src/main.ts +1 -0
  132. package/templates/platformer/src/render/backlightControls.ts +10 -0
  133. package/templates/platformer/src/render/backlightMaterial.ts +4 -4
  134. package/templates/platformer/src/render/materialLighting.ts +5 -5
  135. package/templates/platformer/src/render/quality.ts +7 -32
  136. package/templates/platformer/src/scenes/Play.ts +4 -2
  137. package/templates/platformer/src/style.css +4 -0
  138. package/templates/platformer/src/worker-page.ts +29 -0
  139. package/templates/platformer/src/worker.ts +5 -0
  140. package/templates/platformer/tsconfig.json +1 -1
  141. package/templates/platformer/vite.config.ts +4 -0
  142. package/templates/puzzle/AGENTS.md +7 -2
  143. package/templates/puzzle/CLAUDE.md +7 -2
  144. package/templates/puzzle/package.json +7 -7
  145. package/templates/puzzle/src/entities/Warden.ts +3 -3
  146. package/templates/puzzle/src/game.ts +1 -1
  147. package/templates/puzzle/src/render/backlightControls.ts +10 -0
  148. package/templates/puzzle/src/render/backlightMaterial.ts +4 -4
  149. package/templates/puzzle/src/render/camera.ts +2 -2
  150. package/templates/puzzle/src/render/materialLighting.ts +5 -5
  151. package/templates/puzzle/src/render/quality.ts +7 -32
  152. package/templates/puzzle/src/render/touch-controls.ts +7 -6
  153. package/templates/puzzle/src/scenes/Play.ts +1 -1
  154. package/templates/puzzle/src/style.css +4 -0
  155. package/templates/puzzle/tsconfig.json +1 -1
  156. package/templates/puzzle/vite.config.ts +2 -0
  157. package/templates/racing/AGENTS.md +9 -4
  158. package/templates/racing/CLAUDE.md +9 -4
  159. package/templates/racing/CREDITS.md +29 -0
  160. package/templates/racing/assets/engine-loop.wav +0 -0
  161. package/templates/racing/assets/grass/Grass004_color.jpg +0 -0
  162. package/templates/racing/assets/grass/Grass004_normal.jpg +0 -0
  163. package/templates/racing/assets/grass/Grass004_roughness.jpg +0 -0
  164. package/templates/racing/assets/nitro-burst.wav +0 -0
  165. package/templates/racing/assets/tyre-squeal.wav +0 -0
  166. package/templates/racing/package.json +7 -7
  167. package/templates/racing/playtests/drift-natural.playtest.json +68 -0
  168. package/templates/racing/playtests/drift.playtest.json +100 -0
  169. package/templates/racing/playtests/hud.playtest.json +117 -0
  170. package/templates/racing/playtests/launch-pose.playtest.json +34 -0
  171. package/templates/racing/playtests/nitro.playtest.json +158 -0
  172. package/templates/racing/playtests/outcome.playtest.json +4 -4
  173. package/templates/racing/playtests/performance.playtest.json +1 -1
  174. package/templates/racing/playtests/steady-camera.playtest.json +88 -0
  175. package/templates/racing/src/audio/engine.ts +138 -0
  176. package/templates/racing/src/entities/CarBody.ts +83 -10
  177. package/templates/racing/src/entities/Drift.ts +243 -0
  178. package/templates/racing/src/entities/LineDriver.ts +2 -2
  179. package/templates/racing/src/entities/Nitro.ts +72 -0
  180. package/templates/racing/src/entities/RacingCar.ts +86 -21
  181. package/templates/racing/src/entities/Rival.ts +35 -21
  182. package/templates/racing/src/game.ts +7 -1
  183. package/templates/racing/src/gauges.ts +74 -0
  184. package/templates/racing/src/render/atmosphere.ts +6 -0
  185. package/templates/racing/src/render/backlightControls.ts +10 -0
  186. package/templates/racing/src/render/backlightMaterial.ts +4 -4
  187. package/templates/racing/src/render/camera.ts +29 -4
  188. package/templates/racing/src/render/clouds.ts +16 -1
  189. package/templates/racing/src/render/effects.ts +244 -0
  190. package/templates/racing/src/render/materialLighting.ts +5 -5
  191. package/templates/racing/src/render/materials.ts +43 -8
  192. package/templates/racing/src/render/quality.ts +7 -32
  193. package/templates/racing/src/render/shapes.ts +37 -0
  194. package/templates/racing/src/render/skids.ts +84 -0
  195. package/templates/racing/src/render/touch-controls.ts +10 -10
  196. package/templates/racing/src/scenes/Race.ts +281 -26
  197. package/templates/racing/src/state.ts +35 -0
  198. package/templates/racing/src/style.css +7 -0
  199. package/templates/racing/src/track/Track.ts +132 -58
  200. package/templates/racing/src/track/TrackSector.ts +19 -1
  201. package/templates/racing/src/track/circuit.ts +21 -15
  202. package/templates/racing/src/ui/GameUi.tsx +0 -2
  203. package/templates/racing/src/ui/Hud.tsx +417 -50
  204. package/templates/racing/threenative.config.ts +15 -0
  205. package/templates/racing/tools/make-racing-audio.mjs +388 -0
  206. package/templates/racing/tsconfig.json +1 -1
  207. package/templates/racing/vite.config.ts +2 -0
  208. package/templates/rain/AGENTS.md +6 -2
  209. package/templates/rain/CLAUDE.md +6 -2
  210. package/templates/rain/package.json +6 -6
  211. package/templates/rain/src/game.ts +1 -1
  212. package/templates/rain/src/render/noise-volume.ts +2 -1
  213. package/templates/rain/src/state.ts +3 -1
  214. package/templates/rain/src/ui/GameUi.tsx +1 -1
  215. package/templates/rain/src/ui/automation.ts +10 -8
  216. package/templates/rain/src/ui/tempest.ts +3 -4
  217. package/templates/rain/vite.config.ts +6 -0
  218. package/templates/rts/AGENTS.md +6 -2
  219. package/templates/rts/CLAUDE.md +6 -2
  220. package/templates/rts/package.json +6 -6
  221. package/templates/rts/src/game.ts +1 -1
  222. package/templates/rts/src/render/backlightControls.ts +10 -0
  223. package/templates/rts/src/render/backlightMaterial.ts +4 -4
  224. package/templates/rts/src/render/materialLighting.ts +5 -5
  225. package/templates/rts/src/render/quality.ts +7 -31
  226. package/templates/rts/src/scenes/Play.ts +1 -1
  227. package/templates/rts/src/sim/terrain.ts +1 -0
  228. package/templates/rts/src/sim/types.ts +1 -0
  229. package/templates/rts/src/style.css +4 -0
  230. package/templates/rts/vite.config.ts +2 -0
  231. package/templates/runner/AGENTS.md +7 -2
  232. package/templates/runner/CLAUDE.md +7 -2
  233. package/templates/runner/package.json +7 -7
  234. package/templates/runner/src/game.ts +1 -1
  235. package/templates/runner/src/render/atmosphere.ts +6 -0
  236. package/templates/runner/src/render/backlightControls.ts +10 -0
  237. package/templates/runner/src/render/backlightMaterial.ts +4 -4
  238. package/templates/runner/src/render/clouds.ts +16 -1
  239. package/templates/runner/src/render/materialLighting.ts +5 -5
  240. package/templates/runner/src/render/materials.ts +3 -2
  241. package/templates/runner/src/render/quality.ts +7 -32
  242. package/templates/runner/src/render/touch-controls.ts +7 -6
  243. package/templates/runner/src/scenes/Run.ts +8 -10
  244. package/templates/runner/src/style.css +4 -0
  245. package/templates/runner/tsconfig.json +1 -1
  246. package/templates/runner/vite.config.ts +2 -0
  247. package/templates/sailing/AGENTS.md +7 -2
  248. package/templates/sailing/CLAUDE.md +7 -2
  249. package/templates/sailing/package.json +7 -7
  250. package/templates/sailing/src/game.ts +1 -1
  251. package/templates/sailing/src/render/backlightControls.ts +10 -0
  252. package/templates/sailing/src/render/backlightMaterial.ts +4 -4
  253. package/templates/sailing/src/render/environmentSetup.ts +1 -1
  254. package/templates/sailing/src/render/materialLighting.ts +5 -5
  255. package/templates/sailing/src/render/quality.ts +7 -32
  256. package/templates/sailing/src/render/touch-controls.ts +7 -6
  257. package/templates/sailing/src/style.css +5 -0
  258. package/templates/sailing/vite.config.ts +6 -0
  259. package/templates/shooter/AGENTS.md +6 -2
  260. package/templates/shooter/CLAUDE.md +6 -2
  261. package/templates/shooter/package.json +7 -7
  262. package/templates/shooter/src/game.ts +3 -2
  263. package/templates/shooter/src/render/atmosphere.ts +6 -0
  264. package/templates/shooter/src/render/backlightControls.ts +10 -0
  265. package/templates/shooter/src/render/backlightMaterial.ts +4 -4
  266. package/templates/shooter/src/render/clouds.ts +16 -1
  267. package/templates/shooter/src/render/materialLighting.ts +5 -5
  268. package/templates/shooter/src/render/quality.ts +7 -32
  269. package/templates/shooter/src/scenes/Play.ts +4 -1
  270. package/templates/shooter/src/style.css +4 -0
  271. package/templates/shooter/vite.config.ts +2 -0
  272. package/templates/snow/AGENTS.md +7 -2
  273. package/templates/snow/CLAUDE.md +7 -2
  274. package/templates/snow/package.json +7 -7
  275. package/templates/snow/src/entities/Explorer.ts +6 -12
  276. package/templates/snow/src/game.ts +1 -1
  277. package/templates/snow/src/render/backlightControls.ts +10 -0
  278. package/templates/snow/src/render/backlightMaterial.ts +4 -4
  279. package/templates/snow/src/render/bootPrint.ts +3 -1
  280. package/templates/snow/src/render/camera.ts +3 -2
  281. package/templates/snow/src/render/materialLighting.ts +5 -5
  282. package/templates/snow/src/render/quality.ts +7 -32
  283. package/templates/snow/src/render/scenery.ts +3 -3
  284. package/templates/snow/src/render/touch-controls.ts +7 -6
  285. package/templates/snow/src/render/weather.ts +3 -5
  286. package/templates/snow/src/style.css +5 -0
  287. package/templates/snow/src/terrain.ts +2 -1
  288. package/templates/snow/vite.config.ts +6 -0
  289. package/templates/starter/AGENTS.md +8 -3
  290. package/templates/starter/CLAUDE.md +8 -3
  291. package/templates/starter/native-playtests/render-chain.playtest.json +9 -9
  292. package/templates/starter/package.json +7 -7
  293. package/templates/starter/src/entities/Crate.ts +5 -2
  294. package/templates/starter/src/entities/Player.ts +10 -2
  295. package/templates/starter/src/game.ts +4 -3
  296. package/templates/starter/src/render/adaptiveQuality.ts +17 -0
  297. package/templates/starter/src/render/atmosphere.ts +6 -0
  298. package/templates/starter/src/render/backlightControls.ts +10 -0
  299. package/templates/starter/src/render/backlightMaterial.ts +4 -4
  300. package/templates/starter/src/render/camera.ts +2 -2
  301. package/templates/starter/src/render/clouds.ts +16 -1
  302. package/templates/starter/src/render/contactShadow.ts +1 -1
  303. package/templates/starter/src/render/materialLighting.ts +5 -5
  304. package/templates/starter/src/render/materials.ts +3 -2
  305. package/templates/starter/src/render/postprocessing.ts +11 -10
  306. package/templates/starter/src/render/quality.ts +14 -1
  307. package/templates/starter/src/render/touch-controls.ts +7 -6
  308. package/templates/starter/src/scenes/Play.ts +13 -17
  309. package/templates/starter/src/state.ts +2 -0
  310. package/templates/starter/src/style.css +4 -0
  311. package/templates/starter/src/ui/Menu.tsx +5 -1
  312. package/templates/starter/vite.config.ts +2 -0
  313. package/templates/tower-defense/AGENTS.md +7 -2
  314. package/templates/tower-defense/CLAUDE.md +7 -2
  315. package/templates/tower-defense/package.json +7 -7
  316. package/templates/tower-defense/src/game.ts +1 -1
  317. package/templates/tower-defense/src/render/backlightControls.ts +10 -0
  318. package/templates/tower-defense/src/render/backlightMaterial.ts +4 -4
  319. package/templates/tower-defense/src/render/materialLighting.ts +5 -5
  320. package/templates/tower-defense/src/render/quality.ts +7 -32
  321. package/templates/tower-defense/src/render/shapes.ts +1 -2
  322. package/templates/tower-defense/src/scenes/Battle.ts +4 -9
  323. package/templates/tower-defense/src/style.css +4 -0
  324. package/templates/tower-defense/tsconfig.json +1 -1
  325. package/templates/tower-defense/vite.config.ts +2 -0
  326. package/templates/action-rpg/src/render/environmentContribution.ts +0 -188
  327. package/templates/action-rpg/src/render/environmentRadiance.ts +0 -36
  328. package/templates/action-rpg/src/render/environmentSampleCache.ts +0 -43
  329. package/templates/action-rpg/src/render/environmentSampling.ts +0 -193
  330. package/templates/action-rpg/src/render/environmentSnapshot.ts +0 -53
  331. package/templates/minimal/src/render/environmentContribution.ts +0 -188
  332. package/templates/minimal/src/render/environmentRadiance.ts +0 -36
  333. package/templates/minimal/src/render/environmentSampleCache.ts +0 -43
  334. package/templates/minimal/src/render/environmentSampling.ts +0 -193
  335. package/templates/minimal/src/render/environmentSnapshot.ts +0 -53
  336. package/templates/platformer/src/render/environmentContribution.ts +0 -188
  337. package/templates/platformer/src/render/environmentRadiance.ts +0 -36
  338. package/templates/platformer/src/render/environmentSampleCache.ts +0 -43
  339. package/templates/platformer/src/render/environmentSampling.ts +0 -193
  340. package/templates/platformer/src/render/environmentSnapshot.ts +0 -53
  341. package/templates/puzzle/src/render/environmentContribution.ts +0 -188
  342. package/templates/puzzle/src/render/environmentRadiance.ts +0 -36
  343. package/templates/puzzle/src/render/environmentSampleCache.ts +0 -43
  344. package/templates/puzzle/src/render/environmentSampling.ts +0 -193
  345. package/templates/puzzle/src/render/environmentSnapshot.ts +0 -53
  346. package/templates/racing/src/render/environmentContribution.ts +0 -188
  347. package/templates/racing/src/render/environmentRadiance.ts +0 -36
  348. package/templates/racing/src/render/environmentSampleCache.ts +0 -43
  349. package/templates/racing/src/render/environmentSampling.ts +0 -193
  350. package/templates/racing/src/render/environmentSnapshot.ts +0 -53
  351. package/templates/racing/src/ui/Menu.tsx +0 -7
  352. package/templates/rts/src/render/environmentContribution.ts +0 -188
  353. package/templates/rts/src/render/environmentRadiance.ts +0 -36
  354. package/templates/rts/src/render/environmentSampleCache.ts +0 -43
  355. package/templates/rts/src/render/environmentSampling.ts +0 -193
  356. package/templates/rts/src/render/environmentSnapshot.ts +0 -53
  357. package/templates/runner/src/render/environmentContribution.ts +0 -188
  358. package/templates/runner/src/render/environmentRadiance.ts +0 -36
  359. package/templates/runner/src/render/environmentSampleCache.ts +0 -43
  360. package/templates/runner/src/render/environmentSampling.ts +0 -193
  361. package/templates/runner/src/render/environmentSnapshot.ts +0 -53
  362. package/templates/sailing/src/render/environmentContribution.ts +0 -188
  363. package/templates/sailing/src/render/environmentRadiance.ts +0 -36
  364. package/templates/sailing/src/render/environmentSampleCache.ts +0 -43
  365. package/templates/sailing/src/render/environmentSampling.ts +0 -193
  366. package/templates/sailing/src/render/environmentSnapshot.ts +0 -53
  367. package/templates/shooter/src/render/environmentContribution.ts +0 -188
  368. package/templates/shooter/src/render/environmentRadiance.ts +0 -36
  369. package/templates/shooter/src/render/environmentSampleCache.ts +0 -43
  370. package/templates/shooter/src/render/environmentSampling.ts +0 -193
  371. package/templates/shooter/src/render/environmentSnapshot.ts +0 -53
  372. package/templates/snow/src/render/environmentContribution.ts +0 -188
  373. package/templates/snow/src/render/environmentRadiance.ts +0 -36
  374. package/templates/snow/src/render/environmentSampleCache.ts +0 -43
  375. package/templates/snow/src/render/environmentSampling.ts +0 -193
  376. package/templates/snow/src/render/environmentSnapshot.ts +0 -53
  377. package/templates/starter/src/render/environmentContribution.ts +0 -188
  378. package/templates/starter/src/render/environmentRadiance.ts +0 -36
  379. package/templates/starter/src/render/environmentSampleCache.ts +0 -43
  380. package/templates/starter/src/render/environmentSampling.ts +0 -193
  381. package/templates/starter/src/render/environmentSnapshot.ts +0 -53
  382. package/templates/starter/src/render/rendererGate.ts +0 -36
  383. package/templates/tower-defense/src/render/environmentContribution.ts +0 -188
  384. package/templates/tower-defense/src/render/environmentRadiance.ts +0 -36
  385. package/templates/tower-defense/src/render/environmentSampleCache.ts +0 -43
  386. package/templates/tower-defense/src/render/environmentSampling.ts +0 -193
  387. package/templates/tower-defense/src/render/environmentSnapshot.ts +0 -53
@@ -1,13 +1,10 @@
1
1
  import { type OutputRenderer, WorldEnvironment } from "@threenative/core";
2
2
  // Generated for you: ordinary Three.js; ThreeNative does not read this file.
3
- //
4
- // This file wires two things together and decides nothing itself. `quality.ts` owns which stages
5
- // run at which tier and records what each one measured. Core's `WorldEnvironment` builds them and
6
- // prints `TN_WORLD_ENVIRONMENT`, naming every stage as applied or refused **with a reason**.
7
- //
8
- // To make the game cheaper or prettier everywhere, edit `quality.ts`. To force one tier for one run
9
- // (a slow desktop, a capture to compare), pass `setupPost(renderer, scene, camera, { tier: "low" })`.
10
- // `TN_QUALITY_TIER` names the tier that ran either way.
3
+ // This file wires two things together and decides nothing itself. `quality.ts` owns which stages run at which
4
+ // tier and records what each one measured; core's `WorldEnvironment` builds them and prints `TN_WORLD_ENVIRONMENT`,
5
+ // naming every stage as applied or refused **with a reason**.
6
+ // To make the game cheaper or prettier everywhere, edit `quality.ts`. To force one tier for one run (a slow desktop,
7
+ // a capture to compare), pass `setupPost(renderer, scene, camera, { tier: "low" })`; `TN_QUALITY_TIER` names it.
11
8
  import { type Camera, type DirectionalLight, FloatType, type Scene } from "three";
12
9
  import { LUTCubeLoader } from "three/addons/loaders/LUTCubeLoader.js";
13
10
  import {
@@ -17,7 +14,7 @@ import {
17
14
  formatQualityAdaptation,
18
15
  } from "./adaptiveQuality.js";
19
16
  import { type IGradeTable, filterableTable, gradeStages } from "./grade.js";
20
- import { type QualityTier, gradePreset, qualityPreset } from "./quality.js";
17
+ import { type QualityTier, gradePreset, qualityPreset, tierShadows } from "./quality.js";
21
18
  import { type TemporalAAProvider, temporalAAStages } from "./temporalAAStage.js";
22
19
  import { temporalDetailRequested, temporalDetailStages } from "./temporalDetailStage.js";
23
20
  import type { FogMedium } from "./volumetricFog.js";
@@ -64,6 +61,7 @@ export function setupPost(
64
61
  tier?: QualityTier;
65
62
  /** Scene-owned material assignments follow the same resolved tier. */
66
63
  onTierChanged?: (tier: QualityTier) => void;
64
+ shadows?: boolean; // on or off at every tier; omitted, the tier decides (`tierShadows` in `quality.ts`)
67
65
  /**
68
66
  * The bounded participating medium from `volumetricFog.ts`, built once per graph: a tier change
69
67
  * replaces the graph, and a fog controller owns one graph, so it is released and rebuilt here
@@ -95,6 +93,8 @@ export function setupPost(
95
93
  medium?.dispose();
96
94
  medium = environment.fog?.();
97
95
  const composed = medium;
96
+ const shadows = tierShadows(policy.tier, environment.shadows, renderer.raw);
97
+ observation = { ...observation, shadows };
98
98
  const settings = qualityPreset(policy.tier);
99
99
  const detail = temporalDetailRequested(renderer, settings) ? temporalDetailStages() : [];
100
100
  const world = new WorldEnvironment({
@@ -157,7 +157,7 @@ export function setupPost(
157
157
  console.info(
158
158
  `TN_QUALITY_TIER ${policy.tier} mobile=${environment.mobile === true} software=${
159
159
  environment.software === true
160
- } source=${source}`,
160
+ } source=${source} shadows=${tierShadows(policy.tier, environment.shadows).label}`,
161
161
  );
162
162
  const controller = {
163
163
  get tier(): QualityTier {
@@ -174,6 +174,7 @@ export function setupPost(
174
174
  observation = {
175
175
  stages: observation.stages,
176
176
  dropped: observation.dropped,
177
+ shadows: observation.shadows,
177
178
  ...decision,
178
179
  ...(Number.isInteger(window.window) ? { window: window.window } : {}),
179
180
  };
@@ -52,6 +52,19 @@ export function qualityPreset(tier: string): IWorldEnvironmentOptions {
52
52
  return { ...coreQualityPreset(tier), exposurePolicy: exposureSettings };
53
53
  }
54
54
 
55
+ /**
56
+ * Whether a tier casts shadows: the game's `setupPost(..., { shadows })`, else the tier's. `low` casts none, as
57
+ * Unreal's `sg.ShadowQuality` 0: its shadow pass was an Iris Xe frame's largest GPU cost (PRD-871). Pass the raw
58
+ * renderer to apply it to `shadowMap.enabled`.
59
+ */
60
+ export function tierShadows(tier: QualityTier, override?: boolean, raw?: unknown) {
61
+ const enabled = override ?? qualityTiers.shadow(tier).castShadows;
62
+ const source = override === undefined ? "tier" : "override";
63
+ const shadowMap = (raw as { shadowMap?: { enabled: boolean } } | undefined)?.shadowMap;
64
+ if (shadowMap) shadowMap.enabled = enabled;
65
+ return { enabled, source, label: `${enabled ? "on" : "off"}(${source})` } as const;
66
+ }
67
+
55
68
  /** The grade and grain a tier runs. Throws on a name that is not a tier, for the same reason. */
56
69
  export function gradePreset(tier: string): IGradeSettings {
57
70
  const preset = GRADE_PRESETS[tier as QualityTier];
@@ -67,4 +80,4 @@ export {
67
80
  type IMaterialLightingEnvironment,
68
81
  isWebGLFallbackRenderer,
69
82
  materialLightingEnabled,
70
- } from "./rendererGate.js";
83
+ } from "@threenative/core/render/environment";
@@ -15,6 +15,9 @@ const MOVE_RADIUS = 72;
15
15
  const BUTTON_RADIUS = 62;
16
16
  const EDGE = 36;
17
17
 
18
+ /** The knob's next point: `update` runs every frame, so it uses one instance. */
19
+ const knobPosition = new Vector2();
20
+
18
21
  export interface ITouchPointer {
19
22
  readonly position: Vector2;
20
23
  }
@@ -113,13 +116,11 @@ export class TouchControls {
113
116
  }
114
117
 
115
118
  const center = this.#hasMoveAnchor ? this.#moveAnchor : this.#resting;
116
- place(
117
- this.#moveKnob,
118
- new Vector2(
119
- center.x + this.#input.move.x * MOVE_RADIUS,
120
- center.y - this.#input.move.y * MOVE_RADIUS,
121
- ),
119
+ knobPosition.set(
120
+ center.x + this.#input.move.x * MOVE_RADIUS,
121
+ center.y - this.#input.move.y * MOVE_RADIUS,
122
122
  );
123
+ place(this.#moveKnob, knobPosition);
123
124
  this.#jump.material = jump ? this.#activeMaterial : this.#idleMaterial;
124
125
  this.#input.jumpPressed = jump && !this.#wasJump;
125
126
  this.#wasJump = jump;
@@ -5,10 +5,12 @@ import {
5
5
  type SceneFrame,
6
6
  createRandom,
7
7
  getPlatform,
8
+ isConsole,
8
9
  isMobile,
9
10
  isTouchscreenAvailable,
10
11
  resolveTargetFps,
11
12
  } from "@threenative/core";
13
+ import { type IEnvironmentSample, sampleEnvironment } from "@threenative/core/render/environment";
12
14
  import { Area3D, CollisionShape3D, type IPhysicsContext, RigidBody3D } from "@threenative/physics";
13
15
  import {
14
16
  BufferAttribute,
@@ -24,8 +26,8 @@ import { Goal, ISLAND } from "../entities/Goal.js";
24
26
  import { type IPlayerModel, PLAYER_STAND_Y, Player } from "../entities/Player.js";
25
27
  import { createArena, platform } from "../render/arena.js";
26
28
  import { createSpringArm } from "../render/camera.js";
29
+ import { cloudTextures, primeCloudTextures } from "../render/clouds.js";
27
30
  import { pickupRiseEase } from "../render/easing.js";
28
- import { type IEnvironmentSample, sampleEnvironment } from "../render/environmentSampling.js";
29
31
  import { setupLighting, shadeLikeSubstrate } from "../render/lighting.js";
30
32
  import { createLoadingScreen } from "../render/loading.js";
31
33
  import { createMaterialLighting } from "../render/materialLighting.js";
@@ -64,6 +66,7 @@ export class Play extends Scene<GameState, IPhysicsContext> {
64
66
  levelX: -99,
65
67
  lives: STARTING_LIVES,
66
68
  odometer: 0,
69
+ pad: false,
67
70
  paused: false,
68
71
  peakRise: 0,
69
72
  playerX: -2,
@@ -84,6 +87,8 @@ export class Play extends Scene<GameState, IPhysicsContext> {
84
87
  ]);
85
88
  this.#playerModel = playerModel;
86
89
  this.#sky = sky;
90
+ // The cloud noise is the same every run of this build: generate it once, then read it back.
91
+ primeCloudTextures(await ctx.assets.memo("clouds", () => cloudTextures()));
87
92
  setupSky(ctx.scene, sky, ctx.renderer.softwareAdapter !== undefined);
88
93
  this.#environmentSample = await sampleEnvironment(ctx.renderer.raw, ctx.scene, {
89
94
  web: getPlatform().runtime === "web",
@@ -299,7 +304,10 @@ export class Play extends Scene<GameState, IPhysicsContext> {
299
304
  ctx.add(fixed(floorMesh));
300
305
  ctx.add(fixed(floorBase));
301
306
  lensBlockers.push(...arena.solids, floorMesh, floorBase);
302
- ctx.entities.add("crate", new Crate(ctx, levelX, 4, -1.5, propMaterial));
307
+ ctx.entities.add(
308
+ "crate",
309
+ new Crate(ctx, levelX, 4, -1.5, propMaterial, () => this.#post?.tier === "low"),
310
+ );
303
311
  const pickupBase = block(0.42, 0.14, 0.42, propMaterial);
304
312
  const pickupStem = tube(0.08, 0.08, 0.3, propMaterial);
305
313
  const pickupOrb = ball(0.16, propMaterial);
@@ -346,7 +354,8 @@ export class Play extends Scene<GameState, IPhysicsContext> {
346
354
  if (body === player.body) overGoal = true;
347
355
  });
348
356
  let entityCount = 4;
349
- ctx.state.set({ entityCount });
357
+ // A console has a pad and no keyboard: the menu reads `pad` to show DualShock prompts.
358
+ ctx.state.set({ entityCount, pad: isConsole() });
350
359
  const pickup = new Area3D({
351
360
  physics: ctx.physics,
352
361
  position: { x: pickupX, y: 0.5, z: 0 },
@@ -442,20 +451,7 @@ export class Play extends Scene<GameState, IPhysicsContext> {
442
451
  ),
443
452
  );
444
453
  frameState.respawns = previous.respawns + (respawned ? 1 : 0);
445
- const current = frameCtx.state.getState();
446
- const changed =
447
- frameState.coyoteJumps !== current.coyoteJumps ||
448
- frameState.flagDisplacement !== current.flagDisplacement ||
449
- frameState.flagReadbacks !== current.flagReadbacks ||
450
- frameState.flagSteps !== current.flagSteps ||
451
- frameState.jumps !== current.jumps ||
452
- frameState.lives !== current.lives ||
453
- frameState.odometer !== current.odometer ||
454
- frameState.peakRise !== current.peakRise ||
455
- frameState.playerX !== current.playerX ||
456
- frameState.progress !== current.progress ||
457
- frameState.respawns !== current.respawns;
458
- if (changed) frameCtx.state.set(frameState);
454
+ frameCtx.state.set(frameState);
459
455
  if (respawned) frameCtx.state.flush();
460
456
  };
461
457
  }
@@ -9,6 +9,8 @@ export type GameState = {
9
9
  levelX: number;
10
10
  lives: number;
11
11
  odometer: number;
12
+ /** True on a console (`isConsole()`): the menu shows pad prompts instead of keyboard ones. */
13
+ pad: boolean;
12
14
  /** Set from the UI's pause and resume intents, and read back by the menu. */
13
15
  paused: boolean;
14
16
  /** True once the UI layer has rendered and published its interactive rectangles. */
@@ -9,6 +9,10 @@
9
9
  */
10
10
  @source "../index.html";
11
11
  @source "./";
12
+ /* `src/render/` is shader and material source: a word in its comments ("blur", "filter",
13
+ "table") became a real utility rule, which is what made a clean HUD look like a native-css
14
+ profile failure. Tailwind scans what it is told to scan. */
15
+ @source not "./render";
12
16
 
13
17
  /*
14
18
  * Your palette. Every name here becomes a real Tailwind utility — `bg-ink`,
@@ -43,7 +43,11 @@ export function Menu() {
43
43
  >
44
44
  restart
45
45
  </button>
46
- <span>WASD / arrows to move · shift to run · space to jump the gap · reach the flag</span>
46
+ <span>
47
+ {state.pad
48
+ ? "left stick to move · R2 to run · ✕ to jump the gap · right stick to zoom · reach the flag"
49
+ : "WASD / arrows to move · shift to run · space to jump the gap · reach the flag"}
50
+ </span>
47
51
  </div>
48
52
  );
49
53
  }
@@ -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,
@@ -36,6 +37,7 @@ export default defineConfig({
36
37
  plugins: [
37
38
  createEngineFreshnessPlugin(),
38
39
  createWebBrandPlugin(),
40
+ createEngineCatalogPlugin(),
39
41
  react(),
40
42
  tailwindcss(),
41
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
 
@@ -54,6 +54,7 @@ pnpm dev # play in the browser
54
54
  pnpm test # typecheck, lint, format, then every playtest
55
55
  pnpm build --target desktop # also: web, android, ios
56
56
  npx threenative doctor # build, import, device or blank-frame failure
57
+ npx threenative doctor --fix # refresh agent files
57
58
  ```
58
59
  <!-- /shared -->
59
60
 
@@ -63,6 +64,7 @@ npx threenative doctor # build, import, device or blank-frame failure
63
64
  Each is on by default with a named override. Detail: `node_modules/create-threenative/agent-docs/references/conventions.md#<id>`.
64
65
 
65
66
  - **Look** `#look`: filmic curve, metered auto exposure. Override: `tonemapMode: "aces"`; `autoExposureEnabled: false` + `exposure`. Marker: `TN_WORLD_ENVIRONMENT`.
67
+ - **Ambient occlusion** `#ao-indirect`: darkens indirect light only, not the sun. Override: `gtaoIndirectOnly: false`; `gtaoEnabled: false`. Marker: `TN_WORLD_ENVIRONMENT`.
66
68
  - **Quality tier (`src/render/quality.ts`)** `#quality`: GPU class picks `high`, `medium` or `low`. Override: `setupPost(..., { tier: "low" })`. Marker: `TN_QUALITY_TIER`.
67
69
  - **Resolution scale** `#resolution`: `"auto"`, 0.85 on mobile-low. Override: numeric `resolutionScale`. Marker: `TN_FRAME_BUDGET`.
68
70
  - **Budget real time for the look** `#frame-budget`: frame meter and scene verdict on. Override: `frameBudget: false`. Marker: `TN_FRAME_BUDGET`, `TN_SCENE_WARNING`.
@@ -86,12 +88,15 @@ Each is on by default with a named override. Detail: `node_modules/create-threen
86
88
  - **Frame spans** `#spans`: off. Override: `TN_FRAME_SPANS=1`. Marker: `TN_FRAME_SPANS`.
87
89
  - **Multiplayer** `#net`: none; unsupported transport rejects. Override: `connect` from `@threenative/core/net` with four limits. Marker: `TN_NET_UNAVAILABLE`.
88
90
  - **Desktop window** `#desktop-mode`: CLI, then `display.fullscreen`, then `window.maximized`. Override: `--windowed`; `--maximized`; `--fullscreen`.
91
+ - **CPU priority** `#cpu-priority`: game threads first. Override: `display.priority: "normal"`. Marker: `TN_PROCESS_PRIORITY`.
89
92
  - **Terrain** `#terrain`: authored in the game. Override: optional `@threenative/terrain`; `references/terrain-authoring.md`.
90
93
  - **Navigation** `#navigation`: none; browser-only WASM. Override: import `@threenative/physics/navigation` on purpose.
94
+ - **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`.
91
95
  - **Move input** `#move-axis`: `input.vector("move").y` is +up. Override: one explicit `-move.y` conversion.
92
96
  - **Scene change** `#scene-change`: `ctx.goto(name)` keeps state. Override: `game.goto(name)` resets state.
93
97
  - **Randomness** `#seed`: unseeded. Override: `defineGame({ seed })`.
94
98
  - **Engine** `#engine`: owned C++ engine. Override: `engine: "threejs"` only when the user asks. Marker: `TN_NATIVE_ENGINE_UNBOUND`.
99
+ - **Refused imports** `#engine-catalog`: refused `three` imports fail at their line. Override: `createEngineCatalogPlugin({ mode: "warn" })`. Marker: `TN_ENGINE_CATALOG`.
95
100
  <!-- /shared -->
96
101
 
97
102
  <!-- 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
 
@@ -56,6 +56,7 @@ pnpm dev # play in the browser
56
56
  pnpm test # typecheck, lint, format, then every playtest
57
57
  pnpm build --target desktop # also: web, android, ios
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`.
@@ -88,12 +90,15 @@ Each is on by default with a named override. Detail: `node_modules/create-threen
88
90
  - **Frame spans** `#spans`: off. Override: `TN_FRAME_SPANS=1`. Marker: `TN_FRAME_SPANS`.
89
91
  - **Multiplayer** `#net`: none; unsupported transport rejects. Override: `connect` from `@threenative/core/net` with four limits. Marker: `TN_NET_UNAVAILABLE`.
90
92
  - **Desktop window** `#desktop-mode`: CLI, then `display.fullscreen`, then `window.maximized`. Override: `--windowed`; `--maximized`; `--fullscreen`.
93
+ - **CPU priority** `#cpu-priority`: game threads first. Override: `display.priority: "normal"`. Marker: `TN_PROCESS_PRIORITY`.
91
94
  - **Terrain** `#terrain`: authored in the game. Override: optional `@threenative/terrain`; `references/terrain-authoring.md`.
92
95
  - **Navigation** `#navigation`: none; browser-only WASM. Override: import `@threenative/physics/navigation` on purpose.
96
+ - **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`.
93
97
  - **Move input** `#move-axis`: `input.vector("move").y` is +up. Override: one explicit `-move.y` conversion.
94
98
  - **Scene change** `#scene-change`: `ctx.goto(name)` keeps state. Override: `game.goto(name)` resets state.
95
99
  - **Randomness** `#seed`: unseeded. Override: `defineGame({ seed })`.
96
100
  - **Engine** `#engine`: owned C++ engine. Override: `engine: "threejs"` only when the user asks. Marker: `TN_NATIVE_ENGINE_UNBOUND`.
101
+ - **Refused imports** `#engine-catalog`: refused `three` imports fail at their line. Override: `createEngineCatalogPlugin({ mode: "warn" })`. Marker: `TN_ENGINE_CATALOG`.
97
102
  <!-- /shared -->
98
103
 
99
104
  <!-- shared: kit-stuck -->
@@ -18,9 +18,9 @@
18
18
  "format:check": "biome format src"
19
19
  },
20
20
  "dependencies": {
21
- "@threenative/core": "0.3.12",
22
- "@threenative/physics": "0.3.12",
23
- "@threenative/ui": "0.3.12",
21
+ "@threenative/core": ">=0.3.15",
22
+ "@threenative/physics": ">=0.3.15",
23
+ "@threenative/ui": ">=0.3.15",
24
24
  "react": "19.2.0",
25
25
  "react-dom": "19.2.0",
26
26
  "three": "0.187.0"
@@ -28,13 +28,13 @@
28
28
  "devDependencies": {
29
29
  "@gltf-transform/cli": "4.4.2",
30
30
  "@tailwindcss/vite": "4.3.3",
31
- "@threenative/assets": "0.3.13",
32
- "@threenative/playtest": "0.3.12",
31
+ "@threenative/assets": ">=0.3.16",
32
+ "@threenative/playtest": ">=0.3.15",
33
33
  "@types/react": "19.2.0",
34
34
  "@types/react-dom": "19.2.0",
35
35
  "@types/three": "0.187.0",
36
36
  "@vitejs/plugin-react": "6.0.5",
37
- "create-threenative": "0.2.17",
37
+ "create-threenative": "0.2.20",
38
38
  "esbuild": "0.27.0",
39
39
  "playwright": "1.62.1",
40
40
  "tailwindcss": "4.3.3",
@@ -44,7 +44,7 @@
44
44
  "eslint": "10.13.0"
45
45
  },
46
46
  "optionalDependencies": {
47
- "@threenative/runtime-native": "0.3.12"
47
+ "@threenative/runtime-native": ">=0.3.15"
48
48
  },
49
49
  "overrides": {
50
50
  "sharp": ">=0.35.4",
@@ -40,7 +40,7 @@ const game = defineGame<GameState, IPhysicsContext>({
40
40
  // curve. The world still needs a solver to answer those questions, so gravity is simply zero.
41
41
  plugins: [rapier({ gravity: { x: 0, y: 0, z: 0 } }), playtest({ events })],
42
42
  display: config.display,
43
- render: config.renderer,
43
+ renderer: config.renderer,
44
44
  scenes: { battle: Battle, boot: Boot },
45
45
  seed: 47021,
46
46
  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";
@@ -31,7 +31,6 @@ import {
31
31
  } from "@threenative/core";
32
32
  import { exposureSettings } from "./exposure.js";
33
33
  export type { QualityTier } from "@threenative/core";
34
- import type { QualityTier } from "@threenative/core";
35
34
 
36
35
  /**
37
36
  * The three names this game's look comes in.
@@ -48,34 +47,10 @@ export function qualityPreset(tier: string): IWorldEnvironmentOptions {
48
47
  }
49
48
 
50
49
  /** First admitted material lane: high desktop hardware WebGPU in the browser only. */
51
- export interface IMaterialLightingEnvironment {
52
- readonly web: boolean;
53
- readonly rendererKind: string;
54
- readonly mobile?: boolean;
55
- readonly software?: boolean;
56
- readonly webglFallback?: boolean;
57
- }
58
- export function materialLightingEnabled(
59
- tier: QualityTier,
60
- environment: IMaterialLightingEnvironment,
61
- ): boolean {
62
- return (
63
- tier === "high" &&
64
- environment.web &&
65
- environment.rendererKind === "webgpu" &&
66
- environment.mobile !== true &&
67
- environment.software !== true &&
68
- environment.webglFallback !== true
69
- );
70
- }
71
-
72
- /** A WebGPURenderer wrapper may run an ordinary WebGL fallback backend. */
73
- export function isWebGLFallbackRenderer(renderer: unknown): boolean {
74
- if (renderer === null || typeof renderer !== "object") return false;
75
- const backend = Reflect.get(renderer, "backend");
76
- return (
77
- backend !== null &&
78
- typeof backend === "object" &&
79
- Reflect.get(backend, "isWebGLBackend") === true
80
- );
81
- }
50
+ // The material lane's admission rule and the WebGL-fallback probe are the engine's: twelve kits
51
+ // held a copy each, so a fix to one left eleven admitting what it refused.
52
+ export {
53
+ type IMaterialLightingEnvironment,
54
+ isWebGLFallbackRenderer,
55
+ materialLightingEnabled,
56
+ } from "@threenative/core/render/environment";
@@ -399,11 +399,10 @@ export function reactor(): Group {
399
399
  export function lcg(seed: number): () => number {
400
400
  let state = seed >>> 0;
401
401
  return () => {
402
- state = (Math.imul(state, 1664525) + 1013904223) >>> 0;
402
+ state = (state * 1664525 + 1013904223) >>> 0;
403
403
  return state / 4294967296;
404
404
  };
405
405
  }
406
-
407
406
  function scatter(
408
407
  geometry: BufferGeometry,
409
408
  material: Material,
@@ -6,6 +6,7 @@ import {
6
6
  getPlatform,
7
7
  isMobile,
8
8
  } from "@threenative/core";
9
+ import { type IEnvironmentSample, sampleEnvironment } from "@threenative/core/render/environment";
9
10
  import type { IPhysicsContext } from "@threenative/physics";
10
11
  import { type Group, type Mesh, type PerspectiveCamera, type Texture, Vector3 } from "three";
11
12
  import {
@@ -34,7 +35,6 @@ import { Enemy } from "../enemies/Enemy.js";
34
35
  import { drainIntents } from "../intents.js";
35
36
  import { emitPlaytestEvent } from "../playtest-events.js";
36
37
  import { setupCamera } from "../render/camera.js";
37
- import { type IEnvironmentSample, sampleEnvironment } from "../render/environmentSampling.js";
38
38
  import { setupLighting } from "../render/lighting.js";
39
39
  import { createLoadingScreen } from "../render/loading.js";
40
40
  import { createMaterialLighting } from "../render/materialLighting.js";
@@ -68,11 +68,6 @@ const STRIKE_BOUNDS = { x: 19, z: 12 } as const;
68
68
  const LEFT_SHIFT = "ShiftLeft";
69
69
  const RIGHT_SHIFT = "ShiftRight";
70
70
 
71
- function sameState(a: GameState, b: GameState): boolean {
72
- for (const key of Object.keys(a) as (keyof GameState)[]) if (a[key] !== b[key]) return false;
73
- return true;
74
- }
75
-
76
71
  export class Battle extends Scene<GameState, IPhysicsContext> {
77
72
  #environmentSample: IEnvironmentSample | undefined;
78
73
  #materialLighting: ReturnType<typeof createMaterialLighting> | undefined;
@@ -514,8 +509,8 @@ export class Battle extends Scene<GameState, IPhysicsContext> {
514
509
  ghost.visible = true;
515
510
  };
516
511
 
517
- // Publish only what changed: the HUD is another process on native, and a frame that changed
518
- // nothing should cost it nothing.
512
+ // The store publishes only what changed: the HUD is another process on native, and a frame
513
+ // that changed nothing costs it nothing.
519
514
  const next: GameState = { ...INITIAL_STATE };
520
515
  const publish = (frameCtx: FrameCtx, speed: number): void => {
521
516
  const previous = frameCtx.state.getState();
@@ -556,7 +551,7 @@ export class Battle extends Scene<GameState, IPhysicsContext> {
556
551
  next.towers = towers.size;
557
552
  next.uiReady = previous.uiReady;
558
553
  next.wave = waves.wave;
559
- if (!sameState(next, previous)) frameCtx.state.set(next);
554
+ frameCtx.state.set(next);
560
555
  };
561
556
 
562
557
  this.#materialLighting = ctx.entities.add(
@@ -2,6 +2,10 @@
2
2
 
3
3
  @source "../index.html";
4
4
  @source "./";
5
+ /* `src/render/` is shader and material source: a word in its comments ("blur", "filter",
6
+ "table") became a real utility rule, which is what made a clean HUD look like a native-css
7
+ profile failure. Tailwind scans what it is told to scan. */
8
+ @source not "./render";
5
9
 
6
10
  @theme {
7
11
  --color-ink: #14241e;
@@ -13,5 +13,5 @@
13
13
  "verbatimModuleSyntax": true,
14
14
  "isolatedModules": true
15
15
  },
16
- "include": ["src/**/*.ts", "src/**/*.tsx", "*.ts"]
16
+ "include": ["src/**/*.ts", "src/**/*.tsx", "tests/**/*.ts", "*.ts"]
17
17
  }
@@ -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,
@@ -36,6 +37,7 @@ export default defineConfig({
36
37
  plugins: [
37
38
  createEngineFreshnessPlugin(),
38
39
  createWebBrandPlugin(),
40
+ createEngineCatalogPlugin(),
39
41
  react(),
40
42
  tailwindcss(),
41
43
  assetsWatchPlugin(),