create-threenative 0.2.9 → 0.2.12

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 (737) hide show
  1. package/agent-docs/references/assertion-reference.md +109 -3
  2. package/agent-docs/references/auto-exposure.md +28 -45
  3. package/agent-docs/references/build-profiles.md +1 -1
  4. package/agent-docs/references/capability-reference.md +527 -44
  5. package/agent-docs/references/debug-surface.md +64 -0
  6. package/agent-docs/references/finding-assets.md +11 -12
  7. package/agent-docs/references/performance-basics.md +19 -0
  8. package/agent-docs/references/trace-a-slow-frame.md +21 -0
  9. package/agent-docs/references/visual-baseline.md +23 -4
  10. package/agent-files/.agents/skills/ponytail/SKILL.md +1 -1
  11. package/agent-files/.agents/skills/prd-creator/SKILL.md +17 -6
  12. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +87 -23
  13. package/agent-files/.agents/skills/threenative-performance/SKILL.md +12 -11
  14. package/agent-files/.claude/hooks/ponytail-context.mjs +1 -1
  15. package/agent-files/scripts/reference.mjs +9 -4
  16. package/capabilities.json +739 -50
  17. package/dist/index.d.ts +40 -6
  18. package/dist/index.js +229 -36
  19. package/dist/quality.d.ts +12 -0
  20. package/dist/quality.js +166747 -0
  21. package/dist/threenative.js +60 -44
  22. package/dist/web-engine-gltf-loader.js +2 -0
  23. package/dist/web-engine-mesh-bvh-webgpu.js +1 -1
  24. package/dist/web-engine-mesh-bvh.js +7 -0
  25. package/dist/web-engine-post-effects.js +645 -19
  26. package/dist/web-engine-runtime.js +3528 -343
  27. package/package.json +19 -9
  28. package/template-assets/assets/bay-PROVENANCE.md +21 -0
  29. package/template-assets/assets/bay-ground.webp +0 -0
  30. package/template-assets/assets/bay-metal.webp +0 -0
  31. package/template-assets/assets/bay-pavement-normal.webp +0 -0
  32. package/template-assets/assets/bay-pavement.webp +0 -0
  33. package/template-assets/assets/bay-plaster-normal.webp +0 -0
  34. package/template-assets/assets/bay-plaster.webp +0 -0
  35. package/template-assets/assets/bay-wood-normal.webp +0 -0
  36. package/template-assets/assets/bay-wood.webp +0 -0
  37. package/template-assets/assets/tex-PROVENANCE.md +25 -0
  38. package/template-assets/assets/tex-bark-normal.webp +0 -0
  39. package/template-assets/assets/tex-bark.webp +0 -0
  40. package/template-assets/assets/tex-birch-bark.webp +0 -0
  41. package/template-assets/assets/tex-grass.webp +0 -0
  42. package/template-assets/assets/tex-planks-normal.webp +0 -0
  43. package/template-assets/assets/tex-planks.webp +0 -0
  44. package/template-assets/assets/tex-rock-normal.webp +0 -0
  45. package/template-assets/assets/tex-rock.webp +0 -0
  46. package/template-assets/assets/tex-roof-tiles-normal.webp +0 -0
  47. package/template-assets/assets/tex-roof-tiles.webp +0 -0
  48. package/template-assets/assets/tex-sand-normal.webp +0 -0
  49. package/template-assets/assets/tex-sand.webp +0 -0
  50. package/template-assets/assets/tex-stone-wall-normal.webp +0 -0
  51. package/template-assets/assets/tex-stone-wall.webp +0 -0
  52. package/template-assets/kitExposure.ts +20 -0
  53. package/template-assets/patches/three@0.185.1.patch +481 -272
  54. package/template-assets/quality/biome.json +7 -0
  55. package/template-assets/quality/eslint.config.js +3 -0
  56. package/template-assets/realistic-ocean/README.md +113 -0
  57. package/template-assets/realistic-ocean/install.mjs +56 -0
  58. package/template-assets/realistic-ocean/src/realisticOcean.ts +151 -0
  59. package/template-assets/realistic-ocean/src/realisticOceanLifetime.ts +29 -0
  60. package/template-assets/realistic-ocean/src/render/REALISTIC-OCEAN-LICENSE.txt +25 -0
  61. package/template-assets/realistic-ocean/src/render/realisticSea.ts +642 -0
  62. package/template-assets/realistic-ocean/src/render/realisticSeaMaps.ts +311 -0
  63. package/template-assets/realistic-ocean/src/render/realisticSpectrum.ts +289 -0
  64. package/templates/AGENTS.md +21 -0
  65. package/templates/CLAUDE.md +23 -0
  66. package/templates/action-rpg/.codex/config.toml +6 -2
  67. package/templates/action-rpg/.cursor/mcp.json +8 -2
  68. package/templates/action-rpg/.gemini/settings.json +8 -2
  69. package/templates/action-rpg/.mcp.json +8 -2
  70. package/templates/action-rpg/.vscode/mcp.json +9 -2
  71. package/templates/action-rpg/.zed/settings.json +9 -2
  72. package/templates/action-rpg/AGENTS.md +11 -11
  73. package/templates/action-rpg/CLAUDE.md +11 -11
  74. package/templates/action-rpg/opencode.json +10 -2
  75. package/templates/action-rpg/package.json +17 -11
  76. package/templates/action-rpg/playtests/combat.playtest.json +6 -0
  77. package/templates/action-rpg/playtests/inventory.playtest.json +22 -0
  78. package/templates/action-rpg/playtests/performance.playtest.json +1 -1
  79. package/templates/action-rpg/playtests/roll.playtest.json +112 -0
  80. package/templates/action-rpg/playtests/swing.playtest.json +55 -0
  81. package/templates/action-rpg/playtests/win.playtest.json +4 -4
  82. package/templates/action-rpg/src/entities/Fighter.ts +44 -4
  83. package/templates/action-rpg/src/entities/Player.ts +64 -12
  84. package/templates/action-rpg/src/render/atmosphere.ts +444 -0
  85. package/templates/action-rpg/src/render/backlightMaterial.ts +49 -18
  86. package/templates/action-rpg/src/render/clouds.ts +605 -0
  87. package/templates/action-rpg/src/render/dungeon.ts +8 -6
  88. package/templates/action-rpg/src/render/exposure.ts +11 -109
  89. package/templates/action-rpg/src/render/gpuSky.ts +752 -0
  90. package/templates/action-rpg/src/render/lighting.ts +27 -4
  91. package/templates/action-rpg/src/render/materialLighting.ts +2 -11
  92. package/templates/action-rpg/src/render/palette.ts +1 -0
  93. package/templates/action-rpg/src/render/postprocessing.ts +4 -4
  94. package/templates/action-rpg/src/render/props.ts +10 -8
  95. package/templates/action-rpg/src/render/quality.ts +56 -108
  96. package/templates/action-rpg/src/render/sky.ts +74 -1
  97. package/templates/action-rpg/src/scenes/Play.ts +16 -12
  98. package/templates/action-rpg/src/ui/CharacterPanel.tsx +7 -2
  99. package/templates/action-rpg/src/ui/Hud.tsx +5 -7
  100. package/templates/action-rpg/src/ui/InventoryPanel.tsx +14 -14
  101. package/templates/action-rpg/threenative.config.ts +3 -0
  102. package/templates/adventure/.codex/config.toml +23 -0
  103. package/templates/adventure/.cursor/mcp.json +38 -0
  104. package/templates/adventure/.gemini/settings.json +38 -0
  105. package/templates/adventure/.mcp.json +38 -0
  106. package/templates/adventure/.vscode/mcp.json +43 -0
  107. package/templates/adventure/.zed/settings.json +43 -0
  108. package/templates/adventure/AGENTS.md +60 -0
  109. package/templates/adventure/CLAUDE.md +62 -0
  110. package/templates/adventure/index.html +14 -0
  111. package/templates/adventure/kit.json +8 -0
  112. package/templates/adventure/native-playtests/survives.playtest.json +52 -0
  113. package/templates/adventure/opencode.json +49 -0
  114. package/templates/adventure/package.json +65 -0
  115. package/templates/adventure/playtests/boss.playtest.json +406 -0
  116. package/templates/adventure/playtests/combat.playtest.json +342 -0
  117. package/templates/adventure/playtests/controls.playtest.json +142 -0
  118. package/templates/adventure/playtests/explore.playtest.json +45 -0
  119. package/templates/adventure/playtests/flicker.playtest.json +206 -0
  120. package/templates/adventure/playtests/hearts.playtest.json +171 -0
  121. package/templates/adventure/playtests/lockon.playtest.json +256 -0
  122. package/templates/adventure/playtests/look.playtest.json +72 -0
  123. package/templates/adventure/playtests/move-hollow.playtest.json +106 -0
  124. package/templates/adventure/playtests/move.playtest.json +84 -0
  125. package/templates/adventure/playtests/performance.playtest.json +55 -0
  126. package/templates/adventure/playtests/puzzle.playtest.json +250 -0
  127. package/templates/adventure/playtests/stride.playtest.json +67 -0
  128. package/templates/adventure/playtests/survives.playtest.json +171 -0
  129. package/templates/adventure/playtests/thornback.playtest.json +267 -0
  130. package/templates/adventure/public/favicon.svg +4 -0
  131. package/templates/adventure/src/entities/Block.ts +114 -0
  132. package/templates/adventure/src/entities/Chest.ts +69 -0
  133. package/templates/adventure/src/entities/Door.ts +81 -0
  134. package/templates/adventure/src/entities/Dummy.ts +69 -0
  135. package/templates/adventure/src/entities/Flicker.ts +239 -0
  136. package/templates/adventure/src/entities/Hero.ts +561 -0
  137. package/templates/adventure/src/entities/LockOn.ts +180 -0
  138. package/templates/adventure/src/entities/Mossling.ts +249 -0
  139. package/templates/adventure/src/entities/Switch.ts +49 -0
  140. package/templates/adventure/src/entities/Thornback.ts +238 -0
  141. package/templates/adventure/src/entities/Warden.ts +196 -0
  142. package/templates/adventure/src/game.ts +65 -0
  143. package/templates/adventure/src/interact.ts +63 -0
  144. package/templates/adventure/src/level/Hollow.ts +240 -0
  145. package/templates/adventure/src/level/Vale.ts +383 -0
  146. package/templates/adventure/src/main.ts +18 -0
  147. package/templates/adventure/src/render/camera.ts +416 -0
  148. package/templates/adventure/src/render/creatures.ts +405 -0
  149. package/templates/adventure/src/render/effects.ts +333 -0
  150. package/templates/adventure/src/render/foliage.ts +1072 -0
  151. package/templates/adventure/src/render/hero.ts +1447 -0
  152. package/templates/adventure/src/render/kitExposure.ts +20 -0
  153. package/templates/adventure/src/render/lighting.ts +74 -0
  154. package/templates/adventure/src/render/loading.ts +332 -0
  155. package/templates/adventure/src/render/materials.ts +179 -0
  156. package/templates/adventure/src/render/palette.ts +137 -0
  157. package/templates/adventure/src/render/postprocessing.ts +70 -0
  158. package/templates/adventure/src/render/props.ts +383 -0
  159. package/templates/adventure/src/render/quality.ts +46 -0
  160. package/templates/adventure/src/render/sky.ts +271 -0
  161. package/templates/adventure/src/render/surface.ts +259 -0
  162. package/templates/adventure/src/render/touch-controls.ts +137 -0
  163. package/templates/adventure/src/scenes/Play.ts +959 -0
  164. package/templates/adventure/src/state.ts +113 -0
  165. package/templates/adventure/src/style.css +98 -0
  166. package/templates/adventure/src/ui/App.tsx +22 -0
  167. package/templates/adventure/src/ui/GameUi.tsx +20 -0
  168. package/templates/adventure/src/ui/Hud.tsx +70 -0
  169. package/templates/adventure/src/ui/Menu.tsx +15 -0
  170. package/templates/adventure/src/ui/main.tsx +14 -0
  171. package/templates/adventure/tailwind.config.ts +2 -0
  172. package/templates/adventure/threenative.config.ts +62 -0
  173. package/templates/adventure/tsconfig.json +17 -0
  174. package/templates/adventure/vite.config.ts +49 -0
  175. package/templates/collectathon/.codex/config.toml +23 -0
  176. package/templates/collectathon/.cursor/mcp.json +38 -0
  177. package/templates/collectathon/.gemini/settings.json +38 -0
  178. package/templates/collectathon/.mcp.json +38 -0
  179. package/templates/collectathon/.vscode/mcp.json +43 -0
  180. package/templates/collectathon/.zed/settings.json +43 -0
  181. package/templates/collectathon/AGENTS.md +58 -0
  182. package/templates/collectathon/CLAUDE.md +60 -0
  183. package/templates/collectathon/index.html +14 -0
  184. package/templates/collectathon/kit.json +8 -0
  185. package/templates/collectathon/native-playtests/survives.playtest.json +52 -0
  186. package/templates/collectathon/opencode.json +49 -0
  187. package/templates/collectathon/package.json +65 -0
  188. package/templates/collectathon/playtests/acrobatics.playtest.json +238 -0
  189. package/templates/collectathon/playtests/camera.playtest.json +80 -0
  190. package/templates/collectathon/playtests/clipped-probe.playtest.json +101 -0
  191. package/templates/collectathon/playtests/collect.playtest.json +196 -0
  192. package/templates/collectathon/playtests/combat.playtest.json +246 -0
  193. package/templates/collectathon/playtests/double-tap-air.playtest.json +198 -0
  194. package/templates/collectathon/playtests/double-tap.playtest.json +136 -0
  195. package/templates/collectathon/playtests/effects.playtest.json +124 -0
  196. package/templates/collectathon/playtests/enemies.playtest.json +295 -0
  197. package/templates/collectathon/playtests/explore.playtest.json +45 -0
  198. package/templates/collectathon/playtests/hop-reach.playtest.json +117 -0
  199. package/templates/collectathon/playtests/jump-chain.playtest.json +274 -0
  200. package/templates/collectathon/playtests/ledge-angle.playtest.json +107 -0
  201. package/templates/collectathon/playtests/ledge-too-high.playtest.json +115 -0
  202. package/templates/collectathon/playtests/ledge.playtest.json +100 -0
  203. package/templates/collectathon/playtests/look.playtest.json +64 -0
  204. package/templates/collectathon/playtests/performance.playtest.json +55 -0
  205. package/templates/collectathon/playtests/stride.playtest.json +111 -0
  206. package/templates/collectathon/playtests/survives.playtest.json +123 -0
  207. package/templates/collectathon/playtests/telegraphs.playtest.json +132 -0
  208. package/templates/collectathon/playtests/thornback.playtest.json +157 -0
  209. package/templates/collectathon/playtests/wall-kick.playtest.json +206 -0
  210. package/templates/collectathon/playtests/win.playtest.json +166 -0
  211. package/templates/collectathon/public/favicon.svg +4 -0
  212. package/templates/collectathon/src/entities/Hero.ts +915 -0
  213. package/templates/collectathon/src/entities/Pickup.ts +63 -0
  214. package/templates/collectathon/src/entities/Walker.ts +248 -0
  215. package/templates/collectathon/src/game.ts +51 -0
  216. package/templates/collectathon/src/level/Course.ts +590 -0
  217. package/templates/collectathon/src/level/terrain.ts +144 -0
  218. package/templates/collectathon/src/main.ts +14 -0
  219. package/templates/collectathon/src/playtest-events.ts +15 -0
  220. package/templates/collectathon/src/render/camera.ts +163 -0
  221. package/templates/collectathon/src/render/castle.ts +408 -0
  222. package/templates/collectathon/src/render/effects.ts +284 -0
  223. package/templates/collectathon/src/render/foliage.ts +744 -0
  224. package/templates/collectathon/src/render/ground.ts +139 -0
  225. package/templates/collectathon/src/render/hero.ts +452 -0
  226. package/templates/collectathon/src/render/kitExposure.ts +20 -0
  227. package/templates/collectathon/src/render/lighting.ts +65 -0
  228. package/templates/collectathon/src/render/loading.ts +332 -0
  229. package/templates/collectathon/src/render/materials.ts +196 -0
  230. package/templates/collectathon/src/render/palette.ts +82 -0
  231. package/templates/collectathon/src/render/postprocessing.ts +79 -0
  232. package/templates/collectathon/src/render/props.ts +218 -0
  233. package/templates/collectathon/src/render/quality.ts +54 -0
  234. package/templates/collectathon/src/render/sky.ts +262 -0
  235. package/templates/collectathon/src/render/surface.ts +269 -0
  236. package/templates/collectathon/src/render/touch-controls.ts +179 -0
  237. package/templates/collectathon/src/render/touch-layout.ts +48 -0
  238. package/templates/collectathon/src/render/water.ts +191 -0
  239. package/templates/collectathon/src/scenes/Play.ts +481 -0
  240. package/templates/collectathon/src/state.ts +38 -0
  241. package/templates/collectathon/src/style.css +106 -0
  242. package/templates/collectathon/src/ui/App.tsx +22 -0
  243. package/templates/collectathon/src/ui/GameUi.tsx +20 -0
  244. package/templates/collectathon/src/ui/Hud.tsx +77 -0
  245. package/templates/collectathon/src/ui/Menu.tsx +13 -0
  246. package/templates/collectathon/src/ui/main.tsx +14 -0
  247. package/templates/collectathon/tailwind.config.ts +2 -0
  248. package/templates/collectathon/threenative.config.ts +62 -0
  249. package/templates/collectathon/tsconfig.json +17 -0
  250. package/templates/collectathon/vite.config.ts +49 -0
  251. package/templates/kart/.codex/config.toml +23 -0
  252. package/templates/kart/.cursor/mcp.json +38 -0
  253. package/templates/kart/.gemini/settings.json +38 -0
  254. package/templates/kart/.mcp.json +38 -0
  255. package/templates/kart/.vscode/mcp.json +43 -0
  256. package/templates/kart/.zed/settings.json +43 -0
  257. package/templates/kart/AGENTS.md +58 -0
  258. package/templates/kart/CLAUDE.md +60 -0
  259. package/templates/kart/index.html +14 -0
  260. package/templates/kart/kit.json +8 -0
  261. package/templates/kart/native-playtests/survives.playtest.json +65 -0
  262. package/templates/kart/opencode.json +49 -0
  263. package/templates/kart/package.json +64 -0
  264. package/templates/kart/playtests/drift.playtest.json +226 -0
  265. package/templates/kart/playtests/explore.playtest.json +45 -0
  266. package/templates/kart/playtests/hit-stays-above-road.playtest.json +92 -0
  267. package/templates/kart/playtests/item-key.playtest.json +108 -0
  268. package/templates/kart/playtests/items.playtest.json +143 -0
  269. package/templates/kart/playtests/lap-times.playtest.json +138 -0
  270. package/templates/kart/playtests/laps.playtest.json +149 -0
  271. package/templates/kart/playtests/performance.playtest.json +57 -0
  272. package/templates/kart/playtests/race.playtest.json +294 -0
  273. package/templates/kart/playtests/restart.playtest.json +87 -0
  274. package/templates/kart/playtests/rocket-start.playtest.json +56 -0
  275. package/templates/kart/playtests/smooth-drive.playtest.json +101 -0
  276. package/templates/kart/playtests/surfaces.playtest.json +113 -0
  277. package/templates/kart/playtests/survives.playtest.json +116 -0
  278. package/templates/kart/playtests/wall.playtest.json +118 -0
  279. package/templates/kart/public/favicon.svg +4 -0
  280. package/templates/kart/src/entities/Driver.ts +123 -0
  281. package/templates/kart/src/entities/Items.ts +194 -0
  282. package/templates/kart/src/entities/Kart.ts +517 -0
  283. package/templates/kart/src/game.ts +45 -0
  284. package/templates/kart/src/main.ts +14 -0
  285. package/templates/kart/src/playtest-events.ts +15 -0
  286. package/templates/kart/src/render/camera.ts +83 -0
  287. package/templates/kart/src/render/course.ts +579 -0
  288. package/templates/kart/src/render/effects.ts +266 -0
  289. package/templates/kart/src/render/items.ts +163 -0
  290. package/templates/kart/src/render/kart.ts +256 -0
  291. package/templates/kart/src/render/kitExposure.ts +20 -0
  292. package/templates/kart/src/render/lighting.ts +58 -0
  293. package/templates/kart/src/render/loading.ts +332 -0
  294. package/templates/kart/src/render/materials.ts +119 -0
  295. package/templates/kart/src/render/palette.ts +74 -0
  296. package/templates/kart/src/render/postprocessing.ts +79 -0
  297. package/templates/kart/src/render/quality.ts +54 -0
  298. package/templates/kart/src/render/skids.ts +86 -0
  299. package/templates/kart/src/render/sky.ts +105 -0
  300. package/templates/kart/src/render/touch-controls.ts +168 -0
  301. package/templates/kart/src/render/touch-layout.ts +48 -0
  302. package/templates/kart/src/scenes/Race.ts +850 -0
  303. package/templates/kart/src/state.ts +53 -0
  304. package/templates/kart/src/style.css +106 -0
  305. package/templates/kart/src/track/Course.ts +276 -0
  306. package/templates/kart/src/track/Race.ts +133 -0
  307. package/templates/kart/src/ui/App.tsx +21 -0
  308. package/templates/kart/src/ui/GameUi.tsx +20 -0
  309. package/templates/kart/src/ui/Hud.tsx +172 -0
  310. package/templates/kart/src/ui/Menu.tsx +13 -0
  311. package/templates/kart/src/ui/main.tsx +14 -0
  312. package/templates/kart/tailwind.config.ts +2 -0
  313. package/templates/kart/threenative.config.ts +62 -0
  314. package/templates/kart/tsconfig.json +17 -0
  315. package/templates/kart/vite.config.ts +49 -0
  316. package/templates/minimal/.codex/config.toml +6 -2
  317. package/templates/minimal/.cursor/mcp.json +8 -2
  318. package/templates/minimal/.gemini/settings.json +8 -2
  319. package/templates/minimal/.mcp.json +8 -2
  320. package/templates/minimal/.vscode/mcp.json +9 -2
  321. package/templates/minimal/.zed/settings.json +9 -2
  322. package/templates/minimal/AGENTS.md +11 -13
  323. package/templates/minimal/CLAUDE.md +11 -13
  324. package/templates/minimal/opencode.json +10 -2
  325. package/templates/minimal/package.json +16 -10
  326. package/templates/minimal/playtests/camera-wall.playtest.json +36 -0
  327. package/templates/minimal/playtests/jump.playtest.json +45 -0
  328. package/templates/minimal/playtests/play.playtest.json +1 -1
  329. package/templates/minimal/src/game.ts +2 -0
  330. package/templates/minimal/src/render/atmosphere.ts +444 -0
  331. package/templates/minimal/src/render/backlightMaterial.ts +49 -18
  332. package/templates/minimal/src/render/camera.ts +35 -4
  333. package/templates/minimal/src/render/clouds.ts +605 -0
  334. package/templates/minimal/src/render/exposure.ts +7 -111
  335. package/templates/minimal/src/render/gpuSky.ts +752 -0
  336. package/templates/minimal/src/render/lighting.ts +26 -4
  337. package/templates/minimal/src/render/materialLighting.ts +2 -10
  338. package/templates/minimal/src/render/postprocessing.ts +4 -4
  339. package/templates/minimal/src/render/quality.ts +10 -116
  340. package/templates/minimal/src/render/sky.ts +73 -1
  341. package/templates/minimal/src/scenes/Play.ts +18 -7
  342. package/templates/platformer/.codex/config.toml +6 -2
  343. package/templates/platformer/.cursor/mcp.json +8 -2
  344. package/templates/platformer/.gemini/settings.json +8 -2
  345. package/templates/platformer/.mcp.json +8 -2
  346. package/templates/platformer/.vscode/mcp.json +9 -2
  347. package/templates/platformer/.zed/settings.json +9 -2
  348. package/templates/platformer/AGENTS.md +13 -9
  349. package/templates/platformer/CLAUDE.md +13 -9
  350. package/templates/platformer/opencode.json +10 -2
  351. package/templates/platformer/package.json +17 -11
  352. package/templates/platformer/playtests/dash-jump.playtest.json +34 -0
  353. package/templates/platformer/playtests/finish.playtest.json +58 -0
  354. package/templates/platformer/playtests/idle.playtest.json +44 -0
  355. package/templates/platformer/playtests/performance.playtest.json +1 -1
  356. package/templates/platformer/src/entities/Fox.ts +19 -6
  357. package/templates/platformer/src/game.ts +1 -0
  358. package/templates/platformer/src/level/Stage.ts +4 -1
  359. package/templates/platformer/src/render/backlightMaterial.ts +49 -18
  360. package/templates/platformer/src/render/camera.ts +30 -1
  361. package/templates/platformer/src/render/exposure.ts +6 -111
  362. package/templates/platformer/src/render/fox.ts +5 -2
  363. package/templates/platformer/src/render/kitExposure.ts +20 -0
  364. package/templates/platformer/src/render/materialLighting.ts +2 -11
  365. package/templates/platformer/src/render/postprocessing.ts +4 -4
  366. package/templates/platformer/src/render/props.ts +1 -2
  367. package/templates/platformer/src/render/quality.ts +10 -118
  368. package/templates/platformer/src/scenes/Play.ts +31 -15
  369. package/templates/platformer/src/ui/Menu.tsx +1 -1
  370. package/templates/puzzle/.codex/config.toml +6 -2
  371. package/templates/puzzle/.cursor/mcp.json +8 -2
  372. package/templates/puzzle/.gemini/settings.json +8 -2
  373. package/templates/puzzle/.mcp.json +8 -2
  374. package/templates/puzzle/.vscode/mcp.json +9 -2
  375. package/templates/puzzle/.zed/settings.json +9 -2
  376. package/templates/puzzle/AGENTS.md +14 -17
  377. package/templates/puzzle/CLAUDE.md +14 -17
  378. package/templates/puzzle/opencode.json +10 -2
  379. package/templates/puzzle/package.json +17 -11
  380. package/templates/puzzle/playtests/performance.playtest.json +1 -1
  381. package/templates/puzzle/playtests/replay-keeps-progress.playtest.json +78 -0
  382. package/templates/puzzle/src/render/backlightMaterial.ts +49 -18
  383. package/templates/puzzle/src/render/exposure.ts +11 -109
  384. package/templates/puzzle/src/render/lighting.ts +3 -3
  385. package/templates/puzzle/src/render/materialLighting.ts +2 -11
  386. package/templates/puzzle/src/render/palette.ts +1 -1
  387. package/templates/puzzle/src/render/postprocessing.ts +4 -4
  388. package/templates/puzzle/src/render/quality.ts +44 -153
  389. package/templates/puzzle/src/render/vault.ts +18 -6
  390. package/templates/puzzle/src/scenes/Play.ts +6 -1
  391. package/templates/puzzle/src/ui/Hud.tsx +8 -43
  392. package/templates/racing/.codex/config.toml +6 -2
  393. package/templates/racing/.cursor/mcp.json +8 -2
  394. package/templates/racing/.gemini/settings.json +8 -2
  395. package/templates/racing/.mcp.json +8 -2
  396. package/templates/racing/.vscode/mcp.json +9 -2
  397. package/templates/racing/.zed/settings.json +9 -2
  398. package/templates/racing/AGENTS.md +10 -12
  399. package/templates/racing/CLAUDE.md +10 -12
  400. package/templates/racing/opencode.json +10 -2
  401. package/templates/racing/package.json +17 -11
  402. package/templates/racing/playtests/brake.playtest.json +54 -0
  403. package/templates/racing/playtests/outcome.playtest.json +19 -0
  404. package/templates/racing/playtests/performance.playtest.json +1 -1
  405. package/templates/racing/playtests/stopped-car-is-not-rescued.playtest.json +59 -0
  406. package/templates/racing/src/entities/RacingCar.ts +12 -3
  407. package/templates/racing/src/entities/Rival.ts +11 -2
  408. package/templates/racing/src/render/atmosphere.ts +444 -0
  409. package/templates/racing/src/render/backlightMaterial.ts +49 -18
  410. package/templates/racing/src/render/clouds.ts +605 -0
  411. package/templates/racing/src/render/exposure.ts +6 -111
  412. package/templates/racing/src/render/gpuSky.ts +752 -0
  413. package/templates/racing/src/render/kitExposure.ts +20 -0
  414. package/templates/racing/src/render/lighting.ts +26 -4
  415. package/templates/racing/src/render/materialLighting.ts +2 -11
  416. package/templates/racing/src/render/materials.ts +2 -1
  417. package/templates/racing/src/render/postprocessing.ts +4 -4
  418. package/templates/racing/src/render/quality.ts +27 -115
  419. package/templates/racing/src/render/sky.ts +76 -5
  420. package/templates/racing/src/scenes/Race.ts +53 -42
  421. package/templates/racing/src/track/TrackSector.ts +5 -2
  422. package/templates/racing/src/ui/Hud.tsx +12 -7
  423. package/templates/rain/.codex/config.toml +6 -2
  424. package/templates/rain/.cursor/mcp.json +8 -2
  425. package/templates/rain/.gemini/settings.json +8 -2
  426. package/templates/rain/.mcp.json +8 -2
  427. package/templates/rain/.vscode/mcp.json +9 -2
  428. package/templates/rain/.zed/settings.json +9 -2
  429. package/templates/rain/AGENTS.md +12 -12
  430. package/templates/rain/CLAUDE.md +12 -12
  431. package/templates/rain/opencode.json +10 -2
  432. package/templates/rain/package.json +16 -10
  433. package/templates/rain/playtests/performance.playtest.json +1 -1
  434. package/templates/rain/src/game.ts +1 -1
  435. package/templates/rain/src/render/bloom-shader.ts +1 -1
  436. package/templates/rain/src/render/clouds-shader.ts +2 -2
  437. package/templates/rain/src/render/clouds.ts +2 -1
  438. package/templates/rain/src/render/exposure.ts +11 -109
  439. package/templates/rain/src/render/post-shader.ts +7 -11
  440. package/templates/rain/src/render/postprocessing.ts +8 -24
  441. package/templates/rain/src/render/quality.ts +44 -98
  442. package/templates/rain/src/render/world-shader.ts +281 -97
  443. package/templates/rain/src/render/world.ts +82 -2
  444. package/templates/rain/src/style.css +1 -1
  445. package/templates/rain/src/ui/GameUi.tsx +6 -2
  446. package/templates/rain/src/ui/Hud.tsx +1 -1
  447. package/templates/rain/tools/generate-shaders.mjs +2 -2
  448. package/templates/rain/tools/tempest-post.frag +4 -6
  449. package/templates/rain/tools/tempest-world.frag +80 -12
  450. package/templates/rts/.codex/config.toml +6 -2
  451. package/templates/rts/.cursor/mcp.json +8 -2
  452. package/templates/rts/.gemini/settings.json +8 -2
  453. package/templates/rts/.mcp.json +8 -2
  454. package/templates/rts/.vscode/mcp.json +9 -2
  455. package/templates/rts/.zed/settings.json +9 -2
  456. package/templates/rts/AGENTS.md +15 -16
  457. package/templates/rts/CLAUDE.md +15 -16
  458. package/templates/rts/opencode.json +10 -2
  459. package/templates/rts/package.json +16 -10
  460. package/templates/rts/playtests/performance.playtest.json +1 -1
  461. package/templates/rts/playtests/rts-attack.playtest.json +5 -0
  462. package/templates/rts/playtests/rts-build.playtest.json +20 -1
  463. package/templates/rts/playtests/rts-orders.playtest.json +1 -1
  464. package/templates/rts/playtests/rts-pause.playtest.json +112 -0
  465. package/templates/rts/playtests/rts-train.playtest.json +1 -1
  466. package/templates/rts/playtests/rts-zoom.playtest.json +81 -0
  467. package/templates/rts/src/game.ts +29 -7
  468. package/templates/rts/src/render/army.ts +181 -49
  469. package/templates/rts/src/render/backlightMaterial.ts +49 -18
  470. package/templates/rts/src/render/environment.ts +276 -0
  471. package/templates/rts/src/render/exposure.ts +3 -65
  472. package/templates/rts/src/render/ground.ts +478 -0
  473. package/templates/rts/src/render/lighting.ts +62 -11
  474. package/templates/rts/src/render/materialLighting.ts +2 -11
  475. package/templates/rts/src/render/materials.ts +47 -118
  476. package/templates/rts/src/render/palette.ts +30 -13
  477. package/templates/rts/src/render/picking.ts +18 -0
  478. package/templates/rts/src/render/postprocessing.ts +4 -4
  479. package/templates/rts/src/render/quality.ts +64 -85
  480. package/templates/rts/src/render/resources.ts +21 -22
  481. package/templates/rts/src/render/sky.ts +9 -12
  482. package/templates/rts/src/render/terrain.ts +36 -11
  483. package/templates/rts/src/scenes/Play.ts +373 -38
  484. package/templates/rts/src/sim/ai.ts +0 -11
  485. package/templates/rts/src/state.ts +46 -0
  486. package/templates/rts/src/style.css +1543 -0
  487. package/templates/rts/src/ui/Commands.tsx +204 -107
  488. package/templates/rts/src/ui/GameUi.tsx +12 -5
  489. package/templates/rts/src/ui/Hud.tsx +611 -116
  490. package/templates/rts/src/ui/Minimap.tsx +103 -37
  491. package/templates/rts/src/ui/icons.tsx +116 -0
  492. package/templates/rts/src/ui/labels.ts +73 -0
  493. package/templates/rts/src/ui/minimapPoint.ts +30 -0
  494. package/templates/rts/threenative.config.ts +1 -1
  495. package/templates/runner/.codex/config.toml +6 -2
  496. package/templates/runner/.cursor/mcp.json +8 -2
  497. package/templates/runner/.gemini/settings.json +8 -2
  498. package/templates/runner/.mcp.json +8 -2
  499. package/templates/runner/.vscode/mcp.json +9 -2
  500. package/templates/runner/.zed/settings.json +9 -2
  501. package/templates/runner/AGENTS.md +12 -12
  502. package/templates/runner/CLAUDE.md +12 -12
  503. package/templates/runner/opencode.json +10 -2
  504. package/templates/runner/package.json +17 -11
  505. package/templates/runner/playtests/near-miss.playtest.json +48 -0
  506. package/templates/runner/playtests/performance.playtest.json +2 -2
  507. package/templates/runner/playtests/stride.playtest.json +27 -0
  508. package/templates/runner/playtests/survives.playtest.json +2 -2
  509. package/templates/runner/src/conventions.ts +3 -1
  510. package/templates/runner/src/entities/Runner.ts +11 -5
  511. package/templates/runner/src/render/atmosphere.ts +444 -0
  512. package/templates/runner/src/render/backlightMaterial.ts +49 -18
  513. package/templates/runner/src/render/clouds.ts +605 -0
  514. package/templates/runner/src/render/exposure.ts +6 -111
  515. package/templates/runner/src/render/gpuSky.ts +752 -0
  516. package/templates/runner/src/render/kitExposure.ts +20 -0
  517. package/templates/runner/src/render/lighting.ts +26 -4
  518. package/templates/runner/src/render/materialLighting.ts +2 -11
  519. package/templates/runner/src/render/postprocessing.ts +4 -4
  520. package/templates/runner/src/render/quality.ts +26 -114
  521. package/templates/runner/src/render/sky.ts +73 -1
  522. package/templates/runner/src/scenes/Run.ts +19 -15
  523. package/templates/runner/src/track.ts +12 -3
  524. package/templates/sailing/.codex/config.toml +6 -2
  525. package/templates/sailing/.cursor/mcp.json +8 -2
  526. package/templates/sailing/.gemini/settings.json +8 -2
  527. package/templates/sailing/.mcp.json +8 -2
  528. package/templates/sailing/.vscode/mcp.json +9 -2
  529. package/templates/sailing/.zed/settings.json +9 -2
  530. package/templates/sailing/AGENTS.md +10 -11
  531. package/templates/sailing/CLAUDE.md +10 -11
  532. package/templates/sailing/opencode.json +10 -2
  533. package/templates/sailing/package.json +17 -11
  534. package/templates/sailing/playtests/fail.playtest.json +46 -5
  535. package/templates/sailing/playtests/float-after-the-run-ends.playtest.json +7 -0
  536. package/templates/sailing/playtests/performance.playtest.json +1 -1
  537. package/templates/sailing/src/game.ts +1 -0
  538. package/templates/sailing/src/render/backlightMaterial.ts +49 -18
  539. package/templates/sailing/src/render/exposure.ts +6 -111
  540. package/templates/sailing/src/render/kitExposure.ts +20 -0
  541. package/templates/sailing/src/render/materialLighting.ts +2 -11
  542. package/templates/sailing/src/render/ocean.ts +0 -1
  543. package/templates/sailing/src/render/postprocessing.ts +4 -4
  544. package/templates/sailing/src/render/quality.ts +31 -138
  545. package/templates/sailing/src/scenes/Sailing.ts +12 -4
  546. package/templates/sailing/src/ui/Hud.tsx +6 -2
  547. package/templates/sailing/src/ui/Menu.tsx +1 -1
  548. package/templates/shooter/.codex/config.toml +6 -2
  549. package/templates/shooter/.cursor/mcp.json +8 -2
  550. package/templates/shooter/.gemini/settings.json +8 -2
  551. package/templates/shooter/.mcp.json +8 -2
  552. package/templates/shooter/.vscode/mcp.json +9 -2
  553. package/templates/shooter/.zed/settings.json +9 -2
  554. package/templates/shooter/AGENTS.md +13 -12
  555. package/templates/shooter/CLAUDE.md +13 -12
  556. package/templates/shooter/index.html +1 -1
  557. package/templates/shooter/main.html +13 -0
  558. package/templates/shooter/opencode.json +10 -2
  559. package/templates/shooter/package.json +17 -11
  560. package/templates/shooter/playtests/breakable-shatters.playtest.json +6 -0
  561. package/templates/shooter/playtests/enemy-body-is-a-body.playtest.json +6 -0
  562. package/templates/shooter/playtests/hands-authored-rate.playtest.json +54 -0
  563. package/templates/shooter/playtests/movement-eases.playtest.json +53 -0
  564. package/templates/shooter/playtests/performance.playtest.json +3 -3
  565. package/templates/shooter/playtests/stairs-smooth-the-eye.playtest.json +56 -0
  566. package/templates/shooter/playtests/weapon-sharp-while-turning.playtest.json +206 -0
  567. package/templates/shooter/src/entities/Breakables.ts +34 -10
  568. package/templates/shooter/src/entities/Enemy.ts +176 -54
  569. package/templates/shooter/src/entities/FpsPlayer.ts +55 -16
  570. package/templates/shooter/src/entities/Rifle.ts +83 -9
  571. package/templates/shooter/src/entities/movement.ts +96 -0
  572. package/templates/shooter/src/render/atmosphere.ts +444 -0
  573. package/templates/shooter/src/render/backlightMaterial.ts +49 -18
  574. package/templates/shooter/src/render/camera.ts +3 -1
  575. package/templates/shooter/src/render/clouds.ts +605 -0
  576. package/templates/shooter/src/render/exposure.ts +10 -109
  577. package/templates/shooter/src/render/facade.ts +26 -68
  578. package/templates/shooter/src/render/gpuSky.ts +752 -0
  579. package/templates/shooter/src/render/lighting.ts +27 -4
  580. package/templates/shooter/src/render/materialAssignments.ts +9 -1
  581. package/templates/shooter/src/render/materialLighting.ts +2 -11
  582. package/templates/shooter/src/render/occlusion.ts +13 -4
  583. package/templates/shooter/src/render/palette.ts +1 -0
  584. package/templates/shooter/src/render/postprocessing.ts +4 -4
  585. package/templates/shooter/src/render/quality.ts +50 -108
  586. package/templates/shooter/src/render/scale.ts +0 -11
  587. package/templates/shooter/src/render/sky.ts +103 -2
  588. package/templates/shooter/src/render/surface.ts +140 -0
  589. package/templates/shooter/src/render/town.ts +3 -6
  590. package/templates/shooter/src/render/townMaterials.ts +95 -42
  591. package/templates/shooter/src/render/vehicles.ts +2 -0
  592. package/templates/shooter/src/scenes/Play.ts +83 -23
  593. package/templates/shooter/src/ui/Hud.tsx +268 -193
  594. package/templates/shooter/src/worker-page.ts +29 -0
  595. package/templates/shooter/src/worker.ts +5 -0
  596. package/templates/shooter/threenative.config.ts +3 -0
  597. package/templates/shooter/vite.config.ts +2 -0
  598. package/templates/snow/.codex/config.toml +6 -2
  599. package/templates/snow/.cursor/mcp.json +8 -2
  600. package/templates/snow/.gemini/settings.json +8 -2
  601. package/templates/snow/.mcp.json +8 -2
  602. package/templates/snow/.vscode/mcp.json +9 -2
  603. package/templates/snow/.zed/settings.json +9 -2
  604. package/templates/snow/AGENTS.md +12 -10
  605. package/templates/snow/CLAUDE.md +12 -10
  606. package/templates/snow/opencode.json +10 -2
  607. package/templates/snow/package.json +17 -11
  608. package/templates/snow/playtests/performance.playtest.json +1 -1
  609. package/templates/snow/src/render/backlightMaterial.ts +49 -18
  610. package/templates/snow/src/render/exposure.ts +17 -106
  611. package/templates/snow/src/render/materialLighting.ts +2 -11
  612. package/templates/snow/src/render/postprocessing.ts +11 -5
  613. package/templates/snow/src/render/quality.ts +46 -126
  614. package/templates/snow/src/render/snowSurface.ts +32 -15
  615. package/templates/snow/src/scenes/Snow.ts +2 -1
  616. package/templates/starter/.codex/config.toml +6 -2
  617. package/templates/starter/.cursor/mcp.json +8 -2
  618. package/templates/starter/.gemini/settings.json +8 -2
  619. package/templates/starter/.mcp.json +8 -2
  620. package/templates/starter/.vscode/mcp.json +9 -2
  621. package/templates/starter/.zed/settings.json +9 -2
  622. package/templates/starter/AGENTS.md +18 -14
  623. package/templates/starter/CLAUDE.md +18 -14
  624. package/templates/starter/index.html +1 -1
  625. package/templates/starter/main.html +12 -0
  626. package/templates/starter/native-playtests/react-hud.playtest.json +1 -0
  627. package/templates/starter/native-playtests/render-chain.playtest.json +34 -21
  628. package/templates/starter/opencode.json +10 -2
  629. package/templates/starter/package.json +17 -11
  630. package/templates/starter/playtests/play.playtest.json +22 -2
  631. package/templates/starter/playtests/production-readiness.playtest.json +56 -0
  632. package/templates/starter/src/entities/Crate.ts +19 -1
  633. package/templates/starter/src/render/arena.ts +2 -2
  634. package/templates/starter/src/render/atmosphere.ts +444 -0
  635. package/templates/starter/src/render/backlightMaterial.ts +49 -18
  636. package/templates/starter/src/render/camera.ts +28 -0
  637. package/templates/starter/src/render/clouds.ts +605 -0
  638. package/templates/starter/src/render/contactShadow.ts +50 -0
  639. package/templates/starter/src/render/exposure.ts +9 -111
  640. package/templates/starter/src/render/gpuSky.ts +752 -0
  641. package/templates/starter/src/render/grade.ts +1 -1
  642. package/templates/starter/src/render/lighting.ts +34 -6
  643. package/templates/starter/src/render/materialLighting.ts +2 -11
  644. package/templates/starter/src/render/postprocessing.ts +53 -34
  645. package/templates/starter/src/render/quality.ts +18 -147
  646. package/templates/starter/src/render/sky.ts +90 -40
  647. package/templates/starter/src/render/temporalAA.ts +1 -1
  648. package/templates/starter/src/render/temporalAAStage.ts +1 -1
  649. package/templates/starter/src/render/temporalCurrentFootprint.ts +0 -1
  650. package/templates/starter/src/render/temporalDetailStage.ts +106 -0
  651. package/templates/starter/src/render/temporalRejectionCounter.ts +2 -2
  652. package/templates/starter/src/render/volumetricFogCamera.ts +32 -0
  653. package/templates/starter/src/render/volumetricFogOptions.ts +7 -0
  654. package/templates/starter/src/render/volumetricFogTransport.ts +27 -19
  655. package/templates/starter/src/render/volumetricFogVolume.ts +31 -7
  656. package/templates/starter/src/scenes/Play.ts +11 -8
  657. package/templates/starter/src/ui/Hud.tsx +1 -1
  658. package/templates/starter/src/worker-page.ts +29 -0
  659. package/templates/starter/src/worker.ts +5 -0
  660. package/templates/starter/vite.config.ts +2 -0
  661. package/templates/tower-defense/.codex/config.toml +6 -2
  662. package/templates/tower-defense/.cursor/mcp.json +8 -2
  663. package/templates/tower-defense/.gemini/settings.json +8 -2
  664. package/templates/tower-defense/.mcp.json +8 -2
  665. package/templates/tower-defense/.vscode/mcp.json +9 -2
  666. package/templates/tower-defense/.zed/settings.json +9 -2
  667. package/templates/tower-defense/AGENTS.md +10 -12
  668. package/templates/tower-defense/CLAUDE.md +10 -12
  669. package/templates/tower-defense/opencode.json +10 -2
  670. package/templates/tower-defense/package.json +17 -11
  671. package/templates/tower-defense/playtests/chill-tint.playtest.json +387 -0
  672. package/templates/tower-defense/playtests/performance.playtest.json +1 -1
  673. package/templates/tower-defense/src/enemies/Enemy.ts +9 -0
  674. package/templates/tower-defense/src/render/backlightMaterial.ts +49 -18
  675. package/templates/tower-defense/src/render/exposure.ts +11 -109
  676. package/templates/tower-defense/src/render/lighting.ts +4 -2
  677. package/templates/tower-defense/src/render/materialLighting.ts +2 -11
  678. package/templates/tower-defense/src/render/postprocessing.ts +4 -4
  679. package/templates/tower-defense/src/render/quality.ts +10 -116
  680. package/templates/tower-defense/src/render/sky.ts +2 -2
  681. package/templates/tower-defense/src/scenes/Battle.ts +4 -0
  682. package/template-assets/autoExposure.ts +0 -225
  683. package/template-assets/exposureGraph.ts +0 -178
  684. package/template-assets/exposureReadback.ts +0 -79
  685. package/template-assets/worldEnvironment.ts +0 -1212
  686. package/templates/action-rpg/src/render/autoExposure.ts +0 -225
  687. package/templates/action-rpg/src/render/exposureGraph.ts +0 -178
  688. package/templates/action-rpg/src/render/exposureReadback.ts +0 -79
  689. package/templates/action-rpg/src/render/worldEnvironment.ts +0 -1212
  690. package/templates/minimal/src/render/autoExposure.ts +0 -225
  691. package/templates/minimal/src/render/exposureGraph.ts +0 -178
  692. package/templates/minimal/src/render/exposureReadback.ts +0 -79
  693. package/templates/minimal/src/render/worldEnvironment.ts +0 -1212
  694. package/templates/platformer/src/render/autoExposure.ts +0 -225
  695. package/templates/platformer/src/render/exposureGraph.ts +0 -178
  696. package/templates/platformer/src/render/exposureReadback.ts +0 -79
  697. package/templates/platformer/src/render/worldEnvironment.ts +0 -1212
  698. package/templates/puzzle/src/render/autoExposure.ts +0 -225
  699. package/templates/puzzle/src/render/exposureGraph.ts +0 -178
  700. package/templates/puzzle/src/render/exposureReadback.ts +0 -79
  701. package/templates/puzzle/src/render/worldEnvironment.ts +0 -1212
  702. package/templates/racing/src/render/autoExposure.ts +0 -225
  703. package/templates/racing/src/render/exposureGraph.ts +0 -178
  704. package/templates/racing/src/render/exposureReadback.ts +0 -79
  705. package/templates/racing/src/render/worldEnvironment.ts +0 -1212
  706. package/templates/rain/src/render/autoExposure.ts +0 -225
  707. package/templates/rain/src/render/exposureGraph.ts +0 -178
  708. package/templates/rain/src/render/exposureReadback.ts +0 -79
  709. package/templates/rain/src/render/worldEnvironment.ts +0 -1212
  710. package/templates/rts/src/render/autoExposure.ts +0 -225
  711. package/templates/rts/src/render/exposureGraph.ts +0 -178
  712. package/templates/rts/src/render/exposureReadback.ts +0 -79
  713. package/templates/rts/src/render/worldEnvironment.ts +0 -1212
  714. package/templates/runner/src/render/autoExposure.ts +0 -225
  715. package/templates/runner/src/render/exposureGraph.ts +0 -178
  716. package/templates/runner/src/render/exposureReadback.ts +0 -79
  717. package/templates/runner/src/render/worldEnvironment.ts +0 -1212
  718. package/templates/sailing/src/render/autoExposure.ts +0 -225
  719. package/templates/sailing/src/render/exposureGraph.ts +0 -178
  720. package/templates/sailing/src/render/exposureReadback.ts +0 -79
  721. package/templates/sailing/src/render/worldEnvironment.ts +0 -1212
  722. package/templates/shooter/src/render/autoExposure.ts +0 -225
  723. package/templates/shooter/src/render/exposureGraph.ts +0 -178
  724. package/templates/shooter/src/render/exposureReadback.ts +0 -79
  725. package/templates/shooter/src/render/worldEnvironment.ts +0 -1212
  726. package/templates/snow/src/render/autoExposure.ts +0 -225
  727. package/templates/snow/src/render/exposureGraph.ts +0 -178
  728. package/templates/snow/src/render/exposureReadback.ts +0 -79
  729. package/templates/snow/src/render/worldEnvironment.ts +0 -1212
  730. package/templates/starter/src/render/autoExposure.ts +0 -225
  731. package/templates/starter/src/render/exposureGraph.ts +0 -178
  732. package/templates/starter/src/render/exposureReadback.ts +0 -79
  733. package/templates/starter/src/render/worldEnvironment.ts +0 -1212
  734. package/templates/tower-defense/src/render/autoExposure.ts +0 -225
  735. package/templates/tower-defense/src/render/exposureGraph.ts +0 -178
  736. package/templates/tower-defense/src/render/exposureReadback.ts +0 -79
  737. package/templates/tower-defense/src/render/worldEnvironment.ts +0 -1212
