create-threenative 0.2.3 → 0.2.4

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 (447) hide show
  1. package/README.md +53 -2
  2. package/agent-docs/references/assertion-reference.md +173 -6
  3. package/agent-docs/references/capability-reference.md +1303 -99
  4. package/agent-docs/references/capture-the-frame.md +7 -0
  5. package/agent-docs/references/creating-creatures.md +215 -0
  6. package/agent-docs/references/ctx-cookbook.md +69 -0
  7. package/agent-docs/references/debug-surface.md +8 -3
  8. package/agent-docs/references/dream-loop.md +150 -0
  9. package/agent-docs/references/finding-assets.md +70 -2
  10. package/agent-docs/references/sculpt-from-a-reference.md +3 -2
  11. package/agent-docs/references/trace-a-slow-frame.md +99 -0
  12. package/agent-docs/references/visual-baseline.md +41 -0
  13. package/agent-files/.agents/skills/file-engine-bug/SKILL.md +59 -0
  14. package/agent-files/.agents/skills/prd-creator/SKILL.md +40 -0
  15. package/agent-files/.agents/skills/threenative-assets/SKILL.md +45 -0
  16. package/agent-files/.agents/skills/threenative-builder/SKILL.md +1 -1
  17. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +27 -0
  18. package/agent-files/.agents/skills/threenative-context/SKILL.md +57 -0
  19. package/agent-files/.agents/skills/threenative-performance/SKILL.md +42 -0
  20. package/agent-files/.agents/skills/threenative-playtest/SKILL.md +44 -0
  21. package/agent-files/.agents/skills/threenative-ui/SKILL.md +20 -0
  22. package/agent-files/.agents/skills/threenative-verifier/SKILL.md +1 -1
  23. package/agent-files/.agents/skills/threenative-visuals/SKILL.md +41 -0
  24. package/agent-files/.claude/skills/file-engine-bug/SKILL.md +59 -0
  25. package/agent-files/.claude/skills/prd-creator/SKILL.md +40 -0
  26. package/agent-files/.claude/skills/threenative-assets/SKILL.md +45 -0
  27. package/agent-files/.claude/skills/threenative-capabilities/SKILL.md +27 -0
  28. package/agent-files/.claude/skills/threenative-context/SKILL.md +57 -0
  29. package/agent-files/.claude/skills/threenative-performance/SKILL.md +42 -0
  30. package/agent-files/.claude/skills/threenative-playtest/SKILL.md +44 -0
  31. package/agent-files/.claude/skills/threenative-ui/SKILL.md +20 -0
  32. package/agent-files/.claude/skills/threenative-visuals/SKILL.md +41 -0
  33. package/agent-files/scripts/reference.mjs +705 -0
  34. package/agent-files/scripts/visual-loop.mjs +382 -0
  35. package/capabilities.json +1881 -131
  36. package/dist/index.d.ts +39 -6
  37. package/dist/index.js +297 -32
  38. package/dist/threenative.js +822 -105
  39. package/package.json +30 -5
  40. package/template-assets/loading.ts +12 -2
  41. package/template-assets/patches/three@0.185.1.patch +249 -14
  42. package/template-assets/worldEnvironment.ts +758 -0
  43. package/templates/action-rpg/.codex/config.toml +4 -0
  44. package/templates/action-rpg/.cursor/mcp.json +32 -0
  45. package/templates/action-rpg/.gemini/settings.json +32 -0
  46. package/templates/action-rpg/.mcp.json +15 -3
  47. package/templates/action-rpg/.vscode/mcp.json +36 -0
  48. package/templates/action-rpg/.zed/settings.json +36 -0
  49. package/templates/action-rpg/AGENTS.md +69 -378
  50. package/templates/action-rpg/CLAUDE.md +69 -378
  51. package/templates/action-rpg/opencode.json +41 -0
  52. package/templates/action-rpg/package.json +7 -7
  53. package/templates/action-rpg/playtests/combat.playtest.json +9 -0
  54. package/templates/action-rpg/playtests/performance.playtest.json +24 -7
  55. package/templates/action-rpg/playtests/survives.playtest.json +27 -0
  56. package/templates/action-rpg/playtests/touch-controls.playtest.json +42 -0
  57. package/templates/action-rpg/src/conventions.ts +35 -0
  58. package/templates/action-rpg/src/entities/Enemy.ts +2 -3
  59. package/templates/action-rpg/src/entities/Player.ts +20 -3
  60. package/templates/action-rpg/src/render/camera.ts +7 -2
  61. package/templates/action-rpg/src/render/lighting.ts +5 -3
  62. package/templates/action-rpg/src/render/loading.ts +12 -2
  63. package/templates/action-rpg/src/render/materials.ts +11 -0
  64. package/templates/action-rpg/src/render/palette.ts +10 -3
  65. package/templates/action-rpg/src/render/postprocessing.ts +21 -58
  66. package/templates/action-rpg/src/render/quality.ts +170 -0
  67. package/templates/action-rpg/src/render/shapes.ts +185 -26
  68. package/templates/action-rpg/src/render/touch-controls.ts +185 -0
  69. package/templates/action-rpg/src/render/vfx.ts +257 -0
  70. package/templates/action-rpg/src/render/worldEnvironment.ts +208 -33
  71. package/templates/action-rpg/src/scenes/Play.ts +43 -6
  72. package/templates/action-rpg/src/style.css +20 -0
  73. package/templates/action-rpg/threenative.config.ts +7 -0
  74. package/templates/defense/.codex/config.toml +4 -0
  75. package/templates/defense/.cursor/mcp.json +32 -0
  76. package/templates/defense/.gemini/settings.json +32 -0
  77. package/templates/defense/.mcp.json +15 -3
  78. package/templates/defense/.vscode/mcp.json +36 -0
  79. package/templates/defense/.zed/settings.json +36 -0
  80. package/templates/defense/AGENTS.md +62 -385
  81. package/templates/defense/CLAUDE.md +62 -385
  82. package/templates/defense/opencode.json +41 -0
  83. package/templates/defense/package.json +7 -7
  84. package/templates/defense/playtests/performance.playtest.json +24 -7
  85. package/templates/defense/playtests/pointer-placement.playtest.json +87 -20
  86. package/templates/defense/playtests/scan.playtest.json +1 -1
  87. package/templates/defense/playtests/survive.playtest.json +14 -0
  88. package/templates/defense/src/attackers/Attacker.ts +4 -4
  89. package/templates/defense/src/board/Route.ts +22 -8
  90. package/templates/defense/src/conventions.ts +18 -0
  91. package/templates/defense/src/entities/Player.ts +11 -3
  92. package/templates/defense/src/game.ts +2 -3
  93. package/templates/defense/src/physics.ts +9 -39
  94. package/templates/defense/src/placement/Buildable.ts +4 -4
  95. package/templates/defense/src/render/camera.ts +9 -3
  96. package/templates/defense/src/render/loading.ts +12 -2
  97. package/templates/defense/src/render/materials.ts +9 -0
  98. package/templates/defense/src/render/palette.ts +12 -5
  99. package/templates/defense/src/render/postprocessing.ts +21 -58
  100. package/templates/defense/src/render/quality.ts +170 -0
  101. package/templates/defense/src/render/shapes.ts +142 -23
  102. package/templates/defense/src/render/sky.ts +2 -2
  103. package/templates/defense/src/render/worldEnvironment.ts +208 -33
  104. package/templates/defense/src/scenes/Boot.ts +2 -2
  105. package/templates/defense/src/scenes/Defense.ts +13 -6
  106. package/templates/defense/src/style.css +20 -0
  107. package/templates/defense/src/towers/Tower.ts +11 -12
  108. package/templates/defense/src/towers/targeting.ts +1 -1
  109. package/templates/defense/src/ui/App.tsx +2 -2
  110. package/templates/defense/threenative.config.ts +7 -0
  111. package/templates/minimal/.codex/config.toml +4 -0
  112. package/templates/minimal/.cursor/mcp.json +32 -0
  113. package/templates/minimal/.gemini/settings.json +32 -0
  114. package/templates/minimal/.mcp.json +15 -3
  115. package/templates/minimal/.vscode/mcp.json +36 -0
  116. package/templates/minimal/.zed/settings.json +36 -0
  117. package/templates/minimal/AGENTS.md +76 -485
  118. package/templates/minimal/CLAUDE.md +76 -485
  119. package/templates/minimal/opencode.json +41 -0
  120. package/templates/minimal/package.json +6 -6
  121. package/templates/minimal/playtests/play.playtest.json +2 -1
  122. package/templates/minimal/playtests/survives.playtest.json +48 -4
  123. package/templates/minimal/playtests/touch-controls.playtest.json +42 -0
  124. package/templates/minimal/src/conventions.ts +18 -0
  125. package/templates/minimal/src/entities/Player.ts +39 -6
  126. package/templates/minimal/src/main.ts +14 -4
  127. package/templates/minimal/src/render/materials.ts +7 -0
  128. package/templates/minimal/src/render/palette.ts +3 -3
  129. package/templates/minimal/src/render/postprocessing.ts +17 -56
  130. package/templates/minimal/src/render/quality.ts +162 -0
  131. package/templates/minimal/src/render/sky.ts +23 -9
  132. package/templates/minimal/src/render/touch-controls.ts +165 -0
  133. package/templates/minimal/src/render/worldEnvironment.ts +208 -33
  134. package/templates/minimal/src/scenes/Play.ts +47 -11
  135. package/templates/minimal/src/style.css +20 -0
  136. package/templates/minimal/threenative.config.ts +7 -0
  137. package/templates/platformer/.codex/config.toml +4 -0
  138. package/templates/platformer/.cursor/mcp.json +32 -0
  139. package/templates/platformer/.gemini/settings.json +32 -0
  140. package/templates/platformer/.mcp.json +15 -3
  141. package/templates/platformer/.vscode/mcp.json +36 -0
  142. package/templates/platformer/.zed/settings.json +36 -0
  143. package/templates/platformer/AGENTS.md +70 -430
  144. package/templates/platformer/CLAUDE.md +70 -430
  145. package/templates/platformer/opencode.json +41 -0
  146. package/templates/platformer/package.json +7 -7
  147. package/templates/platformer/playtests/oneway.playtest.json +29 -2
  148. package/templates/platformer/playtests/performance.playtest.json +2 -1
  149. package/templates/platformer/playtests/survives.playtest.json +31 -0
  150. package/templates/platformer/playtests/terminal-loop-fail.playtest.json +3 -0
  151. package/templates/platformer/playtests/touch-controls-web.playtest.json +15 -4
  152. package/templates/platformer/src/conventions.ts +18 -0
  153. package/templates/platformer/src/entities/Character.ts +63 -1
  154. package/templates/platformer/src/game.ts +3 -1
  155. package/templates/platformer/src/level/Platform.ts +13 -1
  156. package/templates/platformer/src/render/lighting.ts +7 -4
  157. package/templates/platformer/src/render/loading.ts +12 -2
  158. package/templates/platformer/src/render/palette.ts +4 -1
  159. package/templates/platformer/src/render/postprocessing.ts +32 -57
  160. package/templates/platformer/src/render/quality.ts +170 -0
  161. package/templates/platformer/src/render/worldEnvironment.ts +208 -33
  162. package/templates/platformer/src/scenes/Level.ts +52 -12
  163. package/templates/platformer/src/style.css +20 -0
  164. package/templates/platformer/threenative.config.ts +7 -0
  165. package/templates/puzzle/.codex/config.toml +19 -0
  166. package/templates/puzzle/.cursor/mcp.json +32 -0
  167. package/templates/puzzle/.gemini/settings.json +32 -0
  168. package/templates/puzzle/.mcp.json +32 -0
  169. package/templates/puzzle/.vscode/mcp.json +36 -0
  170. package/templates/puzzle/.zed/settings.json +36 -0
  171. package/templates/puzzle/AGENTS.md +96 -0
  172. package/templates/puzzle/CLAUDE.md +98 -0
  173. package/templates/puzzle/README.md +43 -0
  174. package/templates/puzzle/index.html +12 -0
  175. package/templates/puzzle/kit.json +7 -0
  176. package/templates/puzzle/opencode.json +41 -0
  177. package/templates/puzzle/package.json +50 -0
  178. package/templates/puzzle/playtests/carry.playtest.json +71 -0
  179. package/templates/puzzle/playtests/performance.playtest.json +23 -0
  180. package/templates/puzzle/playtests/survives.playtest.json +51 -0
  181. package/templates/puzzle/playtests/swing.playtest.json +38 -0
  182. package/templates/puzzle/public/favicon.svg +5 -0
  183. package/templates/puzzle/src/conventions.ts +25 -0
  184. package/templates/puzzle/src/entities/Ball.ts +70 -0
  185. package/templates/puzzle/src/entities/Crate.ts +76 -0
  186. package/templates/puzzle/src/entities/Gripper.ts +69 -0
  187. package/templates/puzzle/src/entities/Pendulum.ts +89 -0
  188. package/templates/puzzle/src/game.ts +48 -0
  189. package/templates/puzzle/src/main.ts +15 -0
  190. package/templates/puzzle/src/physics.ts +19 -0
  191. package/templates/puzzle/src/render/camera.ts +37 -0
  192. package/templates/puzzle/src/render/lighting.ts +55 -0
  193. package/templates/puzzle/src/render/loading.ts +325 -0
  194. package/templates/puzzle/src/render/materials.ts +28 -0
  195. package/templates/puzzle/src/render/palette.ts +31 -0
  196. package/templates/puzzle/src/render/postprocessing.ts +34 -0
  197. package/templates/puzzle/src/render/quality.ts +170 -0
  198. package/templates/puzzle/src/render/shapes.ts +134 -0
  199. package/templates/puzzle/src/render/sky.ts +16 -0
  200. package/templates/puzzle/src/render/touch-controls.ts +185 -0
  201. package/templates/puzzle/src/render/worldEnvironment.ts +758 -0
  202. package/templates/puzzle/src/room.ts +83 -0
  203. package/templates/puzzle/src/scenes/Boot.ts +12 -0
  204. package/templates/puzzle/src/scenes/Puzzle.ts +158 -0
  205. package/templates/puzzle/src/state.ts +30 -0
  206. package/templates/puzzle/src/style.css +96 -0
  207. package/templates/puzzle/src/ui/App.tsx +22 -0
  208. package/templates/puzzle/src/ui/GameUi.tsx +20 -0
  209. package/templates/puzzle/src/ui/Hud.tsx +57 -0
  210. package/templates/puzzle/src/ui/Menu.tsx +7 -0
  211. package/templates/puzzle/src/ui/main.tsx +14 -0
  212. package/templates/puzzle/tailwind.config.ts +1 -0
  213. package/templates/puzzle/threenative.config.ts +49 -0
  214. package/templates/puzzle/tsconfig.json +17 -0
  215. package/templates/puzzle/vite.config.ts +38 -0
  216. package/templates/racing/.codex/config.toml +4 -0
  217. package/templates/racing/.cursor/mcp.json +32 -0
  218. package/templates/racing/.gemini/settings.json +32 -0
  219. package/templates/racing/.mcp.json +15 -3
  220. package/templates/racing/.vscode/mcp.json +36 -0
  221. package/templates/racing/.zed/settings.json +36 -0
  222. package/templates/racing/AGENTS.md +63 -379
  223. package/templates/racing/CLAUDE.md +63 -379
  224. package/templates/racing/native-playtests/survives.playtest.json +43 -0
  225. package/templates/racing/opencode.json +41 -0
  226. package/templates/racing/package.json +8 -7
  227. package/templates/racing/playtests/performance.playtest.json +24 -7
  228. package/templates/racing/playtests/survives.playtest.json +36 -4
  229. package/templates/racing/playtests/touch-controls.playtest.json +41 -0
  230. package/templates/racing/src/conventions.ts +6 -0
  231. package/templates/racing/src/entities/RacingCar.ts +16 -4
  232. package/templates/racing/src/entities/Rival.ts +5 -2
  233. package/templates/racing/src/render/camera.ts +7 -4
  234. package/templates/racing/src/render/lighting.ts +22 -13
  235. package/templates/racing/src/render/loading.ts +12 -2
  236. package/templates/racing/src/render/materials.ts +54 -4
  237. package/templates/racing/src/render/palette.ts +23 -6
  238. package/templates/racing/src/render/postprocessing.ts +21 -58
  239. package/templates/racing/src/render/quality.ts +170 -0
  240. package/templates/racing/src/render/shapes.ts +537 -26
  241. package/templates/racing/src/render/sky.ts +5 -2
  242. package/templates/racing/src/render/touch-controls.ts +185 -0
  243. package/templates/racing/src/render/worldEnvironment.ts +208 -33
  244. package/templates/racing/src/scenes/Race.ts +17 -2
  245. package/templates/racing/src/style.css +20 -0
  246. package/templates/racing/src/track/Track.ts +270 -31
  247. package/templates/racing/threenative.config.ts +7 -0
  248. package/templates/runner/.codex/config.toml +19 -0
  249. package/templates/runner/.cursor/mcp.json +32 -0
  250. package/templates/runner/.gemini/settings.json +32 -0
  251. package/templates/runner/.mcp.json +32 -0
  252. package/templates/runner/.vscode/mcp.json +36 -0
  253. package/templates/runner/.zed/settings.json +36 -0
  254. package/templates/runner/AGENTS.md +96 -0
  255. package/templates/runner/CLAUDE.md +98 -0
  256. package/templates/runner/README.md +43 -0
  257. package/templates/runner/index.html +12 -0
  258. package/templates/runner/kit.json +7 -0
  259. package/templates/runner/opencode.json +41 -0
  260. package/templates/runner/package.json +50 -0
  261. package/templates/runner/playtests/performance.playtest.json +23 -0
  262. package/templates/runner/playtests/streams.playtest.json +38 -0
  263. package/templates/runner/playtests/survives.playtest.json +51 -0
  264. package/templates/runner/public/favicon.svg +5 -0
  265. package/templates/runner/src/conventions.ts +24 -0
  266. package/templates/runner/src/entities/Runner.ts +135 -0
  267. package/templates/runner/src/game.ts +50 -0
  268. package/templates/runner/src/main.ts +15 -0
  269. package/templates/runner/src/physics.ts +13 -0
  270. package/templates/runner/src/render/camera.ts +39 -0
  271. package/templates/runner/src/render/dust.ts +131 -0
  272. package/templates/runner/src/render/lighting.ts +57 -0
  273. package/templates/runner/src/render/loading.ts +325 -0
  274. package/templates/runner/src/render/materials.ts +27 -0
  275. package/templates/runner/src/render/palette.ts +30 -0
  276. package/templates/runner/src/render/postprocessing.ts +34 -0
  277. package/templates/runner/src/render/quality.ts +170 -0
  278. package/templates/runner/src/render/shapes.ts +68 -0
  279. package/templates/runner/src/render/sky.ts +51 -0
  280. package/templates/runner/src/render/touch-controls.ts +185 -0
  281. package/templates/runner/src/render/worldEnvironment.ts +758 -0
  282. package/templates/runner/src/scenes/Boot.ts +12 -0
  283. package/templates/runner/src/scenes/Run.ts +142 -0
  284. package/templates/runner/src/state.ts +29 -0
  285. package/templates/runner/src/style.css +96 -0
  286. package/templates/runner/src/track.ts +176 -0
  287. package/templates/runner/src/ui/App.tsx +22 -0
  288. package/templates/runner/src/ui/GameUi.tsx +20 -0
  289. package/templates/runner/src/ui/Hud.tsx +55 -0
  290. package/templates/runner/src/ui/Menu.tsx +7 -0
  291. package/templates/runner/src/ui/main.tsx +14 -0
  292. package/templates/runner/tailwind.config.ts +1 -0
  293. package/templates/runner/threenative.config.ts +49 -0
  294. package/templates/runner/tsconfig.json +17 -0
  295. package/templates/runner/vite.config.ts +38 -0
  296. package/templates/sailing/.codex/config.toml +4 -0
  297. package/templates/sailing/.cursor/mcp.json +32 -0
  298. package/templates/sailing/.gemini/settings.json +32 -0
  299. package/templates/sailing/.mcp.json +15 -3
  300. package/templates/sailing/.vscode/mcp.json +36 -0
  301. package/templates/sailing/.zed/settings.json +36 -0
  302. package/templates/sailing/AGENTS.md +62 -355
  303. package/templates/sailing/CLAUDE.md +62 -355
  304. package/templates/sailing/README.md +12 -9
  305. package/templates/sailing/native-playtests/float.playtest.json +55 -0
  306. package/templates/sailing/native-playtests/survives.playtest.json +20 -3
  307. package/templates/sailing/opencode.json +41 -0
  308. package/templates/sailing/package.json +8 -8
  309. package/templates/sailing/playtests/float-after-the-run-ends.playtest.json +75 -0
  310. package/templates/sailing/playtests/float.playtest.json +59 -0
  311. package/templates/sailing/playtests/performance.playtest.json +21 -6
  312. package/templates/sailing/playtests/survives.playtest.json +8 -0
  313. package/templates/sailing/playtests/touch-controls.playtest.json +48 -0
  314. package/templates/sailing/src/conventions.ts +8 -0
  315. package/templates/sailing/src/entities/Ship.ts +150 -13
  316. package/templates/sailing/src/render/camera.ts +15 -8
  317. package/templates/sailing/src/render/lighting.ts +10 -5
  318. package/templates/sailing/src/render/loading.ts +12 -2
  319. package/templates/sailing/src/render/materials.ts +24 -8
  320. package/templates/sailing/src/render/ocean.ts +179 -0
  321. package/templates/sailing/src/render/palette.ts +14 -21
  322. package/templates/sailing/src/render/postprocessing.ts +23 -22
  323. package/templates/sailing/src/render/props.ts +584 -34
  324. package/templates/sailing/src/render/quality.ts +140 -0
  325. package/templates/sailing/src/render/sky.ts +8 -3
  326. package/templates/sailing/src/render/touch-controls.ts +142 -0
  327. package/templates/sailing/src/render/worldEnvironment.ts +206 -38
  328. package/templates/sailing/src/scenes/Sailing.ts +43 -16
  329. package/templates/sailing/src/style.css +20 -0
  330. package/templates/sailing/threenative.config.ts +7 -1
  331. package/templates/shooter/.codex/config.toml +4 -0
  332. package/templates/shooter/.cursor/mcp.json +32 -0
  333. package/templates/shooter/.gemini/settings.json +32 -0
  334. package/templates/shooter/.mcp.json +15 -3
  335. package/templates/shooter/.vscode/mcp.json +36 -0
  336. package/templates/shooter/.zed/settings.json +36 -0
  337. package/templates/shooter/AGENTS.md +76 -415
  338. package/templates/shooter/CLAUDE.md +76 -415
  339. package/templates/shooter/kit.json +2 -2
  340. package/templates/shooter/opencode.json +41 -0
  341. package/templates/shooter/package.json +7 -7
  342. package/templates/shooter/playtests/combat.playtest.json +48 -0
  343. package/templates/shooter/playtests/input-control.playtest.json +165 -35
  344. package/templates/shooter/playtests/per-item.playtest.json +3 -3
  345. package/templates/shooter/playtests/performance.playtest.json +24 -7
  346. package/templates/shooter/playtests/shooter.playtest.json +13 -7
  347. package/templates/shooter/playtests/survives.playtest.json +27 -0
  348. package/templates/shooter/playtests/touch-controls.playtest.json +42 -0
  349. package/templates/shooter/playtests/weapon-cycle.playtest.json +164 -0
  350. package/templates/shooter/src/combat/damage.ts +1 -2
  351. package/templates/shooter/src/conventions.ts +51 -0
  352. package/templates/shooter/src/entities/Player.ts +235 -18
  353. package/templates/shooter/src/entities/Target.ts +2 -2
  354. package/templates/shooter/src/game.ts +13 -4
  355. package/templates/shooter/src/render/camera.ts +49 -39
  356. package/templates/shooter/src/render/decals.ts +211 -0
  357. package/templates/shooter/src/render/lighting.ts +7 -3
  358. package/templates/shooter/src/render/loading.ts +12 -2
  359. package/templates/shooter/src/render/materials.ts +56 -3
  360. package/templates/shooter/src/render/palette.ts +6 -3
  361. package/templates/shooter/src/render/postprocessing.ts +21 -58
  362. package/templates/shooter/src/render/quality.ts +170 -0
  363. package/templates/shooter/src/render/scale.ts +22 -0
  364. package/templates/shooter/src/render/shapes.ts +343 -62
  365. package/templates/shooter/src/render/sky.ts +5 -1
  366. package/templates/shooter/src/render/touch-controls.ts +305 -0
  367. package/templates/shooter/src/render/ui.css +85 -0
  368. package/templates/shooter/src/render/ui.ts +19 -3
  369. package/templates/shooter/src/render/vfx.ts +215 -0
  370. package/templates/shooter/src/render/worldEnvironment.ts +208 -33
  371. package/templates/shooter/src/scenes/Play.ts +171 -56
  372. package/templates/shooter/src/state.ts +5 -0
  373. package/templates/shooter/src/style.css +20 -0
  374. package/templates/shooter/src/ui/Crosshair.tsx +25 -0
  375. package/templates/shooter/src/ui/GameUi.tsx +2 -0
  376. package/templates/shooter/src/ui/Hud.tsx +7 -1
  377. package/templates/shooter/src/weapons/Hitscan.ts +3 -4
  378. package/templates/shooter/src/weapons/Projectile.ts +8 -3
  379. package/templates/shooter/src/weapons/Viewmodel.ts +275 -0
  380. package/templates/shooter/threenative.config.ts +7 -0
  381. package/templates/starter/.codex/config.toml +4 -0
  382. package/templates/starter/.cursor/mcp.json +32 -0
  383. package/templates/starter/.gemini/settings.json +32 -0
  384. package/templates/starter/.mcp.json +15 -3
  385. package/templates/starter/.vscode/mcp.json +36 -0
  386. package/templates/starter/.zed/settings.json +36 -0
  387. package/templates/starter/AGENTS.md +70 -527
  388. package/templates/starter/CLAUDE.md +70 -527
  389. package/templates/starter/native-playtests/render-chain.playtest.json +73 -4
  390. package/templates/starter/opencode.json +41 -0
  391. package/templates/starter/package.json +7 -7
  392. package/templates/starter/playtests/boot-failure.playtest.json +45 -0
  393. package/templates/starter/playtests/look.playtest.json +110 -6
  394. package/templates/starter/playtests/play.playtest.json +3 -2
  395. package/templates/starter/playtests/survives.playtest.json +21 -0
  396. package/templates/starter/playtests/touch-controls.playtest.json +42 -0
  397. package/templates/starter/src/conventions.ts +18 -0
  398. package/templates/starter/src/entities/Goal.ts +18 -3
  399. package/templates/starter/src/entities/Player.ts +72 -9
  400. package/templates/starter/src/game.ts +2 -0
  401. package/templates/starter/src/render/adaptiveQuality.ts +195 -0
  402. package/templates/starter/src/render/camera.ts +1 -1
  403. package/templates/starter/src/render/coast.ts +199 -0
  404. package/templates/starter/src/render/hero.ts +88 -0
  405. package/templates/starter/src/render/implicitSurface.ts +199 -0
  406. package/templates/starter/src/render/kuwahara.ts +174 -0
  407. package/templates/starter/src/render/lighting.ts +4 -4
  408. package/templates/starter/src/render/loading.ts +12 -2
  409. package/templates/starter/src/render/materials.ts +25 -6
  410. package/templates/starter/src/render/outline.ts +141 -0
  411. package/templates/starter/src/render/painterly.ts +86 -0
  412. package/templates/starter/src/render/palette.ts +15 -6
  413. package/templates/starter/src/render/postprocessing.ts +87 -36
  414. package/templates/starter/src/render/quality.ts +185 -0
  415. package/templates/starter/src/render/rockRidge.ts +198 -0
  416. package/templates/starter/src/render/rockRidge.worker.ts +77 -0
  417. package/templates/starter/src/render/scenery.ts +16 -59
  418. package/templates/starter/src/render/textureLifetime.ts +53 -0
  419. package/templates/starter/src/render/touch-controls.ts +165 -0
  420. package/templates/starter/src/render/water.ts +38 -0
  421. package/templates/starter/src/render/watercolor.ts +85 -0
  422. package/templates/starter/src/render/worldEnvironment.ts +208 -33
  423. package/templates/starter/src/scenes/Play.ts +103 -16
  424. package/templates/starter/src/style.css +27 -7
  425. package/templates/starter/threenative.config.ts +7 -7
  426. package/agent-docs/asset-mcp-loop.md +0 -33
  427. package/agent-docs/ctx-surface.md +0 -69
  428. package/agent-docs/engine-capabilities.md +0 -4
  429. package/agent-docs/framework-blocks-you.md +0 -60
  430. package/agent-docs/look-at-it-and-budget-the-look.md +0 -27
  431. package/agent-docs/performance-default.md +0 -42
  432. package/agent-docs/pixel-budget.md +0 -20
  433. package/agent-docs/playtest-fail-closed.md +0 -23
  434. package/agent-docs/sculpt-loop.md +0 -16
  435. package/templates/action-rpg/src/physics.ts +0 -40
  436. package/templates/defense/public/icon.png +0 -0
  437. package/templates/minimal/public/icon.png +0 -0
  438. package/templates/platformer/public/icon.png +0 -0
  439. package/templates/racing/public/icon.png +0 -0
  440. package/templates/sailing/public/icon.png +0 -0
  441. package/templates/sailing/src/render/water-material.ts +0 -14
  442. package/templates/sailing/src/render/water-shaders.ts +0 -12
  443. package/templates/sailing/src/render/wave-nodes.ts +0 -10
  444. package/templates/shooter/public/icon.png +0 -0
  445. package/templates/shooter/src/physics.ts +0 -49
  446. package/templates/starter/public/icon.png +0 -0
  447. /package/{templates/action-rpg/public → template-assets}/icon.png +0 -0
