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
@@ -0,0 +1,325 @@
1
+ // Generated for you. This is ordinary Three.js TSL — edit or delete it freely.
2
+ //
3
+ // The vale's grass look: the blade shape and the material that bends, sways, thins and colours it.
4
+ // `GrassField3D` (built in `scenes/Play.ts`) owns the streaming, the scatter, the LOD and the
5
+ // pushers; everything you see is decided here. Each blade bends along a quadratic Bezier from its
6
+ // root: a resting lean, a gust field that scrolls downwind, a per-blade flutter, and the pushers'
7
+ // pull, which lays it flat round Wren. Far blades thin out by priority while the ones left widen,
8
+ // so the field holds its cover and nothing pops. Lighting is the scene's own (sun, sky, exposure,
9
+ // fog), plus light through the blade when the sun is behind it and darker roots.
10
+ import { BufferAttribute, BufferGeometry, Color, DoubleSide, type Vector4 } from "three";
11
+ import {
12
+ Fn,
13
+ abs,
14
+ attribute,
15
+ cameraPosition,
16
+ cos,
17
+ cross,
18
+ dot,
19
+ float,
20
+ floor,
21
+ fract,
22
+ max,
23
+ min,
24
+ mix,
25
+ modelWorldMatrix,
26
+ normalize,
27
+ positionGeometry,
28
+ positionWorld,
29
+ pow,
30
+ sin,
31
+ smoothstep,
32
+ sqrt,
33
+ time,
34
+ transformNormalToView,
35
+ varying,
36
+ vec2,
37
+ vec3,
38
+ vec4,
39
+ } from "three/tsl";
40
+ import { MeshStandardNodeMaterial, type Node, type UniformNode } from "three/webgpu";
41
+ import { C } from "./palette.js";
42
+ import { SUN_DIRECTION } from "./sky.js";
43
+
44
+ /** Every look value, in one place. Shape and wind are live through the uniforms below. */
45
+ export const GRASS = {
46
+ /** Blade segments near, mid and far: each level is one draw range of the same geometry. */
47
+ segments: [4, 2, 1],
48
+ bladeHeight: 0.5,
49
+ /** ± share of `bladeHeight`. */
50
+ heightVariation: 0.4,
51
+ bladeWidth: 0.05,
52
+ /** Higher stays wide longer, then a sharper tip. */
53
+ taper: 1.7,
54
+ /** Resting lean, 0 upright to 1 flat. */
55
+ lean: 0.34,
56
+ leanVariation: 0.2,
57
+ /** Where the bend happens: low arcs from the root, high is a straight stem with a drooping tip. */
58
+ curve: 0.6,
59
+ /** 0 is a uniform lawn, 1 strong tufts. */
60
+ clumpStrength: 0.75,
61
+ /** Widens edge-on blades so they do not alias into lines. */
62
+ viewThicken: 0.55,
63
+ /** Sinks the roots to hide the seam with the floor. */
64
+ rootSink: 0.03,
65
+ /** Each far blade is this many times wider, holding the cover the thinning took. */
66
+ farWidth: 2.8,
67
+ /** Degrees in the ground plane the wind blows toward (0 = +X, 90 = +Z). */
68
+ windDirection: 25,
69
+ /** Gust fronts travel this fast, m/s, and are this big, metres. */
70
+ windSpeed: 4.5,
71
+ gustScale: 26,
72
+ /** Lean added at the peak of a gust, and the per-blade jitter. */
73
+ windStrength: 0.55,
74
+ flutter: 0.07,
75
+ /** Gusts brighten the blades they bend, which makes wind read as waves from afar. */
76
+ gustHighlight: 0.45,
77
+ /** How far a pusher lays the blades over. */
78
+ pushStrength: 1,
79
+ baseColor: C.grassRoot,
80
+ tipColor: C.grassTip,
81
+ /** Broad patches drift toward this colour. */
82
+ dryColor: C.grassDry,
83
+ dryAmount: 0.35,
84
+ patchScale: 22,
85
+ /** Per-tuft brightness spread. */
86
+ colorVariation: 0.4,
87
+ /** Darkening toward the roots. */
88
+ ambientOcclusion: 0.45,
89
+ /** Sunlight through a blade lit from behind. */
90
+ translucency: 0.7,
91
+ /** 0 lights each blade by its own normal, 1 like the ground under it (calmer). */
92
+ terrainNormalBlend: 0.6,
93
+ } as const;
94
+
95
+ const rgb = (hex: number): Node<"vec3"> => {
96
+ const c = new Color(hex);
97
+ return vec3(c.r, c.g, c.b);
98
+ };
99
+
100
+ /** The sun colour the translucency carries, as the key light's colour. */
101
+ const SUN_COLOR = new Color(0xffd9a0);
102
+
103
+ /** The field's uniforms the material reads: what `GrassField3D` hands to `grassMaterial`. */
104
+ export interface IGrassFieldUniforms {
105
+ readonly thinStart: UniformNode<"float", number>;
106
+ readonly thinEnd: UniformNode<"float", number>;
107
+ readonly farDensity: UniformNode<"float", number>;
108
+ readonly fadeStart: UniformNode<"float", number>;
109
+ readonly drawDistance: UniformNode<"float", number>;
110
+ readonly pushers: readonly UniformNode<"vec4", Vector4>[];
111
+ push(rootWorld: Node<"vec3">): Node<"vec3">;
112
+ }
113
+
114
+ /** Every LOD of one blade in one geometry, x across (-0.5..0.5) and y along it (0 root, 1 tip). */
115
+ export function grassBlade(): {
116
+ geometry: BufferGeometry;
117
+ lods: { start: number; count: number }[];
118
+ reach: number;
119
+ } {
120
+ const pos: number[] = [];
121
+ const idx: number[] = [];
122
+ const lods: { start: number; count: number }[] = [];
123
+ for (const seg of GRASS.segments) {
124
+ const base = pos.length / 3;
125
+ const start = idx.length;
126
+ for (let r = 0; r < seg; r++) pos.push(-0.5, r / seg, 0, 0.5, r / seg, 0);
127
+ pos.push(0, 1, 0);
128
+ for (let r = 0; r < seg - 1; r++) {
129
+ const a = base + r * 2;
130
+ idx.push(a, a + 1, a + 2, a + 1, a + 3, a + 2);
131
+ }
132
+ const a = base + (seg - 1) * 2;
133
+ idx.push(a, a + 1, a + 2);
134
+ lods.push({ start, count: idx.length - start });
135
+ }
136
+ const geometry = new BufferGeometry();
137
+ geometry.setAttribute("position", new BufferAttribute(new Float32Array(pos), 3));
138
+ geometry.setIndex(idx);
139
+ return { geometry, lods, reach: GRASS.bladeHeight * (1 + GRASS.heightVariation) };
140
+ }
141
+
142
+ const hash2 = (p: Node<"vec2">): Node<"float"> => {
143
+ const q = fract(p.mul(vec2(123.34, 456.21)));
144
+ const r = q.add(dot(q, q.add(45.32)));
145
+ return fract(r.x.mul(r.y));
146
+ };
147
+
148
+ /** Smooth value noise, 0..1. */
149
+ const noise = Fn(([p]: [Node<"vec2">]) => {
150
+ const i = floor(p);
151
+ const f = fract(p);
152
+ const u = f.mul(f).mul(float(3).sub(f.mul(2)));
153
+ return mix(
154
+ mix(hash2(i), hash2(i.add(vec2(1, 0))), u.x),
155
+ mix(hash2(i.add(vec2(0, 1))), hash2(i.add(vec2(1, 1))), u.x),
156
+ u.y,
157
+ );
158
+ });
159
+
160
+ /**
161
+ * The blade material for `GrassField3D`: reads the field's instance attributes (`grassRoot`,
162
+ * `grassRand`, `grassClump`) and uniforms. Its thinning uses the field's own ranges, so the CPU
163
+ * trim only drops blades this material already hid.
164
+ */
165
+ export function grassMaterial(field: IGrassFieldUniforms): MeshStandardNodeMaterial {
166
+ const g = GRASS;
167
+ const root = attribute("grassRoot", "vec3");
168
+ const rand = attribute("grassRand", "vec4");
169
+ const clump = attribute("grassClump", "vec4");
170
+ const windAngle = (g.windDirection * Math.PI) / 180;
171
+ const wind = vec2(Math.cos(windAngle), Math.sin(windAngle));
172
+ // The blade's own vertex: after `positionNode` moves it, `positionLocal` reads the moved
173
+ // vertex, whose y is the ground height, not the share of the blade.
174
+ const t = positionGeometry.y;
175
+ const side = positionGeometry.x.mul(2);
176
+ const rootWorld = modelWorldMatrix.mul(vec4(root, 1)).xyz;
177
+ const dist = rootWorld.distance(cameraPosition);
178
+ const r0 = fract(sin(rand.z.mul(9871.13).add(0.71)).mul(43758.5453));
179
+ const r1 = fract(r0.mul(57.31).add(rand.x.mul(3.17)));
180
+
181
+ // Distance thinning: blades past this distance's priority cut-off shrink away; the far edge sinks.
182
+ const thinT = smoothstep(field.thinStart, field.thinEnd, dist);
183
+ const keepEdge = mix(float(1.1), field.farDensity, thinT);
184
+ const keep = float(1).sub(smoothstep(keepEdge.sub(0.1), keepEdge, rand.z));
185
+ const fadeSpan = field.drawDistance.sub(field.fadeStart);
186
+ const fadeT = smoothstep(
187
+ field.fadeStart,
188
+ field.drawDistance,
189
+ dist.add(r0.mul(fadeSpan).mul(0.5)),
190
+ );
191
+ const grow = rand.w.mul(keep).mul(float(1).sub(fadeT));
192
+
193
+ // Facing: random, pulled outward from the tuft centre.
194
+ const a = rand.x.mul(Math.PI * 2);
195
+ const facing = normalize(
196
+ mix(vec2(cos(a), sin(a)), vec2(cos(clump.x), sin(clump.x)), g.clumpStrength * 0.65).add(1e-4),
197
+ );
198
+ const height = float(g.bladeHeight)
199
+ .mul(mix(float(1 - g.heightVariation), float(1 + g.heightVariation), rand.y))
200
+ .mul(mix(float(1), clump.y.add(0.5), g.clumpStrength))
201
+ .mul(grow);
202
+
203
+ // Wind: a gust field scrolling downwind, plus per-blade flutter.
204
+ const wuv = rootWorld.xz.sub(wind.mul(time).mul(g.windSpeed)).div(g.gustScale);
205
+ const gust = smoothstep(
206
+ 0.25,
207
+ 0.8,
208
+ noise(wuv)
209
+ .mul(0.6)
210
+ .add(noise(wuv.mul(2.31).add(17.3)).mul(0.4)),
211
+ );
212
+ const fl = gust.mul(0.6).add(0.4).mul(g.flutter);
213
+ const flutA = sin(time.mul(r0.mul(2.2).add(2.6)).add(r1.mul(Math.PI * 2))).mul(fl);
214
+ const flutB = sin(time.mul(r1.mul(2).add(3.3)).add(r0.mul(Math.PI * 2))).mul(fl);
215
+ const pushed = field.push(rootWorld);
216
+ const press = pushed.z;
217
+ const tipRaw = facing
218
+ .mul(
219
+ max(
220
+ r1
221
+ .sub(0.5)
222
+ .mul(2 * g.leanVariation)
223
+ .add(g.lean),
224
+ 0,
225
+ ),
226
+ )
227
+ .add(wind.mul(gust.mul(0.88).add(0.12).mul(g.windStrength).add(flutA)))
228
+ .add(vec2(wind.y.negate(), wind.x).mul(flutB))
229
+ .add(pushed.xy.mul(g.pushStrength));
230
+ const tip = tipRaw.mul(min(1, float(0.96).div(max(tipRaw.length(), 1e-4))));
231
+ const tipY = sqrt(max(float(1).sub(dot(tip, tip)), 0));
232
+ const h = height.mul(float(1).sub(press.mul(0.3)));
233
+
234
+ // Quadratic Bezier: root, a control point straight up, the tip.
235
+ const p1 = vec3(0, g.curve, 0);
236
+ const p2 = vec3(tip.x, tipY, tip.y);
237
+ const it = float(1).sub(t);
238
+ const curve = p1.mul(it.mul(t).mul(2)).add(p2.mul(t.mul(t)));
239
+ const tangent = normalize(p1.mul(it.mul(2)).add(p2.sub(p1).mul(t.mul(2))));
240
+ // The flat of the blade turns toward the way it bends.
241
+ const f2 = normalize(facing.mul(0.6).add(tip).add(1e-4));
242
+ const across = vec3(f2.y.negate(), 0, f2.x);
243
+ const bladeNormal = normalize(cross(across, tangent));
244
+ const width = float(g.bladeWidth * 0.5)
245
+ .mul(mix(float(1), float(g.farWidth), thinT))
246
+ .mul(r1.mul(0.5).add(0.75))
247
+ .mul(float(1).sub(pow(t, g.taper)))
248
+ .mul(sqrt(grow));
249
+ // Edge-on blades turn a little toward the camera.
250
+ const toCam = normalize(cameraPosition.sub(rootWorld));
251
+ const edge = float(1).sub(abs(dot(bladeNormal, toCam)));
252
+ const thick = edge.mul(edge).mul(g.viewThicken);
253
+ const local = root
254
+ .add(curve.mul(h))
255
+ .add(across.add(bladeNormal.mul(thick)).mul(side.mul(width)))
256
+ .sub(vec3(0, it.mul(g.rootSink), 0));
257
+
258
+ // Per-blade values the fragment stage reads.
259
+ const ground = vec3(
260
+ clump.z,
261
+ sqrt(max(float(1).sub(clump.z.mul(clump.z)).sub(clump.w.mul(clump.w)), 0)),
262
+ clump.w,
263
+ );
264
+ const vNormal = varying(
265
+ normalize(mix(bladeNormal, ground, mix(float(g.terrainNormalBlend), float(1), thinT))),
266
+ );
267
+ const vT = varying(t);
268
+ const vFar = varying(thinT);
269
+ const vTuft = varying(clump.y.mul(0.65).add(r0.mul(0.35)));
270
+ const patchUv = rootWorld.xz.div(g.patchScale);
271
+ const vPatch = varying(
272
+ smoothstep(
273
+ 0.3,
274
+ 0.8,
275
+ noise(patchUv.add(91.7))
276
+ .mul(0.65)
277
+ .add(noise(patchUv.mul(2.7).add(5.3)).mul(0.35)),
278
+ ),
279
+ );
280
+ const vGust = varying(gust);
281
+
282
+ const material = new MeshStandardNodeMaterial({ roughness: 0.75, side: DoubleSide });
283
+ material.name = "GrassBlades";
284
+ material.positionNode = local;
285
+ // The blade's normal, turned to face the viewer: a thin blade is lit on the side you see.
286
+ const view = cameraPosition.sub(positionWorld);
287
+ material.normalNode = transformNormalToView(
288
+ vNormal.mul(dot(vNormal, view).sign().add(0.5).sign()),
289
+ );
290
+ // Far blades converge on one mid colour with little root shade, so the thinned field reads as a surface.
291
+ const tc = mix(vT.mul(vT.mul(0.65).add(0.35)), max(vT, 0.5), vFar.mul(0.8));
292
+ const albedo = mix(rgb(g.baseColor), rgb(g.tipColor), tc);
293
+ const dried = mix(albedo, rgb(g.dryColor), vPatch.mul(g.dryAmount).mul(tc.mul(0.65).add(0.35)));
294
+ const occlusion = mix(
295
+ float(1 - g.ambientOcclusion).add(vFar.mul(0.75 * g.ambientOcclusion)),
296
+ float(1),
297
+ vT,
298
+ );
299
+ material.colorNode = vec4(
300
+ dried
301
+ .mul(vTuft.sub(0.5).mul(g.colorVariation).add(1))
302
+ .mul(vGust.sub(0.4).mul(g.gustHighlight).mul(vT).add(1)),
303
+ 1,
304
+ );
305
+ material.aoNode = occlusion;
306
+ // Sun on the far side of the blade: light comes through, warmer and more saturated.
307
+ const sun = vec3(SUN_DIRECTION.x, SUN_DIRECTION.y, SUN_DIRECTION.z);
308
+ const back = max(dot(vNormal, sun).negate(), 0);
309
+ const through = pow(max(dot(normalize(view), sun.negate()), 0), 5);
310
+ const sunColor = vec3(SUN_COLOR.r, SUN_COLOR.g, SUN_COLOR.b);
311
+ material.emissiveNode = dried
312
+ .mul(vec3(1.05, 1.2, 0.5))
313
+ .mul(sunColor)
314
+ .mul(back.mul(0.45).add(through.mul(back.mul(0.65).add(0.35)).mul(1.1)))
315
+ .mul(vT.mul(0.7).add(0.3))
316
+ .mul(g.translucency);
317
+ return material;
318
+ }
319
+
320
+ /** A blade's standing height at `(x, z)` as a share of its rest height: the CPU mirror of the bend under a pusher. */
321
+ export function grassStandAt(press: number): number {
322
+ const lean = GRASS.lean + press * GRASS.pushStrength;
323
+ const reach = Math.min(lean, 0.96);
324
+ return (1 - 0.3 * press) * Math.sqrt(1 - reach * reach);
325
+ }
@@ -15,6 +15,7 @@ import {
15
15
  LinearFilter,
16
16
  LinearMipmapLinearFilter,
17
17
  type Material,
18
+ MathUtils,
18
19
  MeshBasicMaterial,
19
20
  MeshStandardMaterial,
20
21
  NoColorSpace,
@@ -56,8 +57,8 @@ export function detailTexture(): DataTexture {
56
57
  const tx = fx - x0;
57
58
  const ty = fy - y0;
58
59
  const at = (i: number, j: number): number => rng(((j % cells) * cells + (i % cells)) * 1.37);
59
- const sx = tx * tx * (3 - 2 * tx);
60
- const sy = ty * ty * (3 - 2 * ty);
60
+ const sx = MathUtils.smoothstep(tx, 0, 1);
61
+ const sy = MathUtils.smoothstep(ty, 0, 1);
61
62
  const top = at(x0, y0) + (at(x0 + 1, y0) - at(x0, y0)) * sx;
62
63
  const bottom = at(x0, y0 + 1) + (at(x0 + 1, y0 + 1) - at(x0, y0 + 1)) * sx;
63
64
  return top + (bottom - top) * sy;
@@ -24,6 +24,9 @@ export const palette = {
24
24
  export const C = {
25
25
  grassDark: 0x4e7a2a,
26
26
  grassTip: 0x7f9e44,
27
+ /** The streamed grass: the dark root shade and the colour dry patches drift toward. */
28
+ grassRoot: 0x3b5a1d,
29
+ grassDry: 0xa89a4c,
27
30
  dirt: 0x8b6a48,
28
31
  path: 0xb39a72,
29
32
  stoneDark: 0x5d5a52,
@@ -36,6 +36,9 @@ const STICK_RADIUS = 72;
36
36
  const BUTTON_RADIUS = 46;
37
37
  const EDGE = 36;
38
38
 
39
+ /** The resting stick centre: `update` runs every frame, so it uses one instance. */
40
+ const restPoint = new Vector2();
41
+
39
42
  /** Where each button sits: a quarter-circle fan around the bottom-right corner. */
40
43
  function buttonPoint(size: ITouchViewport, index: number): Vector2 {
41
44
  const cx = size.width - EDGE - BUTTON_RADIUS;
@@ -84,7 +87,7 @@ export class TouchControls {
84
87
  }
85
88
 
86
89
  update(pointers: ReadonlyMap<number, ITouchPointer>, size: ITouchViewport): ITouchInput {
87
- const rest = new Vector2(STICK_RADIUS + EDGE, size.height - STICK_RADIUS - EDGE);
90
+ const rest = restPoint.set(STICK_RADIUS + EDGE, size.height - STICK_RADIUS - EDGE);
88
91
  let thumb: ITouchPointer | undefined;
89
92
  for (const pointer of pointers.values()) {
90
93
  if (pointer.position.x < size.width * 0.45 && pointer.position.y > size.height * 0.4) {
@@ -1,11 +1,13 @@
1
1
  import {
2
2
  GPUParticles3D,
3
+ GrassField3D,
3
4
  Scene,
4
5
  type SceneFrame,
5
6
  afterPhysics,
6
7
  isMobile,
7
8
  isTouchscreenAvailable,
8
9
  } from "@threenative/core";
10
+ import { warmUnculled } from "@threenative/core/world";
9
11
  import { type IPhysicsContext, buildStaticColliders } from "@threenative/physics";
10
12
  import {
11
13
  Box3,
@@ -38,8 +40,13 @@ import { Warden } from "../entities/Warden.js";
38
40
  import { Interactions } from "../interact.js";
39
41
  import { type IHollow, buildHollow } from "../level/Hollow.js";
40
42
  import {
43
+ GRASS_BOUNDS,
41
44
  type IVale,
45
+ type IWoodlandFloor,
46
+ STREAM,
42
47
  buildVale,
48
+ buildWoodlandFloor,
49
+ grassCover,
43
50
  isSolid,
44
51
  makeRng,
45
52
  measureRelief,
@@ -47,10 +54,12 @@ import {
47
54
  } from "../level/Vale.js";
48
55
  import { setupCamera } from "../render/camera.js";
49
56
  import { BURSTS, EFFECTS } from "../render/effects.js";
57
+ import { grassBlade, grassMaterial, grassStandAt } from "../render/grass.js";
50
58
  import { setupLighting } from "../render/lighting.js";
51
59
  import { createLoadingScreen } from "../render/loading.js";
52
60
  import { setupPost } from "../render/postprocessing.js";
53
61
  import { createCompanion, createHeartVessel } from "../render/props.js";
62
+ import { resolveQualityTier } from "../render/quality.js";
54
63
  import { type ISky, createSky, setupSky } from "../render/sky.js";
55
64
  import { loadSurfaces, untexturedSurfaces, updateSurfaceSampling } from "../render/surface.js";
56
65
  import { TouchControls } from "../render/touch-controls.js";
@@ -126,6 +135,8 @@ export class Play extends Scene<GameState, IPhysicsContext> {
126
135
 
127
136
  #sky: ISky | undefined;
128
137
  #vale: IVale | undefined;
138
+ #floor: IWoodlandFloor | undefined;
139
+ #grass: GrassField3D | undefined;
129
140
  #hollow: IHollow | undefined;
130
141
  #hero: Hero | undefined;
131
142
  #dummies: Dummy[] = [];
@@ -147,6 +158,20 @@ export class Play extends Scene<GameState, IPhysicsContext> {
147
158
  this.#sky = createSky();
148
159
  setupSky(ctx.scene, this.#sky);
149
160
  const vale = buildVale(makeRng(1986));
161
+ // The forest floor: baked debris and ferns scattered under the old trees (PRD-889). The `low`
162
+ // tier (a software adapter, or a GPU the tier table rates low) leaves it out: on a CPU adapter
163
+ // it held the first frame window past three minutes. Pass `tier` here to force it either way.
164
+ const tier = resolveQualityTier({
165
+ gpuClass: ctx.renderer.gpuClass?.class,
166
+ mobile: isMobile(),
167
+ software: ctx.renderer.softwareAdapter !== undefined,
168
+ });
169
+ if (tier === "low") console.info("TN_WOODLAND_FLOOR off: quality tier low");
170
+ else {
171
+ const floor = await buildWoodlandFloor(ctx.assets, vale);
172
+ vale.group.add(floor.group);
173
+ this.#floor = floor;
174
+ }
150
175
  const hollow = buildHollow(makeRng(1998));
151
176
  this.#vale = vale;
152
177
  this.#hollow = hollow;
@@ -157,6 +182,54 @@ export class Play extends Scene<GameState, IPhysicsContext> {
157
182
  hero.mesh.position.set(vale.spawn.x, vale.spawn.y + FOOT_OFFSET, vale.spawn.z);
158
183
  hero.mesh.rotation.y = vale.spawnYaw;
159
184
  this.#hero = ctx.entities.add("player", hero);
185
+ // The vale's grass: streamed chunks round the camera, its look in `render/grass.ts`. It lives in
186
+ // the vale's group, so it hides with the vale when Wren is in the Hollow.
187
+ const grass = new GrassField3D({
188
+ blade: grassBlade(),
189
+ bounds: GRASS_BOUNDS,
190
+ // Bigger chunks are fewer draws: the engine's per-draw cost outweighed finer culling here.
191
+ buildBudgetMs: 2,
192
+ chunkSize: 16,
193
+ density: 18,
194
+ drawDistance: 40,
195
+ // Thinned under the old trees, where the floor's litter lies: knee-high grass over a flat leaf
196
+ // layer hides the very thing the layer is there to show.
197
+ getDensity: (x: number, z: number) => grassCover(x, z) * (1 - 0.78 * vale.floorZone(x, z)),
198
+ getHeight: valeHeight,
199
+ lodDistances: [7, 16],
200
+ material: grassMaterial,
201
+ minAltitude: STREAM.water + 0.05,
202
+ thinEnd: 30,
203
+ thinStart: 6,
204
+ });
205
+ vale.group.add(grass);
206
+ this.#grass = grass;
207
+ // What a scenario reads: how many chunks draw, and how high a blade stands beside Wren.
208
+ const standAt = (dx: number): number => {
209
+ const x = hero.mesh.position.x + dx;
210
+ const z = hero.mesh.position.z;
211
+ return grassStandAt(grass.pressAt(x, valeHeight(x, z), z));
212
+ };
213
+ ctx.entities.add("grass", {
214
+ debug: () => ({
215
+ blades: grass.stats.blades,
216
+ pending: grass.stats.pending,
217
+ standFar: standAt(3),
218
+ standNear: standAt(0.5),
219
+ visibleChunks: grass.stats.visibleChunks,
220
+ }),
221
+ });
222
+ ctx.entities.add("floor", {
223
+ debug: () => {
224
+ // No fields when the `low` tier left the floor out, so every total reads 0.
225
+ const fields = this.#floor?.fields ?? [];
226
+ return {
227
+ instances: fields.reduce((total, field) => total + field.stats.instances, 0),
228
+ tiles: fields.reduce((total, field) => total + field.stats.tiles, 0),
229
+ visibleTiles: fields.reduce((total, field) => total + field.stats.visibleTiles, 0),
230
+ };
231
+ },
232
+ });
160
233
  vale.dummies.forEach((at, i) => {
161
234
  this.#dummies.push(ctx.entities.add(`dummy.${i}`, new Dummy(`dummy.${i}`, at)));
162
235
  });
@@ -209,6 +282,26 @@ export class Play extends Scene<GameState, IPhysicsContext> {
209
282
  this.#sky === undefined
210
283
  )
211
284
  throw new Error("Play.enter ran before load() built the world.");
285
+ const floor = this.#floor;
286
+ if (floor !== undefined) {
287
+ floor.prewarm();
288
+ ctx.beforeRender(() => {
289
+ if (vale.group.visible) floor.update(hero.mesh.position);
290
+ });
291
+ }
292
+ const grass = this.#grass;
293
+ if (grass !== undefined) {
294
+ // Once per drawn frame: Wren's feet flatten the grass, then the field streams round the camera.
295
+ grass.prewarm();
296
+ ctx.beforeRender(() => {
297
+ if (!vale.group.visible) return;
298
+ const at = hero.mesh.position;
299
+ grass.pushers[0]?.set(at.x, at.y - FOOT_OFFSET, at.z, 1.2);
300
+ grass.update(ctx.camera);
301
+ });
302
+ // The first chunks draw unculled so their pipeline compiles behind the loading curtain.
303
+ ctx.startup.hold("grass", warmUnculled(ctx, grass));
304
+ }
212
305
  ctx.beforeRender(() => {
213
306
  updateSurfaceSampling(
214
307
  ctx.renderer.temporalUpscale?.() === true ? ctx.renderer.surface().resolutionScale : 1,
@@ -609,7 +702,7 @@ export class Play extends Scene<GameState, IPhysicsContext> {
609
702
  hero.mesh.position.z - f.x * 0.7 - f.z * 0.4 + Math.sin(orb.clock * 1.3) * 0.15,
610
703
  );
611
704
  if (companion.group.position.distanceTo(orbGoal) > 6) companion.group.position.copy(orbGoal);
612
- else companion.group.position.lerp(orbGoal, 1 - Math.exp(-dt * 4));
705
+ else companion.group.position.lerp(orbGoal, MathUtils.damp(0, 1, 4, dt));
613
706
  const orbGap = companion.group.position.distanceTo(head);
614
707
  orb.nearest = Math.min(orb.nearest, orbGap);
615
708
  orb.farthest = Math.max(orb.farthest, orbGap);
@@ -774,6 +867,8 @@ export class Play extends Scene<GameState, IPhysicsContext> {
774
867
  Object.assign(seen, { blocks: hero.shieldBlocks, clanks, hits: hero.slashHits });
775
868
  warden.update(dt, hero);
776
869
  for (const dummy of dummies) dummy.update(dt);
870
+ // Everything that moves has moved, so the lock's bounds and reticle are this frame's pose.
871
+ lock.place(camera, dt);
777
872
  // A target falls inside Wren's slash, so count the fallen after everything has moved.
778
873
  for (const fallen of targets) {
779
874
  if (fallen.alive || counted.has(fallen)) continue;
@@ -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: #1d3a5c;
@@ -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(),
@@ -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 studio # open the game in Studio
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`.
@@ -85,12 +87,15 @@ Each is on by default with a named override. Detail: `node_modules/create-threen
85
87
  - **Frame spans** `#spans`: off. Override: `TN_FRAME_SPANS=1`. Marker: `TN_FRAME_SPANS`.
86
88
  - **Multiplayer** `#net`: none; unsupported transport rejects. Override: `connect` from `@threenative/core/net` with four limits. Marker: `TN_NET_UNAVAILABLE`.
87
89
  - **Desktop window** `#desktop-mode`: CLI, then `display.fullscreen`, then `window.maximized`. Override: `--windowed`; `--maximized`; `--fullscreen`.
90
+ - **CPU priority** `#cpu-priority`: game threads first. Override: `display.priority: "normal"`. Marker: `TN_PROCESS_PRIORITY`.
88
91
  - **Terrain** `#terrain`: authored in the game. Override: optional `@threenative/terrain`; `references/terrain-authoring.md`.
89
92
  - **Navigation** `#navigation`: none; browser-only WASM. Override: import `@threenative/physics/navigation` on purpose.
93
+ - **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`.
90
94
  - **Move input** `#move-axis`: `input.vector("move").y` is +up. Override: one explicit `-move.y` conversion.
91
95
  - **Scene change** `#scene-change`: `ctx.goto(name)` keeps state. Override: `game.goto(name)` resets state.
92
96
  - **Randomness** `#seed`: unseeded. Override: `defineGame({ seed })`.
93
97
  - **Engine** `#engine`: owned C++ engine. Override: `engine: "threejs"` only when the user asks. Marker: `TN_NATIVE_ENGINE_UNBOUND`.
98
+ - **Refused imports** `#engine-catalog`: refused `three` imports fail at their line. Override: `createEngineCatalogPlugin({ mode: "warn" })`. Marker: `TN_ENGINE_CATALOG`.
94
99
  <!-- /shared -->
95
100
 
96
101
  <!-- shared: kit-stuck -->