@@ -417,6 +417,21 @@ if (!uvsTile(uv)) rewriteUvs(uv, transforms.get(source)!);
417
417
 
418
418
  ## `@threenative/core`
419
419
 
420
+ ### `addFoliageBackLight`
421
+
422
+ `function` — Adds subsurfaceColor times the far-face irradiance to a Two Sided Foliage leaf's emissive node.
423
+
424
+ ```ts
425
+ export function addFoliageBackLight(material: Material, backIrradiance: Node<"vec3">): boolean { … }
426
+ ```
427
+
428
+ - **Use when:** add bounce light to the far face of a two sided foliage leaf
429
+ - **Constraints:** the material needs the foliage marker and subsurfaceColor, else nothing is added and false is returned; call once per material · the material needs `twoSidedFoliage = true` and a `subsurfaceColor`, or nothing is added and false is returned; backIrradiance is a vec3 node in the unit of `irradianceNode`; call once per material
430
+
431
+ ```ts
432
+ addFoliageBackLight(leaf, backIrradiance);
433
+ ```
434
+
420
435
  ### `addInSlices`
421
436
 
422
437
  `function` — Attach hundreds of built objects to the scene in slices, presenting a frame between each.
@@ -549,15 +564,15 @@ animation.setWeights([0.5, 0.5]); animation.update(dt);
549
564
 
