create-threenative 0.2.5 → 0.2.7

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 (631) hide show
  1. package/README.md +25 -3
  2. package/agent-docs/references/assertion-reference.md +40 -1
  3. package/agent-docs/references/build-profiles.md +126 -0
  4. package/agent-docs/references/capability-reference.md +1382 -65
  5. package/agent-docs/references/finding-assets.md +8 -1
  6. package/agent-docs/references/performance-basics.md +117 -0
  7. package/agent-docs/references/rigging-characters.md +51 -0
  8. package/agent-docs/references/sculpt-from-a-reference.md +1 -1
  9. package/agent-docs/references/trace-a-slow-frame.md +1 -1
  10. package/agent-docs/references/visual-baseline.md +8 -4
  11. package/agent-docs/references/webview-ui.md +3 -2
  12. package/agent-files/.agents/skills/file-engine-bug/SKILL.md +15 -4
  13. package/agent-files/.agents/skills/ponytail/SKILL.md +68 -0
  14. package/agent-files/.agents/skills/threenative-assets/SKILL.md +12 -4
  15. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +1 -1
  16. package/agent-files/.agents/skills/threenative-context/SKILL.md +9 -1
  17. package/agent-files/.agents/skills/threenative-performance/SKILL.md +26 -10
  18. package/agent-files/.agents/skills/threenative-playtest/SKILL.md +1 -1
  19. package/agent-files/.agents/skills/threenative-ui/SKILL.md +1 -1
  20. package/agent-files/.agents/skills/threenative-visuals/SKILL.md +4 -4
  21. package/agent-files/.claude/hooks/ponytail-context.mjs +51 -0
  22. package/agent-files/.claude/settings.json +38 -0
  23. package/agent-files/.codex/hooks.json +40 -0
  24. package/capabilities.json +1891 -101
  25. package/dist/index.d.ts +39 -1
  26. package/dist/index.js +480 -56
  27. package/dist/threenative.js +1247 -177
  28. package/package.json +6 -6
  29. package/template-assets/assets/mannequin-combat.glb +0 -0
  30. package/template-assets/assets/mannequin.glb +0 -0
  31. package/template-assets/assets/player-viewmodel.glb +0 -0
  32. package/template-assets/assets/sky.jpg +0 -0
  33. package/template-assets/clearwater/README.md +141 -0
  34. package/template-assets/clearwater/install.mjs +50 -0
  35. package/template-assets/clearwater/src/clearwater.ts +180 -0
  36. package/template-assets/clearwater/src/clearwaterDemo.ts +28 -0
  37. package/template-assets/clearwater/src/clearwaterLifetime.ts +28 -0
  38. package/{LICENSE → template-assets/clearwater/src/render/CLEARWATER-LICENSE.txt} +4 -1
  39. package/template-assets/clearwater/src/render/clearwater.ts +278 -0
  40. package/template-assets/clearwater/src/render/clearwaterCaustics.ts +138 -0
  41. package/template-assets/clearwater/src/render/clearwaterDemo.ts +65 -0
  42. package/template-assets/clearwater/src/render/clearwaterOptics.ts +33 -0
  43. package/template-assets/clearwater/src/render/clearwaterOptions.ts +177 -0
  44. package/template-assets/clearwater/src/render/clearwaterPass.ts +51 -0
  45. package/template-assets/patches/three@0.185.1.patch +2228 -105
  46. package/template-assets/worldEnvironment.ts +52 -1
  47. package/templates/action-rpg/AGENTS.md +43 -43
  48. package/templates/action-rpg/CLAUDE.md +43 -43
  49. package/templates/action-rpg/kit.json +1 -1
  50. package/templates/action-rpg/package.json +14 -8
  51. package/templates/action-rpg/playtests/combat.playtest.json +162 -23
  52. package/templates/action-rpg/playtests/performance.playtest.json +4 -3
  53. package/templates/action-rpg/playtests/survives.playtest.json +25 -8
  54. package/templates/action-rpg/src/conventions.ts +24 -18
  55. package/templates/action-rpg/src/entities/Enemy.ts +74 -24
  56. package/templates/action-rpg/src/entities/Fighter.ts +127 -0
  57. package/templates/action-rpg/src/entities/Player.ts +102 -32
  58. package/templates/action-rpg/src/game.ts +3 -3
  59. package/templates/action-rpg/src/render/camera.ts +18 -16
  60. package/templates/action-rpg/src/render/dungeon.ts +192 -0
  61. package/templates/action-rpg/src/render/lighting.ts +45 -28
  62. package/templates/action-rpg/src/render/loading.ts +4 -4
  63. package/templates/action-rpg/src/render/materials.ts +191 -47
  64. package/templates/action-rpg/src/render/palette.ts +14 -13
  65. package/templates/action-rpg/src/render/postprocessing.ts +12 -2
  66. package/templates/action-rpg/src/render/props.ts +117 -0
  67. package/templates/action-rpg/src/render/quality.ts +40 -82
  68. package/templates/action-rpg/src/render/sky.ts +36 -13
  69. package/templates/action-rpg/src/render/touch-controls.ts +1 -1
  70. package/templates/action-rpg/src/render/worldEnvironment.ts +52 -1
  71. package/templates/action-rpg/src/scenes/Play.ts +61 -39
  72. package/templates/action-rpg/src/style.css +9 -7
  73. package/templates/action-rpg/src/ui/AbilityBar.tsx +3 -1
  74. package/templates/action-rpg/src/ui/Hud.tsx +3 -3
  75. package/templates/action-rpg/threenative.config.ts +14 -1
  76. package/templates/action-rpg/vite.config.ts +4 -1
  77. package/templates/minimal/AGENTS.md +12 -12
  78. package/templates/minimal/CLAUDE.md +12 -12
  79. package/templates/minimal/package.json +13 -7
  80. package/templates/minimal/playtests/play.playtest.json +6 -5
  81. package/templates/minimal/playtests/sky.playtest.json +27 -0
  82. package/templates/minimal/src/conventions.ts +6 -3
  83. package/templates/minimal/src/entities/Player.ts +73 -27
  84. package/templates/minimal/src/main.ts +2 -3
  85. package/templates/minimal/src/render/camera.ts +22 -4
  86. package/templates/minimal/src/render/lighting.ts +24 -48
  87. package/templates/minimal/src/render/materials.ts +158 -13
  88. package/templates/minimal/src/render/palette.ts +10 -7
  89. package/templates/minimal/src/render/postprocessing.ts +12 -25
  90. package/templates/minimal/src/render/quality.ts +35 -69
  91. package/templates/minimal/src/render/sky.ts +35 -54
  92. package/templates/minimal/src/render/touch-controls.ts +1 -1
  93. package/templates/minimal/src/render/worldEnvironment.ts +52 -1
  94. package/templates/minimal/src/scenes/Play.ts +121 -111
  95. package/templates/minimal/src/state.ts +0 -4
  96. package/templates/minimal/src/style.css +0 -10
  97. package/templates/minimal/threenative.config.ts +15 -1
  98. package/templates/minimal/vite.config.ts +4 -1
  99. package/templates/platformer/AGENTS.md +18 -56
  100. package/templates/platformer/CLAUDE.md +18 -56
  101. package/templates/platformer/kit.json +2 -2
  102. package/templates/platformer/package.json +14 -10
  103. package/templates/platformer/playtests/buffer.playtest.json +15 -5
  104. package/templates/platformer/playtests/collect.playtest.json +8 -34
  105. package/templates/platformer/playtests/coyote.playtest.json +12 -34
  106. package/templates/platformer/playtests/damage.playtest.json +40 -15
  107. package/templates/platformer/playtests/hud.playtest.json +34 -0
  108. package/templates/platformer/playtests/move.playtest.json +24 -0
  109. package/templates/platformer/playtests/performance.playtest.json +24 -7
  110. package/templates/platformer/playtests/respawn.playtest.json +46 -11
  111. package/templates/platformer/playtests/stomp.playtest.json +49 -12
  112. package/templates/platformer/playtests/survives.playtest.json +3 -19
  113. package/templates/platformer/playtests/world.playtest.json +26 -0
  114. package/templates/platformer/src/entities/Fox.ts +273 -0
  115. package/templates/platformer/src/entities/Pickup.ts +43 -60
  116. package/templates/platformer/src/entities/Walker.ts +88 -0
  117. package/templates/platformer/src/game.ts +11 -8
  118. package/templates/platformer/src/level/Checkpoints.ts +29 -16
  119. package/templates/platformer/src/level/Stage.ts +469 -0
  120. package/templates/platformer/src/render/blocks.ts +94 -0
  121. package/templates/platformer/src/render/camera.ts +28 -3
  122. package/templates/platformer/src/render/fox.ts +196 -0
  123. package/templates/platformer/src/render/lighting.ts +42 -33
  124. package/templates/platformer/src/render/materials.ts +115 -5
  125. package/templates/platformer/src/render/palette.ts +68 -53
  126. package/templates/platformer/src/render/pickups.ts +142 -0
  127. package/templates/platformer/src/render/postprocessing.ts +12 -2
  128. package/templates/platformer/src/render/props.ts +147 -0
  129. package/templates/platformer/src/render/quality.ts +47 -99
  130. package/templates/platformer/src/render/scenery.ts +172 -0
  131. package/templates/platformer/src/render/sky.ts +120 -31
  132. package/templates/platformer/src/render/touch-controls.ts +5 -2
  133. package/templates/platformer/src/render/walkers.ts +96 -0
  134. package/templates/platformer/src/render/waterfall.ts +85 -0
  135. package/templates/platformer/src/render/worldEnvironment.ts +52 -1
  136. package/templates/platformer/src/scenes/Boot.ts +3 -4
  137. package/templates/platformer/src/scenes/Play.ts +362 -0
  138. package/templates/platformer/src/state.ts +16 -14
  139. package/templates/platformer/src/style.css +9 -8
  140. package/templates/platformer/src/ui/Hud.tsx +62 -29
  141. package/templates/platformer/src/ui/Menu.tsx +2 -2
  142. package/templates/platformer/threenative.config.ts +14 -1
  143. package/templates/platformer/vite.config.ts +4 -1
  144. package/templates/puzzle/AGENTS.md +21 -22
  145. package/templates/puzzle/CLAUDE.md +21 -22
  146. package/templates/puzzle/assets/native-proof.glb +0 -0
  147. package/templates/puzzle/assets/native-proof.png +0 -0
  148. package/templates/puzzle/kit.json +1 -1
  149. package/templates/puzzle/package.json +14 -8
  150. package/templates/puzzle/playtests/axis.playtest.json +20 -0
  151. package/templates/puzzle/playtests/blocked.playtest.json +73 -0
  152. package/templates/puzzle/playtests/caused.playtest.json +65 -0
  153. package/templates/puzzle/playtests/lit.playtest.json +74 -0
  154. package/templates/puzzle/playtests/performance.playtest.json +24 -7
  155. package/templates/{starter/playtests/respawn.playtest.json → puzzle/playtests/push.playtest.json} +24 -19
  156. package/templates/puzzle/playtests/replay.playtest.json +81 -0
  157. package/templates/puzzle/playtests/restart.playtest.json +108 -0
  158. package/templates/puzzle/playtests/seal.playtest.json +98 -0
  159. package/templates/puzzle/playtests/settle.playtest.json +100 -0
  160. package/templates/puzzle/playtests/survives.playtest.json +6 -29
  161. package/templates/{starter/playtests/hot-reload.playtest.json → puzzle/playtests/travel.playtest.json} +6 -5
  162. package/templates/puzzle/src/entities/Crate.ts +99 -42
  163. package/templates/puzzle/src/entities/Seal.ts +69 -0
  164. package/templates/puzzle/src/entities/Warden.ts +135 -0
  165. package/templates/puzzle/src/game.ts +15 -11
  166. package/templates/puzzle/src/render/camera.ts +66 -31
  167. package/templates/puzzle/src/render/crateShape.ts +70 -0
  168. package/templates/puzzle/src/render/lighting.ts +41 -41
  169. package/templates/puzzle/src/render/loading.ts +4 -4
  170. package/templates/puzzle/src/render/materials.ts +131 -27
  171. package/templates/puzzle/src/render/palette.ts +19 -29
  172. package/templates/puzzle/src/render/postprocessing.ts +15 -3
  173. package/templates/puzzle/src/render/quality.ts +71 -80
  174. package/templates/puzzle/src/render/shapes.ts +109 -108
  175. package/templates/puzzle/src/render/sky.ts +18 -10
  176. package/templates/puzzle/src/render/touch-controls.ts +8 -51
  177. package/templates/puzzle/src/render/vault.ts +315 -0
  178. package/templates/puzzle/src/render/warden.ts +46 -0
  179. package/templates/puzzle/src/render/worldEnvironment.ts +52 -1
  180. package/templates/puzzle/src/scenes/Play.ts +793 -0
  181. package/templates/puzzle/src/state.ts +55 -24
  182. package/templates/puzzle/src/style.css +7 -8
  183. package/templates/puzzle/src/ui/App.tsx +2 -2
  184. package/templates/puzzle/src/ui/Hud.tsx +92 -40
  185. package/templates/puzzle/src/ui/Menu.tsx +40 -2
  186. package/templates/puzzle/threenative.config.ts +14 -1
  187. package/templates/puzzle/vite.config.ts +4 -1
  188. package/templates/racing/AGENTS.md +20 -21
  189. package/templates/racing/CLAUDE.md +20 -21
  190. package/templates/racing/package.json +14 -8
  191. package/templates/racing/playtests/boost.playtest.json +33 -12
  192. package/templates/racing/playtests/outcome.playtest.json +32 -50
  193. package/templates/racing/playtests/performance.playtest.json +2 -1
  194. package/templates/racing/playtests/ranking.playtest.json +5 -14
  195. package/templates/racing/playtests/rescue.playtest.json +2 -2
  196. package/templates/racing/playtests/reverse.playtest.json +30 -8
  197. package/templates/racing/playtests/shortcut.playtest.json +54 -9
  198. package/templates/racing/playtests/touch-controls.playtest.json +32 -5
  199. package/templates/racing/src/entities/CarBody.ts +327 -0
  200. package/templates/racing/src/entities/LineDriver.ts +220 -0
  201. package/templates/racing/src/entities/RacingCar.ts +150 -89
  202. package/templates/racing/src/entities/Rival.ts +61 -24
  203. package/templates/racing/src/game.ts +5 -0
  204. package/templates/racing/src/render/camera.ts +49 -7
  205. package/templates/racing/src/render/lighting.ts +36 -37
  206. package/templates/racing/src/render/materials.ts +239 -19
  207. package/templates/racing/src/render/palette.ts +19 -21
  208. package/templates/racing/src/render/postprocessing.ts +12 -2
  209. package/templates/racing/src/render/quality.ts +43 -82
  210. package/templates/racing/src/render/shapes.ts +20 -6
  211. package/templates/racing/src/render/sky.ts +47 -39
  212. package/templates/racing/src/render/touch-controls.ts +1 -1
  213. package/templates/racing/src/render/worldEnvironment.ts +52 -1
  214. package/templates/racing/src/scenes/Race.ts +107 -54
  215. package/templates/racing/src/state.ts +2 -0
  216. package/templates/racing/src/track/Checkline.ts +22 -7
  217. package/templates/racing/src/track/Lap.ts +64 -36
  218. package/templates/racing/src/track/Ranking.ts +20 -11
  219. package/templates/racing/src/track/Track.ts +809 -361
  220. package/templates/racing/src/track/TrackSector.ts +40 -11
  221. package/templates/racing/src/track/circuit.ts +477 -0
  222. package/templates/racing/src/track/rescue.ts +16 -4
  223. package/templates/racing/threenative.config.ts +14 -1
  224. package/templates/racing/vite.config.ts +4 -1
  225. package/templates/rts/AGENTS.md +96 -0
  226. package/templates/rts/CLAUDE.md +98 -0
  227. package/templates/rts/kit.json +7 -0
  228. package/templates/{defense → rts}/package.json +14 -8
  229. package/templates/{defense → rts}/playtests/performance.playtest.json +28 -26
  230. package/templates/rts/playtests/rts-ai-attack.playtest.json +24 -0
  231. package/templates/rts/playtests/rts-attack.playtest.json +75 -0
  232. package/templates/rts/playtests/rts-build.playtest.json +68 -0
  233. package/templates/rts/playtests/rts-orders.playtest.json +150 -0
  234. package/templates/rts/playtests/rts-train.playtest.json +62 -0
  235. package/templates/rts/playtests/survives.playtest.json +58 -0
  236. package/templates/rts/public/favicon.svg +4 -0
  237. package/templates/rts/src/game.ts +64 -0
  238. package/templates/rts/src/orders.ts +22 -0
  239. package/templates/rts/src/render/army.ts +346 -0
  240. package/templates/rts/src/render/camera.ts +123 -0
  241. package/templates/rts/src/render/lighting.ts +61 -0
  242. package/templates/rts/src/render/loading.ts +33 -0
  243. package/templates/rts/src/render/materials.ts +152 -0
  244. package/templates/rts/src/render/models.ts +705 -0
  245. package/templates/rts/src/render/palette.ts +17 -0
  246. package/templates/rts/src/render/picking.ts +93 -0
  247. package/templates/{defense → rts}/src/render/postprocessing.ts +15 -3
  248. package/templates/rts/src/render/quality.ts +128 -0
  249. package/templates/rts/src/render/resources.ts +141 -0
  250. package/templates/rts/src/render/sky.ts +44 -0
  251. package/templates/rts/src/render/terrain.ts +116 -0
  252. package/templates/{defense → rts}/src/render/worldEnvironment.ts +52 -1
  253. package/templates/rts/src/scenes/Play.ts +650 -0
  254. package/templates/rts/src/sim/ai.ts +1140 -0
  255. package/templates/rts/src/sim/combat.ts +416 -0
  256. package/templates/rts/src/sim/construction.ts +374 -0
  257. package/templates/rts/src/sim/economy.ts +167 -0
  258. package/templates/rts/src/sim/game.ts +1082 -0
  259. package/templates/rts/src/sim/movement.ts +371 -0
  260. package/templates/rts/src/sim/nav.ts +276 -0
  261. package/templates/rts/src/sim/production.ts +180 -0
  262. package/templates/rts/src/sim/terrain.ts +170 -0
  263. package/templates/rts/src/sim/types.ts +647 -0
  264. package/templates/rts/src/sim/vision.ts +46 -0
  265. package/templates/rts/src/state.ts +100 -0
  266. package/templates/{defense → rts}/src/style.css +21 -8
  267. package/templates/rts/src/ui/App.tsx +21 -0
  268. package/templates/rts/src/ui/Commands.tsx +129 -0
  269. package/templates/rts/src/ui/GameUi.tsx +22 -0
  270. package/templates/rts/src/ui/Hud.tsx +165 -0
  271. package/templates/rts/src/ui/Minimap.tsx +84 -0
  272. package/templates/rts/tailwind.config.ts +2 -0
  273. package/templates/rts/threenative.config.ts +56 -0
  274. package/templates/rts/tsconfig.json +17 -0
  275. package/templates/{defense → rts}/vite.config.ts +4 -1
  276. package/templates/runner/AGENTS.md +8 -12
  277. package/templates/runner/CLAUDE.md +8 -12
  278. package/templates/runner/README.md +3 -3
  279. package/templates/runner/package.json +14 -8
  280. package/templates/runner/playtests/performance.playtest.json +2 -2
  281. package/templates/runner/src/conventions.ts +4 -3
  282. package/templates/runner/src/entities/Runner.ts +54 -7
  283. package/templates/runner/src/game.ts +2 -0
  284. package/templates/runner/src/render/camera.ts +4 -2
  285. package/templates/runner/src/render/dust.ts +5 -2
  286. package/templates/runner/src/render/lighting.ts +41 -45
  287. package/templates/runner/src/render/loading.ts +2 -2
  288. package/templates/runner/src/render/materials.ts +165 -25
  289. package/templates/runner/src/render/palette.ts +17 -28
  290. package/templates/runner/src/render/postprocessing.ts +12 -2
  291. package/templates/runner/src/render/quality.ts +42 -96
  292. package/templates/runner/src/render/shapes.ts +59 -37
  293. package/templates/runner/src/render/sky.ts +32 -41
  294. package/templates/runner/src/render/touch-controls.ts +1 -1
  295. package/templates/runner/src/render/worldEnvironment.ts +52 -1
  296. package/templates/runner/src/scenes/Run.ts +26 -6
  297. package/templates/runner/src/track.ts +6 -1
  298. package/templates/runner/threenative.config.ts +14 -1
  299. package/templates/runner/vite.config.ts +4 -1
  300. package/templates/sailing/AGENTS.md +14 -14
  301. package/templates/sailing/CLAUDE.md +14 -14
  302. package/templates/sailing/assets/ship.glb +0 -0
  303. package/templates/sailing/package.json +14 -8
  304. package/templates/sailing/playtests/float-after-the-run-ends.playtest.json +10 -6
  305. package/templates/sailing/playtests/sails.playtest.json +33 -0
  306. package/templates/sailing/playtests/win.playtest.json +156 -8
  307. package/templates/sailing/src/conventions.ts +29 -2
  308. package/templates/sailing/src/entities/Ship.ts +381 -57
  309. package/templates/sailing/src/game.ts +14 -0
  310. package/templates/sailing/src/render/camera.ts +63 -9
  311. package/templates/sailing/src/render/lighting.ts +49 -27
  312. package/templates/sailing/src/render/materials.ts +50 -15
  313. package/templates/sailing/src/render/ocean.ts +647 -60
  314. package/templates/sailing/src/render/palette.ts +16 -12
  315. package/templates/sailing/src/render/postprocessing.ts +12 -2
  316. package/templates/sailing/src/render/props.ts +316 -442
  317. package/templates/sailing/src/render/quality.ts +14 -4
  318. package/templates/sailing/src/render/sky.ts +116 -23
  319. package/templates/sailing/src/render/worldEnvironment.ts +52 -1
  320. package/templates/sailing/src/scenes/Boot.ts +21 -0
  321. package/templates/sailing/src/scenes/Sailing.ts +173 -39
  322. package/templates/sailing/src/state.ts +6 -0
  323. package/templates/sailing/src/ui/Hud.tsx +41 -9
  324. package/templates/sailing/threenative.config.ts +14 -1
  325. package/templates/sailing/vite.config.ts +4 -1
  326. package/templates/shooter/AGENTS.md +29 -44
  327. package/templates/shooter/CLAUDE.md +29 -44
  328. package/templates/shooter/index.html +1 -0
  329. package/templates/shooter/package.json +14 -8
  330. package/templates/shooter/playtests/aim-alignment.playtest.json +58 -0
  331. package/templates/shooter/playtests/breakable-shatters.playtest.json +62 -0
  332. package/templates/shooter/playtests/bullet-holes.playtest.json +56 -0
  333. package/templates/shooter/playtests/camera-tracks-body-vertically.playtest.json +61 -0
  334. package/templates/shooter/playtests/crouch-lowers-the-eye.playtest.json +41 -0
  335. package/templates/shooter/playtests/death-no-snap.playtest.json +77 -0
  336. package/templates/shooter/playtests/debug-ads.playtest.json +58 -0
  337. package/templates/shooter/playtests/debug-clear.playtest.json +383 -0
  338. package/templates/shooter/playtests/debug-endurance.playtest.json +61 -0
  339. package/templates/shooter/playtests/debug-fire.playtest.json +119 -0
  340. package/templates/shooter/playtests/debug-restart.playtest.json +24 -0
  341. package/templates/shooter/playtests/enemy-body-is-a-body.playtest.json +79 -0
  342. package/templates/shooter/playtests/enemy-death-settles.playtest.json +64 -0
  343. package/templates/shooter/playtests/enemy-flinches-when-hit.playtest.json +75 -0
  344. package/templates/shooter/playtests/enemy-foot-contact.playtest.json +41 -0
  345. package/templates/shooter/playtests/enemy-material-is-not-shared.playtest.json +59 -0
  346. package/templates/shooter/playtests/enemy-reaches-walkway.playtest.json +80 -0
  347. package/templates/shooter/playtests/enemy-rifle-grip.playtest.json +101 -0
  348. package/templates/shooter/playtests/enemy-scale.playtest.json +56 -0
  349. package/templates/shooter/playtests/enemy-stops-without-snapping.playtest.json +486 -0
  350. package/templates/shooter/playtests/enemy-stride-matches-speed.playtest.json +198 -0
  351. package/templates/shooter/playtests/enemy-stride-under-crouch.playtest.json +87 -0
  352. package/templates/shooter/playtests/enemy-uses-crouch-clips.playtest.json +74 -0
  353. package/templates/shooter/playtests/five-soldiers.playtest.json +83 -0
  354. package/templates/shooter/playtests/flash-retires.playtest.json +62 -0
  355. package/templates/shooter/playtests/headshot-hits-head.playtest.json +132 -0
  356. package/templates/shooter/playtests/hold-to-fire.playtest.json +45 -0
  357. package/templates/shooter/playtests/input-control.playtest.json +43 -98
  358. package/templates/shooter/playtests/minimap-state.playtest.json +75 -0
  359. package/templates/shooter/playtests/performance.playtest.json +62 -26
  360. package/templates/{starter/playtests/forward.playtest.json → shooter/playtests/round-clock.playtest.json} +11 -16
  361. package/templates/shooter/playtests/shot-tracks-crosshair.playtest.json +79 -0
  362. package/templates/shooter/playtests/survives.playtest.json +36 -30
  363. package/templates/shooter/playtests/walkway-reachable.playtest.json +67 -0
  364. package/templates/shooter/src/entities/Breakables.ts +412 -0
  365. package/templates/shooter/src/entities/Enemy.ts +2095 -0
  366. package/templates/shooter/src/entities/FpsPlayer.ts +283 -0
  367. package/templates/shooter/src/entities/Rifle.ts +442 -0
  368. package/templates/shooter/src/entities/Target.ts +199 -83
  369. package/templates/shooter/src/entities/TouchControls.ts +276 -0
  370. package/templates/shooter/src/game.ts +75 -41
  371. package/templates/shooter/src/main.ts +0 -1
  372. package/templates/shooter/src/postPhysics.ts +36 -0
  373. package/templates/shooter/src/render/camera.ts +78 -74
  374. package/templates/shooter/src/render/decals.ts +142 -82
  375. package/templates/shooter/src/render/facade.ts +1373 -0
  376. package/templates/shooter/src/render/gunfx.ts +704 -0
  377. package/templates/shooter/src/render/lighting.ts +52 -38
  378. package/templates/shooter/src/render/loading.ts +2 -2
  379. package/templates/shooter/src/render/materials.ts +100 -88
  380. package/templates/shooter/src/render/occlusion.ts +108 -0
  381. package/templates/shooter/src/render/palette.ts +10 -10
  382. package/templates/shooter/src/render/palm.ts +455 -0
  383. package/templates/shooter/src/render/pooled-billboards.ts +144 -0
  384. package/templates/shooter/src/render/postprocessing.ts +15 -3
  385. package/templates/shooter/src/render/quality.ts +40 -82
  386. package/templates/shooter/src/render/scale.ts +148 -15
  387. package/templates/shooter/src/render/shapes.ts +138 -613
  388. package/templates/shooter/src/render/sky.ts +35 -35
  389. package/templates/shooter/src/render/town-schematic.ts +120 -0
  390. package/templates/shooter/src/render/town.ts +986 -0
  391. package/templates/shooter/src/render/townMaterials.ts +160 -0
  392. package/templates/shooter/src/render/vehicles.ts +741 -0
  393. package/templates/shooter/src/render/worldEnvironment.ts +52 -1
  394. package/templates/shooter/src/scenes/Play.ts +727 -650
  395. package/templates/shooter/src/state.ts +26 -41
  396. package/templates/shooter/src/style.css +207 -11
  397. package/templates/shooter/src/surfaces.ts +131 -0
  398. package/templates/shooter/src/ui/App.tsx +9 -10
  399. package/templates/shooter/src/ui/Crosshair.tsx +25 -18
  400. package/templates/shooter/src/ui/GameUi.tsx +6 -9
  401. package/templates/shooter/src/ui/Hud.tsx +428 -39
  402. package/templates/shooter/src/ui/Minimap.tsx +164 -0
  403. package/templates/shooter/src/ui/TouchOverlay.tsx +54 -0
  404. package/templates/shooter/src/ui/main.tsx +2 -3
  405. package/templates/shooter/threenative.config.ts +14 -1
  406. package/templates/shooter/vite.config.ts +4 -1
  407. package/templates/starter/AGENTS.md +20 -20
  408. package/templates/starter/CLAUDE.md +20 -20
  409. package/templates/starter/native-playtests/render-chain.playtest.json +13 -45
  410. package/templates/starter/package.json +15 -9
  411. package/templates/starter/playtests/play.playtest.json +2 -1
  412. package/templates/starter/playtests/{restart.playtest.json → production-readiness.playtest.json} +17 -12
  413. package/templates/starter/playtests/survives.playtest.json +1 -1
  414. package/templates/starter/src/conventions.ts +6 -3
  415. package/templates/starter/src/entities/Goal.ts +35 -42
  416. package/templates/starter/src/entities/Player.ts +99 -16
  417. package/templates/starter/src/render/arena.ts +131 -0
  418. package/templates/starter/src/render/lighting.ts +27 -44
  419. package/templates/starter/src/render/materials.ts +164 -35
  420. package/templates/starter/src/render/palette.ts +16 -16
  421. package/templates/starter/src/render/postprocessing.ts +6 -7
  422. package/templates/starter/src/render/quality.ts +43 -101
  423. package/templates/starter/src/render/shapes.ts +1 -1
  424. package/templates/starter/src/render/sky.ts +39 -45
  425. package/templates/starter/src/render/touch-controls.ts +3 -1
  426. package/templates/starter/src/render/worldEnvironment.ts +52 -1
  427. package/templates/starter/src/scenes/Play.ts +82 -81
  428. package/templates/starter/src/ui/Hud.tsx +2 -2
  429. package/templates/starter/src/ui/Menu.tsx +5 -1
  430. package/templates/starter/threenative.config.ts +14 -1
  431. package/templates/starter/vite.config.ts +4 -1
  432. package/templates/tower-defense/.codex/config.toml +19 -0
  433. package/templates/tower-defense/.cursor/mcp.json +32 -0
  434. package/templates/tower-defense/.gemini/settings.json +32 -0
  435. package/templates/tower-defense/.mcp.json +32 -0
  436. package/templates/tower-defense/.vscode/mcp.json +36 -0
  437. package/templates/tower-defense/.zed/settings.json +36 -0
  438. package/templates/{defense → tower-defense}/AGENTS.md +16 -14
  439. package/templates/{defense → tower-defense}/CLAUDE.md +16 -14
  440. package/templates/tower-defense/README.md +16 -0
  441. package/templates/tower-defense/index.html +12 -0
  442. package/templates/tower-defense/kit.json +7 -0
  443. package/templates/tower-defense/opencode.json +41 -0
  444. package/templates/tower-defense/package.json +56 -0
  445. package/templates/tower-defense/playtests/arsenal.playtest.json +214 -0
  446. package/templates/tower-defense/playtests/defeat.playtest.json +85 -0
  447. package/templates/tower-defense/playtests/look.playtest.json +130 -0
  448. package/templates/tower-defense/playtests/performance.playtest.json +77 -0
  449. package/templates/tower-defense/playtests/placement.playtest.json +115 -0
  450. package/templates/{defense → tower-defense}/playtests/pointer-placement.playtest.json +21 -49
  451. package/templates/tower-defense/playtests/strike.playtest.json +98 -0
  452. package/templates/tower-defense/playtests/survives.playtest.json +85 -0
  453. package/templates/tower-defense/playtests/target-priority.playtest.json +177 -0
  454. package/templates/tower-defense/playtests/upgrade-recycle.playtest.json +124 -0
  455. package/templates/tower-defense/playtests/victory.playtest.json +810 -0
  456. package/templates/tower-defense/src/balance.ts +187 -0
  457. package/templates/tower-defense/src/board/Board.ts +100 -0
  458. package/templates/tower-defense/src/board/Route.ts +84 -0
  459. package/templates/tower-defense/src/camera-rig.ts +62 -0
  460. package/templates/tower-defense/src/economy.ts +64 -0
  461. package/templates/tower-defense/src/effects/Effects.ts +284 -0
  462. package/templates/tower-defense/src/enemies/Enemy.ts +198 -0
  463. package/templates/tower-defense/src/game.ts +72 -0
  464. package/templates/tower-defense/src/intents.ts +21 -0
  465. package/templates/tower-defense/src/main.ts +15 -0
  466. package/templates/tower-defense/src/physics.ts +6 -0
  467. package/templates/tower-defense/src/render/camera.ts +38 -0
  468. package/templates/tower-defense/src/render/lighting.ts +42 -0
  469. package/templates/{defense → tower-defense}/src/render/loading.ts +3 -3
  470. package/templates/tower-defense/src/render/materials.ts +103 -0
  471. package/templates/tower-defense/src/render/palette.ts +58 -0
  472. package/templates/tower-defense/src/render/postprocessing.ts +46 -0
  473. package/templates/tower-defense/src/render/quality.ts +128 -0
  474. package/templates/tower-defense/src/render/shapes.ts +550 -0
  475. package/templates/tower-defense/src/render/sky.ts +27 -0
  476. package/templates/tower-defense/src/render/worldEnvironment.ts +809 -0
  477. package/templates/tower-defense/src/scenes/Battle.ts +539 -0
  478. package/templates/{shooter → tower-defense}/src/scenes/Boot.ts +3 -3
  479. package/templates/tower-defense/src/state.ts +88 -0
  480. package/templates/tower-defense/src/style.css +137 -0
  481. package/templates/tower-defense/src/towers/Tower.ts +230 -0
  482. package/templates/tower-defense/src/towers/targeting.ts +97 -0
  483. package/templates/tower-defense/src/ui/Hud.tsx +270 -0
  484. package/templates/tower-defense/src/ui/Menu.tsx +134 -0
  485. package/templates/tower-defense/src/ui/icons.tsx +54 -0
  486. package/templates/tower-defense/src/ui/main.tsx +14 -0
  487. package/templates/tower-defense/src/waves.ts +90 -0
  488. package/templates/{defense → tower-defense}/threenative.config.ts +14 -1
  489. package/templates/tower-defense/vite.config.ts +41 -0
  490. package/agent-files/.claude/skills/file-engine-bug/SKILL.md +0 -59
  491. package/agent-files/.claude/skills/prd-creator/SKILL.md +0 -40
  492. package/agent-files/.claude/skills/threenative-assets/SKILL.md +0 -45
  493. package/agent-files/.claude/skills/threenative-capabilities/SKILL.md +0 -27
  494. package/agent-files/.claude/skills/threenative-context/SKILL.md +0 -57
  495. package/agent-files/.claude/skills/threenative-performance/SKILL.md +0 -42
  496. package/agent-files/.claude/skills/threenative-playtest/SKILL.md +0 -44
  497. package/agent-files/.claude/skills/threenative-ui/SKILL.md +0 -20
  498. package/agent-files/.claude/skills/threenative-visuals/SKILL.md +0 -41
  499. package/agent-files/AGENT-ROLES.md +0 -26
  500. package/templates/action-rpg/src/render/shapes.ts +0 -269
  501. package/templates/action-rpg/src/render/types.ts +0 -3
  502. package/templates/action-rpg/src/scenes/Boot.ts +0 -12
  503. package/templates/defense/README.md +0 -10
  504. package/templates/defense/kit.json +0 -7
  505. package/templates/defense/playtests/leak.playtest.json +0 -23
  506. package/templates/defense/playtests/placement.playtest.json +0 -40
  507. package/templates/defense/playtests/scan.playtest.json +0 -20
  508. package/templates/defense/playtests/survive.playtest.json +0 -45
  509. package/templates/defense/playtests/survives.playtest.json +0 -36
  510. package/templates/defense/src/attackers/Attacker.ts +0 -120
  511. package/templates/defense/src/board/Route.ts +0 -94
  512. package/templates/defense/src/conventions.ts +0 -18
  513. package/templates/defense/src/economy.ts +0 -36
  514. package/templates/defense/src/entities/Player.ts +0 -52
  515. package/templates/defense/src/game.ts +0 -51
  516. package/templates/defense/src/physics.ts +0 -13
  517. package/templates/defense/src/placement/Buildable.ts +0 -49
  518. package/templates/defense/src/render/camera.ts +0 -16
  519. package/templates/defense/src/render/lighting.ts +0 -37
  520. package/templates/defense/src/render/materials.ts +0 -22
  521. package/templates/defense/src/render/palette.ts +0 -28
  522. package/templates/defense/src/render/quality.ts +0 -170
  523. package/templates/defense/src/render/shapes.ts +0 -246
  524. package/templates/defense/src/render/sky.ts +0 -45
  525. package/templates/defense/src/scenes/Boot.ts +0 -12
  526. package/templates/defense/src/scenes/Defense.ts +0 -231
  527. package/templates/defense/src/state.ts +0 -56
  528. package/templates/defense/src/towers/Tower.ts +0 -95
  529. package/templates/defense/src/towers/targeting.ts +0 -53
  530. package/templates/defense/src/ui/Hud.tsx +0 -62
  531. package/templates/defense/src/ui/Menu.tsx +0 -7
  532. package/templates/defense/src/waves.ts +0 -40
  533. package/templates/minimal/playtests/atmosphere.playtest.json +0 -32
  534. package/templates/minimal/src/render/hud.ts +0 -69
  535. package/templates/platformer/playtests/avoidance.playtest.json +0 -28
  536. package/templates/platformer/playtests/chase.playtest.json +0 -21
  537. package/templates/platformer/playtests/collision-layers.playtest.json +0 -36
  538. package/templates/platformer/playtests/oneway.playtest.json +0 -44
  539. package/templates/platformer/playtests/patrol.playtest.json +0 -13
  540. package/templates/platformer/playtests/physics.playtest.json +0 -14
  541. package/templates/platformer/playtests/stomp-rise.playtest.json +0 -55
  542. package/templates/platformer/playtests/terminal-loop-fail.playtest.json +0 -41
  543. package/templates/platformer/playtests/terminal-loop-win.playtest.json +0 -52
  544. package/templates/platformer/src/conventions.ts +0 -18
  545. package/templates/platformer/src/entities/Character.ts +0 -286
  546. package/templates/platformer/src/entities/Chaser.ts +0 -118
  547. package/templates/platformer/src/entities/Patrol.ts +0 -93
  548. package/templates/platformer/src/level/Platform.ts +0 -46
  549. package/templates/platformer/src/render/rig.ts +0 -60
  550. package/templates/platformer/src/render/terrain.ts +0 -31
  551. package/templates/platformer/src/scenes/Level.ts +0 -241
  552. package/templates/puzzle/README.md +0 -43
  553. package/templates/puzzle/playtests/carry.playtest.json +0 -71
  554. package/templates/puzzle/playtests/swing.playtest.json +0 -38
  555. package/templates/puzzle/src/conventions.ts +0 -25
  556. package/templates/puzzle/src/entities/Ball.ts +0 -70
  557. package/templates/puzzle/src/entities/Gripper.ts +0 -69
  558. package/templates/puzzle/src/entities/Pendulum.ts +0 -89
  559. package/templates/puzzle/src/physics.ts +0 -19
  560. package/templates/puzzle/src/room.ts +0 -83
  561. package/templates/puzzle/src/scenes/Boot.ts +0 -12
  562. package/templates/puzzle/src/scenes/Puzzle.ts +0 -158
  563. package/templates/shooter/playtests/combat.playtest.json +0 -48
  564. package/templates/shooter/playtests/fail.playtest.json +0 -31
  565. package/templates/shooter/playtests/per-item.playtest.json +0 -59
  566. package/templates/shooter/playtests/shooter.playtest.json +0 -99
  567. package/templates/shooter/playtests/touch-controls.playtest.json +0 -42
  568. package/templates/shooter/playtests/weapon-cycle.playtest.json +0 -164
  569. package/templates/shooter/src/combat/damage.ts +0 -40
  570. package/templates/shooter/src/conventions.ts +0 -51
  571. package/templates/shooter/src/entities/Pickup.ts +0 -70
  572. package/templates/shooter/src/entities/Player.ts +0 -310
  573. package/templates/shooter/src/level/SpawnPoints.ts +0 -28
  574. package/templates/shooter/src/playtest-events.ts +0 -15
  575. package/templates/shooter/src/render/touch-controls.ts +0 -305
  576. package/templates/shooter/src/render/types.ts +0 -3
  577. package/templates/shooter/src/render/ui.css +0 -330
  578. package/templates/shooter/src/render/ui.ts +0 -75
  579. package/templates/shooter/src/render/vfx.ts +0 -215
  580. package/templates/shooter/src/ui/Menu.tsx +0 -41
  581. package/templates/shooter/src/waves.ts +0 -50
  582. package/templates/shooter/src/weapons/Hitscan.ts +0 -42
  583. package/templates/shooter/src/weapons/Projectile.ts +0 -92
  584. package/templates/shooter/src/weapons/Viewmodel.ts +0 -275
  585. package/templates/starter/playtests/assets.playtest.json +0 -65
  586. package/templates/starter/playtests/buffer.playtest.json +0 -79
  587. package/templates/starter/playtests/cloth.playtest.json +0 -113
  588. package/templates/starter/playtests/coyote.playtest.json +0 -87
  589. package/templates/starter/playtests/gameover.playtest.json +0 -66
  590. package/templates/starter/playtests/goal.playtest.json +0 -67
  591. package/templates/starter/playtests/look.playtest.json +0 -175
  592. package/templates/starter/playtests/models-baseline.png +0 -0
  593. package/templates/starter/playtests/models.playtest.json +0 -74
  594. package/templates/starter/playtests/monitoring.playtest.json +0 -72
  595. package/templates/starter/playtests/odometer.playtest.json +0 -54
  596. package/templates/starter/playtests/seed.playtest.json +0 -54
  597. package/templates/starter/playtests/textures-baseline.png +0 -0
  598. package/templates/starter/playtests/textures.playtest.json +0 -74
  599. package/templates/starter/playtests/touch-controls.playtest.json +0 -42
  600. package/templates/starter/playtests/zoom-pinch.playtest.json +0 -86
  601. package/templates/starter/playtests/zoom-wheel.playtest.json +0 -59
  602. package/templates/starter/src/render/coast.ts +0 -199
  603. package/templates/starter/src/render/hero.ts +0 -88
  604. package/templates/starter/src/render/implicitSurface.ts +0 -199
  605. package/templates/starter/src/render/kuwahara.ts +0 -174
  606. package/templates/starter/src/render/outline.ts +0 -141
  607. package/templates/starter/src/render/painterly.ts +0 -86
  608. package/templates/starter/src/render/rockRidge.ts +0 -198
  609. package/templates/starter/src/render/rockRidge.worker.ts +0 -77
  610. package/templates/starter/src/render/scenery.ts +0 -40
  611. package/templates/starter/src/render/textureLifetime.ts +0 -53
  612. package/templates/starter/src/render/water.ts +0 -38
  613. package/templates/starter/src/render/watercolor.ts +0 -85
  614. /package/templates/{starter → puzzle}/playtests/boot-failure.playtest.json +0 -0
  615. /package/templates/{starter → puzzle}/playtests/pause.playtest.json +0 -0
  616. /package/templates/{defense → rts}/.codex/config.toml +0 -0
  617. /package/templates/{defense → rts}/.cursor/mcp.json +0 -0
  618. /package/templates/{defense → rts}/.gemini/settings.json +0 -0
  619. /package/templates/{defense → rts}/.mcp.json +0 -0
  620. /package/templates/{defense → rts}/.vscode/mcp.json +0 -0
  621. /package/templates/{defense → rts}/.zed/settings.json +0 -0
  622. /package/templates/{defense → rts}/index.html +0 -0
  623. /package/templates/{defense → rts}/opencode.json +0 -0
  624. /package/templates/{defense → rts}/src/main.ts +0 -0
  625. /package/templates/{defense → rts}/src/ui/main.tsx +0 -0
  626. /package/templates/{defense → tower-defense}/public/favicon.svg +0 -0
  627. /package/templates/{defense → tower-defense}/src/playtest-events.ts +0 -0
  628. /package/templates/{defense → tower-defense}/src/ui/App.tsx +0 -0
  629. /package/templates/{defense → tower-defense}/src/ui/GameUi.tsx +0 -0
  630. /package/templates/{defense → tower-defense}/tailwind.config.ts +0 -0
  631. /package/templates/{defense → tower-defense}/tsconfig.json +0 -0
