create-threenative 0.2.2 → 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 (588) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +61 -2
  3. package/agent-docs/references/assertion-reference.md +819 -0
  4. package/agent-docs/references/capability-reference.md +4483 -0
  5. package/agent-docs/references/capture-the-frame.md +60 -0
  6. package/agent-docs/references/creating-creatures.md +215 -0
  7. package/agent-docs/references/ctx-cookbook.md +120 -0
  8. package/agent-docs/references/debug-surface.md +68 -0
  9. package/agent-docs/references/dream-loop.md +150 -0
  10. package/agent-docs/references/finding-assets.md +215 -0
  11. package/agent-docs/references/gameplay-recipes.md +54 -0
  12. package/agent-docs/references/menu-screens.md +69 -0
  13. package/agent-docs/references/mobile-memory-budget.md +87 -0
  14. package/agent-docs/references/sculpt-from-a-reference.md +40 -0
  15. package/agent-docs/references/trace-a-slow-frame.md +99 -0
  16. package/agent-docs/references/visual-baseline.md +174 -0
  17. package/agent-docs/references/webview-ui.md +113 -0
  18. package/agent-files/.agents/skills/file-engine-bug/SKILL.md +59 -0
  19. package/agent-files/.agents/skills/prd-creator/SKILL.md +40 -0
  20. package/agent-files/.agents/skills/threenative-assets/SKILL.md +45 -0
  21. package/agent-files/.agents/skills/threenative-builder/SKILL.md +7 -0
  22. package/agent-files/.agents/skills/threenative-capabilities/SKILL.md +27 -0
  23. package/agent-files/.agents/skills/threenative-context/SKILL.md +57 -0
  24. package/agent-files/.agents/skills/threenative-performance/SKILL.md +42 -0
  25. package/agent-files/.agents/skills/threenative-playtest/SKILL.md +44 -0
  26. package/agent-files/.agents/skills/threenative-ui/SKILL.md +20 -0
  27. package/agent-files/.agents/skills/threenative-verifier/SKILL.md +7 -0
  28. package/agent-files/.agents/skills/threenative-visuals/SKILL.md +41 -0
  29. package/agent-files/.claude/agents/threenative-builder.md +7 -0
  30. package/agent-files/.claude/agents/threenative-verifier.md +7 -0
  31. package/agent-files/.claude/skills/file-engine-bug/SKILL.md +59 -0
  32. package/agent-files/.claude/skills/prd-creator/SKILL.md +40 -0
  33. package/agent-files/.claude/skills/threenative-assets/SKILL.md +45 -0
  34. package/agent-files/.claude/skills/threenative-capabilities/SKILL.md +27 -0
  35. package/agent-files/.claude/skills/threenative-context/SKILL.md +57 -0
  36. package/agent-files/.claude/skills/threenative-performance/SKILL.md +42 -0
  37. package/agent-files/.claude/skills/threenative-playtest/SKILL.md +44 -0
  38. package/agent-files/.claude/skills/threenative-ui/SKILL.md +20 -0
  39. package/agent-files/.claude/skills/threenative-visuals/SKILL.md +41 -0
  40. package/agent-files/.threenative/agents/builder.md +32 -0
  41. package/agent-files/.threenative/agents/verifier.md +31 -0
  42. package/agent-files/AGENT-ROLES.md +26 -0
  43. package/agent-files/scripts/reference.mjs +705 -0
  44. package/agent-files/scripts/visual-loop.mjs +382 -0
  45. package/capabilities.json +5292 -0
  46. package/dist/index.d.ts +224 -3
  47. package/dist/index.js +1972 -73
  48. package/dist/threenative.d.ts +9 -2
  49. package/dist/threenative.js +2570 -176
  50. package/package.json +55 -6
  51. package/template-assets/icon.png +0 -0
  52. package/template-assets/loading.ts +325 -0
  53. package/template-assets/patches/three@0.185.1.patch +522 -0
  54. package/template-assets/worldEnvironment.ts +758 -0
  55. package/templates/action-rpg/.codex/config.toml +19 -0
  56. package/templates/action-rpg/.cursor/mcp.json +32 -0
  57. package/templates/action-rpg/.gemini/settings.json +32 -0
  58. package/templates/action-rpg/.mcp.json +18 -2
  59. package/templates/action-rpg/.vscode/mcp.json +36 -0
  60. package/templates/action-rpg/.zed/settings.json +36 -0
  61. package/templates/action-rpg/AGENTS.md +84 -29
  62. package/templates/action-rpg/CLAUDE.md +84 -29
  63. package/templates/action-rpg/index.html +0 -1
  64. package/templates/action-rpg/opencode.json +41 -0
  65. package/templates/action-rpg/package.json +15 -11
  66. package/templates/action-rpg/playtests/combat.playtest.json +32 -9
  67. package/templates/action-rpg/playtests/fail.playtest.json +3 -3
  68. package/templates/action-rpg/playtests/inventory.playtest.json +16 -10
  69. package/templates/action-rpg/playtests/performance.playtest.json +39 -0
  70. package/templates/action-rpg/playtests/progress.playtest.json +18 -13
  71. package/templates/action-rpg/playtests/survives.playtest.json +27 -0
  72. package/templates/action-rpg/playtests/touch-controls.playtest.json +42 -0
  73. package/templates/action-rpg/playtests/win.playtest.json +10 -4
  74. package/templates/action-rpg/src/conventions.ts +35 -0
  75. package/templates/action-rpg/src/entities/Enemy.ts +16 -7
  76. package/templates/action-rpg/src/entities/Player.ts +20 -3
  77. package/templates/action-rpg/src/game.ts +21 -0
  78. package/templates/action-rpg/src/render/camera.ts +7 -2
  79. package/templates/action-rpg/src/render/lighting.ts +11 -4
  80. package/templates/action-rpg/src/render/loading.ts +278 -43
  81. package/templates/action-rpg/src/render/materials.ts +11 -0
  82. package/templates/action-rpg/src/render/palette.ts +10 -3
  83. package/templates/action-rpg/src/render/postprocessing.ts +32 -16
  84. package/templates/action-rpg/src/render/quality.ts +170 -0
  85. package/templates/action-rpg/src/render/shapes.ts +185 -26
  86. package/templates/action-rpg/src/render/touch-controls.ts +185 -0
  87. package/templates/action-rpg/src/render/vfx.ts +257 -0
  88. package/templates/action-rpg/src/render/worldEnvironment.ts +758 -0
  89. package/templates/action-rpg/src/scenes/Play.ts +91 -24
  90. package/templates/action-rpg/src/state.ts +4 -0
  91. package/templates/action-rpg/src/style.css +65 -1
  92. package/templates/action-rpg/src/ui/AbilityBar.tsx +9 -7
  93. package/templates/action-rpg/src/ui/App.tsx +9 -8
  94. package/templates/action-rpg/src/ui/CharacterPanel.tsx +10 -8
  95. package/templates/action-rpg/src/ui/GameUi.tsx +24 -0
  96. package/templates/action-rpg/src/ui/Hud.tsx +10 -8
  97. package/templates/action-rpg/src/ui/InventoryPanel.tsx +9 -7
  98. package/templates/action-rpg/src/ui/main.tsx +14 -0
  99. package/templates/action-rpg/threenative.config.ts +28 -8
  100. package/templates/action-rpg/vite.config.ts +32 -2
  101. package/templates/defense/.codex/config.toml +19 -0
  102. package/templates/defense/.cursor/mcp.json +32 -0
  103. package/templates/defense/.gemini/settings.json +32 -0
  104. package/templates/defense/.mcp.json +18 -2
  105. package/templates/defense/.vscode/mcp.json +36 -0
  106. package/templates/defense/.zed/settings.json +36 -0
  107. package/templates/defense/AGENTS.md +81 -41
  108. package/templates/defense/CLAUDE.md +81 -41
  109. package/templates/defense/README.md +2 -1
  110. package/templates/defense/index.html +0 -1
  111. package/templates/defense/opencode.json +41 -0
  112. package/templates/defense/package.json +16 -12
  113. package/templates/defense/playtests/leak.playtest.json +9 -4
  114. package/templates/defense/playtests/performance.playtest.json +39 -0
  115. package/templates/defense/playtests/placement.playtest.json +5 -5
  116. package/templates/defense/playtests/pointer-placement.playtest.json +156 -0
  117. package/templates/defense/playtests/scan.playtest.json +4 -4
  118. package/templates/defense/playtests/survive.playtest.json +25 -6
  119. package/templates/defense/src/attackers/Attacker.ts +32 -16
  120. package/templates/defense/src/board/Route.ts +22 -8
  121. package/templates/defense/src/conventions.ts +18 -0
  122. package/templates/defense/src/entities/Player.ts +11 -3
  123. package/templates/defense/src/game.ts +25 -4
  124. package/templates/defense/src/physics.ts +9 -39
  125. package/templates/defense/src/placement/Buildable.ts +4 -4
  126. package/templates/defense/src/render/camera.ts +9 -3
  127. package/templates/defense/src/render/lighting.ts +6 -1
  128. package/templates/defense/src/render/loading.ts +274 -38
  129. package/templates/defense/src/render/materials.ts +9 -0
  130. package/templates/defense/src/render/palette.ts +12 -5
  131. package/templates/defense/src/render/postprocessing.ts +32 -12
  132. package/templates/defense/src/render/quality.ts +170 -0
  133. package/templates/defense/src/render/shapes.ts +180 -23
  134. package/templates/defense/src/render/sky.ts +2 -2
  135. package/templates/defense/src/render/worldEnvironment.ts +758 -0
  136. package/templates/defense/src/scenes/Boot.ts +2 -2
  137. package/templates/defense/src/scenes/Defense.ts +122 -56
  138. package/templates/defense/src/state.ts +6 -0
  139. package/templates/defense/src/style.css +65 -1
  140. package/templates/defense/src/towers/Tower.ts +11 -12
  141. package/templates/defense/src/towers/targeting.ts +1 -1
  142. package/templates/defense/src/ui/App.tsx +11 -6
  143. package/templates/defense/src/ui/GameUi.tsx +20 -0
  144. package/templates/defense/src/ui/Hud.tsx +6 -5
  145. package/templates/defense/src/ui/main.tsx +14 -0
  146. package/templates/defense/threenative.config.ts +28 -8
  147. package/templates/defense/vite.config.ts +34 -1
  148. package/templates/minimal/.codex/config.toml +19 -0
  149. package/templates/minimal/.cursor/mcp.json +32 -0
  150. package/templates/minimal/.gemini/settings.json +32 -0
  151. package/templates/minimal/.mcp.json +18 -2
  152. package/templates/minimal/.vscode/mcp.json +36 -0
  153. package/templates/minimal/.zed/settings.json +36 -0
  154. package/templates/minimal/AGENTS.md +78 -382
  155. package/templates/minimal/CLAUDE.md +78 -382
  156. package/templates/minimal/index.html +0 -1
  157. package/templates/minimal/opencode.json +41 -0
  158. package/templates/minimal/package.json +14 -11
  159. package/templates/minimal/playtests/atmosphere.playtest.json +32 -0
  160. package/templates/minimal/playtests/play.playtest.json +18 -5
  161. package/templates/minimal/playtests/survives.playtest.json +48 -4
  162. package/templates/minimal/playtests/touch-controls.playtest.json +42 -0
  163. package/templates/minimal/src/conventions.ts +18 -0
  164. package/templates/minimal/src/entities/Player.ts +39 -6
  165. package/templates/minimal/src/game.ts +1 -0
  166. package/templates/minimal/src/main.ts +14 -4
  167. package/templates/minimal/src/render/camera.ts +1 -1
  168. package/templates/minimal/src/render/hud.ts +24 -8
  169. package/templates/minimal/src/render/lighting.ts +23 -2
  170. package/templates/minimal/src/render/loading.ts +23 -103
  171. package/templates/minimal/src/render/materials.ts +7 -0
  172. package/templates/minimal/src/render/palette.ts +3 -3
  173. package/templates/minimal/src/render/postprocessing.ts +55 -16
  174. package/templates/minimal/src/render/quality.ts +162 -0
  175. package/templates/minimal/src/render/sky.ts +51 -32
  176. package/templates/minimal/src/render/touch-controls.ts +165 -0
  177. package/templates/minimal/src/render/worldEnvironment.ts +758 -0
  178. package/templates/minimal/src/scenes/Play.ts +128 -14
  179. package/templates/minimal/src/state.ts +8 -1
  180. package/templates/minimal/src/style.css +20 -0
  181. package/templates/minimal/threenative.config.ts +22 -10
  182. package/templates/minimal/vite.config.ts +28 -1
  183. package/templates/platformer/.codex/config.toml +19 -0
  184. package/templates/platformer/.cursor/mcp.json +32 -0
  185. package/templates/platformer/.gemini/settings.json +32 -0
  186. package/templates/platformer/.mcp.json +18 -2
  187. package/templates/platformer/.vscode/mcp.json +36 -0
  188. package/templates/platformer/.zed/settings.json +36 -0
  189. package/templates/platformer/AGENTS.md +81 -186
  190. package/templates/platformer/CLAUDE.md +81 -186
  191. package/templates/platformer/index.html +0 -1
  192. package/templates/platformer/opencode.json +41 -0
  193. package/templates/platformer/package.json +17 -14
  194. package/templates/platformer/playtests/avoidance.playtest.json +6 -1
  195. package/templates/platformer/playtests/branding.playtest.json +29 -0
  196. package/templates/platformer/playtests/buffer.playtest.json +1 -1
  197. package/templates/platformer/playtests/collect.playtest.json +1 -1
  198. package/templates/platformer/playtests/collision-layers.playtest.json +2 -2
  199. package/templates/platformer/playtests/coyote.playtest.json +42 -8
  200. package/templates/platformer/playtests/damage.playtest.json +4 -1
  201. package/templates/platformer/playtests/dash.playtest.json +2 -2
  202. package/templates/platformer/playtests/jump.playtest.json +2 -3
  203. package/templates/platformer/playtests/native/touch-controls.playtest.json +33 -0
  204. package/templates/platformer/playtests/oneway.playtest.json +30 -3
  205. package/templates/platformer/playtests/performance.playtest.json +7 -5
  206. package/templates/platformer/playtests/respawn.playtest.json +2 -2
  207. package/templates/platformer/playtests/stomp-rise.playtest.json +17 -3
  208. package/templates/platformer/playtests/stomp.playtest.json +11 -3
  209. package/templates/platformer/playtests/survives.playtest.json +31 -0
  210. package/templates/platformer/playtests/terminal-loop-fail.playtest.json +16 -4
  211. package/templates/platformer/playtests/terminal-loop-win.playtest.json +3 -3
  212. package/templates/platformer/playtests/touch-controls-web.playtest.json +57 -0
  213. package/templates/platformer/src/conventions.ts +18 -0
  214. package/templates/platformer/src/entities/Character.ts +79 -11
  215. package/templates/platformer/src/entities/Patrol.ts +5 -0
  216. package/templates/platformer/src/game.ts +27 -2
  217. package/templates/platformer/src/level/Platform.ts +13 -1
  218. package/templates/platformer/src/render/lighting.ts +13 -5
  219. package/templates/platformer/src/render/loading.ts +281 -62
  220. package/templates/platformer/src/render/palette.ts +4 -1
  221. package/templates/platformer/src/render/postprocessing.ts +42 -14
  222. package/templates/platformer/src/render/quality.ts +170 -0
  223. package/templates/platformer/src/render/touch-controls.ts +54 -36
  224. package/templates/platformer/src/render/worldEnvironment.ts +758 -0
  225. package/templates/platformer/src/scenes/Level.ts +97 -32
  226. package/templates/platformer/src/state.ts +4 -0
  227. package/templates/platformer/src/style.css +65 -1
  228. package/templates/platformer/src/ui/App.tsx +9 -4
  229. package/templates/platformer/src/ui/GameUi.tsx +20 -0
  230. package/templates/platformer/src/ui/Hud.tsx +6 -5
  231. package/templates/platformer/src/ui/main.tsx +14 -0
  232. package/templates/platformer/threenative.config.ts +27 -10
  233. package/templates/platformer/vite.config.ts +34 -1
  234. package/templates/puzzle/.codex/config.toml +19 -0
  235. package/templates/puzzle/.cursor/mcp.json +32 -0
  236. package/templates/puzzle/.gemini/settings.json +32 -0
  237. package/templates/puzzle/.mcp.json +32 -0
  238. package/templates/puzzle/.vscode/mcp.json +36 -0
  239. package/templates/puzzle/.zed/settings.json +36 -0
  240. package/templates/puzzle/AGENTS.md +96 -0
  241. package/templates/puzzle/CLAUDE.md +98 -0
  242. package/templates/puzzle/README.md +43 -0
  243. package/templates/puzzle/index.html +12 -0
  244. package/templates/puzzle/kit.json +7 -0
  245. package/templates/puzzle/opencode.json +41 -0
  246. package/templates/puzzle/package.json +50 -0
  247. package/templates/puzzle/playtests/carry.playtest.json +71 -0
  248. package/templates/puzzle/playtests/performance.playtest.json +23 -0
  249. package/templates/puzzle/playtests/survives.playtest.json +51 -0
  250. package/templates/puzzle/playtests/swing.playtest.json +38 -0
  251. package/templates/puzzle/public/favicon.svg +5 -0
  252. package/templates/puzzle/src/conventions.ts +25 -0
  253. package/templates/puzzle/src/entities/Ball.ts +70 -0
  254. package/templates/puzzle/src/entities/Crate.ts +76 -0
  255. package/templates/puzzle/src/entities/Gripper.ts +69 -0
  256. package/templates/puzzle/src/entities/Pendulum.ts +89 -0
  257. package/templates/puzzle/src/game.ts +48 -0
  258. package/templates/puzzle/src/main.ts +15 -0
  259. package/templates/puzzle/src/physics.ts +19 -0
  260. package/templates/puzzle/src/render/camera.ts +37 -0
  261. package/templates/puzzle/src/render/lighting.ts +55 -0
  262. package/templates/puzzle/src/render/loading.ts +325 -0
  263. package/templates/puzzle/src/render/materials.ts +28 -0
  264. package/templates/puzzle/src/render/palette.ts +31 -0
  265. package/templates/puzzle/src/render/postprocessing.ts +34 -0
  266. package/templates/puzzle/src/render/quality.ts +170 -0
  267. package/templates/puzzle/src/render/shapes.ts +134 -0
  268. package/templates/puzzle/src/render/sky.ts +16 -0
  269. package/templates/puzzle/src/render/touch-controls.ts +185 -0
  270. package/templates/puzzle/src/render/worldEnvironment.ts +758 -0
  271. package/templates/puzzle/src/room.ts +83 -0
  272. package/templates/puzzle/src/scenes/Boot.ts +12 -0
  273. package/templates/puzzle/src/scenes/Puzzle.ts +158 -0
  274. package/templates/puzzle/src/state.ts +30 -0
  275. package/templates/puzzle/src/style.css +96 -0
  276. package/templates/puzzle/src/ui/App.tsx +22 -0
  277. package/templates/puzzle/src/ui/GameUi.tsx +20 -0
  278. package/templates/puzzle/src/ui/Hud.tsx +57 -0
  279. package/templates/puzzle/src/ui/Menu.tsx +7 -0
  280. package/templates/puzzle/src/ui/main.tsx +14 -0
  281. package/templates/puzzle/tailwind.config.ts +1 -0
  282. package/templates/puzzle/threenative.config.ts +49 -0
  283. package/templates/puzzle/tsconfig.json +17 -0
  284. package/templates/puzzle/vite.config.ts +38 -0
  285. package/templates/racing/.codex/config.toml +19 -0
  286. package/templates/racing/.cursor/mcp.json +32 -0
  287. package/templates/racing/.gemini/settings.json +32 -0
  288. package/templates/racing/.mcp.json +18 -2
  289. package/templates/racing/.vscode/mcp.json +36 -0
  290. package/templates/racing/.zed/settings.json +36 -0
  291. package/templates/racing/AGENTS.md +84 -36
  292. package/templates/racing/CLAUDE.md +84 -36
  293. package/templates/racing/index.html +0 -1
  294. package/templates/racing/native-playtests/survives.playtest.json +43 -0
  295. package/templates/racing/opencode.json +41 -0
  296. package/templates/racing/package.json +17 -12
  297. package/templates/racing/playtests/boost.playtest.json +5 -5
  298. package/templates/racing/playtests/outcome.playtest.json +14 -4
  299. package/templates/racing/playtests/performance.playtest.json +39 -0
  300. package/templates/racing/playtests/ranking.playtest.json +2 -2
  301. package/templates/racing/playtests/rescue.playtest.json +12 -6
  302. package/templates/racing/playtests/reverse.playtest.json +3 -3
  303. package/templates/racing/playtests/shortcut.playtest.json +3 -3
  304. package/templates/racing/playtests/survives.playtest.json +36 -4
  305. package/templates/racing/playtests/touch-controls.playtest.json +41 -0
  306. package/templates/racing/src/conventions.ts +6 -0
  307. package/templates/racing/src/entities/RacingCar.ts +16 -4
  308. package/templates/racing/src/entities/Rival.ts +5 -2
  309. package/templates/racing/src/game.ts +24 -1
  310. package/templates/racing/src/render/camera.ts +15 -8
  311. package/templates/racing/src/render/lighting.ts +28 -14
  312. package/templates/racing/src/render/loading.ts +302 -35
  313. package/templates/racing/src/render/materials.ts +54 -4
  314. package/templates/racing/src/render/palette.ts +23 -6
  315. package/templates/racing/src/render/postprocessing.ts +32 -12
  316. package/templates/racing/src/render/quality.ts +170 -0
  317. package/templates/racing/src/render/shapes.ts +537 -26
  318. package/templates/racing/src/render/sky.ts +5 -2
  319. package/templates/racing/src/render/touch-controls.ts +185 -0
  320. package/templates/racing/src/render/worldEnvironment.ts +758 -0
  321. package/templates/racing/src/scenes/Race.ts +84 -37
  322. package/templates/racing/src/state.ts +4 -0
  323. package/templates/racing/src/style.css +65 -1
  324. package/templates/racing/src/track/Lap.ts +20 -9
  325. package/templates/racing/src/track/Ranking.ts +53 -14
  326. package/templates/racing/src/track/Track.ts +284 -32
  327. package/templates/racing/src/track/TrackSector.ts +14 -4
  328. package/templates/racing/src/ui/App.tsx +9 -4
  329. package/templates/racing/src/ui/GameUi.tsx +20 -0
  330. package/templates/racing/src/ui/Hud.tsx +6 -5
  331. package/templates/racing/src/ui/main.tsx +14 -0
  332. package/templates/racing/threenative.config.ts +28 -8
  333. package/templates/racing/vite.config.ts +34 -1
  334. package/templates/runner/.codex/config.toml +19 -0
  335. package/templates/runner/.cursor/mcp.json +32 -0
  336. package/templates/runner/.gemini/settings.json +32 -0
  337. package/templates/runner/.mcp.json +32 -0
  338. package/templates/runner/.vscode/mcp.json +36 -0
  339. package/templates/runner/.zed/settings.json +36 -0
  340. package/templates/runner/AGENTS.md +96 -0
  341. package/templates/runner/CLAUDE.md +98 -0
  342. package/templates/runner/README.md +43 -0
  343. package/templates/runner/index.html +12 -0
  344. package/templates/runner/kit.json +7 -0
  345. package/templates/runner/opencode.json +41 -0
  346. package/templates/runner/package.json +50 -0
  347. package/templates/runner/playtests/performance.playtest.json +23 -0
  348. package/templates/runner/playtests/streams.playtest.json +38 -0
  349. package/templates/runner/playtests/survives.playtest.json +51 -0
  350. package/templates/runner/public/favicon.svg +5 -0
  351. package/templates/runner/src/conventions.ts +24 -0
  352. package/templates/runner/src/entities/Runner.ts +135 -0
  353. package/templates/runner/src/game.ts +50 -0
  354. package/templates/runner/src/main.ts +15 -0
  355. package/templates/runner/src/physics.ts +13 -0
  356. package/templates/runner/src/render/camera.ts +39 -0
  357. package/templates/runner/src/render/dust.ts +131 -0
  358. package/templates/runner/src/render/lighting.ts +57 -0
  359. package/templates/runner/src/render/loading.ts +325 -0
  360. package/templates/runner/src/render/materials.ts +27 -0
  361. package/templates/runner/src/render/palette.ts +30 -0
  362. package/templates/runner/src/render/postprocessing.ts +34 -0
  363. package/templates/runner/src/render/quality.ts +170 -0
  364. package/templates/runner/src/render/shapes.ts +68 -0
  365. package/templates/runner/src/render/sky.ts +51 -0
  366. package/templates/runner/src/render/touch-controls.ts +185 -0
  367. package/templates/runner/src/render/worldEnvironment.ts +758 -0
  368. package/templates/runner/src/scenes/Boot.ts +12 -0
  369. package/templates/runner/src/scenes/Run.ts +142 -0
  370. package/templates/runner/src/state.ts +29 -0
  371. package/templates/runner/src/style.css +96 -0
  372. package/templates/runner/src/track.ts +176 -0
  373. package/templates/runner/src/ui/App.tsx +22 -0
  374. package/templates/runner/src/ui/GameUi.tsx +20 -0
  375. package/templates/runner/src/ui/Hud.tsx +55 -0
  376. package/templates/runner/src/ui/Menu.tsx +7 -0
  377. package/templates/runner/src/ui/main.tsx +14 -0
  378. package/templates/runner/tailwind.config.ts +1 -0
  379. package/templates/runner/threenative.config.ts +49 -0
  380. package/templates/runner/tsconfig.json +17 -0
  381. package/templates/runner/vite.config.ts +38 -0
  382. package/templates/sailing/.codex/config.toml +19 -0
  383. package/templates/sailing/.cursor/mcp.json +32 -0
  384. package/templates/sailing/.gemini/settings.json +32 -0
  385. package/templates/sailing/.mcp.json +32 -0
  386. package/templates/sailing/.vscode/mcp.json +36 -0
  387. package/templates/sailing/.zed/settings.json +36 -0
  388. package/templates/sailing/AGENTS.md +95 -0
  389. package/templates/sailing/CLAUDE.md +97 -0
  390. package/templates/sailing/README.md +28 -0
  391. package/templates/sailing/index.html +12 -0
  392. package/templates/sailing/kit.json +7 -0
  393. package/templates/sailing/native-playtests/float.playtest.json +55 -0
  394. package/templates/sailing/native-playtests/survives.playtest.json +38 -0
  395. package/templates/sailing/opencode.json +41 -0
  396. package/templates/sailing/package.json +52 -0
  397. package/templates/sailing/playtests/fail.playtest.json +24 -0
  398. package/templates/sailing/playtests/float-after-the-run-ends.playtest.json +75 -0
  399. package/templates/sailing/playtests/float.playtest.json +59 -0
  400. package/templates/sailing/playtests/performance.playtest.json +36 -0
  401. package/templates/sailing/playtests/survives.playtest.json +46 -0
  402. package/templates/sailing/playtests/touch-controls.playtest.json +48 -0
  403. package/templates/sailing/playtests/win.playtest.json +31 -0
  404. package/templates/sailing/public/favicon.svg +5 -0
  405. package/templates/sailing/src/conventions.ts +8 -0
  406. package/templates/sailing/src/entities/Ship.ts +233 -0
  407. package/templates/sailing/src/game.ts +40 -0
  408. package/templates/sailing/src/main.ts +15 -0
  409. package/templates/sailing/src/render/camera.ts +28 -0
  410. package/templates/sailing/src/render/lighting.ts +41 -0
  411. package/templates/sailing/src/render/loading.ts +325 -0
  412. package/templates/sailing/src/render/materials.ts +44 -0
  413. package/templates/sailing/src/render/ocean.ts +179 -0
  414. package/templates/sailing/src/render/palette.ts +17 -0
  415. package/templates/sailing/src/render/postprocessing.ts +34 -0
  416. package/templates/sailing/src/render/props.ts +602 -0
  417. package/templates/sailing/src/render/quality.ts +140 -0
  418. package/templates/sailing/src/render/sky.ts +37 -0
  419. package/templates/sailing/src/render/touch-controls.ts +142 -0
  420. package/templates/sailing/src/render/worldEnvironment.ts +758 -0
  421. package/templates/sailing/src/scenes/Boot.ts +12 -0
  422. package/templates/sailing/src/scenes/Sailing.ts +133 -0
  423. package/templates/sailing/src/state.ts +10 -0
  424. package/templates/sailing/src/style.css +81 -0
  425. package/templates/sailing/src/ui/App.tsx +15 -0
  426. package/templates/sailing/src/ui/GameUi.tsx +12 -0
  427. package/templates/sailing/src/ui/Hud.tsx +55 -0
  428. package/templates/sailing/src/ui/Menu.tsx +30 -0
  429. package/templates/sailing/src/ui/main.tsx +7 -0
  430. package/templates/sailing/tailwind.config.ts +2 -0
  431. package/templates/sailing/threenative.config.ts +40 -0
  432. package/templates/sailing/tsconfig.json +17 -0
  433. package/templates/sailing/vite.config.ts +34 -0
  434. package/templates/shooter/.codex/config.toml +19 -0
  435. package/templates/shooter/.cursor/mcp.json +32 -0
  436. package/templates/shooter/.gemini/settings.json +32 -0
  437. package/templates/shooter/.mcp.json +18 -2
  438. package/templates/shooter/.vscode/mcp.json +36 -0
  439. package/templates/shooter/.zed/settings.json +36 -0
  440. package/templates/shooter/AGENTS.md +81 -54
  441. package/templates/shooter/CLAUDE.md +81 -54
  442. package/templates/shooter/index.html +0 -1
  443. package/templates/shooter/kit.json +2 -2
  444. package/templates/shooter/opencode.json +41 -0
  445. package/templates/shooter/package.json +16 -11
  446. package/templates/shooter/playtests/combat.playtest.json +48 -0
  447. package/templates/shooter/playtests/fail.playtest.json +5 -4
  448. package/templates/shooter/playtests/input-control.playtest.json +261 -0
  449. package/templates/shooter/playtests/per-item.playtest.json +59 -0
  450. package/templates/shooter/playtests/performance.playtest.json +39 -0
  451. package/templates/shooter/playtests/shooter.playtest.json +31 -21
  452. package/templates/shooter/playtests/survives.playtest.json +28 -1
  453. package/templates/shooter/playtests/touch-controls.playtest.json +42 -0
  454. package/templates/shooter/playtests/weapon-cycle.playtest.json +164 -0
  455. package/templates/shooter/public/favicon.svg +1 -1
  456. package/templates/shooter/src/combat/damage.ts +1 -2
  457. package/templates/shooter/src/conventions.ts +51 -0
  458. package/templates/shooter/src/entities/Player.ts +235 -18
  459. package/templates/shooter/src/entities/Target.ts +2 -2
  460. package/templates/shooter/src/game.ts +35 -3
  461. package/templates/shooter/src/main.ts +3 -13
  462. package/templates/shooter/src/render/camera.ts +78 -18
  463. package/templates/shooter/src/render/decals.ts +211 -0
  464. package/templates/shooter/src/render/lighting.ts +13 -4
  465. package/templates/shooter/src/render/loading.ts +274 -35
  466. package/templates/shooter/src/render/materials.ts +56 -3
  467. package/templates/shooter/src/render/palette.ts +6 -3
  468. package/templates/shooter/src/render/postprocessing.ts +32 -17
  469. package/templates/shooter/src/render/quality.ts +170 -0
  470. package/templates/shooter/src/render/scale.ts +22 -0
  471. package/templates/shooter/src/render/shapes.ts +519 -60
  472. package/templates/shooter/src/render/sky.ts +5 -1
  473. package/templates/shooter/src/render/touch-controls.ts +305 -0
  474. package/templates/shooter/src/render/ui.css +119 -1
  475. package/templates/shooter/src/render/ui.ts +19 -3
  476. package/templates/shooter/src/render/vfx.ts +215 -0
  477. package/templates/shooter/src/render/worldEnvironment.ts +758 -0
  478. package/templates/shooter/src/scenes/Play.ts +385 -97
  479. package/templates/shooter/src/state.ts +18 -0
  480. package/templates/shooter/src/style.css +46 -0
  481. package/templates/shooter/src/ui/App.tsx +10 -12
  482. package/templates/shooter/src/ui/Crosshair.tsx +25 -0
  483. package/templates/shooter/src/ui/GameUi.tsx +22 -0
  484. package/templates/shooter/src/ui/Hud.tsx +14 -10
  485. package/templates/shooter/src/ui/Menu.tsx +24 -9
  486. package/templates/shooter/src/ui/main.tsx +15 -0
  487. package/templates/shooter/src/weapons/Hitscan.ts +3 -4
  488. package/templates/shooter/src/weapons/Projectile.ts +29 -13
  489. package/templates/shooter/src/weapons/Viewmodel.ts +275 -0
  490. package/templates/shooter/threenative.config.ts +28 -8
  491. package/templates/shooter/vite.config.ts +32 -2
  492. package/templates/starter/.codex/config.toml +19 -0
  493. package/templates/starter/.cursor/mcp.json +32 -0
  494. package/templates/starter/.gemini/settings.json +32 -0
  495. package/templates/starter/.mcp.json +18 -2
  496. package/templates/starter/.vscode/mcp.json +36 -0
  497. package/templates/starter/.zed/settings.json +36 -0
  498. package/templates/starter/AGENTS.md +72 -426
  499. package/templates/starter/CLAUDE.md +72 -426
  500. package/templates/starter/assets/pickup.wav +0 -0
  501. package/templates/starter/gitignore +4 -0
  502. package/templates/starter/index.html +0 -1
  503. package/templates/starter/native-playtests/react-hud.playtest.json +20 -0
  504. package/templates/starter/native-playtests/render-chain.playtest.json +81 -0
  505. package/templates/starter/opencode.json +41 -0
  506. package/templates/starter/package.json +16 -12
  507. package/templates/starter/playtests/assets.playtest.json +65 -0
  508. package/templates/starter/playtests/boot-failure.playtest.json +45 -0
  509. package/templates/starter/playtests/buffer.playtest.json +59 -9
  510. package/templates/starter/playtests/cloth.playtest.json +113 -0
  511. package/templates/starter/playtests/coyote.playtest.json +60 -8
  512. package/templates/starter/playtests/forward.playtest.json +29 -4
  513. package/templates/starter/playtests/gameover.playtest.json +66 -0
  514. package/templates/starter/playtests/goal.playtest.json +67 -0
  515. package/templates/starter/playtests/hot-reload.playtest.json +48 -8
  516. package/templates/starter/playtests/look.playtest.json +142 -10
  517. package/templates/starter/playtests/models-baseline.png +0 -0
  518. package/templates/starter/playtests/models.playtest.json +74 -0
  519. package/templates/starter/playtests/monitoring.playtest.json +38 -7
  520. package/templates/starter/playtests/odometer.playtest.json +54 -0
  521. package/templates/starter/playtests/pause.playtest.json +27 -4
  522. package/templates/starter/playtests/play.playtest.json +44 -7
  523. package/templates/starter/playtests/respawn.playtest.json +46 -6
  524. package/templates/starter/playtests/restart.playtest.json +65 -10
  525. package/templates/starter/playtests/seed.playtest.json +44 -8
  526. package/templates/starter/playtests/survives.playtest.json +48 -4
  527. package/templates/starter/playtests/textures-baseline.png +0 -0
  528. package/templates/starter/playtests/textures.playtest.json +74 -0
  529. package/templates/starter/playtests/touch-controls.playtest.json +42 -0
  530. package/templates/starter/playtests/zoom-pinch.playtest.json +86 -0
  531. package/templates/starter/playtests/zoom-wheel.playtest.json +59 -0
  532. package/templates/starter/src/conventions.ts +18 -0
  533. package/templates/starter/src/entities/Goal.ts +137 -0
  534. package/templates/starter/src/entities/Player.ts +111 -10
  535. package/templates/starter/src/game.ts +27 -0
  536. package/templates/starter/src/render/adaptiveQuality.ts +195 -0
  537. package/templates/starter/src/render/camera.ts +31 -5
  538. package/templates/starter/src/render/coast.ts +199 -0
  539. package/templates/starter/src/render/easing.ts +5 -0
  540. package/templates/starter/src/render/effects/gradualBackground.ts +48 -0
  541. package/templates/starter/src/render/effects/lensDistortion.ts +43 -0
  542. package/templates/starter/src/render/effects/sparkle.ts +49 -0
  543. package/templates/starter/src/render/hero.ts +88 -0
  544. package/templates/starter/src/render/implicitSurface.ts +199 -0
  545. package/templates/starter/src/render/kuwahara.ts +174 -0
  546. package/templates/starter/src/render/lighting.ts +10 -5
  547. package/templates/starter/src/render/loading.ts +325 -0
  548. package/templates/starter/src/render/materials.ts +39 -4
  549. package/templates/starter/src/render/outline.ts +141 -0
  550. package/templates/starter/src/render/painterly.ts +86 -0
  551. package/templates/starter/src/render/palette.ts +15 -6
  552. package/templates/starter/src/render/pennant.ts +54 -0
  553. package/templates/starter/src/render/postprocessing.ts +97 -15
  554. package/templates/starter/src/render/quality.ts +185 -0
  555. package/templates/starter/src/render/rockRidge.ts +198 -0
  556. package/templates/starter/src/render/rockRidge.worker.ts +77 -0
  557. package/templates/starter/src/render/scenery.ts +40 -0
  558. package/templates/starter/src/render/shapes.ts +9 -21
  559. package/templates/starter/src/render/textureLifetime.ts +53 -0
  560. package/templates/starter/src/render/touch-controls.ts +165 -0
  561. package/templates/starter/src/render/water.ts +38 -0
  562. package/templates/starter/src/render/watercolor.ts +85 -0
  563. package/templates/starter/src/render/worldEnvironment.ts +758 -0
  564. package/templates/starter/src/scenes/Play.ts +243 -46
  565. package/templates/starter/src/state.ts +12 -0
  566. package/templates/starter/src/style.css +72 -8
  567. package/templates/starter/src/ui/App.tsx +9 -6
  568. package/templates/starter/src/ui/GameUi.tsx +20 -0
  569. package/templates/starter/src/ui/Hud.tsx +52 -29
  570. package/templates/starter/src/ui/Menu.tsx +25 -23
  571. package/templates/starter/src/ui/main.tsx +14 -0
  572. package/templates/starter/threenative.config.ts +27 -9
  573. package/templates/starter/tools/look.mjs +109 -0
  574. package/templates/starter/vite.config.ts +32 -2
  575. package/templates/action-rpg/src/physics.ts +0 -40
  576. package/templates/minimal/assets/.gitkeep +0 -0
  577. package/templates/minimal/public/.gitkeep +0 -0
  578. package/templates/minimal/public/icon.png +0 -0
  579. package/templates/platformer/assets/.gitkeep +0 -0
  580. package/templates/platformer/public/.gitkeep +0 -0
  581. package/templates/platformer/public/icon.png +0 -0
  582. package/templates/shooter/src/physics.ts +0 -49
  583. package/templates/starter/assets/.gitkeep +0 -0
  584. package/templates/starter/public/.gitkeep +0 -0
  585. package/templates/starter/public/icon.png +0 -0
  586. package/templates/starter/public/pickup.ogg +0 -0
  587. /package/templates/starter/{public → assets}/native-proof.glb +0 -0
  588. /package/templates/starter/{public → assets}/native-proof.png +0 -0