550
565
  ### `AnimationPlayer`
551
566
 
552
- `class` — Play a skinned or sprite animation from game code. A locomotion clip's playback rate is matched to the ground the body actually covers, so feet do not skate or spin — on by default, `strideSync: false` to keep the authored rate, and `player.stride` reports the measurement either way. Name the body a game moves as `strideRoot` when the rig is a child of it. Clips authored **in place** — every ActorX and Unreal export, every Mixamo "in place" clip, every stock animal pack — are matched too: their stride is read off the ground a planted foot sweeps, and `stride.inPlace` says so.
567
+ `class` — Play a skinned or sprite animation from game code. A locomotion clip's playback rate is matched to the ground the body actually covers, so feet do not skate or spin — on by default, `strideSync: false` to keep the authored rate, and `player.stride` reports the measurement either way. Name the body a game moves as `strideRoot` when the rig is a child of it. Clips authored **in place** — every ActorX and Unreal export, every Mixamo "in place" clip, every stock animal pack — are matched too: their stride is read off the ground a planted foot sweeps, and `stride.inPlace` says so. A mesh counts at its lowest geometry point, so a boot's origin may sit anywhere; an in-place clip with no foot plant reports `inPlace: true` and `clipGroundSpeed: 0`, and stride sync stays off. Evaluation is automatic by default: `updateRate: "auto"` follows measured camera visibility and projected size. `updateRate: 1` evaluates every frame; another positive safe integer names that frame interval. `updateRateReport` reports the effective rate, whether a named override is active, and whether the latest update evaluated. 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 the player to full-rate and observes only loop events after registration, so skipped pre-registration cycles are not replayed; `updateRateReport` reports that effective rate.
553
568
 