@@ -3,23 +3,284 @@
3
3
 
4
4
  # Capability reference
5
5
 
6
- Every public class and function export of `@threenative/core` and `@threenative/physics`,
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`,
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
+ ## `@threenative/assets`
12
+
13
+ ### `audioPass`
14
+
15
+ `function` — Conditions a game's audio and proves the conditioning did not destroy it.
16
+
17
+ ```ts
18
+ export function audioPass(options: IAudioPassOptions = { … }
19
+ ```
20
+
21
+ - **Use when:** make an ambience bed loop without an audible click · halve what a positional sound effect costs a device's memory · stop an audio asset shipping silent on desktop, Android and iOS
22
+ - **Constraints:** a clip declared a loop has its seam measured on the decoded output bytes and fails the build when it exceeds the threshold; the assertion cannot be declared away · which clips loop, which are positional, and what a clip is for are declared per glob and never inferred from a filename · sources must be RIFF/WAVE or Ogg Vorbis, which is exactly what every native target decodes; an MP3 fails the bake
23
+
24
+ ```ts
25
+ const pass = audioPass({ overrides: [{ glob: "audio/*-bed.ogg", loop: true }] });
26
+ ```
27
+
28
+ ### `compileAssets`
29
+
30
+ `function` — Compiles a project's source assets into content-addressed runtime files and a manifest.
31
+
32
+ ```ts
33
+ export async function compileAssets( options: IAssetCompileOptions = { … }
34
+ ```
35
+
36
+ - **Use when:** compile game assets before a web or native build · optimize textures for the GPU · produce a manifest for runtime asset loading
37
+ - **Constraints:** source and output directories must be disjoint; a pass failure stops the build with the asset path
38
+
39
+ ```ts
40
+ const result = await compileAssets({ source: "assets", output: "public" });
41
+ ```
42
+
43
+ ### `formatAudioSizes`
44
+
45
+ `function` — Formats audio conditioning measurements for a build report.
46
+
47
+ ```ts
48
+ export function formatAudioSizes(rows: readonly IAudioRow[]): readonly string[] { … }
49
+ ```
50
+
51
+ - **Use when:** see what audio conditioning did to a clip's wire and decoded size · read the loop seam and cross-fade a build measured
52
+ - **Constraints:** an empty row list produces no report lines
53
+
54
+ ```ts
55
+ const lines = formatAudioSizes(audioRows);
56
+ ```
57
+
58
+ ### `formatHealthReport`
59
+
60
+ `function` — Formats asset health findings and their summary for human-readable output.
61
+
62
+ ```ts
63
+ export function formatHealthReport(report: IAssetHealthReport): readonly string[] { … }
64
+ ```
65
+
66
+ - **Use when:** print asset size, license, and target findings after compilation · show why an asset health check is warning or failing
67
+ - **Constraints:** the returned lines describe findings; target enforcement happens in runHealthReport
68
+
69
+ ```ts
70
+ const lines = formatHealthReport(report);
71
+ ```
72
+
73
+ ### `formatModelSizes`
74
+
75
+ `function` — Formats model byte, geometry, and embedded-texture measurements for a build report.
76
+
77
+ ```ts
78
+ export function formatModelSizes(rows: readonly IModelSizeRow[]): readonly string[] { … }
79
+ ```
80
+
81
+ - **Use when:** inspect how model optimization changed file and GPU sizes · print model compression results after an asset build
82
+ - **Constraints:** rows must use bytes before and after from the same compiled input
83
+
84
+ ```ts
85
+ const lines = formatModelSizes(modelRows);
86
+ ```
87
+
88
+ ### `formatPassCosts`
89
+
90
+ `function` — Formats per-pass wall-clock costs for a build report.
91
+
92
+ ```ts
93
+ export function formatPassCosts(rows: readonly IPassCostRow[]): readonly string[] { … }
94
+ ```
95
+
96
+ - **Use when:** see which asset pass owns the wall clock after a bake · compare pass costs between two builds before optimizing the pipeline
97
+ - **Constraints:** one row per pass in registry order, per-asset rows sorted by logical path
98
+
99
+ ```ts
100
+ const lines = formatPassCosts(result.passCosts);
101
+ ```
102
+
103
+ ### `formatTextureSizes`
104
+
105
+ `function` — Formats standalone texture byte measurements for a build report.
106
+
107
+ ```ts
108
+ export function formatTextureSizes(rows: readonly ITextureSizeRow[]): readonly string[] { … }
109
+ ```
110
+
111
+ - **Use when:** inspect texture compression savings · print which codec a compiled texture uses
112
+ - **Constraints:** an empty row list produces no report lines
113
+
114
+ ```ts
115
+ const lines = formatTextureSizes(textureRows);
116
+ ```
117
+
118
+ ### `lightmapPass`
119
+
120
+ `function` — Generates lightmap UVs and bakes a static GLB's lightmap atlas.
121
+
122
+ ```ts
123
+ export function lightmapPass(options: ILightmapPassOptions): IAssetPass { … }
124
+ ```
125
+
126
+ - **Use when:** add baked static lighting to a model · generate TEXCOORD_1 data for a lightmapped scene
127
+ - **Constraints:** the input must be a static self-contained GLB with at least one punctual light
128
+
129
+ ```ts
130
+ const pass = lightmapPass({ atlasSize: 1024, padding: 2 });
131
+ ```
132
+
133
+ ### `modelPass`
134
+
135
+ `function` — Optimizes self-contained GLB models through the configured geometry and embedded-texture passes.
136
+
137
+ ```ts
138
+ export function modelPass(options: IModelPassOptions = { … }
139
+ ```
140
+
141
+ - **Use when:** reduce a model's download and GPU footprint · optimize a GLB before shipping it with a game
142
+ - **Constraints:** the pass self-verifies reachable geometry, animation, bounds, and embedded texture bindings before returning output
143
+
144
+ ```ts
145
+ const pass = modelPass({ simplify: { ratio: 0.5 } });
146
+ ```
147
+
148
+ ### `parseAudioConfig`
149
+
150
+ `function` — Validates a game's declared `assets.audio` block, the one place its keys and ranges are checked.
151
+
152
+ ```ts
153
+ export function parseAudioConfig(raw: unknown): IAudioPassOptions | undefined { … }
154
+ ```
155
+
156
+ - **Use when:** validate a threenative.config.ts audio block before compiling assets · ship audio exactly as committed without conditioning it
157
+ - **Constraints:** returns undefined for `"none"`, which drops the audio pass; an absent block returns the defaults · throws TN_ASSETS_CONFIG_INVALID or TN_ASSETS_CONFIG_UNKNOWN_KEY rather than dropping a key it does not know
158
+
159
+ ```ts
160
+ const options = parseAudioConfig({ overrides: [{ glob: "audio/*.ogg", conditioning: "none" }] });
161
+ ```
162
+
163
+ ### `parsePng`
164
+
165
+ `function` — Reads dimensions and alpha metadata from a PNG signature and IHDR header.
166
+
167
+ ```ts
168
+ export function parsePng(value: Buffer): IPngInfo | undefined { … }
169
+ ```
170
+
171
+ - **Use when:** inspect a PNG before choosing a texture codec · read source texture dimensions in an asset health check
172
+ - **Constraints:** non-PNG or truncated bytes return undefined instead of being treated as a valid image
173
+
174
+ ```ts
175
+ const png = parsePng(bytes); if (png !== undefined) console.log(png.width, png.height);
176
+ ```
177
+
178
+ ### `resolveBasisTranscoder`
179
+
180
+ `function` — Finds Three.js's Basis Universal transcoder files for the runtime KTX2 loader.
181
+
182
+ ```ts
183
+ export function resolveBasisTranscoder(cwd: string): IBasisTranscoder { … }
184
+ ```
185
+
186
+ - **Use when:** prepare compressed textures for runtime loading · copy the Basis transcoder into a compiled asset output
187
+ - **Constraints:** the supplied working directory must resolve both basis_transcoder.js and basis_transcoder.wasm from its Three.js installation
188
+
189
+ ```ts
190
+ const transcoder = resolveBasisTranscoder(process.cwd());
191
+ ```
192
+
193
+ ### `runHealthReport`
194
+
195
+ `function` — Measures compiled assets and grades them against declared project targets.
196
+
197
+ ```ts
198
+ export async function runHealthReport( inputs: readonly IAssetHealthInput[], targets: IAssetTargets = { … }
199
+ ```
200
+
201
+ - **Use when:** check asset dimensions, triangles, materials, and licenses · enforce asset budgets during a build
202
+ - **Constraints:** a finding is fail-grade only when the corresponding project target was declared
203
+
204
+ ```ts
205
+ const report = await runHealthReport(inputs, { maxTextureDimension: 2048 });
206
+ ```
207
+
208
+ ### `texturePass`
209
+
210
+ `function` — Encodes standalone textures as mipmapped KTX2/Basis assets for GPU storage.
211
+
212
+ ```ts
213
+ export function texturePass(options: ITexturePassOptions = { … }
214
+ ```
215
+
216
+ - **Use when:** optimize textures for the GPU · compress PNG or JPEG files before runtime loading
217
+ - **Constraints:** compressed source width and height must each be divisible by 4; automatic cooking retains an unaligned source unchanged and reports block-size, while an explicit compression codec override fails · every compressed source width and height must be divisible by 4 because BC7, BC1, ETC2, and ASTC 4x4 use 4x4 blocks; WebGPU rejects an unaligned texture at draw time · automatic cooking retains an unaligned source unchanged and reports block-size; an explicit compression codec override fails, while codec "none" remains available
218
+
219
+ ```ts
220
+ const pass = texturePass({ quality: 150 });
221
+ ```
222
+
223
+ ### `watchAssets`
224
+
225
+ `function` — Watches an asset source directory and recompiles settled changes during development.
226
+
227
+ ```ts
228
+ export function watchAssets(options: IAssetWatchOptions = { … }
229
+ ```
230
+
231
+ - **Use when:** recompile a changed texture without restarting the dev server · see asset pipeline failures as files are saved
232
+ - **Constraints:** call close on the returned handle; initial and burst failures are reported without stopping the dev server
233
+
234
+ ```ts
235
+ const watcher = watchAssets({ cwd: process.cwd() });
236
+ ```
237
+
11
238
  ## `@threenative/core`
12
239
 
240
+ ### `addInSlices`
241
+
242
+ `function` — Attach hundreds of built objects to the scene in slices, presenting a frame between each.
243
+
244
+ ```ts
245
+ export async function addInSlices<T>( objects: Iterable<T>, add: (object: T, index: number) => void, options: IAddInSlicesOptions = { … }
246
+ ```
247
+
248
+ - **Use when:** add hundreds of built objects to the scene without one multi-second frame · stream a detail tier in behind a loading curtain without the page looking hung
249
+ - **Constraints:** the objects, and where each one goes, stay the game's; this decides only when each joins the graph · input order is the attach order and cannot be changed · a false `while` stops the run and is reported as `stopped`, never thrown
250
+ - **Overrides:** sliceSize defaults to 256; `marker: false` silences the TN_ADD_SLICES line, not the report
251
+
252
+ ```ts
253
+ const report = await addInSlices(objects, (object) => ctx.add(object), {
254
+ onProgress: ({ added, total }) => setProgress(added / total),
255
+ while: () => generation.live,
256
+ });
257
+ ```
258
+
259
+ ### `afterPhysics`
260
+
261
+ `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.
262
+
263
+ ```ts
264
+ export function afterPhysics( context: IAfterPhysicsContext, callback: AfterPhysicsCallback, ): () => void { … }
265
+ ```
266
+
267
+ - **Use when:** read a body after physics has moved it · place a camera or aim from the solved character transform
268
+ - **Constraints:** register from a scene context; callbacks are cleared when that scene exits
269
+
270
+ ```ts
271
+ afterPhysics(ctx, (dt) => camera.position.copy(player.mesh.position));
272
+ ```
273
+
13
274
  ### `AnimationPlayer`
14
275
 
15
- `class` — Play a skinned or sprite animation from game code. A travelling 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.
276
+ `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.
16
277
 
17
278
  ```ts
18
279
  export class AnimationPlayer { … }
19
280
  ```
20
281
 
21
- - **Use when:** play an animation on a character · switch a character between idle and attack clips · stop a walking character's feet from sliding or spinning · match a walk or run cycle to how fast a character is moving
22
- - **Constraints:** name the body a game moves as strideRoot when the animated rig is a child of it · a one-shot clip always plays at its authored rate; the matched rate re-times loops only
282
+ - **Use when:** play an animation on a character · switch a character between idle and attack clips · stop a walking character's feet from sliding or spinning · match a walk or run cycle to how fast a character is moving · match an in-place walk cycle with no root motion to the body's speed · find out what speed an animation clip was authored for
283
+ - **Constraints:** name the body a game moves as strideRoot when the animated rig is a child of it · a one-shot clip always plays at its authored rate; the matched rate re-times loops only · the matched rate is held inside 0.15x-3x; a speed outside what the clip's own stride supports is clamped, and `stride.rate` says so
23
284
  - **Overrides:** strideSync controls whether the matched rate is applied while stride is still measured
24
285
 
25
286
  ```ts
@@ -105,6 +366,55 @@ const billboard = new Billboard3D(label, { camera });
105
366
  billboard.update();
106
367
  ```
107
368
 
369
+ ### `boneContact`
370
+
371
+ `function` — Measure whether a named bone reaches the object it is supposed to be touching, in metres.
372
+
373
+ ```ts
374
+ export function boneContact( root: Object3D, boneName: string, target: Object3D, ): IBoneContactReport { … }
375
+ ```
376
+
377
+ - **Use when:** check that a seated character's hands reach the keyboard · check that a character's hips meet the chair it is sitting on · turn "the character is not touching the prop" into a number a scenario can assert
378
+ - **Constraints:** this walks the target's vertices; call it on a check or a debug sample, not every frame
379
+
380
+ ```ts
381
+ import { boneContact } from "@threenative/core";
382
+ const contact = boneContact(worker, "hand_r", keyboard);
383
+ ```
384
+
385
+ ### `boneLengthDeviations`
386
+
387
+ `function` — Compare a rig's bone distances now against a captured snapshot and name every bone that moved.
388
+
389
+ ```ts
390
+ export function boneLengthDeviations( root: Object3D, bind: IBoneLengthSnapshot, options: IBoneLengthDeviationsOptions = { … }
391
+ ```
392
+
393
+ - **Use when:** find out why a skinned character renders deformed · check that an animated pose keeps the skeleton rigid · name the bone that breaks a posed skeleton without taking a screenshot
394
+ - **Constraints:** a rigid skeleton preserves every parent→child distance under any pose; a named bone is a defect with an address · this is a diagnostic — it reports numbers and names; it moves nothing and decides no appearance
395
+
396
+ ```ts
397
+ import { boneLengths, boneLengthDeviations } from "@threenative/core";
398
+ const report = boneLengthDeviations(character, boneLengths(character));
399
+ if (!report.rigid && report.worst !== null) console.log(report.worst.bone, report.worst.ratio);
400
+ ```
401
+
402
+ ### `boneLengths`
403
+
404
+ `function` — Measure a rig's parent→child bone distances, in world space, as it stands right now.
405
+
406
+ ```ts
407
+ export function boneLengths(root: Object3D): IBoneLengthSnapshot { … }
408
+ ```
409
+
410
+ - **Use when:** capture a rig's bind-pose bone lengths before any clip plays · measure a skeleton for the bone-length invariance check
411
+ - **Constraints:** the baseline and the later comparison must come from the same rig under the same ancestor transform, so a uniform scale cancels
412
+
413
+ ```ts
414
+ import { boneLengths } from "@threenative/core";
415
+ const baseline = boneLengths(character);
416
+ ```
417
+
108
418
  ### `CameraShake`
109
419
 
110
420
  `class` — Produce a game-authored camera shake offset for a template-owned camera rig.
@@ -131,7 +441,56 @@ export class CanvasLayer { … }
131
441
  - **Use when:** place a HUD layer above the Three.js scene · attach a canvas layer to a camera
132
442
 
133
443
  ```ts
134
- const hud = new CanvasLayer({ camera });
444
+ const hud = new CanvasLayer(ctx.viewport);
445
+ ```
446
+
447
+ ### `clipBoneCoverage`
448
+
449
+ `function` — Report which bones of a character a clip does not drive.
450
+
451
+ ```ts
452
+ export function clipBoneCoverage(root: Object3D, clip: AnimationClip): IClipCoverageReport { … }
453
+ ```
454
+
455
+ - **Use when:** find out why a character keeps the previous animation's hand shape · check how much of a rig a clip covers before shipping it
456
+ - **Constraints:** a track that binds nothing counts as driving nothing
457
+
458
+ ```ts
459
+ import { clipBoneCoverage } from "@threenative/core";
460
+ const coverage = clipBoneCoverage(character, clip);
461
+ ```
462
+
463
+ ### `clipPoseError`
464
+
465
+ `function` — Score a retargeted clip against the source it came from, per bone, in degrees.
466
+
467
+ ```ts
468
+ export function clipPoseError( subject: IClipPoseSubject, reference: IClipPoseSubject, options: IClipPoseErrorOptions = { … }
469
+ ```
470
+
471
+ - **Use when:** find out why a retargeted animation looks wrong on a character · tell a fixed retarget from one that merely moved · catch a retarget that rolled every limb about its own axis
472
+ - **Constraints:** each bone is compared as a whole quaternion relative to its own rig's bind pose, so the two rigs never have to share a bind convention; a bone-direction check reports zero on the roll this catches · both rigs must face the same way in world space, and both are driven and then restored to the transforms they arrived with
473
+ - **Overrides:** bones maps one rig's bone names onto the other's when they differ; samples sets how many poses are compared
474
+
475
+ ```ts
476
+ import { clipPoseError } from "@threenative/core";
477
+ const report = clipPoseError({ root: rig, clip: retargeted }, { root: source, clip: original });
478
+ ```
479
+
480
+ ### `clipTrackBindings`
481
+
482
+ `function` — Report which of a clip's tracks bind to nothing on a character.
483
+
484
+ ```ts
485
+ export function clipTrackBindings(root: Object3D, clip: AnimationClip): IClipBindingReport { … }
486
+ ```
487
+
488
+ - **Use when:** find out why a character plays its bind pose instead of the animation · check that a loaded clip actually drives the model it was written for
489
+ - **Constraints:** the reason is Three.js's own, captured off its console hook so a scenario's console assertions stay clean
490
+
491
+ ```ts
492
+ import { clipTrackBindings } from "@threenative/core";
493
+ const bindings = clipTrackBindings(character, clip);
135
494
  ```
136
495
 
137
496
  ### `ClusteredBatch`
@@ -184,7 +543,7 @@ export class ComputeDrivenRegistry { … }
184
543
  - **Constraints:** add the object through ctx.add so it attaches, dispatches, and releases with its scene
185
544
 
186
545
  ```ts
187
- class Cloth extends Mesh implements IComputeDriven { ... }
546
+ const registry = new ComputeDrivenRegistry(); registry.add(cloth, ctx.renderer.raw);
188
547
  ```
189
548
 
190
549
  ### `createAssetLoader`
@@ -203,6 +562,23 @@ const assets = createAssetLoader({ basePath: "/assets" });
203
562
  const rock = await assets.texture("rock.png");
204
563
  ```
205
564
 
565
+ ### `createPipelineCensus`
566
+
567
+ `function` — Read the renderer's bounded, versioned pipeline capture in a diagnostic or playtest tool.
568
+
569
+ ```ts
570
+ export function createPipelineCensus(options: IPipelineCensusOptions): PipelineCensus { … }
571
+ ```
572
+
573
+ - **Use when:** inspect shader and pipeline creation work during a real launch · correlate pipeline creation with material, object, pass, and shader identities
574
+ - **Constraints:** the capture is bounded and incomplete when the backend cannot expose an observation
575
+
576
+ ```ts
577
+ const capture = game.runtime.pipelineCensus?.();
578
+ // The game normally reaches this through `runtime.pipelineCensus`; direct construction exists
579
+ // for renderer adapters and contract tests, not for gameplay.
580
+ ```
581
+
206
582
  ### `createRandom`
207
583
 
208
584
  `function` — Create a deterministic random source for portable gameplay.
@@ -231,7 +607,7 @@ export function createReplayDriver( recording: Recording, target: EventTarget, p
231
607
  - **Constraints:** use a seeded random source and fixed-step simulation for meaningful replays
232
608
 
233
609
  ```ts
234
- const driver = createReplayDriver({ recording });
610
+ const driver = createReplayDriver(recording, ctx.renderer.domElement);
235
611
  ```
236
612
 
237
613
  ### `defineGame`
@@ -242,11 +618,11 @@ const driver = createReplayDriver({ recording });
242
618
  export function defineGame<TState extends Record<string, unknown>, TPhysics = undefined>( config: IGameConfig<TState, TPhysics>, ): IGame<TState, TPhysics> { … }
243
619
  ```
244
620
 
245
- - **Use when:** start a ThreeNative game from src/game.ts · register physics and gameplay plugins · let the player zoom the camera with a wheel, pinch, or gamepad axis
621
+ - **Use when:** start a ThreeNative game from src/game.ts · register physics and gameplay plugins · let the player zoom the camera with a wheel, pinch, or gamepad axis · frame a camera behind the player
246
622
  - **Constraints:** keep DOM and React mounting in src/main.ts · bind scroll or pinch and read the intent with ctx.input.axis(name); do not add a window wheel listener · scroll: true uses the DOM wheel sign on browser and native: negative deltaY toward the user is positive intent
247
623
 
248
624
  ```ts
249
- const game = defineGame({ input: { zoom: { scroll: true, pinch: true } }, scenes: { Play } });
625
+ const game = defineGame({ input: { zoom: { scroll: true, pinch: true } }, scenes: { Play }, start: "Play" });
250
626
  ```
251
627
 
252
628
  ### `directionalTransmittance`
@@ -356,7 +732,7 @@ if (isMobile()) showTouchControls();
356
732
  export class GPUParticles3D extends Sprite implements IComputeDriven { … }
357
733
  ```
358
734
 
359
- - **Use when:** emit sparks, smoke, or other transient effects · update many small visual particles · emit cannon smoke and muzzle flash particles · fire a cannonball projectile with cannon smoke particles
735
+ - **Use when:** emit sparks, smoke, or other transient effects · update many small visual particles · trail dust, exhaust, or spray behind a moving object · emit cannon smoke and muzzle flash particles · fire a cannonball projectile with cannon smoke particles
360
736
  - **Constraints:** geometry, color, and timing remain supplied by the game
361
737
 
362
738
  ```ts
@@ -418,7 +794,7 @@ const snap = new GroundSnap(character, { enabled: true });
418
794
  export class InstancedBatch { … }
419
795
  ```
420
796
 
421
- - **Use when:** draw hundreds of repeated props without hundreds of draw calls · place repeated props when the count is not known until the layout has been walked · build a chain, railing, cable, or tie rod out of point-to-point segments
797
+ - **Use when:** draw hundreds of repeated props without hundreds of draw calls · draw thousands of identical instanced blocks or obstacles in one mesh · place repeated props when the count is not known until the layout has been walked · build a chain, railing, cable, or tie rod out of point-to-point segments
422
798
  - **Constraints:** geometry and material are required and come from the game; the batch chooses neither · span stretches along +Y, so its geometry must be unit-height and centred on the origin · placing after build() throws, and build() returns undefined when nothing was placed
423
799
  - **Overrides:** castShadow and receiveShadow pass through to the built mesh and default to Three.js's own false
424
800
 
@@ -488,6 +864,22 @@ export function isWeb(): boolean { … }
488
864
  if (isMobile()) showTouchControls();
489
865
  ```
490
866
 
867
+ ### `loadAll`
868
+
869
+ `function` — Load a list with bounded concurrency, returning results in the input's order.
870
+
871
+ ```ts
872
+ export async function loadAll<TIn, TOut>( items: readonly TIn[], load: (item: TIn, index: number) => Promise<TOut>, options: ILoadAllOptions = { … }
873
+ ```
874
+
875
+ - **Use when:** load many models or textures in parallel instead of one at a time · keep a loading screen moving while a list of assets downloads
876
+ - **Constraints:** results are written to each item's own index and never appended, so a positional lookup finds the same asset on every load · the first rejection rejects the call and no lane starts a load it had not begun
877
+ - **Overrides:** concurrency defaults to 6; `marker: false` silences the TN_LOAD_ALL line, not onProgress
878
+
879
+ ```ts
880
+ const species = await loadAll(names, (name) => ctx.assets.model(`flora/${name}.glb`));
881
+ ```
882
+
491
883
  ### `measureThreePose`
492
884
 
493
885
  `function` — Measure a Three.js pose for grounded or attachment-aware checks.
@@ -503,6 +895,24 @@ export function measureThreePose( object: Object3D, options: IMeasureThreePoseOp
503
895
  const measurement = measureThreePose(model);
504
896
  ```
505
897
 
898
+ ### `mergeParts`
899
+
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.
901
+
902
+ ```ts
903
+ export function mergeParts( parts: Iterable<IMergePart>, options: IMergePartsOptions, ): BufferGeometry { … }
904
+ ```
905
+
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
909
+
910
+ ```ts
911
+ const wall = new Mesh(mergeParts(pieces, { label: "gatehouse" }), stone);
912
+ // pieces are meshes, or { geometry, matrix, color } when the colour is per piece:
913
+ const banner = mergeParts([{ color: 0x8b2f1a, geometry: cloth, matrix: placement }], { label: "banner" });
914
+ ```
915
+
506
916
  ### `normaliseToMetres`
507
917
 
508
918
  `function` — Scale an asset to a real-world measurement and return the applied factor.
@@ -545,7 +955,24 @@ export class PathFollow3D { … }
545
955
  - **Use when:** move an enemy or prop along a patrol path · sample a racing line from a curve
546
956
 
547
957
  ```ts
548
- const follower = new PathFollow3D(curve, { loop: true });
958
+ const follower = new PathFollow3D({ points: patrolPoints, loop: true, speed: 3 });
959
+ ```
960
+
961
+ ### `PipelineCensus`
962
+
963
+ `class` — Read the renderer's bounded, versioned pipeline capture in a diagnostic or playtest tool.
964
+
965
+ ```ts
966
+ export class PipelineCensus { … }
967
+ ```
968
+
969
+ - **Use when:** inspect shader and pipeline creation work during a real launch · correlate pipeline creation with material, object, pass, and shader identities
970
+ - **Constraints:** the capture is bounded and incomplete when the backend cannot expose an observation
971
+
972
+ ```ts
973
+ const capture = game.runtime.pipelineCensus?.();
974
+ // The game normally reaches this through `runtime.pipelineCensus`; direct construction exists
975
+ // for renderer adapters and contract tests, not for gameplay.
549
976
  ```
550
977
 
551
978
  ### `PointerEvents3D`
@@ -556,7 +983,7 @@ const follower = new PathFollow3D(curve, { loop: true });
556
983
  export class PointerEvents3D implements IPointerEvents3D { … }
557
984
  ```
558
985
 
559
- - **Use when:** let the player click on a thing in the world · show a 3D object while a pointer hovers over it · handle touch and mouse taps on a loaded model without naming its child meshes
986
+ - **Use when:** let the player click on a thing in the world · show a 3D object while a pointer hovers over it · handle touch and mouse taps on a loaded model without naming its child meshes · drag a crate or prop with the mouse or a finger
560
987
  - **Constraints:** listeners are side-table registrations; Three.js prototypes are never patched · one raycast serves each active pointer and no raycast runs when nothing is registered
561
988
 
562
989
  ```ts
@@ -612,30 +1039,29 @@ const probes = new ProbeVolume({ bounds, density: 0.5 }); ctx.add(probes); void
612
1039
 
613
1040
  ### `readProbeVolumeObservation`
614
1041
 
615
- `function` — Bake static diffuse irradiance that reaches surfaces from outside the camera view.
1042
+ `function` — Read the most recent observation from a probe volume.
616
1043
 
617
1044
  ```ts
618
1045
  export function readProbeVolumeObservation(value: unknown): IProbeVolumeObservation | undefined { … }
619
1046
  ```
620
1047
 
621
- - **Use when:** light bouncing from a room I cannot see · light a wall with an off-screen emitter
622
- - **Constraints:** request a bake after static geometry and lights are authored; this is static-lighting-first, not fully dynamic relighting · add the volume with ctx.add() so its incremental work is measured in the render phase · call sample() or sampleNode() from a game-owned material before screen-space GI; the volume owns no light, material, or colour
623
- - **Overrides:** density, bounds, bakeBudgetMs, and bounces are game-owned choices
1048
+ - **Use when:** inspect the latest probe bake observation
1049
+ - **Constraints:** the returned observation is a measurement; it does not own lighting or materials
624
1050
 
625
1051
  ```ts
626
- const probes = new ProbeVolume({ bounds, density: 0.5 }); ctx.add(probes); void probes.requestBake(scene);
1052
+ const observation = readProbeVolumeObservation(probes);
627
1053
  ```
628
1054
 
629
1055
  ### `readRenderChainObservation`
630
1056
 
631
- `function` — Compose game-provided render nodes in a measured, fail-closed chain.
1057
+ `function` — 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.
632
1058
 
633
1059
  ```ts
634
1060
  export function readRenderChainObservation( renderer: unknown, ): IRenderChainMarker["applied"] | undefined { … }
635
1061
  ```
636
1062
 
637
- - **Use when:** compose screen-space effects in a canonical order · report which render tier and velocity route actually ran
638
- - **Constraints:** stage factories own colour, strength, and all other appearance choices
1063
+ - **Use when:** compose screen-space effects in a canonical order · insert a game-authored post stage into the measured render chain · report which render tier and velocity route actually ran
1064
+ - **Constraints:** stage factories own colour, strength, and all other appearance choices · authored stages declare exactly one before or after anchor
639
1065
 
640
1066
  ```ts
641
1067
  const chain = new RenderChain(renderer, { input: colour, stages, request: { stages: ["bloom"], tier: "auto" } });
@@ -643,14 +1069,14 @@ const chain = new RenderChain(renderer, { input: colour, stages, request: { stag
643
1069
 
644
1070
  ### `readRenderChainReport`
645
1071
 
646
- `function` — Compose game-provided render nodes in a measured, fail-closed chain.
1072
+ `function` — 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.
647
1073
 
648
1074
  ```ts
649
1075
  export function readRenderChainReport(renderer: unknown): IRenderChainMarker | undefined { … }
650
1076
  ```
651
1077
 
652
- - **Use when:** compose screen-space effects in a canonical order · report which render tier and velocity route actually ran · expose the render tier and dropped-stage reasons to a playtest · inspect whether a temporal pass received velocity
653
- - **Constraints:** stage factories own colour, strength, and all other appearance choices · an absent value means no chain was installed and must fail a chain assertion
1078
+ - **Use when:** compose screen-space effects in a canonical order · insert a game-authored post stage into the measured render chain · report which render tier and velocity route actually ran · expose the render tier and dropped-stage reasons to a playtest · inspect whether a temporal pass received velocity
1079
+ - **Constraints:** stage factories own colour, strength, and all other appearance choices · authored stages declare exactly one before or after anchor · an absent value means no chain was installed and must fail a chain assertion
654
1080
 
655
1081
  ```ts
656
1082
  const chain = new RenderChain(renderer, { input: colour, stages, request: { stages: ["bloom"], tier: "auto" } });
@@ -719,34 +1145,66 @@ renderer.render(scene, camera);
719
1145
  tracker.commit(scene);
720
1146
  ```
721
1147
 
722
- ### `RenderChain`
1148
+ ### `readVirtualShadowMarker`
723
1149
 
724
- `class` — Compose game-provided render nodes in a measured, fail-closed chain.
1150
+ `function` — Parse a `TN_VIRTUAL_SHADOW` console line back into its complete stats, or `undefined`.
725
1151
 
726
1152
  ```ts
727
- export class RenderChain { … }
1153
+ export function readVirtualShadowMarker(line: string): IVirtualShadowStats | undefined { … }
728
1154
  ```
729
1155
 
730
- - **Use when:** compose screen-space effects in a canonical order · report which render tier and velocity route actually ran
731
- - **Constraints:** stage factories own colour, strength, and all other appearance choices
1156
+ - **Use when:** inspect virtual shadow cache and mover counters from a renderer log
1157
+ - **Constraints:** non-marker lines and markers with incomplete or non-numeric stats return `undefined`
732
1158
 
733
1159
  ```ts
734
- const chain = new RenderChain(renderer, { input: colour, stages, request: { stages: ["bloom"], tier: "auto" } });
1160
+ const stats = readVirtualShadowMarker(line);
1161
+ if (stats !== undefined) console.log(stats.reuseRatio);
735
1162
  ```
736
1163
 
737
- ### `replay`
1164
+ ### `reconcileMirroredClips`
738
1165
 
739
- `function` — Record or replay deterministic game input and state.
1166
+ `function` — Repair an exported rig whose animation clips are z-mirrored against its own bind pose.
740
1167
 
741
1168
  ```ts
742
- export function replay< TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined, >(options: IReplayOptions = { … }
1169
+ export function reconcileMirroredClips(root: Object3D, clips: readonly AnimationClip[]): boolean { … }
743
1170
  ```
744
1171
 
745
- - **Use when:** reproduce a gameplay bug from recorded input · run a deterministic replay in a playtest
746
- - **Constraints:** use a seeded random source and fixed-step simulation for meaningful replays
1172
+ - **Use when:** find out why a skinned character renders deformed · repair an imported character that walks backwards with its spine folded · load a rigged GLB through a custom loader and keep the framework's repair
1173
+ - **Constraints:** the model loader already applies this automatically; only a game loading GLBs around it needs the call · detection votes per tracked bone and converts only on an overwhelming signature; a file that does not carry it is left byte-identical
747
1174
 
748
1175
  ```ts
749
- const driver = createReplayDriver({ recording });
1176
+ import { reconcileMirroredClips } from "@threenative/core";
1177
+ if (reconcileMirroredClips(gltf.scene, gltf.animations)) console.info("clips were z-mirrored; repaired");
1178
+ ```
1179
+
1180
+ ### `RenderChain`
1181
+
1182
+ `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.
1183
+
1184
+ ```ts
1185
+ export class RenderChain { … }
1186
+ ```
1187
+
1188
+ - **Use when:** compose screen-space effects in a canonical order · insert a game-authored post stage into the measured render chain · report which render tier and velocity route actually ran
1189
+ - **Constraints:** stage factories own colour, strength, and all other appearance choices · authored stages declare exactly one before or after anchor
1190
+
1191
+ ```ts
1192
+ const chain = new RenderChain(renderer, { input: colour, stages, request: { stages: ["bloom"], tier: "auto" } });
1193
+ ```
1194
+
1195
+ ### `replay`
1196
+
1197
+ `function` — Record or replay deterministic game input and state.
1198
+
1199
+ ```ts
1200
+ export function replay< TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined, >(options: IReplayOptions = { … }
1201
+ ```
1202
+
1203
+ - **Use when:** reproduce a gameplay bug from recorded input · run a deterministic replay in a playtest
1204
+ - **Constraints:** use a seeded random source and fixed-step simulation for meaningful replays
1205
+
1206
+ ```ts
1207
+ const driver = createReplayDriver(recording, ctx.renderer.domElement);
750
1208
  ```
751
1209
 
752
1210
  ### `resolveAtmosphereLutResolutions`
@@ -806,7 +1264,7 @@ export class ScenePicker { … }
806
1264
  - **Supersedes (writing this fails `pnpm budgets`):** new Raycaster(
807
1265
 
808
1266
  ```ts
809
- const picker = new ScenePicker({ camera, scene });
1267
+ const picker = new ScenePicker({ camera: ctx.camera, scene: ctx.scene, pointer: () => ctx.input.raw.pointer, viewport: ctx.viewport });
810
1268
  ```
811
1269
 
812
1270
  ### `Scheduler`
@@ -825,6 +1283,28 @@ const door = { y: 0 };
825
1283
  await ctx.tween(door, { y: 2.4 }, 0.5, { ease: (t) => 1 - (1 - t) ** 3 });
826
1284
  ```
827
1285
 
1286
+ ### `SkeletalMesh3D`
1287
+
1288
+ `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.
1289
+
1290
+ ```ts
1291
+ export class SkeletalMesh3D extends AnimationPlayer { … }
1292
+ ```
1293
+
1294
+ - **Use when:** put an animated character in the scene · my imported character renders deformed · instance an imported rigged character · validate animation clips on a character rig at load time · prepare a skinned character with safe skeleton cloning and stride sync
1295
+ - **Constraints:** use strideRoot to name the body moved by game code when the rig is parented under it · requiredClips fails closed at load time if any requested clip is missing or binds 0 tracks
1296
+ - **Overrides:** strideSync controls whether locomotion playback rate matches ground covered · size normalises the instance to real-world metres with skin-aware measurement
1297
+
1298
+ ```ts
1299
+ import { SkeletalMesh3D } from "@threenative/core";
1300
+ const character = new SkeletalMesh3D({
1301
+ source: gltf.scene, clips: gltf.animations, requiredClips: ["idle", "walk"],
1302
+ size: { metres: 1.8, axis: "height" }, strideRoot: body,
1303
+ });
1304
+ body.add(character.root); character.play("idle");
1305
+ function update(dt: number): void { character.update(dt); }
1306
+ ```
1307
+
828
1308
  ### `skeletonBones`
829
1309
 
830
1310
  `function` — List the names of every bone in a character hierarchy.
@@ -879,7 +1359,7 @@ const puff = softCircleDataTexture(64, 0.25);
879
1359
  export function solarPosition(input: ISolarPositionInput, target?: ISolarPosition): ISolarPosition;
880
1360
  ```
881
1361
 
882
- - **Use when:** move a sun across a real day at a game's latitude and longitude
1362
+ - **Use when:** move a sun across a real day at a game's latitude and longitude · run a day and night cycle over the game's sky
883
1363
  - **Constraints:** dates are interpreted as UTC unless utcOffset is supplied; no fixed sun direction is assumed · pass a mutable { azimuth, elevation } target to reuse the result object in a steady frame loop
884
1364
 
885
1365
  ```ts
@@ -1018,6 +1498,24 @@ renderer.render(scene, camera);
1018
1498
  tracker.commit(scene);
1019
1499
  ```
1020
1500
 
1501
+ ### `VirtualShadowNode`
1502
+
1503
+ `class` — One directional shadow for a whole open world: camera-centred clip levels, each snapped to its own texel grid and re-rendered only when its window moves. Tracked casters draw into a per-level mover map every frame, so animated casters do not invalidate the cached levels after the one refresh caused by tracking or untracking them. Plugs into three's own `light.shadow.shadowNode` slot, so every material receives it.
1504
+
1505
+ ```ts
1506
+ export class VirtualShadowNode extends ShadowBaseNode { … }
1507
+ ```
1508
+
1509
+ - **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
1511
+ - **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
+
1513
+ ```ts
1514
+ const sun = new DirectionalLight(0xffffff, 3);
1515
+ sun.castShadow = true;
1516
+ sun.shadow.shadowNode = new VirtualShadowNode(sun, { clipExtents: [12, 40, 120] });
1517
+ ```
1518
+
1021
1519
  ### `warmUpScene`
1022
1520
 
1023
1521
  `function` — Warms up `scene` for `camera`, in slices, presenting a frame between each. Fail closed on a nonsensical slice size rather than quietly choosing one: a zero or negative slice would loop forever, and a caller that passed it has a bug worth seeing now.
@@ -1032,6 +1530,22 @@ export async function warmUpScene( renderer: IWarmUpRenderer, scene: Object3D, c
1032
1530
  await warmUpScene(renderer, scene, camera, { onProgress: (p) => setLoading(p) });
1033
1531
  ```
1034
1532
 
1533
+ ### `WaterSurface3D`
1534
+
1535
+ `class` — Give a horizontal water surface the world mirrored in it, the world beneath it, and the metres of water between them.
1536
+
1537
+ ```ts
1538
+ export class WaterSurface3D { … }
1539
+ ```
1540
+
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
1543
+
1544
+ ```ts
1545
+ const surface = new WaterSurface3D({ level: 0, maxThickness: 3, reflection: { resolutionScale: 0.5 } });
1546
+ material.colorNode = mix(surface.refractionAt(offset), surface.reflectionAt(offset), fresnel);
1547
+ ```
1548
+
1035
1549
  ### `WaveField`
1036
1550
 
1037
1551
  `class` — Evaluate analytic waves on CPU and displace game-owned vertices with the matching TSL graph.
@@ -1116,6 +1630,24 @@ export function assertPortableState(state: unknown): void { … }
1116
1630
  assertPortableState(game.state.getState());
1117
1631
  ```
1118
1632
 
1633
+ ## `@threenative/core/net`
1634
+
1635
+ ### `connect`
1636
+
1637
+ `function` — Open a bounded, authenticated WebTransport message channel shared by browser and native games.
1638
+
1639
+ ```ts
1640
+ export function connect(url: string, options: INetworkOptions): Promise<INetworkConnection> { … }
1641
+ ```
1642
+
1643
+ - **Use when:** connect two game clients over the portable WebTransport seam · send ordered actions and bounded unreliable state messages between game clients · exchange multiplayer messages without putting replication or gameplay in the engine
1644
+ - **Constraints:** the URL must use HTTPS and the credential is supplied by the game's identity flow; this API never issues credentials · channels, message sizes, and queues are validated before WebTransport opens, and reliable overflow returns false · native qualification depends on the installed host WebTransport bridge; iOS remains unverified
1645
+ - **Overrides:** connectTimeoutMs, maxReliableMessageBytes, maxQueuedReliableBytes, and maxQueuedDatagrams are named per-connection limits
1646
+
1647
+ ```ts
1648
+ const connection = await connect("https://game.example/game", { applicationProtocol: "my-game/1", credential, channels: [{ id: 1, delivery: "unreliable" }] });
1649
+ ```
1650
+
1119
1651
  ## `@threenative/core/playtest`
1120
1652
 
1121
1653
  ### `playtest`
@@ -1217,7 +1749,7 @@ export function View(props: IViewProps): ReactNode { … }
1217
1749
  - **Use when:** group and position native React HUD elements
1218
1750
 
1219
1751
  ```ts
1220
- <View style={{ centerX: 0, top: 24 }}><Text>READY</Text></View>
1752
+ <View style={{ centerX: true, top: 24 }}><Text>READY</Text></View>
1221
1753
  ```
1222
1754
 
1223
1755
  ## `@threenative/core/ui-layer`
@@ -1314,15 +1846,31 @@ const mirror = subscribeUiState(bridge);
1314
1846
 
1315
1847
  ## `@threenative/core/world`
1316
1848
 
1849
+ ### `getWorldCapabilities`
1850
+
1851
+ `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.
1852
+
1853
+ ```ts
1854
+ export function getWorldCapabilities(options: IWorldCapabilitiesOptions = { … }
1855
+ ```
1856
+
1857
+ - **Use when:** decide whether generated terrain can use GPU compute · report why terrain generation is using a reduced CPU fallback
1858
+ - **Constraints:** unsupported is returned when compute limits are unknown or below the requirement; callers must not silently continue
1859
+ - **Overrides:** minimumWorkgroupsPerDimension, minimumStorageBufferBindingSize, and cpuFallbackIterations
1860
+
1861
+ ```ts
1862
+ const capabilities = getWorldCapabilities({ limits: adapter.limits, cpuFallbackIterations: 8 });
1863
+ ```
1864
+
1317
1865
  ### `Heightfield`
1318
1866
 
1319
1867
  `class` — One height buffer shared by world queries, rendered geometry, and a physics heightfield. The game supplies every value, so changing the terrain's shape never requires a package edit. `fromSampler` evaluates that game function exactly once at each vertex and retains only the resulting numbers. Queries interpolate those same numbers instead of evaluating the function again.
1320
1868
 
1321
1869
  ```ts
1322
- export class Heightfield { … }
1870
+ export class Heightfield extends Group implements IComputeDriven { … }
1323
1871
  ```
1324
1872
 
1325
- - **Use when:** build terrain geometry and collision from one game-authored height function · query the same ground height or normal that a player sees and collides with · build islands and coastlines from terrain
1873
+ - **Use when:** build terrain geometry and collision from one game-authored height function · generate a terrain a player can walk across · query the same ground height or normal that a player sees and collides with · ask how high the ground is here · build islands and coastlines from terrain
1326
1874
  - **Constraints:** sampleHeight owns the terrain shape and stays in game source; the framework stores and interpolates its output · rows and columns are vertex counts; geometry is row-major z-then-x and collider export transposes once into Rapier's column-major matrix order
1327
1875
  - **Overrides:** rows, columns, width, depth, origin, and sampleHeight are explicit on every field
1328
1876
 
@@ -1330,6 +1878,22 @@ export class Heightfield { … }
1330
1878
  const field = Heightfield.fromSampler({ rows: 65, columns: 65, width: 64, depth: 64, origin: { x: 0, z: 0 }, sampleHeight: terrainHeight });
1331
1879
  ```
1332
1880
 
1881
+ ### `TerrainTiles`
1882
+
1883
+ `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.
1884
+
1885
+ ```ts
1886
+ export class TerrainTiles extends Object3D implements IComputeDriven { … }
1887
+ ```
1888
+
1889
+ - **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
1892
+
1893
+ ```ts
1894
+ const tiles = new TerrainTiles({ sampleHeight, surface: gameSurface(), tileSize: 256, tileResolution: 129, residentTileBudget: 25, residentByteBudget: 32_000_000 });
1895
+ ```
1896
+
1333
1897
  ## `@threenative/physics`
1334
1898
 
1335
1899
  ### `Area3D`
@@ -1344,7 +1908,22 @@ export class Area3D { … }
1344
1908
  - **Constraints:** add the area to the physics context before stepping the world
1345
1909
 
1346
1910
  ```ts
1347
- const area = new Area3D({ context, shape });
1911
+ const goal = new Area3D({ physics: ctx.physics, shape: CollisionShape3D.sphere(1.2), position: { x: 0, y: 0.5, z: -8 } });
1912
+ ```
1913
+
1914
+ ### `buildStaticColliders`
1915
+
1916
+ `function` — Build fixed trimesh bodies from the meshes a game authored in a scene root.
1917
+
1918
+ ```ts
1919
+ export function buildStaticColliders( context: IStaticColliderContext, root: Object3D, filter?: StaticColliderFilter, ): readonly RigidBody3D[] { … }
1920
+ ```
1921
+
1922
+ - **Use when:** make the level I built stop the player · turn a cathedral or map scene into static collision
1923
+ - **Constraints:** supply the game-owned predicate for decorative meshes; the helper throws when it selects nothing · generated bodies use trimesh geometry and world-space instance transforms
1924
+
1925
+ ```ts
1926
+ const colliders = buildStaticColliders(ctx, level, { predicate: (object) => object.name.startsWith("wall") });
1348
1927
  ```
1349
1928
 
1350
1929
  ### `Buoyancy3D`
@@ -1375,7 +1954,7 @@ export class CharacterBody3D { … }
1375
1954
  - **Constraints:** use moveAndSlide inside the physics update
1376
1955
 
1377
1956
  ```ts
1378
- const body = new CharacterBody3D({ context, object });
1957
+ const body = new CharacterBody3D({ object: hero, physics: ctx.physics, shape: CollisionShape3D.capsule(0.5, 0.35) });
1379
1958
  ```
1380
1959
 
1381
1960
  ### `CollisionShape3D`
@@ -1390,7 +1969,7 @@ export class CollisionShape3D { … }
1390
1969
  - **Constraints:** create shapes through the owning physics context
1391
1970
 
1392
1971
  ```ts
1393
- const shape = new CollisionShape3D({ context, shape: "capsule" });
1972
+ const shape = CollisionShape3D.capsule(0.5, 0.35);
1394
1973
  ```
1395
1974
 
1396
1975
  ### `interactionGroups`
@@ -1415,11 +1994,11 @@ const groups = interactionGroups(1, 3);
1415
1994
  export class Joint3D { … }
1416
1995
  ```
1417
1996
 
1418
- - **Use when:** constrain a rigid body to another body · build a hinge or pin mechanism
1997
+ - **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
1419
1998
  - **Constraints:** both bodies must belong to the same physics context
1420
1999
 
1421
2000
  ```ts
1422
- const joint = new Joint3D({ context, kind: "hinge" });
2001
+ 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 } });
1423
2002
  ```
1424
2003
 
1425
2004
  ### `PhysicsDirectSpaceState3D`
@@ -1460,11 +2039,12 @@ const game = defineGame({ plugins: [rapier()] });
1460
2039
  export class RigidBody3D { … }
1461
2040
  ```
1462
2041
 
1463
- - **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
2042
+ - **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
1464
2043
  - **Constraints:** register rapier() in the game plugin list before using bodies
2044
+ - **Overrides:** continuousCollision: false opts one body out while body.continuousCollision still reports the effective setting
1465
2045
 
1466
2046
  ```ts
1467
- const crate = new RigidBody3D({ context, object, mode: "dynamic" });
2047
+ const crate = new RigidBody3D({ object, physics: ctx.physics, shape: CollisionShape3D.box(1, 1, 1), mass: 8 });
1468
2048
  ```
1469
2049
 
1470
2050
  ### `softBodyCollision`
@@ -1741,7 +2321,7 @@ export function playtestDiagnostic( code: PlaytestDiagnosticCode, message: strin
1741
2321
  - **Use when:** report a named runtime diagnostic to a scenario · explain why a playtest assertion cannot pass
1742
2322
 
1743
2323
  ```ts
1744
- playtestDiagnostic("physics", "body missing");
2324
+ playtestDiagnostic("TN_PLAYTEST_CAPABILITY_MISSING", "body missing", "register rapier() before adding bodies");
1745
2325
  ```
1746
2326
 
1747
2327
  ### `PlaytestScenarioError`
@@ -1809,7 +2389,7 @@ const scenario = await loadPlaytestScenario(project, file);
1809
2389
  `function` — Evaluate rich semantic assertions against captured observations.
1810
2390
 
1811
2391
  ```ts
1812
- export function requiredPlaytestCapabilities(scenario: IPlaytestScenario): PlaytestCapability[] { … }
2392
+ export function requiredPlaytestCapabilities( scenario: IPlaytestScenario, target?: string, ): PlaytestCapability[] { … }
1813
2393
  ```
1814
2394
 
1815
2395
  - **Use when:** assert movement, visibility, or diagnostics in a playtest · turn a scenario observation into a pass or failure
@@ -1824,7 +2404,7 @@ const result = evaluateRichPlaytestAssertions(input);
1824
2404
  `function` — Resolve the effective diagnostics policy for a run, with fail-closed defaults applied.
1825
2405
 
1826
2406
  ```ts
1827
- export function resolveDiagnosticsPolicy( policy: IPlaytestDiagnosticsAssertion | undefined, ): IPlaytestDiagnosticsPolicy { … }
2407
+ export function resolveDiagnosticsPolicy( policy: IPlaytestDiagnosticsAssertion | undefined, target?: string, ): IPlaytestDiagnosticsPolicy { … }
1828
2408
  ```
1829
2409
 
1830
2410
  - **Use when:** judge captured console, network, or runtime diagnostics for a playtest
@@ -1983,7 +2563,7 @@ export function advanceTimeoutMs( ticks: number, perTickMs: number = PLAYTEST_AD
1983
2563
  - **Constraints:** the bridge must answer the handshake or the run fails
1984
2564
 
1985
2565
  ```ts
1986
- const bridge = await connectPlaytestBridge(page);
2566
+ const bridge = await connectPlaytestBridge(page, scenario);
1987
2567
  ```
1988
2568
 
1989
2569
  ### `androidMailboxPaths`
@@ -2058,7 +2638,7 @@ export function bridgeWaitTimeoutMs( operationMs: number = PLAYTEST_PROTOCOL_LIM
2058
2638
  - **Constraints:** the bridge must answer the handshake or the run fails
2059
2639
 
2060
2640
  ```ts
2061
- const bridge = await connectPlaytestBridge(page);
2641
+ const bridge = await connectPlaytestBridge(page, scenario);
2062
2642
  ```
2063
2643
 
2064
2644
  ### `buildReport`
@@ -2103,7 +2683,7 @@ export async function connectPlaytestBridge( page: Page, scenario: IPlaytestScen
2103
2683
  - **Constraints:** the bridge must answer the handshake or the run fails
2104
2684
 
2105
2685
  ```ts
2106
- const bridge = await connectPlaytestBridge(page);
2686
+ const bridge = await connectPlaytestBridge(page, scenario);
2107
2687
  ```
2108
2688
 
2109
2689
  ### `connectPlaytestBridgeTransport`
@@ -2111,14 +2691,14 @@ const bridge = await connectPlaytestBridge(page);
2111
2691
  `function` — Connect a Playwright page to a playtest bridge.
2112
2692
 
2113
2693
  ```ts
2114
- export async function connectPlaytestBridgeTransport( transport: IBridgeTransport, scenario: IPlaytestScenario, timeoutMs: number = bridgeWaitTimeoutMs(), ): Promise<IPlaytestBridgeClient | undefined> { … }
2694
+ export async function connectPlaytestBridgeTransport( transport: IBridgeTransport, scenario: IPlaytestScenario, timeoutMs: number = bridgeWaitTimeoutMs(), target?: string, ): Promise<IPlaytestBridgeClient | undefined> { … }
2115
2695
  ```
2116
2696
 
2117
2697
  - **Use when:** run a browser scenario against a game · inspect bridge diagnostics from a runner
2118
2698
  - **Constraints:** the bridge must answer the handshake or the run fails
2119
2699
 
2120
2700
  ```ts
2121
- const bridge = await connectPlaytestBridge(page);
2701
+ const bridge = await connectPlaytestBridge(page, scenario);
2122
2702
  ```
2123
2703
 
2124
2704
  ### `DesktopPlaytestDriver`
@@ -2226,6 +2806,21 @@ export function failedDiagnosticsAssertion(policy: IPlaytestDiagnosticsPolicy):
2226
2806
  const report = await runStandalonePlaytest(options);
2227
2807
  ```
2228
2808
 
2809
+ ### `formatPipelineSummary`
2810
+
2811
+ `function` — Parse and explain bounded shader-compilation captures.
2812
+
2813
+ ```ts
2814
+ export function formatPipelineSummary(summary: IPipelineSummary): string { … }
2815
+ ```
2816
+
2817
+ - **Use when:** diagnose a slow shader-heavy launch from one browser or native capture · reconcile pipeline creation counts and compile timing
2818
+ - **Constraints:** incomplete or malformed captures never become a successful empty report
2819
+
2820
+ ```ts
2821
+ summarizePipelineCapture(parsePipelineCapture(captureText));
2822
+ ```
2823
+
2229
2824
  ### `formatUsage`
2230
2825
 
2231
2826
  `function` — Parse standalone playtest runner configuration.
@@ -2376,6 +2971,21 @@ export function parseAndroidConsole(output: string): Array< { … }
2376
2971
  const adb = discoverAdb(process.env);
2377
2972
  ```
2378
2973
 
2974
+ ### `parseAndroidTouchViewport`
2975
+
2976
+ `function` — Drive and inspect Android playtest transport.
2977
+
2978
+ ```ts
2979
+ export function parseAndroidTouchViewport(output: string): IAndroidTouchViewport { … }
2980
+ ```
2981
+
2982
+ - **Use when:** run a scenario on an Android emulator or device · parse Android console diagnostics
2983
+ - **Constraints:** Android evidence must name its target and transport
2984
+
2985
+ ```ts
2986
+ const adb = discoverAdb(process.env);
2987
+ ```
2988
+
2379
2989
  ### `parseLaunchedPid`
2380
2990
 
2381
2991
  `function` — Drive and inspect iOS simulator playtest transport.
@@ -2391,6 +3001,36 @@ export function parseLaunchedPid(output: string): string { … }
2391
3001
  const driver = new XcrunIosDriver(options);
2392
3002
  ```
2393
3003
 
3004
+ ### `parsePipelineCapture`
3005
+
3006
+ `function` — Parse and explain bounded shader-compilation captures.
3007
+
3008
+ ```ts
3009
+ export function parsePipelineCapture(input: string | unknown): IPipelineCapture { … }
3010
+ ```
3011
+
3012
+ - **Use when:** diagnose a slow shader-heavy launch from one browser or native capture · reconcile pipeline creation counts and compile timing
3013
+ - **Constraints:** incomplete or malformed captures never become a successful empty report
3014
+
3015
+ ```ts
3016
+ summarizePipelineCapture(parsePipelineCapture(captureText));
3017
+ ```
3018
+
3019
+ ### `parsePipelineEventMarkers`
3020
+
3021
+ `function` — Parse and explain bounded shader-compilation captures.
3022
+
3023
+ ```ts
3024
+ export function parsePipelineEventMarkers(text: string): IPipelineCaptureEvent[] { … }
3025
+ ```
3026
+
3027
+ - **Use when:** diagnose a slow shader-heavy launch from one browser or native capture · reconcile pipeline creation counts and compile timing
3028
+ - **Constraints:** incomplete or malformed captures never become a successful empty report
3029
+
3030
+ ```ts
3031
+ summarizePipelineCapture(parsePipelineCapture(captureText));
3032
+ ```
3033
+
2394
3034
  ### `parseStandalonePlaytestArgs`
2395
3035
 
2396
3036
  `function` — Parse standalone playtest runner configuration.
@@ -2418,7 +3058,7 @@ export class PlaytestBridgeError extends Error { … }
2418
3058
  - **Constraints:** the bridge must answer the handshake or the run fails
2419
3059
 
2420
3060
  ```ts
2421
- const bridge = await connectPlaytestBridge(page);
3061
+ const bridge = await connectPlaytestBridge(page, scenario);
2422
3062
  ```
2423
3063
 
2424
3064
  ### `PlaytestCliUsageError`
@@ -2463,7 +3103,7 @@ export class PlaywrightTransport implements IBridgeTransport { … }
2463
3103
  - **Constraints:** the bridge must answer the handshake or the run fails
2464
3104
 
2465
3105
  ```ts
2466
- const bridge = await connectPlaytestBridge(page);
3106
+ const bridge = await connectPlaytestBridge(page, scenario);
2467
3107
  ```
2468
3108
 
2469
3109
  ### `preflightDisplay`
@@ -2706,6 +3346,21 @@ export function substituteManagedPort(command: string, port: number): string {
2706
3346
  const report = await runStandalonePlaytest(options);
2707
3347
  ```
2708
3348
 
3349
+ ### `summarizePipelineCapture`
3350
+
3351
+ `function` — Parse and explain bounded shader-compilation captures.
3352
+
3353
+ ```ts
3354
+ export function summarizePipelineCapture(capture: IPipelineCapture): IPipelineSummary { … }
3355
+ ```
3356
+
3357
+ - **Use when:** diagnose a slow shader-heavy launch from one browser or native capture · reconcile pipeline creation counts and compile timing
3358
+ - **Constraints:** incomplete or malformed captures never become a successful empty report
3359
+
3360
+ ```ts
3361
+ summarizePipelineCapture(parsePipelineCapture(captureText));
3362
+ ```
3363
+
2709
3364
  ### `tapCommand`
2710
3365
 
2711
3366
  `function` — Drive and inspect Android playtest transport.
@@ -2721,6 +3376,21 @@ export function tapCommand(x: number, y: number): string[] { … }
2721
3376
  const adb = discoverAdb(process.env);
2722
3377
  ```
2723
3378
 
3379
+ ### `touchPositionForViewport`
3380
+
3381
+ `function` — Drive and inspect Android playtest transport.
3382
+
3383
+ ```ts
3384
+ export function touchPositionForViewport( x: number, y: number, viewport: IAndroidTouchViewport, rotationOverride?: number, ): [number, number] { … }
3385
+ ```
3386
+
3387
+ - **Use when:** run a scenario on an Android emulator or device · parse Android console diagnostics
3388
+ - **Constraints:** Android evidence must name its target and transport
3389
+
3390
+ ```ts
3391
+ const adb = discoverAdb(process.env);
3392
+ ```
3393
+
2724
3394
  ### `touchRotationFromWindowDump`
2725
3395
 
2726
3396
  `function` — Drive and inspect Android playtest transport.
@@ -2766,6 +3436,21 @@ export function viewportPresentationCommands( viewport: { … }
2766
3436
  const adb = discoverAdb(process.env);
2767
3437
  ```
2768
3438
 
3439
+ ### `viewportPresentationObserved`
3440
+
3441
+ `function` — Drive and inspect Android playtest transport.
3442
+
3443
+ ```ts
3444
+ export function viewportPresentationObserved( override: string | undefined, expected: string | undefined, physical: { … }
3445
+ ```
3446
+
3447
+ - **Use when:** run a scenario on an Android emulator or device · parse Android console diagnostics · verify that an Android device presented the requested viewport · accept the physical panel size when `wm size` omits its override line
3448
+ - **Constraints:** Android evidence must name its target and transport
3449
+
3450
+ ```ts
3451
+ const adb = discoverAdb(process.env);
3452
+ ```
3453
+
2769
3454
  ### `viewportRestoreCommands`
2770
3455
 
2771
3456
  `function` — Drive and inspect Android playtest transport.
@@ -2855,7 +3540,7 @@ export function connectDevicePlaytestBridge( bridge: IPlaytestBridgeV1, endpoint
2855
3540
  - **Constraints:** use the device transport selected by the runner
2856
3541
 
2857
3542
  ```ts
2858
- const connection = await connectDevicePlaytestBridge();
3543
+ const connection = connectDevicePlaytestBridge(bridge, endpoint);
2859
3544
  ```
2860
3545
 
2861
3546
  ### `installThreePlaytestBridge`
@@ -2873,6 +3558,21 @@ export function installThreePlaytestBridge(options: IThreePlaytestBridgeOptions)
2873
3558
  const bridge = installThreePlaytestBridge(options);
2874
3559
  ```
2875
3560
 
3561
+ ### `observeSceneResources`
3562
+
3563
+ `function` — Observe the room a game is played in — lights, materials, fog, background and camera framing.
3564
+
3565
+ ```ts
3566
+ export function observeSceneResources(scene: Scene, camera: Camera): IPlaytestSceneObservation { … }
3567
+ ```
3568
+
3569
+ - **Use when:** ask why a frame is black or washed out without opening a screenshot · ask what lights, materials and framing a running game actually has
3570
+ - **Constraints:** reports counts and names only; it decides nothing about how the game looks · reports counts and names only; nothing here decides how the game looks · a walk that hits {@link SCENE_WALK_OBJECT_CAP} reports `truncated: true`
3571
+
3572
+ ```ts
3573
+ const room = observeSceneResources(scene, camera);
3574
+ ```
3575
+
2876
3576
  ### `readPlaytestEndpoint`
2877
3577
 
2878
3578
  `function` — Connect a device-hosted game to the playtest bridge.
@@ -2885,7 +3585,7 @@ export function readPlaytestEndpoint(): string | undefined { … }
2885
3585
  - **Constraints:** use the device transport selected by the runner
2886
3586
 
2887
3587
  ```ts
2888
- const connection = await connectDevicePlaytestBridge();
3588
+ const connection = connectDevicePlaytestBridge(bridge, endpoint);
2889
3589
  ```
2890
3590
 
2891
3591
  ### `ThreePlaytestPhysicsRecorder`
@@ -2900,7 +3600,345 @@ export class ThreePlaytestPhysicsRecorder { … }
2900
3600
  - **Constraints:** keep recorder limits within the documented caps
2901
3601
 
2902
3602
  ```ts
2903
- const physics = new ThreePlaytestPhysicsRecorder();
3603
+ const physics = new ThreePlaytestPhysicsRecorder(worldPhysics);
3604
+ ```
3605
+
3606
+ ## `@threenative/raw-unreal`
3607
+
3608
+ ### `createThreeGeometry`
3609
+
3610
+ `function` — Converts a decoded `.uasset` static mesh into a `THREE.BufferGeometry`, with one draw group per material section.
3611
+
3612
+ ```ts
3613
+ export function createThreeGeometry(decoded: IDecodedUAssetStaticMesh): BufferGeometry { … }
3614
+ ```
3615
+
3616
+ - **Use when:** build custom scene objects from Unreal mesh data instead of a whole mesh · hand a decoded Unreal mesh to a framework pipeline that owns materials itself
3617
+ - **Constraints:** materials are never chosen here; the geometry carries groups, the game carries materials
3618
+ - **Requires:** npm i @threenative/raw-unreal
3619
+
3620
+ ```ts
3621
+ const geometry = createThreeGeometry(parseUAssetStaticMesh(buffer));
3622
+ ```
3623
+
3624
+ ### `createThreeObject`
3625
+
3626
+ `function` — Converts a decoded `.uasset` static mesh into a renderable `THREE.Mesh` with provenance in `userData.unreal` and material selection left to the game's `materialFactory`.
3627
+
3628
+ ```ts
3629
+ export function createThreeObject( decoded: IDecodedUAssetStaticMesh, options: IThreeAdapterOptions = { … }
3630
+ ```
3631
+
3632
+ - **Use when:** put a raw .uasset mesh on screen without converting it to glTF first · key materials to a package's own sections by name or section index
3633
+ - **Constraints:** the fallback is three.js's own plain MeshStandardMaterial; every real material comes from the game
3634
+ - **Requires:** npm i @threenative/raw-unreal
3635
+
3636
+ ```ts
3637
+ const mesh = createThreeObject(decoded, { materialFactory: (d) => d.sections.map(() => barkMaterial) });
3638
+ ```
3639
+
3640
+ ### `decompressBulkData`
3641
+
3642
+ `function` — Reads the `FByteBulkData` headers an editor package serializes into its export data, and resolves each payload — inline, at the end of the package, or in a sibling `.ubulk`/`.uptnl` file whose bytes the caller supplies — decompressing `FArchive::SerializeCompressed` blocks.
3643
+
3644
+ ```ts
3645
+ export function decompressBulkData( container: Uint8Array, codecs: { … }
3646
+ ```
3647
+
3648
+ - **Use when:** read a UE4 editor static mesh whose source model lives in bulk data rather than inline · decompress the zlib-chunked bulk payload a UE4.2x package stores its MeshDescription in
3649
+ - **Constraints:** zlib payloads require an injected `zlib` codec; the package never bundles one, and a missing codec throws MISSING_CODEC instead of guessing · a payload written to a sibling file throws MISSING_BULK_DATA_FILE naming that file, rather than inventing geometry
3650
+ - **Requires:** npm i @threenative/raw-unreal
3651
+
3652
+ ```ts
3653
+ const payload = resolveBulkDataPayload(bytes, header, { zlib });
3654
+ ```
3655
+
3656
+ ### `decompressCompressedBuffer`
3657
+
3658
+ `function` — Parses one UE5 `FCompressedBuffer` and decompresses it block-by-block with the codecs the caller injected — uncompressed payloads are handled natively.
3659
+
3660
+ ```ts
3661
+ export function decompressCompressedBuffer( buffer: ICompressedBuffer, codecs: IUAssetCodecs, ): Uint8Array { … }
3662
+ ```
3663
+
3664
+ - **Use when:** decompress the package-trailer payload that carries a UE5 MeshDescription
3665
+ - **Constraints:** Oodle and LZ4 payloads require an injected codec; the package never bundles one, and a missing codec throws MISSING_CODEC instead of guessing
3666
+ - **Requires:** npm i @threenative/raw-unreal
3667
+
3668
+ ```ts
3669
+ const payload = decompressCompressedBuffer(parseCompressedBuffer(bytes, offset), { oodle });
3670
+ ```
3671
+
3672
+ ### `findBulkDataHeaders`
3673
+
3674
+ `function` — Reads the `FByteBulkData` headers an editor package serializes into its export data, and resolves each payload — inline, at the end of the package, or in a sibling `.ubulk`/`.uptnl` file whose bytes the caller supplies — decompressing `FArchive::SerializeCompressed` blocks.
3675
+
3676
+ ```ts
3677
+ export function findBulkDataHeaders( bytes: Uint8Array, layout: IPackageLayout, files: IUAssetBulkDataFiles = { … }
3678
+ ```
3679
+
3680
+ - **Use when:** read a UE4 editor static mesh whose source model lives in bulk data rather than inline · decompress the zlib-chunked bulk payload a UE4.2x package stores its MeshDescription in
3681
+ - **Constraints:** zlib payloads require an injected `zlib` codec; the package never bundles one, and a missing codec throws MISSING_CODEC instead of guessing · a payload written to a sibling file throws MISSING_BULK_DATA_FILE naming that file, rather than inventing geometry
3682
+ - **Requires:** npm i @threenative/raw-unreal
3683
+
3684
+ ```ts
3685
+ const payload = resolveBulkDataPayload(bytes, header, { zlib });
3686
+ ```
3687
+
3688
+ ### `findCompressedBufferOffsets`
3689
+
3690
+ `function` — Parses one UE5 `FCompressedBuffer` and decompresses it block-by-block with the codecs the caller injected — uncompressed payloads are handled natively.
3691
+
3692
+ ```ts
3693
+ export function findCompressedBufferOffsets(bytes: Uint8Array): number[] { … }
3694
+ ```
3695
+
3696
+ - **Use when:** decompress the package-trailer payload that carries a UE5 MeshDescription
3697
+ - **Constraints:** Oodle and LZ4 payloads require an injected codec; the package never bundles one, and a missing codec throws MISSING_CODEC instead of guessing
3698
+ - **Requires:** npm i @threenative/raw-unreal
3699
+
3700
+ ```ts
3701
+ const payload = decompressCompressedBuffer(parseCompressedBuffer(bytes, offset), { oodle });
3702
+ ```
3703
+
3704
+ ### `findMeshDescriptionOffsets`
3705
+
3706
+ `function` — Parses a serialized `FMeshDescription` — element containers, allocation bit arrays, and attribute sets — into validated typed arrays, exactly consuming its byte range.
3707
+
3708
+ ```ts
3709
+ export function findMeshDescriptionOffsets(bytes: Uint8Array): number[] { … }
3710
+ ```
3711
+
3712
+ - **Use when:** inspect the vertex, triangle, and polygon-group structure of a UE5 MeshDescription
3713
+ - **Constraints:** every count is validated against its neighbors before any geometry is built
3714
+ - **Requires:** npm i @threenative/raw-unreal
3715
+
3716
+ ```ts
3717
+ const description = parseMeshDescription(payload, offset);
3718
+ ```
3719
+
3720
+ ### `findRawMeshBlobs`
3721
+
3722
+ `function` — Parses one `FRawMesh` blob — the UE4.18-era source-model layout — validating that the fixed eighteen-array walk consumes the blob exactly and every count agrees with the wedge totals.
3723
+
3724
+ ```ts
3725
+ export function findRawMeshBlobs(bytes: Uint8Array): IRawMeshBlob[] { … }
3726
+ ```
3727
+
3728
+ - **Use when:** read the source geometry of a Fab pack saved by UE 4.18 straight from its .uasset
3729
+ - **Constraints:** only inline uncompressed blobs are found; compressed or external bulk data throws rather than guessing
3730
+ - **Requires:** npm i @threenative/raw-unreal
3731
+
3732
+ ```ts
3733
+ const blob = parseRawMesh(bytes, offset);
3734
+ ```
3735
+
3736
+ ### `looksLikeMeshDescription`
3737
+
3738
+ `function` — Parses a serialized `FMeshDescription` — element containers, allocation bit arrays, and attribute sets — into validated typed arrays, exactly consuming its byte range.
3739
+
3740
+ ```ts
3741
+ export function looksLikeMeshDescription(bytes: Uint8Array, offset = 0): boolean { … }
3742
+ ```
3743
+
3744
+ - **Use when:** inspect the vertex, triangle, and polygon-group structure of a UE5 MeshDescription
3745
+ - **Constraints:** every count is validated against its neighbors before any geometry is built
3746
+ - **Requires:** npm i @threenative/raw-unreal
3747
+
3748
+ ```ts
3749
+ const description = parseMeshDescription(payload, offset);
3750
+ ```
3751
+
3752
+ ### `looksLikeMeshDescriptionUe4`
3753
+
3754
+ `function` — Parses the UE4.2x serialization of `FMeshDescription` — fixed-order element containers, and a triangle container that trails the attribute sets rather than sitting with its siblings.
3755
+
3756
+ ```ts
3757
+ export function looksLikeMeshDescriptionUe4(bytes: Uint8Array, offset = 0): boolean { … }
3758
+ ```
3759
+
3760
+ - **Use when:** decode the MeshDescription a UE 4.23-4.27 editor package keeps in bulk data
3761
+ - **Constraints:** the walk must consume the payload exactly; a short walk throws rather than returning the geometry it managed to read
3762
+ - **Requires:** npm i @threenative/raw-unreal
3763
+
3764
+ ```ts
3765
+ const description = parseMeshDescriptionUe4(payload);
3766
+ ```
3767
+
3768
+ ### `parseBulkDataHeader`
3769
+
3770
+ `function` — Reads the `FByteBulkData` headers an editor package serializes into its export data, and resolves each payload — inline, at the end of the package, or in a sibling `.ubulk`/`.uptnl` file whose bytes the caller supplies — decompressing `FArchive::SerializeCompressed` blocks.
3771
+
3772
+ ```ts
3773
+ export function parseBulkDataHeader( bytes: Uint8Array, offset: number, layout: IPackageLayout, ): IBulkDataHeader { … }
3774
+ ```
3775
+
3776
+ - **Use when:** read a UE4 editor static mesh whose source model lives in bulk data rather than inline · decompress the zlib-chunked bulk payload a UE4.2x package stores its MeshDescription in
3777
+ - **Constraints:** zlib payloads require an injected `zlib` codec; the package never bundles one, and a missing codec throws MISSING_CODEC instead of guessing · a payload written to a sibling file throws MISSING_BULK_DATA_FILE naming that file, rather than inventing geometry
3778
+ - **Requires:** npm i @threenative/raw-unreal
3779
+
3780
+ ```ts
3781
+ const payload = resolveBulkDataPayload(bytes, header, { zlib });
3782
+ ```
3783
+
3784
+ ### `parseCompressedBuffer`
3785
+
3786
+ `function` — Parses one UE5 `FCompressedBuffer` and decompresses it block-by-block with the codecs the caller injected — uncompressed payloads are handled natively.
3787
+
3788
+ ```ts
3789
+ export function parseCompressedBuffer(bytes: Uint8Array, offset = 0): ICompressedBuffer { … }
3790
+ ```
3791
+
3792
+ - **Use when:** decompress the package-trailer payload that carries a UE5 MeshDescription
3793
+ - **Constraints:** Oodle and LZ4 payloads require an injected codec; the package never bundles one, and a missing codec throws MISSING_CODEC instead of guessing
3794
+ - **Requires:** npm i @threenative/raw-unreal
3795
+
3796
+ ```ts
3797
+ const payload = decompressCompressedBuffer(parseCompressedBuffer(bytes, offset), { oodle });
3798
+ ```
3799
+
3800
+ ### `parseMeshDescription`
3801
+
3802
+ `function` — Parses a serialized `FMeshDescription` — element containers, allocation bit arrays, and attribute sets — into validated typed arrays, exactly consuming its byte range.
3803
+
3804
+ ```ts
3805
+ export function parseMeshDescription(input: Uint8Array, offset = 0): IMeshDescription { … }
3806
+ ```
3807
+
3808
+ - **Use when:** inspect the vertex, triangle, and polygon-group structure of a UE5 MeshDescription
3809
+ - **Constraints:** every count is validated against its neighbors before any geometry is built
3810
+ - **Requires:** npm i @threenative/raw-unreal
3811
+
3812
+ ```ts
3813
+ const description = parseMeshDescription(payload, offset);
3814
+ ```
3815
+
3816
+ ### `parseMeshDescriptionUe4`
3817
+
3818
+ `function` — Parses the UE4.2x serialization of `FMeshDescription` — fixed-order element containers, and a triangle container that trails the attribute sets rather than sitting with its siblings.
3819
+
3820
+ ```ts
3821
+ export function parseMeshDescriptionUe4(input: Uint8Array, offset = 0): IUe4MeshDescription { … }
3822
+ ```
3823
+
3824
+ - **Use when:** decode the MeshDescription a UE 4.23-4.27 editor package keeps in bulk data
3825
+ - **Constraints:** the walk must consume the payload exactly; a short walk throws rather than returning the geometry it managed to read
3826
+ - **Requires:** npm i @threenative/raw-unreal
3827
+
3828
+ ```ts
3829
+ const description = parseMeshDescriptionUe4(payload);
3830
+ ```
3831
+
3832
+ ### `parseRawMesh`
3833
+
3834
+ `function` — Parses one `FRawMesh` blob — the UE4.18-era source-model layout — validating that the fixed eighteen-array walk consumes the blob exactly and every count agrees with the wedge totals.
3835
+
3836
+ ```ts
3837
+ export function parseRawMesh(bytes: Uint8Array, offset = 0): IRawMeshBlob { … }
3838
+ ```
3839
+
3840
+ - **Use when:** read the source geometry of a Fab pack saved by UE 4.18 straight from its .uasset
3841
+ - **Constraints:** only inline uncompressed blobs are found; compressed or external bulk data throws rather than guessing
3842
+ - **Requires:** npm i @threenative/raw-unreal
3843
+
3844
+ ```ts
3845
+ const blob = parseRawMesh(bytes, offset);
3846
+ ```
3847
+
3848
+ ### `parseUAssetStaticMesh`
3849
+
3850
+ `function` — Parses a raw Unreal editor `.uasset` static mesh into validated, plain typed arrays — UE5 `FMeshDescription` payloads (including the Oodle-compressed package-trailer form) and the UE4.18-era `FRawMesh` source-model layout, with no interchange conversion at any step.
3851
+
3852
+ ```ts
3853
+ export function parseUAssetStaticMesh( input: ArrayBuffer | ArrayBufferView, options: IUAssetParseOptions = { … }
3854
+ ```
3855
+
3856
+ - **Use when:** load a raw Unreal editor .uasset mesh in the browser without conversion · decode a Fab pack's UE4.18 static meshes straight from their .uasset files
3857
+ - **Constraints:** only legacy-tag uncooked editor packages are read; IoStore (.utoc/.ucas), PAK archives, cooked render buffers, Nanite, and skeletal data throw UAssetError · the format layer never invents fallback geometry; every malformed or unsupported layout surfaces as UAssetError with its byte offset or counts
3858
+ - **Requires:** npm i @threenative/raw-unreal
3859
+
3860
+ ```ts
3861
+ const decoded = parseUAssetStaticMesh(await file.arrayBuffer(), { oodle });
3862
+ ```
3863
+
3864
+ ### `readPackageLayout`
3865
+
3866
+ `function` — Walks the whole `FPackageFileSummary` for the offsets bulk data is addressed against — `TotalHeaderSize` and `BulkDataStartOffset` — and returns `undefined` when the walk cannot be trusted.
3867
+
3868
+ ```ts
3869
+ export function readPackageLayout(bytes: Uint8Array): IPackageLayout | undefined { … }
3870
+ ```
3871
+
3872
+ - **Use when:** find where a .uasset's export data and bulk-data region begin
3873
+ - **Constraints:** returns undefined rather than guessing when the summary does not end on its own name table, or when the package uses a LegacyFileVersion this walk does not model
3874
+ - **Requires:** npm i @threenative/raw-unreal
3875
+
3876
+ ```ts
3877
+ const layout = readPackageLayout(bytes); if (layout) readBulk(layout.bulkDataStartOffset);
3878
+ ```
3879
+
3880
+ ### `readPackageSummary`
3881
+
3882
+ `function` — Reads the fixed prefix of `FPackageFileSummary` — the legacy tag, engine versions, and the custom-version list — without walking the name map, export map, or dependency graph.
3883
+
3884
+ ```ts
3885
+ export function readPackageSummary(bytes: Uint8Array): IPackageSummary { … }
3886
+ ```
3887
+
3888
+ - **Use when:** report which engine generation a .uasset was written by before decoding it · reject a non-Unreal file with the stable INVALID_PACKAGE_TAG error
3889
+ - **Constraints:** only the summary prefix is read; locating payload data is the payload readers' self-validating signature scans
3890
+ - **Requires:** npm i @threenative/raw-unreal
3891
+
3892
+ ```ts
3893
+ const summary = readPackageSummary(bytes);
3894
+ ```
3895
+
3896
+ ### `resolveBulkDataPayload`
3897
+
3898
+ `function` — Reads the `FByteBulkData` headers an editor package serializes into its export data, and resolves each payload — inline, at the end of the package, or in a sibling `.ubulk`/`.uptnl` file whose bytes the caller supplies — decompressing `FArchive::SerializeCompressed` blocks.
3899
+
3900
+ ```ts
3901
+ export function resolveBulkDataPayload( bytes: Uint8Array, header: IBulkDataHeader, options: { … }
3902
+ ```
3903
+
3904
+ - **Use when:** read a UE4 editor static mesh whose source model lives in bulk data rather than inline · decompress the zlib-chunked bulk payload a UE4.2x package stores its MeshDescription in
3905
+ - **Constraints:** zlib payloads require an injected `zlib` codec; the package never bundles one, and a missing codec throws MISSING_CODEC instead of guessing · a payload written to a sibling file throws MISSING_BULK_DATA_FILE naming that file, rather than inventing geometry
3906
+ - **Requires:** npm i @threenative/raw-unreal
3907
+
3908
+ ```ts
3909
+ const payload = resolveBulkDataPayload(bytes, header, { zlib });
3910
+ ```
3911
+
3912
+ ### `UAssetError`
3913
+
3914
+ `class` — The error thrown for every malformed, truncated, or unsupported `.uasset` input, carrying a stable `code` and structured details instead of invented fallback geometry.
3915
+
3916
+ ```ts
3917
+ export class UAssetError extends Error { … }
3918
+ ```
3919
+
3920
+ - **Use when:** tell why a raw .uasset failed to load, by code, before any geometry is shown · branch on an unsupported Unreal layout instead of shipping broken geometry
3921
+ - **Constraints:** every parse, decompression, and geometry failure surfaces as this error; the loader never invents fallback geometry
3922
+ - **Requires:** npm i @threenative/raw-unreal
3923
+
3924
+ ```ts
3925
+ catch (error) { if (error instanceof UAssetError) log(error.code, error.details); }
3926
+ ```
3927
+
3928
+ ### `UAssetLoader`
3929
+
3930
+ `class` — Loads a raw Unreal `.uasset` static mesh as a three.js loader — `load(url)` for the browser, `parse(data)` for bytes you already hold — with parse and adapter options passed through.
3931
+
3932
+ ```ts
3933
+ export class UAssetLoader extends Loader { … }
3934
+ ```
3935
+
3936
+ - **Use when:** load a .uasset asset in the browser with the standard three.js loader protocol · hand raw Fab-pack meshes to the framework's asset loading without a conversion step
3937
+ - **Constraints:** UE5 Oodle payloads require an `oodle` codec in the parse options; see README licensing
3938
+ - **Requires:** npm i @threenative/raw-unreal
3939
+
3940
+ ```ts
3941
+ const mesh = new UAssetLoader(manager, { parse: { oodle } }).parse(data);
2904
3942
  ```
2905
3943
 
2906
3944
  ## `@threenative/template/starter/src/render/effects/gradualBackground`
@@ -2954,6 +3992,104 @@ function sparkle
2954
3992
  sparkle(...)
2955
3993
  ```
2956
3994
 
3995
+ ## `@threenative/ueformat`
3996
+
3997
+ ### `createThreeGeometry`
3998
+
3999
+ `function` — Converts one parsed Unreal mesh LOD into a `THREE.BufferGeometry` — coordinates, scale, winding, normals, tangents, UVs, vertex colours, morphs, skin weights, and material groups.
4000
+
4001
+ ```ts
4002
+ export function createThreeGeometry( lod: IUEModelLOD, adapterOptions: IThreeAdapterOptions = { … }
4003
+ ```
4004
+
4005
+ - **Use when:** convert one Unreal mesh LOD into a three.js BufferGeometry by hand · build custom scene objects from Unreal mesh data instead of a whole model
4006
+ - **Constraints:** rejects indices, channels, or material sections that disagree with the vertex count before any geometry is constructed
4007
+ - **Requires:** npm i @threenative/ueformat
4008
+
4009
+ ```ts
4010
+ const geometry = createThreeGeometry(model.lods[0]);
4011
+ ```
4012
+
4013
+ ### `createThreeObject`
4014
+
4015
+ `function` — Builds a renderable Three.js object — a `Group` for single-LOD models, a `THREE.LOD` for multi-LOD ones — from parsed `.uemodel` data, with collision geometry on `userData`.
4016
+
4017
+ ```ts
4018
+ export function createThreeObject( model: IUEModelData, adapterOptions: IThreeAdapterOptions = { … }
4019
+ ```
4020
+
4021
+ - **Use when:** put a mesh exported from an Unreal package on screen · load an Unreal static or skeletal mesh with LODs, sockets, and collision geometry
4022
+ - **Constraints:** every material comes from the game through `materialFactory`; the fallback is three.js's own GLTFLoader default, a plain MeshStandardMaterial · parsed bones are exposed on `userData` but never bound into a THREE.SkinnedMesh — skeletal rendering is the game's job
4023
+ - **Requires:** npm i @threenative/ueformat
4024
+
4025
+ ```ts
4026
+ const hero = createThreeObject(parseUEModel(buffer), { lodDistances: [0, 25, 50] });
4027
+ ```
4028
+
4029
+ ### `parseUEModel`
4030
+
4031
+ `function` — Parses a UEFormat v10 `.uemodel` body — the interchange format CUE4Parse and FModel export from Unreal packages — into validated, plain mesh data without building any Three.js objects.
4032
+
4033
+ ```ts
4034
+ export function parseUEModel( input: ArrayBuffer | ArrayBufferView, options: IParseUEModelOptions = { … }
4035
+ ```
4036
+
4037
+ - **Use when:** parse a mesh exported from an Unreal package without Unreal installed · inspect the LODs, skeleton, sockets, and collision inside a .uemodel file
4038
+ - **Constraints:** only UEFormat v10 UEMODEL files are accepted; anything else throws UEFormatError with the byte offset · ZSTD-compressed bodies require an injected `zstdDecoder`; the package never bundles a ZSTD implementation
4039
+ - **Requires:** npm i @threenative/ueformat
4040
+
4041
+ ```ts
4042
+ const model = parseUEModel(await file.arrayBuffer());
4043
+ ```
4044
+
4045
+ ### `summarizeUEModel`
4046
+
4047
+ `function` — Summarizes a parsed `.uemodel` — LOD, material, skeleton, collision, and unknown-attribute counts — without dumping vertex arrays, for logs, validation, and build reports.
4048
+
4049
+ ```ts
4050
+ export function summarizeUEModel(model: IUEModelData): IUEModelSummary { … }
4051
+ ```
4052
+
4053
+ - **Use when:** report what a UEFormat model contains without dumping its vertex data · validate a .uemodel file before building geometry from it
4054
+ - **Constraints:** the summary reflects one already-parsed model; it does not read files itself
4055
+ - **Requires:** npm i @threenative/ueformat
4056
+
4057
+ ```ts
4058
+ const summary = summarizeUEModel(parseUEModel(buffer));
4059
+ ```
4060
+
4061
+ ### `UEFormatError`
4062
+
4063
+ `class` — The error thrown for every malformed, truncated, or unsupported `.uemodel` input, carrying a stable `code` and the byte offset where validation stopped.
4064
+
4065
+ ```ts
4066
+ export class UEFormatError extends Error { … }
4067
+ ```
4068
+
4069
+ - **Use when:** tell why a .uemodel file failed to load · report a malformed Unreal export with its byte offset instead of a generic error
4070
+ - **Constraints:** every parse and geometry failure surfaces as this error; nothing malformed is silently skipped
4071
+ - **Requires:** npm i @threenative/ueformat
4072
+
4073
+ ```ts
4074
+ catch (error) { if (error instanceof UEFormatError) log(error.code, error.offset); }
4075
+ ```
4076
+
4077
+ ### `UEFormatLoader`
4078
+
4079
+ `class` — Loads a `.uemodel` file as a Three.js loader — `load(url)` for the browser, `parse(data)` for bytes you already hold — with the parser and three-adapter options passed straight through.
4080
+
4081
+ ```ts
4082
+ export class UEFormatLoader extends Loader { … }
4083
+ ```
4084
+
4085
+ - **Use when:** load a .uemodel asset in the browser with the standard three.js loader protocol · hand a game's Unreal-exported meshes to the framework's asset loading
4086
+ - **Constraints:** ZSTD-compressed bodies require an injected `zstdDecoder` in the parse options
4087
+ - **Requires:** npm i @threenative/ueformat
4088
+
4089
+ ```ts
4090
+ const model = new UEFormatLoader(manager).parse(data);
4091
+ ```
4092
+
2957
4093
  ## `@threenative/ui`
2958
4094
 
2959
4095
  ### `DebugOverlay`
@@ -2967,7 +4103,7 @@ export function DebugOverlay() { … }
2967
4103
  - **Use when:** display runtime and playtest diagnostics in a React HUD · inspect a game without changing its scene
2968
4104
 
2969
4105
  ```ts
2970
- <DebugOverlay game={game} />
4106
+ <DebugOverlay />
2971
4107
  ```
2972
4108
 
2973
4109
  ### `GameCanvas`
@@ -3042,24 +4178,92 @@ export function useUiState<TState extends object>(): TState | undefined;
3042
4178
  - **Constraints:** returns undefined until the game publishes its first state
3043
4179
 
3044
4180
  ```ts
3045
- const score = useUiState((state) => state.score);
4181
+ const score = useUiState<GameState, number>((state) => state.score);
4182
+ ```
4183
+
4184
+ ## `src/render/worldEnvironment.ts`
4185
+
4186
+ ### `WorldEnvironment`
4187
+
4188
+ `class` — The generated file that composes every lighting stage and prints TN_RENDER_CHAIN naming each one as applied or refused with a reason. It is the game's source, not the framework's — edit it.
4189
+
4190
+ ```ts
4191
+ class WorldEnvironment
4192
+ ```
4193
+
4194
+ - **Use when:** turn a lighting or post-processing effect on or off · find out why an effect you enabled is not visible · change how the scene is lit, graded, or tonemapped · match a reference image's lighting
4195
+ - **Constraints:** Read the TN_RENDER_CHAIN line before assuming a stage ran: it names every stage as applied or dropped, with the reason it was dropped. · A stage reported `applied` can still be invisible if its own inputs are wrong — the chain reports whether it built, not whether you can see it. · Appearance belongs here, in generated game source. Nothing in packages/ decides how the scene looks.
4196
+
4197
+ ```ts
4198
+ src/render/postprocessing.ts — edit the preset it passes to WorldEnvironment
4199
+ ```
4200
+
4201
+ ## `three/addons/tsl/display/BloomNode.js`
4202
+
4203
+ ### `bloom`
4204
+
4205
+ `function` — Glow around bright pixels. Already wired as the `bloom` stage.
4206
+
4207
+ ```ts
4208
+ bloom(node, strength, radius, threshold)
4209
+ ```
4210
+
4211
+ - **Use when:** make a bright opening or a lamp glow · bloom, glare, light spill
4212
+ - **Constraints:** Strength above ~0.3 on an interior washes the mid-tones; the reference-matching band is lower than it looks.
4213
+
4214
+ ```ts
4215
+ src/render/postprocessing.ts — edit the preset it passes to WorldEnvironment
3046
4216
  ```
3047
4217
 
3048
4218
  ## `three/addons/tsl/display/DenoiseNode.js`
3049
4219
 
3050
- ### `DenoiseNode`
4220
+ ### `denoise`
3051
4221
 
3052
- `class` — ThreeNative equivalent for realism-effects DenoiseNode.
4222
+ `function` — ThreeNative equivalent for realism-effects denoise.
3053
4223
 
3054
4224
  ```ts
3055
- class DenoiseNode
4225
+ function denoise
3056
4226
  ```
3057
4227
 
3058
4228
  - **Use when:** denoise a noisy screen-space pass
3059
4229
  - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
3060
4230
 
3061
4231
  ```ts
3062
- DenoiseNode(...)
4232
+ denoise(...)
4233
+ ```
4234
+
4235
+ ## `three/addons/tsl/display/GodraysNode.js`
4236
+
4237
+ ### `godrays`
4238
+
4239
+ `function` — Raymarched shafts of light. Already wired as the `godRays` stage of the render chain; turn it on with `godraysEnabled` in src/render/postprocessing.ts.
4240
+
4241
+ ```ts
4242
+ godrays(textureNode, light, shadowMap, params)
4243
+ ```
4244
+
4245
+ - **Use when:** draw a visible shaft of light through a window or a hole in a roof · god rays, sun shafts, light beams, crepuscular rays · make sunlight visible in dusty or misty air indoors · light a cave or a hall through an opening above · volumetric lighting without adding cone geometry
4246
+ - **Constraints:** Needs a shadow-casting DirectionalLight passed as `godraysLight`, and `renderer.shadowMap.enabled = true` — without the shadow map the stage refuses and the whole chain reports it dropped. · `godraysFloor` is what separates beams from fog: it subtracts out-of-beam scatter before `godraysIntensity` multiplies. Raising intensity with a floor near zero brightens the haze over the whole room instead of the beams. · Do not author cone geometry for beams. A hand-built additive cone draws its own silhouette and reads as a plastic tube; this stage is the supported route. · Measured band on an interior scene: density 0.7, floor 0.08, intensity 3.0, maxDensity 0.6. Above ~0.8 density the haze stops being confined to the beams and the room fogs.
4247
+
4248
+ ```ts
4249
+ src/render/postprocessing.ts — edit the preset it passes to WorldEnvironment
4250
+ ```
4251
+
4252
+ ## `three/addons/tsl/display/GTAONode.js`
4253
+
4254
+ ### `ao`
4255
+
4256
+ `function` — Ground-truth ambient occlusion. Already wired as the `ambientOcclusion` stage; turn it on with `gtaoEnabled`.
4257
+
4258
+ ```ts
4259
+ ao(scene, camera, resolution, radius, intensity)
4260
+ ```
4261
+
4262
+ - **Use when:** darken the contact where an object meets the floor · stop props looking like they float · ambient occlusion, contact shadows, crevice darkening
4263
+ - **Constraints:** Radius is in metres; a radius sized for a room reads as a smudge on a prop.
4264
+
4265
+ ```ts
4266
+ src/render/postprocessing.ts — edit the preset it passes to WorldEnvironment
3063
4267
  ```
3064
4268
 
3065
4269
  ## `three/addons/tsl/display/MotionBlur.js`
@@ -3081,121 +4285,121 @@ motionBlur(...)
3081
4285
 
3082
4286
  ## `three/addons/tsl/display/RecurrentDenoiseNode.js`
3083
4287
 
3084
- ### `RecurrentDenoiseNode`
4288
+ ### `recurrentDenoise`
3085
4289
 
3086
- `class` — ThreeNative equivalent for realism-effects RecurrentDenoiseNode.
4290
+ `function` — ThreeNative equivalent for realism-effects recurrentDenoise.
3087
4291
 
3088
4292
  ```ts
3089
- class RecurrentDenoiseNode
4293
+ function recurrentDenoise
3090
4294
  ```
3091
4295
 
3092
4296
  - **Use when:** denoise a noisy screen-space pass
3093
4297
  - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
3094
4298
 
3095
4299
  ```ts
3096
- RecurrentDenoiseNode(...)
4300
+ recurrentDenoise(...)
3097
4301
  ```
3098
4302
 
3099
4303
  ## `three/addons/tsl/display/SharpenNode.js`
3100
4304
 
3101
- ### `SharpenNode`
4305
+ ### `sharpen`
3102
4306
 
3103
- `class` — ThreeNative equivalent for realism-effects SharpenNode.
4307
+ `function` — ThreeNative equivalent for realism-effects sharpen.
3104
4308
 
3105
4309
  ```ts
3106
- class SharpenNode
4310
+ function sharpen
3107
4311
  ```
3108
4312
 
3109
4313
  - **Use when:** make the image sharper
3110
4314
  - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
3111
4315
 
3112
4316
  ```ts
3113
- SharpenNode(...)
4317
+ sharpen(...)
3114
4318
  ```
3115
4319
 
3116
4320
  ## `three/addons/tsl/display/SSAAPassNode.js`
3117
4321
 
3118
- ### `SSAAPassNode`
4322
+ ### `ssaaPass`
3119
4323
 
3120
- `class` — ThreeNative equivalent for realism-effects SSAAPassNode.
4324
+ `function` — ThreeNative equivalent for realism-effects ssaaPass.
3121
4325
 
3122
4326
  ```ts
3123
- class SSAAPassNode
4327
+ function ssaaPass
3124
4328
  ```
3125
4329
 
3126
4330
  - **Use when:** anti-alias still and moving scenes
3127
4331
  - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
3128
4332
 
3129
4333
  ```ts
3130
- SSAAPassNode(...)
4334
+ ssaaPass(...)
3131
4335
  ```
3132
4336
 
3133
4337
  ## `three/addons/tsl/display/SSGINode.js`
3134
4338
 
3135
- ### `SSGINode`
4339
+ ### `ssgi`
3136
4340
 
3137
- `class` — ThreeNative equivalent for realism-effects SSGINode.
4341
+ `function` — ThreeNative equivalent for realism-effects ssgi.
3138
4342
 
3139
4343
  ```ts
3140
- class SSGINode
4344
+ function ssgi
3141
4345
  ```
3142
4346
 
3143
4347
  - **Use when:** add screen-space global illumination
3144
4348
  - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
3145
4349
 
3146
4350
  ```ts
3147
- SSGINode(...)
4351
+ ssgi(...)
3148
4352
  ```
3149
4353
 
3150
4354
  ## `three/addons/tsl/display/SSRNode.js`
3151
4355
 
3152
- ### `SSRNode`
4356
+ ### `ssr`
3153
4357
 
3154
- `class` — ThreeNative equivalent for realism-effects SSRNode.
4358
+ `function` — ThreeNative equivalent for realism-effects ssr.
3155
4359
 
3156
4360
  ```ts
3157
- class SSRNode
4361
+ function ssr
3158
4362
  ```
3159
4363
 
3160
4364
  - **Use when:** add screen-space reflections
3161
4365
  - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
3162
4366
 
3163
4367
  ```ts
3164
- SSRNode(...)
4368
+ ssr(...)
3165
4369
  ```
3166
4370
 
3167
4371
  ## `three/addons/tsl/display/TemporalReprojectNode.js`
3168
4372
 
3169
- ### `TemporalReprojectNode`
4373
+ ### `temporalReproject`
3170
4374
 
3171
- `class` — ThreeNative equivalent for realism-effects TemporalReprojectNode.
4375
+ `function` — ThreeNative equivalent for realism-effects temporalReproject.
3172
4376
 
3173
4377
  ```ts
3174
- class TemporalReprojectNode
4378
+ function temporalReproject
3175
4379
  ```
3176
4380
 
3177
4381
  - **Use when:** reproject a temporal history
3178
4382
  - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
3179
4383
 
3180
4384
  ```ts
3181
- TemporalReprojectNode(...)
4385
+ temporalReproject(...)
3182
4386
  ```
3183
4387
 
3184
4388
  ## `three/addons/tsl/display/TRAANode.js`
3185
4389
 
3186
- ### `TRAANode`
4390
+ ### `traa`
3187
4391
 
3188
- `class` — ThreeNative equivalent for realism-effects TRAANode.
4392
+ `function` — ThreeNative equivalent for realism-effects traa.
3189
4393
 
3190
4394
  ```ts
3191
- class TRAANode
4395
+ function traa
3192
4396
  ```
3193
4397
 
3194
4398
  - **Use when:** temporally resolve a moving image
3195
4399
  - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
3196
4400
 
3197
4401
  ```ts
3198
- TRAANode(...)
4402
+ traa(...)
3199
4403
  ```
3200
4404
 
3201
4405
  ## `three/tsl`
@@ -3230,19 +4434,19 @@ function mrt
3230
4434
  mrt(...)
3231
4435
  ```
3232
4436
 
3233
- ### `normal`
4437
+ ### `normalView`
3234
4438
 
3235
- `function` — ThreeNative equivalent for realism-effects normal.
4439
+ `function` — ThreeNative equivalent for realism-effects normalView.
3236
4440
 
3237
4441
  ```ts
3238
- function normal
4442
+ function normalView
3239
4443
  ```
3240
4444
 
3241
4445
  - **Use when:** provide normals to screen-space effects
3242
4446
  - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
3243
4447
 
3244
4448
  ```ts
3245
- normal(...)
4449
+ normalView(...)
3246
4450
  ```
3247
4451
 
3248
4452
  ### `velocity`