@@ -3,13 +3,28 @@
3
3
 
4
4
  # Capability reference
5
5
 
6
- Every public class and function export represented by this manifest across `@threenative/assets`, `@threenative/core`, `@threenative/physics`, `@threenative/playtest`, `@threenative/raw-unreal`, `@threenative/ueformat`, `@threenative/ui`, `template:starter`, and `three`,
6
+ Every public class and function export represented by this manifest across `@threenative/assets`, `@threenative/core`, `@threenative/metahuman`, `@threenative/physics`, `@threenative/playtest`, `@threenative/raw-unreal`, `@threenative/ueformat`, `@threenative/ui`, `template:starter`, and `three`,
7
7
  generated from the doc tags the engine itself compiles, so this page cannot disagree with
8
8
  the code. Look here before writing a replacement; ask `engine_search_capabilities` when an
9
9
  MCP server is available.
10
10
 
11
11
  ## `@threenative/assets`
12
12
 
13
+ ### `atlasManifest`
14
+
15
+ `function` — Pack texture sources into deterministic atlas pages and answer each source's UV transform, so a build can stop giving every material a private texture.
16
+
17
+ ```ts
18
+ export function atlasManifest(result: IAtlasResult): string { … }
19
+ ```
20
+
21
+ - **Use when:** a merge found nothing to collapse because each imported part owns its own texture · cut the material count of an imported model pack at build time
22
+ - **Constraints:** deterministic by construction: the packing order is derived from the sources, never from directory order, so a rebuild places every source at the same pixel · a source the scene samples outside [0, 1] is excluded and reported, never clamped onto a shared page · page bounds hold regardless of input order; padding keeps a mip tap from reaching the next source
23
+
24
+ ```ts
25
+ const { pages, transforms, excluded } = packAtlas(sources, { pageSize: 4096, padding: 4 });
26
+ ```
27
+
13
28
  ### `audioPass`