554
569
  ```ts
555
570
  export class AnimationPlayer { … }
556
571
  ```
557
572
 
558
- - **Use when:** play an animation on a character · switch a character between idle and attack clips · stop a walking character's feet from sliding or spinning · match a walk or run cycle to how fast a character is moving · match an in-place walk cycle with no root motion to the body's speed · find out what speed an animation clip was authored for
559
- - **Constraints:** name the body a game moves as strideRoot when the animated rig is a child of it · a one-shot clip always plays at its authored rate; the matched rate re-times loops only · the matched rate is held inside 0.15x-3x; a speed outside what the clip's own stride supports is clamped, and `stride.rate` says so
560
- - **Overrides:** strideSync controls whether the matched rate is applied while stride is still measured
573
+ - **Use when:** play an animation on a character · switch a character between idle and attack clips · stop a walking character's feet from sliding or spinning · match a walk or run cycle to how fast a character is moving · match an in-place walk cycle with no root motion to the body's speed · find out what speed an animation clip was authored for · reduce animation CPU for distant characters · inspect the effective animation evaluation rate
574
+ - **Constraints:** name the body a game moves as strideRoot when the animated rig is a child of it · a one-shot clip always plays at its authored rate; the matched rate re-times loops only · a foot mesh is measured at its lowest geometry point (the sole), never its origin; a skinned mesh is measured through its bones · `stride.inPlace: true` with `clipGroundSpeed: 0` means no foot plant was found and stride sync is not active; the playtest `stride` observation carries `inPlace` · the matched rate is held inside 0.15x-3x; a speed outside what the clip's own stride supports is clamped, and `stride.rate` says so
575
+ - **Overrides:** strideSync controls whether the matched rate is applied while stride is still measured · updateRate: "auto" chooses the camera-based interval; 1 is full evaluation, and another positive safe integer requests that interval; a public `mixer` `"loop"` listener promotes effective evaluation to 1 to preserve event timing
561
576
 
