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
@@ -3,7 +3,7 @@
3
3
 
4
4
  # Capability reference
5
5
 
6
- Every public class and function export represented by this manifest across `@threenative/assets`, `@threenative/core`, `@threenative/metahuman`, `@threenative/physics`, `@threenative/playtest`, `@threenative/procedural-animals`, `@threenative/raw-unreal`, `@threenative/terrain`, `@threenative/ueformat`, `@threenative/ui`, `template:rain`, `template:starter`, and `three`,
6
+ Every public class and function export represented by this manifest across `@threenative/assets`, `@threenative/core`, `@threenative/metahuman`, `@threenative/physics`, `@threenative/playtest`, `@threenative/procedural-animals`, `@threenative/procedural-vegetation`, `@threenative/raw-unreal`, `@threenative/terrain`, `@threenative/ueformat`, `@threenative/ui`, `template:rain`, `template:starter`, and `three`,
7
7
  generated from the doc tags the engine itself compiles, so this page cannot disagree with
8
8
  the code. Look here before writing a replacement; ask `engine_search_capabilities` when an
9
9
  MCP server is available.
@@ -227,8 +227,9 @@ pnpm census:content public/assets
227
227
  export function modelPass(options: IModelPassOptions = { … }
228
228
  ```
229
229
 
230
- - **Use when:** reduce a model's download and GPU footprint · optimize a GLB before shipping it with a game
231
- - **Constraints:** the pass self-verifies reachable geometry, animation, bounds, and embedded texture bindings before returning output
230
+ - **Use when:** reduce a model's download and GPU footprint · optimize a GLB before shipping it with a game · texture bytes too big after the model cook · a KTX2 model texture came out larger than its WebP or JPEG source · choose ETC1S or UASTC for a model's embedded textures · model texture codec ladder · keep smaller source texture · TN_ASSETS_COMPRESSION_SKIPPED
231
+ - **Constraints:** the pass self-verifies reachable geometry, animation, bounds, and embedded texture bindings before returning output · each colour texture climbs a codec ladder (ETC1S, then UASTC with RDO, then plain UASTC) and keeps the smallest rung that meets the quality floor (SSIM 0.95, ΔE00 3); a data slot such as a normal or metallic-roughness map takes UASTC only, as ETC1S is forbidden there (`TN_ASSETS_TEXTURE_SLOT_CODEC`); a result is kept only when it is smaller than the source, else the source stays and the report says `not-smaller` · a PNG or JPEG source can always be kept; a WebP source can be kept only on a web target, whose runtimes all decode WebP, so on desktop and mobile it always becomes KTX2
232
+ - **Overrides:** `textures: { overrides: [{ slot: "baseColorTexture", codec: "uastc" }] }` forces one glTF slot's codec (`etc1s`, `uastc` or `none`); `textures: { floor }` moves the quality floor; `textures: "none"` keeps every embedded texture as authored
232
233
 
233
234
  ```ts
234
235
  const pass = modelPass({ simplify: { ratio: 0.5 } });
@@ -1026,9 +1027,9 @@ const counters = FrameCounters.install(counterDeviceOf(renderer.raw));
1026
1027
  export function createAssetLoader(options: IAssetLoaderOptions = { … }
1027
1028
  ```
1028
1029
 
1029
- - **Use when:** preload models, textures, or audio before a scene enters · keep downloaded web assets on disk between visits · download the next scene before the player gets there · free the disk cache from a settings menu · prefetch assets into the Cache Storage disk cache of a large web game · load assets from a nonstandard base path or a compiled asset manifest
1030
- - **Constraints:** reuse the loader handed to scenes as `ctx.assets` instead of building parallel caches · await everything the spawn camera sees before the reveal; `ctx.assets.prefetch` and the background fill are for content out of view, or the player spawns into a half-built world · web only: a native host reads installed files, so `ctx.assets.cache` reports `enabled: false` with the reason and `prefetch` resolves at once
1031
- - **Overrides:** `assets.cache: false` turns the disk cache off and `assets.backgroundFill: false` turns the post-reveal fill off; both are reported on `ctx.assets.cache`
1030
+ - **Use when:** preload models, textures, or audio before a scene enters · keep downloaded web assets on disk between visits · download the next scene before the player gets there · free the disk cache from a settings menu · prefetch assets into the Cache Storage disk cache of a large web game · load assets from a nonstandard base path or a compiled asset manifest · stream a large game: boot on the spawn bytes and prefetch the rest · make the first scene play before the whole game finishes downloading · draw a heavy model's coarsest level first and its full detail when the file lands · draw a model's textures at their resident mips first and the whole files later · coarse first model streaming · streamMeshes and streamTextures: stream the meshes and textures of a model · mip streaming textures · TN_STREAMING_POOL · TN_ASSET_LATE · an asset pops in after the reveal and the game needs to count it · a model texture looks blurry or low resolution right after load, then sharpens · build a collider or navmesh from a streamed model only once its full file landed · compressed texture upload on the owned engine (KTX2 to BC7 or ETC2 on the GPU) · load a model with KHR_texture_basisu or EXT_meshopt_compression on the owned engine · stream a finer mip level into a CompressedTexture that already draws · KTX2Loader on the owned engine · CompressedTexture upload · TN_TEXTURE_TRANSCODE_TARGET · TN_NATIVE_TEXTURE_UNSUPPORTED · webRuntimeDecoders meshopt ktx2
1031
+ - **Constraints:** reuse the loader handed to scenes as `ctx.assets` instead of building parallel caches · await everything the spawn camera sees before the reveal; `ctx.assets.prefetch` and the background fill are for content out of view, or the player spawns into a half-built world · a whole-file load requested after the reveal that the game had not `prefetch`ed logs one `TN_ASSET_LATE` line with its bytes, so a pop-in is countable from a playtest · web only: a native host reads installed files, so `ctx.assets.cache` reports `enabled: false` with the reason and `prefetch` resolves at once · streaming is engine-owned and on by default: a cooked LOD-chained model loads its `.coarse.<digest>.glb` companion first, then the full file at "soon" priority, and the full geometry replaces the coarse in place (clones and the projection mirror included); a failed coarse load falls back to the whole file and logs `TN_ASSETS_STREAM_FAILED` · texture streaming rides on the coarse parse: each shared `.ktx2` of that model is read by `Range` as its resident mips (the header and the tail), and the whole files replace them when the full model lands; a host without `Range` sends the whole file and keeps it whole. `TN_STREAMING_POOL` reports `files`, `residentBytes`, `fullBytes`, `deferredBytes` and `upgraded` once, two seconds after the last change · the whole texture keeps what the game set on the resident one (`anisotropy`, wrap, filters, offset, repeat, `userData`), so the swap changes the mips and nothing else · every web build cooks meshopt geometry and KTX2 textures for both engines (`webRuntimeDecoders` in create-threenative answers `{ ktx2: true, meshopt: true }`); the owned engine's glTF loader decodes both itself, with no JS decoder · the owned engine transcodes a KTX2 image to BC7 on a device with `texture-compression-bc`, else ETC2, else RGBA8 with an engine mip chain, and prints `TN_TEXTURE_TRANSCODE_TARGET <target>` once; a block format needs a width and height that are multiples of 4, so any other size stays RGBA8 and the same line names it · a three `CompressedTexture` (format plus `mipmaps`) uploads one GPU write per level; a block format the device lacks throws `TN_NATIVE_TEXTURE_UNSUPPORTED` by name instead of drawing garbage · levels are coarse-first: a level whose `mipmaps[i].data` is null is not resident and the texture samples its finest resident level; set `mipmaps[i].data` and `needsUpdate = true` to write that one finer level in place, without re-creating the texture or rewriting the other levels
1032
+ - **Overrides:** `assets.cache: false` turns the disk cache off and `assets.backgroundFill: false` turns the post-reveal fill off; both are reported on `ctx.assets.cache` · `ctx.assets.model(path, { whole: true })` resolves only once the full file has replaced the coarse companion, for a collider or navmesh that copies vertices once · `assets.streamMeshes: false` loads every model whole (reported once as `TN_ASSETS_STREAM_MESHES_OFF`); `assets.streamTextures: false` loads every model texture whole (`TN_ASSETS_STREAM_TEXTURES_OFF`) · `engine: "threejs"` runs three's own `KTX2Loader` and `MeshoptDecoder` in JS instead of the owned engine's decoders
1032
1033
 
1033
1034
  ```ts
1034
1035
  const assets = createAssetLoader({ basePath: "/assets" });
@@ -1108,7 +1109,7 @@ ctx.add(daylight);
1108
1109
  export function debugFlag(name: string): boolean { … }
1109
1110
  ```
1110
1111
 
1111
- - **Use when:** read a debug toggle from the URL or an environment variable
1112
+ - **Use when:** read a debug toggle from the URL, an environment variable or a harness global
1112
1113
  - **Constraints:** a name in camelCase becomes UPPER_SNAKE: `debugFlag("freeCam")` reads `?freeCam` or `TN_DEBUG_FREE_CAM` · `0` and `false` are off, so a saved URL cannot turn a switch back on
1113
1114
 
1114
1115
  ```ts
@@ -1116,6 +1117,22 @@ import { debugFlag } from "@threenative/core";
1116
1117
  if (debugFlag("freeCam")) camera.flyMode = true;
1117
1118
  ```
1118
1119
 
1120
+ ### `debugValue`
1121
+
1122
+ `function` — Read the text a debug switch was given by the launch, on the same rule as `debugFlag`.
1123
+
1124
+ ```ts
1125
+ export function debugValue(name: string): string | undefined { … }
1126
+ ```
1127
+
1128
+ - **Use when:** read a debug override whose value is not a boolean · override a quality tier or a mode for one run without changing the code
1129
+ - **Constraints:** the same name rule as `debugFlag`: `?quality=` on the web, `TN_DEBUG_QUALITY` on a native launch · a name in camelCase becomes UPPER_SNAKE: `debugValue("quality")` reads `?quality=` or `TN_DEBUG_QUALITY`
1130
+
1131
+ ```ts
1132
+ import { debugValue } from "@threenative/core";
1133
+ const tier = debugValue("quality");
1134
+ ```
1135
+
1119
1136
  ### `defineGame`
1120
1137
 
1121
1138
  `function` — Define the portable game entry shared by web and native.
@@ -1161,6 +1178,22 @@ export function describeSceneWarning(warning: ISceneWarning): string { … }
1161
1178
  defineGame({ display: { maxFps: 60 }, scenes: { Play } });
1162
1179
  ```
1163
1180
 
1181
+ ### `devGlobal`
1182
+
1183
+ `function` — The one name every dev surface publishes under, and the reader/writer for it.
1184
+
1185
+ ```ts
1186
+ export function devGlobal(scope: unknown): DevGlobal | undefined { … }
1187
+ ```
1188
+
1189
+ - **Use when:** read or extend the `__THREENATIVE__` object a dev launch publishes
1190
+ - **Constraints:** every dev surface publishes under this key; the worker's typed mirror tuple names it too
1191
+
1192
+ ```ts
1193
+ import { DEV_GLOBAL_KEY, devGlobal } from "@threenative/core";
1194
+ const tools = devGlobal(globalThis);
1195
+ ```
1196
+
1164
1197
  ### `directionalTransmittance`
1165
1198
 
1166
1199
  `function` — Approximate direct transmittance for a ray leaving the game surface.
@@ -1319,6 +1352,21 @@ export function exposureFromEv100(ev100: number): number { … }
1319
1352
  renderer.toneMappingExposure = exposureFromEv100(ev100FromCamera(4, 1 / 60, 100));
1320
1353
  ```
1321
1354
 
1355
+ ### `fetchAsset`
1356
+
1357
+ `function` — Fetch a data file the asset loader serves: each url `assets.resolve(path)` names, in order, until one answers ok. A built game serves the hashed output and a dev server the source path, so taking only the first url 404s on one of them. When none answers it throws `TN_ASSET_NOT_SERVED` naming every url tried and why, so a missing file is never a half-drawn world.
1358
+
1359
+ ```ts
1360
+ export async function fetchAsset( assets: Pick<IAssetLoader, "resolve">, path: string, ): Promise<Response> { … }
1361
+ ```
1362
+
1363
+ - **Use when:** load a baked JSON or binary file (a heightmap, a placement buffer, a data table) that the loader has no typed method for · a data file loads in dev but 404s in the built game
1364
+ - **Constraints:** reads the response once; call `.json()` or `.arrayBuffer()` on the result
1365
+
1366
+ ```ts
1367
+ const heights = new Float32Array(await (await fetchAsset(ctx.assets, "world/forest.bin")).arrayBuffer());
1368
+ ```
1369
+
1322
1370
  ### `FlightModel`
1323
1371
 
1324
1372
  `class` — Fly a fixed-wing aircraft with a real force balance instead of a steered velocity.
@@ -1486,11 +1534,12 @@ model.step(1 / 60, { turn: -1, pitch: 0.4 });
1486
1534
  export function getPlatform(): Readonly<IPlatformInfo> { … }
1487
1535
  ```
1488
1536
 
1489
- - **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native
1537
+ - **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native · show gamepad prompts and bind pad buttons on a games console such as the PS4
1490
1538
  - **Constraints:** only use the returned platform facts; native globals are host-owned · image ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result · a native desktop host with ray tracing hardware traces ray batches with `mystralRT.traceRayBatch`, which writes hit records into a typed array you own; read `mystralRT.capabilities().rayBatch` first, and keep the software BVH trace for the web and every other host · when `mystralRT.capabilities().sharedTransport` is true, `mystralRT.traceRayBatchGpu({ tlas, rays, hits, rayCount })` traces between two GPUBuffers with no copy through CPU memory; `rays` needs the CopySrc usage and `hits` the CopyDst usage, and each call costs CPU time, so measure it against the software trace for your batch size
1491
1539
 
1492
1540
  ```ts
1493
1541
  if (isMobile()) showTouchControls();
1542
+ if (isConsole()) showPadPrompts(isPs4() ? "dualshock" : "generic");
1494
1543
  ```
1495
1544
 
1496
1545
  ### `GIBudget`
@@ -1573,6 +1622,25 @@ export class GPUSceneBVH extends Group implements IComputeDriven { … }
1573
1622
  const bvh = ctx.add(new GPUSceneBVH(ctx.scene, { include: (object) => object.userData.traceable === true }));
1574
1623
  ```
1575
1624
 
1625
+ ### `GrassField3D`
1626
+
1627
+ `class` — Stream instanced grass in chunks around the camera; the game owns the blade and its TSL material.
1628
+
1629
+ ```ts
1630
+ export class GrassField3D extends Group { … }
1631
+ ```
1632
+
1633
+ - **Use when:** grass that sways and parts around the player · a meadow, lawn or grassy field over terrain that streams around the camera · ground cover grass blades with distance thinning and LOD that does not pop · grass flattened or pushed aside where the player, a creature or a vehicle walks · grow grass on a terrain biome's grass rows with grassFieldFromBiome · Grass that sways and parts around the player across a large terrain. · Stream instanced ground cover in chunks around the camera under a frame budget. · Meadow, lawn or field grass with distance thinning and LOD that does not pop.
1634
+ - **Constraints:** call `update(camera)` once per rendered frame from `ctx.beforeRender`; chunks build nearest first inside `buildBudgetMs` · the material reads `GRASS_FIELD_ATTRIBUTES` and the field's `nodes` uniforms, so its thinning matches the CPU trim · a chunk is built inside 1.3 × the draw distance and discarded past 1.4 ×, so a camera on the edge rebuilds nothing · Call `update(camera)` once per rendered frame, from `ctx.beforeRender`. · Rotating or scaling the field is not supported; translating it is.
1635
+ - **Overrides:** densityScale and cullDistanceScale scale every density and distance at once; prewarm() builds all in range on the next update
1636
+
1637
+ ```ts
1638
+ // the look lives in the kit's src/render/grass.ts
1639
+ const grass = new GrassField3D({ blade: grassBlade(), material: grassMaterial, getHeight: height });
1640
+ ctx.add(grass);
1641
+ ctx.beforeRender(() => { grass.pushers[0]?.set(hero.x, hero.y, hero.z, 1.2); grass.update(ctx.camera); });
1642
+ ```
1643
+
1576
1644
  ### `GroundSnap`
1577
1645
 
1578
1646
  `class` — Keep a rendered model's feet on a surface while preserving an auditable override.
@@ -1598,8 +1666,9 @@ const snap = new GroundSnap(character, { enabled: true });
1598
1666
  export class InputMap { … }
1599
1667
  ```
1600
1668
 
1601
- - **Use when:** map WASD keys to a movement axis instead of reading the held key set in the update loop · read a jump, a fire or a reload as one named action bound to key, gamepad button and mouse button together · read mouse look, wheel zoom or a two-finger pinch as an axis the frame loop already ticks
1602
- - **Constraints:** `buttons` is the gamepad and `mouseButtons` the mouse; `up`/`down`/`left`/`right` are the directions of `vector(name)`, not the keys that press it · scroll, pinch and pointer-relative sources are declared on the binding and read through `axis(name)`; a game adds no window listener of its own
1669
+ - **Use when:** map WASD keys to a movement axis instead of reading the held key set in the update loop · read a jump, a fire or a reload as one named action bound to key, gamepad button and mouse button together · read mouse look, wheel zoom or a two-finger pinch as an axis the frame loop already ticks · support an Xbox pad, a generic XInput clone, an 8BitDo or a Steam Deck controller · the character drifts while the controller stick is idle · the controller does nothing in Firefox on Linux · a second controller or a wheel steals the input from the pad the player holds
1670
+ - **Constraints:** `buttons` is the gamepad and `mouseButtons` the mouse; `up`/`down`/`left`/`right` are the directions of `vector(name)`, not the keys that press it · scroll, pinch and pointer-relative sources are declared on the binding and read through `axis(name)`; a game adds no window listener of its own · gamepad buttons are W3C standard indices on every pad: 0 south (A/Cross), 1 east, 2 west, 3 north, 4/5 shoulders, 6/7 triggers, 8 select, 9 start, 10/11 stick clicks; axes 0..3 are the sticks · both sticks carry a radial dead zone, `0.2` by default, reported per connected pad as `TN_GAMEPAD`; a pad the browser reports unmapped and the table does not know is ignored, never read with raw indices · a pad claims the input when a button goes down or a stick travels past half tilt, and keeps it while idle so its releases read; a stick resting past the dead zone or jittering across it claims nothing, so an idle pad in the first slot cannot steal input
1671
+ - **Overrides:** defineGame({ gamepadDeadZone: 0 }) publishes raw axes
1603
1672
 
1604
1673
  ```ts
1605
1674
  const game = defineGame({ input: { move: { up: ["KeyW"], down: ["KeyS"], left: ["KeyA"], right: ["KeyD"] } }, scenes: { Play } });
@@ -1670,6 +1739,22 @@ export function invalidateStatic(object: Object3D): number | undefined { … }
1670
1739
  invalidateStatic(drawbridge);
1671
1740
  ```
1672
1741
 
1742
+ ### `isConsole`
1743
+
1744
+ `function` — Read the host platform without reaching for browser globals.
1745
+
1746
+ ```ts
1747
+ export function isConsole(): boolean { … }
1748
+ ```
1749
+
1750
+ - **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native · show gamepad prompts and bind pad buttons on a games console such as the PS4
1751
+ - **Constraints:** only use the returned platform facts; native globals are host-owned · image ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result · a native desktop host with ray tracing hardware traces ray batches with `mystralRT.traceRayBatch`, which writes hit records into a typed array you own; read `mystralRT.capabilities().rayBatch` first, and keep the software BVH trace for the web and every other host · when `mystralRT.capabilities().sharedTransport` is true, `mystralRT.traceRayBatchGpu({ tlas, rays, hits, rayCount })` traces between two GPUBuffers with no copy through CPU memory; `rays` needs the CopySrc usage and `hits` the CopyDst usage, and each call costs CPU time, so measure it against the software trace for your batch size
1752
+
1753
+ ```ts
1754
+ if (isMobile()) showTouchControls();
1755
+ if (isConsole()) showPadPrompts(isPs4() ? "dualshock" : "generic");
1756
+ ```
1757
+
1673
1758
  ### `isMobile`
1674
1759
 
1675
1760
  `function` — Read the host platform without reaching for browser globals.
@@ -1678,11 +1763,12 @@ invalidateStatic(drawbridge);
1678
1763
  export function isMobile(): boolean { … }
1679
1764
  ```
1680
1765
 
1681
- - **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native
1766
+ - **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native · show gamepad prompts and bind pad buttons on a games console such as the PS4
1682
1767
  - **Constraints:** only use the returned platform facts; native globals are host-owned · image ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result · a native desktop host with ray tracing hardware traces ray batches with `mystralRT.traceRayBatch`, which writes hit records into a typed array you own; read `mystralRT.capabilities().rayBatch` first, and keep the software BVH trace for the web and every other host · when `mystralRT.capabilities().sharedTransport` is true, `mystralRT.traceRayBatchGpu({ tlas, rays, hits, rayCount })` traces between two GPUBuffers with no copy through CPU memory; `rays` needs the CopySrc usage and `hits` the CopyDst usage, and each call costs CPU time, so measure it against the software trace for your batch size
1683
1768
 
1684
1769
  ```ts
1685
1770
  if (isMobile()) showTouchControls();
1771
+ if (isConsole()) showPadPrompts(isPs4() ? "dualshock" : "generic");
1686
1772
  ```
1687
1773
 
1688
1774
  ### `isNative`
@@ -1693,11 +1779,28 @@ if (isMobile()) showTouchControls();
1693
1779
  export function isNative(): boolean { … }
1694
1780
  ```
1695
1781
 
1696
- - **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native
1782
+ - **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native · show gamepad prompts and bind pad buttons on a games console such as the PS4
1697
1783
  - **Constraints:** only use the returned platform facts; native globals are host-owned · image ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result · a native desktop host with ray tracing hardware traces ray batches with `mystralRT.traceRayBatch`, which writes hit records into a typed array you own; read `mystralRT.capabilities().rayBatch` first, and keep the software BVH trace for the web and every other host · when `mystralRT.capabilities().sharedTransport` is true, `mystralRT.traceRayBatchGpu({ tlas, rays, hits, rayCount })` traces between two GPUBuffers with no copy through CPU memory; `rays` needs the CopySrc usage and `hits` the CopyDst usage, and each call costs CPU time, so measure it against the software trace for your batch size
1698
1784
 
1699
1785
  ```ts
1700
1786
  if (isMobile()) showTouchControls();
1787
+ if (isConsole()) showPadPrompts(isPs4() ? "dualshock" : "generic");
1788
+ ```
1789
+
1790
+ ### `isPs4`
1791
+
1792
+ `function` — Read the host platform without reaching for browser globals.
1793
+
1794
+ ```ts
1795
+ export function isPs4(): boolean { … }
1796
+ ```
1797
+
1798
+ - **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native · show gamepad prompts and bind pad buttons on a games console such as the PS4
1799
+ - **Constraints:** only use the returned platform facts; native globals are host-owned · image ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result · a native desktop host with ray tracing hardware traces ray batches with `mystralRT.traceRayBatch`, which writes hit records into a typed array you own; read `mystralRT.capabilities().rayBatch` first, and keep the software BVH trace for the web and every other host · when `mystralRT.capabilities().sharedTransport` is true, `mystralRT.traceRayBatchGpu({ tlas, rays, hits, rayCount })` traces between two GPUBuffers with no copy through CPU memory; `rays` needs the CopySrc usage and `hits` the CopyDst usage, and each call costs CPU time, so measure it against the software trace for your batch size
1800
+
1801
+ ```ts
1802
+ if (isMobile()) showTouchControls();
1803
+ if (isConsole()) showPadPrompts(isPs4() ? "dualshock" : "generic");
1701
1804
  ```
1702
1805
 
1703
1806
  ### `isStatic`
@@ -1715,6 +1818,21 @@ export function isStatic(root: Object3D): boolean { … }
1715
1818
  invalidateStatic(drawbridge);
1716
1819
  ```
1717
1820
 
1821
+ ### `isStreamedGeometry`
1822
+
1823
+ `function` — True while a geometry is the coarse companion a streamed model draws first (PRD-860), before its full file replaces it in place. A caller that copies vertices (a trimesh collider, a navmesh bake, a merge) waits with `ctx.assets.model(path, { whole: true })` instead of copying the coarse ones.
1824
+
1825
+ ```ts
1826
+ export function isStreamedGeometry(geometry: BufferGeometry): boolean { … }
1827
+ ```
1828
+
1829
+ - **Use when:** collider or navmesh built from a model is coarser than what is drawn · wait for the full model before copying its vertices · whole model before collision · TN_COLLIDER_COARSE
1830
+ - **Constraints:** `CollisionShape3D.fromMesh` with "trimesh" or "convexHull" on a streamed geometry warns `TN_COLLIDER_COARSE` naming the mesh and the `{ whole: true }` override, and still builds
1831
+
1832
+ ```ts
1833
+ const coarse = isStreamedGeometry(mesh.geometry);
1834
+ ```
1835
+
1718
1836
  ### `isTouchscreenAvailable`
1719
1837
 
1720
1838
  `function` — Read the host platform without reaching for browser globals.
@@ -1723,11 +1841,12 @@ invalidateStatic(drawbridge);
1723
1841
  export function isTouchscreenAvailable(): boolean { … }
1724
1842
  ```
1725
1843
 
1726
- - **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native
1844
+ - **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native · show gamepad prompts and bind pad buttons on a games console such as the PS4
1727
1845
  - **Constraints:** only use the returned platform facts; native globals are host-owned · image ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result · a native desktop host with ray tracing hardware traces ray batches with `mystralRT.traceRayBatch`, which writes hit records into a typed array you own; read `mystralRT.capabilities().rayBatch` first, and keep the software BVH trace for the web and every other host · when `mystralRT.capabilities().sharedTransport` is true, `mystralRT.traceRayBatchGpu({ tlas, rays, hits, rayCount })` traces between two GPUBuffers with no copy through CPU memory; `rays` needs the CopySrc usage and `hits` the CopyDst usage, and each call costs CPU time, so measure it against the software trace for your batch size
1728
1846
 
1729
1847
  ```ts
1730
1848
  if (isMobile()) showTouchControls();
1849
+ if (isConsole()) showPadPrompts(isPs4() ? "dualshock" : "generic");
1731
1850
  ```
1732
1851
 
1733
1852
  ### `isWeb`
@@ -1738,11 +1857,12 @@ if (isMobile()) showTouchControls();
1738
1857
  export function isWeb(): boolean { … }
1739
1858
  ```
1740
1859
 
1741
- - **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native
1860
+ - **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native · show gamepad prompts and bind pad buttons on a games console such as the PS4
1742
1861
  - **Constraints:** only use the returned platform facts; native globals are host-owned · image ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result · a native desktop host with ray tracing hardware traces ray batches with `mystralRT.traceRayBatch`, which writes hit records into a typed array you own; read `mystralRT.capabilities().rayBatch` first, and keep the software BVH trace for the web and every other host · when `mystralRT.capabilities().sharedTransport` is true, `mystralRT.traceRayBatchGpu({ tlas, rays, hits, rayCount })` traces between two GPUBuffers with no copy through CPU memory; `rays` needs the CopySrc usage and `hits` the CopyDst usage, and each call costs CPU time, so measure it against the software trace for your batch size
1743
1862
 
1744
1863
  ```ts
1745
1864
  if (isMobile()) showTouchControls();
1865
+ if (isConsole()) showPadPrompts(isPs4() ? "dualshock" : "generic");
1746
1866
  ```
1747
1867
 
1748
1868
  ### `lampPenumbraTangent`
@@ -2060,6 +2180,22 @@ export class ProbeVolume extends Object3D implements IComputeDriven { … }
2060
2180
  const probes = new ProbeVolume({ bounds, density: 0.5 }); ctx.add(probes); void probes.requestBake(scene);
2061
2181
  ```
2062
2182
 
2183
+ ### `publishDevGlobal`
2184
+
2185
+ `function` — The one name every dev surface publishes under, and the reader/writer for it.
2186
+
2187
+ ```ts
2188
+ export function publishDevGlobal(name: string, value: unknown, scope: unknown): void { … }
2189
+ ```
2190
+
2191
+ - **Use when:** read or extend the `__THREENATIVE__` object a dev launch publishes
2192
+ - **Constraints:** every dev surface publishes under this key; the worker's typed mirror tuple names it too
2193
+
2194
+ ```ts
2195
+ import { DEV_GLOBAL_KEY, devGlobal } from "@threenative/core";
2196
+ const tools = devGlobal(globalThis);
2197
+ ```
2198
+
2063
2199
  ### `qualityPreset`
2064
2200
 
2065
2201
  `function` — The quality tiers of the Unreal 5.8.3 look: what `high` (a desktop, Unreal's Epic), `medium` and `low` (a phone) turn on, how a GPU family picks its start tier, and the global illumination and shadow filter settings per tier named after Unreal's scalability levels. A `WorldEnvironment` with no options starts from `high`. `qualityTiers` holds the tier tables: `resolve` picks a start tier from a GPU class, `gi` and `shadow` read a tier's settings.
@@ -2076,6 +2212,22 @@ export function qualityPreset(tier: string): IWorldEnvironmentOptions { … }
2076
2212
  const world = new WorldEnvironment({ ...qualityPreset(qualityTiers.resolve({ gpuClass: renderer.gpuClass })), bloomEnabled: false });
2077
2213
  ```
2078
2214
 
2215
+ ### `RadianceCache`
2216
+
2217
+ `class` — A probe field of diffuse irradiance that refreshes by tracing the packed scene, with no scene draw: the radiance cache of a dynamic global-illumination pass. Probes in view refresh first, oldest first, within `numProbesToTraceBudget` a frame; a lamp toggled in game code or a sun that steps more than one degree re-traces them while the old values keep lighting the frame.
2218
+
2219
+ ```ts
2220
+ export class RadianceCache extends ProbeVolume { … }
2221
+ ```
2222
+
2223
+ - **Use when:** light follows a lamp that switches on and off in a room · bounce light that updates when the sun moves, with no baked lightmap · global illumination that refreshes fast enough to read as dynamic
2224
+ - **Constraints:** build a GPUSceneBVH of the static meshes first and pass it as trace.bvh; the cache reads colour and emissive from each material, a texture or a node is counted as ignored · add the cache with ctx.add() so its refresh is measured in the render phase, and read it with sampleNode(position, normal) from a game-owned material · a one-sided material is not seen from behind, as a cube capture would not draw it
2225
+ - **Overrides:** numProbesToTraceBudget (100), probeResolution (8, so 64 rays a probe; 32 for a small emitter), bounds, density, bounces and the sun and sky values are game-owned
2226
+
2227
+ ```ts
2228
+ const bvh = new GPUSceneBVH(ctx.scene); ctx.add(bvh); const cache = new RadianceCache({ bounds, density: 0.5, trace: { bvh, sun, sky, camera: ctx.camera } }); ctx.add(cache);
2229
+ ```
2230
+
2079
2231
  ### `readGIMarker`
2080
2232
 
2081
2233
  `function` — Parse a `TN_GI` console line back into its report, or `undefined`.
@@ -2445,6 +2597,24 @@ ripples.advance(dt);
2445
2597
  const lift = ripples.heightAt(boat.x, boat.z);
2446
2598
  ```
2447
2599
 
2600
+ ### `ScatterField3D`
2601
+
2602
+ `class` — Stream instanced copies of any baked mesh around a follow point, with distance thinning and levels of detail, from the game's own placement rule.
2603
+
2604
+ ```ts
2605
+ export class ScatterField3D extends Group { … }
2606
+ ```
2607
+
2608
+ - **Use when:** scatter fallen logs, twigs, leaf litter, stones and ferns over a forest floor · stream instanced props of any baked mesh round the player without one draw per prop · place rocks, debris or plants on a heightfield with distance thinning and level of detail
2609
+ - **Constraints:** call `update(follow)` once per rendered frame · `place` runs once per candidate per tile build: return false for paths and clearings · rotating or scaling the field is not supported; translating it is
2610
+ - **Requires:** npm i -D @threenative/procedural-vegetation for the bake these instances come from
2611
+
2612
+ ```ts
2613
+ const floor = new ScatterField3D({ parts: [{ lods, material }], getHeight, density: 0.05, place });
2614
+ ctx.add(floor);
2615
+ ctx.beforeRender(() => floor.update(hero.position));
2616
+ ```
2617
+
2448
2618
  ### `Scene`
2449
2619
 
2450
2620
  `class` — Implement a portable Godot-shaped game scene lifecycle.
@@ -2507,6 +2677,24 @@ const door = { y: 0 };
2507
2677
  await ctx.tween(door, { y: 2.4 }, 0.5, { ease: (t) => 1 - (1 - t) ** 3 });
2508
2678
  ```
2509
2679
 
2680
+ ### `ScreenProbeGather`
2681
+
2682
+ `class` — Lumen's Screen Probe Gather: one probe per 16 x 16 pixels traces an 8 x 8 octahedron of rays, the probes are filtered into an irradiance octahedron each, and a pixel blends the four nearest probes it can see, instead of every pixel tracing its own rays. A ray that hits on screen returns the lit frame minus the cache along it; a ray that leaves the screen continues through the packed scene up to the radiance cache's cell and reads the cache where it ended, so the light that arrives from off screen is that direction's and not the pixel's mean.
2683
+
2684
+ ```ts
2685
+ export class ScreenProbeGather { … }
2686
+ ```
2687
+
2688
+ - **Use when:** bounce light that reads the room off screen instead of a flat ambient term · global illumination that costs a fraction of one ray per pixel · the light a corner sees from around the wall, which a per-pixel screen trace loses · lumen screen probe gather · lumen final gather
2689
+ - **Constraints:** the owned engine only: on engine: "threejs" the upstream node takes the camera as its fourth argument and has no probes, and gather() refuses · the gather is a delta in E / pi: multiply it by the receiver's diffuse colour (mrt({ diffuseColor })) and add it after the scene pass, and give the scene pass no other indirect diffuse or the light is counted twice · a viewport resize needs a new gather: the probe grid is fixed when it is built · the grid is the cost: downsampleFactor 16 and an 8 x 8 octahedron are Unreal's Epic, 32 and 8 its High · radiance answers in the frame's units (the cache read times the frame's gain), and a trace reads it only where the screen has nothing
2690
+ - **Overrides:** downsampleFactor, tracingOctahedronResolution, cacheCellSize, timedPass and the strength of the composite are game-owned choices
2691
+
2692
+ ```ts
2693
+ const gather = new ScreenProbeGather({ camera, viewport, radiance, trace });
2694
+ const gi = gather.gather(convertToTexture(input), depth(), normalView());
2695
+ const bounce = gather.getGINode().rgb.mul(diffuseColor.rgb);
2696
+ ```
2697
+
2510
2698
  ### `setAttitude`
2511
2699
 
2512
2700
  `function` — Fly a fixed-wing aircraft with a real force balance instead of a steered velocity.
@@ -2555,6 +2743,24 @@ const filter = new ShadowFilterBudget({ tier: "high", framePeriodMs: 1000 / 60,
2555
2743
  ctx.beforeRender(() => filter.observeRenderer(ctx.renderer.raw));
2556
2744
  ```
2557
2745
 
2746
+ ### `ShortRangeAO`
2747
+
2748
+ `class` — Unreal's Short Range AO: a horizon search of 2 sweeps around the view normal, 3 samples each at the squared fraction of a 32 px screen reach, at full resolution, with a bent normal at Epic. It is the occlusion that runs *with* dynamic global illumination — the contact detail Lumen keeps after the screen probe gather has already answered the wide occlusion — so a gathered frame is not darkened twice by two wide treatments. The result is one texture: `rgb` the bent normal in view space, `a` the share of the hemisphere left open, which multiplies indirect light only.
2749
+
2750
+ ```ts
2751
+ export class ShortRangeAO { … }
2752
+ ```
2753
+
2754
+ - **Use when:** contact shadow at the foot of an object while dynamic GI runs · dark line where a wall meets the floor, without a second wide AO over the gathered light · lumen short range ao
2755
+ - **Constraints:** it replaces GTAO when dynamic GI runs; a tier without GI keeps ambientOcclusion · the occlusion multiplies indirect light only: direct light and emission keep their own occlusion · multi-bounce and its albedo cap belong to the game's composite; Unreal caps the albedo at 0.5 · an authored stage that carries its name must anchor itself (`before: "ssgi"`), because the chain's built-in order names no shortRangeAO
2756
+ - **Overrides:** horizonSearchSliceCount, horizonSearchStepCount, reachPx, bentNormal and intensity are game-owned choices
2757
+
2758
+ ```ts
2759
+ const shortRange = new ShortRangeAO({ camera, viewport: renderer.drawingBufferSize });
2760
+ const contact = shortRange.occlusion(depth(), normalView());
2761
+ const indirect = input.rgb.mul(contact.a);
2762
+ ```
2763
+
2558
2764
  ### `SkeletalMesh3D`
2559
2765
 
2560
2766
  `class` — Shared preparation for an imported rigged character. Instances the rig with a skeleton-safe clone, normalises size with skin-aware measurement, validates requested clips against the file and rig at load time, and sets up AnimationPlayer with honest stride-root accounting. Animation evaluation inherits AnimationPlayer's automatic camera-based `updateRate: "auto"` default; `updateRate: 1` evaluates every frame, another positive safe integer requests that interval, and `updateRateReport` exposes the effective rate, override status and latest result. One-shots and fades stay full-rate; root-motion `AnimationComposer` advances every tick, and auto camera-ray targets and camera-parented rigs stay full-rate. A public `mixer` `"loop"` listener promotes effective evaluation to 1 and observes only loop events after registration, so skipped pre-registration cycles are not replayed.
@@ -3369,6 +3575,169 @@ const root = createCssUiRoot();
3369
3575
  root.render(createElement("section", { className: "fixed inset-0 bg-zinc-900/90" }, "READY"));
3370
3576
  ```
3371
3577
 
3578
+ ## `@threenative/core/render/environment`
3579
+
3580
+ ### `cachedEnvironmentSample`
3581
+
3582
+ `function` — The sample this renderer took of `scene`'s environment, if it is still current.
3583
+
3584
+ ```ts
3585
+ export function cachedEnvironmentSample( renderer: object, scene: Scene, ): IEnvironmentSample | undefined { … }
3586
+ ```
3587
+
3588
+ - **Use when:** skip a second environment readback in the same frame
3589
+ - **Constraints:** a sample whose source texture or intensity moved is dropped, so a stale one never reaches a material
3590
+
3591
+ ```ts
3592
+ const hit = cachedEnvironmentSample(renderer, scene);
3593
+ ```
3594
+
3595
+ ### `cacheEnvironmentSample`
3596
+
3597
+ `function` — Remembers `sample` as this renderer's reading of `scene`'s environment.
3598
+
3599
+ ```ts
3600
+ export function cacheEnvironmentSample( renderer: object, scene: Scene, sample: IEnvironmentSample, ): void { … }
3601
+ ```
3602
+
3603
+ - **Use when:** reuse one environment readback across the materials of a scene
3604
+
3605
+ ```ts
3606
+ cacheEnvironmentSample(renderer, scene, sample);
3607
+ ```
3608
+
3609
+ ### `captureEnvironmentSnapshot`
3610
+
3611
+ `function` — The provenance of a scene's environment: which texture, at which intensity, in which colour space.
3612
+
3613
+ ```ts
3614
+ export function captureEnvironmentSnapshot(scene: Scene): IEnvironmentSourceSnapshot { … }
3615
+ ```
3616
+
3617
+ - **Use when:** reject an environment readback that belongs to a different sky
3618
+
3619
+ ```ts
3620
+ const snapshot = captureEnvironmentSnapshot(scene);
3621
+ ```
3622
+
3623
+ ### `environmentSnapshotCurrent`
3624
+
3625
+ `function` — Whether the scene's environment still matches the snapshot a sample was taken from.
3626
+
3627
+ ```ts
3628
+ export function environmentSnapshotCurrent( scene: Scene, snapshot: IEnvironmentSourceSnapshot, ): boolean { … }
3629
+ ```
3630
+
3631
+ - **Use when:** hold a material's fill light to the sky that is on screen now
3632
+
3633
+ ```ts
3634
+ if (environmentSnapshotCurrent(scene, snapshot)) draw(snapshot);
3635
+ ```
3636
+
3637
+ ### `isWebGLFallbackRenderer`
3638
+
3639
+ `function` — Whether a `WebGPURenderer` wrapper is running three's WebGL backend behind it.
3640
+
3641
+ ```ts
3642
+ export function isWebGLFallbackRenderer(renderer: unknown): boolean { … }
3643
+ ```
3644
+
3645
+ - **Use when:** refuse a GPU-only lane on a WebGL fallback instead of drawing something wrong
3646
+
3647
+ ```ts
3648
+ if (isWebGLFallbackRenderer(renderer)) skipMaterialLane();
3649
+ ```
3650
+
3651
+ ### `materialLightingEnabled`
3652
+
3653
+ `function` — Whether `tier` may run the material-lighting lane in `environment`.
3654
+
3655
+ ```ts
3656
+ export function materialLightingEnabled( tier: QualityTier, environment: IMaterialLightingEnvironment, ): boolean { … }
3657
+ ```
3658
+
3659
+ - **Use when:** decide whether this renderer is the admitted material lane
3660
+ - **Constraints:** high tier, browser, hardware WebGPU, not mobile, not software, not a WebGL fallback
3661
+
3662
+ ```ts
3663
+ if (materialLightingEnabled("high", env)) lightMaterials();
3664
+ ```
3665
+
3666
+ ### `measureEnvironment`
3667
+
3668
+ `function` — The environment measure-and-sample mechanism every kit repeats: what the scene's environment actually contributes, a bounded GPU sample of it with a cache and a readback deadline, the provenance a stale readback is rejected by, and the gate that decides which renderer may run the material lane. The backlight itself is a shader with fixed constants, so it stays in each kit's `src/render/` (stamped from one source there) where the game can change how it looks. This is machinery, not a look: every colour, gain and threshold arrives as an argument, and a kit that wants a different bound passes a different one. It lives here because twelve kits held byte-identical copies — 9 084 lines — so a fix to one left eleven wrong with every gate green (`c93b427d0` touched 552 files for one look change).
3669
+
3670
+ ```ts
3671
+ export function measureEnvironment(scene: Scene, maxSourceTexels: number): IEnvironmentMeasurement { … }
3672
+ ```
3673
+
3674
+ - **Use when:** measure what a scene's environment actually contributes · sample the environment on the GPU without stalling the frame · keep an environment readback from reaching a frame it does not belong to
3675
+
3676
+ ```ts
3677
+ const m = measureEnvironment(scene, 2048);
3678
+ ```
3679
+
3680
+ ### `reportEnvironmentContribution`
3681
+
3682
+ `function` — The environment measure-and-sample mechanism every kit repeats: what the scene's environment actually contributes, a bounded GPU sample of it with a cache and a readback deadline, the provenance a stale readback is rejected by, and the gate that decides which renderer may run the material lane. The backlight itself is a shader with fixed constants, so it stays in each kit's `src/render/` (stamped from one source there) where the game can change how it looks. This is machinery, not a look: every colour, gain and threshold arrives as an argument, and a kit that wants a different bound passes a different one. It lives here because twelve kits held byte-identical copies — 9 084 lines — so a fix to one left eleven wrong with every gate green (`c93b427d0` touched 552 files for one look change).
3683
+
3684
+ ```ts
3685
+ export function reportEnvironmentContribution( scene: Scene, options: IContributionControls, measurement?: IEnvironmentMeasurement, ) { … }
3686
+ ```
3687
+
3688
+ - **Use when:** measure what a scene's environment actually contributes · sample the environment on the GPU without stalling the frame · keep an environment readback from reaching a frame it does not belong to
3689
+
3690
+ ```ts
3691
+ reportEnvironmentContribution(scene, {
3692
+ darkThreshold: 0.02, fillAdmitted: true, fillColor: new Color(1, 1, 1), fillGain: 0.4,
3693
+ maxSourceTexels: 2048, rimGain: 0.6,
3694
+ });
3695
+ ```
3696
+
3697
+ ### `sampledRadiance`
3698
+
3699
+ `function` — The mean radiance and colour of a bounded linear sample, or `unknown` with the reason.
3700
+
3701
+ ```ts
3702
+ export function sampledRadiance(samples: unknown, intensity: number): IEnvironmentMeasurement { … }
3703
+ ```
3704
+
3705
+ - **Use when:** turn an environment readback into the radiance a material's fill light needs · know why an environment sample could not be measured
3706
+ - **Constraints:** the sample must be the qualified 64x32 float RGBA readback; anything else is refused by name
3707
+
3708
+ ```ts
3709
+ const m = sampledRadiance(readback, 1);
3710
+ ```
3711
+
3712
+ ### `sampleEnvironment`
3713
+
3714
+ `function` — Measures and samples the scene's real environment on the GPU, bounded by a readback deadline.
3715
+
3716
+ ```ts
3717
+ export async function sampleEnvironment( renderer: unknown, scene: Scene, environment: IMaterialLightingEnvironment, ): Promise<IEnvironmentSample> { … }
3718
+ ```
3719
+
3720
+ - **Use when:** measure what a scene's environment actually contributes without stalling the frame · give a material's fill light the environment's own radiance
3721
+ - **Constraints:** off unless the renderer is the admitted high-tier WebGPU lane; every refusal is reported by name · the readback is abandoned after the deadline and the frame keeps the previous answer
3722
+
3723
+ ```ts
3724
+ const sample = await sampleEnvironment(renderer, scene, env);
3725
+ ```
3726
+
3727
+ ### `samplingSourceSupported`
3728
+
3729
+ `function` — Whether an environment texture's mapping and colour space are qualified for the bounded GPU sample.
3730
+
3731
+ ```ts
3732
+ export function samplingSourceSupported(source: NonNullable<Scene["environment"]>): boolean { … }
3733
+ ```
3734
+
3735
+ - **Use when:** know why an environment was not sampled on the GPU
3736
+
3737
+ ```ts
3738
+ if (samplingSourceSupported(source)) sample(source);
3739
+ ```
3740
+
3372
3741
  ## `@threenative/core/spells`
3373
3742
 
3374
3743
  ### `CastPool`
@@ -3757,6 +4126,21 @@ const handle = startWorkerGame(new Worker(new URL("./worker.ts", import.meta.url
3757
4126
 
3758
4127
  ## `@threenative/core/world`
3759
4128
 
4129
+ ### `AdmissionBudget`
4130
+
4131
+ `class` — One frame's admission allowance, shared by every path that puts streamed content on screen. A streaming world has no frame-time ceiling anywhere else: a cell row arriving builds a batch per asset run over every placement in it, a terrain tile builds every LOD level, and the game's `createCollider` runs for every resident tile — all in the one frame that discovers them. That is the 100-330 ms hitch a 60 m/s camera feels every time the ring moves, and it is admission cost, not streaming: the loads never fail. The budget is opened once per `update` and drawn down by the units it admits. A unit always finishes, so a frame spends at most the limit plus the unit that crossed it, and the rest of the backlog waits for the next frame rather than being dropped.
4132
+
4133
+ ```ts
4134
+ export class AdmissionBudget implements IAdmissionBudget { … }
4135
+ ```
4136
+
4137
+ - **Use when:** streamed terrain tiles or cells hitch the frame that admits them · cap how many milliseconds a frame spends building streamed content
4138
+ - **Constraints:** open a new budget each frame; a unit always finishes, so one unit can cross the limit
4139
+
4140
+ ```ts
4141
+ tiles.follow(player.position, new AdmissionBudget(2, () => performance.now()));
4142
+ ```
4143
+
3760
4144
  ### `applyTerrainSurface`
3761
4145
 
3762
4146
  `function` — Apply a cooked GLB's package-authored layered surface to its marked terrain meshes. `url` is the loaded GLB URL; extras pointers are relative to it. Uses the same asset/fetch path as loadTerrainSplat on web and native. The caller owns the assigned materials' lifetime.
@@ -3804,6 +4188,21 @@ export function bakedNoise( p: Node<"vec3">, amplitude: Scalar = 1, pivot: Scala
3804
4188
  const patch = smoothstep(-0.35, 0.35, bakedNoise(positionWorld.mul(0.025)));
3805
4189
  ```
3806
4190
 
4191
+ ### `baseRingGap`
4192
+
4193
+ `function` — The highest gap between a wide model's rim and the ground, one sample per angular sector: in each sector, the lowest vertex beyond `rim` of that sector's reach. A narrow buried stem then cannot hold a wide base up in the air on the downhill side. Sink the pose by `gap` (plus any burial the game wants) to close it.
4194
+
4195
+ ```ts
4196
+ export function baseRingGap( geometry: BufferGeometry, matrix: Matrix4, ground: StaticGroundQuery, options: { … }
4197
+ ```
4198
+
4199
+ - **Use when:** a cliff or crag model rests on a buried stem while its wide base hangs over the downhill ground
4200
+ - **Constraints:** throws `TN_STATIC_POSE_GROUND` where the ground does not answer; check `samples` before trusting `gap`
4201
+
4202
+ ```ts
4203
+ const ring = baseRingGap(geometry, matrix, ground); if (ring.samples >= 4) matrix.elements[13] -= ring.gap + 0.5;
4204
+ ```
4205
+
3807
4206
  ### `cellPlacements`
3808
4207
 
3809
4208
  `function` — Borrow the run's placement records as a live view over the placement buffer.
@@ -3819,6 +4218,21 @@ export function cellPlacements(placements: ArrayBuffer, run: IWorldRun): Float32
3819
4218
  const records = cellPlacements(buffer, { asset: "tree", offset: 0, count: 120 });
3820
4219
  ```
3821
4220
 
4221
+ ### `footprintGap`
4222
+
4223
+ `function` — How far the flat underside of a static geometry rises above the ground at its highest point. Snapping the lowest point leaves the downhill side of a flat-bottomed rock hanging; sinking the pose by this much buries the whole footprint. Returns 0 when the footprint is already buried.
4224
+
4225
+ ```ts
4226
+ export function footprintGap( geometry: BufferGeometry, matrix: Matrix4, ground: StaticGroundQuery, margin = 0, ): number { … }
4227
+ ```
4228
+
4229
+ - **Use when:** a rock snapped to a slope shows a lip or a gap under its downhill side
4230
+ - **Constraints:** the footprint is every vertex at the geometry's lowest local y; throws `TN_STATIC_POSE_GROUND` where the ground does not answer
4231
+
4232
+ ```ts
4233
+ matrix.elements[13] -= footprintGap(geometry, matrix, ground, 0.08);
4234
+ ```
4235
+
3822
4236
  ### `getWorldCapabilities`
3823
4237
 
3824
4238
  `function` — Resolve the active world-generation path from host capability facts. The function accepts the adapter facts instead of reaching through a renderer-specific global, so browser and native hosts can report the same object. Missing limits are not treated as infinite: a host must either provide a valid GPU limit report or explicitly choose CPU fallback. GPU generation remains unavailable until a GPU readback can own the canonical field; a host adapter report therefore never upgrades a CPU fallback into a GPU generation claim.
@@ -3910,6 +4324,21 @@ export function lakeReach(field: Heightfield, lake: IWaterLake): number { … }
3910
4324
  const reach = lakeReach(field, { ...lake, margin: 1.12 });
3911
4325
  ```
3912
4326
 
4327
+ ### `lakeSurfaceGeometry`
4328
+
4329
+ `function` — A lake's water surface: a level disc out to `lakeReach`, the footprint `WaterBodies` floods, with a `metres` attribute (water depth over the ground). Only cells with a corner the seed's water reaches get triangles, so the surface does not hover over dry hillside, a hollow past the basin's rim (a river valley beyond the dam) stays dry instead of standing under a sheet that stops where the reach does, and the shore follows the ground's contour. The rings pack towards the middle, so an irregular basin costs vertices where the camera sees them. Returns `undefined` when the basin holds no water at its level.
4330
+
4331
+ ```ts
4332
+ export function lakeSurfaceGeometry( lake: IWaterLake, field: Heightfield, options: ILakeSurfaceOptions = { … }
4333
+ ```
4334
+
4335
+ - **Use when:** draw a lake's water surface from the baked level and seed · a lake's drawn water and the swimmer's water disagree · lake water ends in a straight edge over a valley past the basin's rim
4336
+ - **Constraints:** the lake row and field come from the game's bake; the game's material shades the geometry
4337
+
4338
+ ```ts
4339
+ const geometry = lakeSurfaceGeometry({ ...lake, margin: 1.12 }, field, { maxDepth: 1.6 });
4340
+ ```
4341
+
3913
4342
  ### `loadTerrainSplat`
3914
4343
 
3915
4344
  `function` — The splat terrain surface a world package describes, for `WorldCells.load({ surface })`. Layers blend over a base by mask channels read as linear data (the masks ship raw, beside the heightmap, so no cook moves a blend threshold), with noise-broken edges and macro brightness variation. Texture sets tile in world metres on the package's ground plane (x, -z: a Z-up authoring tool's x and y), cliffs can be triplanar, and the base plus any layer that asks carries a normal map. Each layer answers light from its own ORM map where the table ships one and from the table's own roughness and metalness where it does not; a layer that states neither is matte and dielectric, and named in a warning. Nothing here is a look choice: textures, tiles, tints, thresholds, surface response and noise scales all come from the package's table, which the game authors once and its DCC shares.
@@ -3942,6 +4371,21 @@ export async function loadWorldHeightmap(url: string): Promise<Uint16Array> {
3942
4371
  const data = await loadWorldHeightmap("/world/terrain/heightmap.u16");
3943
4372
  ```
3944
4373
 
4374
+ ### `meshSections`
4375
+
4376
+ `function` — A mesh's material sections: one per geometry group for a material array, else the whole mesh. Instanced props draw one batch per material, so an imported model splits here first.
4377
+
4378
+ ```ts
4379
+ export function meshSections(mesh: Mesh): IMeshSection[] { … }
4380
+ ```
4381
+
4382
+ - **Use when:** scatter or instance an imported glTF model that has several materials
4383
+ - **Constraints:** a section's `material` can be `undefined` for a group naming a missing material slot; skip it
4384
+
4385
+ ```ts
4386
+ for (const section of meshSections(mesh)) parts.push(sectionGeometry(mesh, box, section));
4387
+ ```
4388
+
3945
4389
  ### `noiseVolume`
3946
4390
 
3947
4391
  `function` — The one volume every material shares: baked on first use, 1 MiB of RGBA8 (it stays in L2).
@@ -3957,6 +4401,66 @@ export function noiseVolume(): Data3DTexture { … }
3957
4401
  const volume = noiseVolume();
3958
4402
  ```
3959
4403
 
4404
+ ### `repairZeroNormals`
4405
+
4406
+ `function` — Recompute the normals of a geometry whose normals are missing, zero or not finite, and leave authored normals alone. Some exported art ships zero normals and draws black under any light. Run it after any reshape, so the recomputed normals fit the final shape.
4407
+
4408
+ ```ts
4409
+ export function repairZeroNormals(geometry: BufferGeometry): boolean { … }
4410
+ ```
4411
+
4412
+ - **Use when:** an imported model draws black or unlit because it ships zero normals
4413
+ - **Constraints:** one bad normal recomputes them all; an intentionally hard-edged model loses its authored split normals only if one is bad
4414
+
4415
+ ```ts
4416
+ geometry.scale(1.1, 1, 1.1); repairZeroNormals(geometry);
4417
+ ```
4418
+
4419
+ ### `riverRibbonGeometry`
4420
+
4421
+ `function` — The water surface of every river, as one geometry with one group per river. Each station is a row across the river at its own surface height, out to `reach` widths either side of the centreline, the reach `WaterBodies` floods; one more row a reach past each end stands where `WaterBodies` clamps a segment, so the water a swimmer finds past a river's end is drawn there too (cut at the end station, the surface stopped in a straight edge with its carved bed dry beyond). Quads dry on both rows against `field` are dropped, so the surface ends at the shore. Past an end where the ground falls below the end's bed, the water would run off: that cap is not drawn, and the end stays cut at its last station. Attributes for the game's water material: `flow` (the unit downstream heading), `flowUv` (metres down the centreline, metres across it) and `metres` (water depth over the ground). It decides no colour, ripple or opacity: the game shades it.
4422
+
4423
+ ```ts
4424
+ export function riverRibbonGeometry( rivers: readonly { … }
4425
+ ```
4426
+
4427
+ - **Use when:** draw a river's water surface from the baked stations · a river's water stops in a straight edge, or a swimmer floats where no water is drawn · share one river shape between the drawn water and the swimmer · river water hangs over dry ground past the river's head or tail
4428
+ - **Constraints:** stations, width and reach come from the game's bake; the game's material shades the geometry
4429
+
4430
+ ```ts
4431
+ const geometry = riverRibbonGeometry(rivers, field, { maxDepth: 1.6 });
4432
+ ```
4433
+
4434
+ ### `sectionGeometry`
4435
+
4436
+ `function` — One section's geometry in model space, standing on y = 0. Every section of a model takes the same base from the whole model's `box`, so a crown keeps its place on its trunk: basing each section on its own bounds detaches them. The mesh's LOD0 geometry is cloned under its world matrix, and a group becomes the clone's draw range.
4437
+
4438
+ ```ts
4439
+ export function sectionGeometry( mesh: Mesh, box: Box3, section: IMeshSection, options: { … }
4440
+ ```
4441
+
4442
+ - **Use when:** the crown of an instanced tree floats off its trunk, or the parts of a model separate · turn each part of an imported model into a geometry for an instanced prop batch
4443
+ - **Constraints:** `box` is the whole model's world bounds after any unit normalisation; call `mesh.updateWorldMatrix` first
4444
+
4445
+ ```ts
4446
+ const box = new Box3().setFromObject(root); const geometry = sectionGeometry(mesh, box, section);
4447
+ ```
4448
+
4449
+ ### `shoreField`
4450
+
4451
+ `function` — Distance to the shore and open-sea exposure for every node of a square height grid, measured once from the bake. `distance` is a two-pass chamfer distance to the nearest node at or above `level` (0 on dry ground). `exposed` floods from the grid's edge through water deeper than `openDepth`, then `carry` metres further into shallow water, so a sheltered lagoon behind a sand bar stays out of it. Both feed the game's surf and shore masks; neither decides a colour.
4452
+
4453
+ ```ts
4454
+ export function shoreField( heights: ArrayLike<number>, resolution: number, size: number, level: number, options: IShoreFieldOptions = { … }
4455
+ ```
4456
+
4457
+ - **Use when:** surf breaks only on water open to the sea, not in a sheltered lagoon · distance from each water cell to the shore, for a foam or depth mask
4458
+ - **Constraints:** heights are row-major, `resolution` by `resolution`, across `size` metres; measured once, never per frame
4459
+
4460
+ ```ts
4461
+ const { distance, exposed } = shoreField(world.heights, world.resolution, world.size, world.waterLevel);
4462
+ ```
4463
+
3960
4464
  ### `snowDiscFootprint`
3961
4465
 
3962
4466
  `function` — A circular contact footprint, sized from a radius the caller measures. The shape a sphere, a ball, a wheel or a probe presses into snow, and the default the physics binding derives from a sphere's contact geometry. Flat inside the radius, eased over the softness band, with a raised rim just outside it.
@@ -3981,7 +4485,7 @@ const footprint = snowDiscFootprint(0.25);
3981
4485
  export class SnowField { … }
3982
4486
  ```
3983
4487
 
3984
- - **Use when:** leave footprints, tracks and tyre ruts in snow that persist and fill in over time · let a pushed sphere carve a connected track and a dropped one settle into a crater · store snow deformation that rendered geometry and collision both read · reset a snowfield between rounds or change its depth at runtime · show how packed the snow is where people have walked or objects have rested
4488
+ - **Use when:** leave footprints, tracks and tyre ruts in snow that persist and fill in over time · let a fresh snowfall slowly fill older tracks back in as the field recovers · let a pushed sphere carve a connected track and a dropped one settle into a crater · store snow deformation that rendered geometry and collision both read · reset a snowfield between rounds or change its depth at runtime · show how packed the snow is where people have walked or objects have rested
3985
4489
  - **Constraints:** the field composes onto a Heightfield; construct the terrain first and let this own the surface · zero depth is bare ground: contacts register no indentation at all · out-of-region heightAt and normalAt follow Heightfield's error contract; sample returns zeros
3986
4490
  - **Requires:** @threenative/core/world Heightfield as the canonical terrain and surface
3987
4491
  - **Overrides:** depth, hardness, yieldFraction, maxBank and responseTime name the response coefficients
@@ -3994,6 +4498,36 @@ snow.stamp({ x: 0, z: 0, area: 0.074, load: 784, duration: 0.1, footprint: snowD
3994
4498
  snow.recover(1 / 60, 0.0012, 0.4);
3995
4499
  ```
3996
4500
 
4501
+ ### `staticLowestY`
4502
+
4503
+ `function` — Exact lowest world Y of a static geometry under `matrix`, the precise measurement `GroundSnap` audits against, cheap enough for a load that poses hundreds of thousands of props. An upright pose reads the bounding box. A tilted pose scans the vertices bottom first (sorted once per geometry) and stops once no later vertex can be lower: `|x e1 + z e9| <= reach * hypot(e1, e9)`.
4504
+
4505
+ ```ts
4506
+ export function staticLowestY(geometry: BufferGeometry, matrix: Matrix4): number { … }
4507
+ ```
4508
+
4509
+ - **Use when:** stand a scattered rock, tree or crate on the ground by its lowest point, not its origin · props hover or sink because their pivot is not at their base
4510
+ - **Constraints:** static geometry only; a skinned model uses `GroundSnap`; the sort is cached per geometry, so do not mutate its positions
4511
+
4512
+ ```ts
4513
+ placed.position.y += ground - staticLowestY(geometry, matrix);
4514
+ ```
4515
+
4516
+ ### `surfaceSampler`
4517
+
4518
+ `function` — `Heightfield.surfaceAt` under the transform the game draws the field's mesh with, so a prop or a player stands on the triangles the eye sees rather than on the bilinear field between them. Answers `null` outside the field and for a transform it does not model (any rotation, or an unequal scale), so the caller keeps its own fallback there.
4519
+
4520
+ ```ts
4521
+ export function surfaceSampler(field: Heightfield, matrixWorld: Matrix4): SurfaceSampler { … }
4522
+ ```
4523
+
4524
+ - **Use when:** stand props or a player on the drawn terrain triangles under a moved or scaled mesh · props float or sink where the terrain mesh is drawn under a transform
4525
+ - **Constraints:** the mesh is `field.toGeometry()` drawn upright under a uniform scale; read `matrixWorld` after it settles
4526
+
4527
+ ```ts
4528
+ const ground = surfaceSampler(field, mesh.matrixWorld); const y = ground(x, z) ?? fallback;
4529
+ ```
4530
+
3997
4531
  ### `TerrainTiles`
3998
4532
 
3999
4533
  `class` — Stream a bounded square of game-authored heightfields and keep their render and physics units together. The class composes ordinary THREE.LOD objects and leaves frustum/projection culling to the renderer's existing scene path.
@@ -4002,7 +4536,7 @@ snow.recover(1 / 60, 0.0012, 0.4);
4002
4536
  export class TerrainTiles extends Object3D implements IComputeDriven { … }
4003
4537
  ```
4004
4538
 
4005
- - **Use when:** stream terrain without cracks · keep generated terrain resident around a moving player · put a generated terrain tile into a game-owned physics world
4539
+ - **Use when:** stream terrain without cracks · keep generated terrain resident around a moving player · put a generated terrain tile into a game-owned physics world · a hole or a flicker where streamed terrain tiles are still building (`settledHalf`) · split the ground between streamed tiles and a far mesh around the player (`settledHalf`)
4006
4540
  - **Constraints:** sampleHeight and surface are required game choices; no landform or surface preset is installed · residentTileBudget and residentByteBudget are hard caps; a tile that cannot fit throws · seam gap, LOD pop and the rendered-vertex finiteness scan are measurements that are off by default; TN_TERRAIN_VALIDATE=1, ?tnTerrainValidate=1 or validate: true runs them, and maxSeamGap, maxVisualSeamGap and maxLodPop report undefined while they are off
4007
4541
  - **Overrides:** tileSize, tileResolution, lodFactors, lodDistances, skirtDepth, streamRadius, colliderRadius, mergeTiles, validate, and budgets
4008
4542
 
@@ -4043,6 +4577,21 @@ export function validateWorldPackage( manifest: unknown, options: IWorldPackageV
4043
4577
  const { ok, errors } = validateWorldPackage(json, { placementsByteLength: buffer.byteLength });
4044
4578
  ```
4045
4579
 
4580
+ ### `warmUnculled`
4581
+
4582
+ `function` — Draw `root` with frustum culling off until it has drawn `draws` times, then cull it again and resolve. A pipeline is built by its first real draw (a startup warm-up compiles a different pass), so content the spawn view does not see — streamed tiles behind the player, a mirror that draws only when its water does — builds its pipelines after the reveal and hitches the first frames that see it. Join the promise to the loading curtain to build them behind it. Objects that join `root` while it warms draw unculled too.
4583
+
4584
+ ```ts
4585
+ export function warmUnculled( ctx: { … }
4586
+ ```
4587
+
4588
+ - **Use when:** the first frames after the loading curtain hitch on pipeline builds for content behind the camera · streamed terrain or a lake compiles its pipelines after the reveal
4589
+ - **Constraints:** `ctx.beforeRender` runs on every world draw, also behind the curtain; join the promise to the curtain's hold
4590
+
4591
+ ```ts
4592
+ const warm = warmUnculled(ctx, lake.mesh); ctx.startup.hold("lake", () => warm);
4593
+ ```
4594
+
4046
4595
  ### `WaterBodies`
4047
4596
 
4048
4597
  `class` — One world's water, queried: surface height, current and footprint from the baked arrays. Rendering and physics read the same store, as they do for `Heightfield`, so the surface a player sees and the surface a swimmer rests on cannot disagree. Every station, level, extent and speed comes from the game, and the shading stays in the game's own `src/render/`. A river's segments sit in a uniform grid, so a query tests the few that can reach its cell instead of every station of every river.
@@ -4083,7 +4632,7 @@ export class WorldCells extends Group implements IComputeDriven { … }
4083
4632
 
4084
4633
  - **Use when:** stream a large Blender-authored world by cell instead of one huge GLB · keep scattered props and hand-placed chunks resident around a moving player · honour per-asset draw distances and hard streaming budgets without a mid-frame throw
4085
4634
  - **Constraints:** surface is the game's; this class creates no material, colour or geometry · a cell's model loads at `soon` priority, so a file the running scene awaits through `ctx.assets` starts first · budgets are hard caps that report pressure instead of over-committing · `whenSpawnReady(position, radius, timeoutMs)` snapshots a fixed region and settles from existing updates or disposal; it does not drive streaming, and `prewarmed` remains the separate draw gate · model loads are bounded by `concurrency` (default 12) across every resident cell, not per cell · refilters are bounded by `rebuildsPerUpdate` (default 16) per update, nearest cell first · residency and `placementReach` follow `follow`; levels and `maxDistance` are graded from the render camera, as UE picks instance LODs per view; `lodFrom: "follow"`, `?tnLodFromCamera=0` or `TN_LOD_FROM_CAMERA=0` grade from `follow`, reported as `TN_WORLD_MAIN_CULL lodFrom=` · admission is bounded by `admissionBudgetMs` (default 2) per update across every path, plus at most one unit each for terrain and props; while props are queued terrain takes at most half, so neither starves the other, and a deferred cell keeps drawing what it has · SkinnedMesh parts are skipped; an instanced copy would draw one rest pose · a baked chain's switch distances are measured against `autoLod` (default 4 px of error over 60° and 1080 raster rows), because an instanced draw cannot select a level per instance; an asset with nonempty authored `lods` never consults it; explicit empty lists enroll only unchanged static geometry/material parts · eligible static sources can use cooked HLOD (chunk-only alongside GPU scatter, whole-cell on CPU) after compilation and an observed main-context backend submission; projected-error hysteresis requires actual source triangle reduction and no extra material draws, unsupported or shared source stays resident, and collision/shadow paths retain source representations; stats().hlod counts lifecycle and charged resources, not GPU timing or physical allocation · `prewarmed` resolves once every prewarmed shared batch has been drawn; a game with a loading screen waits on it, and `stats().pendingPrewarm` is the same gate as a number · every `asset:level:part` is one InstancedMesh for the main pass, plus one caster InstancedMesh per world-grid square of `clusterSize` on the shadow caster layer, so the main pass draws one mesh per key and a shadow level submits only the squares it covers · two definitions the asset loader resolves to one model — the same cooked `glb`, the same `lods` at the same distances, the same `maxDistance` and bounds — are one asset under the lexicographically smallest id: one model load, one set of `asset:level:part` keys, one prewarm and one refcount, released when the last cell holding any member of the group leaves the ring; `TN_WORLD_ASSET_ALIAS` reports how many of the package's assets are really distinct · the main pass mesh draws only the squares the render camera's frustum covers — on by default, narrowed once per frame for every main batch by the engine's render-cadence dispatch, never for an orthographic camera — a batch with nothing to draw is hidden rather than submitted at `count 0`, and `TN_WORLD_MAIN_CULL` reports both every five seconds · a loaded chunk is merged by material before it is added, so it submits one draw per material rather than one per node; a skinned, multi-material or morph-target mesh, one carrying a baked AutoLOD chain, and an instanced mesh past `chunkMergeMaxTriangles` (default 43,690 triangles) or with a shape over 2,048 triangles, all keep their own geometry; a material group crossing 131,072 vertices (4 MiB of position + normal + uv) is split into several meshes in traversal order instead of one giant upload, indexed parts keep their index, and `TN_WORLD_CHUNK_MERGE` reports what the merge did and the bytes it left · `shadows.castDistance` is accepted and ignored (clusters replaced it); `shadows.invalidate` is called at most once a second after streamed records changed
4086
- - **Overrides:** `hlod: false` keeps source rendering; ring, budgets, terrain tile size/resolution, terrain stream and collider radius, `transparentScatter`, `clusterSize` and `shadows.invalidate`, load `concurrency`, `rebuildsPerUpdate`, `admissionBudgetMs` and the package's per-asset maxDistance; `impostorFar: "always"` keeps the far aggregate the near ring's guaranteed radius made unnecessary
4635
+ - **Overrides:** `hlod: false` keeps source rendering; `partMaterial` gives a part the game's own surface (a swaying tree); ring, budgets, terrain tile size/resolution, terrain stream and collider radius, `transparentScatter`, `clusterSize` and `shadows.invalidate`, load `concurrency`, `rebuildsPerUpdate`, `admissionBudgetMs` and the package's per-asset maxDistance; `impostorFar: "always"` keeps the far aggregate the near ring's guaranteed radius made unnecessary
4087
4636
 
4088
4637
  ```ts
4089
4638
  const world = await WorldCells.load({ url: "/world/world.json", surface, follow, ring: 1, budgets: { residentCells: 25, instances: 20000, bytes: 8000000 } });
@@ -4371,7 +4920,7 @@ export function rapier(options: IPhysicsOptions = { … }
4371
4920
  ```
4372
4921
 
4373
4922
  - **Use when:** add physics to a portable game · provide the context used by character and rigid bodies
4374
- - **Constraints:** place rapier() before recast() in the plugin list
4923
+ - **Constraints:** place rapier() before recast() in the plugin list · ctx.physics is set before Scene.enter(), not during load(): Rapier initializes while the scene loads, so create bodies in enter() or later (TN_PHYSICS_NOT_READY)
4375
4924
  - **Requires:** npm i @threenative/physics
4376
4925
 
4377
4926
  ```ts
@@ -4974,6 +5523,23 @@ if (requestedPlaytestClockMode() === "wall-clock") host.pumpDrivesTheSimulation(
4974
5523
 
4975
5524
  ## `@threenative/playtest/runner`
4976
5525
 
5526
+ ### `absolutesVerdict`
5527
+
5528
+ `function` — The host-load reading and the rule that decides whether absolute milliseconds are trustworthy: absolutes are invalid once the one-minute load passes half the cores.
5529
+
5530
+ ```ts
5531
+ export function absolutesVerdict(reading: IPerfHostLoadReading): IPerfHostLoad["absolutes"] { … }
5532
+ ```
5533
+
5534
+ - **Use when:** mark a benchmark run invalid because the machine was busy
5535
+ - **Constraints:** an unreadable load is a refusal, not a silence: an unmeasured machine cannot vouch
5536
+
5537
+ ```ts
5538
+ import { absolutesVerdict, readHostLoad } from "@threenative/playtest/runner";
5539
+ const load = readHostLoad();
5540
+ if (absolutesVerdict(load) === "invalid-absolute") ignoreAbsoluteMilliseconds();
5541
+ ```
5542
+
4977
5543
  ### `AdbAndroidDriver`
4978
5544
 
4979
5545
  `class` — Drive and inspect Android playtest transport.
@@ -5606,6 +6172,23 @@ export function preflightDisplay( config: Pick<IStandalonePlaytestConfig, "headl
5606
6172
  const report = await runStandalonePlaytest(options);
5607
6173
  ```
5608
6174
 
6175
+ ### `readHostLoad`
6176
+
6177
+ `function` — The host-load reading and the rule that decides whether absolute milliseconds are trustworthy: absolutes are invalid once the one-minute load passes half the cores.
6178
+
6179
+ ```ts
6180
+ export function readHostLoad( source: IPerfHostLoadSource = { … }
6181
+ ```
6182
+
6183
+ - **Use when:** mark a benchmark run invalid because the machine was busy
6184
+ - **Constraints:** an unreadable load is a refusal, not a silence: an unmeasured machine cannot vouch
6185
+
6186
+ ```ts
6187
+ import { absolutesVerdict, readHostLoad } from "@threenative/playtest/runner";
6188
+ const load = readHostLoad();
6189
+ if (absolutesVerdict(load) === "invalid-absolute") ignoreAbsoluteMilliseconds();
6190
+ ```
6191
+
5609
6192
  ### `reconcileBrowserPointers`
5610
6193
 
5611
6194
  `function` — Compare pointer snapshots and produce down, move, and up transitions.
@@ -5745,17 +6328,17 @@ await runDesktopPlaytest(options);
5745
6328
 
5746
6329
  ### `runDevicePlaytest`
5747
6330
 
5748
- `function` — Run a playtest on Android through the configured device transport.
6331
+ `function` — Run a playtest on any device lane (Android, desktop or iOS) through its driver and transport.
5749
6332
 
5750
6333
  ```ts
5751
6334
  export async function runDevicePlaytest( config: IStandalonePlaytestConfig, target: IDevicePlaytestTarget, ): Promise<IStandalonePlaytestReport> { … }
5752
6335
  ```
5753
6336
 
5754
- - **Use when:** execute a scenario on an Android target · collect Android playtest artifacts
5755
- - **Constraints:** the app bundle and device transport must be prepared
6337
+ - **Use when:** execute a scenario on a device target with a custom driver
6338
+ - **Constraints:** the driver must prepare the app bundle and the transport must answer the handshake
5756
6339
 
5757
6340
  ```ts
5758
- await runAndroidPlaytest(options);
6341
+ await runDevicePlaytest(config, { name: "android", driver, transport, processName, mailboxPaths });
5759
6342
  ```
5760
6343
 
5761
6344
  ### `runIosPlaytest`
@@ -6239,6 +6822,41 @@ export async function bakeWolfToFile( options: IWolfBakeOptions, destination: st
6239
6822
  await bakeWolfToFile({ seed: 7, tier: "crowd" }, "assets/wolf-crowd.animal");
6240
6823
  ```
6241
6824
 
6825
+ ## `@threenative/procedural-vegetation`
6826
+
6827
+ ### `bakeVegetation`
6828
+
6829
+ `function` — Bake a procedural tree (Arbor) to GLBs, one per level of detail, ready for ctx.assets.model. Each GLB carries the _WIND vertex attribute, COLOR_0 and TEXCOORD_0; the Arbor presets also embed their bark and leaf textures with alpha-masked leaves, while forest-kit debris and cover shade from COLOR_0 alone.
6830
+
6831
+ ```ts
6832
+ export async function bakeVegetation(options: IBakeVegetationOptions): Promise<IVegetationBake[]> { … }
6833
+ ```
6834
+
6835
+ - **Use when:** generate a procedural tree, an oak, pine, spruce, palm or any forest species as a GLB · procedural oak tree GLB with level of detail for a game forest · tree GLB for Unity, Unreal or Godot, with wind weights in a _WIND attribute · a fallen mossy log and leaf litter on the forest floor, with a stump, twigs and boulders · reeds and cattails at a pond edge, or sedge tussocks, clover and seeding grass as cover
6836
+ - **Constraints:** fails closed: an unknown preset throws naming the nearest ids, the seed must be an integer and each lod 0 to 2 · the same preset, seed and lods write identical bytes; files are written atomically (temporary file, then rename) · bake-time only, so keep it a dev dependency; the game owns the look and the sway (a TSL render/wind.ts reading _WIND), because Arbor.three is not shipped · _WIND is vec4 (trunk sway, branch sway, flutter, phase): forest-kit sway is flutter in z, and debris writes all four zero · form and leafImage patch an Arbor preset only; a forest-kit debris or cover preset throws when given either
6837
+ - **Requires:** npm i -D @threenative/procedural-vegetation
6838
+
6839
+ ```ts
6840
+ await bakeVegetation({ preset: "oak", seed: 7, lods: [0, 1], out: "assets/trees" });
6841
+ await bakeVegetation({ preset: "log", seed: 3, out: "assets/debris" });
6842
+ ```
6843
+
6844
+ ### `vegetationPresets`
6845
+
6846
+ `function` — List every preset a bake can grow: id, name, latin name and kind. Trees and cover come from Arbor; the `debris` rows (log, stump, twig, branch, leaflitter, rock) and the extra cover rows (reeds, tussock, seedgrass, clover, dock, plume) come from forest-kit.
6847
+
6848
+ ```ts
6849
+ export function vegetationPresets(): IVegetationPreset[] { … }
6850
+ ```
6851
+
6852
+ - **Use when:** list the oak, pine, spruce, palm and other tree species a bake can grow · choose a tree species id for bakeVegetation or a terrain arbor: species · what deadwood, leaf litter, boulders, reeds and tussocks can I bake for a forest floor
6853
+ - **Constraints:** ids come from the vendored Arbor and forest-kit presets; trees are kind "tree", grass, ferns and flowers are kind "cover", deadwood, litter and stone are kind "debris"
6854
+ - **Requires:** npm i -D @threenative/procedural-vegetation
6855
+
6856
+ ```ts
6857
+ vegetationPresets().filter((p) => p.kind === "debris").map((p) => p.id);
6858
+ ```
6859
+
6242
6860
  ## `@threenative/raw-unreal`
6243
6861
 
6244
6862
  ### `createThreeGeometry`
@@ -6649,13 +7267,13 @@ const state = applyPlacementOverrides(terrain.evaluate(), document.placementOver
6649
7267
 
6650
7268
  ### `bakeBiome`
6651
7269
 
6652
- `function` — Bake one biome: the recipe's evaluated state and the world package it streams. This is the composition `terrain_generate` and a game's build script both call, so the file layout a player streams is decided in one place. The biome is validated first — an inline spec from a request is checked here, not trusted — and the package's own placement runs are checked against the state they came from, so a bake can never ship a cell list that lost instances.
7270
+ `function` — Bake one biome: the recipe's evaluated state and the world package it streams. This is the composition `terrain_generate` and a game's build script both call, so the file layout a player streams is decided in one place. The biome is validated first — an inline spec from a request is checked here, not trusted — and the package's own placement runs are checked against the state they came from, so a bake can never ship a cell list that lost instances. An agent does not write this call to get a world: the `threenative-terrain` MCP tool `terrain_generate` takes the request in words ("a pine forest under snowy mountains with a river", "a volcanic island", or `ground: { location }` for a real place) and cooks the world.glb, recipe.json and world.json a game loads with `ctx.assets.model`.
6653
7271
 
6654
7272
  ```ts
6655
7273
  export function bakeBiome(options: IBakeBiomeOptions): IBakedBiome { … }
6656
7274
  ```
6657
7275
 
6658
- - **Use when:** bake one biome's world package from an evaluated recipe and a biome file
7276
+ - **Use when:** bake one biome's world package from an evaluated recipe and a biome file · generate terrain with mountains, hills, a river, a lake or an island from a request in words · generate a landscape or open world map for a game · procedural terrain for a level: a volcanic island, a mountain valley or a coast · make a canyon, a volcano, a fjord, a desert, a tundra or a forest world · cook the real terrain of a place on Earth from its latitude and longitude
6659
7277
  - **Constraints:** every instance's asset must be in `assets`; every instance must land in exactly one cell run
6660
7278
  - **Requires:** npm i -D @threenative/terrain
6661
7279
 
@@ -6779,6 +7397,22 @@ export async function decodeHeightPNG( input: Uint8Array | ArrayBuffer, options:
6779
7397
  const png = await encodeHeightPNG(new Terrain({ resolution: 17 }).evaluate()); const heights = await decodeHeightPNG(png);
6780
7398
  ```
6781
7399
 
7400
+ ### `decodePropBucket`
7401
+
7402
+ `function` — The records of one compiled prop bucket, read back in record order: the inverse of `compilePropBuckets`, so a loader that fetched a bake's files gets each record's ID, model, pose and reach without re-deriving the container layout.
7403
+
7404
+ ```ts
7405
+ export function decodePropBucket(bucket: IPropBucketPackage): IPropBucketRecord[] { … }
7406
+ ```
7407
+
7408
+ - **Use when:** read a baked prop bucket back into placements to ground them on this machine's terrain
7409
+ - **Constraints:** throws `TN_PROP_BUCKET_INVALID` when the record buffer, the IDs and the runs disagree
7410
+ - **Requires:** npm i -D @threenative/terrain
7411
+
7412
+ ```ts
7413
+ for (const record of decodePropBucket(bucket)) pose(record.key, record.position, record.quaternion);
7414
+ ```
7415
+
6782
7416
  ### `decodeRAW16`
6783
7417
 
6784
7418
  `function` — Validates dimensions and range before decoding numerical height samples.
@@ -6923,6 +7557,23 @@ export function gradientAt(grid: ISampledGrid, x: number, z: number): [number, n
6923
7557
  const gradient = gradientAt(new Terrain({ resolution: 17 }).evaluate(), 0, 0);
6924
7558
  ```
6925
7559
 
7560
+ ### `grassFieldFromBiome`
7561
+
7562
+ `function` — Turns a terrain biome's grass rows and its ground into `GrassField3D` placement options, so a generated or cooked world grows streamed grass with one call. Returns null when the biome has no grass rows: the game draws no field. Each row covers its own slope band (full to `slope[1]`, gone `slopeFalloff` degrees past it), its own height band above `ground.floor` (fading over `heightFalloff` below the ceiling) and stays `waterMargin` above `ground.waterLevel`; the field takes the strongest row at each spot.
7563
+
7564
+ ```ts
7565
+ export function grassFieldFromBiome( biome: Pick<IBiomeSpec, "grass" | "seed">, ground: IGrassGround, ): IGrassFieldPlacement | null { … }
7566
+ ```
7567
+
7568
+ - **Use when:** grow streamed grass on a terrain world's biome grass rows · a Strata or terrain_generate world with a meadow that sways round the player · feed a cooked biome to GrassField3D
7569
+ - **Constraints:** the look stays the game's: pass the result with the kit's `render/grass.ts` blade and material
7570
+ - **Requires:** npm i -D @threenative/terrain
7571
+
7572
+ ```ts
7573
+ const placement = grassFieldFromBiome(biome, { heightAt: (x, z) => field.heightAt(x, z), waterLevel: 0 });
7574
+ if (placement) ctx.add(new GrassField3D({ ...placement, blade: grassBlade(), material: grassMaterial }));
7575
+ ```
7576
+
6926
7577
  ### `landform`
6927
7578
 
6928
7579
  `function` — One call, one landscape: a calibrated layer recipe for a kind of environment.
@@ -6957,6 +7608,22 @@ export function landformBackdrop( kind: LandformKind, options: IBackdropOptions
6957
7608
  const { size, resolution, heights } = landformBackdrop("temperateMountains", { seed: 7, centerHeight: 13 });
6958
7609
  ```
6959
7610
 
7611
+ ### `liftMassif`
7612
+
7613
+ `function` — A tile's mountain above its own foot: the heights minus a smooth surface through its border, so its edge is exactly zero and stands on any ground with no wall or ramp. Signed: a valley inside the mountain cuts below the foot, as it does in the survey.
7614
+
7615
+ ```ts
7616
+ export function liftMassif(tile: IMassifTile): Float32Array { … }
7617
+ ```
7618
+
7619
+ - **Use when:** measure how tall a surveyed mountain stands above the valley floor around it
7620
+ - **Constraints:** the tile must cover the whole mountain; a summit crop lifts as a cone
7621
+ - **Requires:** npm i -D @threenative/terrain
7622
+
7623
+ ```ts
7624
+ const lifted = liftMassif({ id: "hill", size: 400, resolution: 3, heights: [0, 0, 0, 0, 90, 0, 0, 0, 0] });
7625
+ ```
7626
+
6960
7627
  ### `makeExport`
6961
7628
 
6962
7629
  `function` — Recovered numerical/project exports; GLB/runtime outputs contain terrain only.
@@ -7005,6 +7672,23 @@ export function orderedScatterRules(spec: IBiomeSpec): IOrderedScatterRules {
7005
7672
  const rules = orderedScatterRules(spec);
7006
7673
  ```
7007
7674
 
7675
+ ### `placeMassif`
7676
+
7677
+ `function` — Stands one surveyed mountain behind a world, chosen and posed by a seed: the tile from a list, a point on a bearing and distance, a turn that faces its steepest wall to the centre within 20 degrees, a mirror and a summit height. It stands on the host's own foot (a smooth surface through the host under its border), replacing the host's hills inside its square, and leaves the centre square untouched. Appends one `heightmap` layer; the placement carries the tile-spacing heights a relief map reads.
7678
+
7679
+ ```ts
7680
+ export function placeMassif( terrain: Terrain, options: IPlaceMassifOptions, ): { … }
7681
+ ```
7682
+
7683
+ - **Use when:** put a real-shaped mountain behind a generated world, a different one per seed
7684
+ - **Constraints:** the tile must be a whole mountain whose border is valley floor; erosion after it carves the survey
7685
+ - **Requires:** npm i -D @threenative/terrain
7686
+ - **Overrides:** `at`, `bearing`, `distance`, `height`, `top`, `face` and `keepOut` on the same call
7687
+
7688
+ ```ts
7689
+ const { terrain, placement } = placeMassif(new Terrain({ size: 5000, resolution: 129 }), { seed: 3, tile: { id: "cone", size: 2000, resolution: 3, heights: [0, 0, 0, 0, 900, 0, 0, 0, 0] } });
7690
+ ```
7691
+
7008
7692
  ### `propAssetOf`
7009
7693
 
7010
7694
  `function` — The asset a package run names. A prop run names the model it draws, `asset:variant[@shape]`; a container written by `bakeWorldPackage` names the asset alone. Both reduce to the asset here, which is what a count, a material or a placement's own `asset` field holds.
@@ -7265,6 +7949,21 @@ export function createEditorSelection( { … }
7265
7949
  const selection = createEditorSelection({ gizmo, proxy, controller, grounding, surface, defaultFootprintSize, refreshPose, drawFootprint, restorePlacement, previewPlacement, setSaving, selectedChanged, setNavigation, message });
7266
7950
  ```
7267
7951
 
7952
+ ### `createTweakBox`
7953
+
7954
+ `function` — A box of range bars and colour pickers over the running game, for tuning numbers by eye. The game names its knobs and applies each change itself; the box owns the page elements, the stored values and the Copy button, whose JSON is what gets pasted back and written into the game's own source. With no `document` (a native launch, a test) it draws nothing and still holds the values, so the game code that reads them is the same on every target.
7955
+
7956
+ ```ts
7957
+ export function createTweakBox<K extends string>(options: ITweakBoxOptions<K>): ITweakBox<K> { … }
7958
+ ```
7959
+
7960
+ - **Use when:** tune look numbers by eye with live range bars and colour pickers while the game runs
7961
+ - **Requires:** npm i -D @threenative/terrain
7962
+
7963
+ ```ts
7964
+ const box = createTweakBox({ title: "Fog", knobs: { density: { min: 0, max: 0.1, value: 0.02 } }, onChange: (name, value) => console.info(name, value) });
7965
+ ```
7966
+
7268
7967
  ### `editorPlacementCenter`
7269
7968
 
7270
7969
  `function` — Transform the caller's measured geometry centre into the evaluated placement's world space.
@@ -8035,6 +8734,24 @@ export function useUiStateDuringStartup<TState extends object>(options: { … }
8035
8734
  const loading = useUiStateDuringStartup<GameState, number>({ reason: "staged loading overlay" }, (state) => state.loading.progress);
8036
8735
  ```
8037
8736
 
8737
+ ## `src/assets.ts`
8738
+
8739
+ ### `ctx.assets.memo`
8740
+
8741
+ `function` — Returns what `build` returned the last time this build of the game ran, read back from disk, and calls `build` only when nothing is stored. Use it for seeded work that is the same every run: placement lists, painted sky pixels, terrain heights, a generated stage.
8742
+
8743
+ ```ts
8744
+ ctx.assets.memo<T>(key: string, build: () => T | Promise<T>): Promise<T>
8745
+ ```
8746
+
8747
+ - **Use when:** cache generated geometry between page loads · stop rebuilding the same generated stage on every page load · cache painted sky pixels or baked terrain heights between runs · keep seeded placement work the same every run without recomputing it · make a slow boot fast without shipping a baked asset
8748
+ - **Constraints:** The value is named typed arrays; a map of names to typed arrays is what is stored. · On the dev server and on a native host `build` runs every time, and `TN_ASSET_MEMO` reports why: the cache is a build artifact, not a substitute for authoring. · A new build of the game regenerates: the key alone does not pin a value across a rebuild. · A game that drives a loader outside `defineGame` may call it whenever it likes; the reveal is not waited on.
8749
+ - **Overrides:** TN_ASSET_MEMO reports why a run rebuilt instead of reading the store
8750
+
8751
+ ```ts
8752
+ const { pixels } = await ctx.assets.memo("sky", () => ({ pixels: paintSky() }));
8753
+ ```
8754
+
8038
8755
  ## `src/audio/storm.ts`
8039
8756
 
8040
8757
  ### `createStormAudio`
@@ -8170,6 +8887,55 @@ createWeatherWorld(scene: Scene, camera: PerspectiveCamera): IWeatherWorld
8170
8887
  src/render/world.ts — edit the shader there, or the weather it is fed from src/state.ts
8171
8888
  ```
8172
8889
 
8890
+ ## `src/scene.ts`
8891
+
8892
+ ### `ctx.after`
8893
+
8894
+ `function` — Runs `callback` once, `delay` seconds of game time later, and returns a handle that cancels it. Game time stops while the game is paused, so a delayed beat does not fire behind a paused frame.
8895
+
8896
+ ```ts
8897
+ ctx.after(delay: number, callback: () => void): ScheduleHandle
8898
+ ```
8899
+
8900
+ - **Use when:** run a callback after a delay · schedule a one-shot timer that pauses with the game · do something a moment later without setTimeout · cancel a pending delayed action when a scene exits
8901
+ - **Constraints:** The delay is game seconds: a paused game does not age it, and a slow frame does not skip it. · `setTimeout` keeps running while the game is paused and after the scene is gone; this does not. · Call the returned handle to cancel: a pending callback holds its scene's closure alive.
8902
+
8903
+ ```ts
8904
+ const spawn = ctx.after(0.4, () => ctx.add(makeWave()));
8905
+ spawn(); // cancels
8906
+ ```
8907
+
8908
+ ### `ctx.beforeRender`
8909
+
8910
+ `function` — Registers work that runs once per actual world render, after the frame's last fixed update and before the projection reconciles and the renderer draws. The last place to change a transform, a uniform or a camera before the frame is presented.
8911
+
8912
+ ```ts
8913
+ ctx.beforeRender(callback: () => void): () => void
8914
+ ```
8915
+
8916
+ - **Use when:** run a callback just before the frame renders · update a camera or a uniform after physics and before the draw · change a transform in the same frame it is seen · run per-render work that must not run on a loader-only frame
8917
+ - **Constraints:** A held, loader-only frame has no world draw and dispatches nothing. · Runs after every fixed update in the frame, so a value it writes is the one drawn. · Returns an unregister function; call it when the object that needed it is gone.
8918
+
8919
+ ```ts
8920
+ const stop = ctx.beforeRender(() => (material.uniforms.time.value = clock.elapsed));
8921
+ // later: stop();
8922
+ ```
8923
+
8924
+ ### `ctx.startup.progress`
8925
+
8926
+ `function` — How much of the start scene has loaded and presented, 0 to 1, for a loading cover's bar. It never falls: a loader whose pending work grows keeps the number it reached rather than jumping backwards.
8927
+
8928
+ ```ts
8929
+ ctx.startup.progress: number
8930
+ ```
8931
+
8932
+ - **Use when:** boot progress bar · show how much of the start scene has loaded · loading screen percentage · a progress bar that never goes backwards · report startup progress while assets stream in
8933
+ - **Constraints:** Never decreases, even when the loader is asked for more work mid-boot. · Reaches 1 only after the first world render has been presented, not when the last byte arrived. · A loading view the engine drew for you already reads it; this is for a cover the game draws itself.
8934
+
8935
+ ```ts
8936
+ const width = `${Math.round(ctx.startup.progress * 100)}%`; // a cover the game draws on ctx.canvasLayer
8937
+ ```
8938
+
8173
8939
  ## `three/addons/tsl/display/BloomNode.js`
8174
8940
 
8175
8941
  ### `bloom`