@@ -0,0 +1,4483 @@
1
+ <!-- Generated by scripts/generate-capability-reference.ts from capabilities.json — do not hand-edit. -->
2
+ <!-- Regenerate: pnpm build -->
3
+
4
+ # Capability reference
5
+
6
+ Every public class and function export represented by this manifest across `@threenative/assets`, `@threenative/core`, `@threenative/physics`, `@threenative/playtest`, `@threenative/raw-unreal`, `@threenative/ueformat`, `@threenative/ui`, `template:starter`, and `three`,
7
+ generated from the doc tags the engine itself compiles, so this page cannot disagree with
8
+ the code. Look here before writing a replacement; ask `engine_search_capabilities` when an
9
+ MCP server is available.
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
+
238
+ ## `@threenative/core`
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
+
274
+ ### `AnimationPlayer`
275
+
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.
277
+
278
+ ```ts
279
+ export class AnimationPlayer { … }
280
+ ```
281
+
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
284
+ - **Overrides:** strideSync controls whether the matched rate is applied while stride is still measured
285
+
286
+ ```ts
287
+ const player = new AnimationPlayer({ clips, root: rig, strideRoot: body });
288
+ ```
289
+
290
+ ### `Atmosphere`
291
+
292
+ `class` — Own the compute lifetime and expose only parameter-driven atmosphere nodes. The class deliberately creates no mesh, material, or scene light. A template chooses all of those, and the same object remains useful when a game supplies a completely different look.
293
+
294
+ ```ts
295
+ export class Atmosphere extends Group implements IComputeDriven { … }
296
+ ```
297
+
298
+ - **Use when:** render a sunrise that changes as time and place change · add distance haze from the depth of a scene pass
299
+ - **Constraints:** supply rayleigh, mie, ozone, planetRadius, and atmosphereRadius; there is no Earth fallback · the game creates the sky object, surface, and sun from the returned nodes
300
+
301
+ ```ts
302
+ const atmosphere = new Atmosphere({ rayleigh, mie, ozone, planetRadius, atmosphereRadius });
303
+ ctx.add(atmosphere);
304
+ ```
305
+
306
+ ### `AtmosphereLuts`
307
+
308
+ `class` — Own the transmittance, multi-scattering, and sky-view compute lookup textures.
309
+
310
+ ```ts
311
+ export class AtmosphereLuts { … }
312
+ ```
313
+
314
+ - **Use when:** bake the three atmosphere LUTs once before a game shows its world
315
+ - **Constraints:** supply all physical parameters; this class creates no scene appearance
316
+
317
+ ```ts
318
+ const luts = new AtmosphereLuts({ rayleigh, mie, ozone, planetRadius, atmosphereRadius });
319
+ ```
320
+
321
+ ### `attachToBone`
322
+
323
+ `function` — Attach a game-owned object to a named skeleton bone.
324
+
325
+ ```ts
326
+ export function attachToBone(root: Object3D, boneName: string, child: Object3D): Object3D { … }
327
+ ```
328
+
329
+ - **Use when:** put a weapon in a character's hand · hold a rifle in a character's right hand · add an enemy that patrols the level, chases the player when it sees them, and holds a rifle in its right hand · attach an accessory to a skinned model · equip crew with swords and pistols · put a sword or pistol in a crew member's hand
330
+ - **Constraints:** when a request is to hold or attach a weapon to a hand, import and call `attachToBone` from `@threenative/core`; do not manually parent, position, or rotate the rifle · if a stock visual has no skeleton, add a portable Three.js Bone named `RightHand` under the character, then call `attachToBone`; do not replace the helper with manual parenting
331
+
332
+ ```ts
333
+ import { attachToBone } from "@threenative/core";
334
+ attachToBone(character, "RightHand", rifle);
335
+ ```
336
+
337
+ ### `AudioBus`
338
+
339
+ `class` — Route effects through a named audio bus.
340
+
341
+ ```ts
342
+ export class AudioBus { … }
343
+ ```
344
+
345
+ - **Use when:** play a sound effect with a volume bus · mute or adjust a category of game audio · keep a gunshot audible at 20 metres by tuning positional falloff · play cannon, wave, and ship sound effects
346
+ - **Constraints:** create buses before playing clips and dispose them with the game · refDistance and rolloffFactor tune positional falloff and apply to playAt only
347
+ - **Supersedes (writing this fails `pnpm budgets`):** new Audio(
348
+
349
+ ```ts
350
+ const effects = new AudioBus({ camera });
351
+ ```
352
+
353
+ ### `Billboard3D`
354
+
355
+ `class` — Face a game-owned object toward a perspective or orthographic camera.
356
+
357
+ ```ts
358
+ export class Billboard3D { … }
359
+ ```
360
+
361
+ - **Use when:** keep a world-space marker or nameplate facing the camera · billboard a tree, label, or effect under a rotated parent
362
+ - **Constraints:** call update from the owning scene; no global scene scan is installed · orthographic cameras use their forward direction, and lockAxis restricts world rotation
363
+
364
+ ```ts
365
+ const billboard = new Billboard3D(label, { camera });
366
+ billboard.update();
367
+ ```
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
+
418
+ ### `CameraShake`
419
+
420
+ `class` — Produce a game-authored camera shake offset for a template-owned camera rig.
421
+
422
+ ```ts
423
+ export class CameraShake { … }
424
+ ```
425
+
426
+ - **Use when:** add a hit, explosion, or landing shake to a camera · compose a transient camera offset after camera damping
427
+ - **Constraints:** amplitude, rotationAmplitude, frequency, decay, and curve are required game choices · update returns an offset and never writes to a camera
428
+
429
+ ```ts
430
+ const shake = new CameraShake({ amplitude, rotationAmplitude, frequency, decay, curve });
431
+ ```
432
+
433
+ ### `CanvasLayer`
434
+
435
+ `class` — Manage a camera or screen-facing canvas layer.
436
+
437
+ ```ts
438
+ export class CanvasLayer { … }
439
+ ```
440
+
441
+ - **Use when:** place a HUD layer above the Three.js scene · attach a canvas layer to a camera
442
+
443
+ ```ts
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);
494
+ ```
495
+
496
+ ### `ClusteredBatch`
497
+
498
+ `class` — Draw many copies of one over-detailed body, each at the detail its own distance earns. `InstancedBatch` collapses repeated props into one draw and gives every copy the same triangles. This gives a copy two hundred metres away a coarser cut than one twelve metres away, and still submits one draw per distance group rather than one per copy — which is what makes four hundred scanned boulders affordable. The shape, the surface and every transform stay the game's.
499
+
500
+ ```ts
501
+ export class ClusteredBatch { … }
502
+ ```
503
+
504
+ - **Use when:** draw hundreds of copies of a scanned or sculpted body without hundreds of draw calls · stop distant copies of a dense prop from costing their full triangle count
505
+ - **Constraints:** the body's geometry must carry a cluster table from `assets.models.virtual` · every copy is placed before build(); place() after build() throws
506
+ - **Overrides:** distanceRatio sets how wide one distance group is, default 1.25 · errorPixels sets the screen-space error budget, default 1 pixel
507
+
508
+ ```ts
509
+ const boulders = new ClusteredBatch({ geometry, material, table });
510
+ boulders.place({ position: [x, y, z], rotation: [0, angle, 0] });
511
+ boulders.build({ name: "boulders", parent: ctx.scene });
512
+ // in the scene's update, before the render:
513
+ boulders.update(ctx.camera, ctx.renderer.domElement.height);
514
+ ```
515
+
516
+ ### `ClusteredMesh`
517
+
518
+ `class` — Draw a model too detailed for the screen to resolve, without submitting the part it cannot. **This is on, and a game does not call it.** Any primitive of 65,536 triangles or more bakes to a cluster DAG in the asset pipeline, the loader returns a `ClusteredMesh` for it, and the engine takes the cut every frame before it renders. Each frame the mesh submits one draw holding only the clusters whose error projects to fewer than `errorPixels` screen pixels; a mesh nothing has cut yet draws in full, so the worst case is an ordinary `Mesh`. Geometry, surface and every appearance parameter stay the game's.
519
+
520
+ ```ts
521
+ export class ClusteredMesh extends Mesh { … }
522
+ ```
523
+
524
+ - **Use when:** draw a model too detailed for the screen to resolve · import a scanned or sculpted mesh of millions of triangles and still hold the frame · stop a dense rock face or terrain body from costing its full triangle count up close
525
+ - **Constraints:** the bake happens in the asset pipeline, never at run time — there is no runtime flag · the payload costs about 3-4x a baked primitive's bytes; `assets.models.virtual: "none"` opts out and `minSourceTriangles` moves the 65,536 line · needs a perspective camera; a screen-space error has no meaning without one · one shadow cut is chosen at load and does not follow a shadow camera
526
+ - **Overrides:** errorPixels sets the screen-space error budget, default 1 pixel · recutDistance sets how far the camera moves before the cut is retaken, default a thousandth of the mesh's radius
527
+
528
+ ```ts
529
+ // Nothing to call: the loader returns one of these and the engine cuts it every frame.
530
+ const face = await ctx.assets.model("quarry-face.glb");
531
+ ctx.scene.add(face.scene);
532
+ ```
533
+
534
+ ### `ComputeDrivenRegistry`
535
+
536
+ `class` — Register game-owned IComputeDriven objects with the shared compute lifetime.
537
+
538
+ ```ts
539
+ export class ComputeDrivenRegistry { … }
540
+ ```
541
+
542
+ - **Use when:** use IComputeDriven for a cloth, fluid, boid, or other GPU simulation · run a cloth or fluid simulation with ordered GPU passes · keep IComputeDriven kernels warm before the first visible frame
543
+ - **Constraints:** add the object through ctx.add so it attaches, dispatches, and releases with its scene
544
+
545
+ ```ts
546
+ const registry = new ComputeDrivenRegistry(); registry.add(cloth, ctx.renderer.raw);
547
+ ```
548
+
549
+ ### `createAssetLoader`
550
+
551
+ `function` — Create the portable asset loader a scene also receives as `ctx.assets`.
552
+
553
+ ```ts
554
+ export function createAssetLoader(options: IAssetLoaderOptions = { … }
555
+ ```
556
+
557
+ - **Use when:** preload models, textures, or audio before a scene enters · load assets from a nonstandard base path or a compiled asset manifest
558
+ - **Constraints:** reuse the loader handed to scenes as `ctx.assets` instead of building parallel caches
559
+
560
+ ```ts
561
+ const assets = createAssetLoader({ basePath: "/assets" });
562
+ const rock = await assets.texture("rock.png");
563
+ ```
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
+
582
+ ### `createRandom`
583
+
584
+ `function` — Create a deterministic random source for portable gameplay.
585
+
586
+ ```ts
587
+ export function createRandom(seed?: number): IRandom { … }
588
+ ```
589
+
590
+ - **Use when:** seed enemy patrol choices · reproduce the same procedural level in a playtest
591
+ - **Constraints:** use the returned source instead of Math.random for replayable behavior
592
+ - **Supersedes (writing this fails `pnpm budgets`):** Math.random(
593
+
594
+ ```ts
595
+ const random = createRandom(42);
596
+ ```
597
+
598
+ ### `createReplayDriver`
599
+
600
+ `function` — Record or replay deterministic game input and state.
601
+
602
+ ```ts
603
+ export function createReplayDriver( recording: Recording, target: EventTarget, pointerTarget = target, ) { … }
604
+ ```
605
+
606
+ - **Use when:** reproduce a gameplay bug from recorded input · run a deterministic replay in a playtest
607
+ - **Constraints:** use a seeded random source and fixed-step simulation for meaningful replays
608
+
609
+ ```ts
610
+ const driver = createReplayDriver(recording, ctx.renderer.domElement);
611
+ ```
612
+
613
+ ### `defineGame`
614
+
615
+ `function` — Define the portable game entry shared by web and native.
616
+
617
+ ```ts
618
+ export function defineGame<TState extends Record<string, unknown>, TPhysics = undefined>( config: IGameConfig<TState, TPhysics>, ): IGame<TState, TPhysics> { … }
619
+ ```
620
+
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
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
623
+
624
+ ```ts
625
+ const game = defineGame({ input: { zoom: { scroll: true, pinch: true } }, scenes: { Play }, start: "Play" });
626
+ ```
627
+
628
+ ### `directionalTransmittance`
629
+
630
+ `function` — Approximate direct transmittance for a ray leaving the game surface.
631
+
632
+ ```ts
633
+ export function directionalTransmittance( parameters: IAtmosphereParameters | IResolvedAtmosphereParameters, direction: Vector3, ): Vector3 { … }
634
+ ```
635
+
636
+ - **Use when:** colour a game-owned sun from atmosphere extinction
637
+ - **Constraints:** pass a non-zero direction; coefficients and radii come from the game
638
+
639
+ ```ts
640
+ const transmittance = directionalTransmittance(parameters, sunDirection);
641
+ ```
642
+
643
+ ### `directionFromSolarPosition`
644
+
645
+ `function` — Convert solar elevation and azimuth degrees into a normalized Three.js direction.
646
+
647
+ ```ts
648
+ export function directionFromSolarPosition(elevation: number, azimuth: number): Vector3 { … }
649
+ ```
650
+
651
+ - **Use when:** aim a template's sun from solarPosition output
652
+ - **Constraints:** elevation and azimuth must be finite degrees
653
+
654
+ ```ts
655
+ const direction = directionFromSolarPosition(sun.elevation, sun.azimuth);
656
+ ```
657
+
658
+ ### `ensureVelocityOutput`
659
+
660
+ `function` — Provision screen-space motion data for temporal nodes and keep per-instance history at the frame boundary.
661
+
662
+ ```ts
663
+ export function ensureVelocityOutput(pass: IVelocityRenderPass): MRTNode { … }
664
+ ```
665
+
666
+ - **Use when:** keep a skinned character or instanced crowd stable in a temporal stage · add the velocity output to a Three.js scene pass · add a velocity target before a temporal stage consumes a scene pass
667
+ - **Constraints:** call `VelocityTracker.update()` before the render and `commit()` after it · a pass is only given a velocity target when a temporal stage consumes it · call only when a temporal stage is active
668
+
669
+ ```ts
670
+ const scenePass = pass(scene, camera);
671
+ ensureVelocityOutput(scenePass);
672
+ renderer.setOutputNode(scenePass);
673
+ const tracker = new VelocityTracker();
674
+ tracker.update(scene);
675
+ renderer.render(scene, camera);
676
+ tracker.commit(scene);
677
+ ```
678
+
679
+ ### `FluidField2D`
680
+
681
+ `class` — Simulate a deterministic 2D velocity-and-dye field on the GPU while exposing its data to game-owned rendering.
682
+
683
+ ```ts
684
+ export class FluidField2D extends Group { … }
685
+ ```
686
+
687
+ - **Use when:** simulate smoke, fire, fog, wind, or fluid response on a grid · inject a touch, pointer, or gameplay impulse into a fluid field · sample fluid dye or velocity in a game-owned render node · simulate ocean currents and wind affecting a sailing ship · simulate ocean fluid dynamics and currents that affect a ship
688
+ - **Constraints:** add the field through `ctx.add` so renderer attachment, fixed-step dispatch, and release are automatic · `dye` and `velocity` are numeric samplers; appearance stays in the game's `src/render/` code · the conformance sample measures mean absolute velocity divergence at 0.001732 after four 32² steps with pressureIterations 2, below the 0.0025 threshold
689
+ - **Overrides:** pressureIterations, viscosity, vorticity, and splatRadius tune the solver without changing its pass order
690
+
691
+ ```ts
692
+ const field = new FluidField2D({ resolution: 256, pressureIterations: 20 });
693
+ ctx.add(field);
694
+ field.splat({ x: 0.5, y: 0.5 }, { x: 0.2, y: 0 }, 1);
695
+ ```
696
+
697
+ ### `FrameBudget`
698
+
699
+ `class` — Read where the frame's milliseconds went, per presented frame, on any platform.
700
+
701
+ ```ts
702
+ export class FrameBudget { … }
703
+ ```
704
+
705
+ - **Use when:** find out why a game runs slowly on a phone · attribute a frame to present wait, simulation, three.js render, or overlay
706
+ - **Constraints:** on by default and printed as TN_FRAME_BUDGET; defineGame({ frameBudget: false }) silences the marker, not the measurement
707
+
708
+ ```ts
709
+ defineGame({ frameBudget: { reportEvery: 120 }, scenes: { Play } });
710
+ ```
711
+
712
+ ### `getPlatform`
713
+
714
+ `function` — Read the host platform without reaching for browser globals.
715
+
716
+ ```ts
717
+ export function getPlatform(): Readonly<IPlatformInfo> { … }
718
+ ```
719
+
720
+ - **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native
721
+ - **Constraints:** only use the returned platform facts; native globals are host-owned · ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result
722
+
723
+ ```ts
724
+ if (isMobile()) showTouchControls();
725
+ ```
726
+
727
+ ### `GPUParticles3D`
728
+
729
+ `class` — Dispatch a game-owned particle surface and process function through a pooled system.
730
+
731
+ ```ts
732
+ export class GPUParticles3D extends Sprite implements IComputeDriven { … }
733
+ ```
734
+
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
736
+ - **Constraints:** geometry, color, and timing remain supplied by the game
737
+
738
+ ```ts
739
+ const particles = new GPUParticles3D(particleOptions);
740
+ ```
741
+
742
+ ### `GPUReadback`
743
+
744
+ `class` — Copy a GPU buffer back to the CPU on a throttle, and report how old each sample is.
745
+
746
+ ```ts
747
+ export class GPUReadback { … }
748
+ ```
749
+
750
+ - **Use when:** read a GPU simulation on the CPU without stalling the frame · float a body on a wave field whose height only exists on the GPU · count GPU-side survivors for a diagnostic without blocking drawing · keep a ship floating on simulated ocean waves
751
+ - **Constraints:** the copy is asynchronous, so every sample carries staleFrames and is never this frame · WebGPU only; the seam throws on a WebGL2 renderer rather than returning nothing · one copy is in flight at a time and requests made during one are dropped, not queued
752
+
753
+ ```ts
754
+ const heights = new GPUReadback({ attribute: field.value, everyFrames: 4 });
755
+ ```
756
+
757
+ ### `GPUSceneBVH`
758
+
759
+ `class` — Pack a selected static scene into TSL storage nodes for an upstream BVH ray query.
760
+
761
+ ```ts
762
+ export class GPUSceneBVH extends Group implements IComputeDriven { … }
763
+ ```
764
+
765
+ - **Use when:** trace thousands of scene rays inside a TSL kernel · build a contact-occlusion or visibility query over loaded meshes
766
+ - **Constraints:** call rebuild() after a scene transform or geometry change; the snapshot is static by default · rebuild() is an explicit CPU SAH build proportional to selected triangles; process() is a no-op, and the game pays upstream traversal per shader ray
767
+
768
+ ```ts
769
+ const bvh = ctx.add(new GPUSceneBVH(ctx.scene, { include: (object) => object.userData.traceable === true }));
770
+ ```
771
+
772
+ ### `GroundSnap`
773
+
774
+ `class` — Keep a rendered model's feet on a surface while preserving an auditable override.
775
+
776
+ ```ts
777
+ export class GroundSnap { … }
778
+ ```
779
+
780
+ - **Use when:** keep a character's feet on the floor · correct visual grounding after an animation update
781
+ - **Constraints:** import from `@threenative/core`; this moves the rendered model, not its physics collider
782
+ - **Overrides:** enabled controls whether correction is applied while clearance is still measured
783
+
784
+ ```ts
785
+ import { GroundSnap } from "@threenative/core";
786
+ const snap = new GroundSnap(character, { enabled: true });
787
+ ```
788
+
789
+ ### `InstancedBatch`
790
+
791
+ `class` — Collapse many copies of one game-authored shape into a single draw, without counting them first. `new InstancedMesh(geometry, material, count)` needs the count before anything is placed, so a procedural builder ends up walking its layout twice or over-allocating. Place as you go and `build()` once; the shape, the surface and every transform stay the game's, and the built mesh is returned so instances can still be animated by the index `place` and `span` hand back.
792
+
793
+ ```ts
794
+ export class InstancedBatch { … }
795
+ ```
796
+
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
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
799
+ - **Overrides:** castShadow and receiveShadow pass through to the built mesh and default to Three.js's own false
800
+
801
+ ```ts
802
+ const curbs = new InstancedBatch({ geometry: new BoxGeometry(1, 1, 1), material });
803
+ curbs.place({ position: [x, 0.08, z], rotation: [0, angle, 0], scale: [length, 0.18, 0.42] });
804
+ curbs.build({ castShadow: true, name: "curbs", parent: ctx.scene });
805
+ ```
806
+
807
+ ### `isMobile`
808
+
809
+ `function` — Read the host platform without reaching for browser globals.
810
+
811
+ ```ts
812
+ export function isMobile(): boolean { … }
813
+ ```
814
+
815
+ - **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native
816
+ - **Constraints:** only use the returned platform facts; native globals are host-owned · ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result
817
+
818
+ ```ts
819
+ if (isMobile()) showTouchControls();
820
+ ```
821
+
822
+ ### `isNative`
823
+
824
+ `function` — Read the host platform without reaching for browser globals.
825
+
826
+ ```ts
827
+ export function isNative(): boolean { … }
828
+ ```
829
+
830
+ - **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native
831
+ - **Constraints:** only use the returned platform facts; native globals are host-owned · ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result
832
+
833
+ ```ts
834
+ if (isMobile()) showTouchControls();
835
+ ```
836
+
837
+ ### `isTouchscreenAvailable`
838
+
839
+ `function` — Read the host platform without reaching for browser globals.
840
+
841
+ ```ts
842
+ export function isTouchscreenAvailable(): boolean { … }
843
+ ```
844
+
845
+ - **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native
846
+ - **Constraints:** only use the returned platform facts; native globals are host-owned · ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result
847
+
848
+ ```ts
849
+ if (isMobile()) showTouchControls();
850
+ ```
851
+
852
+ ### `isWeb`
853
+
854
+ `function` — Read the host platform without reaching for browser globals.
855
+
856
+ ```ts
857
+ export function isWeb(): boolean { … }
858
+ ```
859
+
860
+ - **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native
861
+ - **Constraints:** only use the returned platform facts; native globals are host-owned · ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result
862
+
863
+ ```ts
864
+ if (isMobile()) showTouchControls();
865
+ ```
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
+
883
+ ### `measureThreePose`
884
+
885
+ `function` — Measure a Three.js pose for grounded or attachment-aware checks.
886
+
887
+ ```ts
888
+ export function measureThreePose( object: Object3D, options: IMeasureThreePoseOptions = { … }
889
+ ```
890
+
891
+ - **Use when:** inspect a skinned model's posed bounds · verify a character's visual pose
892
+ - **Constraints:** precise per-vertex measurement is opt-in and not for frame loops
893
+
894
+ ```ts
895
+ const measurement = measureThreePose(model);
896
+ ```
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
+
916
+ ### `normaliseToMetres`
917
+
918
+ `function` — Scale an asset to a real-world measurement and return the applied factor.
919
+
920
+ ```ts
921
+ export function normaliseToMetres(object: Object3D, options: INormaliseToMetresOptions): number { … }
922
+ ```
923
+
924
+ - **Use when:** make a character exactly 1.8 metres tall · normalize a prop or weapon to a known longest axis
925
+ - **Constraints:** skinned height uses a crown bone; game-specific asset expectations stay in render code
926
+ - **Supersedes (writing this fails `pnpm budgets`):** new Box3().setFromObject(
927
+
928
+ ```ts
929
+ normaliseToMetres(character, { metres: 1.8, axis: "height" });
930
+ ```
931
+
932
+ ### `parseReplayRecording`
933
+
934
+ `function` — Validate and parse a replay recording file.
935
+
936
+ ```ts
937
+ export function parseReplayRecording(value: unknown): IReplayRecording { … }
938
+ ```
939
+
940
+ - **Use when:** validate a recording before replaying it in another host
941
+ - **Constraints:** recordings are version 1; the parser fails closed with TN_REPLAY_* codes
942
+
943
+ ```ts
944
+ const recording = parseReplayRecording(rawRecording);
945
+ ```
946
+
947
+ ### `PathFollow3D`
948
+
949
+ `class` — Move an object along a Three.js curve with Godot-style path following.
950
+
951
+ ```ts
952
+ export class PathFollow3D { … }
953
+ ```
954
+
955
+ - **Use when:** move an enemy or prop along a patrol path · sample a racing line from a curve
956
+
957
+ ```ts
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.
976
+ ```
977
+
978
+ ### `PointerEvents3D`
979
+
980
+ `class` — Dispatch portable pointer events from the game surface to registered Three.js objects.
981
+
982
+ ```ts
983
+ export class PointerEvents3D implements IPointerEvents3D { … }
984
+ ```
985
+
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
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
988
+
989
+ ```ts
990
+ ctx.pointer.on(tile, "tapped", (event) => place(event.point));
991
+ ```
992
+
993
+ ### `posedBounds`
994
+
995
+ `function` — Measure a Three.js pose for grounded or attachment-aware checks.
996
+
997
+ ```ts
998
+ export function posedBounds(root: Object3D, meshes?: readonly Object3D[]): IThreePoseBounds { … }
999
+ ```
1000
+
1001
+ - **Use when:** inspect a skinned model's posed bounds · verify a character's visual pose
1002
+ - **Constraints:** precise per-vertex measurement is opt-in and not for frame loops
1003
+
1004
+ ```ts
1005
+ const measurement = measureThreePose(model);
1006
+ ```
1007
+
1008
+ ### `prewarm`
1009
+
1010
+ `function` — Keep transient render surfaces in the renderer's pipeline cache before first use.
1011
+
1012
+ ```ts
1013
+ export function prewarm(object: Object3D | readonly Object3D[]): void { … }
1014
+ ```
1015
+
1016
+ - **Use when:** prewarm a projectile, tracer, particle, or other transient effect · avoid a long first-use frame for a newly visible effect
1017
+ - **Constraints:** keep the surface visible with zero opacity; do not hide it with `visible = false`
1018
+ - **Supersedes (writing this fails `pnpm budgets`):** .visible = false
1019
+
1020
+ ```ts
1021
+ prewarm(tracerPool);
1022
+ ```
1023
+
1024
+ ### `ProbeVolume`
1025
+
1026
+ `class` — Bake static diffuse irradiance that reaches surfaces from outside the camera view.
1027
+
1028
+ ```ts
1029
+ export class ProbeVolume extends Object3D implements IComputeDriven { … }
1030
+ ```
1031
+
1032
+ - **Use when:** light bouncing from a room I cannot see · light a wall with an off-screen emitter
1033
+ - **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
1034
+ - **Overrides:** density, bounds, bakeBudgetMs, and bounces are game-owned choices
1035
+
1036
+ ```ts
1037
+ const probes = new ProbeVolume({ bounds, density: 0.5 }); ctx.add(probes); void probes.requestBake(scene);
1038
+ ```
1039
+
1040
+ ### `readProbeVolumeObservation`
1041
+
1042
+ `function` — Read the most recent observation from a probe volume.
1043
+
1044
+ ```ts
1045
+ export function readProbeVolumeObservation(value: unknown): IProbeVolumeObservation | undefined { … }
1046
+ ```
1047
+
1048
+ - **Use when:** inspect the latest probe bake observation
1049
+ - **Constraints:** the returned observation is a measurement; it does not own lighting or materials
1050
+
1051
+ ```ts
1052
+ const observation = readProbeVolumeObservation(probes);
1053
+ ```
1054
+
1055
+ ### `readRenderChainObservation`
1056
+
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.
1058
+
1059
+ ```ts
1060
+ export function readRenderChainObservation( renderer: unknown, ): IRenderChainMarker["applied"] | undefined { … }
1061
+ ```
1062
+
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
1065
+
1066
+ ```ts
1067
+ const chain = new RenderChain(renderer, { input: colour, stages, request: { stages: ["bloom"], tier: "auto" } });
1068
+ ```
1069
+
1070
+ ### `readRenderChainReport`
1071
+
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.
1073
+
1074
+ ```ts
1075
+ export function readRenderChainReport(renderer: unknown): IRenderChainMarker | undefined { … }
1076
+ ```
1077
+
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
1080
+
1081
+ ```ts
1082
+ const chain = new RenderChain(renderer, { input: colour, stages, request: { stages: ["bloom"], tier: "auto" } });
1083
+ ```
1084
+
1085
+ ### `readVelocityPreviousBoneMatrices`
1086
+
1087
+ `function` — Provision screen-space motion data for temporal nodes and keep per-instance history at the frame boundary.
1088
+
1089
+ ```ts
1090
+ export function readVelocityPreviousBoneMatrices(object: Object3D): Float32Array | undefined { … }
1091
+ ```
1092
+
1093
+ - **Use when:** keep a skinned character or instanced crowd stable in a temporal stage · add the velocity output to a Three.js scene pass · inspect the previous skinned pose at a renderer adapter boundary
1094
+ - **Constraints:** call `VelocityTracker.update()` before the render and `commit()` after it · a pass is only given a velocity target when a temporal stage consumes it
1095
+
1096
+ ```ts
1097
+ const scenePass = pass(scene, camera);
1098
+ ensureVelocityOutput(scenePass);
1099
+ renderer.setOutputNode(scenePass);
1100
+ const tracker = new VelocityTracker();
1101
+ tracker.update(scene);
1102
+ renderer.render(scene, camera);
1103
+ tracker.commit(scene);
1104
+ ```
1105
+
1106
+ ### `readVelocityPreviousMatrices`
1107
+
1108
+ `function` — Provision screen-space motion data for temporal nodes and keep per-instance history at the frame boundary.
1109
+
1110
+ ```ts
1111
+ export function readVelocityPreviousMatrices(object: Object3D): Float32Array | undefined { … }
1112
+ ```
1113
+
1114
+ - **Use when:** keep a skinned character or instanced crowd stable in a temporal stage · add the velocity output to a Three.js scene pass · inspect the previous instance frame at a renderer adapter boundary
1115
+ - **Constraints:** call `VelocityTracker.update()` before the render and `commit()` after it · a pass is only given a velocity target when a temporal stage consumes it
1116
+
1117
+ ```ts
1118
+ const scenePass = pass(scene, camera);
1119
+ ensureVelocityOutput(scenePass);
1120
+ renderer.setOutputNode(scenePass);
1121
+ const tracker = new VelocityTracker();
1122
+ tracker.update(scene);
1123
+ renderer.render(scene, camera);
1124
+ tracker.commit(scene);
1125
+ ```
1126
+
1127
+ ### `readVelocityPreviousWorldMatrix`
1128
+
1129
+ `function` — Provision screen-space motion data for temporal nodes and keep per-instance history at the frame boundary.
1130
+
1131
+ ```ts
1132
+ export function readVelocityPreviousWorldMatrix(object: Object3D): Matrix4 | undefined { … }
1133
+ ```
1134
+
1135
+ - **Use when:** keep a skinned character or instanced crowd stable in a temporal stage · add the velocity output to a Three.js scene pass · inspect the previous rigid transform at a renderer adapter boundary
1136
+ - **Constraints:** call `VelocityTracker.update()` before the render and `commit()` after it · a pass is only given a velocity target when a temporal stage consumes it
1137
+
1138
+ ```ts
1139
+ const scenePass = pass(scene, camera);
1140
+ ensureVelocityOutput(scenePass);
1141
+ renderer.setOutputNode(scenePass);
1142
+ const tracker = new VelocityTracker();
1143
+ tracker.update(scene);
1144
+ renderer.render(scene, camera);
1145
+ tracker.commit(scene);
1146
+ ```
1147
+
1148
+ ### `readVirtualShadowMarker`
1149
+
1150
+ `function` — Parse a `TN_VIRTUAL_SHADOW` console line back into its complete stats, or `undefined`.
1151
+
1152
+ ```ts
1153
+ export function readVirtualShadowMarker(line: string): IVirtualShadowStats | undefined { … }
1154
+ ```
1155
+
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`
1158
+
1159
+ ```ts
1160
+ const stats = readVirtualShadowMarker(line);
1161
+ if (stats !== undefined) console.log(stats.reuseRatio);
1162
+ ```
1163
+
1164
+ ### `reconcileMirroredClips`
1165
+
1166
+ `function` — Repair an exported rig whose animation clips are z-mirrored against its own bind pose.
1167
+
1168
+ ```ts
1169
+ export function reconcileMirroredClips(root: Object3D, clips: readonly AnimationClip[]): boolean { … }
1170
+ ```
1171
+
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
1174
+
1175
+ ```ts
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);
1208
+ ```
1209
+
1210
+ ### `resolveAtmosphereLutResolutions`
1211
+
1212
+ `function` — Resolve the three LUT dimensions, allowing a game to trade startup cost for resolution.
1213
+
1214
+ ```ts
1215
+ export function resolveAtmosphereLutResolutions( resolutions: Partial<IAtmosphereLutResolutions> | undefined, ): IAtmosphereLutResolutions { … }
1216
+ ```
1217
+
1218
+ - **Use when:** choose atmosphere LUT dimensions for a measured startup budget
1219
+ - **Constraints:** every width and height must be a positive integer; the dimensions are not a named fidelity tier
1220
+
1221
+ ```ts
1222
+ const resolutions = resolveAtmosphereLutResolutions({ skyView: { width: 128, height: 72 } });
1223
+ ```
1224
+
1225
+ ### `resolveAtmosphereParameters`
1226
+
1227
+ `function` — Validate and clone game-owned atmosphere coefficients.
1228
+
1229
+ ```ts
1230
+ export function resolveAtmosphereParameters( options: IAtmosphereParameters, ): IResolvedAtmosphereParameters { … }
1231
+ ```
1232
+
1233
+ - **Use when:** validate atmosphere coefficients before a game creates its sky
1234
+ - **Constraints:** provide all three coefficient vectors and both radii; omitted fields are errors
1235
+
1236
+ ```ts
1237
+ const parameters = resolveAtmosphereParameters({ rayleigh, mie, ozone, planetRadius, atmosphereRadius });
1238
+ ```
1239
+
1240
+ ### `Scene`
1241
+
1242
+ `class` — Implement a portable Godot-shaped game scene lifecycle.
1243
+
1244
+ ```ts
1245
+ export abstract class Scene< TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined, > { … }
1246
+ ```
1247
+
1248
+ - **Use when:** add a playable level or menu scene · move scene setup and per-frame gameplay out of the entry point
1249
+ - **Constraints:** scene code must stay portable across web and native
1250
+
1251
+ ```ts
1252
+ class Play extends Scene { update(ctx, dt) {} }
1253
+ ```
1254
+
1255
+ ### `ScenePicker`
1256
+
1257
+ `class` — Raycast the game scene using the framework's picker.
1258
+
1259
+ ```ts
1260
+ export class ScenePicker { … }
1261
+ ```
1262
+
1263
+ - **Use when:** select an object under the pointer · interact with the first collider or mesh hit
1264
+ - **Supersedes (writing this fails `pnpm budgets`):** new Raycaster(
1265
+
1266
+ ```ts
1267
+ const picker = new ScenePicker({ camera: ctx.camera, scene: ctx.scene, pointer: () => ctx.input.raw.pointer, viewport: ctx.viewport });
1268
+ ```
1269
+
1270
+ ### `Scheduler`
1271
+
1272
+ `class` — Schedule delayed and repeating callbacks or tween numeric properties with game-owned cleanup.
1273
+
1274
+ ```ts
1275
+ export class Scheduler { … }
1276
+ ```
1277
+
1278
+ - **Use when:** delay an enemy patrol transition · run a callback every simulation tick · tween a numeric property with a game-owned curve
1279
+ - **Constraints:** dispose returned handles when the owning scene exits · ease receives progress in the range 0 to 1 and its return value is the interpolation factor
1280
+
1281
+ ```ts
1282
+ const door = { y: 0 };
1283
+ await ctx.tween(door, { y: 2.4 }, 0.5, { ease: (t) => 1 - (1 - t) ** 3 });
1284
+ ```
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
+
1308
+ ### `skeletonBones`
1309
+
1310
+ `function` — List the names of every bone in a character hierarchy.
1311
+
1312
+ ```ts
1313
+ export function skeletonBones(root: Object3D): readonly string[] { … }
1314
+ ```
1315
+
1316
+ - **Use when:** inspect the available bones before attaching a game-owned object · debug a missing skeleton bone name
1317
+
1318
+ ```ts
1319
+ import { skeletonBones } from "@threenative/core";
1320
+ const bones = skeletonBones(character);
1321
+ ```
1322
+
1323
+ ### `SoftBody3D`
1324
+
1325
+ `class` — Simulate an ordinary game-authored triangle mesh as cloth on the existing fixed-step GPU lane. The mesh supplies every visible choice. This class welds exporter duplicates, owns spring and position buffers, and replaces only the cloned material's position node. It adds no material, colour, texture, wind, stiffness, damping, or pinning default.
1326
+
1327
+ ```ts
1328
+ export class SoftBody3D extends Mesh<BufferGeometry, NodeMaterial> implements IComputeDriven { … }
1329
+ ```
1330
+
1331
+ - **Use when:** make a flag, cape, or curtain move as cloth · simulate a deforming surface while keeping one edge pinned · simulate cloth sails blowing in the wind · make cloth sails billow in wind on a ship
1332
+ - **Constraints:** the mesh must use one Three.js node material and contain complete triangles · pinned, stiffness, damping, gravity, and wind are required game-owned inputs · Pixel 8 steady upper bound for the shipped 45-vertex pennant with readback every two frames: whole-starter update p95 4.66 ms, render p95 3.56 ms, and GPU timer 0.05 ms across three 300-frame final-rung windows at 552x248 with 4x MSAA; these whole-scene numbers are not isolated solver cost
1333
+ - **Overrides:** timeStep follows the engine 1/60-second convention unless the game overrides it · readbackEveryFrames enables an explicitly stale CPU position sample; zero disables it
1334
+
1335
+ ```ts
1336
+ const flag = new SoftBody3D(flagMesh, { pinned: topEdge, stiffness: 35, damping: 1.8, gravity: [0, -9.81, 0], wind: [1.5, 0, 0.4] });
1337
+ ```
1338
+
1339
+ ### `softCircleDataTexture`
1340
+
1341
+ `function` — Build a soft round sprite as pixel data instead of painting a canvas.
1342
+
1343
+ ```ts
1344
+ export function softCircleDataTexture(size = 64, hardness = 0.25): DataTexture { … }
1345
+ ```
1346
+
1347
+ - **Use when:** give smoke, flash, or glow sprites a radial alpha falloff · generate sprite images that render identically under every backend
1348
+ - **Constraints:** canvas-painted images sample black under WebGPURenderer; write sprites as pixel data there
1349
+
1350
+ ```ts
1351
+ const puff = softCircleDataTexture(64, 0.25);
1352
+ ```
1353
+
1354
+ ### `solarPosition`
1355
+
1356
+ `function` — Calculate solar elevation and azimuth from time, latitude, and longitude.
1357
+
1358
+ ```ts
1359
+ export function solarPosition(input: ISolarPositionInput, target?: ISolarPosition): ISolarPosition;
1360
+ ```
1361
+
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
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
1364
+
1365
+ ```ts
1366
+ const sun = solarPosition({ date, latitude: 49.28, longitude: -123.12, utcOffset: -8 });
1367
+ ```
1368
+
1369
+ ### `solarPositionAt`
1370
+
1371
+ `function` — Calculate solar elevation and azimuth for one UTC date.
1372
+
1373
+ ```ts
1374
+ export function solarPositionAt( date: Date | string, latitude: number, longitude: number, ): ISolarPosition { … }
1375
+ ```
1376
+
1377
+ - **Use when:** calculate a sun direction from a timestamp and a game location
1378
+ - **Constraints:** dates are interpreted as UTC; use solarPosition for an explicit local offset
1379
+
1380
+ ```ts
1381
+ const sun = solarPositionAt(new Date(), 49.28, -123.12);
1382
+ ```
1383
+
1384
+ ### `SpectralOcean`
1385
+
1386
+ `class` — Simulate a spectral ocean — cascaded wave spectra inverse-transformed on the GPU each frame.
1387
+
1388
+ ```ts
1389
+ export class SpectralOcean extends Object3D implements IComputeDriven { … }
1390
+ ```
1391
+
1392
+ - **Use when:** make an ocean whose surface is the view rather than a background · float a boat on waves the GPU is drawing · drive a water material from a wave simulation without writing an FFT · sail a ship on simulated ocean waves with buoyancy
1393
+ - **Constraints:** it draws nothing; the game supplies the mesh, the material and every colour · CPU height is a throttled copy carrying staleFrames, never this frame and never exact · an exact free CPU height needs an analytic wave field instead; that is a different contract · cascades are ordered largest patchSize first and every tuning number is required
1394
+
1395
+ ```ts
1396
+ const sea = ctx.add(new SpectralOcean(oceanOptions));
1397
+ ```
1398
+
1399
+ ### `SpriteAnimator3D`
1400
+
1401
+ `class` — Advance a game-owned non-uniform sprite atlas on the fixed step.
1402
+
1403
+ ```ts
1404
+ export class SpriteAnimator3D { … }
1405
+ ```
1406
+
1407
+ - **Use when:** play an animated pickup or sprite-sheet effect · sequence atlas frames with different authored durations
1408
+ - **Constraints:** the game supplies the atlas texture, surface, filtering, layout, and every frame duration · update is driven by the scene fixed step; no wall clock or default frame rate is used
1409
+
1410
+ ```ts
1411
+ const animator = new SpriteAnimator3D({ texture: atlas, frames, mode: "pingPong" });
1412
+ ```
1413
+
1414
+ ### `TracerPool3D`
1415
+
1416
+ `class` — Pool travelling bullet-streak meshes for hitscan shots.
1417
+
1418
+ ```ts
1419
+ export class TracerPool3D { … }
1420
+ ```
1421
+
1422
+ - **Use when:** show where a hitscan round went · draw incoming fire without spawning projectiles
1423
+ - **Constraints:** the surface comes from the game; pooling, travel, and fading belong to the engine · update once per frame and dispose with the owning scene
1424
+
1425
+ ```ts
1426
+ const tracers = new TracerPool3D(ctx.scene, tracerOptions);
1427
+ tracers.spawn(muzzle, shotDirection, hit.distance);
1428
+ ```
1429
+
1430
+ ### `updateAtmosphereParameters`
1431
+
1432
+ `function` — Apply a partial game-owned atmosphere change while preserving validation.
1433
+
1434
+ ```ts
1435
+ export function updateAtmosphereParameters( current: IResolvedAtmosphereParameters, patch: IAtmosphereParameterPatch, ): IResolvedAtmosphereParameters { … }
1436
+ ```
1437
+
1438
+ - **Use when:** change scattering coefficients and rebake an atmosphere
1439
+ - **Constraints:** patches cannot introduce omitted, negative, or non-finite physical values
1440
+
1441
+ ```ts
1442
+ atmosphere.setAtmosphere({ rayleigh: [0.008, 0.016, 0.04] });
1443
+ ```
1444
+
1445
+ ### `updateClusteredMeshes`
1446
+
1447
+ `function` — Take every clustered mesh under a root through this frame's cut, before the render. The engine already does this for the scene it renders; reach for it only to cut a subtree the engine does not render, such as one staged for a camera of your own.
1448
+
1449
+ ```ts
1450
+ export function updateClusteredMeshes( root: { … }
1451
+ ```
1452
+
1453
+ - **Use when:** cut a virtual-geometry subtree the engine does not render itself
1454
+
1455
+ ```ts
1456
+ updateClusteredMeshes(stagedRoot, myCamera, ctx.renderer.domElement.height);
1457
+ ```
1458
+
1459
+ ### `velocityTexture`
1460
+
1461
+ `function` — Provision screen-space motion data for temporal nodes and keep per-instance history at the frame boundary.
1462
+
1463
+ ```ts
1464
+ export function velocityTexture(pass: IVelocityRenderPass): Node { … }
1465
+ ```
1466
+
1467
+ - **Use when:** keep a skinned character or instanced crowd stable in a temporal stage · add the velocity output to a Three.js scene pass · read screen-space motion for a temporal stage
1468
+ - **Constraints:** call `VelocityTracker.update()` before the render and `commit()` after it · a pass is only given a velocity target when a temporal stage consumes it
1469
+
1470
+ ```ts
1471
+ const scenePass = pass(scene, camera);
1472
+ ensureVelocityOutput(scenePass);
1473
+ renderer.setOutputNode(scenePass);
1474
+ const tracker = new VelocityTracker();
1475
+ tracker.update(scene);
1476
+ renderer.render(scene, camera);
1477
+ tracker.commit(scene);
1478
+ ```
1479
+
1480
+ ### `VelocityTracker`
1481
+
1482
+ `class` — Provision screen-space motion data for temporal nodes and keep per-instance history at the frame boundary.
1483
+
1484
+ ```ts
1485
+ export class VelocityTracker { … }
1486
+ ```
1487
+
1488
+ - **Use when:** keep a skinned character or instanced crowd stable in a temporal stage · add the velocity output to a Three.js scene pass · retain previous transforms for animated and instanced renderables
1489
+ - **Constraints:** call `VelocityTracker.update()` before the render and `commit()` after it · a pass is only given a velocity target when a temporal stage consumes it · call `update()` after gameplay writes and `commit()` after the render
1490
+
1491
+ ```ts
1492
+ const scenePass = pass(scene, camera);
1493
+ ensureVelocityOutput(scenePass);
1494
+ renderer.setOutputNode(scenePass);
1495
+ const tracker = new VelocityTracker();
1496
+ tracker.update(scene);
1497
+ renderer.render(scene, camera);
1498
+ tracker.commit(scene);
1499
+ ```
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
+
1519
+ ### `warmUpScene`
1520
+
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.
1522
+
1523
+ ```ts
1524
+ export async function warmUpScene( renderer: IWarmUpRenderer, scene: Object3D, camera: Camera, options: IWarmUpOptions = { … }
1525
+ ```
1526
+
1527
+ - **Use when:** compile a scene's shaders during the loading screen instead of on the first frame · stop a native launch freezing for seconds inside its first rendered frame
1528
+
1529
+ ```ts
1530
+ await warmUpScene(renderer, scene, camera, { onProgress: (p) => setLoading(p) });
1531
+ ```
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
+
1549
+ ### `WaveField`
1550
+
1551
+ `class` — Evaluate analytic waves on CPU and displace game-owned vertices with the matching TSL graph.
1552
+
1553
+ ```ts
1554
+ export class WaveField { … }
1555
+ ```
1556
+
1557
+ - **Use when:** float a boat on waves · make water move · find the water surface height at a point
1558
+ - **Constraints:** supply every wave amplitude, wavelength, direction, speed and warp value · call setTime for the default graph clock when the game advances its own time
1559
+
1560
+ ```ts
1561
+ const field = new WaveField({ waves });
1562
+ const { height, normal } = field.sample(x, z, elapsed);
1563
+ ```
1564
+
1565
+ ### `withVelocityContext`
1566
+
1567
+ `function` — Provision screen-space motion data for temporal nodes and keep per-instance history at the frame boundary.
1568
+
1569
+ ```ts
1570
+ export function withVelocityContext<T>(node: T, source: Node): T { … }
1571
+ ```
1572
+
1573
+ - **Use when:** keep a skinned character or instanced crowd stable in a temporal stage · add the velocity output to a Three.js scene pass · hand the provisioned velocity source through a composed temporal graph
1574
+ - **Constraints:** call `VelocityTracker.update()` before the render and `commit()` after it · a pass is only given a velocity target when a temporal stage consumes it
1575
+
1576
+ ```ts
1577
+ const scenePass = pass(scene, camera);
1578
+ ensureVelocityOutput(scenePass);
1579
+ renderer.setOutputNode(scenePass);
1580
+ const tracker = new VelocityTracker();
1581
+ tracker.update(scene);
1582
+ renderer.render(scene, camera);
1583
+ tracker.commit(scene);
1584
+ ```
1585
+
1586
+ ### `zenithTransmittance`
1587
+
1588
+ `function` — Return direct vertical transmittance for the supplied atmosphere.
1589
+
1590
+ ```ts
1591
+ export function zenithTransmittance( parameters: IAtmosphereParameters | IResolvedAtmosphereParameters, ): AtmosphereRgb { … }
1592
+ ```
1593
+
1594
+ - **Use when:** check a supplied atmosphere's direct vertical transmittance
1595
+ - **Constraints:** use the returned value as a validation oracle; the rendered path samples the LUT
1596
+
1597
+ ```ts
1598
+ const zenith = zenithTransmittance({ rayleigh, mie, ozone, planetRadius, atmosphereRadius });
1599
+ ```
1600
+
1601
+ ## `@threenative/core/hot`
1602
+
1603
+ ### `acceptHotUpdate`
1604
+
1605
+ `function` — Register hot-reload state preservation for a game.
1606
+
1607
+ ```ts
1608
+ export function acceptHotUpdate<TState extends Record<string, unknown>, TPhysics>( game: IGame<TState, TPhysics>, hot: IImportMeta["hot"], ): void { … }
1609
+ ```
1610
+
1611
+ - **Use when:** keep game state while editing source in development · diagnose state shape changes during hot reload
1612
+ - **Constraints:** use only in the web development entry
1613
+
1614
+ ```ts
1615
+ acceptHotUpdate(game, import.meta.hot);
1616
+ ```
1617
+
1618
+ ### `assertPortableState`
1619
+
1620
+ `function` — Validate that hot-reload state can cross the Vite boundary.
1621
+
1622
+ ```ts
1623
+ export function assertPortableState(state: unknown): void { … }
1624
+ ```
1625
+
1626
+ - **Use when:** preserve JSON-shaped state during hot reload · reject a non-portable game state before reload
1627
+ - **Constraints:** state must contain finite numbers and plain objects only
1628
+
1629
+ ```ts
1630
+ assertPortableState(game.state.getState());
1631
+ ```
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
+
1651
+ ## `@threenative/core/playtest`
1652
+
1653
+ ### `playtest`
1654
+
1655
+ `function` — Install the playtest bridge into a portable game.
1656
+
1657
+ ```ts
1658
+ export function playtest< TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined, >(options: IPlaytestOptions = { … }
1659
+ ```
1660
+
1661
+ - **Use when:** expose movement and world observations to a playtest · connect a game to the ThreeNative scenario runner
1662
+ - **Constraints:** install once in the game's plugin list
1663
+
1664
+ ```ts
1665
+ const game = defineGame({ plugins: [playtest()] });
1666
+ ```
1667
+
1668
+ ## `@threenative/core/react`
1669
+
1670
+ ### `createReactOverlay`
1671
+
1672
+ `function` — `@threenative/core/react` — React that renders on a phone, with no DOM and no WebView. A subpath on purpose. `react` and `react-reconciler` are **optional** peers, and nothing in `@threenative/core`'s main entry imports either of them, so a game that never mounts a React overlay pays nothing and core stays consumable from React Three Fiber. Importing this module is the opt-in. The element vocabulary is two components, borrowed from React Native rather than invented: {@link View} is a rectangle, {@link Text} is a run of glyphs. They are components and not lowercase intrinsics because `view` and `text` are already SVG tags in `@types/react`, and a HUD element that silently means `<svg:text>` on one platform is exactly the kind of quiet divergence this path exists to end.
1673
+
1674
+ ```ts
1675
+ export function createReactOverlay(options: IReactOverlayOptions): IReactOverlay { … }
1676
+ ```
1677
+
1678
+ - **Use when:** render a React HUD on Android or iOS without a WebView · show the same React component on web and on a phone · show a React HUD on Android, iOS or desktop native · render the same React component on web and on a phone without a WebView
1679
+ - **Constraints:** styling is the `style` prop; Tailwind class names are CSS and cannot cross · import `react`, never `react-dom`, from the portable native entry · import `react`, never `react-dom`, from a native entry
1680
+
1681
+ ```ts
1682
+ const overlay = createReactOverlay({ canvasLayer: ctx.canvasLayer });
1683
+ ```
1684
+
1685
+ ### `measureText`
1686
+
1687
+ `function` — Width in pixels of a glyph run at a given cell height.
1688
+
1689
+ ```ts
1690
+ export function measureText(text: string, fontSize: number, letterSpacing = 0): number { … }
1691
+ ```
1692
+
1693
+ - **Use when:** measure native React HUD text before laying it out
1694
+
1695
+ ```ts
1696
+ const scoreWidth = measureText("SCORE 10", 24)
1697
+ ```
1698
+
1699
+ ### `supportedGlyphs`
1700
+
1701
+ `function` — Every character this glyph set can draw, for error messages and for the templates' AGENTS.md.
1702
+
1703
+ ```ts
1704
+ export function supportedGlyphs(): string { … }
1705
+ ```
1706
+
1707
+ - **Use when:** discover which characters a native React HUD can draw
1708
+
1709
+ ```ts
1710
+ supportedGlyphs().includes("A")
1711
+ ```
1712
+
1713
+ ### `supportedStyleKeys`
1714
+
1715
+ `function` — Every style key the overlay implements, for the templates' AGENTS.md and for error messages.
1716
+
1717
+ ```ts
1718
+ export function supportedStyleKeys(): readonly string[] { … }
1719
+ ```
1720
+
1721
+ - **Use when:** discover which React HUD style properties work on native
1722
+
1723
+ ```ts
1724
+ supportedStyleKeys().includes("centerX")
1725
+ ```
1726
+
1727
+ ### `Text`
1728
+
1729
+ `function` — A run of bitmap glyphs, drawn as one instanced quad per lit pixel.
1730
+
1731
+ ```ts
1732
+ export function Text(props: ITextProps): ReactNode { … }
1733
+ ```
1734
+
1735
+ - **Use when:** show text in a native React HUD without a DOM
1736
+
1737
+ ```ts
1738
+ <Text style={{ color: "#ffffff", fontSize: 24 }}>SCORE 10</Text>
1739
+ ```
1740
+
1741
+ ### `View`
1742
+
1743
+ `function` — A rectangle. Paints when its style has a `background`; otherwise it only positions children.
1744
+
1745
+ ```ts
1746
+ export function View(props: IViewProps): ReactNode { … }
1747
+ ```
1748
+
1749
+ - **Use when:** group and position native React HUD elements
1750
+
1751
+ ```ts
1752
+ <View style={{ centerX: true, top: 24 }}><Text>READY</Text></View>
1753
+ ```
1754
+
1755
+ ## `@threenative/core/ui-layer`
1756
+
1757
+ ### `connectUiBridge`
1758
+
1759
+ `function` — Open the message channel between a game and its UI, whatever host is underneath.
1760
+
1761
+ ```ts
1762
+ export function connectUiBridge(options: IConnectOptions): IUiBridge { … }
1763
+ ```
1764
+
1765
+ - **Use when:** write a UI that talks to the game on web and on a phone alike · send a message from a HUD rendered over the game surface · connect game code to a platform-owned UI realm · share one UI bridge implementation across web, Android, iOS, and desktop
1766
+ - **Constraints:** the transport is discovered, never configured; no game names the web view
1767
+
1768
+ ```ts
1769
+ const bridge = connectUiBridge({ end: "ui" });
1770
+ ```
1771
+
1772
+ ### `onUiIntent`
1773
+
1774
+ `function` — Handle the actions a UI sends back to the game.
1775
+
1776
+ ```ts
1777
+ export function onUiIntent( bridge: IUiBridge, listener: (intent: string, payload: unknown) => void, ): () => void { … }
1778
+ ```
1779
+
1780
+ - **Use when:** restart or pause a game from a button in its HUD · handle a HUD button action in game code · route native and web UI commands through one listener
1781
+ - **Constraints:** prefer game.ui.onIntent, which connects the bridge for you
1782
+
1783
+ ```ts
1784
+ onUiIntent(bridge, (intent) => { if (intent === "restart") game.goto("Play"); });
1785
+ ```
1786
+
1787
+ ### `publishHitRegions`
1788
+
1789
+ `function` — Tell the native input host where a UI's touchable controls are.
1790
+
1791
+ ```ts
1792
+ export function publishHitRegions(options: IRegistryOptions): IHitRegionRegistry { … }
1793
+ ```
1794
+
1795
+ - **Use when:** let a touch on empty HUD space reach the game instead of the UI · make a HUD button receive taps on a phone · give native input hosts the rectangles claimed by UI controls · keep touch hit testing aligned with a moving web or native HUD
1796
+ - **Constraints:** mark controls with data-tn-interactive; pointer-events is not the mechanism
1797
+
1798
+ ```ts
1799
+ publishHitRegions({ bridge });
1800
+ ```
1801
+
1802
+ ### `publishUiState`
1803
+
1804
+ `function` — Publish the game's state so a UI in another process can mirror it.
1805
+
1806
+ ```ts
1807
+ export function publishUiState<T>( bridge: IUiBridge, store: IPublishableStore<T>, options: IPublishOptions = { … }
1808
+ ```
1809
+
1810
+ - **Use when:** show score or health in a UI rendered over the game surface · keep a HUD in step with the game without re-rendering on the loop · publish game state to a HUD in another realm · keep a web and native UI mirror on the same throttled state stream
1811
+ - **Constraints:** publishes at the store's throttled cadence, and not at all with no UI listening
1812
+
1813
+ ```ts
1814
+ publishUiState(bridge, game.state);
1815
+ ```
1816
+
1817
+ ### `sendUiIntent`
1818
+
1819
+ `function` — Send a player action from the UI back to the game.
1820
+
1821
+ ```ts
1822
+ export function sendUiIntent(bridge: IUiBridge, intent: string, payload?: unknown): void { … }
1823
+ ```
1824
+
1825
+ - **Use when:** wire a Restart button in a HUD to the running game · pause a game from a menu drawn over its surface · send a button or menu action from a UI HUD to game code · keep UI input portable across web and native hosts
1826
+ - **Constraints:** one-way; the game decides what each name means and may ignore one
1827
+
1828
+ ```ts
1829
+ sendUiIntent(bridge, "restart");
1830
+ ```
1831
+
1832
+ ### `subscribeUiState`
1833
+
1834
+ `function` — Mirror the game's published state on the UI side.
1835
+
1836
+ ```ts
1837
+ export function subscribeUiState<T>(bridge: IUiBridge): IUiStateMirror<T> { … }
1838
+ ```
1839
+
1840
+ - **Use when:** read game state from a HUD that runs in the platform's web view · read published game state from a UI HUD · subscribe a web or native UI to the game's mirrored state
1841
+ - **Constraints:** returns undefined until the game publishes its first state
1842
+
1843
+ ```ts
1844
+ const mirror = subscribeUiState(bridge);
1845
+ ```
1846
+
1847
+ ## `@threenative/core/world`
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
+
1865
+ ### `Heightfield`
1866
+
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.
1868
+
1869
+ ```ts
1870
+ export class Heightfield extends Group implements IComputeDriven { … }
1871
+ ```
1872
+
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
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
1875
+ - **Overrides:** rows, columns, width, depth, origin, and sampleHeight are explicit on every field
1876
+
1877
+ ```ts
1878
+ const field = Heightfield.fromSampler({ rows: 65, columns: 65, width: 64, depth: 64, origin: { x: 0, z: 0 }, sampleHeight: terrainHeight });
1879
+ ```
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
+
1897
+ ## `@threenative/physics`
1898
+
1899
+ ### `Area3D`
1900
+
1901
+ `class` — Detect overlaps without turning the body into a moving collider.
1902
+
1903
+ ```ts
1904
+ export class Area3D { … }
1905
+ ```
1906
+
1907
+ - **Use when:** detect when an enemy enters a trigger area · react to a player entering a zone
1908
+ - **Constraints:** add the area to the physics context before stepping the world
1909
+
1910
+ ```ts
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") });
1927
+ ```
1928
+
1929
+ ### `Buoyancy3D`
1930
+
1931
+ `class` — Float a rigid body on a game-owned height source with fixed-step force ordering.
1932
+
1933
+ ```ts
1934
+ export class Buoyancy3D { … }
1935
+ ```
1936
+
1937
+ - **Use when:** float a boat on waves · keep a hull above a moving water surface
1938
+ - **Constraints:** supply hull points, density, drag, and the height source
1939
+ - **Overrides:** buoyancy disables force application while submergedFraction remains measured
1940
+
1941
+ ```ts
1942
+ new Buoyancy3D({ body, surface: field, hullPoints, density: 1_000, drag: 4 });
1943
+ ```
1944
+
1945
+ ### `CharacterBody3D`
1946
+
1947
+ `class` — Move a character body with collision-aware sliding.
1948
+
1949
+ ```ts
1950
+ export class CharacterBody3D { … }
1951
+ ```
1952
+
1953
+ - **Use when:** move an enemy or player through a level · keep a character from walking through walls
1954
+ - **Constraints:** use moveAndSlide inside the physics update
1955
+
1956
+ ```ts
1957
+ const body = new CharacterBody3D({ object: hero, physics: ctx.physics, shape: CollisionShape3D.capsule(0.5, 0.35) });
1958
+ ```
1959
+
1960
+ ### `CollisionShape3D`
1961
+
1962
+ `class` — Give a physics body a Three.js collision shape.
1963
+
1964
+ ```ts
1965
+ export class CollisionShape3D { … }
1966
+ ```
1967
+
1968
+ - **Use when:** add a capsule or box collider to a character · configure the shape used by a rigid body
1969
+ - **Constraints:** create shapes through the owning physics context
1970
+
1971
+ ```ts
1972
+ const shape = CollisionShape3D.capsule(0.5, 0.35);
1973
+ ```
1974
+
1975
+ ### `interactionGroups`
1976
+
1977
+ `function` — Encode collision layers and masks for Rapier groups.
1978
+
1979
+ ```ts
1980
+ export function interactionGroups(layer: number, mask: number): number { … }
1981
+ ```
1982
+
1983
+ - **Use when:** make an enemy collide with the world but not pickups · configure which physics layers interact
1984
+
1985
+ ```ts
1986
+ const groups = interactionGroups(1, 3);
1987
+ ```
1988
+
1989
+ ### `Joint3D`
1990
+
1991
+ `class` — Connect two physics bodies with a Godot-style joint.
1992
+
1993
+ ```ts
1994
+ export class Joint3D { … }
1995
+ ```
1996
+
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
1998
+ - **Constraints:** both bodies must belong to the same physics context
1999
+
2000
+ ```ts
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 } });
2002
+ ```
2003
+
2004
+ ### `PhysicsDirectSpaceState3D`
2005
+
2006
+ `class` — Query the physics world without creating a body.
2007
+
2008
+ ```ts
2009
+ export class PhysicsDirectSpaceState3D { … }
2010
+ ```
2011
+
2012
+ - **Use when:** raycast for visibility or aiming · find bodies inside a shape or point query
2013
+ - **Constraints:** query results are bounded by the configured result limit
2014
+
2015
+ ```ts
2016
+ const space = new PhysicsDirectSpaceState3D(context);
2017
+ ```
2018
+
2019
+ ### `rapier`
2020
+
2021
+ `function` — Install the Rapier physics plugin and simulation backend.
2022
+
2023
+ ```ts
2024
+ export function rapier(options: IPhysicsOptions = { … }
2025
+ ```
2026
+
2027
+ - **Use when:** add physics to a portable game · provide the context used by character and rigid bodies
2028
+ - **Constraints:** place rapier() before recast() in the plugin list
2029
+
2030
+ ```ts
2031
+ const game = defineGame({ plugins: [rapier()] });
2032
+ ```
2033
+
2034
+ ### `RigidBody3D`
2035
+
2036
+ `class` — Simulate a dynamic or static rigid body.
2037
+
2038
+ ```ts
2039
+ export class RigidBody3D { … }
2040
+ ```
2041
+
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
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
2045
+
2046
+ ```ts
2047
+ const crate = new RigidBody3D({ object, physics: ctx.physics, shape: CollisionShape3D.box(1, 1, 1), mass: 8 });
2048
+ ```
2049
+
2050
+ ### `softBodyCollision`
2051
+
2052
+ `function` — Feed existing rigid-body boxes into `SoftBody3D` without inventing a second collider API.
2053
+
2054
+ ```ts
2055
+ export function softBodyCollision(...bodies: readonly RigidBody3D[]): ISoftBodyCollision { … }
2056
+ ```
2057
+
2058
+ - **Use when:** stop a cloth flag, cape, or curtain at an existing physics wall · collide SoftBody3D with fixed box bodies
2059
+ - **Constraints:** every body must use CollisionShape3D.box and retain its Three.js object transform · rotated boxes become conservative cloth-local axis-aligned bounds
2060
+
2061
+ ```ts
2062
+ const cloth = new SoftBody3D(mesh, { ...options, collision: softBodyCollision(wall) });
2063
+ ```
2064
+
2065
+ ## `@threenative/physics/navigation`
2066
+
2067
+ ### `NavigationAgent3D`
2068
+
2069
+ `class` — Move an agent along a baked navmesh toward a target.
2070
+
2071
+ ```ts
2072
+ export class NavigationAgent3D { … }
2073
+ ```
2074
+
2075
+ - **Use when:** enemy walks around a wall · enemy patrols a level and chases the player · enemy walks around a patrol path and chases the player when it sees them · enemy patrols and chases while avoiding obstacles · enemy chases the player with line of sight and obstacle avoidance · NPC walks to a destination · move crew around a ship deck
2076
+ - **Constraints:** import NavigationAgent3D from exactly `@threenative/physics/navigation`; `@threenative/physics` is not a valid import for this symbol; use this capability instead of hand-written A*; requires recast() after rapier(), plus a baked NavigationRegion3D
2077
+
2078
+ ```ts
2079
+ import { NavigationAgent3D } from "@threenative/physics/navigation";
2080
+ import { Vector3 } from "three";
2081
+ const agent = new NavigationAgent3D({ navigation, object });
2082
+ agent.setTargetPosition(player.position);
2083
+ const reusableTarget = new Vector3();
2084
+ const next = agent.getNextPathPosition(reusableTarget);
2085
+ ```
2086
+
2087
+ ### `NavigationObstacle3D`
2088
+
2089
+ `class` — Add a non-moving crowd obstacle to a navmesh.
2090
+
2091
+ ```ts
2092
+ export class NavigationObstacle3D { … }
2093
+ ```
2094
+
2095
+ - **Use when:** keep navigation agents away from a blocking prop · make a stationary character affect crowd avoidance
2096
+ - **Constraints:** create it after recast() and dispose it with the scene
2097
+
2098
+ ```ts
2099
+ const obstacle = new NavigationObstacle3D({ navigation, object });
2100
+ ```
2101
+
2102
+ ### `NavigationRegion3D`
2103
+
2104
+ `class` — Bake walkable Three.js geometry into a navigation region.
2105
+
2106
+ ```ts
2107
+ export class NavigationRegion3D { … }
2108
+ ```
2109
+
2110
+ - **Use when:** let enemies walk around level geometry · create the baked navmesh required by NavigationAgent3D
2111
+ - **Constraints:** bake before creating agents or obstacles
2112
+
2113
+ ```ts
2114
+ const region = new NavigationRegion3D({ navigation, meshes: [floor] });
2115
+ ```
2116
+
2117
+ ### `recast`
2118
+
2119
+ `function` — Install navmesh pathfinding and crowd avoidance.
2120
+
2121
+ ```ts
2122
+ export function recast(): NavigationPlugin { … }
2123
+ ```
2124
+
2125
+ - **Use when:** enemy walks around a wall · NPC patrols a level and chases a player
2126
+ - **Constraints:** requires rapier() earlier in the plugins array
2127
+
2128
+ ```ts
2129
+ const game = defineGame({ plugins: [rapier(), recast()] });
2130
+ ```
2131
+
2132
+ ## `@threenative/playtest`
2133
+
2134
+ ### `assertJsonSafe`
2135
+
2136
+ `function` — Validate JSON-safe bridge messages and protocol sizes.
2137
+
2138
+ ```ts
2139
+ export function assertJsonSafe(value: unknown, path = "$"): asserts value is JsonValue { … }
2140
+ ```
2141
+
2142
+ - **Use when:** send a safe observation over the playtest bridge · reject an oversized or cyclic playtest payload · validate entity components and gameplay observations before crossing the bridge
2143
+ - **Constraints:** bridge values must be JSON-shaped · throws instead of silently dropping the offending field
2144
+
2145
+ ```ts
2146
+ assertJsonSafe({ score: 10 });
2147
+ ```
2148
+
2149
+ ### `DeviceMetricsError`
2150
+
2151
+ `class` — Measure and judge device thermal, power and battery state around a device playtest run.
2152
+
2153
+ ```ts
2154
+ export class DeviceMetricsError extends Error { … }
2155
+ ```
2156
+
2157
+ - **Use when:** find out whether an Android run was throttled or started hot · read battery temperature, current draw or per-rail power for a run
2158
+ - **Constraints:** a reading the device does not expose reports unavailable, never zero · a run that started hot or whose thermal status rose is flagged as confounded
2159
+
2160
+ ```ts
2161
+ const verdict = summarizeDeviceMetrics(observation.samples);
2162
+ ```
2163
+
2164
+ ### `DeviceMetricsRecorder`
2165
+
2166
+ `class` — Measure and judge device thermal, power and battery state around a device playtest run.
2167
+
2168
+ ```ts
2169
+ export class DeviceMetricsRecorder { … }
2170
+ ```
2171
+
2172
+ - **Use when:** find out whether an Android run was throttled or started hot · read battery temperature, current draw or per-rail power for a run
2173
+ - **Constraints:** a reading the device does not expose reports unavailable, never zero · a run that started hot or whose thermal status rose is flagged as confounded
2174
+
2175
+ ```ts
2176
+ const verdict = summarizeDeviceMetrics(observation.samples);
2177
+ ```
2178
+
2179
+ ### `evaluateRichPlaytestAssertions`
2180
+
2181
+ `function` — Evaluate rich semantic assertions against captured observations.
2182
+
2183
+ ```ts
2184
+ export function evaluateRichPlaytestAssertions(input: { … }
2185
+ ```
2186
+
2187
+ - **Use when:** assert movement, visibility, or diagnostics in a playtest · turn a scenario observation into a pass or failure
2188
+ - **Constraints:** malformed or empty assertions fail closed
2189
+
2190
+ ```ts
2191
+ const result = evaluateRichPlaytestAssertions(input);
2192
+ ```
2193
+
2194
+ ### `invalidScenario`
2195
+
2196
+ `function` — Load and validate a scenario, then control its tick steps.
2197
+
2198
+ ```ts
2199
+ export function invalidScenario(scenarioPath: string, message: string): PlaytestScenarioError { … }
2200
+ ```
2201
+
2202
+ - **Use when:** create a browser or device playtest scenario · wait or hold a game for a deterministic number of ticks
2203
+ - **Constraints:** unknown scenario keys fail closed
2204
+
2205
+ ```ts
2206
+ const scenario = await loadPlaytestScenario(project, file);
2207
+ ```
2208
+
2209
+ ### `jsonByteLength`
2210
+
2211
+ `function` — Validate JSON-safe bridge messages and protocol sizes.
2212
+
2213
+ ```ts
2214
+ export function jsonByteLength(value: JsonValue): number { … }
2215
+ ```
2216
+
2217
+ - **Use when:** send a safe observation over the playtest bridge · reject an oversized or cyclic playtest payload · check a runtime observation against the protocol payload limit before sampling
2218
+ - **Constraints:** bridge values must be JSON-shaped
2219
+
2220
+ ```ts
2221
+ assertJsonSafe({ score: 10 });
2222
+ ```
2223
+
2224
+ ### `loadPlaytestScenario`
2225
+
2226
+ `function` — Load and validate a scenario, then control its tick steps.
2227
+
2228
+ ```ts
2229
+ export async function loadPlaytestScenario(projectPath: string, scenarioPath: string): Promise<IPlaytestScenario> { … }
2230
+ ```
2231
+
2232
+ - **Use when:** create a browser or device playtest scenario · wait or hold a game for a deterministic number of ticks
2233
+ - **Constraints:** unknown scenario keys fail closed
2234
+
2235
+ ```ts
2236
+ const scenario = await loadPlaytestScenario(project, file);
2237
+ ```
2238
+
2239
+ ### `missingPlaytestCapabilities`
2240
+
2241
+ `function` — Validate and inspect playtest capability declarations.
2242
+
2243
+ ```ts
2244
+ export function missingPlaytestCapabilities(required: readonly string[], available: readonly string[]): string[] { … }
2245
+ ```
2246
+
2247
+ - **Use when:** check whether a scenario's required capabilities are installed · report unknown or missing playtest capabilities
2248
+
2249
+ ```ts
2250
+ const missing = missingPlaytestCapabilities(required, available);
2251
+ ```
2252
+
2253
+ ### `parseDeviceBattery`
2254
+
2255
+ `function` — Measure and judge device thermal, power and battery state around a device playtest run.
2256
+
2257
+ ```ts
2258
+ export function parseDeviceBattery(output: string): IPlaytestDeviceBattery { … }
2259
+ ```
2260
+
2261
+ - **Use when:** find out whether an Android run was throttled or started hot · read battery temperature, current draw or per-rail power for a run
2262
+ - **Constraints:** a reading the device does not expose reports unavailable, never zero · a run that started hot or whose thermal status rose is flagged as confounded
2263
+
2264
+ ```ts
2265
+ const verdict = summarizeDeviceMetrics(observation.samples);
2266
+ ```
2267
+
2268
+ ### `parseDeviceCurrent`
2269
+
2270
+ `function` — Measure and judge device thermal, power and battery state around a device playtest run.
2271
+
2272
+ ```ts
2273
+ export function parseDeviceCurrent(output: string): PlaytestDeviceMeasurement<number> { … }
2274
+ ```
2275
+
2276
+ - **Use when:** find out whether an Android run was throttled or started hot · read battery temperature, current draw or per-rail power for a run
2277
+ - **Constraints:** a reading the device does not expose reports unavailable, never zero · a run that started hot or whose thermal status rose is flagged as confounded
2278
+
2279
+ ```ts
2280
+ const verdict = summarizeDeviceMetrics(observation.samples);
2281
+ ```
2282
+
2283
+ ### `parseDevicePowerRails`
2284
+
2285
+ `function` — Measure and judge device thermal, power and battery state around a device playtest run.
2286
+
2287
+ ```ts
2288
+ export function parseDevicePowerRails(output: string): PlaytestDevicePowerRails { … }
2289
+ ```
2290
+
2291
+ - **Use when:** find out whether an Android run was throttled or started hot · read battery temperature, current draw or per-rail power for a run
2292
+ - **Constraints:** a reading the device does not expose reports unavailable, never zero · a run that started hot or whose thermal status rose is flagged as confounded
2293
+
2294
+ ```ts
2295
+ const verdict = summarizeDeviceMetrics(observation.samples);
2296
+ ```
2297
+
2298
+ ### `parseDeviceThermal`
2299
+
2300
+ `function` — Measure and judge device thermal, power and battery state around a device playtest run.
2301
+
2302
+ ```ts
2303
+ export function parseDeviceThermal(output: string): IPlaytestDeviceThermal { … }
2304
+ ```
2305
+
2306
+ - **Use when:** find out whether an Android run was throttled or started hot · read battery temperature, current draw or per-rail power for a run
2307
+ - **Constraints:** a reading the device does not expose reports unavailable, never zero · a run that started hot or whose thermal status rose is flagged as confounded
2308
+
2309
+ ```ts
2310
+ const verdict = summarizeDeviceMetrics(observation.samples);
2311
+ ```
2312
+
2313
+ ### `playtestDiagnostic`
2314
+
2315
+ `function` — Create a structured playtest diagnostic.
2316
+
2317
+ ```ts
2318
+ export function playtestDiagnostic( code: PlaytestDiagnosticCode, message: string, instruction: string, details: Pick<IPlaytestProtocolDiagnostic, "capability" | "path"> & { … }
2319
+ ```
2320
+
2321
+ - **Use when:** report a named runtime diagnostic to a scenario · explain why a playtest assertion cannot pass
2322
+
2323
+ ```ts
2324
+ playtestDiagnostic("TN_PLAYTEST_CAPABILITY_MISSING", "body missing", "register rapier() before adding bodies");
2325
+ ```
2326
+
2327
+ ### `PlaytestScenarioError`
2328
+
2329
+ `class` — Load and validate a scenario, then control its tick steps.
2330
+
2331
+ ```ts
2332
+ export class PlaytestScenarioError extends Error { … }
2333
+ ```
2334
+
2335
+ - **Use when:** create a browser or device playtest scenario · wait or hold a game for a deterministic number of ticks
2336
+ - **Constraints:** unknown scenario keys fail closed
2337
+
2338
+ ```ts
2339
+ const scenario = await loadPlaytestScenario(project, file);
2340
+ ```
2341
+
2342
+ ### `playtestStepHoldTicks`
2343
+
2344
+ `function` — Load and validate a scenario, then control its tick steps.
2345
+
2346
+ ```ts
2347
+ export function playtestStepHoldTicks(step: IPlaytestStep, fallback = 1): number { … }
2348
+ ```
2349
+
2350
+ - **Use when:** create a browser or device playtest scenario · wait or hold a game for a deterministic number of ticks
2351
+ - **Constraints:** unknown scenario keys fail closed
2352
+
2353
+ ```ts
2354
+ const scenario = await loadPlaytestScenario(project, file);
2355
+ ```
2356
+
2357
+ ### `playtestStepWaitTicks`
2358
+
2359
+ `function` — Load and validate a scenario, then control its tick steps.
2360
+
2361
+ ```ts
2362
+ export function playtestStepWaitTicks(step: IPlaytestStep): number { … }
2363
+ ```
2364
+
2365
+ - **Use when:** create a browser or device playtest scenario · wait or hold a game for a deterministic number of ticks
2366
+ - **Constraints:** unknown scenario keys fail closed
2367
+
2368
+ ```ts
2369
+ const scenario = await loadPlaytestScenario(project, file);
2370
+ ```
2371
+
2372
+ ### `rejectUnknownKeys`
2373
+
2374
+ `function` — Load and validate a scenario, then control its tick steps.
2375
+
2376
+ ```ts
2377
+ export function rejectUnknownKeys( value: Record<string, unknown>, allowedKeys: readonly string[], scenarioPath: string, objectPath: string, ): void { … }
2378
+ ```
2379
+
2380
+ - **Use when:** create a browser or device playtest scenario · wait or hold a game for a deterministic number of ticks
2381
+ - **Constraints:** unknown scenario keys fail closed
2382
+
2383
+ ```ts
2384
+ const scenario = await loadPlaytestScenario(project, file);
2385
+ ```
2386
+
2387
+ ### `requiredPlaytestCapabilities`
2388
+
2389
+ `function` — Evaluate rich semantic assertions against captured observations.
2390
+
2391
+ ```ts
2392
+ export function requiredPlaytestCapabilities( scenario: IPlaytestScenario, target?: string, ): PlaytestCapability[] { … }
2393
+ ```
2394
+
2395
+ - **Use when:** assert movement, visibility, or diagnostics in a playtest · turn a scenario observation into a pass or failure
2396
+ - **Constraints:** malformed or empty assertions fail closed
2397
+
2398
+ ```ts
2399
+ const result = evaluateRichPlaytestAssertions(input);
2400
+ ```
2401
+
2402
+ ### `resolveDiagnosticsPolicy`
2403
+
2404
+ `function` — Resolve the effective diagnostics policy for a run, with fail-closed defaults applied.
2405
+
2406
+ ```ts
2407
+ export function resolveDiagnosticsPolicy( policy: IPlaytestDiagnosticsAssertion | undefined, target?: string, ): IPlaytestDiagnosticsPolicy { … }
2408
+ ```
2409
+
2410
+ - **Use when:** judge captured console, network, or runtime diagnostics for a playtest
2411
+ - **Constraints:** absent policy fields default to rejecting errors
2412
+
2413
+ ```ts
2414
+ const policy = resolveDiagnosticsPolicy(scenario.assert?.diagnostics);
2415
+ ```
2416
+
2417
+ ### `summarizeDeviceMetrics`
2418
+
2419
+ `function` — Measure and judge device thermal, power and battery state around a device playtest run.
2420
+
2421
+ ```ts
2422
+ export function summarizeDeviceMetrics( samples: readonly IPlaytestDeviceMetricsSample[], ): IPlaytestDeviceMetricsVerdict { … }
2423
+ ```
2424
+
2425
+ - **Use when:** find out whether an Android run was throttled or started hot · read battery temperature, current draw or per-rail power for a run
2426
+ - **Constraints:** a reading the device does not expose reports unavailable, never zero · a run that started hot or whose thermal status rose is flagged as confounded
2427
+
2428
+ ```ts
2429
+ const verdict = summarizeDeviceMetrics(observation.samples);
2430
+ ```
2431
+
2432
+ ### `unknownPlaytestCapabilities`
2433
+
2434
+ `function` — Validate and inspect playtest capability declarations.
2435
+
2436
+ ```ts
2437
+ export function unknownPlaytestCapabilities(capabilities: readonly string[]): string[] { … }
2438
+ ```
2439
+
2440
+ - **Use when:** check whether a scenario's required capabilities are installed · report unknown or missing playtest capabilities
2441
+
2442
+ ```ts
2443
+ const missing = missingPlaytestCapabilities(required, available);
2444
+ ```
2445
+
2446
+ ## `@threenative/playtest/capture`
2447
+
2448
+ ### `assertCaptureNotBlank`
2449
+
2450
+ `function` — Fail closed when a screenshot is blank or uniform.
2451
+
2452
+ ```ts
2453
+ export function assertCaptureNotBlank(png: Buffer, label: string): ICaptureFrameStats { … }
2454
+ ```
2455
+
2456
+ - **Use when:** guard a visual playtest against a blank frame · prove a screenshot contains more than a loading surface
2457
+ - **Constraints:** the assertion throws instead of returning a false pass
2458
+
2459
+ ```ts
2460
+ assertCaptureNotBlank(png, "first frame");
2461
+ ```
2462
+
2463
+ ### `CaptureGuardError`
2464
+
2465
+ `class` — Explain why a captured frame failed the non-blank guard.
2466
+
2467
+ ```ts
2468
+ export class CaptureGuardError extends Error { … }
2469
+ ```
2470
+
2471
+ - **Use when:** fail a visual test when the rendered frame is blank · include capture statistics in a playtest error
2472
+
2473
+ ```ts
2474
+ throw new CaptureGuardError("menu", "no bright pixels");
2475
+ ```
2476
+
2477
+ ### `inspectFrame`
2478
+
2479
+ `function` — Inspect a PNG frame for visible pixels and luminance variation.
2480
+
2481
+ ```ts
2482
+ export function inspectFrame(png: Buffer): ICaptureFrameStats { … }
2483
+ ```
2484
+
2485
+ - **Use when:** measure whether a screenshot contains a rendered game · diagnose a uniform or blank capture
2486
+
2487
+ ```ts
2488
+ const stats = inspectFrame(png);
2489
+ ```
2490
+
2491
+ ## `@threenative/playtest/protocol`
2492
+
2493
+ ### `assertJsonSafe`
2494
+
2495
+ `function` — Reject any value that would not survive JSON serialization.
2496
+
2497
+ ```ts
2498
+ export function assertJsonSafe(value: unknown, path = "$"): asserts value is JsonValue { … }
2499
+ ```
2500
+
2501
+ - **Use when:** validate entity components and gameplay observations before crossing the bridge
2502
+ - **Constraints:** throws instead of silently dropping the offending field
2503
+
2504
+ ```ts
2505
+ assertJsonSafe(snapshot, "$.components");
2506
+ ```
2507
+
2508
+ ### `jsonByteLength`
2509
+
2510
+ `function` — Measure a payload's wire size in bytes.
2511
+
2512
+ ```ts
2513
+ export function jsonByteLength(value: JsonValue): number { … }
2514
+ ```
2515
+
2516
+ - **Use when:** check a runtime observation against the protocol payload limit before sampling
2517
+
2518
+ ```ts
2519
+ const bytes = jsonByteLength(observation);
2520
+ ```
2521
+
2522
+ ## `@threenative/playtest/runner`
2523
+
2524
+ ### `AdbAndroidDriver`
2525
+
2526
+ `class` — Drive and inspect Android playtest transport.
2527
+
2528
+ ```ts
2529
+ export class AdbAndroidDriver implements IAndroidDriver { … }
2530
+ ```
2531
+
2532
+ - **Use when:** run a scenario on an Android emulator or device · parse Android console diagnostics
2533
+ - **Constraints:** Android evidence must name its target and transport
2534
+
2535
+ ```ts
2536
+ const adb = discoverAdb(process.env);
2537
+ ```
2538
+
2539
+ ### `advanceFixedStep`
2540
+
2541
+ `function` — Execute scenario steps, assertions, and evidence capture.
2542
+
2543
+ ```ts
2544
+ export async function advanceFixedStep( page: Page, bridge: Pick<IPlaytestBridgeClient, "advance">, ticks: number, ): Promise<void> { … }
2545
+ ```
2546
+
2547
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
2548
+ - **Constraints:** missing observations and malformed assertions fail closed
2549
+
2550
+ ```ts
2551
+ const report = await runStandalonePlaytest(options);
2552
+ ```
2553
+
2554
+ ### `advanceTimeoutMs`
2555
+
2556
+ `function` — Connect a Playwright page to a playtest bridge.
2557
+
2558
+ ```ts
2559
+ export function advanceTimeoutMs( ticks: number, perTickMs: number = PLAYTEST_ADVANCE_TICK_BUDGET_MS, ): number { … }
2560
+ ```
2561
+
2562
+ - **Use when:** run a browser scenario against a game · inspect bridge diagnostics from a runner
2563
+ - **Constraints:** the bridge must answer the handshake or the run fails
2564
+
2565
+ ```ts
2566
+ const bridge = await connectPlaytestBridge(page, scenario);
2567
+ ```
2568
+
2569
+ ### `androidMailboxPaths`
2570
+
2571
+ `function` — Resolve a native device transport and its mailbox paths.
2572
+
2573
+ ```ts
2574
+ export function androidMailboxPaths( packageName: string, root = `/sdcard/Android/data/$ { … }
2575
+ ```
2576
+
2577
+ - **Use when:** connect a native host to the playtest runner · validate an Android or iOS device endpoint
2578
+ - **Constraints:** paths stay inside the managed artifact directory
2579
+
2580
+ ```ts
2581
+ const paths = deviceMailboxPaths(projectRoot);
2582
+ ```
2583
+
2584
+ ### `androidTouchBatches`
2585
+
2586
+ `function` — Drive and inspect Android playtest transport.
2587
+
2588
+ ```ts
2589
+ export function androidTouchBatches( identity: readonly string[], positions: readonly string[], ): string[][] { … }
2590
+ ```
2591
+
2592
+ - **Use when:** run a scenario on an Android emulator or device · parse Android console diagnostics
2593
+ - **Constraints:** Android evidence must name its target and transport
2594
+
2595
+ ```ts
2596
+ const adb = discoverAdb(process.env);
2597
+ ```
2598
+
2599
+ ### `batchArtifactDirectory`
2600
+
2601
+ `function` — Execute scenario steps, assertions, and evidence capture.
2602
+
2603
+ ```ts
2604
+ export function batchArtifactDirectory(base: string, scenarioPath: string, index: number): string { … }
2605
+ ```
2606
+
2607
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
2608
+ - **Constraints:** missing observations and malformed assertions fail closed
2609
+
2610
+ ```ts
2611
+ const report = await runStandalonePlaytest(options);
2612
+ ```
2613
+
2614
+ ### `boundedTeardownStep`
2615
+
2616
+ `function` — Execute scenario steps, assertions, and evidence capture.
2617
+
2618
+ ```ts
2619
+ export async function boundedTeardownStep( step: Promise<unknown> | undefined, timeoutMs: number, ): Promise<boolean> { … }
2620
+ ```
2621
+
2622
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
2623
+ - **Constraints:** missing observations and malformed assertions fail closed
2624
+
2625
+ ```ts
2626
+ const report = await runStandalonePlaytest(options);
2627
+ ```
2628
+
2629
+ ### `bridgeWaitTimeoutMs`
2630
+
2631
+ `function` — Connect a Playwright page to a playtest bridge.
2632
+
2633
+ ```ts
2634
+ export function bridgeWaitTimeoutMs( operationMs: number = PLAYTEST_PROTOCOL_LIMITS.operationTimeoutMs, ): number { … }
2635
+ ```
2636
+
2637
+ - **Use when:** run a browser scenario against a game · inspect bridge diagnostics from a runner
2638
+ - **Constraints:** the bridge must answer the handshake or the run fails
2639
+
2640
+ ```ts
2641
+ const bridge = await connectPlaytestBridge(page, scenario);
2642
+ ```
2643
+
2644
+ ### `buildReport`
2645
+
2646
+ `function` — Execute scenario steps, assertions, and evidence capture.
2647
+
2648
+ ```ts
2649
+ export function buildReport( config: IStandalonePlaytestConfig, scenario: IPlaytestScenario, beforeSnapshot: IPlaytestObservationSnapshot | undefined, afterSnapshot: IPlaytestObservationSnapshot | undefined, consoleEntries: IRunnerConsoleEntry[], networkEntries: Array< { … }
2650
+ ```
2651
+
2652
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
2653
+ - **Constraints:** missing observations and malformed assertions fail closed
2654
+
2655
+ ```ts
2656
+ const report = await runStandalonePlaytest(options);
2657
+ ```
2658
+
2659
+ ### `captureVisualSurface`
2660
+
2661
+ `function` — Execute scenario steps, assertions, and evidence capture.
2662
+
2663
+ ```ts
2664
+ export async function captureVisualSurface( page: Page, artifactPath?: string, ): Promise<Buffer | undefined> { … }
2665
+ ```
2666
+
2667
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
2668
+ - **Constraints:** missing observations and malformed assertions fail closed
2669
+
2670
+ ```ts
2671
+ const report = await runStandalonePlaytest(options);
2672
+ ```
2673
+
2674
+ ### `connectPlaytestBridge`
2675
+
2676
+ `function` — Connect a Playwright page to a playtest bridge.
2677
+
2678
+ ```ts
2679
+ export async function connectPlaytestBridge( page: Page, scenario: IPlaytestScenario, timeoutMs: number = PLAYTEST_PROTOCOL_LIMITS.operationTimeoutMs, ): Promise<IPlaytestBridgeClient | undefined> { … }
2680
+ ```
2681
+
2682
+ - **Use when:** run a browser scenario against a game · inspect bridge diagnostics from a runner
2683
+ - **Constraints:** the bridge must answer the handshake or the run fails
2684
+
2685
+ ```ts
2686
+ const bridge = await connectPlaytestBridge(page, scenario);
2687
+ ```
2688
+
2689
+ ### `connectPlaytestBridgeTransport`
2690
+
2691
+ `function` — Connect a Playwright page to a playtest bridge.
2692
+
2693
+ ```ts
2694
+ export async function connectPlaytestBridgeTransport( transport: IBridgeTransport, scenario: IPlaytestScenario, timeoutMs: number = bridgeWaitTimeoutMs(), target?: string, ): Promise<IPlaytestBridgeClient | undefined> { … }
2695
+ ```
2696
+
2697
+ - **Use when:** run a browser scenario against a game · inspect bridge diagnostics from a runner
2698
+ - **Constraints:** the bridge must answer the handshake or the run fails
2699
+
2700
+ ```ts
2701
+ const bridge = await connectPlaytestBridge(page, scenario);
2702
+ ```
2703
+
2704
+ ### `DesktopPlaytestDriver`
2705
+
2706
+ `class` — Drive a local desktop playtest mailbox.
2707
+
2708
+ ```ts
2709
+ export class DesktopPlaytestDriver implements IDevicePlaytestDriver { … }
2710
+ ```
2711
+
2712
+ - **Use when:** run a desktop target through the playtest protocol · exchange observations with a native desktop host
2713
+ - **Constraints:** the mailbox lifecycle must be disposed after the run
2714
+
2715
+ ```ts
2716
+ const driver = new DesktopPlaytestDriver(options);
2717
+ ```
2718
+
2719
+ ### `DeviceBridgeTransport`
2720
+
2721
+ `class` — Resolve a native device transport and its mailbox paths.
2722
+
2723
+ ```ts
2724
+ export class DeviceBridgeTransport implements IDevicePlaytestTransport { … }
2725
+ ```
2726
+
2727
+ - **Use when:** connect a native host to the playtest runner · validate an Android or iOS device endpoint
2728
+ - **Constraints:** paths stay inside the managed artifact directory
2729
+
2730
+ ```ts
2731
+ const paths = deviceMailboxPaths(projectRoot);
2732
+ ```
2733
+
2734
+ ### `deviceMailboxPaths`
2735
+
2736
+ `function` — Resolve a native device transport and its mailbox paths.
2737
+
2738
+ ```ts
2739
+ export function deviceMailboxPaths(root: string): IDeviceMailboxPaths { … }
2740
+ ```
2741
+
2742
+ - **Use when:** connect a native host to the playtest runner · validate an Android or iOS device endpoint
2743
+ - **Constraints:** paths stay inside the managed artifact directory
2744
+
2745
+ ```ts
2746
+ const paths = deviceMailboxPaths(projectRoot);
2747
+ ```
2748
+
2749
+ ### `DeviceMailboxTransport`
2750
+
2751
+ `class` — Resolve a native device transport and its mailbox paths.
2752
+
2753
+ ```ts
2754
+ export class DeviceMailboxTransport implements IDevicePlaytestTransport { … }
2755
+ ```
2756
+
2757
+ - **Use when:** connect a native host to the playtest runner · validate an Android or iOS device endpoint
2758
+ - **Constraints:** paths stay inside the managed artifact directory
2759
+
2760
+ ```ts
2761
+ const paths = deviceMailboxPaths(projectRoot);
2762
+ ```
2763
+
2764
+ ### `deviceTimeoutDiagnostic`
2765
+
2766
+ `function` — Resolve a native device transport and its mailbox paths.
2767
+
2768
+ ```ts
2769
+ export function deviceTimeoutDiagnostic( diagnostic: IPlaytestProtocolDiagnostic, hostAlive: boolean | undefined, lastConsoleLines: readonly string[], ): IPlaytestProtocolDiagnostic { … }
2770
+ ```
2771
+
2772
+ - **Use when:** connect a native host to the playtest runner · validate an Android or iOS device endpoint
2773
+ - **Constraints:** paths stay inside the managed artifact directory
2774
+
2775
+ ```ts
2776
+ const paths = deviceMailboxPaths(projectRoot);
2777
+ ```
2778
+
2779
+ ### `discoverAdb`
2780
+
2781
+ `function` — Drive and inspect Android playtest transport.
2782
+
2783
+ ```ts
2784
+ export function discoverAdb(environment: NodeJS.ProcessEnv = process.env): string { … }
2785
+ ```
2786
+
2787
+ - **Use when:** run a scenario on an Android emulator or device · parse Android console diagnostics
2788
+ - **Constraints:** Android evidence must name its target and transport
2789
+
2790
+ ```ts
2791
+ const adb = discoverAdb(process.env);
2792
+ ```
2793
+
2794
+ ### `failedDiagnosticsAssertion`
2795
+
2796
+ `function` — Execute scenario steps, assertions, and evidence capture.
2797
+
2798
+ ```ts
2799
+ export function failedDiagnosticsAssertion(policy: IPlaytestDiagnosticsPolicy): IPlaytestAssertionResult { … }
2800
+ ```
2801
+
2802
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
2803
+ - **Constraints:** missing observations and malformed assertions fail closed
2804
+
2805
+ ```ts
2806
+ const report = await runStandalonePlaytest(options);
2807
+ ```
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
+
2824
+ ### `formatUsage`
2825
+
2826
+ `function` — Parse standalone playtest runner configuration.
2827
+
2828
+ ```ts
2829
+ export function formatUsage(): string { … }
2830
+ ```
2831
+
2832
+ - **Use when:** invoke the playtest CLI from a scaffold · validate runner flags before launching a browser
2833
+ - **Constraints:** invalid flags throw a named usage error
2834
+
2835
+ ```ts
2836
+ const config = parseStandalonePlaytestArgs(argv);
2837
+ ```
2838
+
2839
+ ### `handlePlaytestSignal`
2840
+
2841
+ `function` — Execute scenario steps, assertions, and evidence capture.
2842
+
2843
+ ```ts
2844
+ export async function handlePlaytestSignal( teardown: (stopManagedServer: boolean) => Promise<void>, setExitCode: (code: number) => void = (code) => { … }
2845
+ ```
2846
+
2847
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
2848
+ - **Constraints:** missing observations and malformed assertions fail closed
2849
+
2850
+ ```ts
2851
+ const report = await runStandalonePlaytest(options);
2852
+ ```
2853
+
2854
+ ### `initStandalonePlaytest`
2855
+
2856
+ `function` — Initialize the standalone playtest files for a project.
2857
+
2858
+ ```ts
2859
+ export async function initStandalonePlaytest(projectPath = process.cwd()): Promise< { … }
2860
+ ```
2861
+
2862
+ - **Use when:** add the runner contract to a new game · create a starter scenario fixture
2863
+ - **Constraints:** generated scenarios must contain real assertions
2864
+
2865
+ ```ts
2866
+ await initStandalonePlaytest(projectPath);
2867
+ ```
2868
+
2869
+ ### `isRuntimeReadout`
2870
+
2871
+ `function` — Execute scenario steps, assertions, and evidence capture.
2872
+
2873
+ ```ts
2874
+ export function isRuntimeReadout(entry: unknown): boolean { … }
2875
+ ```
2876
+
2877
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
2878
+ - **Constraints:** missing observations and malformed assertions fail closed
2879
+
2880
+ ```ts
2881
+ const report = await runStandalonePlaytest(options);
2882
+ ```
2883
+
2884
+ ### `keyboardIsShown`
2885
+
2886
+ `function` — Drive and inspect Android playtest transport.
2887
+
2888
+ ```ts
2889
+ export function keyboardIsShown(dump: string): boolean { … }
2890
+ ```
2891
+
2892
+ - **Use when:** run a scenario on an Android emulator or device · parse Android console diagnostics
2893
+ - **Constraints:** Android evidence must name its target and transport
2894
+
2895
+ ```ts
2896
+ const adb = discoverAdb(process.env);
2897
+ ```
2898
+
2899
+ ### `LocalDeviceMailbox`
2900
+
2901
+ `class` — Drive a local desktop playtest mailbox.
2902
+
2903
+ ```ts
2904
+ export class LocalDeviceMailbox { … }
2905
+ ```
2906
+
2907
+ - **Use when:** run a desktop target through the playtest protocol · exchange observations with a native desktop host
2908
+ - **Constraints:** the mailbox lifecycle must be disposed after the run
2909
+
2910
+ ```ts
2911
+ const driver = new DesktopPlaytestDriver(options);
2912
+ ```
2913
+
2914
+ ### `ManagedServerError`
2915
+
2916
+ `class` — Execute scenario steps, assertions, and evidence capture.
2917
+
2918
+ ```ts
2919
+ export class ManagedServerError extends Error { … }
2920
+ ```
2921
+
2922
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
2923
+ - **Constraints:** missing observations and malformed assertions fail closed
2924
+
2925
+ ```ts
2926
+ const report = await runStandalonePlaytest(options);
2927
+ ```
2928
+
2929
+ ### `openPageAndConnectBridge`
2930
+
2931
+ `function` — Execute scenario steps, assertions, and evidence capture.
2932
+
2933
+ ```ts
2934
+ export async function openPageAndConnectBridge( page: Page, config: IStandalonePlaytestConfig, scenario: IPlaytestScenario, ): Promise<IPlaytestBridgeClient | undefined> { … }
2935
+ ```
2936
+
2937
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
2938
+ - **Constraints:** missing observations and malformed assertions fail closed
2939
+
2940
+ ```ts
2941
+ const report = await runStandalonePlaytest(options);
2942
+ ```
2943
+
2944
+ ### `pageLifecycleDiagnostic`
2945
+
2946
+ `function` — Execute scenario steps, assertions, and evidence capture.
2947
+
2948
+ ```ts
2949
+ export function pageLifecycleDiagnostic( error: unknown, lifecycle: IPageLifecycle, url: string, ): IPlaytestProtocolDiagnostic | undefined { … }
2950
+ ```
2951
+
2952
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
2953
+ - **Constraints:** missing observations and malformed assertions fail closed
2954
+
2955
+ ```ts
2956
+ const report = await runStandalonePlaytest(options);
2957
+ ```
2958
+
2959
+ ### `parseAndroidConsole`
2960
+
2961
+ `function` — Drive and inspect Android playtest transport.
2962
+
2963
+ ```ts
2964
+ export function parseAndroidConsole(output: string): Array< { … }
2965
+ ```
2966
+
2967
+ - **Use when:** run a scenario on an Android emulator or device · parse Android console diagnostics
2968
+ - **Constraints:** Android evidence must name its target and transport
2969
+
2970
+ ```ts
2971
+ const adb = discoverAdb(process.env);
2972
+ ```
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
+
2989
+ ### `parseLaunchedPid`
2990
+
2991
+ `function` — Drive and inspect iOS simulator playtest transport.
2992
+
2993
+ ```ts
2994
+ export function parseLaunchedPid(output: string): string { … }
2995
+ ```
2996
+
2997
+ - **Use when:** run a scenario on the iOS simulator · parse the launched native process identifier
2998
+ - **Constraints:** simulator evidence does not claim physical-device proof
2999
+
3000
+ ```ts
3001
+ const driver = new XcrunIosDriver(options);
3002
+ ```
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
+
3034
+ ### `parseStandalonePlaytestArgs`
3035
+
3036
+ `function` — Parse standalone playtest runner configuration.
3037
+
3038
+ ```ts
3039
+ export function parseStandalonePlaytestArgs(argv: readonly string[], cwd = process.cwd()): IStandalonePlaytestConfig { … }
3040
+ ```
3041
+
3042
+ - **Use when:** invoke the playtest CLI from a scaffold · validate runner flags before launching a browser
3043
+ - **Constraints:** invalid flags throw a named usage error
3044
+
3045
+ ```ts
3046
+ const config = parseStandalonePlaytestArgs(argv);
3047
+ ```
3048
+
3049
+ ### `PlaytestBridgeError`
3050
+
3051
+ `class` — Connect a Playwright page to a playtest bridge.
3052
+
3053
+ ```ts
3054
+ export class PlaytestBridgeError extends Error { … }
3055
+ ```
3056
+
3057
+ - **Use when:** run a browser scenario against a game · inspect bridge diagnostics from a runner
3058
+ - **Constraints:** the bridge must answer the handshake or the run fails
3059
+
3060
+ ```ts
3061
+ const bridge = await connectPlaytestBridge(page, scenario);
3062
+ ```
3063
+
3064
+ ### `PlaytestCliUsageError`
3065
+
3066
+ `class` — Parse standalone playtest runner configuration.
3067
+
3068
+ ```ts
3069
+ export class PlaytestCliUsageError extends Error { … }
3070
+ ```
3071
+
3072
+ - **Use when:** invoke the playtest CLI from a scaffold · validate runner flags before launching a browser
3073
+ - **Constraints:** invalid flags throw a named usage error
3074
+
3075
+ ```ts
3076
+ const config = parseStandalonePlaytestArgs(argv);
3077
+ ```
3078
+
3079
+ ### `playtestStepDrivesMovement`
3080
+
3081
+ `function` — Execute scenario steps, assertions, and evidence capture.
3082
+
3083
+ ```ts
3084
+ export function playtestStepDrivesMovement( step: IPlaytestScenario["steps"][number], hasHeldInput: boolean, ): boolean { … }
3085
+ ```
3086
+
3087
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
3088
+ - **Constraints:** missing observations and malformed assertions fail closed
3089
+
3090
+ ```ts
3091
+ const report = await runStandalonePlaytest(options);
3092
+ ```
3093
+
3094
+ ### `PlaywrightTransport`
3095
+
3096
+ `class` — Connect a Playwright page to a playtest bridge.
3097
+
3098
+ ```ts
3099
+ export class PlaywrightTransport implements IBridgeTransport { … }
3100
+ ```
3101
+
3102
+ - **Use when:** run a browser scenario against a game · inspect bridge diagnostics from a runner
3103
+ - **Constraints:** the bridge must answer the handshake or the run fails
3104
+
3105
+ ```ts
3106
+ const bridge = await connectPlaytestBridge(page, scenario);
3107
+ ```
3108
+
3109
+ ### `preflightDisplay`
3110
+
3111
+ `function` — Execute scenario steps, assertions, and evidence capture.
3112
+
3113
+ ```ts
3114
+ export function preflightDisplay( config: Pick<IStandalonePlaytestConfig, "headless">, scenario: Pick<IPlaytestScenario, "artifacts" | "assert" | "steps">, environment: NodeJS.ProcessEnv = process.env, platform = process.platform, ): IPlaytestDiagnostic | undefined { … }
3115
+ ```
3116
+
3117
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
3118
+ - **Constraints:** missing observations and malformed assertions fail closed
3119
+
3120
+ ```ts
3121
+ const report = await runStandalonePlaytest(options);
3122
+ ```
3123
+
3124
+ ### `reconcileBrowserPointers`
3125
+
3126
+ `function` — Select safe Chromium arguments for WebGPU playtests.
3127
+
3128
+ ```ts
3129
+ export function reconcileBrowserPointers( previous: ReadonlyMap<number, Required<IPlaytestPointer>>, next: readonly IPlaytestPointer[], ): IBrowserPointerChange[] { … }
3130
+ ```
3131
+
3132
+ - **Use when:** run a browser playtest with Vulkan WebGPU · reject a SwiftShader adapter as evidence
3133
+ - **Constraints:** inspect the adapter name before claiming GPU proof
3134
+
3135
+ ```ts
3136
+ const args = resolveBrowserArguments(undefined);
3137
+ ```
3138
+
3139
+ ### `recordToScenario`
3140
+
3141
+ `function` — Convert captured runner observations into a replay scenario.
3142
+
3143
+ ```ts
3144
+ export function recordToScenario( value: unknown, scenarioPath = "recording.json", oracleValue?: unknown, ): IPlaytestScenario { … }
3145
+ ```
3146
+
3147
+ - **Use when:** preserve a failing playtest as a replay fixture · require assertions before recording a scenario
3148
+ - **Constraints:** an empty assertion set is a failure
3149
+
3150
+ ```ts
3151
+ const scenario = recordToScenario(recording);
3152
+ ```
3153
+
3154
+ ### `requireAssertions`
3155
+
3156
+ `function` — Convert captured runner observations into a replay scenario.
3157
+
3158
+ ```ts
3159
+ export function requireAssertions( value: IPlaytestScenario["assert"], scenarioPath: string, ): NonNullable<IPlaytestScenario["assert"]> { … }
3160
+ ```
3161
+
3162
+ - **Use when:** preserve a failing playtest as a replay fixture · require assertions before recording a scenario
3163
+ - **Constraints:** an empty assertion set is a failure
3164
+
3165
+ ```ts
3166
+ const scenario = recordToScenario(recording);
3167
+ ```
3168
+
3169
+ ### `resolveBrowserArguments`
3170
+
3171
+ `function` — Select safe Chromium arguments for WebGPU playtests.
3172
+
3173
+ ```ts
3174
+ export function resolveBrowserArguments(browserArgs: readonly string[] | undefined): string[] { … }
3175
+ ```
3176
+
3177
+ - **Use when:** run a browser playtest with Vulkan WebGPU · reject a SwiftShader adapter as evidence
3178
+ - **Constraints:** inspect the adapter name before claiming GPU proof
3179
+
3180
+ ```ts
3181
+ const args = resolveBrowserArguments(undefined);
3182
+ ```
3183
+
3184
+ ### `resolveManagedServerCommand`
3185
+
3186
+ `function` — Execute scenario steps, assertions, and evidence capture.
3187
+
3188
+ ```ts
3189
+ export function resolveManagedServerCommand( config: IStandalonePlaytestConfig, dynamicPort?: number, ): string { … }
3190
+ ```
3191
+
3192
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
3193
+ - **Constraints:** missing observations and malformed assertions fail closed
3194
+
3195
+ ```ts
3196
+ const report = await runStandalonePlaytest(options);
3197
+ ```
3198
+
3199
+ ### `resolveManagedServerConfig`
3200
+
3201
+ `function` — Execute scenario steps, assertions, and evidence capture.
3202
+
3203
+ ```ts
3204
+ export async function resolveManagedServerConfig( config: IStandalonePlaytestConfig, ): Promise<IStandalonePlaytestConfig> { … }
3205
+ ```
3206
+
3207
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
3208
+ - **Constraints:** missing observations and malformed assertions fail closed
3209
+
3210
+ ```ts
3211
+ const report = await runStandalonePlaytest(options);
3212
+ ```
3213
+
3214
+ ### `rotatedTouchPosition`
3215
+
3216
+ `function` — Drive and inspect Android playtest transport.
3217
+
3218
+ ```ts
3219
+ export function rotatedTouchPosition(x: number, y: number, rotation: number): [number, number] { … }
3220
+ ```
3221
+
3222
+ - **Use when:** run a scenario on an Android emulator or device · parse Android console diagnostics
3223
+ - **Constraints:** Android evidence must name its target and transport
3224
+
3225
+ ```ts
3226
+ const adb = discoverAdb(process.env);
3227
+ ```
3228
+
3229
+ ### `runAndroidPlaytest`
3230
+
3231
+ `function` — Run a playtest on Android through the configured device transport.
3232
+
3233
+ ```ts
3234
+ export async function runAndroidPlaytest( config: IStandalonePlaytestConfig, dependencies: IAndroidPlaytestDependencies = { … }
3235
+ ```
3236
+
3237
+ - **Use when:** execute a scenario on an Android target · collect Android playtest artifacts
3238
+ - **Constraints:** the app bundle and device transport must be prepared
3239
+
3240
+ ```ts
3241
+ await runAndroidPlaytest(options);
3242
+ ```
3243
+
3244
+ ### `runDesktopPlaytest`
3245
+
3246
+ `function` — Run a desktop playtest and collect its report.
3247
+
3248
+ ```ts
3249
+ export async function runDesktopPlaytest( config: IStandalonePlaytestConfig, dependencies: IDesktopPlaytestDependencies = { … }
3250
+ ```
3251
+
3252
+ - **Use when:** execute a scenario against the desktop host · verify native desktop behavior from the same scenario
3253
+ - **Constraints:** the desktop host must be built before launching
3254
+
3255
+ ```ts
3256
+ await runDesktopPlaytest(options);
3257
+ ```
3258
+
3259
+ ### `runDevicePlaytest`
3260
+
3261
+ `function` — Run a playtest on Android through the configured device transport.
3262
+
3263
+ ```ts
3264
+ export async function runDevicePlaytest( config: IStandalonePlaytestConfig, target: IDevicePlaytestTarget, ): Promise<IStandalonePlaytestReport> { … }
3265
+ ```
3266
+
3267
+ - **Use when:** execute a scenario on an Android target · collect Android playtest artifacts
3268
+ - **Constraints:** the app bundle and device transport must be prepared
3269
+
3270
+ ```ts
3271
+ await runAndroidPlaytest(options);
3272
+ ```
3273
+
3274
+ ### `runIosPlaytest`
3275
+
3276
+ `function` — Run a playtest on the iOS simulator or device transport.
3277
+
3278
+ ```ts
3279
+ export async function runIosPlaytest( config: IStandalonePlaytestConfig, dependencies: IIosPlaytestDependencies = { … }
3280
+ ```
3281
+
3282
+ - **Use when:** execute a scenario on an iOS target · collect iOS playtest artifacts
3283
+ - **Constraints:** identify simulator versus physical transport in evidence
3284
+
3285
+ ```ts
3286
+ await runIosPlaytest(options);
3287
+ ```
3288
+
3289
+ ### `runStandalonePlaytest`
3290
+
3291
+ `function` — Execute scenario steps, assertions, and evidence capture.
3292
+
3293
+ ```ts
3294
+ export async function runStandalonePlaytest( config: IStandalonePlaytestConfig, options: IStandalonePlaytestRunOptions = { … }
3295
+ ```
3296
+
3297
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
3298
+ - **Constraints:** missing observations and malformed assertions fail closed
3299
+
3300
+ ```ts
3301
+ const report = await runStandalonePlaytest(options);
3302
+ ```
3303
+
3304
+ ### `runStandalonePlaytests`
3305
+
3306
+ `function` — Execute scenario steps, assertions, and evidence capture.
3307
+
3308
+ ```ts
3309
+ export async function runStandalonePlaytests( config: IStandalonePlaytestConfig, ): Promise<readonly IStandalonePlaytestReport[]> { … }
3310
+ ```
3311
+
3312
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
3313
+ - **Constraints:** missing observations and malformed assertions fail closed
3314
+
3315
+ ```ts
3316
+ const report = await runStandalonePlaytest(options);
3317
+ ```
3318
+
3319
+ ### `softwareAdapterName`
3320
+
3321
+ `function` — Select safe Chromium arguments for WebGPU playtests.
3322
+
3323
+ ```ts
3324
+ export function softwareAdapterName(adapter: Readonly<Record<string, string>> | undefined): string | undefined { … }
3325
+ ```
3326
+
3327
+ - **Use when:** run a browser playtest with Vulkan WebGPU · reject a SwiftShader adapter as evidence
3328
+ - **Constraints:** inspect the adapter name before claiming GPU proof
3329
+
3330
+ ```ts
3331
+ const args = resolveBrowserArguments(undefined);
3332
+ ```
3333
+
3334
+ ### `substituteManagedPort`
3335
+
3336
+ `function` — Execute scenario steps, assertions, and evidence capture.
3337
+
3338
+ ```ts
3339
+ export function substituteManagedPort(command: string, port: number): string { … }
3340
+ ```
3341
+
3342
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
3343
+ - **Constraints:** missing observations and malformed assertions fail closed
3344
+
3345
+ ```ts
3346
+ const report = await runStandalonePlaytest(options);
3347
+ ```
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
+
3364
+ ### `tapCommand`
3365
+
3366
+ `function` — Drive and inspect Android playtest transport.
3367
+
3368
+ ```ts
3369
+ export function tapCommand(x: number, y: number): string[] { … }
3370
+ ```
3371
+
3372
+ - **Use when:** run a scenario on an Android emulator or device · parse Android console diagnostics
3373
+ - **Constraints:** Android evidence must name its target and transport
3374
+
3375
+ ```ts
3376
+ const adb = discoverAdb(process.env);
3377
+ ```
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
+
3394
+ ### `touchRotationFromWindowDump`
3395
+
3396
+ `function` — Drive and inspect Android playtest transport.
3397
+
3398
+ ```ts
3399
+ export function touchRotationFromWindowDump(dump: string): number | undefined { … }
3400
+ ```
3401
+
3402
+ - **Use when:** run a scenario on an Android emulator or device · parse Android console diagnostics
3403
+ - **Constraints:** Android evidence must name its target and transport
3404
+
3405
+ ```ts
3406
+ const adb = discoverAdb(process.env);
3407
+ ```
3408
+
3409
+ ### `validateDeviceEndpoint`
3410
+
3411
+ `function` — Resolve a native device transport and its mailbox paths.
3412
+
3413
+ ```ts
3414
+ export function validateDeviceEndpoint(value: string): URL { … }
3415
+ ```
3416
+
3417
+ - **Use when:** connect a native host to the playtest runner · validate an Android or iOS device endpoint
3418
+ - **Constraints:** paths stay inside the managed artifact directory
3419
+
3420
+ ```ts
3421
+ const paths = deviceMailboxPaths(projectRoot);
3422
+ ```
3423
+
3424
+ ### `viewportPresentationCommands`
3425
+
3426
+ `function` — Drive and inspect Android playtest transport.
3427
+
3428
+ ```ts
3429
+ export function viewportPresentationCommands( viewport: { … }
3430
+ ```
3431
+
3432
+ - **Use when:** run a scenario on an Android emulator or device · parse Android console diagnostics
3433
+ - **Constraints:** Android evidence must name its target and transport
3434
+
3435
+ ```ts
3436
+ const adb = discoverAdb(process.env);
3437
+ ```
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
+
3454
+ ### `viewportRestoreCommands`
3455
+
3456
+ `function` — Drive and inspect Android playtest transport.
3457
+
3458
+ ```ts
3459
+ export function viewportRestoreCommands(): string[][] { … }
3460
+ ```
3461
+
3462
+ - **Use when:** run a scenario on an Android emulator or device · parse Android console diagnostics
3463
+ - **Constraints:** Android evidence must name its target and transport
3464
+
3465
+ ```ts
3466
+ const adb = discoverAdb(process.env);
3467
+ ```
3468
+
3469
+ ### `writeCaptureProvenance`
3470
+
3471
+ `function` — Execute scenario steps, assertions, and evidence capture.
3472
+
3473
+ ```ts
3474
+ export async function writeCaptureProvenance( artifactDirectory: string, provenance: IPlaytestCaptureProvenance, ): Promise<void> { … }
3475
+ ```
3476
+
3477
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
3478
+ - **Constraints:** missing observations and malformed assertions fail closed
3479
+
3480
+ ```ts
3481
+ const report = await runStandalonePlaytest(options);
3482
+ ```
3483
+
3484
+ ### `writeObservationArtifacts`
3485
+
3486
+ `function` — Execute scenario steps, assertions, and evidence capture.
3487
+
3488
+ ```ts
3489
+ export async function writeObservationArtifacts( artifactDirectory: string, requested: IPlaytestArtifactRequest | undefined, observations: { … }
3490
+ ```
3491
+
3492
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
3493
+ - **Constraints:** missing observations and malformed assertions fail closed
3494
+
3495
+ ```ts
3496
+ const report = await runStandalonePlaytest(options);
3497
+ ```
3498
+
3499
+ ### `XcrunIosDriver`
3500
+
3501
+ `class` — Drive and inspect iOS simulator playtest transport.
3502
+
3503
+ ```ts
3504
+ export class XcrunIosDriver implements IDevicePlaytestDriver { … }
3505
+ ```
3506
+
3507
+ - **Use when:** run a scenario on the iOS simulator · parse the launched native process identifier
3508
+ - **Constraints:** simulator evidence does not claim physical-device proof
3509
+
3510
+ ```ts
3511
+ const driver = new XcrunIosDriver(options);
3512
+ ```
3513
+
3514
+ ## `@threenative/playtest/three`
3515
+
3516
+ ### `adviseThreeRenderWorkload`
3517
+
3518
+ `function` — Explain which render workloads should be collapsed or retained.
3519
+
3520
+ ```ts
3521
+ export function adviseThreeRenderWorkload(input: IRenderAdvisorInput): IRenderAdvisorReport { … }
3522
+ ```
3523
+
3524
+ - **Use when:** diagnose a slow Three.js scene · choose a render optimization from observed workload data
3525
+ - **Constraints:** use measured input rather than visual guesses
3526
+
3527
+ ```ts
3528
+ const advice = adviseThreeRenderWorkload(input);
3529
+ ```
3530
+
3531
+ ### `connectDevicePlaytestBridge`
3532
+
3533
+ `function` — Connect a device-hosted game to the playtest bridge.
3534
+
3535
+ ```ts
3536
+ export function connectDevicePlaytestBridge( bridge: IPlaytestBridgeV1, endpoint: string, ): IDeviceBridgeInstallation { … }
3537
+ ```
3538
+
3539
+ - **Use when:** run the same playtest on an Android or iOS target · read the device bridge endpoint
3540
+ - **Constraints:** use the device transport selected by the runner
3541
+
3542
+ ```ts
3543
+ const connection = connectDevicePlaytestBridge(bridge, endpoint);
3544
+ ```
3545
+
3546
+ ### `installThreePlaytestBridge`
3547
+
3548
+ `function` — Install the playtest observation bridge for a plain Three.js game.
3549
+
3550
+ ```ts
3551
+ export function installThreePlaytestBridge(options: IThreePlaytestBridgeOptions): IThreePlaytestBridgeInstallation { … }
3552
+ ```
3553
+
3554
+ - **Use when:** expose a non-ThreeNative game to the scenario runner · add semantic observations to a browser playtest
3555
+ - **Constraints:** install once before the runner connects
3556
+
3557
+ ```ts
3558
+ const bridge = installThreePlaytestBridge(options);
3559
+ ```
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
+
3576
+ ### `readPlaytestEndpoint`
3577
+
3578
+ `function` — Connect a device-hosted game to the playtest bridge.
3579
+
3580
+ ```ts
3581
+ export function readPlaytestEndpoint(): string | undefined { … }
3582
+ ```
3583
+
3584
+ - **Use when:** run the same playtest on an Android or iOS target · read the device bridge endpoint
3585
+ - **Constraints:** use the device transport selected by the runner
3586
+
3587
+ ```ts
3588
+ const connection = connectDevicePlaytestBridge(bridge, endpoint);
3589
+ ```
3590
+
3591
+ ### `ThreePlaytestPhysicsRecorder`
3592
+
3593
+ `class` — Record Three.js physics bodies for playtest observations.
3594
+
3595
+ ```ts
3596
+ export class ThreePlaytestPhysicsRecorder { … }
3597
+ ```
3598
+
3599
+ - **Use when:** assert physics contacts in a plain Three.js game · capture bounded body state for a scenario
3600
+ - **Constraints:** keep recorder limits within the documented caps
3601
+
3602
+ ```ts
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);
3942
+ ```
3943
+
3944
+ ## `@threenative/template/starter/src/render/effects/gradualBackground`
3945
+
3946
+ ### `gradualBackground`
3947
+
3948
+ `function` — ThreeNative equivalent for realism-effects gradualBackground.
3949
+
3950
+ ```ts
3951
+ function gradualBackground
3952
+ ```
3953
+
3954
+ - **Use when:** grade a background by distance
3955
+ - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
3956
+
3957
+ ```ts
3958
+ gradualBackground(...)
3959
+ ```
3960
+
3961
+ ## `@threenative/template/starter/src/render/effects/lensDistortion`
3962
+
3963
+ ### `lensDistortion`
3964
+
3965
+ `function` — ThreeNative equivalent for realism-effects lensDistortion.
3966
+
3967
+ ```ts
3968
+ function lensDistortion
3969
+ ```
3970
+
3971
+ - **Use when:** warp the image with radial lens distortion
3972
+ - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
3973
+
3974
+ ```ts
3975
+ lensDistortion(...)
3976
+ ```
3977
+
3978
+ ## `@threenative/template/starter/src/render/effects/sparkle`
3979
+
3980
+ ### `sparkle`
3981
+
3982
+ `function` — ThreeNative equivalent for realism-effects sparkle.
3983
+
3984
+ ```ts
3985
+ function sparkle
3986
+ ```
3987
+
3988
+ - **Use when:** add glints to bright highlights
3989
+ - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
3990
+
3991
+ ```ts
3992
+ sparkle(...)
3993
+ ```
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
+
4093
+ ## `@threenative/ui`
4094
+
4095
+ ### `DebugOverlay`
4096
+
4097
+ `function` — Show framework diagnostics while developing a game.
4098
+
4099
+ ```ts
4100
+ export function DebugOverlay() { … }
4101
+ ```
4102
+
4103
+ - **Use when:** display runtime and playtest diagnostics in a React HUD · inspect a game without changing its scene
4104
+
4105
+ ```ts
4106
+ <DebugOverlay />
4107
+ ```
4108
+
4109
+ ### `GameCanvas`
4110
+
4111
+ `function` — Mount a ThreeNative game in a React canvas.
4112
+
4113
+ ```ts
4114
+ export function GameCanvas<TState extends Record<string, unknown>, TPhysics>( { … }
4115
+ ```
4116
+
4117
+ - **Use when:** add a game viewport to a React application · connect a game canvas to the web UI shell
4118
+ - **Constraints:** keep the portable game entry free of React DOM code
4119
+
4120
+ ```ts
4121
+ <GameCanvas game={game} />
4122
+ ```
4123
+
4124
+ ### `UiLayer`
4125
+
4126
+ `function` — Render a game's UI so the same source runs on web and on every native target.
4127
+
4128
+ ```ts
4129
+ export function UiLayer( { … }
4130
+ ```
4131
+
4132
+ - **Use when:** write one HUD that looks the same on the web build and on a phone · mount a React UI over the game surface on Android or iOS
4133
+ - **Constraints:** mark every control the player touches with data-tn-interactive
4134
+
4135
+ ```ts
4136
+ <UiLayer><Hud /></UiLayer>
4137
+ ```
4138
+
4139
+ ### `useGameState`
4140
+
4141
+ `function` — Read throttled game state from React.
4142
+
4143
+ ```ts
4144
+ export function useGameState<TState extends Record<string, unknown>, TPhysics, TSelected>( game: IGame<TState, TPhysics>, selector: GameSelector<TState, TSelected>, ): TSelected;
4145
+ ```
4146
+
4147
+ - **Use when:** bind a HUD component to game state · select a slice of state for a React panel
4148
+ - **Constraints:** use this hook only from the web UI entry
4149
+
4150
+ ```ts
4151
+ const score = useGameState(game, (state) => state.score);
4152
+ ```
4153
+
4154
+ ### `useUiIntent`
4155
+
4156
+ `function` — Send a player action from the UI back to the game.
4157
+
4158
+ ```ts
4159
+ export function useUiIntent(): (intent: string, payload?: unknown) => void { … }
4160
+ ```
4161
+
4162
+ - **Use when:** wire a Restart button in a HUD to the running game · pause a game from a menu rendered over its surface
4163
+ - **Constraints:** the game decides what each intent name means; it may ignore one
4164
+
4165
+ ```ts
4166
+ const send = useUiIntent(); send("restart");
4167
+ ```
4168
+
4169
+ ### `useUiState`
4170
+
4171
+ `function` — Read the game's published state from a UI that may be in another process.
4172
+
4173
+ ```ts
4174
+ export function useUiState<TState extends object>(): TState | undefined;
4175
+ ```
4176
+
4177
+ - **Use when:** bind a HUD to game state on web and native alike · show score or health in a UI rendered over the game surface
4178
+ - **Constraints:** returns undefined until the game publishes its first state
4179
+
4180
+ ```ts
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
4216
+ ```
4217
+
4218
+ ## `three/addons/tsl/display/DenoiseNode.js`
4219
+
4220
+ ### `denoise`
4221
+
4222
+ `function` — ThreeNative equivalent for realism-effects denoise.
4223
+
4224
+ ```ts
4225
+ function denoise
4226
+ ```
4227
+
4228
+ - **Use when:** denoise a noisy screen-space pass
4229
+ - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
4230
+
4231
+ ```ts
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
4267
+ ```
4268
+
4269
+ ## `three/addons/tsl/display/MotionBlur.js`
4270
+
4271
+ ### `motionBlur`
4272
+
4273
+ `function` — ThreeNative equivalent for realism-effects motionBlur.
4274
+
4275
+ ```ts
4276
+ function motionBlur
4277
+ ```
4278
+
4279
+ - **Use when:** blur motion using a velocity buffer
4280
+ - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
4281
+
4282
+ ```ts
4283
+ motionBlur(...)
4284
+ ```
4285
+
4286
+ ## `three/addons/tsl/display/RecurrentDenoiseNode.js`
4287
+
4288
+ ### `recurrentDenoise`
4289
+
4290
+ `function` — ThreeNative equivalent for realism-effects recurrentDenoise.
4291
+
4292
+ ```ts
4293
+ function recurrentDenoise
4294
+ ```
4295
+
4296
+ - **Use when:** denoise a noisy screen-space pass
4297
+ - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
4298
+
4299
+ ```ts
4300
+ recurrentDenoise(...)
4301
+ ```
4302
+
4303
+ ## `three/addons/tsl/display/SharpenNode.js`
4304
+
4305
+ ### `sharpen`
4306
+
4307
+ `function` — ThreeNative equivalent for realism-effects sharpen.
4308
+
4309
+ ```ts
4310
+ function sharpen
4311
+ ```
4312
+
4313
+ - **Use when:** make the image sharper
4314
+ - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
4315
+
4316
+ ```ts
4317
+ sharpen(...)
4318
+ ```
4319
+
4320
+ ## `three/addons/tsl/display/SSAAPassNode.js`
4321
+
4322
+ ### `ssaaPass`
4323
+
4324
+ `function` — ThreeNative equivalent for realism-effects ssaaPass.
4325
+
4326
+ ```ts
4327
+ function ssaaPass
4328
+ ```
4329
+
4330
+ - **Use when:** anti-alias still and moving scenes
4331
+ - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
4332
+
4333
+ ```ts
4334
+ ssaaPass(...)
4335
+ ```
4336
+
4337
+ ## `three/addons/tsl/display/SSGINode.js`
4338
+
4339
+ ### `ssgi`
4340
+
4341
+ `function` — ThreeNative equivalent for realism-effects ssgi.
4342
+
4343
+ ```ts
4344
+ function ssgi
4345
+ ```
4346
+
4347
+ - **Use when:** add screen-space global illumination
4348
+ - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
4349
+
4350
+ ```ts
4351
+ ssgi(...)
4352
+ ```
4353
+
4354
+ ## `three/addons/tsl/display/SSRNode.js`
4355
+
4356
+ ### `ssr`
4357
+
4358
+ `function` — ThreeNative equivalent for realism-effects ssr.
4359
+
4360
+ ```ts
4361
+ function ssr
4362
+ ```
4363
+
4364
+ - **Use when:** add screen-space reflections
4365
+ - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
4366
+
4367
+ ```ts
4368
+ ssr(...)
4369
+ ```
4370
+
4371
+ ## `three/addons/tsl/display/TemporalReprojectNode.js`
4372
+
4373
+ ### `temporalReproject`
4374
+
4375
+ `function` — ThreeNative equivalent for realism-effects temporalReproject.
4376
+
4377
+ ```ts
4378
+ function temporalReproject
4379
+ ```
4380
+
4381
+ - **Use when:** reproject a temporal history
4382
+ - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
4383
+
4384
+ ```ts
4385
+ temporalReproject(...)
4386
+ ```
4387
+
4388
+ ## `three/addons/tsl/display/TRAANode.js`
4389
+
4390
+ ### `traa`
4391
+
4392
+ `function` — ThreeNative equivalent for realism-effects traa.
4393
+
4394
+ ```ts
4395
+ function traa
4396
+ ```
4397
+
4398
+ - **Use when:** temporally resolve a moving image
4399
+ - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
4400
+
4401
+ ```ts
4402
+ traa(...)
4403
+ ```
4404
+
4405
+ ## `three/tsl`
4406
+
4407
+ ### `depth`
4408
+
4409
+ `function` — ThreeNative equivalent for realism-effects depth.
4410
+
4411
+ ```ts
4412
+ function depth
4413
+ ```
4414
+
4415
+ - **Use when:** provide depth to screen-space effects
4416
+ - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
4417
+
4418
+ ```ts
4419
+ depth(...)
4420
+ ```
4421
+
4422
+ ### `mrt`
4423
+
4424
+ `function` — ThreeNative equivalent for realism-effects mrt.
4425
+
4426
+ ```ts
4427
+ function mrt
4428
+ ```
4429
+
4430
+ - **Use when:** provision velocity, normal, and depth render targets
4431
+ - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
4432
+
4433
+ ```ts
4434
+ mrt(...)
4435
+ ```
4436
+
4437
+ ### `normalView`
4438
+
4439
+ `function` — ThreeNative equivalent for realism-effects normalView.
4440
+
4441
+ ```ts
4442
+ function normalView
4443
+ ```
4444
+
4445
+ - **Use when:** provide normals to screen-space effects
4446
+ - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
4447
+
4448
+ ```ts
4449
+ normalView(...)
4450
+ ```
4451
+
4452
+ ### `velocity`
4453
+
4454
+ `function` — ThreeNative equivalent for realism-effects velocity.
4455
+
4456
+ ```ts
4457
+ function velocity
4458
+ ```
4459
+
4460
+ - **Use when:** provide motion vectors to temporal effects
4461
+ - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
4462
+
4463
+ ```ts
4464
+ velocity(...)
4465
+ ```
4466
+
4467
+ ## `three/webgpu`
4468
+
4469
+ ### `VelocityNode`
4470
+
4471
+ `class` — ThreeNative equivalent for realism-effects VelocityNode.
4472
+
4473
+ ```ts
4474
+ class VelocityNode
4475
+ ```
4476
+
4477
+ - **Use when:** provide motion vectors to temporal effects
4478
+ - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
4479
+
4480
+ ```ts
4481
+ VelocityNode(...)
4482
+ ```
4483
+