562
577
  ```ts
563
578
  const player = new AnimationPlayer({ clips, root: rig, strideRoot: body });
@@ -642,6 +657,22 @@ export class AudioBus { … }
642
657
  const effects = new AudioBus({ camera });
643
658
  ```
644
659
 
660
+ ### `AutoExposureNode`
661
+
662
+ `class` — Auto exposure with Unreal 5.8.3's metering: a 64-bin histogram of log2 luminance (the darkest and brightest 10% ignored), key 0.18 x 2, -10 to +20 EV100, 3 stops/s brighter and 1 stop/s darker. `AutoExposureNode` meters a colour texture and outputs the adapted exposure; `exposureSettings` holds the defaults.
663
+
664
+ ```ts
665
+ export class AutoExposureNode extends TempNode<"float"> { … }
666
+ ```
667
+
668
+ - **Use when:** the frame should expose itself the way a fresh Unreal project does as the sun and the view change · a white snowfield or a bright storm should not meter to middle grey, and the compensation changes with the weather
669
+ - **Constraints:** WebGPU renderers only: a renderer without WebGPU keeps the fixed exposure and says so
670
+ - **Overrides:** every `IExposureSettings` field, spread over `exposureSettings` and passed to `AutoExposureNode`, replaces the Unreal default · `setExposureBias(stops)` is Unreal's Exposure Compensation, live: the game changes it per place or weather (`WorldEnvironment.apply` returns the node as `exposure`)
671
+
672
+ ```ts
673
+ const slow = { ...exposureSettings, rateDown: 0.5 }; const node = new AutoExposureNode(input, slow, 1);
674
+ ```
675
+
645
676
  ### `baseGeometryOf`
646
677
 
647
678
  `function` — The full-detail geometry of a mesh the loader gave an automatic LOD chain. Selection swaps `mesh.geometry`, so a ray test or a collision body built from the current geometry would change with the camera. Framework picking and gameplay collide against this instead: the authored LOD0, which never changes as the camera moves.
@@ -766,6 +797,22 @@ import { boneLengths } from "@threenative/core";
766
797
  const baseline = boneLengths(character);
767
798
  ```
768
799
 
800
+ ### `BudgetLadder`
801
+
802
+ `class` — A cost ladder for one render stage: the whole GPU frame against the frame period moves it, by Unreal's DynamicRenderScaling rule. A frame over the period for 2 frames in a row steps the level down at once, a frame over the period less 10% headroom steps it down after the 8-frame change period, and a frame with room steps it up. A stage steps only when it could absorb the overage at zero cost, and a level that failed is retried after a growing wait. It decides when to move; the game applies the move.
803
+
804
+ ```ts
805
+ export class BudgetLadder<L extends string> { … }
806
+ ```
807
+
808
+ - **Use when:** step a render stage down when the GPU frame goes over the frame period · pick a quality level from measured GPU time without oscillating
809
+ - **Constraints:** levels are listed cheapest first, and the frame period is the game's own display target · a frame without a resolved GPU reading never moves the level
810
+ - **Overrides:** explicit: true keeps the level and only reports a frame over the target
811
+
812
+ ```ts
813
+ const ladder = new BudgetLadder({ levels: ["low", "high"], framePeriodMs: 1000 / 60, start: "high" }); const window = ladder.observe(stageMs, frameMs);
814
+ ```
815
+
769
816
  ### `bvhIntersectFirstHit`
770
817
 
771
818
  `function` — Pack a selected static scene into TSL storage nodes for an upstream BVH ray query.
@@ -950,8 +997,9 @@ const counters = FrameCounters.install(counterDeviceOf(renderer.raw));
950
997
  export function createAssetLoader(options: IAssetLoaderOptions = { … }
951
998
  ```
952
999
 
953
- - **Use when:** preload models, textures, or audio before a scene enters · load assets from a nonstandard base path or a compiled asset manifest
954
- - **Constraints:** reuse the loader handed to scenes as `ctx.assets` instead of building parallel caches
1000
+ - **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
1001
+ - **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
1002
+ - **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`
955
1003
 
956
1004
  ```ts
957
1005
  const assets = createAssetLoader({ basePath: "/assets" });