14
29
 
15
30
  `function` — Conditions a game's audio and proves the conditioning did not destroy it.
@@ -25,6 +40,21 @@ export function audioPass(options: IAudioPassOptions = { … }
25
40
  const pass = audioPass({ overrides: [{ glob: "audio/*-bed.ogg", loop: true }] });
26
41
  ```
27
42
 
43
+ ### `censusDocument`
44
+
45
+ `function` — Census one glTF document, or a directory of them: the merge buckets a scene has now, and the buckets it would have once its atlasable textures shared pages.
46
+
47
+ ```ts
48
+ export function censusDocument( model: string, document: Document, pageSize = 4_096, ): IContentCensus { … }
49
+ ```
50
+
51
+ - **Use when:** find out whether "fewer objects" is available in this content before promising it · explain why a per-material merge collapsed nothing
52
+ - **Constraints:** reads geometry and materials only: no GPU, no runtime, no game · a texture whose size the document does not state is reported excluded, never assumed square · a model the reader cannot open is named, never skipped silently
53
+
54
+ ```ts
55
+ pnpm census:content public/assets
56
+ ```
57
+
28
58
  ### `compileAssets`
29
59
 
30
60
  `function` — Compiles a project's source assets into content-addressed runtime files and a manifest.
@@ -40,6 +70,21 @@ export async function compileAssets( options: IAssetCompileOptions = { … }
40
70
  const result = await compileAssets({ source: "assets", output: "public" });
41
71
  ```
42
72
 
73
+ ### `dedupeMaterials`
74
+
75
+ `function` — Collapse materials that became identical once their textures shared an atlas page, and count the buckets a merge would find — before and after — so the promise can be checked rather than made.
76
+
77
+ ```ts
78
+ export function dedupeMaterials(materials: readonly IMaterialState[]): { … }
79
+ ```
80
+
81
+ - **Use when:** decide whether fewer objects is actually available in this content · report why a per-material merge collapsed nothing
82
+ - **Constraints:** the signature ignores the material name, which is what made every imported part a singleton, and keeps materials apart on any field it does not understand · the census reads geometry and materials only: no GPU, no runtime, no game
83
+
84
+ ```ts
85
+ pnpm census:content public/assets
86
+ ```
87
+
43
88
  ### `formatAudioSizes`
44
89
 
45
90
  `function` — Formats audio conditioning measurements for a build report.
@@ -130,6 +175,36 @@ export function lightmapPass(options: ILightmapPassOptions): IAssetPass { … }
130
175
  const pass = lightmapPass({ atlasSize: 1024, padding: 2 });
131
176
  ```
132
177
 
178
+ ### `materialSignature`
179
+
180
+ `function` — Collapse materials that became identical once their textures shared an atlas page, and count the buckets a merge would find — before and after — so the promise can be checked rather than made.
181
+
182
+ ```ts
183
+ export function materialSignature(material: IMaterialState): string { … }
184
+ ```
185
+
186
+ - **Use when:** decide whether fewer objects is actually available in this content · report why a per-material merge collapsed nothing
187
+ - **Constraints:** the signature ignores the material name, which is what made every imported part a singleton, and keeps materials apart on any field it does not understand · the census reads geometry and materials only: no GPU, no runtime, no game
188
+
189
+ ```ts
190
+ pnpm census:content public/assets
191
+ ```
192
+
193
+ ### `materialStateOf`
194
+
195
+ `function` — Census one glTF document, or a directory of them: the merge buckets a scene has now, and the buckets it would have once its atlasable textures shared pages.
196
+
197
+ ```ts
198
+ export function materialStateOf(material: Material): IMaterialState { … }
199
+ ```
200
+
201
+ - **Use when:** find out whether "fewer objects" is available in this content before promising it · explain why a per-material merge collapsed nothing
202
+ - **Constraints:** reads geometry and materials only: no GPU, no runtime, no game · a texture whose size the document does not state is reported excluded, never assumed square · a model the reader cannot open is named, never skipped silently
203
+
204
+ ```ts
205
+ pnpm census:content public/assets
206
+ ```
207
+
133
208
  ### `modelPass`
134
209
 
135
210
  `function` — Optimizes self-contained GLB models through the configured geometry and embedded-texture passes.
@@ -145,6 +220,21 @@ export function modelPass(options: IModelPassOptions = { … }
145
220
  const pass = modelPass({ simplify: { ratio: 0.5 } });
146
221
  ```
147
222
 
223
+ ### `packAtlas`
224
+
225
+ `function` — Pack texture sources into deterministic atlas pages and answer each source's UV transform, so a build can stop giving every material a private texture.
226
+
227
+ ```ts
228
+ export function packAtlas( sources: readonly IAtlasSource[], options: IAtlasOptions = { … }
229
+ ```
230
+
231
+ - **Use when:** a merge found nothing to collapse because each imported part owns its own texture · cut the material count of an imported model pack at build time
232
+ - **Constraints:** deterministic by construction: the packing order is derived from the sources, never from directory order, so a rebuild places every source at the same pixel · a source the scene samples outside [0, 1] is excluded and reported, never clamped onto a shared page · page bounds hold regardless of input order; padding keeps a mip tap from reaching the next source
233
+
234
+ ```ts
235
+ const { pages, transforms, excluded } = packAtlas(sources, { pageSize: 4096, padding: 4 });
236
+ ```
237
+
148
238
  ### `parseAudioConfig`
149
239
 
150
240
  `function` — Validates a game's declared `assets.audio` block, the one place its keys and ranges are checked.
@@ -190,6 +280,36 @@ export function resolveBasisTranscoder(cwd: string): IBasisTranscoder { … }
190
280
  const transcoder = resolveBasisTranscoder(process.cwd());
191
281
  ```
192
282
 
283
+ ### `resolveSourceTexel`
284
+
285
+ `function` — Move a mesh's UVs onto its atlas page, and decide from the geometry which meshes may not go.
286
+
287
+ ```ts
288
+ export function resolveSourceTexel( atlasUv: readonly [number, number], transform: IAtlasTransform, source: { … }
289
+ ```
290
+
291
+ - **Use when:** rewrite a model's texture coordinates after packing its images into an atlas · tell a surface that tiles from one that merely has a repeating sampler
292
+ - **Constraints:** a surface is tiling when its own UVs leave [0, 1]; glTF's default wrap is REPEAT, so the sampler alone excludes almost everything and is the wrong test · the rewrite is in place, and a buffer that does not hold pairs throws rather than rewriting half a coordinate · `resolveSourceTexel` is the inverse, so a build can round-trip a texel instead of asserting the arithmetic against itself
293
+
294
+ ```ts
295
+ if (!uvsTile(uv)) rewriteUvs(uv, transforms.get(source)!);
296
+ ```
297
+
298
+ ### `rewriteUvs`
299
+
300
+ `function` — Move a mesh's UVs onto its atlas page, and decide from the geometry which meshes may not go.
301
+
302
+ ```ts
303
+ export function rewriteUvs(uv: Float32Array, transform: IAtlasTransform): Float32Array { … }
304
+ ```
305
+
306
+ - **Use when:** rewrite a model's texture coordinates after packing its images into an atlas · tell a surface that tiles from one that merely has a repeating sampler
307
+ - **Constraints:** a surface is tiling when its own UVs leave [0, 1]; glTF's default wrap is REPEAT, so the sampler alone excludes almost everything and is the wrong test · the rewrite is in place, and a buffer that does not hold pairs throws rather than rewriting half a coordinate · `resolveSourceTexel` is the inverse, so a build can round-trip a texel instead of asserting the arithmetic against itself
308
+
309
+ ```ts
310
+ if (!uvsTile(uv)) rewriteUvs(uv, transforms.get(source)!);
311
+ ```
312
+
193
313
  ### `runHealthReport`
194
314
 
195
315
  `function` — Measures compiled assets and grades them against declared project targets.
@@ -220,6 +340,36 @@ export function texturePass(options: ITexturePassOptions = { … }
220
340
  const pass = texturePass({ quality: 150 });
221
341
  ```
222
342
 
343
+ ### `totalCensus`
344
+
345
+ `function` — Census one glTF document, or a directory of them: the merge buckets a scene has now, and the buckets it would have once its atlasable textures shared pages.
346
+
347
+ ```ts
348
+ export function totalCensus(entries: readonly IContentCensus[]): Omit<IContentCensus, "model"> { … }
349
+ ```
350
+
351
+ - **Use when:** find out whether "fewer objects" is available in this content before promising it · explain why a per-material merge collapsed nothing
352
+ - **Constraints:** reads geometry and materials only: no GPU, no runtime, no game · a texture whose size the document does not state is reported excluded, never assumed square · a model the reader cannot open is named, never skipped silently
353
+
354
+ ```ts
355
+ pnpm census:content public/assets
356
+ ```
357
+
358
+ ### `uvsTile`
359
+
360
+ `function` — Move a mesh's UVs onto its atlas page, and decide from the geometry which meshes may not go.
361
+
362
+ ```ts
363
+ export function uvsTile(uv: ArrayLike<number>): boolean { … }
364
+ ```
365
+
366
+ - **Use when:** rewrite a model's texture coordinates after packing its images into an atlas · tell a surface that tiles from one that merely has a repeating sampler
367
+ - **Constraints:** a surface is tiling when its own UVs leave [0, 1]; glTF's default wrap is REPEAT, so the sampler alone excludes almost everything and is the wrong test · the rewrite is in place, and a buffer that does not hold pairs throws rather than rewriting half a coordinate · `resolveSourceTexel` is the inverse, so a build can round-trip a texel instead of asserting the arithmetic against itself
368
+
369
+ ```ts
370
+ if (!uvsTile(uv)) rewriteUvs(uv, transforms.get(source)!);
371
+ ```
372
+
223
373
  ### `watchAssets`
224
374
 
225
375
  `function` — Watches an asset source directory and recompiles settled changes during development.
@@ -235,6 +385,36 @@ export function watchAssets(options: IAssetWatchOptions = { … }
235
385
  const watcher = watchAssets({ cwd: process.cwd() });
236
386
  ```
237
387
 
388
+ ### `withAtlasTextures`
389
+
390
+ `function` — Collapse materials that became identical once their textures shared an atlas page, and count the buckets a merge would find — before and after — so the promise can be checked rather than made.
391
+
392
+ ```ts
393
+ export function withAtlasTextures( materials: readonly IMaterialState[], pageOf: (texture: string) => string | undefined, ): IMaterialState[] { … }
394
+ ```
395
+
396
+ - **Use when:** decide whether fewer objects is actually available in this content · report why a per-material merge collapsed nothing
397
+ - **Constraints:** the signature ignores the material name, which is what made every imported part a singleton, and keeps materials apart on any field it does not understand · the census reads geometry and materials only: no GPU, no runtime, no game
398
+
399
+ ```ts
400
+ pnpm census:content public/assets
401
+ ```
402
+
403
+ ### `wrapTiles`
404
+
405
+ `function` — Move a mesh's UVs onto its atlas page, and decide from the geometry which meshes may not go.
406
+
407
+ ```ts
408
+ export function wrapTiles(wrapS: number | undefined, wrapT: number | undefined): boolean { … }
409
+ ```
410
+
411
+ - **Use when:** rewrite a model's texture coordinates after packing its images into an atlas · tell a surface that tiles from one that merely has a repeating sampler
412
+ - **Constraints:** a surface is tiling when its own UVs leave [0, 1]; glTF's default wrap is REPEAT, so the sampler alone excludes almost everything and is the wrong test · the rewrite is in place, and a buffer that does not hold pairs throws rather than rewriting half a coordinate · `resolveSourceTexel` is the inverse, so a build can round-trip a texel instead of asserting the arithmetic against itself
413
+
414
+ ```ts
415
+ if (!uvsTile(uv)) rewriteUvs(uv, transforms.get(source)!);
416
+ ```
417
+
238
418
  ## `@threenative/core`
239
419
 
240
420
  ### `addInSlices`
@@ -256,6 +436,37 @@ const report = await addInSlices(objects, (object) => ctx.add(object), {
256
436
  });
257
437
  ```
258
438
 
439
+ ### `addSpan`
440
+
441
+ `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.
442
+
443
+ ```ts
444
+ export function addSpan(id: SpanId, ms: number): void { … }
445
+ ```
446
+
447
+ - **Use when:** find out what inside the render phase is actually costing the frame · tell a shadow pass's traversal from the main pass's, with the residual computed · price an optimisation against a measured part of the phase rather than the whole of it
448
+ - **Constraints:** off by default and installed by `TN_FRAME_SPANS=1`; unset, every call site is one guarded return · the tree is closed against the frame budget's own render phase, so `TN_FRAME_SPANS` and `TN_FRAME_BUDGET` describe the same frames · measurement only: no span changes what is drawn, in what order, or with which renderer
449
+
450
+ ```ts
451
+ if (spansRequested()) setSpanRecorder(new SpanRecorder());
452
+ ```
453
+
454
+ ### `aerodynamicCoefficients`
455
+
456
+ `function` — Fly a fixed-wing aircraft with a real force balance instead of a steered velocity.
457
+
458
+ ```ts
459
+ export function aerodynamicCoefficients( alpha: number, flaps = 0, gear = 0, brakes = 0, ): { … }
460
+ ```
461
+
462
+ - **Use when:** fly an airplane with lift, drag, stall and control authority · launch an aircraft off a moving carrier deck · apply component damage or a loadout to an aircraft's performance
463
+ - **Constraints:** every mass, area, power and inertia value comes from the game's airframe · damage, stores and configuration arrive as the game's own modifier sample
464
+
465
+ ```ts
466
+ const model = new FlightModel({ airframe: sbd, state: aircraft, wind: seaWind });
467
+ model.step(1 / 60, { turn: -1, pitch: 0.4 });
468
+ ```
469
+
259
470
  ### `afterPhysics`
260
471
 
261
472
  `function` — Register work that reads a body or camera after physics has moved it and before this frame draws. The engine owns the phase ordering; a callback cannot be misplaced by plugin-array order.
@@ -271,6 +482,55 @@ export function afterPhysics( context: IAfterPhysicsContext, callback: AfterPhys
271
482
  afterPhysics(ctx, (dt) => camera.position.copy(player.mesh.position));
272
483
  ```
273
484
 
485
+ ### `aircraftMass`
486
+
487
+ `function` — Fly a fixed-wing aircraft with a real force balance instead of a steered velocity.
488
+
489
+ ```ts
490
+ export function aircraftMass(state: IFlightState, airframe: IAircraftAirframe): number { … }
491
+ ```
492
+
493
+ - **Use when:** fly an airplane with lift, drag, stall and control authority · launch an aircraft off a moving carrier deck · apply component damage or a loadout to an aircraft's performance
494
+ - **Constraints:** every mass, area, power and inertia value comes from the game's airframe · damage, stores and configuration arrive as the game's own modifier sample
495
+
496
+ ```ts
497
+ const model = new FlightModel({ airframe: sbd, state: aircraft, wind: seaWind });
498
+ model.step(1 / 60, { turn: -1, pitch: 0.4 });
499
+ ```
500
+
501
+ ### `airDensity`
502
+
503
+ `function` — Fly a fixed-wing aircraft with a real force balance instead of a steered velocity.
504
+
505
+ ```ts
506
+ export function airDensity(y: number): number { … }
507
+ ```
508
+
509
+ - **Use when:** fly an airplane with lift, drag, stall and control authority · launch an aircraft off a moving carrier deck · apply component damage or a loadout to an aircraft's performance
510
+ - **Constraints:** every mass, area, power and inertia value comes from the game's airframe · damage, stores and configuration arrive as the game's own modifier sample
511
+
512
+ ```ts
513
+ const model = new FlightModel({ airframe: sbd, state: aircraft, wind: seaWind });
514
+ model.step(1 / 60, { turn: -1, pitch: 0.4 });
515
+ ```
516
+
517
+ ### `alwaysRender`
518
+
519
+ `function` — Keep an object drawn even when the render camera cannot resolve it. The engine's projected-size gate is on by default: an object whose world bounding sphere projects to fewer than 0.5 raster pixels in the camera about to render it is not submitted, per camera. Mark the player's own cockpit, a nameplate, a quest marker, or anything a game never wants to pop out of the frame. `alwaysRender(object, false)` removes the marker. Camera-attached objects and shadow casters are already kept, and the number of marked objects is reported beside the cull in the `TN_PROJECTION` window rather than hidden. The threshold itself is `renderer.minimumProjectedPixels` — a larger number cuts more aggressively, `false` leaves every object drawn while still measuring.
520
+
521
+ ```ts
522
+ export function alwaysRender(object: Object3D, enabled = true): void { … }
523
+ ```
524
+
525
+ - **Use when:** keep a small object drawn when the engine would skip it as too far to resolve · stop my cockpit, marker or player model popping out at distance · a tiny object disappeared at range and I need it always visible · widen or narrow the projected-size cull with a named threshold
526
+ - **Constraints:** the marker is per object and is reported as `exemptMarked` in the projection window · `renderer.minimumProjectedPixels: false` leaves the scene drawn and keeps the measurement on · the marker is per object and survives scene rebuilds only as long as the object does · disabling the gate (`renderer.minimumProjectedPixels: false`) keeps its measurement on
527
+ - **Overrides:** renderer.minimumProjectedPixels sets the projected-pixel threshold, default 0.5
528
+
529
+ ```ts
530
+ import { alwaysRender } from "@threenative/core";
531
+ alwaysRender(ctx.camera.children[0]); // a camera-attached cockpit stays drawn
532
+ ```
533
+
274
534
  ### `AnimationPlayer`
275
535
 
276
536
  `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.
@@ -334,6 +594,22 @@ import { attachToBone } from "@threenative/core";
334
594
  attachToBone(character, "RightHand", rifle);
335
595
  ```
336
596
 
597
+ ### `attitudeAxes`
598
+
599
+ `function` — Fly a fixed-wing aircraft with a real force balance instead of a steered velocity.
600
+
601
+ ```ts
602
+ export function attitudeAxes(state: IFlightState): IFlightAxes { … }
603
+ ```
604
+
605
+ - **Use when:** fly an airplane with lift, drag, stall and control authority · launch an aircraft off a moving carrier deck · apply component damage or a loadout to an aircraft's performance
606
+ - **Constraints:** every mass, area, power and inertia value comes from the game's airframe · damage, stores and configuration arrive as the game's own modifier sample
607
+
608
+ ```ts
609
+ const model = new FlightModel({ airframe: sbd, state: aircraft, wind: seaWind });
610
+ model.step(1 / 60, { turn: -1, pitch: 0.4 });
611
+ ```
612
+
337
613
  ### `AudioBus`
338
614
 
339
615
  `class` — Route effects through a named audio bus.
@@ -350,6 +626,35 @@ export class AudioBus { … }
350
626
  const effects = new AudioBus({ camera });
351
627
  ```
352
628
 
629
+ ### `baseGeometryOf`
630
+
631
+ `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.
632
+
633
+ ```ts
634
+ export function baseGeometryOf(mesh: Mesh): BufferGeometry { … }
635
+ ```
636
+
637
+ - **Use when:** collide or ray-test the authored geometry of a mesh whose render detail changes with distance
638
+
639
+ ```ts
640
+ const geometry = baseGeometryOf(mesh);
641
+ ```
642
+
643
+ ### `beginSpan`
644
+
645
+ `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.
646
+
647
+ ```ts
648
+ export function beginSpan(id: SpanId): void { … }
649
+ ```
650
+
651
+ - **Use when:** find out what inside the render phase is actually costing the frame · tell a shadow pass's traversal from the main pass's, with the residual computed · price an optimisation against a measured part of the phase rather than the whole of it
652
+ - **Constraints:** off by default and installed by `TN_FRAME_SPANS=1`; unset, every call site is one guarded return · the tree is closed against the frame budget's own render phase, so `TN_FRAME_SPANS` and `TN_FRAME_BUDGET` describe the same frames · measurement only: no span changes what is drawn, in what order, or with which renderer
653
+
654
+ ```ts
655
+ if (spansRequested()) setSpanRecorder(new SpanRecorder());
656
+ ```
657
+
353
658
  ### `Billboard3D`
354
659
 
355
660
  `class` — Face a game-owned object toward a perspective or orthographic camera.
@@ -415,6 +720,21 @@ import { boneLengths } from "@threenative/core";
415
720
  const baseline = boneLengths(character);
416
721
  ```
417
722
 
723
+ ### `bvhIntersectFirstHit`
724
+
725
+ `function` — Pack a selected static scene into TSL storage nodes for an upstream BVH ray query.
726
+
727
+ ```ts
728
+ bvhIntersectFirstHit = upstream.bvhIntersectFirstHit
729
+ ```
730
+
731
+ - **Use when:** trace thousands of scene rays inside a TSL kernel · build a contact-occlusion or visibility query over loaded meshes
732
+ - **Constraints:** call rebuild() after a scene transform or geometry change; the snapshot is static by default · rebuild() is an explicit CPU SAH build proportional to selected triangles; process() is a no-op, and the game pays upstream traversal per shader ray
733
+
734
+ ```ts
735
+ const bvh = ctx.add(new GPUSceneBVH(ctx.scene, { include: (object) => object.userData.traceable === true }));
736
+ ```
737
+
418
738
  ### `CameraShake`
419
739
 
420
740
  `class` — Produce a game-authored camera shake offset for a template-owned camera rig.
@@ -444,6 +764,21 @@ export class CanvasLayer { … }
444
764
  const hud = new CanvasLayer(ctx.viewport);
445
765
  ```
446
766
 
767
+ ### `captureMouse`
768
+
769
+ `function` — Lock the pointer to the game's surface: the capture every first-person mouse look needs. A browser grants capture only from a user gesture, so call it from a click or a pointerdown handler. A relative binding such as `look: { pointerRelative: true }` already requests capture on the first canvas click; this is the same request for a game that starts capture from another named gesture, and `ctx.input.captureMouse()` is the map's own way to ask.
770
+
771
+ ```ts
772
+ export function captureMouse(target: EventTarget): Promise<void> | undefined { … }
773
+ ```
774
+
775
+ - **Use when:** lock the mouse pointer so first-person mouse look keeps the cursor out of the way · stop the cursor leaving the window in the middle of a turn
776
+ - **Constraints:** the browser grants capture only from a user gesture and a refusal is reported, never swallowed · a relative binding requests capture on canvas click unless `captureOnClick: false` opts out
777
+
778
+ ```ts
779
+ canvas.addEventListener("click", () => captureMouse(canvas));
780
+ ```
781
+
447
782
  ### `clipBoneCoverage`
448
783
 
449
784
  `function` — Report which bones of a character a clip does not drive.
@@ -546,6 +881,21 @@ export class ComputeDrivenRegistry { … }
546
881
  const registry = new ComputeDrivenRegistry(); registry.add(cloth, ctx.renderer.raw);
547
882
  ```
548
883
 
884
+ ### `counterDeviceOf`
885
+
886
+ `function` — Count the frame's host-boundary crossings and the bytes it writes into GPU buffers, off unless `TN_FRAME_SPANS` asks for them. On the frame budget's own window as `counters`, so a crossing count and a millisecond split describe the same frames.
887
+
888
+ ```ts
889
+ export function counterDeviceOf(raw: unknown): unknown { … }
890
+ ```
891
+
892
+ - **Use when:** decide whether a CPU-bound frame is paying for the V8-to-host boundary · measure how many bytes a frame writes into GPU buffers, and how many commands it issues
893
+ - **Constraints:** counts command-encoder and queue methods only; `mapAsync` and the presentation path are named, not folded in · `gpuBytes` is `queue.writeBuffer` exactly, so it reconciles against a driver; texture uploads are not included · `jsAllocBytes` needs `performance.memory` and stays absent where the platform lacks it
894
+
895
+ ```ts
896
+ const counters = FrameCounters.install(counterDeviceOf(renderer.raw));
897
+ ```
898
+
549
899
  ### `createAssetLoader`
550
900
 
551
901
  `function` — Create the portable asset loader a scene also receives as `ctx.assets`.
@@ -587,7 +937,7 @@ const capture = game.runtime.pipelineCensus?.();
587
937
  export function createRandom(seed?: number): IRandom { … }
588
938
  ```
589
939
 
590
- - **Use when:** seed enemy patrol choices · reproduce the same procedural level in a playtest
940
+ - **Use when:** get a seeded deterministic random number generator — the same mulberry32 a game would hand-roll · seed enemy patrol choices · reproduce the same procedural level in a playtest
591
941
  - **Constraints:** use the returned source instead of Math.random for replayable behavior
592
942
  - **Supersedes (writing this fails `pnpm budgets`):** Math.random(
593
943
 
@@ -610,6 +960,39 @@ export function createReplayDriver( recording: Recording, target: EventTarget, p
610
960
  const driver = createReplayDriver(recording, ctx.renderer.domElement);
611
961
  ```
612
962
 
963
+ ### `Daylight`
964
+
965
+ `class` — An outdoor daylight rig: physical sky, one sun with open-world shadows that follow the eye, hemisphere fill, sky-coloured haze and the AgX tone curve. Every value is the game's.
966
+
967
+ ```ts
968
+ export class Daylight extends Group implements IComputeDriven { … }
969
+ ```
970
+
971
+ - **Use when:** daytime sky, sun and shadows for a large outdoor map · distant terrain should fade into the sky instead of a coloured wall · match a Blender look-dev scene's sun, sky and exposure in the game
972
+ - **Constraints:** every value is required; there is no default sun, sky, haze or exposure · `skySize` must keep the sky box's corners inside the camera's far plane · shadowExtents follow `VirtualShadowNode`: half-widths, finest first, strictly increasing
973
+ - **Overrides:** sky uniforms stay live on `daylight.sky`; the light and fill are `daylight.sun` and `daylight.fill`
974
+
975
+ ```ts
976
+ const daylight = new Daylight({ follow: ctx.camera, sunDirection, sunColor, sunIntensity: 4, shadowExtents: [24, 96, 320], sky: { turbidity: 3, rayleigh: 1.4, mieCoefficient: 0.004, mieDirectionalG: 0.8 }, fill: { sky, ground, intensity: 1.1 }, haze: { color: horizon, density: 0.0011 }, exposure: 2 ** -0.6, skySize: 1600 });
977
+ ctx.add(daylight);
978
+ ```
979
+
980
+ ### `debugFlag`
981
+
982
+ `function` — Read a debug switch from the URL, or from `TN_DEBUG_*` in the environment on a native launch.
983
+
984
+ ```ts
985
+ export function debugFlag(name: string): boolean { … }
986
+ ```
987
+
988
+ - **Use when:** read a debug toggle from the URL or an environment variable
989
+ - **Constraints:** a name in camelCase becomes UPPER_SNAKE: `debugFlag("freeCam")` reads `?freeCam` or `TN_DEBUG_FREE_CAM` · `0` and `false` are off, so a saved URL cannot turn a switch back on
990
+
991
+ ```ts
992
+ import { debugFlag } from "@threenative/core";
993
+ if (debugFlag("freeCam")) camera.flyMode = true;
994
+ ```
995
+
613
996
  ### `defineGame`
614
997
 
615
998
  `function` — Define the portable game entry shared by web and native.
@@ -625,6 +1008,36 @@ export function defineGame<TState extends Record<string, unknown>, TPhysics = un
625
1008
  const game = defineGame({ input: { zoom: { scroll: true, pinch: true } }, scenes: { Play }, start: "Play" });
626
1009
  ```
627
1010
 
1011
+ ### `describeSceneShape`
1012
+
1013
+ `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.
1014
+
1015
+ ```ts
1016
+ export function describeSceneShape( window: IFrameBudgetWindow, cull: IRenderCameraCullReport | undefined, ): ISceneShape | undefined { … }
1017
+ ```
1018
+
1019
+ - **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
1020
+ - **Constraints:** the rule is derived from the frame's own numbers; the display period comes from the host's presentation cap or the game's declared target, never a constant · no verdict without a measured GPU reading and a pass census — an absent measurement is not evidence · the record carries objects considered, draws per pass, triangles per draw and shadow-exempt casters, so the reader is not dependent on the ranking
1021
+
1022
+ ```ts
1023
+ defineGame({ display: { maxFps: 60 }, scenes: { Play } });
1024
+ ```
1025
+
1026
+ ### `describeSceneWarning`
1027
+
1028
+ `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.
1029
+
1030
+ ```ts
1031
+ export function describeSceneWarning(warning: ISceneWarning): string { … }
1032
+ ```
1033
+
1034
+ - **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
1035
+ - **Constraints:** the rule is derived from the frame's own numbers; the display period comes from the host's presentation cap or the game's declared target, never a constant · no verdict without a measured GPU reading and a pass census — an absent measurement is not evidence · the record carries objects considered, draws per pass, triangles per draw and shadow-exempt casters, so the reader is not dependent on the ranking
1036
+
1037
+ ```ts
1038
+ defineGame({ display: { maxFps: 60 }, scenes: { Play } });
1039
+ ```
1040
+
628
1041
  ### `directionalTransmittance`
629
1042
 
630
1043
  `function` — Approximate direct transmittance for a ray leaving the game surface.
@@ -655,6 +1068,36 @@ export function directionFromSolarPosition(elevation: number, azimuth: number):
655
1068
  const direction = directionFromSolarPosition(sun.elevation, sun.azimuth);
656
1069
  ```
657
1070
 
1071
+ ### `displayPeriodMs`
1072
+
1073
+ `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.
1074
+
1075
+ ```ts
1076
+ export function displayPeriodMs( declaredTargetFps: number | undefined, ): { … }
1077
+ ```
1078
+
1079
+ - **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
1080
+ - **Constraints:** the rule is derived from the frame's own numbers; the display period comes from the host's presentation cap or the game's declared target, never a constant · no verdict without a measured GPU reading and a pass census — an absent measurement is not evidence · the record carries objects considered, draws per pass, triangles per draw and shadow-exempt casters, so the reader is not dependent on the ranking
1081
+
1082
+ ```ts
1083
+ defineGame({ display: { maxFps: 60 }, scenes: { Play } });
1084
+ ```
1085
+
1086
+ ### `endSpan`
1087
+
1088
+ `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.
1089
+
1090
+ ```ts
1091
+ export function endSpan(id: SpanId): void { … }
1092
+ ```
1093
+
1094
+ - **Use when:** find out what inside the render phase is actually costing the frame · tell a shadow pass's traversal from the main pass's, with the residual computed · price an optimisation against a measured part of the phase rather than the whole of it
1095
+ - **Constraints:** off by default and installed by `TN_FRAME_SPANS=1`; unset, every call site is one guarded return · the tree is closed against the frame budget's own render phase, so `TN_FRAME_SPANS` and `TN_FRAME_BUDGET` describe the same frames · measurement only: no span changes what is drawn, in what order, or with which renderer
1096
+
1097
+ ```ts
1098
+ if (spansRequested()) setSpanRecorder(new SpanRecorder());
1099
+ ```
1100
+
658
1101
  ### `ensureVelocityOutput`
659
1102
 
660
1103
  `function` — Provision screen-space motion data for temporal nodes and keep per-instance history at the frame boundary.
@@ -676,6 +1119,39 @@ renderer.render(scene, camera);
676
1119
  tracker.commit(scene);
677
1120
  ```
678
1121
 
1122
+ ### `exposeDebug`
1123
+
1124
+ `function` — Publish one game object under `__THREENATIVE__.debug` for a capture script or the console.
1125
+
1126
+ ```ts
1127
+ export function exposeDebug(name: string, value: unknown): void { … }
1128
+ ```
1129
+
1130
+ - **Use when:** expose a game object to a capture script or the console in dev builds
1131
+ - **Constraints:** development builds only; a production build publishes nothing
1132
+
1133
+ ```ts
1134
+ import { exposeDebug } from "@threenative/core";
1135
+ exposeDebug("player", player);
1136
+ // then from the console: __THREENATIVE__.debug.player
1137
+ ```
1138
+
1139
+ ### `FlightModel`
1140
+
1141
+ `class` — Fly a fixed-wing aircraft with a real force balance instead of a steered velocity.
1142
+
1143
+ ```ts
1144
+ export class FlightModel<TState extends IFlightState = IFlightState> { … }
1145
+ ```
1146
+
1147
+ - **Use when:** fly an airplane with lift, drag, stall and control authority · launch an aircraft off a moving carrier deck · apply component damage or a loadout to an aircraft's performance
1148
+ - **Constraints:** every mass, area, power and inertia value comes from the game's airframe · damage, stores and configuration arrive as the game's own modifier sample
1149
+
1150
+ ```ts
1151
+ const model = new FlightModel({ airframe: sbd, state: aircraft, wind: seaWind });
1152
+ model.step(1 / 60, { turn: -1, pitch: 0.4 });
1153
+ ```
1154
+
679
1155
  ### `FluidField2D`
680
1156
 
681
1157
  `class` — Simulate a deterministic 2D velocity-and-dye field on the GPU while exposing its data to game-owned rendering.
@@ -694,21 +1170,97 @@ ctx.add(field);
694
1170
  field.splat({ x: 0.5, y: 0.5 }, { x: 0.2, y: 0 }, 1);
695
1171
  ```
696
1172
 
1173
+ ### `formatSceneWarning`
1174
+
1175
+ `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.
1176
+
1177
+ ```ts
1178
+ export function formatSceneWarning(warning: ISceneWarning): string { … }
1179
+ ```
1180
+
1181
+ - **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
1182
+ - **Constraints:** the rule is derived from the frame's own numbers; the display period comes from the host's presentation cap or the game's declared target, never a constant · no verdict without a measured GPU reading and a pass census — an absent measurement is not evidence · the record carries objects considered, draws per pass, triangles per draw and shadow-exempt casters, so the reader is not dependent on the ranking
1183
+
1184
+ ```ts
1185
+ defineGame({ display: { maxFps: 60 }, scenes: { Play } });
1186
+ ```
1187
+
1188
+ ### `formatSpansWindow`
1189
+
1190
+ `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.
1191
+
1192
+ ```ts
1193
+ export function formatSpansWindow(window: ISpanWindow): string { … }
1194
+ ```
1195
+
1196
+ - **Use when:** find out what inside the render phase is actually costing the frame · tell a shadow pass's traversal from the main pass's, with the residual computed · price an optimisation against a measured part of the phase rather than the whole of it
1197
+ - **Constraints:** off by default and installed by `TN_FRAME_SPANS=1`; unset, every call site is one guarded return · the tree is closed against the frame budget's own render phase, so `TN_FRAME_SPANS` and `TN_FRAME_BUDGET` describe the same frames · measurement only: no span changes what is drawn, in what order, or with which renderer
1198
+
1199
+ ```ts
1200
+ if (spansRequested()) setSpanRecorder(new SpanRecorder());
1201
+ ```
1202
+
1203
+ ### `formatValidationReport`
1204
+
1205
+ `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.
1206
+
1207
+ ```ts
1208
+ export function formatValidationReport(report: IValidationReport): string { … }
1209
+ ```
1210
+
1211
+ - **Use when:** prove a static freeze did not leave a stale transform on screen · gate a scene in CI against silent transform divergence
1212
+ - **Constraints:** off by default and expensive by construction — it does the work it is checking, twice · it throws on the first divergence rather than logging; a validation mode that continues is one nobody reads · it proves the frames it ran on and nothing else
1213
+
1214
+ ```ts
1215
+ if (renderListValidationRequested()) console.log(formatValidationReport(report));
1216
+ ```
1217
+
697
1218
  ### `FrameBudget`
698
1219
 
699
- `class` — Read where the frame's milliseconds went, per presented frame, on any platform.
1220
+ `class` — Read where the frame's milliseconds went, per presented frame, on any platform; each `TN_FRAME_BUDGET` window also carries the GPU time per resolved frame and the draw calls and triangles each render pass submitted.
700
1221
 
701
1222
  ```ts
702
1223
  export class FrameBudget { … }
703
1224
  ```
704
1225
 
705
- - **Use when:** find out why a game runs slowly on a phone · attribute a frame to present wait, simulation, three.js render, or overlay
706
- - **Constraints:** on by default and printed as TN_FRAME_BUDGET; defineGame({ frameBudget: false }) silences the marker, not the measurement
1226
+ - **Use when:** show an on-screen frame time meter with p50, p95 and p99 percentiles · find out why a game runs slowly on a phone · attribute a frame to present wait, simulation, three.js render, or overlay · tell whether the GPU is the frame's constraint from a per-frame series, not one lagged timestamp · split a frame's draw calls and triangles per render pass (main, shadow, reflection) · tell a shadow or reflection pass's cost from the main colour pass
1227
+ - **Constraints:** on by default and printed as TN_FRAME_BUDGET; defineGame({ frameBudget: false }) silences the marker, not the measurement · per-pass numbers are attributed to the innermost active render call, so nested shadow and reflection passes do not read as main · GPU is a mean/p50/p95/max series over resolved frames (`gpu`) with `gpuStale` counting frames that had no fresh reading; absent means no timestamps, never zero
707
1228
 
708
1229
  ```ts
709
1230
  defineGame({ frameBudget: { reportEvery: 120 }, scenes: { Play } });
710
1231
  ```
711
1232
 
1233
+ ### `FrameCounters`
1234
+
1235
+ `class` — Count the frame's host-boundary crossings and the bytes it writes into GPU buffers, off unless `TN_FRAME_SPANS` asks for them. On the frame budget's own window as `counters`, so a crossing count and a millisecond split describe the same frames.
1236
+
1237
+ ```ts
1238
+ export class FrameCounters { … }
1239
+ ```
1240
+
1241
+ - **Use when:** decide whether a CPU-bound frame is paying for the V8-to-host boundary · measure how many bytes a frame writes into GPU buffers, and how many commands it issues
1242
+ - **Constraints:** counts command-encoder and queue methods only; `mapAsync` and the presentation path are named, not folded in · `gpuBytes` is `queue.writeBuffer` exactly, so it reconciles against a driver; texture uploads are not included · `jsAllocBytes` needs `performance.memory` and stays absent where the platform lacks it
1243
+
1244
+ ```ts
1245
+ const counters = FrameCounters.install(counterDeviceOf(renderer.raw));
1246
+ ```
1247
+
1248
+ ### `gearClearance`
1249
+
1250
+ `function` — Fly a fixed-wing aircraft with a real force balance instead of a steered velocity.
1251
+
1252
+ ```ts
1253
+ export function gearClearance(state: IFlightState): number { … }
1254
+ ```
1255
+
1256
+ - **Use when:** fly an airplane with lift, drag, stall and control authority · launch an aircraft off a moving carrier deck · apply component damage or a loadout to an aircraft's performance
1257
+ - **Constraints:** every mass, area, power and inertia value comes from the game's airframe · damage, stores and configuration arrive as the game's own modifier sample
1258
+
1259
+ ```ts
1260
+ const model = new FlightModel({ airframe: sbd, state: aircraft, wind: seaWind });
1261
+ model.step(1 / 60, { turn: -1, pitch: 0.4 });
1262
+ ```
1263
+
712
1264
  ### `getPlatform`
713
1265
 
714
1266
  `function` — Read the host platform without reaching for browser globals.
@@ -786,6 +1338,37 @@ import { GroundSnap } from "@threenative/core";
786
1338
  const snap = new GroundSnap(character, { enabled: true });
787
1339
  ```
788
1340
 
1341
+ ### `InputMap`
1342
+
1343
+ `class` — The map a game reads input through: named actions, 2D vectors and scalar axes resolved from keyboard, gamepad, mouse, wheel, pinch and touch. `defineGame({ input })` builds one and hands it to the running game as `ctx.input`, so the usual route is a binding in the config and `ctx.input.axis("move")` in the update. Construct one directly to drive a menu, a replay or a test outside a running game.
1344
+
1345
+ ```ts
1346
+ export class InputMap { … }
1347
+ ```
1348
+
1349
+ - **Use when:** map WASD keys to a movement axis instead of reading the held key set in the update loop · read a jump, a fire or a reload as one named action bound to key, gamepad button and mouse button together · read mouse look, wheel zoom or a two-finger pinch as an axis the frame loop already ticks
1350
+ - **Constraints:** `buttons` is the gamepad and `mouseButtons` the mouse; `up`/`down`/`left`/`right` are the directions of `vector(name)`, not the keys that press it · scroll, pinch and pointer-relative sources are declared on the binding and read through `axis(name)`; a game adds no window listener of its own
1351
+
1352
+ ```ts
1353
+ const game = defineGame({ input: { move: { up: ["KeyW"], down: ["KeyS"], left: ["KeyA"], right: ["KeyD"] } }, scenes: { Play } });
1354
+ // inside the scene, per frame: ctx.input.axis("move") is 0 at rest and 1 at full tilt
1355
+ ```
1356
+
1357
+ ### `installSpanProbes`
1358
+
1359
+ `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.
1360
+
1361
+ ```ts
1362
+ export function installSpanProbes(target: ISpanProbeTarget, root: Object3D): () => void { … }
1363
+ ```
1364
+
1365
+ - **Use when:** measure which part of three's render path costs the frame · attach the span tree to a renderer a test or a tool constructed itself
1366
+ - **Constraints:** returns an uninstall that restores every wrapper, asserted by test · a renderer whose internals have moved loses that span rather than throwing, and it is absent from the report rather than zero · only the outermost `_projectObject` opens a span, because three's recurses per child
1367
+
1368
+ ```ts
1369
+ const uninstall = installSpanProbes(renderer.raw, scene);
1370
+ ```
1371
+
789
1372
  ### `InstancedBatch`
790
1373
 
791
1374
  `class` — Collapse many copies of one game-authored shape into a single draw, without counting them first. `new InstancedMesh(geometry, material, count)` needs the count before anything is placed, so a procedural builder ends up walking its layout twice or over-allocating. Place as you go and `build()` once; the shape, the surface and every transform stay the game's, and the built mesh is returned so instances can still be animated by the index `place` and `span` hand back.
@@ -804,6 +1387,21 @@ curbs.place({ position: [x, 0.08, z], rotation: [0, angle, 0], scale: [length, 0
804
1387
  curbs.build({ castShadow: true, name: "curbs", parent: ctx.scene });
805
1388
  ```
806
1389
 
1390
+ ### `invalidateStatic`
1391
+
1392
+ `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.
1393
+
1394
+ ```ts
1395
+ export function invalidateStatic(object: Object3D): number | undefined { … }
1396
+ ```
1397
+
1398
+ - **Use when:** cut the per-frame matrix work of terrain, buildings, props and other scenery that never moves · keep a frozen subtree correct when the game does move it after all
1399
+ - **Constraints:** staticness is authored, never guessed; no heuristic watches gameplay and decides for you · it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless · a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened
1400
+
1401
+ ```ts
1402
+ invalidateStatic(drawbridge);
1403
+ ```
1404
+
807
1405
  ### `isMobile`
808
1406
 
809
1407
  `function` — Read the host platform without reaching for browser globals.
@@ -834,6 +1432,21 @@ export function isNative(): boolean { … }
834
1432
  if (isMobile()) showTouchControls();
835
1433
  ```
836
1434
 
1435
+ ### `isStatic`
1436
+
1437
+ `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.
1438
+
1439
+ ```ts
1440
+ export function isStatic(root: Object3D): boolean { … }
1441
+ ```
1442
+
1443
+ - **Use when:** cut the per-frame matrix work of terrain, buildings, props and other scenery that never moves · keep a frozen subtree correct when the game does move it after all
1444
+ - **Constraints:** staticness is authored, never guessed; no heuristic watches gameplay and decides for you · it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless · a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened
1445
+
1446
+ ```ts
1447
+ invalidateStatic(drawbridge);
1448
+ ```
1449
+
837
1450
  ### `isTouchscreenAvailable`
838
1451
 
839
1452
  `function` — Read the host platform without reaching for browser globals.
@@ -880,6 +1493,53 @@ export async function loadAll<TIn, TOut>( items: readonly TIn[], load: (item: TI
880
1493
  const species = await loadAll(names, (name) => ctx.assets.model(`flora/${name}.glb`));
881
1494
  ```
882
1495
 
1496
+ ### `lodPixelScale`
1497
+
1498
+ `function` — The screen pixels one world unit covers at `depth` for this camera and viewport. Perspective divides the projected scale by the depth; orthographic has no depth term and uses the frustum height instead. This is the number a level of detail is chosen against: multiply a level's world-space error by it and you have the on-screen error a player can see, which is the comparison `updateModelLods` makes from the baked chain.
1499
+
1500
+ ```ts
1501
+ export function lodPixelScale(camera: Camera, viewportHeight: number, depth: number): number { … }
1502
+ ```
1503
+
1504
+ - **Use when:** pick a level of detail from an object's projected size in pixels on screen · know how many screen pixels a world-space error covers at a given distance
1505
+ - **Constraints:** a non-positive viewport height, a non-positive frustum height or an unprojectable camera throws · a non-positive depth has no projected scale and returns Infinity
1506
+
1507
+ ```ts
1508
+ const pixels = lodPixelScale(camera, canvas.clientHeight, mesh.position.distanceTo(camera.position));
1509
+ ```
1510
+
1511
+ ### `markStatic`
1512
+
1513
+ `function` — Freeze a subtree nobody moves: `markStatic(root)` composes its transforms once and stops the per-frame recompose. It is the call a game makes on scenery, terrain, buildings and props. The engine re-arms a root whose own transform the game changes; a write deeper inside a frozen subtree is announced with `invalidateStatic(object)`.
1514
+
1515
+ ```ts
1516
+ export function markStatic(root: Object3D): number { … }
1517
+ ```
1518
+
1519
+ - **Use when:** freeze a static mesh or subtree so its matrices are not recomputed every frame · stop the engine recomposing the transforms of props, terrain and buildings each frame
1520
+ - **Constraints:** staticness is authored, never guessed; no heuristic watches gameplay and decides for you · a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened
1521
+
1522
+ ```ts
1523
+ markStatic(island); invalidateStatic(drawbridge);
1524
+ ```
1525
+
1526
+ ### `MatrixWorldPass`
1527
+
1528
+ `class` — Walk the scene graph's world matrices each frame without recursing into a hidden subtree. On by default as `renderer.matrixWorld: "visible"`. three's `updateMatrixWorld` recurses into every child whatever its `visible` flag, so a hidden LOD body, a merged stand-in and a parked model cost a world-matrix multiply each while nothing under them can draw. This pass mirrors three exactly for every visible node and defers a hidden node's subtree until the frame it shows again. A class that overrides `updateMatrixWorld` (`SkinnedMesh`, `Camera`) runs its own, and a hidden node that holds bones is walked, so no skeleton or view matrix goes stale.
1529
+
1530
+ ```ts
1531
+ export class MatrixWorldPass { … }
1532
+ ```
1533
+
1534
+ - **Use when:** update the world matrices of the visible objects each frame instead of the whole scene · the per-frame world matrix walk is hot in a profile · stop multiplying matrices for hidden models, LOD levels and merged stand-ins · a game needs every node walked, exactly as three's own updateMatrixWorld does
1535
+ - **Constraints:** a game that reads a hidden object's matrixWorld directly must use getWorldPosition or updateWorldMatrix(true, false) first · `renderer.matrixWorld: "all"` visits every node; `TN_PROJECTION` reports the visited count either way
1536
+ - **Overrides:** renderer.matrixWorld: "all" runs three's full walk instead of the visible-only default
1537
+
1538
+ ```ts
1539
+ import { MatrixWorldPass } from "@threenative/core";
1540
+ const pass = new MatrixWorldPass(); // renderer.matrixWorld defaults to "visible"
1541
+ ```
1542
+
883
1543
  ### `measureThreePose`
884
1544
 
885
1545
  `function` — Measure a Three.js pose for grounded or attachment-aware checks.
@@ -895,22 +1555,42 @@ export function measureThreePose( object: Object3D, options: IMeasureThreePoseOp
895
1555
  const measurement = measureThreePose(model);
896
1556
  ```
897
1557
 
1558
+ ### `mergeByMaterial`
1559
+
1560
+ `function` — Bake a hierarchy's static meshes into one mesh per material, with their transforms baked in. already made; nothing here decides appearance tree: add them to root and remove the sources yourself, or both draw vertices are not its own to bake texture mapping; a missing normal is recomputed
1561
+
1562
+ ```ts
1563
+ export function mergeByMaterial(root: Object3D, options: IMergeByMaterialOptions): Mesh[] { … }
1564
+ ```
1565
+
1566
+ - **Use when:** collapse a building or ship of dozens of boxes into one draw call per material · consolidate the static parts of a group before adding it to the scene
1567
+ - **Constraints:** the material is the game's own instance and the split follows the materials the game · the meshes come back in root's local space and unparented, with the originals still in the · a skinned or instanced mesh, and a mesh with several materials, is left out — its · a group where only some meshes carry uv throws naming the label rather than losing the
1568
+ - **Overrides:** skip leaves one mesh out of its group and out of the result
1569
+
1570
+ ```ts
1571
+ const [hull, deck] = mergeByMaterial(ship, { label: "ship" });
1572
+ // a piece that must keep moving at run time:
1573
+ const [steady] = mergeByMaterial(ship, { label: "ship", skip: (mesh) => mesh.name === "radar" });
1574
+ ```
1575
+
898
1576
  ### `mergeParts`
899
1577
 
900
- `function` — Merge pieces a game authored out of primitives into one buffer, keeping each piece's own colour. `InstancedBatch` collapses many copies of one shape; this collapses many *different* shapes that never move relative to each other — a building, a ship, a character built from boxes. Two things go wrong every time and neither is about how any of it looks. `mergeGeometries` hands back `null` on mismatched inputs instead of throwing, and the usual mismatch is invisible: one `ExtrudeGeometry` is non-indexed while every other primitive is indexed, so the merge fails at the first piece and the scene never loads. And a merged buffer draws with one surface, so per-piece colour is gone unless every piece carries a flat `color` attribute written before the merge. Both are mechanical. Geometry, placement, colour and the surface it draws with all stay the game's.
1578
+ `function` — Merge pieces a game authored out of primitives into one buffer, keeping each piece's own look. `InstancedBatch` collapses many copies of one shape; this collapses many *different* shapes that never move relative to each other — a building, a ship, a character built from boxes, or the static parts of an imported glTF model. Two things go wrong every time and neither is about how any of it looks. `mergeGeometries` hands back `null` on mismatched inputs instead of throwing, and the usual mismatch is invisible: one `ExtrudeGeometry` is non-indexed while every other primitive is indexed, so the merge fails at the first piece and the scene never loads. And a merged buffer draws with one surface, so per-piece colour is gone unless every piece carries a flat `color` attribute written before the merge. Both are mechanical. By default every part is stripped to position and the normals are recomputed from the merged buffer; pass `preserve` to keep authored normals and texture UVs while baking each part's object transform. Geometry, placement, colour and the surface it draws with all stay the game's.
901
1579
 
902
1580
  ```ts
903
1581
  export function mergeParts( parts: Iterable<IMergePart>, options: IMergePartsOptions, ): BufferGeometry { … }
904
1582
  ```
905
1583
 
906
- - **Use when:** bake a building, ship or character authored out of primitives into one draw call · merge many small geometries and keep each piece's own colour · stop mergeGeometries from silently returning null on an extruded shape
907
- - **Constraints:** every part is de-indexed and stripped to position, so UVs and authored normals do not survive; normals are recomputed from the merged buffer · either every part names a color or none does, and a mix throws · an empty part list throws, and a merge three.js refuses throws naming the label
908
- - **Overrides:** color is per part and optional; without it no colour attribute is written and the surface alone decides
1584
+ - **Use when:** bake a building, ship or character authored out of primitives into one draw call · merge multiple static Three.js meshes into one mesh per material · consolidate the static parts of an imported glTF model into one buffer · preserve texture UV coordinates and authored normals while baking object transforms · merge many small geometries and keep each piece's own colour · stop mergeGeometries from silently returning null on an extruded shape
1585
+ - **Constraints:** every part is de-indexed; without preserve it is stripped to position and normals are recomputed from the merged buffer · preserve keeps the listed channels, transforming position and normal by the part's placement matrix while UV values are retained unchanged · a part that does not carry a listed preserve channel throws naming the label, the part and the channel · either every part names a color or none does, and a mix throws · an empty part list throws, and a merge three.js refuses throws naming the label
1586
+ - **Overrides:** color is per part and optional; without it no colour attribute is written and the surface alone decides · preserve is optional and empty by default: position-only merge with recomputed normals, exactly as before
909
1587
 
910
1588
  ```ts
911
1589
  const wall = new Mesh(mergeParts(pieces, { label: "gatehouse" }), stone);
912
1590
  // pieces are meshes, or { geometry, matrix, color } when the colour is per piece:
913
1591
  const banner = mergeParts([{ color: 0x8b2f1a, geometry: cloth, matrix: placement }], { label: "banner" });
1592
+ // keep a model's texture UVs and authored normals while baking its transforms:
1593
+ const hull = mergeParts(hullParts, { label: "hull", preserve: ["uv", "normal"] });
914
1594
  ```
915
1595
 
916
1596
  ### `normaliseToMetres`
@@ -929,6 +1609,20 @@ export function normaliseToMetres(object: Object3D, options: INormaliseToMetresO
929
1609
  normaliseToMetres(character, { metres: 1.8, axis: "height" });
930
1610
  ```
931
1611
 
1612
+ ### `onLaunchFailure`
1613
+
1614
+ `function` — Called for every launch failure the engine notices, with the message to show the player.
1615
+
1616
+ ```ts
1617
+ export function onLaunchFailure(listener: (failure: ILaunchFailure) => void): () => void { … }
1618
+ ```
1619
+
1620
+ - **Use when:** show the player why the game stopped loading instead of leaving the loading screen up · report a stalled launch or a lost GPU device in the game's own UI
1621
+
1622
+ ```ts
1623
+ const off = onLaunchFailure((failure) => shell.loading({ failure: failure.message }));
1624
+ ```
1625
+
932
1626
  ### `parseReplayRecording`
933
1627
 
934
1628
  `function` — Validate and parse a replay recording file.
@@ -1177,6 +1871,21 @@ import { reconcileMirroredClips } from "@threenative/core";
1177
1871
  if (reconcileMirroredClips(gltf.scene, gltf.animations)) console.info("clips were z-mirrored; repaired");
1178
1872
  ```
1179
1873
 
1874
+ ### `refreshStaticTransforms`
1875
+
1876
+ `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.
1877
+
1878
+ ```ts
1879
+ export function refreshStaticTransforms(): void { … }
1880
+ ```
1881
+
1882
+ - **Use when:** cut the per-frame matrix work of terrain, buildings, props and other scenery that never moves · keep a frozen subtree correct when the game does move it after all
1883
+ - **Constraints:** staticness is authored, never guessed; no heuristic watches gameplay and decides for you · it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless · a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened
1884
+
1885
+ ```ts
1886
+ invalidateStatic(drawbridge);
1887
+ ```
1888
+
1180
1889
  ### `RenderChain`
1181
1890
 
1182
1891
  `class` — Compose game-provided render nodes in a measured, fail-closed chain. Authored stages use an opaque id and anchor before or after a built-in or another supplied stage; the engine does not need to know the effect's visual vocabulary.
@@ -1192,6 +1901,36 @@ export class RenderChain { … }
1192
1901
  const chain = new RenderChain(renderer, { input: colour, stages, request: { stages: ["bloom"], tier: "auto" } });
1193
1902
  ```
1194
1903
 
1904
+ ### `renderListValidationRequested`
1905
+
1906
+ `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.
1907
+
1908
+ ```ts
1909
+ export function renderListValidationRequested(): boolean { … }
1910
+ ```
1911
+
1912
+ - **Use when:** prove a static freeze did not leave a stale transform on screen · gate a scene in CI against silent transform divergence
1913
+ - **Constraints:** off by default and expensive by construction — it does the work it is checking, twice · it throws on the first divergence rather than logging; a validation mode that continues is one nobody reads · it proves the frames it ran on and nothing else
1914
+
1915
+ ```ts
1916
+ if (renderListValidationRequested()) console.log(formatValidationReport(report));
1917
+ ```
1918
+
1919
+ ### `RenderListValidator`
1920
+
1921
+ `class` — 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.
1922
+
1923
+ ```ts
1924
+ export class RenderListValidator { … }
1925
+ ```
1926
+
1927
+ - **Use when:** prove a static freeze did not leave a stale transform on screen · gate a scene in CI against silent transform divergence
1928
+ - **Constraints:** off by default and expensive by construction — it does the work it is checking, twice · it throws on the first divergence rather than logging; a validation mode that continues is one nobody reads · it proves the frames it ran on and nothing else
1929
+
1930
+ ```ts
1931
+ if (renderListValidationRequested()) console.log(formatValidationReport(report));
1932
+ ```
1933
+
1195
1934
  ### `replay`
1196
1935
 
1197
1936
  `function` — Record or replay deterministic game input and state.
@@ -1207,6 +1946,35 @@ export function replay< TState extends Record<string, unknown> = Record<string,
1207
1946
  const driver = createReplayDriver(recording, ctx.renderer.domElement);
1208
1947
  ```
1209
1948
 
1949
+ ### `resetAudioCueLedger`
1950
+
1951
+ `function` — Forgets every recorded cue.
1952
+
1953
+ ```ts
1954
+ export function resetAudioCueLedger(): void { … }
1955
+ ```
1956
+
1957
+ - **Use when:** clear the recorded audio cue counts between tests so one test cannot read another's plays
1958
+
1959
+ ```ts
1960
+ resetAudioCueLedger();
1961
+ ```
1962
+
1963
+ ### `resetStaticTransforms`
1964
+
1965
+ `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.
1966
+
1967
+ ```ts
1968
+ export function resetStaticTransforms(): void { … }
1969
+ ```
1970
+
1971
+ - **Use when:** cut the per-frame matrix work of terrain, buildings, props and other scenery that never moves · keep a frozen subtree correct when the game does move it after all
1972
+ - **Constraints:** staticness is authored, never guessed; no heuristic watches gameplay and decides for you · it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless · a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened
1973
+
1974
+ ```ts
1975
+ invalidateStatic(drawbridge);
1976
+ ```
1977
+
1210
1978
  ### `resolveAtmosphereLutResolutions`
1211
1979
 
1212
1980
  `function` — Resolve the three LUT dimensions, allowing a game to trade startup cost for resolution.
@@ -1237,6 +2005,40 @@ export function resolveAtmosphereParameters( options: IAtmosphereParameters, ):
1237
2005
  const parameters = resolveAtmosphereParameters({ rayleigh, mie, ozone, planetRadius, atmosphereRadius });
1238
2006
  ```
1239
2007
 
2008
+ ### `resolveTargetFps`
2009
+
2010
+ `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.
2011
+
2012
+ ```ts
2013
+ export function resolveTargetFps( config: ITargetFpsConfig | undefined, platform: ITargetFpsPlatform | undefined, measuredRefreshHz?: number, ): ITargetFps { … }
2014
+ ```
2015
+
2016
+ - **Use when:** my game does frame-rate-dependent work and must not hardcode 60
2017
+ - **Constraints:** pass the measured display rate when you have one; without it the answer is the 60 fallback and says so
2018
+
2019
+ ```ts
2020
+ resolveTargetFps(config, getPlatform()).targetFps;
2021
+ ```
2022
+
2023
+ ### `RippleField`
2024
+
2025
+ `class` — Propagate a disturbance across a patch of water surface and let it fade. step is 1/60s or the CFL stability limit for the given resolution and speed, whichever is smaller
2026
+
2027
+ ```ts
2028
+ export class RippleField { … }
2029
+ ```
2030
+
2031
+ - **Use when:** make a splash or explosion ripple outward across water · show the sea reacting to a bomb, shell, or torpedo hitting it · leave a foam trail behind something moving through water · disturb a water surface the player can see respond · spread and drift foam on a water surface over time
2032
+ - **Constraints:** it draws nothing; the game supplies the mesh, the material and every colour · add its height to an analytic swell, never in place of one · the patch is finite and its rim absorbs; call recenter to keep it over the action · there is no obstacle mask, because a mask is only correct for a body that never moves
2033
+ - **Overrides:** speed, damping, foamHalfLife, current, step and maxSteps tune the solve; the default
2034
+
2035
+ ```ts
2036
+ const ripples = new RippleField({ resolution: 128, size: 400 });
2037
+ ripples.impulse(hit.x, hit.z, 6, -40, 0.5);
2038
+ ripples.advance(dt);
2039
+ const lift = ripples.heightAt(boat.x, boat.z);
2040
+ ```
2041
+
1240
2042
  ### `Scene`
1241
2043
 
1242
2044
  `class` — Implement a portable Godot-shaped game scene lifecycle.
@@ -1245,11 +2047,12 @@ const parameters = resolveAtmosphereParameters({ rayleigh, mie, ozone, planetRad
1245
2047
  export abstract class Scene< TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined, > { … }
1246
2048
  ```
1247
2049
 
1248
- - **Use when:** add a playable level or menu scene · move scene setup and per-frame gameplay out of the entry point
2050
+ - **Use when:** add a playable level or menu scene · move scene setup and per-frame gameplay out of the entry point · run scene work once per actual world draw, after the frame's last fixed update and before the projection packs
1249
2051
  - **Constraints:** scene code must stay portable across web and native
1250
2052
 
1251
2053
  ```ts
1252
2054
  class Play extends Scene { update(ctx, dt) {} }
2055
+ ctx.beforeRender(() => packBatches()); // cleared on scene change and stop, like ctx.afterPhysics
1253
2056
  ```
1254
2057
 
1255
2058
  ### `ScenePicker`
@@ -1267,6 +2070,21 @@ export class ScenePicker { … }
1267
2070
  const picker = new ScenePicker({ camera: ctx.camera, scene: ctx.scene, pointer: () => ctx.input.raw.pointer, viewport: ctx.viewport });
1268
2071
  ```
1269
2072
 
2073
+ ### `sceneWarning`
2074
+
2075
+ `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.
2076
+
2077
+ ```ts
2078
+ export function sceneWarning( window: IFrameBudgetWindow, shape: ISceneShape | undefined, declaredTargetFps: number | undefined, ): ISceneWarning | undefined { … }
2079
+ ```
2080
+
2081
+ - **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
2082
+ - **Constraints:** the rule is derived from the frame's own numbers; the display period comes from the host's presentation cap or the game's declared target, never a constant · no verdict without a measured GPU reading and a pass census — an absent measurement is not evidence · the record carries objects considered, draws per pass, triangles per draw and shadow-exempt casters, so the reader is not dependent on the ranking
2083
+
2084
+ ```ts
2085
+ defineGame({ display: { maxFps: 60 }, scenes: { Play } });
2086
+ ```
2087
+
1270
2088
  ### `Scheduler`
1271
2089
 
1272
2090
  `class` — Schedule delayed and repeating callbacks or tween numeric properties with game-owned cleanup.
@@ -1283,6 +2101,37 @@ const door = { y: 0 };
1283
2101
  await ctx.tween(door, { y: 2.4 }, 0.5, { ease: (t) => 1 - (1 - t) ** 3 });
1284
2102
  ```
1285
2103
 
2104
+ ### `setAttitude`
2105
+
2106
+ `function` — Fly a fixed-wing aircraft with a real force balance instead of a steered velocity.
2107
+
2108
+ ```ts
2109
+ export function setAttitude( state: IFlightState, heading = 0, pitch = 0, roll = 0, ): IFlightQuaternion { … }
2110
+ ```
2111
+
2112
+ - **Use when:** fly an airplane with lift, drag, stall and control authority · launch an aircraft off a moving carrier deck · apply component damage or a loadout to an aircraft's performance
2113
+ - **Constraints:** every mass, area, power and inertia value comes from the game's airframe · damage, stores and configuration arrive as the game's own modifier sample
2114
+
2115
+ ```ts
2116
+ const model = new FlightModel({ airframe: sbd, state: aircraft, wind: seaWind });
2117
+ model.step(1 / 60, { turn: -1, pitch: 0.4 });
2118
+ ```
2119
+
2120
+ ### `setSpanRecorder`
2121
+
2122
+ `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.
2123
+
2124
+ ```ts
2125
+ export function setSpanRecorder(next: SpanRecorder | undefined): void { … }
2126
+ ```
2127
+
2128
+ - **Use when:** find out what inside the render phase is actually costing the frame · tell a shadow pass's traversal from the main pass's, with the residual computed · price an optimisation against a measured part of the phase rather than the whole of it
2129
+ - **Constraints:** off by default and installed by `TN_FRAME_SPANS=1`; unset, every call site is one guarded return · the tree is closed against the frame budget's own render phase, so `TN_FRAME_SPANS` and `TN_FRAME_BUDGET` describe the same frames · measurement only: no span changes what is drawn, in what order, or with which renderer
2130
+
2131
+ ```ts
2132
+ if (spansRequested()) setSpanRecorder(new SpanRecorder());
2133
+ ```
2134
+
1286
2135
  ### `SkeletalMesh3D`
1287
2136
 
1288
2137
  `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.
@@ -1305,19 +2154,34 @@ body.add(character.root); character.play("idle");
1305
2154
  function update(dt: number): void { character.update(dt); }
1306
2155
  ```
1307
2156
 
1308
- ### `skeletonBones`
2157
+ ### `skeletonBones`
2158
+
2159
+ `function` — List the names of every bone in a character hierarchy.
2160
+
2161
+ ```ts
2162
+ export function skeletonBones(root: Object3D): readonly string[] { … }
2163
+ ```
2164
+
2165
+ - **Use when:** inspect the available bones before attaching a game-owned object · debug a missing skeleton bone name
2166
+
2167
+ ```ts
2168
+ import { skeletonBones } from "@threenative/core";
2169
+ const bones = skeletonBones(character);
2170
+ ```
2171
+
2172
+ ### `snapRefreshRate`
1309
2173
 
1310
- `function` — List the names of every bone in a character hierarchy.
2174
+ `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.
1311
2175
 
1312
2176
  ```ts
1313
- export function skeletonBones(root: Object3D): readonly string[] { … }
2177
+ export function snapRefreshRate(refreshHz: number): number { … }
1314
2178
  ```
1315
2179
 
1316
- - **Use when:** inspect the available bones before attaching a game-owned object · debug a missing skeleton bone name
2180
+ - **Use when:** my game does frame-rate-dependent work and must not hardcode 60
2181
+ - **Constraints:** pass the measured display rate when you have one; without it the answer is the 60 fallback and says so
1317
2182
 
1318
2183
  ```ts
1319
- import { skeletonBones } from "@threenative/core";
1320
- const bones = skeletonBones(character);
2184
+ resolveTargetFps(config, getPlatform()).targetFps;
1321
2185
  ```
1322
2186
 
1323
2187
  ### `SoftBody3D`
@@ -1381,6 +2245,66 @@ export function solarPositionAt( date: Date | string, latitude: number, longitud
1381
2245
  const sun = solarPositionAt(new Date(), 49.28, -123.12);
1382
2246
  ```
1383
2247
 
2248
+ ### `spanNow`
2249
+
2250
+ `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.
2251
+
2252
+ ```ts
2253
+ export function spanNow(): number { … }
2254
+ ```
2255
+
2256
+ - **Use when:** find out what inside the render phase is actually costing the frame · tell a shadow pass's traversal from the main pass's, with the residual computed · price an optimisation against a measured part of the phase rather than the whole of it
2257
+ - **Constraints:** off by default and installed by `TN_FRAME_SPANS=1`; unset, every call site is one guarded return · the tree is closed against the frame budget's own render phase, so `TN_FRAME_SPANS` and `TN_FRAME_BUDGET` describe the same frames · measurement only: no span changes what is drawn, in what order, or with which renderer
2258
+
2259
+ ```ts
2260
+ if (spansRequested()) setSpanRecorder(new SpanRecorder());
2261
+ ```
2262
+
2263
+ ### `spanRecorder`
2264
+
2265
+ `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.
2266
+
2267
+ ```ts
2268
+ export function spanRecorder(): SpanRecorder | undefined { … }
2269
+ ```
2270
+
2271
+ - **Use when:** find out what inside the render phase is actually costing the frame · tell a shadow pass's traversal from the main pass's, with the residual computed · price an optimisation against a measured part of the phase rather than the whole of it
2272
+ - **Constraints:** off by default and installed by `TN_FRAME_SPANS=1`; unset, every call site is one guarded return · the tree is closed against the frame budget's own render phase, so `TN_FRAME_SPANS` and `TN_FRAME_BUDGET` describe the same frames · measurement only: no span changes what is drawn, in what order, or with which renderer
2273
+
2274
+ ```ts
2275
+ if (spansRequested()) setSpanRecorder(new SpanRecorder());
2276
+ ```
2277
+
2278
+ ### `SpanRecorder`
2279
+
2280
+ `class` — 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.
2281
+
2282
+ ```ts
2283
+ export class SpanRecorder { … }
2284
+ ```
2285
+
2286
+ - **Use when:** find out what inside the render phase is actually costing the frame · tell a shadow pass's traversal from the main pass's, with the residual computed · price an optimisation against a measured part of the phase rather than the whole of it
2287
+ - **Constraints:** off by default and installed by `TN_FRAME_SPANS=1`; unset, every call site is one guarded return · the tree is closed against the frame budget's own render phase, so `TN_FRAME_SPANS` and `TN_FRAME_BUDGET` describe the same frames · measurement only: no span changes what is drawn, in what order, or with which renderer
2288
+
2289
+ ```ts
2290
+ if (spansRequested()) setSpanRecorder(new SpanRecorder());
2291
+ ```
2292
+
2293
+ ### `spansRequested`
2294
+
2295
+ `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.
2296
+
2297
+ ```ts
2298
+ export function spansRequested(): boolean { … }
2299
+ ```
2300
+
2301
+ - **Use when:** find out what inside the render phase is actually costing the frame · tell a shadow pass's traversal from the main pass's, with the residual computed · price an optimisation against a measured part of the phase rather than the whole of it
2302
+ - **Constraints:** off by default and installed by `TN_FRAME_SPANS=1`; unset, every call site is one guarded return · the tree is closed against the frame budget's own render phase, so `TN_FRAME_SPANS` and `TN_FRAME_BUDGET` describe the same frames · measurement only: no span changes what is drawn, in what order, or with which renderer
2303
+
2304
+ ```ts
2305
+ if (spansRequested()) setSpanRecorder(new SpanRecorder());
2306
+ ```
2307
+
1384
2308
  ### `SpectralOcean`
1385
2309
 
1386
2310
  `class` — Simulate a spectral ocean — cascaded wave spectra inverse-transformed on the GPU each frame.
@@ -1411,6 +2335,21 @@ export class SpriteAnimator3D { … }
1411
2335
  const animator = new SpriteAnimator3D({ texture: atlas, frames, mode: "pingPong" });
1412
2336
  ```
1413
2337
 
2338
+ ### `staticTransformCensus`
2339
+
2340
+ `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.
2341
+
2342
+ ```ts
2343
+ export function staticTransformCensus(): IStaticTransformCensus { … }
2344
+ ```
2345
+
2346
+ - **Use when:** cut the per-frame matrix work of terrain, buildings, props and other scenery that never moves · keep a frozen subtree correct when the game does move it after all
2347
+ - **Constraints:** staticness is authored, never guessed; no heuristic watches gameplay and decides for you · it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless · a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened
2348
+
2349
+ ```ts
2350
+ invalidateStatic(drawbridge);
2351
+ ```
2352
+
1414
2353
  ### `TracerPool3D`
1415
2354
 
1416
2355
  `class` — Pool travelling bullet-streak meshes for hitscan shots.
@@ -1427,6 +2366,21 @@ const tracers = new TracerPool3D(ctx.scene, tracerOptions);
1427
2366
  tracers.spawn(muzzle, shotDirection, hit.distance);
1428
2367
  ```
1429
2368
 
2369
+ ### `unmarkStatic`
2370
+
2371
+ `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.
2372
+
2373
+ ```ts
2374
+ export function unmarkStatic(root: Object3D): void { … }
2375
+ ```
2376
+
2377
+ - **Use when:** cut the per-frame matrix work of terrain, buildings, props and other scenery that never moves · keep a frozen subtree correct when the game does move it after all
2378
+ - **Constraints:** staticness is authored, never guessed; no heuristic watches gameplay and decides for you · it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless · a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened
2379
+
2380
+ ```ts
2381
+ invalidateStatic(drawbridge);
2382
+ ```
2383
+
1430
2384
  ### `updateAtmosphereParameters`
1431
2385
 
1432
2386
  `function` — Apply a partial game-owned atmosphere change while preserving validation.
@@ -1456,6 +2410,39 @@ export function updateClusteredMeshes( root: { … }
1456
2410
  updateClusteredMeshes(stagedRoot, myCamera, ctx.renderer.domElement.height);
1457
2411
  ```
1458
2412
 
2413
+ ### `updateModelLods`
2414
+
2415
+ `function` — Draw a model at the detail its projected geometric error earns, from a chain the asset cook baked. **This is engine-owned, and a game does not call it.** `assets.lod: {}` opts in — the default-on front door opens after qualification — the `model` pass bakes `TN_discrete_lod` into eligible models, the loader registers the reader, and the engine runs the selection every frame before it renders. Each frame the mesh picks the cheapest baked level whose measured error projects to fewer than the resolved pixel budget, taking the camera's own projection, zoom, viewport and a conservative nearest depth into account. Refinement is immediate; coarsening waits for the resolved hysteresis. A mesh with no baked chain draws its full geometry.
2416
+
2417
+ ```ts
2418
+ export function updateModelLods( root: { … }
2419
+ ```
2420
+
2421
+ - **Use when:** draw a vehicle or hull built from many small meshes at distance without its full triangles · stop a distant model from costing its authored mesh count and triangle count · one source model, right detail by default, no hand-authored LOD files
2422
+ - **Constraints:** the chain is baked by the asset cook; there is no runtime generation and no runtime flag · `assets.lod: false` opts out globally and `assets.lod.overrides` per asset, with no runtime controller installed · only static indexed triangles are eligible; skinned, morphed, alpha-blended or authored-LOD meshes keep full detail · the real gate is measured benefit: a level must save at least `minSaving` (20% default) of its predecessor, and a mesh that cannot is skipped, not forced
2423
+ - **Overrides:** `assets.lod.generation.maxLevels`, `.minTriangles`, `.minTrianglesScope`, `.minSaving` and `.errorTargets` move the bake's ceiling, pre-filter, its scope, its saving rule and its error ladder; `assets.lod.runtime.maxPixelError` and `.hysteresis` move the runtime budget and coarsen band; all by project, preset or asset
2424
+
2425
+ ```ts
2426
+ // Nothing to call: the loader returns a mesh with the chain and the engine selects every frame.
2427
+ const hull = await ctx.assets.model("hull.glb");
2428
+ ctx.scene.add(hull.scene);
2429
+ ```
2430
+
2431
+ ### `validateWorldMatrices`
2432
+
2433
+ `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.
2434
+
2435
+ ```ts
2436
+ export function validateWorldMatrices(root: Object3D): { … }
2437
+ ```
2438
+
2439
+ - **Use when:** prove a static freeze did not leave a stale transform on screen · gate a scene in CI against silent transform divergence
2440
+ - **Constraints:** off by default and expensive by construction — it does the work it is checking, twice · it throws on the first divergence rather than logging; a validation mode that continues is one nobody reads · it proves the frames it ran on and nothing else
2441
+
2442
+ ```ts
2443
+ if (renderListValidationRequested()) console.log(formatValidationReport(report));
2444
+ ```
2445
+
1459
2446
  ### `velocityTexture`
1460
2447
 
1461
2448
  `function` — Provision screen-space motion data for temporal nodes and keep per-instance history at the frame boundary.
@@ -1507,7 +2494,7 @@ export class VirtualShadowNode extends ShadowBaseNode { … }
1507
2494
  ```
1508
2495
 
1509
2496
  - **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
1510
- - **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 · call `trackCaster(object)` for movers; it enables layer `VIRTUAL_SHADOW_MOVER_LAYER` on the object and its descendants, tracking or untracking refreshes cached levels once, and subsequent mover movement refreshes only when a window moves
2497
+ - **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 · call `trackCaster(object)` for movers; it enables layer `VIRTUAL_SHADOW_MOVER_LAYER` on the object and its descendants, tracking or untracking refreshes cached levels once, and subsequent mover movement refreshes only when a window moves · 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
1511
2498
  - **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
1512
2499
 
1513
2500
  ```ts
@@ -1538,28 +2525,30 @@ await warmUpScene(renderer, scene, camera, { onProgress: (p) => setLoading(p) })
1538
2525
  export class WaterSurface3D { … }
1539
2526
  ```
1540
2527
 
1541
- - **Use when:** reflect the sky and the shoreline in a lake, pond or river · see the bed through the water and have the shallows fade at the shore · know how deep the water is under a pixel without a second render pass · stop a water surface repeating in visible bands or stripes
1542
- - **Constraints:** it draws nothing; the game supplies the mesh, the material and every colour · the material must be transparent so the frame beneath it is already drawn · thickness is metres, saturating at maxThickness; sky behind the surface reads deep · one reflection is a second draw of the world, so resolutionScale is the whole cost · the mirror plane is level, from level alone; do not parent target to a scaled mesh
2528
+ - **Use when:** reflect the sky and the shoreline in a lake, pond or river · see the bed through the water and have the shallows fade at the shore · know how deep the water is under a pixel without a second render pass · stop a water surface repeating in visible bands or stripes · keep a crowd of small actors out of the water's reflection so the frame can afford it · stop the water reflection redrawing the whole world every frame
2529
+ - **Constraints:** it draws nothing; the game supplies the mesh, the material and every colour · the material must be transparent so the frame beneath it is already drawn · thickness is metres, saturating at maxThickness; sky behind the surface reads deep · one reflection is a second draw of the world; resolutionScale is its pixels only · on a crowded scene the mirrored pass is draw-bound: name reflection.layers or pay twice · reflection.refreshInterval is in presented frames; 1 is every frame, and the default · the mirror plane is level, from level alone; do not parent target to a scaled mesh
1543
2530
 
1544
2531
  ```ts
1545
- const surface = new WaterSurface3D({ level: 0, maxThickness: 3, reflection: { resolutionScale: 0.5 } });
2532
+ const REFLECTED = 1; // the layer the big silhouettes sit on
2533
+ const surface = new WaterSurface3D({ level: 0, maxThickness: 3, reflection: { resolutionScale: 0.5, layers: (1 << 0) | (1 << REFLECTED) } });
1546
2534
  material.colorNode = mix(surface.refractionAt(offset), surface.reflectionAt(offset), fresnel);
1547
2535
  ```
1548
2536
 
1549
2537
  ### `WaveField`
1550
2538
 
1551
- `class` — Evaluate analytic waves on CPU and displace game-owned vertices with the matching TSL graph.
2539
+ `class` — Evaluate analytic waves on CPU and displace game-owned vertices with the matching TSL graph. wanted, and the warp jacobian, every slope and both allocations are skipped
1552
2540
 
1553
2541
  ```ts
1554
2542
  export class WaveField { … }
1555
2543
  ```
1556
2544
 
1557
2545
  - **Use when:** float a boat on waves · make water move · find the water surface height at a point
1558
- - **Constraints:** supply every wave amplitude, wavelength, direction, speed and warp value · call setTime for the default graph clock when the game advances its own time
2546
+ - **Constraints:** supply every wave amplitude, wavelength, direction, speed and warp value · call setTime for the default graph clock when the game advances its own time · sample allocates a result and a normal vector; ask heightAt when only the height is
1559
2547
 
1560
2548
  ```ts
1561
2549
  const field = new WaveField({ waves });
1562
2550
  const { height, normal } = field.sample(x, z, elapsed);
2551
+ const lift = field.heightAt(x, z, elapsed);
1563
2552
  ```
1564
2553
 
1565
2554
  ### `withVelocityContext`
@@ -1807,8 +2796,8 @@ publishHitRegions({ bridge });
1807
2796
  export function publishUiState<T>( bridge: IUiBridge, store: IPublishableStore<T>, options: IPublishOptions = { … }
1808
2797
  ```
1809
2798
 
1810
- - **Use when:** show score or health in a UI rendered over the game surface · keep a HUD in step with the game without re-rendering on the loop · publish game state to a HUD in another realm · keep a web and native UI mirror on the same throttled state stream
1811
- - **Constraints:** publishes at the store's throttled cadence, and not at all with no UI listening
2799
+ - **Use when:** show score or health in a UI rendered over the game surface · keep a HUD in step with the game without re-rendering on the loop · publish game state to a HUD in another realm · keep a web and native UI mirror on the same coalesced state stream
2800
+ - **Constraints:** publishes once per rendered frame unless stateFlushMs selects a slower interval, and not at all with no UI listening
1812
2801
 
1813
2802
  ```ts
1814
2803
  publishUiState(bridge, game.state);
@@ -1846,6 +2835,21 @@ const mirror = subscribeUiState(bridge);
1846
2835
 
1847
2836
  ## `@threenative/core/world`
1848
2837
 
2838
+ ### `cellPlacements`
2839
+
2840
+ `function` — Borrow the run's placement records as a live view over the placement buffer.
2841
+
2842
+ ```ts
2843
+ export function cellPlacements(placements: ArrayBuffer, run: IWorldRun): Float32Array { … }
2844
+ ```
2845
+
2846
+ - **Use when:** feed one cell's instance transforms into a batch without copying
2847
+ - **Constraints:** the returned view aliases the caller's buffer; writing to it mutates the source
2848
+
2849
+ ```ts
2850
+ const records = cellPlacements(buffer, { asset: "tree", offset: 0, count: 120 });
2851
+ ```
2852
+
1849
2853
  ### `getWorldCapabilities`
1850
2854
 
1851
2855
  `function` — Resolve the active world-generation path from host capability facts. The function accepts the adapter facts instead of reaching through a renderer-specific global, so browser and native hosts can report the same object. Missing limits are not treated as infinite: a host must either provide a valid GPU limit report or explicitly choose CPU fallback. GPU generation remains unavailable until a GPU readback can own the canonical field; a host adapter report therefore never upgrades a CPU fallback into a GPU generation claim.
@@ -1878,6 +2882,53 @@ export class Heightfield extends Group implements IComputeDriven { … }
1878
2882
  const field = Heightfield.fromSampler({ rows: 65, columns: 65, width: 64, depth: 64, origin: { x: 0, z: 0 }, sampleHeight: terrainHeight });
1879
2883
  ```
1880
2884
 
2885
+ ### `heightSamplerFromHeightmap`
2886
+
2887
+ `function` — Build a game-usable `sampleHeight` from a raw v1 heightmap. The returned function interpolates bilinearly in world units and clamps to the map edges, so it plugs straight into `Heightfield.fromSampler` and `TerrainTiles`. Height is `heightMin + v / 65535 * (heightMax - heightMin)` at vertex `(column, row)`.
2888
+
2889
+ ```ts
2890
+ export function heightSamplerFromHeightmap( terrain: IWorldTerrain, extent: IWorldExtent, data: Uint16Array, ): (x: number, z: number) => number { … }
2891
+ ```
2892
+
2893
+ - **Use when:** turn an exported raw heightmap into terrain collision and rendering · query ground height from a Blender-authored world package
2894
+ - **Constraints:** the sampler reads the game's data; the framework never selects a terrain shape
2895
+
2896
+ ```ts
2897
+ const sampleHeight = heightSamplerFromHeightmap(terrain, extent, await loadWorldHeightmap(url));
2898
+ ```
2899
+
2900
+ ### `loadTerrainSplat`
2901
+
2902
+ `function` — The splat terrain surface a world package describes, for `WorldCells.load({ surface })`. Layers blend over a base by mask channels read as linear data (the masks ship raw, beside the heightmap, so no cook moves a blend threshold), with noise-broken edges and macro brightness variation. Texture sets tile in world metres on the package's ground plane (x, -z: a Z-up authoring tool's x and y), cliffs can be triplanar, and the base plus any layer that asks carries a normal map. Nothing here is a look choice: textures, tiles, tints, thresholds and noise scales all come from the package's table, which the game authors once and its DCC shares.
2903
+
2904
+ ```ts
2905
+ export async function loadTerrainSplat(options: ILoadTerrainSplatOptions): Promise<Material> { … }
2906
+ ```
2907
+
2908
+ - **Use when:** terrain textured by splat masks exported from Blender with the world package · the game's terrain should match the DCC's terrain material without a second copy
2909
+ - **Constraints:** the package's world.json must carry `terrain.layers.table` and `terrain.layers.splat`, written by the `export_terrain_layers.py` recipe · WebGPU allows 16 sampled textures per stage: planes + diffuse maps + normal maps must fit
2910
+ - **Overrides:** every value comes from the package's table; the returned material is the game's to adjust
2911
+
2912
+ ```ts
2913
+ const surface = await loadTerrainSplat({ assets: ctx.assets, url: "world/world.json" });
2914
+ const world = await WorldCells.load({ assets: ctx.assets, url: "world/world.json", surface, follow, ring: 2 });
2915
+ ```
2916
+
2917
+ ### `loadWorldHeightmap`
2918
+
2919
+ `function` — Fetch a raw little-endian uint16 heightmap and expose it as samples.
2920
+
2921
+ ```ts
2922
+ export async function loadWorldHeightmap(url: string): Promise<Uint16Array> { … }
2923
+ ```
2924
+
2925
+ - **Use when:** load a world package's heightmap once before building terrain
2926
+ - **Constraints:** a non-OK response throws; bytes are byte-swapped only on a big-endian host
2927
+
2928
+ ```ts
2929
+ const data = await loadWorldHeightmap("/world/terrain/heightmap.u16");
2930
+ ```
2931
+
1881
2932
  ### `TerrainTiles`
1882
2933
 
1883
2934
  `class` — Stream a bounded square of game-authored heightfields and keep their render and physics units together. The class composes ordinary THREE.LOD objects and leaves frustum/projection culling to the renderer's existing scene path.
@@ -1887,13 +2938,150 @@ export class TerrainTiles extends Object3D implements IComputeDriven { … }
1887
2938
  ```
1888
2939
 
1889
2940
  - **Use when:** stream terrain without cracks · keep generated terrain resident around a moving player · put a generated terrain tile into a game-owned physics world
1890
- - **Constraints:** sampleHeight and surface are required game choices; no landform or surface preset is installed · residentTileBudget and residentByteBudget are hard caps; a tile that cannot fit throws
1891
- - **Overrides:** tileSize, tileResolution, lodFactors, lodDistances, skirtDepth, streamRadius, and budgets
2941
+ - **Constraints:** sampleHeight and surface are required game choices; no landform or surface preset is installed · residentTileBudget and residentByteBudget are hard caps; a tile that cannot fit throws · seam gap, LOD pop and the rendered-vertex finiteness scan are measurements that are off by default; TN_TERRAIN_VALIDATE=1, ?tnTerrainValidate=1 or validate: true runs them, and maxSeamGap, maxVisualSeamGap and maxLodPop report undefined while they are off
2942
+ - **Overrides:** tileSize, tileResolution, lodFactors, lodDistances, skirtDepth, streamRadius, colliderRadius, validate, and budgets
1892
2943
 
1893
2944
  ```ts
1894
2945
  const tiles = new TerrainTiles({ sampleHeight, surface: gameSurface(), tileSize: 256, tileResolution: 129, residentTileBudget: 25, residentByteBudget: 32_000_000 });
1895
2946
  ```
1896
2947
 
2948
+ ### `terrainValidationRequested`
2949
+
2950
+ `function` — Whether `TN_TERRAIN_VALIDATE` asks for terrain validation on this launch.
2951
+
2952
+ ```ts
2953
+ export function terrainValidationRequested(): boolean { … }
2954
+ ```
2955
+
2956
+ - **Use when:** turn terrain's per-frame seam, LOD pop and vertex checks on for one run · assert the terrain geometry a game streams before it ships
2957
+ - **Constraints:** off by default: it is the work it checks, every frame
2958
+
2959
+ ```ts
2960
+ // Reads its own the way `renderListValidationRequested` does: a native launch sets the
2961
+ // environment variable, a browser asks with the query string, a test or harness sets the
2962
+ // global. `0` and `false` are off, so a saved URL that enabled it still says "off".
2963
+ const tiles = new TerrainTiles({ ...options, validate: terrainValidationRequested() });
2964
+ ```
2965
+
2966
+ ### `validateWorldPackage`
2967
+
2968
+ `function` — Validate a `world.json` manifest against the v1 contract. Never throws on garbage input: a non-object manifest is `WORLD_MALFORMED`. Every problem is collected, so an exporter sees the complete list at once.
2969
+
2970
+ ```ts
2971
+ export function validateWorldPackage( manifest: unknown, options: IWorldPackageValidationOptions, ): { … }
2972
+ ```
2973
+
2974
+ - **Use when:** check a Blender-exported world package before the runtime attaches anything · report why a world package cannot be streamed
2975
+ - **Constraints:** validation only checks structure and ranges; it never fetches the heightmap or GLBs
2976
+
2977
+ ```ts
2978
+ const { ok, errors } = validateWorldPackage(json, { placementsByteLength: buffer.byteLength });
2979
+ ```
2980
+
2981
+ ### `WorldCells`
2982
+
2983
+ `class` — Stream a Blender-authored world package by cell and keep it resident around a followed point. The class composes `TerrainTiles` for the package's heightmap, builds one `InstancedBatch` per resident cell asset run, distance level and mesh part, and loads hand-placed chunk GLBs through `loadAll` + `addInSlices`. Ring residency, per-asset `maxDistance` filtering, the per-asset `lods` levels, hard budgets and generation-tokened cancellation all live here; every geometry, material and surface still comes from the package's GLBs and the game. An asset is drawn per part, not per model: a GLB with several primitives is one `InstancedBatch` each, and a scattered part whose own material is transparent draws as an alpha cutout unless the game asks for blending, because an `InstancedMesh` cannot sort its instances. An asset whose package entry names no `lods` is drawn at the levels its own model carries a baked AutoLOD chain for: the levels an instanced draw cannot reach by itself, switched at the distance their error projects over the `autoLod` viewport. Authored `lods` win; a chain is only a fallback.
2984
+
2985
+ ```ts
2986
+ export class WorldCells extends Group implements IComputeDriven { … }
2987
+ ```
2988
+
2989
+ - **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
2990
+ - **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 authored `lods` never consults it · `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
2991
+ - **Overrides:** 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
2992
+
2993
+ ```ts
2994
+ const world = await WorldCells.load({ url: "/world/world.json", surface, follow, ring: 1, budgets: { residentCells: 25, instances: 20000, bytes: 8000000 } });
2995
+ scene.add(world);
2996
+ world.update();
2997
+ ```
2998
+
2999
+ ## `@threenative/metahuman`
3000
+
3001
+ ### `assertAssetPath`
3002
+
3003
+ `function` — Keeps a caller-supplied asset path inside the asset directory.
3004
+
3005
+ ```ts
3006
+ export function assertAssetPath(path: string): string { … }
3007
+ ```
3008
+
3009
+ - **Use when:** reject a MetaHuman asset path that would read outside the game's asset root
3010
+ - **Constraints:** absolute paths, Windows drive letters, backslashes and any `..` segment throw MetaHumanAssetError with TN_MH_PATH_ESCAPE before the path is joined onto a root
3011
+ - **Requires:** npm i @threenative/metahuman
3012
+
3013
+ ```ts
3014
+ assertAssetPath("metahuman/specimen.glb");
3015
+ ```
3016
+
3017
+ ### `loadMetaHuman`
3018
+
3019
+ `function` — Load a prepared MetaHuman head and drive its expression from the browser's WASM evaluator: declared faceboard controls in, joint deltas and morph weights out, applied to an ordinary Three.js object graph. two characters never write each other's face and nothing is disposed that `ctx.assets` still owns switch re-evaluates the current controls before the replacement mesh is shown `dispose()` throw, each with a stable `code`; nothing is clamped or coerced `diagnostics().backend` reads "native"; the game code does not change
3020
+
3021
+ ```ts
3022
+ loadMetaHuman = (options: ILoadMetaHumanOptions): Promise<IMetaHuman> => createMetaHuman( { … }
3023
+ ```
3024
+
3025
+ - **Use when:** put a MetaHuman head in a browser game without an Unreal import or a baked clip
3026
+ - **Constraints:** the model is loaded through the game's own asset loader and cloned per instance, so · the rig's own GUI-to-raw mapping runs; the adapter never re-derives it, and a LOD · an undeclared control, an out-of-domain value, an undeclared LOD and any call after · in a native host that installed the MetaHuman resident the C++ evaluator runs and
3027
+ - **Requires:** npm i @threenative/metahuman
3028
+
3029
+ ```ts
3030
+ const human = await loadMetaHuman({ assets: ctx.assets, model: "metahuman/head.glb",
3031
+ dna: "metahuman/head.dna", bindings: "metahuman/bindings.json" });
3032
+ human.setControls({ jawOpen: 0.4 });
3033
+ // in the scene update, after any body animation
3034
+ human.update();
3035
+ ```
3036
+
3037
+ ### `MetaHumanAssetError`
3038
+
3039
+ `class` — The rejection every check in this package raises, carrying a stable machine-readable code.
3040
+
3041
+ ```ts
3042
+ export class MetaHumanAssetError extends Error { … }
3043
+ ```
3044
+
3045
+ - **Use when:** branch on why a MetaHuman asset or evaluator call was refused
3046
+ - **Constraints:** `code` is part of the public surface; renaming one is a breaking change
3047
+ - **Requires:** npm i @threenative/metahuman
3048
+
3049
+ ```ts
3050
+ if (error instanceof MetaHumanAssetError && error.code === "TN_MH_HASH_MISMATCH") refetch();
3051
+ ```
3052
+
3053
+ ### `RigEvaluator`
3054
+
3055
+ `class` — One MetaHuman head rig over the checksum-verified browser WASM build of the shared OpenRigLogic ABI: faceboard GUI controls in, joint deltas, blend shape weights and animated map weights out. instantiated, and nothing is fetched from a CDN evaluator throws instead of reading freed memory `create` and the WASM is never fetched; `RigEvaluator.backend()` says which one runs
3056
+
3057
+ ```ts
3058
+ export class RigEvaluator implements IRigEvaluator { … }
3059
+ ```
3060
+
3061
+ - **Use when:** drive a prepared MetaHuman head's expression from the browser without an Unreal import
3062
+ - **Constraints:** the binary's SHA-256 is checked against the shipped manifest before it is · every returned array is a copy, so no view survives a memory growth; a disposed · a native host that installed the MetaHuman resident gets its C++ evaluator from
3063
+ - **Requires:** npm i @threenative/metahuman
3064
+
3065
+ ```ts
3066
+ const rig = await RigEvaluator.create(dna); rig.setGuiControls(gui); rig.evaluate(true); rig.jointOutputs();
3067
+ ```
3068
+
3069
+ ### `validateMetaHumanAssets`
3070
+
3071
+ `function` — Checks one prepared specimen — bindings sidecar, DNA and GLB — against the rig it claims to drive, and returns the bindings only when every name, index, domain and hash holds up. channels, morph targets or LODs the loaded files do not contain disk and an index past the end of its array are rejections, each with a stable code cannot pass a hand-written sidecar the rig cannot drive
3072
+
3073
+ ```ts
3074
+ export function validateMetaHumanAssets(input: IMetaHumanAssetInput): IMetaHumanBindings { … }
3075
+ ```
3076
+
3077
+ - **Use when:** refuse a MetaHuman specimen whose bindings point at joints, nodes, blend shape
3078
+ - **Constraints:** fails closed: a missing key, a wrong type, a hash that differs from the bytes on · reads the rig's real names and the GLB's real node, mesh and target counts, so it
3079
+ - **Requires:** npm i @threenative/metahuman
3080
+
3081
+ ```ts
3082
+ const bindings = validateMetaHumanAssets({ bindings: parsed, dnaSha256, glbSha256, rig, gltf });
3083
+ ```
3084
+
1897
3085
  ## `@threenative/physics`
1898
3086
 
1899
3087
  ### `Area3D`
@@ -1906,6 +3094,7 @@ export class Area3D { … }
1906
3094
 
1907
3095
  - **Use when:** detect when an enemy enters a trigger area · react to a player entering a zone
1908
3096
  - **Constraints:** add the area to the physics context before stepping the world
3097
+ - **Deprecated:** Constructor option `world` is deprecated; pass an IPhysicsContext as `physics` instead. Area3D itself is not deprecated.
1909
3098
 
1910
3099
  ```ts
1911
3100
  const goal = new Area3D({ physics: ctx.physics, shape: CollisionShape3D.sphere(1.2), position: { x: 0, y: 0.5, z: -8 } });
@@ -1952,6 +3141,7 @@ export class CharacterBody3D { … }
1952
3141
 
1953
3142
  - **Use when:** move an enemy or player through a level · keep a character from walking through walls
1954
3143
  - **Constraints:** use moveAndSlide inside the physics update
3144
+ - **Deprecated:** Constructor option `world` is deprecated; pass an IPhysicsContext as `physics` instead. CharacterBody3D itself is not deprecated.
1955
3145
 
1956
3146
  ```ts
1957
3147
  const body = new CharacterBody3D({ object: hero, physics: ctx.physics, shape: CollisionShape3D.capsule(0.5, 0.35) });
@@ -1996,6 +3186,7 @@ export class Joint3D { … }
1996
3186
 
1997
3187
  - **Use when:** constrain a rigid body to another body · build a hinge or pin mechanism · swing a pendulum, wrecking ball, or hinged door on a joint
1998
3188
  - **Constraints:** both bodies must belong to the same physics context
3189
+ - **Deprecated:** Constructor option `world` is deprecated; pass an IPhysicsContext as `physics` instead. Joint3D itself is not deprecated.
1999
3190
 
2000
3191
  ```ts
2001
3192
  const hinge = Joint3D.hinge({ physics: ctx.physics, bodyA: beam, bodyB: bob, anchorA: { x: 0, y: 0, z: 0 }, anchorB: { x: 0, y: 2.4, z: 0 }, axis: { x: 1, y: 0, z: 0 } });
@@ -2042,6 +3233,7 @@ export class RigidBody3D { … }
2042
3233
  - **Use when:** give a crate or prop physical motion · create a body that collides with a character · fire physical cannonballs that collide with ships or scenery · fire a cannonball projectile with cannon smoke particles · a bullet passes through a wall
2043
3234
  - **Constraints:** register rapier() in the game plugin list before using bodies
2044
3235
  - **Overrides:** continuousCollision: false opts one body out while body.continuousCollision still reports the effective setting
3236
+ - **Deprecated:** Constructor option `world` is deprecated; pass an IPhysicsContext as `physics` instead. RigidBody3D itself is not deprecated.
2045
3237
 
2046
3238
  ```ts
2047
3239
  const crate = new RigidBody3D({ object, physics: ctx.physics, shape: CollisionShape3D.box(1, 1, 1), mass: 8 });
@@ -2062,6 +3254,22 @@ export function softBodyCollision(...bodies: readonly RigidBody3D[]): ISoftBodyC
2062
3254
  const cloth = new SoftBody3D(mesh, { ...options, collision: softBodyCollision(wall) });
2063
3255
  ```
2064
3256
 
3257
+ ### `VehicleBody3D`
3258
+
3259
+ `class` — Drive a car on ray-cast suspension instead of faking speed and heading.
3260
+
3261
+ ```ts
3262
+ export class VehicleBody3D extends RigidBody3D { … }
3263
+ ```
3264
+
3265
+ - **Use when:** drive a car, truck or bike around a track · make a vehicle roll over kerbs, brake into a corner or stop at a wall
3266
+ - **Constraints:** write engineForce, brake and steering every physics update; a car with no input does not move · suspensionStiffness is a frequency squared, not newtons per metre; 100 is a road car and 20 bottoms out
3267
+ - **Overrides:** a wheel ray never hits the chassis it hangs from, and it honours the chassis collision mask · continuousCollision is on for the chassis, so a fast car cannot tunnel through a wall
3268
+
3269
+ ```ts
3270
+ const car = new VehicleBody3D({ object: chassis, physics: ctx.physics, shape: CollisionShape3D.box(1.6, 0.5, 3.6), mass: 900, wheels: [{ position: { x: 0.8, y: -0.15, z: -1.2 }, wheelRadius: 0.34, suspensionRestLength: 0.3, suspensionStiffness: 100, dampingCompression: 2.3, dampingRelaxation: 4.4, wheelFrictionSlip: 10.5, maxSuspensionTravel: 0.3, useAsSteering: true, useAsTraction: false }] });
3271
+ ```
3272
+
2065
3273
  ## `@threenative/physics/navigation`
2066
3274
 
2067
3275
  ### `NavigationAgent3D`
@@ -2193,17 +3401,18 @@ const result = evaluateRichPlaytestAssertions(input);
2193
3401
 
2194
3402
  ### `invalidScenario`
2195
3403
 
2196
- `function` — Load and validate a scenario, then control its tick steps.
3404
+ `function` — Construct a named invalid-scenario error without loading or executing a scenario.
2197
3405
 
2198
3406
  ```ts
2199
3407
  export function invalidScenario(scenarioPath: string, message: string): PlaytestScenarioError { … }
2200
3408
  ```
2201
3409
 
2202
- - **Use when:** create a browser or device playtest scenario · wait or hold a game for a deterministic number of ticks
2203
- - **Constraints:** unknown scenario keys fail closed
3410
+ - **Use when:** construct a validation error for malformed scenario input
3411
+ - **Constraints:** returns an error; the caller must throw it
2204
3412
 
2205
3413
  ```ts
2206
- const scenario = await loadPlaytestScenario(project, file);
3414
+ import { invalidScenario } from "@threenative/playtest";
3415
+ throw invalidScenario("smoke.playtest.json", "Expected a non-empty assertion set");
2207
3416
  ```
2208
3417
 
2209
3418
  ### `jsonByteLength`
@@ -2223,17 +3432,18 @@ assertJsonSafe({ score: 10 });
2223
3432
 
2224
3433
  ### `loadPlaytestScenario`
2225
3434
 
2226
- `function` — Load and validate a scenario, then control its tick steps.
3435
+ `function` — Load and validate a scenario and its referenced evidence before running it.
2227
3436
 
2228
3437
  ```ts
2229
3438
  export async function loadPlaytestScenario(projectPath: string, scenarioPath: string): Promise<IPlaytestScenario> { … }
2230
3439
  ```
2231
3440
 
2232
- - **Use when:** create a browser or device playtest scenario · wait or hold a game for a deterministic number of ticks
2233
- - **Constraints:** unknown scenario keys fail closed
3441
+ - **Use when:** create a browser or device playtest scenario · load a deterministic tick-based playtest scenario
3442
+ - **Constraints:** unknown scenario keys and missing referenced evidence fail closed · loading validates the fixture; use the runner to execute it
2234
3443
 
2235
3444
  ```ts
2236
- const scenario = await loadPlaytestScenario(project, file);
3445
+ import { loadPlaytestScenario } from "@threenative/playtest";
3446
+ const scenario = await loadPlaytestScenario(process.cwd(), "playtests/smoke.playtest.json");
2237
3447
  ```
2238
3448
 
2239
3449
  ### `missingPlaytestCapabilities`
@@ -2326,62 +3536,66 @@ playtestDiagnostic("TN_PLAYTEST_CAPABILITY_MISSING", "body missing", "register r
2326
3536
 
2327
3537
  ### `PlaytestScenarioError`
2328
3538
 
2329
- `class` — Load and validate a scenario, then control its tick steps.
3539
+ `class` — Carry a structured scenario validation diagnostic as an error.
2330
3540
 
2331
3541
  ```ts
2332
3542
  export class PlaytestScenarioError extends Error { … }
2333
3543
  ```
2334
3544
 
2335
- - **Use when:** create a browser or device playtest scenario · wait or hold a game for a deterministic number of ticks
2336
- - **Constraints:** unknown scenario keys fail closed
3545
+ - **Use when:** catch a structured playtest scenario validation error
3546
+ - **Constraints:** the diagnostic describes a failed load, not a successfully executed scenario
2337
3547
 
2338
3548
  ```ts
2339
- const scenario = await loadPlaytestScenario(project, file);
3549
+ import { PlaytestScenarioError } from "@threenative/playtest";
3550
+ const error = new PlaytestScenarioError({ code: "TN_PLAYTEST_SCENARIO_INVALID", message: "Invalid fixture", severity: "error", suggestion: "Fix the fixture" });
2340
3551
  ```
2341
3552
 
2342
3553
  ### `playtestStepHoldTicks`
2343
3554
 
2344
- `function` — Load and validate a scenario, then control its tick steps.
3555
+ `function` — Read a validated step's input-hold duration in simulation ticks.
2345
3556
 
2346
3557
  ```ts
2347
3558
  export function playtestStepHoldTicks(step: IPlaytestStep, fallback = 1): number { … }
2348
3559
  ```
2349
3560
 
2350
- - **Use when:** create a browser or device playtest scenario · wait or hold a game for a deterministic number of ticks
2351
- - **Constraints:** unknown scenario keys fail closed
3561
+ - **Use when:** read the deterministic number of ticks to hold a playtest input
3562
+ - **Constraints:** reads the duration only; the runner advances the simulation
2352
3563
 
2353
3564
  ```ts
2354
- const scenario = await loadPlaytestScenario(project, file);
3565
+ import { playtestStepHoldTicks } from "@threenative/playtest";
3566
+ const ticks = playtestStepHoldTicks({ kind: "input", press: "KeyW", holdTicks: 30, release: true });
2355
3567
  ```
2356
3568
 
2357
3569
  ### `playtestStepWaitTicks`
2358
3570
 
2359
- `function` — Load and validate a scenario, then control its tick steps.
3571
+ `function` — Read a validated step's no-input duration in simulation ticks.
2360
3572
 
2361
3573
  ```ts
2362
3574
  export function playtestStepWaitTicks(step: IPlaytestStep): number { … }
2363
3575
  ```
2364
3576
 
2365
- - **Use when:** create a browser or device playtest scenario · wait or hold a game for a deterministic number of ticks
2366
- - **Constraints:** unknown scenario keys fail closed
3577
+ - **Use when:** wait or hold a game for a deterministic number of ticks
3578
+ - **Constraints:** reads the wait duration only; the runner advances the simulation
2367
3579
 
2368
3580
  ```ts
2369
- const scenario = await loadPlaytestScenario(project, file);
3581
+ import { playtestStepWaitTicks } from "@threenative/playtest";
3582
+ const ticks = playtestStepWaitTicks({ kind: "wait", waitTicks: 30, release: true });
2370
3583
  ```
2371
3584
 
2372
3585
  ### `rejectUnknownKeys`
2373
3586
 
2374
- `function` — Load and validate a scenario, then control its tick steps.
3587
+ `function` — Reject object keys outside the explicitly allowed scenario fields.
2375
3588
 
2376
3589
  ```ts
2377
3590
  export function rejectUnknownKeys( value: Record<string, unknown>, allowedKeys: readonly string[], scenarioPath: string, objectPath: string, ): void { … }
2378
3591
  ```
2379
3592
 
2380
- - **Use when:** create a browser or device playtest scenario · wait or hold a game for a deterministic number of ticks
2381
- - **Constraints:** unknown scenario keys fail closed
3593
+ - **Use when:** reject an unknown field while validating a scenario object
3594
+ - **Constraints:** throws an invalid-scenario error on the first unknown key
2382
3595
 
2383
3596
  ```ts
2384
- const scenario = await loadPlaytestScenario(project, file);
3597
+ import { rejectUnknownKeys } from "@threenative/playtest";
3598
+ rejectUnknownKeys({ name: "smoke" }, ["name"], "smoke.playtest.json", "scenario");
2385
3599
  ```
2386
3600
 
2387
3601
  ### `requiredPlaytestCapabilities`
@@ -2460,6 +3674,21 @@ export function assertCaptureNotBlank(png: Buffer, label: string): ICaptureFrame
2460
3674
  assertCaptureNotBlank(png, "first frame");
2461
3675
  ```
2462
3676
 
3677
+ ### `assertFrameShowsSomething`
3678
+
3679
+ `function` — Fail closed when a screenshot is blank or uniform.
3680
+
3681
+ ```ts
3682
+ assertFrameShowsSomething = assertCaptureNotBlank
3683
+ ```
3684
+
3685
+ - **Use when:** guard a visual playtest against a blank frame · prove a screenshot contains more than a loading surface
3686
+ - **Constraints:** the assertion throws instead of returning a false pass
3687
+
3688
+ ```ts
3689
+ assertFrameShowsSomething(png, "first frame");
3690
+ ```
3691
+
2463
3692
  ### `CaptureGuardError`
2464
3693
 
2465
3694
  `class` — Explain why a captured frame failed the non-blank guard.
@@ -2701,6 +3930,23 @@ export async function connectPlaytestBridgeTransport( transport: IBridgeTranspor
2701
3930
  const bridge = await connectPlaytestBridge(page, scenario);
2702
3931
  ```
2703
3932
 
3933
+ ### `decideDisplayStrategy`
3934
+
3935
+ `function` — Decide which display a pixel-producing run paints on, the same decision the runner makes.
3936
+
3937
+ ```ts
3938
+ export function decideDisplayStrategy(input: IDisplayDecisionInput): IDisplayStrategy { … }
3939
+ ```
3940
+
3941
+ - **Use when:** judge whether a measured frame rate came from a display that can carry one
3942
+ - **Constraints:** a private Xvfb is software, so a rate read there measures the X server
3943
+
3944
+ ```ts
3945
+ import { decideDisplayStrategy } from "@threenative/playtest/runner";
3946
+ const lane = decideDisplayStrategy({ env: process.env, platform: "linux" });
3947
+ if (lane.kind === "private-xvfb") throw new Error("refuse to judge this frame rate");
3948
+ ```
3949
+
2704
3950
  ### `DesktopPlaytestDriver`
2705
3951
 
2706
3952
  `class` — Drive a local desktop playtest mailbox.
@@ -3123,17 +4369,18 @@ const report = await runStandalonePlaytest(options);
3123
4369
 
3124
4370
  ### `reconcileBrowserPointers`
3125
4371
 
3126
- `function` — Select safe Chromium arguments for WebGPU playtests.
4372
+ `function` — Compare pointer snapshots and produce down, move, and up transitions.
3127
4373
 
3128
4374
  ```ts
3129
4375
  export function reconcileBrowserPointers( previous: ReadonlyMap<number, Required<IPlaytestPointer>>, next: readonly IPlaytestPointer[], ): IBrowserPointerChange[] { … }
3130
4376
  ```
3131
4377
 
3132
- - **Use when:** run a browser playtest with Vulkan WebGPU · reject a SwiftShader adapter as evidence
3133
- - **Constraints:** inspect the adapter name before claiming GPU proof
4378
+ - **Use when:** reconcile pointer contacts into down move and up events
4379
+ - **Constraints:** returns changes only; the caller dispatches them and retains the next snapshot
3134
4380
 
3135
4381
  ```ts
3136
- const args = resolveBrowserArguments(undefined);
4382
+ import { reconcileBrowserPointers } from "@threenative/playtest/runner";
4383
+ const changes = reconcileBrowserPointers(new Map(), [{ id: 1, x: 20, y: 30 }]);
3137
4384
  ```
3138
4385
 
3139
4386
  ### `recordToScenario`
@@ -3168,17 +4415,18 @@ const scenario = recordToScenario(recording);
3168
4415
 
3169
4416
  ### `resolveBrowserArguments`
3170
4417
 
3171
- `function` — Select safe Chromium arguments for WebGPU playtests.
4418
+ `function` — Copy the selected Chromium arguments without silently enabling a rendering recipe.
3172
4419
 
3173
4420
  ```ts
3174
4421
  export function resolveBrowserArguments(browserArgs: readonly string[] | undefined): string[] { … }
3175
4422
  ```
3176
4423
 
3177
- - **Use when:** run a browser playtest with Vulkan WebGPU · reject a SwiftShader adapter as evidence
3178
- - **Constraints:** inspect the adapter name before claiming GPU proof
4424
+ - **Use when:** run a browser playtest with Vulkan WebGPU
4425
+ - **Constraints:** pass WEBGPU_BROWSER_ARGS explicitly; undefined selects no additional arguments · inspect the observed adapter before claiming hardware GPU evidence
3179
4426
 
3180
4427
  ```ts
3181
- const args = resolveBrowserArguments(undefined);
4428
+ import { resolveBrowserArguments, WEBGPU_BROWSER_ARGS } from "@threenative/playtest/runner";
4429
+ const args = resolveBrowserArguments(WEBGPU_BROWSER_ARGS);
3182
4430
  ```
3183
4431
 
3184
4432
  ### `resolveManagedServerCommand`
@@ -3318,17 +4566,18 @@ const report = await runStandalonePlaytest(options);
3318
4566
 
3319
4567
  ### `softwareAdapterName`
3320
4568
 
3321
- `function` — Select safe Chromium arguments for WebGPU playtests.
4569
+ `function` — Identify a software renderer in the fields reported by adapter.info.
3322
4570
 
3323
4571
  ```ts
3324
4572
  export function softwareAdapterName(adapter: Readonly<Record<string, string>> | undefined): string | undefined { … }
3325
4573
  ```
3326
4574
 
3327
- - **Use when:** run a browser playtest with Vulkan WebGPU · reject a SwiftShader adapter as evidence
3328
- - **Constraints:** inspect the adapter name before claiming GPU proof
4575
+ - **Use when:** reject a SwiftShader adapter as evidence
4576
+ - **Constraints:** undefined means no software name was found, not proof of a hardware adapter
3329
4577
 
3330
4578
  ```ts
3331
- const args = resolveBrowserArguments(undefined);
4579
+ import { softwareAdapterName } from "@threenative/playtest/runner";
4580
+ const software = softwareAdapterName({ architecture: "swiftshader" });
3332
4581
  ```
3333
4582
 
3334
4583
  ### `substituteManagedPort`
@@ -3466,6 +4715,23 @@ export function viewportRestoreCommands(): string[][] { … }
3466
4715
  const adb = discoverAdb(process.env);
3467
4716
  ```
3468
4717
 
4718
+ ### `withBrowserCapture`
4719
+
4720
+ `function` — Capture a ready ThreeNative game with the runner's display, lock, server and browser ownership.
4721
+
4722
+ ```ts
4723
+ export async function withBrowserCapture<T>( config: IStandalonePlaytestConfig, capture: (session: IBrowserCaptureSession) => Promise<T>, signal?: AbortSignal, ): Promise<T> { … }
4724
+ ```
4725
+
4726
+ - **Use when:** write a custom browser capture without owning Xvfb or Chromium cleanup
4727
+ - **Constraints:** browser only; requires a scenario and runtime.startup; does not execute scenario steps or assertions · cancellation is checked between resource acquisitions; lock waiting retains its own bounded queue policy · use session.screenshot for nonblank PNGs; private-display captures are not FPS evidence · use threenative-playtest trace --url <url> for slow-frame attribution instead of creating another profiler
4728
+
4729
+ ```ts
4730
+ import { parseStandalonePlaytestArgs, withBrowserCapture } from "@threenative/playtest/runner";
4731
+ const config = parseStandalonePlaytestArgs(["--scenario", "playtests/smoke.playtest.json", "--url", "http://127.0.0.1:5173"]);
4732
+ await withBrowserCapture(config, async (session) => session.screenshot("ready"));
4733
+ ```
4734
+
3469
4735
  ### `writeCaptureProvenance`
3470
4736
 
3471
4737
  `function` — Execute scenario steps, assertions, and evidence capture.
@@ -4094,13 +5360,14 @@ const model = new UEFormatLoader(manager).parse(data);
4094
5360
 
4095
5361
  ### `DebugOverlay`
4096
5362
 
4097
- `function` — Show framework diagnostics while developing a game.
5363
+ `function` — Show framework diagnostics while developing a game. Backtick opens it; the Entities tab lists registered entity fields, and the Geometry tab captures one frame and ranks the objects that submitted its triangles beside their projected size on screen.
4098
5364
 
4099
5365
  ```ts
4100
5366
  export function DebugOverlay() { … }
4101
5367
  ```
4102
5368
 
4103
- - **Use when:** display runtime and playtest diagnostics in a React HUD · inspect a game without changing its scene
5369
+ - **Use when:** display runtime and playtest diagnostics in a React HUD · inspect a game without changing its scene · find out which scene object is submitting the frame's triangles · tell a cheap foreground character from an expensive distant prop
5370
+ - **Constraints:** the Geometry tab captures only on an explicit press; nothing is collected while idle · per-object numbers are measured submissions reconciled against the frame's own pass totals, and the remainder is reported rather than hidden
4104
5371
 
4105
5372
  ```ts
4106
5373
  <DebugOverlay />
@@ -4138,7 +5405,7 @@ export function UiLayer( { … }
4138
5405
 
4139
5406
  ### `useGameState`
4140
5407
 
4141
- `function` — Read throttled game state from React.
5408
+ `function` — Read the game's coalesced frame snapshot from React.
4142
5409
 
4143
5410
  ```ts
4144
5411
  export function useGameState<TState extends Record<string, unknown>, TPhysics, TSelected>( game: IGame<TState, TPhysics>, selector: GameSelector<TState, TSelected>, ): TSelected;
@@ -4181,6 +5448,56 @@ export function useUiState<TState extends object>(): TState | undefined;
4181
5448
  const score = useUiState<GameState, number>((state) => state.score);
4182
5449
  ```
4183
5450
 
5451
+ ## `src/game.ts`
5452
+
5453
+ ### `renderer.matrixWorld`
5454
+
5455
+ `function` — The per-frame world-matrix walk, on by default as `"visible"`: a hidden subtree — a full-detail body behind a merged stand-in, a hidden LOD level, a parked or hangared model — is not recursed into, so nothing that cannot draw pays a world-matrix multiply. Every visible node is composed exactly as three does, a class that overrides `updateMatrixWorld` (`SkinnedMesh`, `Camera`) runs its own, and a hidden node that holds bones is still walked. `"all"` restores three's every-node walk.
5456
+
5457
+ ```ts
5458
+ renderer.matrixWorld?: "visible" | "all"
5459
+ ```
5460
+
5461
+ - **Use when:** updateMatrixWorld and multiplyMatrices are hot in a profile · the per-frame matrix walk is slow with many hidden LOD bodies or paired full/hull models · stop paying for matrices of models nothing can draw · a skinned mesh or camera goes stale because its world matrix was not refreshed · restore three's own full updateMatrixWorld walk · compare how many scene nodes the engine walks per frame
5462
+ - **Constraints:** Unset is the shipping behaviour: `"visible"`, which does not recurse into a hidden subtree. `"all"` visits every node exactly as three's own `updateMatrixWorld` does. · A game that reads a hidden object's `matrixWorld` directly must not rely on the walk reaching it: use `getWorldPosition`/`getWorldQuaternion`/`getWorldScale` or call `object.updateWorldMatrix(true, false)` first. · The walk is the engine's either way, so three's renderer never walks the scene a second time; the count of nodes visited is reported as `matrixWorld` in every `TN_PROJECTION` window. · Bones are never skipped: a hidden node that holds a `Bone` is walked, because a visible `SkinnedMesh` draws with its skeleton's matrices wherever the armature sits.
5463
+ - **Overrides:** renderer.matrixWorld: "all" restores three's every-node walk; the visited count still reports
5464
+
5465
+ ```ts
5466
+ renderer: { matrixWorld: "all" } // in threenative.config.ts; omit for the visible-only default
5467
+ ```
5468
+
5469
+ ### `renderer.minimumProjectedPixels`
5470
+
5471
+ `function` — Do not submit what the render camera cannot resolve. On by default at a conservative 0.5 projected pixel; an object below it is skipped per render camera. Raise the number to cull more, set `false` to leave every object drawn — the count of what was skipped still reports in `TN_PROJECTION`.
5472
+
5473
+ ```ts
5474
+ renderer.minimumProjectedPixels?: number | false
5475
+ ```
5476
+
5477
+ - **Use when:** my frame is slow with many distant objects · draw count is high but the screen is mostly empty · far away models, aircraft, boats or props cost draw calls but are specks · a large roster or fleet drops the frame rate while barely visible · stop submitting objects smaller than a pixel to the camera · cull by how big something looks to the camera rather than how far it is from the player · tune how aggressively distant objects are skipped · a small object I need disappeared at range
5478
+ - **Constraints:** Unset is the shipping behaviour: the gate runs at 0.5 px. A game that wants the cut a shipped title tuned names 2; `false` leaves every object drawn. · The decision reads the render camera's projection and viewport, not the player's distance — a camera far from the player still culls its own specks. · It writes only `object.visible`, which the projection's batch key ignores; `castShadow`, `layers` and `frustumCulled` are never flipped, because that churns batch grouping. · Shadow casters and objects attached to the render camera are never dropped on the main view alone. Exempt any other object with `alwaysRender`. · Turning the gate off with `false` does not turn its measurement off: `TN_PROJECTION` still reports considered and skipped counts as `cull`.
5479
+ - **Overrides:** alwaysRender(object) keeps one object drawn whatever the render camera resolves · renderer.minimumProjectedPixels: false leaves the scene drawn and keeps the measurement on
5480
+
5481
+ ```ts
5482
+ renderer: { minimumProjectedPixels: 2 } // in threenative.config.ts
5483
+ ```
5484
+
5485
+ ### `renderer.projection`
5486
+
5487
+ `function` — The engine's scene-render projection — an internal mirror that collapses repeated draws, including animated skinned rigs that share a geometry and material into one palette draw per pass — on by default. Set `renderer.projection: false` to decline it, or `projection: { materialChecks: 'everyFrame' }` to keep it and pay for a per-material check on every frame.
5488
+
5489
+ ```ts
5490
+ renderer.projection?: boolean | { materialChecks?: 'spread' | 'everyFrame' }
5491
+ ```
5492
+
5493
+ - **Use when:** a crowd of animated characters draws slowly · many SkinnedMesh copies of one rig, each its own draw call · the game got slower after the projection engaged · turn off the render projection, batching, or the instanced mirror · draw count fell but frame time did not · a multi-second freeze when the mirror first engages · opt out of an engine render optimizer · thousands of props each with their own material, one colour apart · a material edit takes a few frames to show up · check every batched material every frame anyway
5494
+ - **Constraints:** Unset is the shipping behaviour: the projection runs. Only an explicit `false` declines it. · An opted-out game builds no mirror and runs no eligibility scan; the authored scene is what renders, so declining costs nothing rather than being re-judged each frame. · TN_RENDER_PROJECTION still reports the verdict, with reasonCode `disabled` rather than one of the measured declines. · `materialChecks: 'spread'` is the default: a bounded slice of the batched materials is proved per frame instead of all of them, so a frame of 4,096 colour-only materials costs 512 checks rather than 4,096. A base-colour edit is never delayed — that write is O(1) per member. · The price of `spread` is staleness on every other material edit: a material that gains a roughness, a map or a define still leaves its group and is drawn exactly, up to `materialCheckStaleFrames` frames later. TN_RENDER_PROJECTION reports that bound; `materialChecks: 'everyFrame'` sets it to 0 and restores the per-member, per-frame check. · Any other `materialChecks` value throws at startup rather than falling back to a default.
5495
+ - **Overrides:** renderer.projection: false declines the whole mirror and costs nothing to decline · renderer: { projection: { materialChecks: 'everyFrame' } } proves every batched material every frame instead of the default bounded slice
5496
+
5497
+ ```ts
5498
+ renderer: { projection: false } // in threenative.config.ts
5499
+ ```
5500
+
4184
5501
  ## `src/render/worldEnvironment.ts`
4185
5502
 
4186
5503
  ### `WorldEnvironment`