@@ -1056,7 +1104,7 @@ const game = defineGame({ input: { zoom: { scroll: true, pinch: true } }, scenes
1056
1104
 
1057
1105
  ### `describeSceneShape`
1058
1106
 
1059
- `function` — Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its JS render phase is longer than the display's own period is a scene-shape problem, and the engine already has the shape. On by default, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.
1107
+ `function` — Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its JS render phase is longer than the display's own period is a scene-shape problem, and the engine already has the shape. On by default in a debug launch, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.
1060
1108
 
1061
1109
  ```ts
1062
1110
  export function describeSceneShape( window: IFrameBudgetWindow, cull: IRenderCameraCullReport | undefined, ): ISceneShape | undefined { … }
@@ -1071,7 +1119,7 @@ defineGame({ display: { maxFps: 60 }, scenes: { Play } });
1071
1119
 
1072
1120
  ### `describeSceneWarning`
1073
1121
 
1074
- `function` — Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its JS render phase is longer than the display's own period is a scene-shape problem, and the engine already has the shape. On by default, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.
1122
+ `function` — Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its JS render phase is longer than the display's own period is a scene-shape problem, and the engine already has the shape. On by default in a debug launch, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.
1075
1123
 
1076
1124
  ```ts
1077
1125
  export function describeSceneWarning(warning: ISceneWarning): string { … }
@@ -1116,7 +1164,7 @@ const direction = directionFromSolarPosition(sun.elevation, sun.azimuth);
1116
1164
 
1117
1165
  ### `displayPeriodMs`
1118
1166
 
1119
- `function` — Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its JS render phase is longer than the display's own period is a scene-shape problem, and the engine already has the shape. On by default, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.
1167
+ `function` — Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its JS render phase is longer than the display's own period is a scene-shape problem, and the engine already has the shape. On by default in a debug launch, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.
1120
1168
 
1121
1169
  ```ts
1122
1170
  export function displayPeriodMs( declaredTargetFps: number | undefined, ): { … }
@@ -1165,6 +1213,51 @@ renderer.render(scene, camera);
1165
1213
  tracker.commit(scene);
1166
1214
  ```
1167
1215
 
1216
+ ### `ev100FromCamera`
1217
+
1218
+ `function` — Photometric exposure units: EV100 to the renderer multiplier and back, a physical camera's EV100, and a meter reading. Conversion only; the exposure and the light values are the game's.
1219
+
1220
+ ```ts
1221
+ export function ev100FromCamera(aperture: number, shutterSeconds: number, iso: number): number { … }
1222
+ ```
1223
+
1224
+ - **Use when:** expose a frame lit in lux and nits with a physical camera exposure value · expose like a camera with an aperture, a shutter time and an ISO
1225
+ - **Constraints:** arguments must be finite; multipliers, apertures, shutter times, ISO and luminance must be > 0 · every argument must be finite and greater than zero
1226
+
1227
+ ```ts
1228
+ renderer.toneMappingExposure = exposureFromEv100(ev100FromCamera(4, 1 / 60, 100));
1229
+ ```
1230
+
1231
+ ### `ev100FromExposure`
1232
+
1233
+ `function` — Photometric exposure units: EV100 to the renderer multiplier and back, a physical camera's EV100, and a meter reading. Conversion only; the exposure and the light values are the game's.
1234
+
1235
+ ```ts
1236
+ export function ev100FromExposure(multiplier: number): number { … }
1237
+ ```
1238
+
1239
+ - **Use when:** expose a frame lit in lux and nits with a physical camera exposure value · report a hand-set exposure multiplier as an EV100
1240
+ - **Constraints:** arguments must be finite; multipliers, apertures, shutter times, ISO and luminance must be > 0 · multiplier must be finite and greater than zero
1241
+
1242
+ ```ts
1243
+ renderer.toneMappingExposure = exposureFromEv100(ev100FromCamera(4, 1 / 60, 100));
1244
+ ```
1245
+
1246
+ ### `ev100FromLuminance`
1247
+
1248
+ `function` — Photometric exposure units: EV100 to the renderer multiplier and back, a physical camera's EV100, and a meter reading. Conversion only; the exposure and the light values are the game's.
1249
+
1250
+ ```ts
1251
+ export function ev100FromLuminance(luminance: number): number { … }
1252
+ ```
1253
+
1254
+ - **Use when:** expose a frame lit in lux and nits with a physical camera exposure value · meter a frame's average luminance in cd/m² into an exposure value
1255
+ - **Constraints:** arguments must be finite; multipliers, apertures, shutter times, ISO and luminance must be > 0 · luminance must be finite and greater than zero
1256
+
1257
+ ```ts
1258
+ renderer.toneMappingExposure = exposureFromEv100(ev100FromCamera(4, 1 / 60, 100));
1259
+ ```
1260
+
1168
1261
  ### `exposeDebug`
1169
1262
 
1170
1263
  `function` — Publish one game object under `__THREENATIVE__.debug` for a capture script or the console.
@@ -1182,6 +1275,21 @@ exposeDebug("player", player);
1182
1275
  // then from the console: __THREENATIVE__.debug.player
1183
1276
  ```
1184
1277
 
1278
+ ### `exposureFromEv100`
1279
+
1280
+ `function` — Photometric exposure units: EV100 to the renderer multiplier and back, a physical camera's EV100, and a meter reading. Conversion only; the exposure and the light values are the game's.
1281
+
1282
+ ```ts
1283
+ export function exposureFromEv100(ev100: number): number { … }
1284
+ ```
1285
+
1286
+ - **Use when:** expose a frame lit in lux and nits with a physical camera exposure value
1287
+ - **Constraints:** arguments must be finite; multipliers, apertures, shutter times, ISO and luminance must be > 0 · ev100 must be finite; a unitless scene keeps its own multiplier instead
1288
+
1289
+ ```ts
1290
+ renderer.toneMappingExposure = exposureFromEv100(ev100FromCamera(4, 1 / 60, 100));
1291
+ ```
1292
+
1185
1293
  ### `FlightModel`
1186
1294
 
1187
1295
  `class` — Fly a fixed-wing aircraft with a real force balance instead of a steered velocity.
@@ -1236,7 +1344,7 @@ water.fill([-2.8, 0.1, -1.5], [-0.6, 3, 1.5]);
1236
1344
 
1237
1345
  ### `formatSceneWarning`
1238
1346
 
1239
- `function` — Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its JS render phase is longer than the display's own period is a scene-shape problem, and the engine already has the shape. On by default, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.
1347
+ `function` — Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its JS render phase is longer than the display's own period is a scene-shape problem, and the engine already has the shape. On by default in a debug launch, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.
1240
1348
 
1241
1349
  ```ts
1242
1350
  export function formatSceneWarning(warning: ISceneWarning): string { … }
@@ -1350,12 +1458,45 @@ export function getPlatform(): Readonly<IPlatformInfo> { … }
1350
1458
  ```
1351
1459
 
1352
1460
  - **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native
1353
- - **Constraints:** only use the returned platform facts; native globals are host-owned · 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
1461
+ - **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
1354
1462
 
1355
1463
  ```ts
1356
1464
  if (isMobile()) showTouchControls();
1357
1465
  ```
1358
1466
 
1467
+ ### `GIBudget`
1468
+
1469
+ `class` — Reports what a game's global illumination costs against the frame period: the GI share of the GPU frame and whether the frame fits its period less 10% headroom. The method (`none`, `irradianceField`, `screenProbeGather`) holds its level while the game runs, as Unreal's Lumen does: a frame over its period gets cheaper through the primary resolution scale, and the GI pass follows the lower resolution. The budget is the frame period, never a GI time in milliseconds, because a stage reading moves with the GPU clock.
1470
+
1471
+ ```ts
1472
+ export class GIBudget { … }
1473
+ ```
1474
+
1475
+ - **Use when:** global illumination costs too much on a weak GPU · see what share of the GPU frame the bounce light takes · quality tier for indirect lighting that follows the hardware
1476
+ - **Constraints:** the method never changes while the game runs: the primary resolution scale is the run-time lever · the GPU time of a pass is read by the scene name three or the game gave it, so name every GI pass in `stages` · timestamp queries are needed: without them every window is unobserved
1477
+
1478
+ ```ts
1479
+ const gi = new GIBudget({ method: "screenProbeGather", stages: ["SSGI"], framePeriodMs: 1000 / 60 });
1480
+ ctx.beforeRender(() => gi.observeRenderer(ctx.renderer.raw));
1481
+ ```
1482
+
1483
+ ### `GIVisualize`
1484
+
1485
+ `class` — Shows the indirect diffuse light of a frame by itself, the counterpart of Unreal's Lumen `Visualize IndirectDiffuse` mode, so a lighting gap against a reference can be told apart from a scene gap. The game's chain builds the term; this class selects it and fails when the term is missing.
1486
+
1487
+ ```ts
1488
+ export class GIVisualize { … }
1489
+ ```
1490
+
1491
+ - **Use when:** see only the bounce light of a frame · compare indirect lighting alone against Unreal · debug global illumination by looking at the indirect diffuse term
1492
+ - **Constraints:** the game's render chain builds the indirectDiffuse node (gathered and cached light times albedo); this class draws nothing else · a mode whose term the chain did not build throws instead of showing the finished frame
1493
+ - **Overrides:** mode: "off" returns the finished frame unchanged
1494
+
1495
+ ```ts
1496
+ const view = new GIVisualize({ mode: "indirectDiffuse", beauty: frame, indirectDiffuse: albedo.mul(bounce) });
1497
+ pipeline.outputNode = view.node;
1498
+ ```
1499
+
1359
1500
  ### `GPUParticles3D`
1360
1501
 
1361
1502
  `class` — Dispatch a game-owned particle surface and process function through a pooled system.
@@ -1436,6 +1577,22 @@ const game = defineGame({ input: { move: { up: ["KeyW"], down: ["KeyS"], left: [
1436
1577
  // inside the scene, per frame: ctx.input.axis("move") is 0 at rest and 1 at full tilt
1437
1578
  ```
1438
1579
 
1580
+ ### `installFilmicToneMapping`
1581
+
1582
+ `function` — Unreal 5.8.3's tone curve, the default tone mapping of `createRenderer` and `Game`: a filmic curve in ACEScg (slope 0.88, toe 0.55, shoulder 0.26) after the gamut expansion and blue correction of Unreal's colour LUT. `installFilmicToneMapping` registers it as three's custom tone mapping.
1583
+
1584
+ ```ts
1585
+ export function installFilmicToneMapping( raw: unknown, c: IFilmicCurve = FILMIC_CURVE, grade: IColorGrade = COLOR_GRADE, ): number | undefined { … }
1586
+ ```
1587
+
1588
+ - **Use when:** the frame should tone map the way a fresh Unreal project does
1589
+ - **Constraints:** WebGPU renderers only: a renderer without a node library keeps ACES and reports `TN_TONEMAP`
1590
+ - **Overrides:** `createRenderer({ toneMapping: "aces" | "agx" | "neutral" | "none" })` or `game.renderer.toneMapping` in the game config; setting `renderer.raw.toneMapping` later wins
1591
+
1592
+ ```ts
1593
+ const renderer = await createRenderer({ toneMapping: "aces" }); // the named override
1594
+ ```
1595
+
1439
1596
  ### `installSpanProbes`
1440
1597
 
1441
1598
  `function` — Attach the span probes to a renderer: three's `render`, `_projectObject`, the render list's `sort`, the per-draw submission, and the scene-graph walk. Installed for you when `TN_FRAME_SPANS` asks; exported so a harness can wrap a renderer it owns.
@@ -1493,7 +1650,7 @@ export function isMobile(): boolean { … }
1493
1650
  ```
1494
1651
 
1495
1652
  - **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native
1496
- - **Constraints:** only use the returned platform facts; native globals are host-owned · 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
1653
+ - **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
1497
1654
 
1498
1655
  ```ts
1499
1656
  if (isMobile()) showTouchControls();
@@ -1508,7 +1665,7 @@ export function isNative(): boolean { … }
1508
1665
  ```
1509
1666
 
1510
1667
  - **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native
1511
- - **Constraints:** only use the returned platform facts; native globals are host-owned · 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
1668
+ - **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
1512
1669
 
1513
1670
  ```ts
1514
1671
  if (isMobile()) showTouchControls();
@@ -1538,7 +1695,7 @@ export function isTouchscreenAvailable(): boolean { … }
1538
1695
  ```
1539
1696
 
1540
1697
  - **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native
1541
- - **Constraints:** only use the returned platform facts; native globals are host-owned · 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
1698
+ - **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
1542
1699
 
1543
1700
  ```ts
1544
1701
  if (isMobile()) showTouchControls();
@@ -1553,12 +1710,43 @@ export function isWeb(): boolean { … }
1553
1710
  ```
1554
1711
 
1555
1712
  - **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native
1556
- - **Constraints:** only use the returned platform facts; native globals are host-owned · 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
1713
+ - **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
1557
1714
 
1558
1715
  ```ts
1559
1716
  if (isMobile()) showTouchControls();
1560
1717
  ```
1561
1718
 
1719
+ ### `lampPenumbraTangent`
1720
+
1721
+ `function` — A lamp's penumbra radius in tangent units at a receiver, from the lamp's source radius and the blocker and receiver distances.
1722
+
1723
+ ```ts
1724
+ export function lampPenumbraTangent( sourceRadius: number, blockerDistance: number, receiverDistance: number, ): number { … }
1725
+ ```
1726
+
1727
+ - **Use when:** measure a lamp shadow's penumbra width without a GPU
1728
+ - **Constraints:** sourceRadius is 0 or more; both distances are positive metres; the result is the geometric tangent, before penumbraScale
1729
+
1730
+ ```ts
1731
+ const tangent = lampPenumbraTangent(0.05, 2, 3);
1732
+ ```
1733
+
1734
+ ### `lampShadowMarker`
1735
+
1736
+ `function` — The `TN_LAMP_SHADOW` line for the renderer's last frame, or `undefined` on a renderer that keeps no lamp counters (three's own).
1737
+
1738
+ ```ts
1739
+ export function lampShadowMarker( renderer: { … }
1740
+ ```
1741
+
1742
+ - **Use when:** log lamp shadow redraws and GPU time apart from the sun's on the owned engine
1743
+ - **Constraints:** counters that do not add up to the frame's shadow draws throw TN_LAMP_SHADOW_INVALID
1744
+
1745
+ ```ts
1746
+ const line = lampShadowMarker(renderer, frame);
1747
+ if (line !== undefined) console.info(line);
1748
+ ```
1749
+
1562
1750
  ### `loadAll`
1563
1751
 
1564
1752
  `function` — Load a list with bounded concurrency, returning results in the input's order.
@@ -1734,6 +1922,21 @@ export class PathFollow3D { … }
1734
1922
  const follower = new PathFollow3D({ points: patrolPoints, loop: true, speed: 3 });
1735
1923
  ```
1736
1924
 
1925
+ ### `penumbraUv`
1926
+
1927
+ `function` — Convert world-space caster gap to a shadow UV radius, floored at one texel.
1928
+
1929
+ ```ts
1930
+ export function penumbraUv( gapMetres: number, sourceAngleRad: number, frustumWidthMetres: number, mapSize: number, ): number { … }
1931
+ ```
1932
+
1933
+ - **Use when:** measure a source-angle shadow's filter radius without a GPU
1934
+ - **Constraints:** inputs must be finite and non-negative; sizes must be positive and angle < PI/2 radians
1935
+
1936
+ ```ts
1937
+ const radius = penumbraUv(10, angle, 40, 2048);
1938
+ ```
1939
+
1737
1940
  ### `PipelineCensus`
1738
1941
 
1739
1942
  `class` — Read the renderer's bounded, versioned pipeline capture in a diagnostic or playtest tool.
@@ -1805,14 +2008,61 @@ prewarm(tracerPool);
1805
2008
  export class ProbeVolume extends Object3D implements IComputeDriven { … }
1806
2009
  ```
1807
2010
 
1808
- - **Use when:** light bouncing from a room I cannot see · light a wall with an off-screen emitter
1809
- - **Constraints:** request a bake after static geometry and lights are authored; this is static-lighting-first, not fully dynamic relighting · add the volume with ctx.add() so its incremental work is measured in the render phase · call sample() or sampleNode() from a game-owned material before screen-space GI; the volume owns no light, material, or colour
2011
+ - **Use when:** light bouncing from a room I cannot see · light a wall with an off-screen emitter · glass or fog inside a room takes the room's bounce light
2012
+ - **Constraints:** request a bake after static geometry and lights are authored; this is static-lighting-first, not fully dynamic relighting · add the volume with ctx.add() so its incremental work is measured in the render phase · call sample() or sampleNode() from a game-owned material before screen-space GI; the volume owns no light, material, or colour · a translucent material or a fog sample has no side that faces the light: it reads sampleNonDirectional(position), one atlas fetch, the same in every direction (divide by pi for a radiance)
1810
2013
  - **Overrides:** density, bounds, bakeBudgetMs, and bounces are game-owned choices
1811
2014
 
1812
2015
  ```ts
1813
2016
  const probes = new ProbeVolume({ bounds, density: 0.5 }); ctx.add(probes); void probes.requestBake(scene);
1814
2017
  ```
1815
2018
 
2019
+ ### `qualityPreset`
2020
+
2021
+ `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.
2022
+
2023
+ ```ts
2024
+ export function qualityPreset(tier: string): IWorldEnvironmentOptions { … }
2025
+ ```
2026
+
2027
+ - **Use when:** pick a start tier for the GPU class and read what that tier costs the look · build a `WorldEnvironment` for a weaker device from a named tier
2028
+ - **Constraints:** an unknown tier name throws with the names it expected
2029
+ - **Overrides:** pass any `IWorldEnvironmentOptions` field after `qualityPreset(tier)`, or an explicit `tier` to `qualityTiers.resolve`
2030
+
2031
+ ```ts
2032
+ const world = new WorldEnvironment({ ...qualityPreset(qualityTiers.resolve({ gpuClass: renderer.gpuClass })), bloomEnabled: false });
2033
+ ```
2034
+
2035
+ ### `readGIMarker`
2036
+
2037
+ `function` — Parse a `TN_GI` console line back into its report, or `undefined`.
2038
+
2039
+ ```ts
2040
+ export function readGIMarker(line: string): IGIBudgetReport | undefined { … }
2041
+ ```
2042
+
2043
+ - **Use when:** inspect which global illumination method ran and what the frame cost
2044
+ - **Constraints:** non-marker lines and malformed markers return `undefined`
2045
+
2046
+ ```ts
2047
+ const report = readGIMarker(line); if (report?.verdict === "over") console.log(report.reason);
2048
+ ```
2049
+
2050
+ ### `readLampShadowMarker`
2051
+
2052
+ `function` — Parse a `TN_LAMP_SHADOW` line back into its stats, or `undefined`.
2053
+
2054
+ ```ts
2055
+ export function readLampShadowMarker(line: string): ILampShadowStats | undefined { … }
2056
+ ```
2057
+
2058
+ - **Use when:** count lamp shadow redraws from a renderer log, for example a moving-caster run
2059
+ - **Constraints:** non-marker lines and markers whose sun and lamp draws do not add up return `undefined`
2060
+
2061
+ ```ts
2062
+ const stats = readLampShadowMarker(line);
2063
+ if (stats !== undefined) console.log(stats.lamps.redraws);
2064
+ ```
2065
+
1816
2066
  ### `readProbeVolumeObservation`
1817
2067
 
1818
2068
  `function` — Read the most recent observation from a probe volume.
@@ -1858,6 +2108,21 @@ export function readRenderChainReport(renderer: unknown): IRenderChainMarker | u
1858
2108
  const chain = new RenderChain(renderer, { input: colour, stages, request: { stages: ["bloom"], tier: "auto" } });
1859
2109
  ```
1860
2110
 
2111
+ ### `readShadowTierMarker`
2112
+
2113
+ `function` — Parse a `TN_SHADOW_TIER` console line back into its report, or `undefined`.
2114
+
2115
+ ```ts
2116
+ export function readShadowTierMarker(line: string): IShadowFilterReport | undefined { … }
2117
+ ```
2118
+
2119
+ - **Use when:** inspect which shadow filter tier ran and why it stepped
2120
+ - **Constraints:** non-marker lines and malformed markers return `undefined`
2121
+
2122
+ ```ts
2123
+ const report = readShadowTierMarker(line); if (report?.stepped) console.log(report.reason);
2124
+ ```
2125
+
1861
2126
  ### `readVelocityPreviousBoneMatrices`
1862
2127
 
1863
2128
  `function` — Provision screen-space motion data for temporal nodes and keep per-instance history at the frame boundary.
@@ -2169,10 +2434,10 @@ const picker = new ScenePicker({ camera: ctx.camera, scene: ctx.scene, pointer:
2169
2434
 
2170
2435
  ### `sceneWarning`
2171
2436
 
2172
- `function` — Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its JS render phase is longer than the display's own period is a scene-shape problem, and the engine already has the shape. On by default, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.
2437
+ `function` — Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its JS render phase is longer than the display's own period is a scene-shape problem, and the engine already has the shape. On by default in a debug launch, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.
2173
2438
 
2174
2439
  ```ts
2175
- export function sceneWarning( window: IFrameBudgetWindow, shape: ISceneShape | undefined, declaredTargetFps: number | undefined, ): ISceneWarning | undefined { … }
2440
+ export function sceneWarning( window: IFrameBudgetWindow, shape: ISceneShape | undefined, declaredTargetFps: number | undefined, gpuClass?: string, ): ISceneWarning | undefined { … }
2176
2441
  ```
2177
2442
 
2178
2443
  - **Use when:** find out whether a slow frame is the scene's shape or the device · tell an authoring agent what to reduce before it promises a merge
@@ -2229,17 +2494,34 @@ export function setSpanRecorder(next: SpanRecorder | undefined): void { … }
2229
2494
  if (spansRequested()) setSpanRecorder(new SpanRecorder());
2230
2495
  ```
2231
2496
 
2497
+ ### `ShadowFilterBudget`
2498
+
2499
+ `class` — Steps a game's soft-shadow tier down (`low`, `medium`, `high`) when the whole GPU frame stays over the frame period, and back up when the frame has room, by the settings of Unreal's virtual shadow map budget (a linear model, 5% headroom). A frame that is slow for another reason keeps its shadows: the tier steps only when the shadow passes could absorb the overage. The game owns the sample counts of each tier and rebuilds its filter on each step; the tiers follow Unreal's `sg.ShadowQuality` Low, Medium and Epic.
2500
+
2501
+ ```ts
2502
+ export class ShadowFilterBudget { … }
2503
+ ```
2504
+
2505
+ - **Use when:** soft shadow filter costs too much on a weak GPU · step the shadow quality tier when the GPU frame goes over the frame period · shadow quality tier that follows the hardware
2506
+ - **Constraints:** the game rebuilds its filter with the tier's sample counts on each step; this class draws nothing · timestamp queries are needed: without them every window is unobserved and the tier holds · the rule reads the whole GPU frame and the `Shadow` stage, which the receiver filter inside the colour pass is not part of
2507
+ - **Overrides:** explicit: true keeps the game's own sample counts and reports an over-budget frame
2508
+
2509
+ ```ts
2510
+ const filter = new ShadowFilterBudget({ tier: "high", framePeriodMs: 1000 / 60, onStep: (tier) => { light.shadow.filterNode = filterFor(tier); } });
2511
+ ctx.beforeRender(() => filter.observeRenderer(ctx.renderer.raw));
2512
+ ```
2513
+
2232
2514
  ### `SkeletalMesh3D`
2233
2515
 
2234
- `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.
2516
+ `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.
2235
2517
 
2236
2518
  ```ts
2237
2519
  export class SkeletalMesh3D extends AnimationPlayer { … }
2238
2520
  ```
2239
2521
 
2240
- - **Use when:** put an animated character in the scene · my imported character renders deformed · instance an imported rigged character · validate animation clips on a character rig at load time · prepare a skinned character with safe skeleton cloning and stride sync
2522
+ - **Use when:** put an animated character in the scene · my imported character renders deformed · instance an imported rigged character · validate animation clips on a character rig at load time · prepare a skinned character with safe skeleton cloning and stride sync · reduce animation CPU for a crowd of imported rigs · inspect an imported rig's effective animation evaluation rate
2241
2523
  - **Constraints:** use strideRoot to name the body moved by game code when the rig is parented under it · requiredClips fails closed at load time if any requested clip is missing or binds 0 tracks
2242
- - **Overrides:** strideSync controls whether locomotion playback rate matches ground covered · size normalises the instance to real-world metres with skin-aware measurement
2524
+ - **Overrides:** strideSync controls whether locomotion playback rate matches ground covered · size normalises the instance to real-world metres with skin-aware measurement · updateRate: "auto" chooses the camera-based interval; 1 is full evaluation, and another positive safe integer requests that interval; a public `mixer` `"loop"` listener promotes effective evaluation to 1 to preserve event timing
2243
2525
 
2244
2526
  ```ts
2245
2527
  import { SkeletalMesh3D } from "@threenative/core";
@@ -2266,6 +2548,36 @@ import { skeletonBones } from "@threenative/core";
2266
2548
  const bones = skeletonBones(character);
2267
2549
  ```
2268
2550
 
2551
+ ### `SkyCapture`
2552
+
2553
+ `class` — Capture game-owned sky radiance into a sun-triggered, frame-budgeted environment map.
2554
+
2555
+ ```ts
2556
+ export class SkyCapture { … }
2557
+ ```
2558
+
2559
+ - **Use when:** light a scene from a procedural sky when its sun moves
2560
+ - **Constraints:** use an initialized WebGPURenderer; the game supplies the sky and assigns the texture · call update once per frame on an initialized WebGPURenderer; assign texture after it returns true · sky nodes use a world-space view direction; keep supplied sky resources alive until dispose
2561
+
2562
+ ```ts
2563
+ const capture = new SkyCapture(renderer, skyNode); if (capture.update(sun)) scene.environment = capture.texture;
2564
+ ```
2565
+
2566
+ ### `SkyCaptureSchedule`
2567
+
2568
+ `class` — Capture game-owned sky radiance into a sun-triggered, frame-budgeted environment map.
2569
+
2570
+ ```ts
2571
+ export class SkyCaptureSchedule { … }
2572
+ ```
2573
+
2574
+ - **Use when:** light a scene from a procedural sky when its sun moves
2575
+ - **Constraints:** use an initialized WebGPURenderer; the game supplies the sky and assigns the texture
2576
+
2577
+ ```ts
2578
+ const capture = new SkyCapture(renderer, skyNode); if (capture.update(sun)) scene.environment = capture.texture;
2579
+ ```
2580
+
2269
2581
  ### `snapRefreshRate`
2270
2582
 
2271
2583
  `function` — Read what frame rate a game gets when its config does not say, and why. `display.maxFps` follows the display — capped at 120 on desktop and web, 60 on mobile — rather than the 60 every template used to ship, and an explicit number still wins with `0` still uncapping. The engine calls this itself; a game calls it when it needs the same number for its own frame-rate-dependent work, and `TN_FRAME_BUDGET` reports the resolved target and its source on every window.
@@ -2342,6 +2654,37 @@ export function solarPositionAt( date: Date | string, latitude: number, longitud
2342
2654
  const sun = solarPositionAt(new Date(), 49.28, -123.12);
2343
2655
  ```
2344
2656
 
2657
+ ### `sourceAngleShadowFilter`
2658
+
2659
+ `function` — Source-angle blocker search and variable-radius PCF on three's shadow map.
2660
+
2661
+ ```ts
2662
+ export function sourceAngleShadowFilter( { … }
2663
+ ```
2664
+
2665
+ - **Use when:** soften a directional shadow as the caster-receiver gap grows
2666
+ - **Constraints:** sourceAngleRad is required, in radians in [0, PI/2); orthographic depth shadows only, not VSM
2667
+
2668
+ ```ts
2669
+ sun.shadow.filterNode = sourceAngleShadowFilter({ sourceAngleRad: angle });
2670
+ ```
2671
+
2672
+ ### `sourceRadiusShadowFilter`
2673
+
2674
+ `function` — Source-radius blocker search and variable-radius PCF on a spot or point light's shadow map.
2675
+
2676
+ ```ts
2677
+ export function sourceRadiusShadowFilter( { … }
2678
+ ```
2679
+
2680
+ - **Use when:** soften a lamp's shadow by the lamp's size, as Unreal's SourceRadius does
2681
+ - **Constraints:** sourceRadius is required, in metres, 0 or more (0 is one hard tap); penumbraScale, the share of the geometric penumbra kept, is in (0, 4] and defaults to 0.6, the width Unreal's lamp ray test resolves; forward-depth maps only
2682
+ - **Overrides:** penumbraScale: 1 gives the geometric penumbra of a disk lamp
2683
+
2684
+ ```ts
2685
+ lamp.shadow.filterNode = sourceRadiusShadowFilter({ sourceRadius: 0.05 });
2686
+ ```
2687
+
2345
2688
  ### `spanNow`
2346
2689
 
2347
2690
  `function` — Attribute the render phase to 100% with a nested span tree, off unless `TN_FRAME_SPANS` asks. Every non-leaf reports its own time minus the spans inside it, so an unmeasured part shows up as a residual instead of being filed under "other"; a child that outlives its parent reports a negative residual rather than a clamped zero.
@@ -2432,6 +2775,21 @@ export class SpriteAnimator3D { … }
2432
2775
  const animator = new SpriteAnimator3D({ texture: atlas, frames, mode: "pingPong" });
2433
2776
  ```
2434
2777
 
2778
+ ### `stageGpuReading`
2779
+
2780
+ `function` — Read the GPU milliseconds of each named render pass of the newest resolved frame, such as `SSGI` or `AO`, with the whole frame's total.
2781
+
2782
+ ```ts
2783
+ export function stageGpuReading(renderer: unknown): IStageGpuReading | undefined { … }
2784
+ ```
2785
+
2786
+ - **Use when:** read the GPU cost of one post-processing stage · tell which render pass takes the GPU time
2787
+ - **Constraints:** absent before a whole frame resolves and on an adapter without timestamp queries; the frame number counts each reading once
2788
+
2789
+ ```ts
2790
+ const reading = stageGpuReading(renderer); const ssgiMs = reading?.stages.SSGI;
2791
+ ```
2792
+
2435
2793
  ### `staticTransformCensus`
2436
2794
 
2437
2795
  `function` — Stop recomposing the transforms of a subtree nobody moves. `markStatic(root)` composes the subtree once and freezes it; the engine re-arms a root whose own transform the game changes, and `invalidateStatic(object)` announces a write deeper inside one.
@@ -2447,6 +2805,54 @@ export function staticTransformCensus(): IStaticTransformCensus { … }
2447
2805
  invalidateStatic(drawbridge);
2448
2806
  ```
2449
2807
 
2808
+ ### `SurfaceCache`
2809
+
2810
+ `class` — The Surface Cache: what a traced global-illumination ray reads where it hits a surface. A material atlas (base colour and emissive maps reduced to small tiles) answers the albedo and the glow at the hit UV; a flat material keeps its colour. `SurfaceLights` adds the scene's point and spot lamps at the hit, the brightest eight.
2811
+
2812
+ ```ts
2813
+ export class SurfaceCache { … }
2814
+ ```
2815
+
2816
+ - **Use when:** give a traced bounce ray the texture colour and glow of the surface it hits
2817
+ - **Constraints:** the materials are fixed when the cache is built; build a new one when a material or a map changes · a map whose image the runtime does not show to JavaScript (the owned engine's glTF maps) returns the flat colour and is listed in `report.fallbacks`; the `images` option hands over its pixels · the cache owns no colour, texture or light; the game's materials and lamps are the only source
2818
+ - **Overrides:** atlasSize and cardTexelDensityScale size the atlas; images supplies the pixels of a map the runtime hides
2819
+
2820
+ ```ts
2821
+ const cache = SurfaceCache.from(materials); cache.albedo(slot, hit.uv.x, hit.uv.y, out);
2822
+ ```
2823
+
2824
+ ### `SurfaceLights`
2825
+
2826
+ `class` — The local lamps at the hit of a traced ray: the point and spot lights whose range reaches it, the brightest eight, one shadow ray each. The Surface Cache gives the hit its colour; this gives it the lamps.
2827
+
2828
+ ```ts
2829
+ export class SurfaceLights { … }
2830
+ ```
2831
+
2832
+ - **Use when:** light the hit of a traced ray with the scene's point and spot lamps
2833
+ - **Constraints:** the cap skips the ninth-brightest lamp and every one after it, and counts them in `skipped` · the caller answers each shadow ray; the class owns no scene
2834
+ - **Overrides:** maxLights caps the lamps evaluated at one hit
2835
+
2836
+ ```ts
2837
+ const lamps = new SurfaceLights(lights); lamps.shade(point, normal, albedo, out, (i) => !occluded(i));
2838
+ ```
2839
+
2840
+ ### `TracedReflections`
2841
+
2842
+ `class` — Reflection rays against the scene's triangles, in TSL. For a smooth surface, a ray finds what the screen cannot show (a room behind the camera, the far side of an object) and returns the hit's position, normal and material. The game lights the hit in its own stage. The kernel is plain TSL: float textures and a loop, no storage buffer.
2843
+
2844
+ ```ts
2845
+ export class TracedReflections { … }
2846
+ ```
2847
+
2848
+ - **Use when:** reflect what is behind the camera in a mirror or a chrome sphere · make a glossy or wet floor reflect objects that are off screen · trace a shadow ray from a reflected surface toward the sun · split a surface's specular by roughness into traced, radiance-cache and diffuse-GI shares
2849
+ - **Constraints:** the pack is a snapshot of the static triangles taken when the object is built: build a new one after geometry moves · instanced, skinned, batched and morphing meshes are not in the pack; report.skippedMoving counts them · trace only pixels at or below maxRoughnessToTrace (0.4, Unreal's cut-off): each ray walks the tree · a ray visits at most maxSteps tree nodes, then reports a miss; hit light, the miss colour and the blend with the frame stay in the game's src/render/ · the pack needs a device with float32-filterable
2850
+ - **Overrides:** maxRoughnessToTrace, roughnessFadeLength, maxRoughnessToEvaluateRoughSpecular, roughSpecularFadeLength and maxSteps are game-owned choices
2851
+
2852
+ ```ts
2853
+ const traced = new TracedReflections(ctx.scene); const hit = traced.trace({ origin, direction, far: 30 }); // light hit.albedo at hit.position in the stage
2854
+ ```
2855
+
2450
2856
  ### `TracerPool3D`
2451
2857
 
2452
2858
  `class` — Pool travelling bullet-streak meshes for hitscan shots.
@@ -2541,6 +2947,22 @@ const hull = await ctx.assets.model("hull.glb");
2541
2947
  ctx.scene.add(hull.scene);
2542
2948
  ```
2543
2949
 
2950
+ ### `useRoughDiffuse`
2951
+
2952
+ `function` — Unreal's Substrate rough diffuse (EON) on standard and physical materials, so direct sun and lamp light meets a rough surface the way Unreal shades it. The same `roughDiffuse` flag works on three's WebGPU renderer and on the owned engine.
2953
+
2954
+ ```ts
2955
+ export function useRoughDiffuse(root: Object3D, enabled = true): number { … }
2956
+ ```
2957
+
2958
+ - **Use when:** shade rough surfaces under a sun or a lamp the way Unreal's Substrate does, not as flat Lambert
2959
+ - **Constraints:** direct light only, indirect light stays Lambert; standard and physical materials; a lamp's `sourceRadius` in metres fades the effect to Lambert at 20 cm; a material changed after its first draw needs `needsUpdate`
2960
+ - **Overrides:** material.roughDiffuse = false, or useRoughDiffuse(root, false), puts Lambert back
2961
+
2962
+ ```ts
2963
+ useRoughDiffuse(scene);
2964
+ ```
2965
+
2544
2966
  ### `validateWorldMatrices`
2545
2967
 
2546
2968
  `function` — Prove that nothing a cache skipped changed the picture: `TN_RENDERLIST_VALIDATE=1` recomputes every world matrix the long way, every frame, and throws on the first element that disagrees with what the frame is about to draw.
@@ -2608,7 +3030,7 @@ export class VirtualShadowNode extends ShadowBaseNode { … }
2608
3030
 
2609
3031
  - **Use when:** crisp shadows close to the player across a large outdoor level · shadow map too coarse over a big terrain · one directional light shadow for a whole open world · shadows shimmer when the camera moves
2610
3032
  - **Constraints:** the light must be a DirectionalLight with `castShadow` and a target in the scene · clipExtents are half-widths in world units, finest first, strictly increasing · movers sort themselves: a layer-0 caster whose world matrix, instance matrix or deformation changed draws through the mover maps and leaves the cached levels, and returns to them after `staticAfterFrames` quiet frames; the cache redraws only the region it left · `trackCaster(object)` is the override that pins an object as a mover for good (it enables layer `VIRTUAL_SHADOW_MOVER_LAYER` on the object and its descendants), and `pinStatic(object)` opts an object out of detection; tracking or untracking refreshes only that object's region · call `object.layers.set(VIRTUAL_SHADOW_CASTER_LAYER)` for a mesh that exists only to cast; the level cameras already render that layer and the main camera never does
2611
- - **Overrides:** bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults, and `marker: false` silences the TN_VIRTUAL_SHADOW line, not the measurement · bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults · followViewFocus: false keeps eye follow; receiverPlaneBias: false uses only authored bias
3033
+ - **Overrides:** bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults, and `marker: false` silences the TN_VIRTUAL_SHADOW line, not the measurement · bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults · followViewFocus: false keeps eye follow; receiverPlaneBias: false uses only authored bias · minWindowAspect: below 1, a level is as high as `sin(sun elevation)` times its width, never under this, so a low sun's floor shadows keep the texel density of a high sun's; the default 1 keeps square levels
2612
3034
 
2613
3035
  ```ts
2614
3036
  const sun = new DirectionalLight(0xffffff, 3);
@@ -2685,6 +3107,22 @@ renderer.render(scene, camera);
2685
3107
  tracker.commit(scene);
2686
3108
  ```
2687
3109
 
3110
+ ### `WorldEnvironment`
3111
+
3112
+ `class` — The node that says which lighting effects a scene runs and how strong they are, with a fresh Unreal 5.8.3 project's defaults: the filmic tone curve, Unreal-metered auto exposure, screen-space GI and ambient occlusion, SMAA, Unreal's bloom and local exposure. It builds the post chain through `renderer.createRenderChain()` and prints `TN_RENDER_CHAIN` naming every stage as applied or refused with a reason. Property names are Godot's `Environment` where it has one.
3113
+
3114
+ ```ts
3115
+ export class WorldEnvironment { … }
3116
+ ```
3117
+
3118
+ - **Use when:** a scene should light and tone map like a fresh Unreal level without wiring each post stage by hand · turn one lighting effect off, or pick a cheaper tier, for a weak GPU or a stylised look
3119
+ - **Constraints:** post stages run on WebGPU only: a renderer without it keeps the fixed exposure and reports `TN_AUTO_EXPOSURE_REFUSED`, and a missing node library keeps ACES and reports `TN_TONEMAP` · an unknown option value throws instead of becoming the default
3120
+ - **Overrides:** every option on `IWorldEnvironmentOptions`: `tonemapMode: "aces" | "agx" | "neutral"`, `autoExposureEnabled: false` with a fixed `exposure`, `bloomEnabled`, `gtaoEnabled`, `ssgiEnabled`, `screenSpaceAA`
3121
+
3122
+ ```ts
3123
+ const world = new WorldEnvironment({ tonemapMode: "aces", autoExposureEnabled: false, exposure: 0.8 }); world.apply(renderer, scene, view);
3124
+ ```
3125
+
2688
3126
  ### `zenithTransmittance`
2689
3127
 
2690
3128
  `function` — Return direct vertical transmittance for the supplied atmosphere.
@@ -2964,6 +3402,36 @@ export function subscribeUiState<T>(bridge: IUiBridge): IUiStateMirror<T> { …
2964
3402
  const mirror = subscribeUiState(bridge);
2965
3403
  ```
2966
3404
 
3405
+ ## `@threenative/core/worker`
3406
+
3407
+ ### `serveWorkerGame`
3408
+
3409
+ `function` — Runs inside the worker: wire the page's messages to the unchanged portable game. Call it last in the worker entry, after the game module evaluated: it posts the ready message the page waits for before it sends the canvas.
3410
+
3411
+ ```ts
3412
+ export function serveWorkerGame( game: { … }
3413
+ ```
3414
+
3415
+ - **Use when:** run the game loop in a web worker so a busy page cannot stall its frames
3416
+
3417
+ ```ts
3418
+ serveWorkerGame(game);
3419
+ ```
3420
+
3421
+ ### `startWorkerGame`
3422
+
3423
+ `function` — Runs on the page: own the canvas and the DOM, and feed the worker game. Call it before the UI mounts: the HUD's bridge host globals exist from this call on.
3424
+
3425
+ ```ts
3426
+ export function startWorkerGame( worker: Worker, container: HTMLElement, ): { … }
3427
+ ```
3428
+
3429
+ - **Use when:** host a worker-run game's canvas, input and HUD on the page
3430
+
3431
+ ```ts
3432
+ const handle = startWorkerGame(new Worker(new URL("./worker.ts", import.meta.url), { type: "module" }), root);
3433
+ ```
3434
+
2967
3435
  ## `@threenative/core/world`
2968
3436
 
2969
3437
  ### `cellPlacements`
@@ -3155,7 +3623,7 @@ export class WorldCells extends Group implements IComputeDriven { … }
3155
3623
  ```
3156
3624
 
3157
3625
  - **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
3158
- - **Constraints:** surface is the game's; this class creates no material, colour or geometry · budgets are hard caps that report pressure instead of over-committing · 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 · 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
3626
+ - **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 · 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 · 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
3159
3627
  - **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
3160
3628
 
3161
3629
  ```ts
@@ -3426,8 +3894,9 @@ export class PhysicsDirectSpaceState3D { … }
3426
3894
  ```
3427
3895
 
3428
3896
  - **Use when:** raycast for visibility or aiming · find bodies inside a shape or point query
3429
- - **Constraints:** query results are bounded by the configured result limit
3897
+ - **Constraints:** query results are bounded by the configured result limit · intersectRay ignores a solid that contains the ray origin and returns the next real hit or none, like Godot hit_from_inside false
3430
3898
  - **Requires:** npm i @threenative/physics
3899
+ - **Overrides:** hitFromInside: true returns the solid around the ray origin as a distance 0 hit with a zero normal
3431
3900
 
3432
3901
  ```ts
3433
3902
  const space = new PhysicsDirectSpaceState3D(context);
@@ -4049,7 +4518,7 @@ const adb = discoverAdb(process.env);
4049
4518
  `function` — Execute scenario steps, assertions, and evidence capture.
4050
4519
 
4051
4520
  ```ts
4052
- export async function advanceFixedStep( page: Page, bridge: Pick<IPlaytestBridgeClient, "advance">, ticks: number, render = false, ): Promise<void> { … }
4521
+ export async function advanceFixedStep( page: Page, bridge: { … }
4053
4522
  ```
4054
4523
 
4055
4524
  - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
@@ -5026,6 +5495,21 @@ const config = parseStandalonePlaytestArgs(["--scenario", "playtests/smoke.playt
5026
5495
  await withBrowserCapture(config, async (session) => session.screenshot("ready"));
5027
5496
  ```
5028
5497
 
5498
+ ### `withScenarioClock`
5499
+
5500
+ `function` — Parse standalone playtest runner configuration.
5501
+
5502
+ ```ts
5503
+ export function withScenarioClock<T extends { … }
5504
+ ```
5505
+
5506
+ - **Use when:** invoke the playtest CLI from a scaffold · validate runner flags before launching a browser
5507
+ - **Constraints:** invalid flags throw a named usage error
5508
+
5509
+ ```ts
5510
+ const config = parseStandalonePlaytestArgs(argv);
5511
+ ```
5512
+
5029
5513
  ### `writeCaptureProvenance`
5030
5514
 
5031
5515
  `function` — Execute scenario steps, assertions, and evidence capture.
@@ -6600,13 +7084,29 @@ export function useUiState<TState extends object>(): TState | undefined;
6600
7084
  ```
6601
7085
 
6602
7086
  - **Use when:** bind a HUD to game state on web and native alike · show score or health in a UI rendered over the game surface
6603
- - **Constraints:** returns undefined until the game publishes its first state
7087
+ - **Constraints:** returns undefined until the game publishes its first state and while the loading cover is up
6604
7088
  - **Requires:** npm i @threenative/ui
6605
7089
 
6606
7090
  ```ts
6607
7091
  const score = useUiState<GameState, number>((state) => state.score);
6608
7092
  ```
6609
7093
 
7094
+ ### `useUiStateDuringStartup`
7095
+
7096
+ `function` — Read the game's published state while the loading cover is still up, for a UI that draws its own loading screen.
7097
+
7098
+ ```ts
7099
+ export function useUiStateDuringStartup<TState extends object>(options: { … }
7100
+ ```
7101
+
7102
+ - **Use when:** draw a staged loading overlay from the startup progress the game publishes
7103
+ - **Constraints:** needs a non-empty reason, reported once as TN_UI_STARTUP_OVERRIDE; every other HUD uses useUiState
7104
+ - **Requires:** npm i @threenative/ui
7105
+
7106
+ ```ts
7107
+ const loading = useUiStateDuringStartup<GameState, number>({ reason: "staged loading overlay" }, (state) => state.loading.progress);
7108
+ ```
7109
+
6610
7110
  ## `src/audio/storm.ts`
6611
7111
 
6612
7112
  ### `createStormAudio`
@@ -6742,23 +7242,6 @@ createWeatherWorld(scene: Scene, camera: PerspectiveCamera): IWeatherWorld
6742
7242
  src/render/world.ts — edit the shader there, or the weather it is fed from src/state.ts
6743
7243
  ```
6744
7244
 
6745
- ## `src/render/worldEnvironment.ts`
6746
-
6747
- ### `WorldEnvironment`
6748
-
6749
- `class` — The generated file that composes every lighting stage and prints TN_RENDER_CHAIN naming each one as applied or refused with a reason. It is the game's source, not the framework's — edit it.
6750
-
6751
- ```ts
6752
- class WorldEnvironment
6753
- ```
6754
-
6755
- - **Use when:** turn a lighting or post-processing effect on or off · find out why an effect you enabled is not visible · change how the scene is lit, graded, or tonemapped · match a reference image's lighting
6756
- - **Constraints:** Read the TN_RENDER_CHAIN line before assuming a stage ran: it names every stage as applied or dropped, with the reason it was dropped. · A stage reported `applied` can still be invisible if its own inputs are wrong — the chain reports whether it built, not whether you can see it. · Appearance belongs here, in generated game source. Nothing in packages/ decides how the scene looks.
6757
-
6758
- ```ts
6759
- src/render/postprocessing.ts — edit the preset it passes to WorldEnvironment
6760
- ```
6761
-
6762
7245
  ## `three/addons/tsl/display/BloomNode.js`
6763
7246
 
6764
7247
  ### `bloom`