create-threenative 0.2.2 → 0.2.3

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 (343) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +10 -2
  3. package/agent-docs/asset-mcp-loop.md +33 -0
  4. package/agent-docs/ctx-surface.md +69 -0
  5. package/agent-docs/engine-capabilities.md +4 -0
  6. package/agent-docs/framework-blocks-you.md +60 -0
  7. package/agent-docs/look-at-it-and-budget-the-look.md +27 -0
  8. package/agent-docs/performance-default.md +42 -0
  9. package/agent-docs/pixel-budget.md +20 -0
  10. package/agent-docs/playtest-fail-closed.md +23 -0
  11. package/agent-docs/references/assertion-reference.md +652 -0
  12. package/agent-docs/references/capability-reference.md +3279 -0
  13. package/agent-docs/references/capture-the-frame.md +53 -0
  14. package/agent-docs/references/ctx-cookbook.md +51 -0
  15. package/agent-docs/references/debug-surface.md +63 -0
  16. package/agent-docs/references/finding-assets.md +147 -0
  17. package/agent-docs/references/gameplay-recipes.md +54 -0
  18. package/agent-docs/references/menu-screens.md +69 -0
  19. package/agent-docs/references/mobile-memory-budget.md +87 -0
  20. package/agent-docs/references/sculpt-from-a-reference.md +39 -0
  21. package/agent-docs/references/visual-baseline.md +133 -0
  22. package/agent-docs/references/webview-ui.md +113 -0
  23. package/agent-docs/sculpt-loop.md +16 -0
  24. package/agent-files/.agents/skills/threenative-builder/SKILL.md +7 -0
  25. package/agent-files/.agents/skills/threenative-verifier/SKILL.md +7 -0
  26. package/agent-files/.claude/agents/threenative-builder.md +7 -0
  27. package/agent-files/.claude/agents/threenative-verifier.md +7 -0
  28. package/agent-files/.threenative/agents/builder.md +32 -0
  29. package/agent-files/.threenative/agents/verifier.md +31 -0
  30. package/agent-files/AGENT-ROLES.md +26 -0
  31. package/capabilities.json +3542 -0
  32. package/dist/index.d.ts +191 -3
  33. package/dist/index.js +1707 -73
  34. package/dist/threenative.d.ts +9 -2
  35. package/dist/threenative.js +1825 -148
  36. package/package.json +30 -6
  37. package/template-assets/loading.ts +315 -0
  38. package/template-assets/patches/three@0.185.1.patch +287 -0
  39. package/templates/action-rpg/.codex/config.toml +15 -0
  40. package/templates/action-rpg/.mcp.json +6 -2
  41. package/templates/action-rpg/AGENTS.md +370 -6
  42. package/templates/action-rpg/CLAUDE.md +370 -6
  43. package/templates/action-rpg/index.html +0 -1
  44. package/templates/action-rpg/package.json +15 -11
  45. package/templates/action-rpg/playtests/combat.playtest.json +23 -9
  46. package/templates/action-rpg/playtests/fail.playtest.json +3 -3
  47. package/templates/action-rpg/playtests/inventory.playtest.json +16 -10
  48. package/templates/action-rpg/playtests/performance.playtest.json +22 -0
  49. package/templates/action-rpg/playtests/progress.playtest.json +18 -13
  50. package/templates/action-rpg/playtests/win.playtest.json +10 -4
  51. package/templates/action-rpg/public/icon.png +0 -0
  52. package/templates/action-rpg/src/entities/Enemy.ts +14 -4
  53. package/templates/action-rpg/src/game.ts +21 -0
  54. package/templates/action-rpg/src/render/lighting.ts +6 -1
  55. package/templates/action-rpg/src/render/loading.ts +267 -42
  56. package/templates/action-rpg/src/render/postprocessing.ts +68 -15
  57. package/templates/action-rpg/src/render/worldEnvironment.ts +583 -0
  58. package/templates/action-rpg/src/scenes/Play.ts +49 -19
  59. package/templates/action-rpg/src/state.ts +4 -0
  60. package/templates/action-rpg/src/style.css +45 -1
  61. package/templates/action-rpg/src/ui/AbilityBar.tsx +9 -7
  62. package/templates/action-rpg/src/ui/App.tsx +9 -8
  63. package/templates/action-rpg/src/ui/CharacterPanel.tsx +10 -8
  64. package/templates/action-rpg/src/ui/GameUi.tsx +24 -0
  65. package/templates/action-rpg/src/ui/Hud.tsx +10 -8
  66. package/templates/action-rpg/src/ui/InventoryPanel.tsx +9 -7
  67. package/templates/action-rpg/src/ui/main.tsx +14 -0
  68. package/templates/action-rpg/threenative.config.ts +21 -8
  69. package/templates/action-rpg/vite.config.ts +32 -2
  70. package/templates/defense/.codex/config.toml +15 -0
  71. package/templates/defense/.mcp.json +6 -2
  72. package/templates/defense/AGENTS.md +371 -8
  73. package/templates/defense/CLAUDE.md +371 -8
  74. package/templates/defense/README.md +2 -1
  75. package/templates/defense/index.html +0 -1
  76. package/templates/defense/package.json +16 -12
  77. package/templates/defense/playtests/leak.playtest.json +9 -4
  78. package/templates/defense/playtests/performance.playtest.json +22 -0
  79. package/templates/defense/playtests/placement.playtest.json +5 -5
  80. package/templates/defense/playtests/pointer-placement.playtest.json +89 -0
  81. package/templates/defense/playtests/scan.playtest.json +3 -3
  82. package/templates/defense/playtests/survive.playtest.json +11 -6
  83. package/templates/defense/public/icon.png +0 -0
  84. package/templates/defense/src/attackers/Attacker.ts +28 -12
  85. package/templates/defense/src/game.ts +24 -2
  86. package/templates/defense/src/render/lighting.ts +6 -1
  87. package/templates/defense/src/render/loading.ts +263 -37
  88. package/templates/defense/src/render/postprocessing.ts +70 -13
  89. package/templates/defense/src/render/shapes.ts +38 -0
  90. package/templates/defense/src/render/worldEnvironment.ts +583 -0
  91. package/templates/defense/src/scenes/Defense.ts +109 -50
  92. package/templates/defense/src/state.ts +6 -0
  93. package/templates/defense/src/style.css +45 -1
  94. package/templates/defense/src/ui/App.tsx +9 -4
  95. package/templates/defense/src/ui/GameUi.tsx +20 -0
  96. package/templates/defense/src/ui/Hud.tsx +6 -5
  97. package/templates/defense/src/ui/main.tsx +14 -0
  98. package/templates/defense/threenative.config.ts +21 -8
  99. package/templates/defense/vite.config.ts +34 -1
  100. package/templates/minimal/.codex/config.toml +15 -0
  101. package/templates/minimal/.mcp.json +6 -2
  102. package/templates/minimal/AGENTS.md +360 -255
  103. package/templates/minimal/CLAUDE.md +360 -255
  104. package/templates/minimal/index.html +0 -1
  105. package/templates/minimal/package.json +14 -11
  106. package/templates/minimal/playtests/atmosphere.playtest.json +32 -0
  107. package/templates/minimal/playtests/play.playtest.json +17 -5
  108. package/templates/minimal/public/icon.png +0 -0
  109. package/templates/minimal/src/game.ts +1 -0
  110. package/templates/minimal/src/render/camera.ts +1 -1
  111. package/templates/minimal/src/render/hud.ts +24 -8
  112. package/templates/minimal/src/render/lighting.ts +23 -2
  113. package/templates/minimal/src/render/loading.ts +23 -103
  114. package/templates/minimal/src/render/postprocessing.ts +92 -14
  115. package/templates/minimal/src/render/sky.ts +37 -32
  116. package/templates/minimal/src/render/worldEnvironment.ts +583 -0
  117. package/templates/minimal/src/scenes/Play.ts +91 -13
  118. package/templates/minimal/src/state.ts +8 -1
  119. package/templates/minimal/threenative.config.ts +15 -10
  120. package/templates/minimal/vite.config.ts +28 -1
  121. package/templates/platformer/.codex/config.toml +15 -0
  122. package/templates/platformer/.mcp.json +6 -2
  123. package/templates/platformer/AGENTS.md +385 -130
  124. package/templates/platformer/CLAUDE.md +385 -130
  125. package/templates/platformer/index.html +0 -1
  126. package/templates/platformer/package.json +17 -14
  127. package/templates/platformer/playtests/avoidance.playtest.json +6 -1
  128. package/templates/platformer/playtests/branding.playtest.json +29 -0
  129. package/templates/platformer/playtests/buffer.playtest.json +1 -1
  130. package/templates/platformer/playtests/collect.playtest.json +1 -1
  131. package/templates/platformer/playtests/collision-layers.playtest.json +2 -2
  132. package/templates/platformer/playtests/coyote.playtest.json +42 -8
  133. package/templates/platformer/playtests/damage.playtest.json +4 -1
  134. package/templates/platformer/playtests/dash.playtest.json +2 -2
  135. package/templates/platformer/playtests/jump.playtest.json +2 -3
  136. package/templates/platformer/playtests/native/touch-controls.playtest.json +33 -0
  137. package/templates/platformer/playtests/oneway.playtest.json +1 -1
  138. package/templates/platformer/playtests/performance.playtest.json +6 -5
  139. package/templates/platformer/playtests/respawn.playtest.json +2 -2
  140. package/templates/platformer/playtests/stomp-rise.playtest.json +17 -3
  141. package/templates/platformer/playtests/stomp.playtest.json +11 -3
  142. package/templates/platformer/playtests/terminal-loop-fail.playtest.json +13 -4
  143. package/templates/platformer/playtests/terminal-loop-win.playtest.json +3 -3
  144. package/templates/platformer/playtests/touch-controls-web.playtest.json +46 -0
  145. package/templates/platformer/public/icon.png +0 -0
  146. package/templates/platformer/src/entities/Character.ts +16 -10
  147. package/templates/platformer/src/entities/Patrol.ts +5 -0
  148. package/templates/platformer/src/game.ts +24 -1
  149. package/templates/platformer/src/render/lighting.ts +6 -1
  150. package/templates/platformer/src/render/loading.ts +270 -61
  151. package/templates/platformer/src/render/postprocessing.ts +68 -15
  152. package/templates/platformer/src/render/touch-controls.ts +54 -36
  153. package/templates/platformer/src/render/worldEnvironment.ts +583 -0
  154. package/templates/platformer/src/scenes/Level.ts +47 -22
  155. package/templates/platformer/src/state.ts +4 -0
  156. package/templates/platformer/src/style.css +45 -1
  157. package/templates/platformer/src/ui/App.tsx +9 -4
  158. package/templates/platformer/src/ui/GameUi.tsx +20 -0
  159. package/templates/platformer/src/ui/Hud.tsx +6 -5
  160. package/templates/platformer/src/ui/main.tsx +14 -0
  161. package/templates/platformer/threenative.config.ts +20 -10
  162. package/templates/platformer/vite.config.ts +34 -1
  163. package/templates/racing/.codex/config.toml +15 -0
  164. package/templates/racing/.mcp.json +6 -2
  165. package/templates/racing/AGENTS.md +370 -6
  166. package/templates/racing/CLAUDE.md +370 -6
  167. package/templates/racing/index.html +0 -1
  168. package/templates/racing/package.json +16 -12
  169. package/templates/racing/playtests/boost.playtest.json +5 -5
  170. package/templates/racing/playtests/outcome.playtest.json +14 -4
  171. package/templates/racing/playtests/performance.playtest.json +22 -0
  172. package/templates/racing/playtests/ranking.playtest.json +2 -2
  173. package/templates/racing/playtests/rescue.playtest.json +12 -6
  174. package/templates/racing/playtests/reverse.playtest.json +3 -3
  175. package/templates/racing/playtests/shortcut.playtest.json +3 -3
  176. package/templates/racing/public/icon.png +0 -0
  177. package/templates/racing/src/game.ts +24 -1
  178. package/templates/racing/src/render/camera.ts +10 -6
  179. package/templates/racing/src/render/lighting.ts +6 -1
  180. package/templates/racing/src/render/loading.ts +291 -34
  181. package/templates/racing/src/render/postprocessing.ts +70 -13
  182. package/templates/racing/src/render/worldEnvironment.ts +583 -0
  183. package/templates/racing/src/scenes/Race.ts +68 -36
  184. package/templates/racing/src/state.ts +4 -0
  185. package/templates/racing/src/style.css +45 -1
  186. package/templates/racing/src/track/Lap.ts +20 -9
  187. package/templates/racing/src/track/Ranking.ts +53 -14
  188. package/templates/racing/src/track/Track.ts +29 -16
  189. package/templates/racing/src/track/TrackSector.ts +14 -4
  190. package/templates/racing/src/ui/App.tsx +9 -4
  191. package/templates/racing/src/ui/GameUi.tsx +20 -0
  192. package/templates/racing/src/ui/Hud.tsx +6 -5
  193. package/templates/racing/src/ui/main.tsx +14 -0
  194. package/templates/racing/threenative.config.ts +21 -8
  195. package/templates/racing/vite.config.ts +34 -1
  196. package/templates/sailing/.codex/config.toml +15 -0
  197. package/templates/sailing/.mcp.json +20 -0
  198. package/templates/sailing/AGENTS.md +388 -0
  199. package/templates/sailing/CLAUDE.md +390 -0
  200. package/templates/sailing/README.md +25 -0
  201. package/templates/sailing/index.html +12 -0
  202. package/templates/sailing/kit.json +7 -0
  203. package/templates/sailing/native-playtests/survives.playtest.json +21 -0
  204. package/templates/sailing/package.json +52 -0
  205. package/templates/sailing/playtests/fail.playtest.json +24 -0
  206. package/templates/sailing/playtests/performance.playtest.json +21 -0
  207. package/templates/sailing/playtests/survives.playtest.json +38 -0
  208. package/templates/sailing/playtests/win.playtest.json +31 -0
  209. package/templates/sailing/public/favicon.svg +5 -0
  210. package/templates/sailing/public/icon.png +0 -0
  211. package/templates/sailing/src/entities/Ship.ts +96 -0
  212. package/templates/sailing/src/game.ts +40 -0
  213. package/templates/sailing/src/main.ts +15 -0
  214. package/templates/sailing/src/render/camera.ts +21 -0
  215. package/templates/sailing/src/render/lighting.ts +36 -0
  216. package/templates/sailing/src/render/loading.ts +315 -0
  217. package/templates/sailing/src/render/materials.ts +28 -0
  218. package/templates/sailing/src/render/palette.ts +24 -0
  219. package/templates/sailing/src/render/postprocessing.ts +33 -0
  220. package/templates/sailing/src/render/props.ts +52 -0
  221. package/templates/sailing/src/render/sky.ts +32 -0
  222. package/templates/sailing/src/render/water-material.ts +14 -0
  223. package/templates/sailing/src/render/water-shaders.ts +12 -0
  224. package/templates/sailing/src/render/wave-nodes.ts +10 -0
  225. package/templates/sailing/src/render/worldEnvironment.ts +590 -0
  226. package/templates/sailing/src/scenes/Boot.ts +12 -0
  227. package/templates/sailing/src/scenes/Sailing.ts +106 -0
  228. package/templates/sailing/src/state.ts +10 -0
  229. package/templates/sailing/src/style.css +61 -0
  230. package/templates/sailing/src/ui/App.tsx +15 -0
  231. package/templates/sailing/src/ui/GameUi.tsx +12 -0
  232. package/templates/sailing/src/ui/Hud.tsx +55 -0
  233. package/templates/sailing/src/ui/Menu.tsx +30 -0
  234. package/templates/sailing/src/ui/main.tsx +7 -0
  235. package/templates/sailing/tailwind.config.ts +2 -0
  236. package/templates/sailing/threenative.config.ts +34 -0
  237. package/templates/sailing/tsconfig.json +17 -0
  238. package/templates/sailing/vite.config.ts +34 -0
  239. package/templates/shooter/.codex/config.toml +15 -0
  240. package/templates/shooter/.mcp.json +6 -2
  241. package/templates/shooter/AGENTS.md +373 -7
  242. package/templates/shooter/CLAUDE.md +373 -7
  243. package/templates/shooter/index.html +0 -1
  244. package/templates/shooter/package.json +16 -11
  245. package/templates/shooter/playtests/fail.playtest.json +5 -4
  246. package/templates/shooter/playtests/input-control.playtest.json +131 -0
  247. package/templates/shooter/playtests/per-item.playtest.json +59 -0
  248. package/templates/shooter/playtests/performance.playtest.json +22 -0
  249. package/templates/shooter/playtests/shooter.playtest.json +22 -18
  250. package/templates/shooter/playtests/survives.playtest.json +1 -1
  251. package/templates/shooter/public/favicon.svg +1 -1
  252. package/templates/shooter/public/icon.png +0 -0
  253. package/templates/shooter/src/game.ts +24 -1
  254. package/templates/shooter/src/main.ts +3 -13
  255. package/templates/shooter/src/render/camera.ts +62 -12
  256. package/templates/shooter/src/render/lighting.ts +6 -1
  257. package/templates/shooter/src/render/loading.ts +262 -33
  258. package/templates/shooter/src/render/palette.ts +1 -1
  259. package/templates/shooter/src/render/postprocessing.ts +68 -16
  260. package/templates/shooter/src/render/shapes.ts +178 -0
  261. package/templates/shooter/src/render/ui.css +34 -1
  262. package/templates/shooter/src/render/worldEnvironment.ts +583 -0
  263. package/templates/shooter/src/scenes/Play.ts +246 -73
  264. package/templates/shooter/src/state.ts +13 -0
  265. package/templates/shooter/src/style.css +26 -0
  266. package/templates/shooter/src/ui/App.tsx +10 -12
  267. package/templates/shooter/src/ui/GameUi.tsx +20 -0
  268. package/templates/shooter/src/ui/Hud.tsx +8 -10
  269. package/templates/shooter/src/ui/Menu.tsx +24 -9
  270. package/templates/shooter/src/ui/main.tsx +15 -0
  271. package/templates/shooter/src/weapons/Projectile.ts +21 -10
  272. package/templates/shooter/threenative.config.ts +21 -8
  273. package/templates/shooter/vite.config.ts +32 -2
  274. package/templates/starter/.codex/config.toml +15 -0
  275. package/templates/starter/.mcp.json +6 -2
  276. package/templates/starter/AGENTS.md +429 -326
  277. package/templates/starter/CLAUDE.md +429 -326
  278. package/templates/starter/assets/pickup.wav +0 -0
  279. package/templates/starter/gitignore +4 -0
  280. package/templates/starter/index.html +0 -1
  281. package/templates/starter/native-playtests/react-hud.playtest.json +20 -0
  282. package/templates/starter/native-playtests/render-chain.playtest.json +12 -0
  283. package/templates/starter/package.json +16 -12
  284. package/templates/starter/playtests/assets.playtest.json +65 -0
  285. package/templates/starter/playtests/buffer.playtest.json +59 -9
  286. package/templates/starter/playtests/cloth.playtest.json +113 -0
  287. package/templates/starter/playtests/coyote.playtest.json +60 -8
  288. package/templates/starter/playtests/forward.playtest.json +29 -4
  289. package/templates/starter/playtests/gameover.playtest.json +66 -0
  290. package/templates/starter/playtests/goal.playtest.json +67 -0
  291. package/templates/starter/playtests/hot-reload.playtest.json +48 -8
  292. package/templates/starter/playtests/look.playtest.json +34 -6
  293. package/templates/starter/playtests/models-baseline.png +0 -0
  294. package/templates/starter/playtests/models.playtest.json +74 -0
  295. package/templates/starter/playtests/monitoring.playtest.json +38 -7
  296. package/templates/starter/playtests/odometer.playtest.json +54 -0
  297. package/templates/starter/playtests/pause.playtest.json +27 -4
  298. package/templates/starter/playtests/play.playtest.json +43 -7
  299. package/templates/starter/playtests/respawn.playtest.json +46 -6
  300. package/templates/starter/playtests/restart.playtest.json +65 -10
  301. package/templates/starter/playtests/seed.playtest.json +44 -8
  302. package/templates/starter/playtests/survives.playtest.json +27 -4
  303. package/templates/starter/playtests/textures-baseline.png +0 -0
  304. package/templates/starter/playtests/textures.playtest.json +74 -0
  305. package/templates/starter/playtests/zoom-pinch.playtest.json +86 -0
  306. package/templates/starter/playtests/zoom-wheel.playtest.json +59 -0
  307. package/templates/starter/public/icon.png +0 -0
  308. package/templates/starter/src/entities/Goal.ts +122 -0
  309. package/templates/starter/src/entities/Player.ts +40 -2
  310. package/templates/starter/src/game.ts +25 -0
  311. package/templates/starter/src/render/camera.ts +31 -5
  312. package/templates/starter/src/render/easing.ts +5 -0
  313. package/templates/starter/src/render/effects/gradualBackground.ts +48 -0
  314. package/templates/starter/src/render/effects/lensDistortion.ts +43 -0
  315. package/templates/starter/src/render/effects/sparkle.ts +49 -0
  316. package/templates/starter/src/render/lighting.ts +6 -1
  317. package/templates/starter/src/render/loading.ts +315 -0
  318. package/templates/starter/src/render/materials.ts +17 -1
  319. package/templates/starter/src/render/pennant.ts +54 -0
  320. package/templates/starter/src/render/postprocessing.ts +46 -15
  321. package/templates/starter/src/render/scenery.ts +83 -0
  322. package/templates/starter/src/render/shapes.ts +9 -21
  323. package/templates/starter/src/render/worldEnvironment.ts +583 -0
  324. package/templates/starter/src/scenes/Play.ts +146 -36
  325. package/templates/starter/src/state.ts +12 -0
  326. package/templates/starter/src/style.css +45 -1
  327. package/templates/starter/src/ui/App.tsx +9 -6
  328. package/templates/starter/src/ui/GameUi.tsx +20 -0
  329. package/templates/starter/src/ui/Hud.tsx +52 -29
  330. package/templates/starter/src/ui/Menu.tsx +25 -23
  331. package/templates/starter/src/ui/main.tsx +14 -0
  332. package/templates/starter/threenative.config.ts +27 -9
  333. package/templates/starter/tools/look.mjs +109 -0
  334. package/templates/starter/vite.config.ts +32 -2
  335. package/templates/minimal/assets/.gitkeep +0 -0
  336. package/templates/minimal/public/.gitkeep +0 -0
  337. package/templates/platformer/assets/.gitkeep +0 -0
  338. package/templates/platformer/public/.gitkeep +0 -0
  339. package/templates/starter/assets/.gitkeep +0 -0
  340. package/templates/starter/public/.gitkeep +0 -0
  341. package/templates/starter/public/pickup.ogg +0 -0
  342. /package/templates/starter/{public → assets}/native-proof.glb +0 -0
  343. /package/templates/starter/{public → assets}/native-proof.png +0 -0
@@ -0,0 +1,3279 @@
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 of `@threenative/core` and `@threenative/physics`,
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/core`
12
+
13
+ ### `AnimationPlayer`
14
+
15
+ `class` — Play a skinned or sprite animation from game code. A travelling clip's playback rate is matched to the ground the body actually covers, so feet do not skate or spin — on by default, `strideSync: false` to keep the authored rate, and `player.stride` reports the measurement either way. Name the body a game moves as `strideRoot` when the rig is a child of it.
16
+
17
+ ```ts
18
+ export class AnimationPlayer { … }
19
+ ```
20
+
21
+ - **Use when:** play an animation on a character · switch a character between idle and attack clips · stop a walking character's feet from sliding or spinning · match a walk or run cycle to how fast a character is moving
22
+ - **Constraints:** name the body a game moves as strideRoot when the animated rig is a child of it · a one-shot clip always plays at its authored rate; the matched rate re-times loops only
23
+ - **Overrides:** strideSync controls whether the matched rate is applied while stride is still measured
24
+
25
+ ```ts
26
+ const player = new AnimationPlayer({ clips, root: rig, strideRoot: body });
27
+ ```
28
+
29
+ ### `Atmosphere`
30
+
31
+ `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.
32
+
33
+ ```ts
34
+ export class Atmosphere extends Group implements IComputeDriven { … }
35
+ ```
36
+
37
+ - **Use when:** render a sunrise that changes as time and place change · add distance haze from the depth of a scene pass
38
+ - **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
39
+
40
+ ```ts
41
+ const atmosphere = new Atmosphere({ rayleigh, mie, ozone, planetRadius, atmosphereRadius });
42
+ ctx.add(atmosphere);
43
+ ```
44
+
45
+ ### `AtmosphereLuts`
46
+
47
+ `class` — Own the transmittance, multi-scattering, and sky-view compute lookup textures.
48
+
49
+ ```ts
50
+ export class AtmosphereLuts { … }
51
+ ```
52
+
53
+ - **Use when:** bake the three atmosphere LUTs once before a game shows its world
54
+ - **Constraints:** supply all physical parameters; this class creates no scene appearance
55
+
56
+ ```ts
57
+ const luts = new AtmosphereLuts({ rayleigh, mie, ozone, planetRadius, atmosphereRadius });
58
+ ```
59
+
60
+ ### `attachToBone`
61
+
62
+ `function` — Attach a game-owned object to a named skeleton bone.
63
+
64
+ ```ts
65
+ export function attachToBone(root: Object3D, boneName: string, child: Object3D): Object3D { … }
66
+ ```
67
+
68
+ - **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
69
+ - **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
70
+
71
+ ```ts
72
+ import { attachToBone } from "@threenative/core";
73
+ attachToBone(character, "RightHand", rifle);
74
+ ```
75
+
76
+ ### `AudioBus`
77
+
78
+ `class` — Route effects through a named audio bus.
79
+
80
+ ```ts
81
+ export class AudioBus { … }
82
+ ```
83
+
84
+ - **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
85
+ - **Constraints:** create buses before playing clips and dispose them with the game · refDistance and rolloffFactor tune positional falloff and apply to playAt only
86
+ - **Supersedes (writing this fails `pnpm budgets`):** new Audio(
87
+
88
+ ```ts
89
+ const effects = new AudioBus({ camera });
90
+ ```
91
+
92
+ ### `Billboard3D`
93
+
94
+ `class` — Face a game-owned object toward a perspective or orthographic camera.
95
+
96
+ ```ts
97
+ export class Billboard3D { … }
98
+ ```
99
+
100
+ - **Use when:** keep a world-space marker or nameplate facing the camera · billboard a tree, label, or effect under a rotated parent
101
+ - **Constraints:** call update from the owning scene; no global scene scan is installed · orthographic cameras use their forward direction, and lockAxis restricts world rotation
102
+
103
+ ```ts
104
+ const billboard = new Billboard3D(label, { camera });
105
+ billboard.update();
106
+ ```
107
+
108
+ ### `CameraShake`
109
+
110
+ `class` — Produce a game-authored camera shake offset for a template-owned camera rig.
111
+
112
+ ```ts
113
+ export class CameraShake { … }
114
+ ```
115
+
116
+ - **Use when:** add a hit, explosion, or landing shake to a camera · compose a transient camera offset after camera damping
117
+ - **Constraints:** amplitude, rotationAmplitude, frequency, decay, and curve are required game choices · update returns an offset and never writes to a camera
118
+
119
+ ```ts
120
+ const shake = new CameraShake({ amplitude, rotationAmplitude, frequency, decay, curve });
121
+ ```
122
+
123
+ ### `CanvasLayer`
124
+
125
+ `class` — Manage a camera or screen-facing canvas layer.
126
+
127
+ ```ts
128
+ export class CanvasLayer { … }
129
+ ```
130
+
131
+ - **Use when:** place a HUD layer above the Three.js scene · attach a canvas layer to a camera
132
+
133
+ ```ts
134
+ const hud = new CanvasLayer({ camera });
135
+ ```
136
+
137
+ ### `ClusteredBatch`
138
+
139
+ `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.
140
+
141
+ ```ts
142
+ export class ClusteredBatch { … }
143
+ ```
144
+
145
+ - **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
146
+ - **Constraints:** the body's geometry must carry a cluster table from `assets.models.virtual` · every copy is placed before build(); place() after build() throws
147
+ - **Overrides:** distanceRatio sets how wide one distance group is, default 1.25 · errorPixels sets the screen-space error budget, default 1 pixel
148
+
149
+ ```ts
150
+ const boulders = new ClusteredBatch({ geometry, material, table });
151
+ boulders.place({ position: [x, y, z], rotation: [0, angle, 0] });
152
+ boulders.build({ name: "boulders", parent: ctx.scene });
153
+ // in the scene's update, before the render:
154
+ boulders.update(ctx.camera, ctx.renderer.domElement.height);
155
+ ```
156
+
157
+ ### `ClusteredMesh`
158
+
159
+ `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.
160
+
161
+ ```ts
162
+ export class ClusteredMesh extends Mesh { … }
163
+ ```
164
+
165
+ - **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
166
+ - **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
167
+ - **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
168
+
169
+ ```ts
170
+ // Nothing to call: the loader returns one of these and the engine cuts it every frame.
171
+ const face = await ctx.assets.model("quarry-face.glb");
172
+ ctx.scene.add(face.scene);
173
+ ```
174
+
175
+ ### `ComputeDrivenRegistry`
176
+
177
+ `class` — Register game-owned IComputeDriven objects with the shared compute lifetime.
178
+
179
+ ```ts
180
+ export class ComputeDrivenRegistry { … }
181
+ ```
182
+
183
+ - **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
184
+ - **Constraints:** add the object through ctx.add so it attaches, dispatches, and releases with its scene
185
+
186
+ ```ts
187
+ class Cloth extends Mesh implements IComputeDriven { ... }
188
+ ```
189
+
190
+ ### `createAssetLoader`
191
+
192
+ `function` — Create the portable asset loader a scene also receives as `ctx.assets`.
193
+
194
+ ```ts
195
+ export function createAssetLoader(options: IAssetLoaderOptions = { … }
196
+ ```
197
+
198
+ - **Use when:** preload models, textures, or audio before a scene enters · load assets from a nonstandard base path or a compiled asset manifest
199
+ - **Constraints:** reuse the loader handed to scenes as `ctx.assets` instead of building parallel caches
200
+
201
+ ```ts
202
+ const assets = createAssetLoader({ basePath: "/assets" });
203
+ const rock = await assets.texture("rock.png");
204
+ ```
205
+
206
+ ### `createRandom`
207
+
208
+ `function` — Create a deterministic random source for portable gameplay.
209
+
210
+ ```ts
211
+ export function createRandom(seed?: number): IRandom { … }
212
+ ```
213
+
214
+ - **Use when:** seed enemy patrol choices · reproduce the same procedural level in a playtest
215
+ - **Constraints:** use the returned source instead of Math.random for replayable behavior
216
+ - **Supersedes (writing this fails `pnpm budgets`):** Math.random(
217
+
218
+ ```ts
219
+ const random = createRandom(42);
220
+ ```
221
+
222
+ ### `createReplayDriver`
223
+
224
+ `function` — Record or replay deterministic game input and state.
225
+
226
+ ```ts
227
+ export function createReplayDriver( recording: Recording, target: EventTarget, pointerTarget = target, ) { … }
228
+ ```
229
+
230
+ - **Use when:** reproduce a gameplay bug from recorded input · run a deterministic replay in a playtest
231
+ - **Constraints:** use a seeded random source and fixed-step simulation for meaningful replays
232
+
233
+ ```ts
234
+ const driver = createReplayDriver({ recording });
235
+ ```
236
+
237
+ ### `defineGame`
238
+
239
+ `function` — Define the portable game entry shared by web and native.
240
+
241
+ ```ts
242
+ export function defineGame<TState extends Record<string, unknown>, TPhysics = undefined>( config: IGameConfig<TState, TPhysics>, ): IGame<TState, TPhysics> { … }
243
+ ```
244
+
245
+ - **Use when:** start a ThreeNative game from src/game.ts · register physics and gameplay plugins · let the player zoom the camera with a wheel, pinch, or gamepad axis
246
+ - **Constraints:** keep DOM and React mounting in src/main.ts · bind scroll or pinch and read the intent with ctx.input.axis(name); do not add a window wheel listener · scroll: true uses the DOM wheel sign on browser and native: negative deltaY toward the user is positive intent
247
+
248
+ ```ts
249
+ const game = defineGame({ input: { zoom: { scroll: true, pinch: true } }, scenes: { Play } });
250
+ ```
251
+
252
+ ### `directionalTransmittance`
253
+
254
+ `function` — Approximate direct transmittance for a ray leaving the game surface.
255
+
256
+ ```ts
257
+ export function directionalTransmittance( parameters: IAtmosphereParameters | IResolvedAtmosphereParameters, direction: Vector3, ): Vector3 { … }
258
+ ```
259
+
260
+ - **Use when:** colour a game-owned sun from atmosphere extinction
261
+ - **Constraints:** pass a non-zero direction; coefficients and radii come from the game
262
+
263
+ ```ts
264
+ const transmittance = directionalTransmittance(parameters, sunDirection);
265
+ ```
266
+
267
+ ### `directionFromSolarPosition`
268
+
269
+ `function` — Convert solar elevation and azimuth degrees into a normalized Three.js direction.
270
+
271
+ ```ts
272
+ export function directionFromSolarPosition(elevation: number, azimuth: number): Vector3 { … }
273
+ ```
274
+
275
+ - **Use when:** aim a template's sun from solarPosition output
276
+ - **Constraints:** elevation and azimuth must be finite degrees
277
+
278
+ ```ts
279
+ const direction = directionFromSolarPosition(sun.elevation, sun.azimuth);
280
+ ```
281
+
282
+ ### `ensureVelocityOutput`
283
+
284
+ `function` — Provision screen-space motion data for temporal nodes and keep per-instance history at the frame boundary.
285
+
286
+ ```ts
287
+ export function ensureVelocityOutput(pass: IVelocityRenderPass): MRTNode { … }
288
+ ```
289
+
290
+ - **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
291
+ - **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
292
+
293
+ ```ts
294
+ const scenePass = pass(scene, camera);
295
+ ensureVelocityOutput(scenePass);
296
+ renderer.setOutputNode(scenePass);
297
+ const tracker = new VelocityTracker();
298
+ tracker.update(scene);
299
+ renderer.render(scene, camera);
300
+ tracker.commit(scene);
301
+ ```
302
+
303
+ ### `FluidField2D`
304
+
305
+ `class` — Simulate a deterministic 2D velocity-and-dye field on the GPU while exposing its data to game-owned rendering.
306
+
307
+ ```ts
308
+ export class FluidField2D extends Group { … }
309
+ ```
310
+
311
+ - **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
312
+ - **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
313
+ - **Overrides:** pressureIterations, viscosity, vorticity, and splatRadius tune the solver without changing its pass order
314
+
315
+ ```ts
316
+ const field = new FluidField2D({ resolution: 256, pressureIterations: 20 });
317
+ ctx.add(field);
318
+ field.splat({ x: 0.5, y: 0.5 }, { x: 0.2, y: 0 }, 1);
319
+ ```
320
+
321
+ ### `FrameBudget`
322
+
323
+ `class` — Read where the frame's milliseconds went, per presented frame, on any platform.
324
+
325
+ ```ts
326
+ export class FrameBudget { … }
327
+ ```
328
+
329
+ - **Use when:** find out why a game runs slowly on a phone · attribute a frame to present wait, simulation, three.js render, or overlay
330
+ - **Constraints:** on by default and printed as TN_FRAME_BUDGET; defineGame({ frameBudget: false }) silences the marker, not the measurement
331
+
332
+ ```ts
333
+ defineGame({ frameBudget: { reportEvery: 120 }, scenes: { Play } });
334
+ ```
335
+
336
+ ### `getPlatform`
337
+
338
+ `function` — Read the host platform without reaching for browser globals.
339
+
340
+ ```ts
341
+ export function getPlatform(): Readonly<IPlatformInfo> { … }
342
+ ```
343
+
344
+ - **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native
345
+ - **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
346
+
347
+ ```ts
348
+ if (isMobile()) showTouchControls();
349
+ ```
350
+
351
+ ### `GPUParticles3D`
352
+
353
+ `class` — Dispatch a game-owned particle surface and process function through a pooled system.
354
+
355
+ ```ts
356
+ export class GPUParticles3D extends Sprite implements IComputeDriven { … }
357
+ ```
358
+
359
+ - **Use when:** emit sparks, smoke, or other transient effects · update many small visual particles · emit cannon smoke and muzzle flash particles · fire a cannonball projectile with cannon smoke particles
360
+ - **Constraints:** geometry, color, and timing remain supplied by the game
361
+
362
+ ```ts
363
+ const particles = new GPUParticles3D(particleOptions);
364
+ ```
365
+
366
+ ### `GPUReadback`
367
+
368
+ `class` — Copy a GPU buffer back to the CPU on a throttle, and report how old each sample is.
369
+
370
+ ```ts
371
+ export class GPUReadback { … }
372
+ ```
373
+
374
+ - **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
375
+ - **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
376
+
377
+ ```ts
378
+ const heights = new GPUReadback({ attribute: field.value, everyFrames: 4 });
379
+ ```
380
+
381
+ ### `GPUSceneBVH`
382
+
383
+ `class` — Pack a selected static scene into TSL storage nodes for an upstream BVH ray query.
384
+
385
+ ```ts
386
+ export class GPUSceneBVH extends Group implements IComputeDriven { … }
387
+ ```
388
+
389
+ - **Use when:** trace thousands of scene rays inside a TSL kernel · build a contact-occlusion or visibility query over loaded meshes
390
+ - **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
391
+
392
+ ```ts
393
+ const bvh = ctx.add(new GPUSceneBVH(ctx.scene, { include: (object) => object.userData.traceable === true }));
394
+ ```
395
+
396
+ ### `GroundSnap`
397
+
398
+ `class` — Keep a rendered model's feet on a surface while preserving an auditable override.
399
+
400
+ ```ts
401
+ export class GroundSnap { … }
402
+ ```
403
+
404
+ - **Use when:** keep a character's feet on the floor · correct visual grounding after an animation update
405
+ - **Constraints:** import from `@threenative/core`; this moves the rendered model, not its physics collider
406
+ - **Overrides:** enabled controls whether correction is applied while clearance is still measured
407
+
408
+ ```ts
409
+ import { GroundSnap } from "@threenative/core";
410
+ const snap = new GroundSnap(character, { enabled: true });
411
+ ```
412
+
413
+ ### `InstancedBatch`
414
+
415
+ `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.
416
+
417
+ ```ts
418
+ export class InstancedBatch { … }
419
+ ```
420
+
421
+ - **Use when:** draw hundreds of repeated props without hundreds of draw calls · place repeated props when the count is not known until the layout has been walked · build a chain, railing, cable, or tie rod out of point-to-point segments
422
+ - **Constraints:** geometry and material are required and come from the game; the batch chooses neither · span stretches along +Y, so its geometry must be unit-height and centred on the origin · placing after build() throws, and build() returns undefined when nothing was placed
423
+ - **Overrides:** castShadow and receiveShadow pass through to the built mesh and default to Three.js's own false
424
+
425
+ ```ts
426
+ const curbs = new InstancedBatch({ geometry: new BoxGeometry(1, 1, 1), material });
427
+ curbs.place({ position: [x, 0.08, z], rotation: [0, angle, 0], scale: [length, 0.18, 0.42] });
428
+ curbs.build({ castShadow: true, name: "curbs", parent: ctx.scene });
429
+ ```
430
+
431
+ ### `isMobile`
432
+
433
+ `function` — Read the host platform without reaching for browser globals.
434
+
435
+ ```ts
436
+ export function isMobile(): boolean { … }
437
+ ```
438
+
439
+ - **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native
440
+ - **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
441
+
442
+ ```ts
443
+ if (isMobile()) showTouchControls();
444
+ ```
445
+
446
+ ### `isNative`
447
+
448
+ `function` — Read the host platform without reaching for browser globals.
449
+
450
+ ```ts
451
+ export function isNative(): boolean { … }
452
+ ```
453
+
454
+ - **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native
455
+ - **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
456
+
457
+ ```ts
458
+ if (isMobile()) showTouchControls();
459
+ ```
460
+
461
+ ### `isTouchscreenAvailable`
462
+
463
+ `function` — Read the host platform without reaching for browser globals.
464
+
465
+ ```ts
466
+ export function isTouchscreenAvailable(): boolean { … }
467
+ ```
468
+
469
+ - **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native
470
+ - **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
471
+
472
+ ```ts
473
+ if (isMobile()) showTouchControls();
474
+ ```
475
+
476
+ ### `isWeb`
477
+
478
+ `function` — Read the host platform without reaching for browser globals.
479
+
480
+ ```ts
481
+ export function isWeb(): boolean { … }
482
+ ```
483
+
484
+ - **Use when:** branch a portable game on web or native · choose touch controls for a mobile device · can I raytrace on native
485
+ - **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
486
+
487
+ ```ts
488
+ if (isMobile()) showTouchControls();
489
+ ```
490
+
491
+ ### `measureThreePose`
492
+
493
+ `function` — Measure a Three.js pose for grounded or attachment-aware checks.
494
+
495
+ ```ts
496
+ export function measureThreePose( object: Object3D, options: IMeasureThreePoseOptions = { … }
497
+ ```
498
+
499
+ - **Use when:** inspect a skinned model's posed bounds · verify a character's visual pose
500
+ - **Constraints:** precise per-vertex measurement is opt-in and not for frame loops
501
+
502
+ ```ts
503
+ const measurement = measureThreePose(model);
504
+ ```
505
+
506
+ ### `normaliseToMetres`
507
+
508
+ `function` — Scale an asset to a real-world measurement and return the applied factor.
509
+
510
+ ```ts
511
+ export function normaliseToMetres(object: Object3D, options: INormaliseToMetresOptions): number { … }
512
+ ```
513
+
514
+ - **Use when:** make a character exactly 1.8 metres tall · normalize a prop or weapon to a known longest axis
515
+ - **Constraints:** skinned height uses a crown bone; game-specific asset expectations stay in render code
516
+ - **Supersedes (writing this fails `pnpm budgets`):** new Box3().setFromObject(
517
+
518
+ ```ts
519
+ normaliseToMetres(character, { metres: 1.8, axis: "height" });
520
+ ```
521
+
522
+ ### `parseReplayRecording`
523
+
524
+ `function` — Validate and parse a replay recording file.
525
+
526
+ ```ts
527
+ export function parseReplayRecording(value: unknown): IReplayRecording { … }
528
+ ```
529
+
530
+ - **Use when:** validate a recording before replaying it in another host
531
+ - **Constraints:** recordings are version 1; the parser fails closed with TN_REPLAY_* codes
532
+
533
+ ```ts
534
+ const recording = parseReplayRecording(rawRecording);
535
+ ```
536
+
537
+ ### `PathFollow3D`
538
+
539
+ `class` — Move an object along a Three.js curve with Godot-style path following.
540
+
541
+ ```ts
542
+ export class PathFollow3D { … }
543
+ ```
544
+
545
+ - **Use when:** move an enemy or prop along a patrol path · sample a racing line from a curve
546
+
547
+ ```ts
548
+ const follower = new PathFollow3D(curve, { loop: true });
549
+ ```
550
+
551
+ ### `PointerEvents3D`
552
+
553
+ `class` — Dispatch portable pointer events from the game surface to registered Three.js objects.
554
+
555
+ ```ts
556
+ export class PointerEvents3D implements IPointerEvents3D { … }
557
+ ```
558
+
559
+ - **Use when:** let the player click on a thing in the world · show a 3D object while a pointer hovers over it · handle touch and mouse taps on a loaded model without naming its child meshes
560
+ - **Constraints:** listeners are side-table registrations; Three.js prototypes are never patched · one raycast serves each active pointer and no raycast runs when nothing is registered
561
+
562
+ ```ts
563
+ ctx.pointer.on(tile, "tapped", (event) => place(event.point));
564
+ ```
565
+
566
+ ### `posedBounds`
567
+
568
+ `function` — Measure a Three.js pose for grounded or attachment-aware checks.
569
+
570
+ ```ts
571
+ export function posedBounds(root: Object3D, meshes?: readonly Object3D[]): IThreePoseBounds { … }
572
+ ```
573
+
574
+ - **Use when:** inspect a skinned model's posed bounds · verify a character's visual pose
575
+ - **Constraints:** precise per-vertex measurement is opt-in and not for frame loops
576
+
577
+ ```ts
578
+ const measurement = measureThreePose(model);
579
+ ```
580
+
581
+ ### `prewarm`
582
+
583
+ `function` — Keep transient render surfaces in the renderer's pipeline cache before first use.
584
+
585
+ ```ts
586
+ export function prewarm(object: Object3D | readonly Object3D[]): void { … }
587
+ ```
588
+
589
+ - **Use when:** prewarm a projectile, tracer, particle, or other transient effect · avoid a long first-use frame for a newly visible effect
590
+ - **Constraints:** keep the surface visible with zero opacity; do not hide it with `visible = false`
591
+ - **Supersedes (writing this fails `pnpm budgets`):** .visible = false
592
+
593
+ ```ts
594
+ prewarm(tracerPool);
595
+ ```
596
+
597
+ ### `ProbeVolume`
598
+
599
+ `class` — Bake static diffuse irradiance that reaches surfaces from outside the camera view.
600
+
601
+ ```ts
602
+ export class ProbeVolume extends Object3D implements IComputeDriven { … }
603
+ ```
604
+
605
+ - **Use when:** light bouncing from a room I cannot see · light a wall with an off-screen emitter
606
+ - **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
607
+ - **Overrides:** density, bounds, bakeBudgetMs, and bounces are game-owned choices
608
+
609
+ ```ts
610
+ const probes = new ProbeVolume({ bounds, density: 0.5 }); ctx.add(probes); void probes.requestBake(scene);
611
+ ```
612
+
613
+ ### `readProbeVolumeObservation`
614
+
615
+ `function` — Bake static diffuse irradiance that reaches surfaces from outside the camera view.
616
+
617
+ ```ts
618
+ export function readProbeVolumeObservation(value: unknown): IProbeVolumeObservation | undefined { … }
619
+ ```
620
+
621
+ - **Use when:** light bouncing from a room I cannot see · light a wall with an off-screen emitter
622
+ - **Constraints:** request a bake after static geometry and lights are authored; this is static-lighting-first, not fully dynamic relighting · add the volume with ctx.add() so its incremental work is measured in the render phase · call sample() or sampleNode() from a game-owned material before screen-space GI; the volume owns no light, material, or colour
623
+ - **Overrides:** density, bounds, bakeBudgetMs, and bounces are game-owned choices
624
+
625
+ ```ts
626
+ const probes = new ProbeVolume({ bounds, density: 0.5 }); ctx.add(probes); void probes.requestBake(scene);
627
+ ```
628
+
629
+ ### `readRenderChainObservation`
630
+
631
+ `function` — Compose game-provided render nodes in a measured, fail-closed chain.
632
+
633
+ ```ts
634
+ export function readRenderChainObservation( renderer: unknown, ): IRenderChainMarker["applied"] | undefined { … }
635
+ ```
636
+
637
+ - **Use when:** compose screen-space effects in a canonical order · report which render tier and velocity route actually ran
638
+ - **Constraints:** stage factories own colour, strength, and all other appearance choices
639
+
640
+ ```ts
641
+ const chain = new RenderChain(renderer, { input: colour, stages, request: { stages: ["bloom"], tier: "auto" } });
642
+ ```
643
+
644
+ ### `readRenderChainReport`
645
+
646
+ `function` — Compose game-provided render nodes in a measured, fail-closed chain.
647
+
648
+ ```ts
649
+ export function readRenderChainReport(renderer: unknown): IRenderChainMarker | undefined { … }
650
+ ```
651
+
652
+ - **Use when:** compose screen-space effects in a canonical order · report which render tier and velocity route actually ran · expose the render tier and dropped-stage reasons to a playtest · inspect whether a temporal pass received velocity
653
+ - **Constraints:** stage factories own colour, strength, and all other appearance choices · an absent value means no chain was installed and must fail a chain assertion
654
+
655
+ ```ts
656
+ const chain = new RenderChain(renderer, { input: colour, stages, request: { stages: ["bloom"], tier: "auto" } });
657
+ ```
658
+
659
+ ### `readVelocityPreviousBoneMatrices`
660
+
661
+ `function` — Provision screen-space motion data for temporal nodes and keep per-instance history at the frame boundary.
662
+
663
+ ```ts
664
+ export function readVelocityPreviousBoneMatrices(object: Object3D): Float32Array | undefined { … }
665
+ ```
666
+
667
+ - **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
668
+ - **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
669
+
670
+ ```ts
671
+ const scenePass = pass(scene, camera);
672
+ ensureVelocityOutput(scenePass);
673
+ renderer.setOutputNode(scenePass);
674
+ const tracker = new VelocityTracker();
675
+ tracker.update(scene);
676
+ renderer.render(scene, camera);
677
+ tracker.commit(scene);
678
+ ```
679
+
680
+ ### `readVelocityPreviousMatrices`
681
+
682
+ `function` — Provision screen-space motion data for temporal nodes and keep per-instance history at the frame boundary.
683
+
684
+ ```ts
685
+ export function readVelocityPreviousMatrices(object: Object3D): Float32Array | undefined { … }
686
+ ```
687
+
688
+ - **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
689
+ - **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
690
+
691
+ ```ts
692
+ const scenePass = pass(scene, camera);
693
+ ensureVelocityOutput(scenePass);
694
+ renderer.setOutputNode(scenePass);
695
+ const tracker = new VelocityTracker();
696
+ tracker.update(scene);
697
+ renderer.render(scene, camera);
698
+ tracker.commit(scene);
699
+ ```
700
+
701
+ ### `readVelocityPreviousWorldMatrix`
702
+
703
+ `function` — Provision screen-space motion data for temporal nodes and keep per-instance history at the frame boundary.
704
+
705
+ ```ts
706
+ export function readVelocityPreviousWorldMatrix(object: Object3D): Matrix4 | undefined { … }
707
+ ```
708
+
709
+ - **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
710
+ - **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
711
+
712
+ ```ts
713
+ const scenePass = pass(scene, camera);
714
+ ensureVelocityOutput(scenePass);
715
+ renderer.setOutputNode(scenePass);
716
+ const tracker = new VelocityTracker();
717
+ tracker.update(scene);
718
+ renderer.render(scene, camera);
719
+ tracker.commit(scene);
720
+ ```
721
+
722
+ ### `RenderChain`
723
+
724
+ `class` — Compose game-provided render nodes in a measured, fail-closed chain.
725
+
726
+ ```ts
727
+ export class RenderChain { … }
728
+ ```
729
+
730
+ - **Use when:** compose screen-space effects in a canonical order · report which render tier and velocity route actually ran
731
+ - **Constraints:** stage factories own colour, strength, and all other appearance choices
732
+
733
+ ```ts
734
+ const chain = new RenderChain(renderer, { input: colour, stages, request: { stages: ["bloom"], tier: "auto" } });
735
+ ```
736
+
737
+ ### `replay`
738
+
739
+ `function` — Record or replay deterministic game input and state.
740
+
741
+ ```ts
742
+ export function replay< TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined, >(options: IReplayOptions = { … }
743
+ ```
744
+
745
+ - **Use when:** reproduce a gameplay bug from recorded input · run a deterministic replay in a playtest
746
+ - **Constraints:** use a seeded random source and fixed-step simulation for meaningful replays
747
+
748
+ ```ts
749
+ const driver = createReplayDriver({ recording });
750
+ ```
751
+
752
+ ### `resolveAtmosphereLutResolutions`
753
+
754
+ `function` — Resolve the three LUT dimensions, allowing a game to trade startup cost for resolution.
755
+
756
+ ```ts
757
+ export function resolveAtmosphereLutResolutions( resolutions: Partial<IAtmosphereLutResolutions> | undefined, ): IAtmosphereLutResolutions { … }
758
+ ```
759
+
760
+ - **Use when:** choose atmosphere LUT dimensions for a measured startup budget
761
+ - **Constraints:** every width and height must be a positive integer; the dimensions are not a named fidelity tier
762
+
763
+ ```ts
764
+ const resolutions = resolveAtmosphereLutResolutions({ skyView: { width: 128, height: 72 } });
765
+ ```
766
+
767
+ ### `resolveAtmosphereParameters`
768
+
769
+ `function` — Validate and clone game-owned atmosphere coefficients.
770
+
771
+ ```ts
772
+ export function resolveAtmosphereParameters( options: IAtmosphereParameters, ): IResolvedAtmosphereParameters { … }
773
+ ```
774
+
775
+ - **Use when:** validate atmosphere coefficients before a game creates its sky
776
+ - **Constraints:** provide all three coefficient vectors and both radii; omitted fields are errors
777
+
778
+ ```ts
779
+ const parameters = resolveAtmosphereParameters({ rayleigh, mie, ozone, planetRadius, atmosphereRadius });
780
+ ```
781
+
782
+ ### `Scene`
783
+
784
+ `class` — Implement a portable Godot-shaped game scene lifecycle.
785
+
786
+ ```ts
787
+ export abstract class Scene< TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined, > { … }
788
+ ```
789
+
790
+ - **Use when:** add a playable level or menu scene · move scene setup and per-frame gameplay out of the entry point
791
+ - **Constraints:** scene code must stay portable across web and native
792
+
793
+ ```ts
794
+ class Play extends Scene { update(ctx, dt) {} }
795
+ ```
796
+
797
+ ### `ScenePicker`
798
+
799
+ `class` — Raycast the game scene using the framework's picker.
800
+
801
+ ```ts
802
+ export class ScenePicker { … }
803
+ ```
804
+
805
+ - **Use when:** select an object under the pointer · interact with the first collider or mesh hit
806
+ - **Supersedes (writing this fails `pnpm budgets`):** new Raycaster(
807
+
808
+ ```ts
809
+ const picker = new ScenePicker({ camera, scene });
810
+ ```
811
+
812
+ ### `Scheduler`
813
+
814
+ `class` — Schedule delayed and repeating callbacks or tween numeric properties with game-owned cleanup.
815
+
816
+ ```ts
817
+ export class Scheduler { … }
818
+ ```
819
+
820
+ - **Use when:** delay an enemy patrol transition · run a callback every simulation tick · tween a numeric property with a game-owned curve
821
+ - **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
822
+
823
+ ```ts
824
+ const door = { y: 0 };
825
+ await ctx.tween(door, { y: 2.4 }, 0.5, { ease: (t) => 1 - (1 - t) ** 3 });
826
+ ```
827
+
828
+ ### `skeletonBones`
829
+
830
+ `function` — List the names of every bone in a character hierarchy.
831
+
832
+ ```ts
833
+ export function skeletonBones(root: Object3D): readonly string[] { … }
834
+ ```
835
+
836
+ - **Use when:** inspect the available bones before attaching a game-owned object · debug a missing skeleton bone name
837
+
838
+ ```ts
839
+ import { skeletonBones } from "@threenative/core";
840
+ const bones = skeletonBones(character);
841
+ ```
842
+
843
+ ### `SoftBody3D`
844
+
845
+ `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.
846
+
847
+ ```ts
848
+ export class SoftBody3D extends Mesh<BufferGeometry, NodeMaterial> implements IComputeDriven { … }
849
+ ```
850
+
851
+ - **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
852
+ - **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
853
+ - **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
854
+
855
+ ```ts
856
+ const flag = new SoftBody3D(flagMesh, { pinned: topEdge, stiffness: 35, damping: 1.8, gravity: [0, -9.81, 0], wind: [1.5, 0, 0.4] });
857
+ ```
858
+
859
+ ### `softCircleDataTexture`
860
+
861
+ `function` — Build a soft round sprite as pixel data instead of painting a canvas.
862
+
863
+ ```ts
864
+ export function softCircleDataTexture(size = 64, hardness = 0.25): DataTexture { … }
865
+ ```
866
+
867
+ - **Use when:** give smoke, flash, or glow sprites a radial alpha falloff · generate sprite images that render identically under every backend
868
+ - **Constraints:** canvas-painted images sample black under WebGPURenderer; write sprites as pixel data there
869
+
870
+ ```ts
871
+ const puff = softCircleDataTexture(64, 0.25);
872
+ ```
873
+
874
+ ### `solarPosition`
875
+
876
+ `function` — Calculate solar elevation and azimuth from time, latitude, and longitude.
877
+
878
+ ```ts
879
+ export function solarPosition(input: ISolarPositionInput, target?: ISolarPosition): ISolarPosition;
880
+ ```
881
+
882
+ - **Use when:** move a sun across a real day at a game's latitude and longitude
883
+ - **Constraints:** dates are interpreted as UTC unless utcOffset is supplied; no fixed sun direction is assumed · pass a mutable { azimuth, elevation } target to reuse the result object in a steady frame loop
884
+
885
+ ```ts
886
+ const sun = solarPosition({ date, latitude: 49.28, longitude: -123.12, utcOffset: -8 });
887
+ ```
888
+
889
+ ### `solarPositionAt`
890
+
891
+ `function` — Calculate solar elevation and azimuth for one UTC date.
892
+
893
+ ```ts
894
+ export function solarPositionAt( date: Date | string, latitude: number, longitude: number, ): ISolarPosition { … }
895
+ ```
896
+
897
+ - **Use when:** calculate a sun direction from a timestamp and a game location
898
+ - **Constraints:** dates are interpreted as UTC; use solarPosition for an explicit local offset
899
+
900
+ ```ts
901
+ const sun = solarPositionAt(new Date(), 49.28, -123.12);
902
+ ```
903
+
904
+ ### `SpectralOcean`
905
+
906
+ `class` — Simulate a spectral ocean — cascaded wave spectra inverse-transformed on the GPU each frame.
907
+
908
+ ```ts
909
+ export class SpectralOcean extends Object3D implements IComputeDriven { … }
910
+ ```
911
+
912
+ - **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
913
+ - **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
914
+
915
+ ```ts
916
+ const sea = ctx.add(new SpectralOcean(oceanOptions));
917
+ ```
918
+
919
+ ### `SpriteAnimator3D`
920
+
921
+ `class` — Advance a game-owned non-uniform sprite atlas on the fixed step.
922
+
923
+ ```ts
924
+ export class SpriteAnimator3D { … }
925
+ ```
926
+
927
+ - **Use when:** play an animated pickup or sprite-sheet effect · sequence atlas frames with different authored durations
928
+ - **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
929
+
930
+ ```ts
931
+ const animator = new SpriteAnimator3D({ texture: atlas, frames, mode: "pingPong" });
932
+ ```
933
+
934
+ ### `TracerPool3D`
935
+
936
+ `class` — Pool travelling bullet-streak meshes for hitscan shots.
937
+
938
+ ```ts
939
+ export class TracerPool3D { … }
940
+ ```
941
+
942
+ - **Use when:** show where a hitscan round went · draw incoming fire without spawning projectiles
943
+ - **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
944
+
945
+ ```ts
946
+ const tracers = new TracerPool3D(ctx.scene, tracerOptions);
947
+ tracers.spawn(muzzle, shotDirection, hit.distance);
948
+ ```
949
+
950
+ ### `updateAtmosphereParameters`
951
+
952
+ `function` — Apply a partial game-owned atmosphere change while preserving validation.
953
+
954
+ ```ts
955
+ export function updateAtmosphereParameters( current: IResolvedAtmosphereParameters, patch: IAtmosphereParameterPatch, ): IResolvedAtmosphereParameters { … }
956
+ ```
957
+
958
+ - **Use when:** change scattering coefficients and rebake an atmosphere
959
+ - **Constraints:** patches cannot introduce omitted, negative, or non-finite physical values
960
+
961
+ ```ts
962
+ atmosphere.setAtmosphere({ rayleigh: [0.008, 0.016, 0.04] });
963
+ ```
964
+
965
+ ### `updateClusteredMeshes`
966
+
967
+ `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.
968
+
969
+ ```ts
970
+ export function updateClusteredMeshes( root: { … }
971
+ ```
972
+
973
+ - **Use when:** cut a virtual-geometry subtree the engine does not render itself
974
+
975
+ ```ts
976
+ updateClusteredMeshes(stagedRoot, myCamera, ctx.renderer.domElement.height);
977
+ ```
978
+
979
+ ### `velocityTexture`
980
+
981
+ `function` — Provision screen-space motion data for temporal nodes and keep per-instance history at the frame boundary.
982
+
983
+ ```ts
984
+ export function velocityTexture(pass: IVelocityRenderPass): Node { … }
985
+ ```
986
+
987
+ - **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
988
+ - **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
989
+
990
+ ```ts
991
+ const scenePass = pass(scene, camera);
992
+ ensureVelocityOutput(scenePass);
993
+ renderer.setOutputNode(scenePass);
994
+ const tracker = new VelocityTracker();
995
+ tracker.update(scene);
996
+ renderer.render(scene, camera);
997
+ tracker.commit(scene);
998
+ ```
999
+
1000
+ ### `VelocityTracker`
1001
+
1002
+ `class` — Provision screen-space motion data for temporal nodes and keep per-instance history at the frame boundary.
1003
+
1004
+ ```ts
1005
+ export class VelocityTracker { … }
1006
+ ```
1007
+
1008
+ - **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
1009
+ - **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
1010
+
1011
+ ```ts
1012
+ const scenePass = pass(scene, camera);
1013
+ ensureVelocityOutput(scenePass);
1014
+ renderer.setOutputNode(scenePass);
1015
+ const tracker = new VelocityTracker();
1016
+ tracker.update(scene);
1017
+ renderer.render(scene, camera);
1018
+ tracker.commit(scene);
1019
+ ```
1020
+
1021
+ ### `warmUpScene`
1022
+
1023
+ `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.
1024
+
1025
+ ```ts
1026
+ export async function warmUpScene( renderer: IWarmUpRenderer, scene: Object3D, camera: Camera, options: IWarmUpOptions = { … }
1027
+ ```
1028
+
1029
+ - **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
1030
+
1031
+ ```ts
1032
+ await warmUpScene(renderer, scene, camera, { onProgress: (p) => setLoading(p) });
1033
+ ```
1034
+
1035
+ ### `WaveField`
1036
+
1037
+ `class` — Evaluate analytic waves on CPU and displace game-owned vertices with the matching TSL graph.
1038
+
1039
+ ```ts
1040
+ export class WaveField { … }
1041
+ ```
1042
+
1043
+ - **Use when:** float a boat on waves · make water move · find the water surface height at a point
1044
+ - **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
1045
+
1046
+ ```ts
1047
+ const field = new WaveField({ waves });
1048
+ const { height, normal } = field.sample(x, z, elapsed);
1049
+ ```
1050
+
1051
+ ### `withVelocityContext`
1052
+
1053
+ `function` — Provision screen-space motion data for temporal nodes and keep per-instance history at the frame boundary.
1054
+
1055
+ ```ts
1056
+ export function withVelocityContext<T>(node: T, source: Node): T { … }
1057
+ ```
1058
+
1059
+ - **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
1060
+ - **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
1061
+
1062
+ ```ts
1063
+ const scenePass = pass(scene, camera);
1064
+ ensureVelocityOutput(scenePass);
1065
+ renderer.setOutputNode(scenePass);
1066
+ const tracker = new VelocityTracker();
1067
+ tracker.update(scene);
1068
+ renderer.render(scene, camera);
1069
+ tracker.commit(scene);
1070
+ ```
1071
+
1072
+ ### `zenithTransmittance`
1073
+
1074
+ `function` — Return direct vertical transmittance for the supplied atmosphere.
1075
+
1076
+ ```ts
1077
+ export function zenithTransmittance( parameters: IAtmosphereParameters | IResolvedAtmosphereParameters, ): AtmosphereRgb { … }
1078
+ ```
1079
+
1080
+ - **Use when:** check a supplied atmosphere's direct vertical transmittance
1081
+ - **Constraints:** use the returned value as a validation oracle; the rendered path samples the LUT
1082
+
1083
+ ```ts
1084
+ const zenith = zenithTransmittance({ rayleigh, mie, ozone, planetRadius, atmosphereRadius });
1085
+ ```
1086
+
1087
+ ## `@threenative/core/hot`
1088
+
1089
+ ### `acceptHotUpdate`
1090
+
1091
+ `function` — Register hot-reload state preservation for a game.
1092
+
1093
+ ```ts
1094
+ export function acceptHotUpdate<TState extends Record<string, unknown>, TPhysics>( game: IGame<TState, TPhysics>, hot: IImportMeta["hot"], ): void { … }
1095
+ ```
1096
+
1097
+ - **Use when:** keep game state while editing source in development · diagnose state shape changes during hot reload
1098
+ - **Constraints:** use only in the web development entry
1099
+
1100
+ ```ts
1101
+ acceptHotUpdate(game, import.meta.hot);
1102
+ ```
1103
+
1104
+ ### `assertPortableState`
1105
+
1106
+ `function` — Validate that hot-reload state can cross the Vite boundary.
1107
+
1108
+ ```ts
1109
+ export function assertPortableState(state: unknown): void { … }
1110
+ ```
1111
+
1112
+ - **Use when:** preserve JSON-shaped state during hot reload · reject a non-portable game state before reload
1113
+ - **Constraints:** state must contain finite numbers and plain objects only
1114
+
1115
+ ```ts
1116
+ assertPortableState(game.state.getState());
1117
+ ```
1118
+
1119
+ ## `@threenative/core/playtest`
1120
+
1121
+ ### `playtest`
1122
+
1123
+ `function` — Install the playtest bridge into a portable game.
1124
+
1125
+ ```ts
1126
+ export function playtest< TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined, >(options: IPlaytestOptions = { … }
1127
+ ```
1128
+
1129
+ - **Use when:** expose movement and world observations to a playtest · connect a game to the ThreeNative scenario runner
1130
+ - **Constraints:** install once in the game's plugin list
1131
+
1132
+ ```ts
1133
+ const game = defineGame({ plugins: [playtest()] });
1134
+ ```
1135
+
1136
+ ## `@threenative/core/react`
1137
+
1138
+ ### `createReactOverlay`
1139
+
1140
+ `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.
1141
+
1142
+ ```ts
1143
+ export function createReactOverlay(options: IReactOverlayOptions): IReactOverlay { … }
1144
+ ```
1145
+
1146
+ - **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
1147
+ - **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
1148
+
1149
+ ```ts
1150
+ const overlay = createReactOverlay({ canvasLayer: ctx.canvasLayer });
1151
+ ```
1152
+
1153
+ ### `measureText`
1154
+
1155
+ `function` — Width in pixels of a glyph run at a given cell height.
1156
+
1157
+ ```ts
1158
+ export function measureText(text: string, fontSize: number, letterSpacing = 0): number { … }
1159
+ ```
1160
+
1161
+ - **Use when:** measure native React HUD text before laying it out
1162
+
1163
+ ```ts
1164
+ const scoreWidth = measureText("SCORE 10", 24)
1165
+ ```
1166
+
1167
+ ### `supportedGlyphs`
1168
+
1169
+ `function` — Every character this glyph set can draw, for error messages and for the templates' AGENTS.md.
1170
+
1171
+ ```ts
1172
+ export function supportedGlyphs(): string { … }
1173
+ ```
1174
+
1175
+ - **Use when:** discover which characters a native React HUD can draw
1176
+
1177
+ ```ts
1178
+ supportedGlyphs().includes("A")
1179
+ ```
1180
+
1181
+ ### `supportedStyleKeys`
1182
+
1183
+ `function` — Every style key the overlay implements, for the templates' AGENTS.md and for error messages.
1184
+
1185
+ ```ts
1186
+ export function supportedStyleKeys(): readonly string[] { … }
1187
+ ```
1188
+
1189
+ - **Use when:** discover which React HUD style properties work on native
1190
+
1191
+ ```ts
1192
+ supportedStyleKeys().includes("centerX")
1193
+ ```
1194
+
1195
+ ### `Text`
1196
+
1197
+ `function` — A run of bitmap glyphs, drawn as one instanced quad per lit pixel.
1198
+
1199
+ ```ts
1200
+ export function Text(props: ITextProps): ReactNode { … }
1201
+ ```
1202
+
1203
+ - **Use when:** show text in a native React HUD without a DOM
1204
+
1205
+ ```ts
1206
+ <Text style={{ color: "#ffffff", fontSize: 24 }}>SCORE 10</Text>
1207
+ ```
1208
+
1209
+ ### `View`
1210
+
1211
+ `function` — A rectangle. Paints when its style has a `background`; otherwise it only positions children.
1212
+
1213
+ ```ts
1214
+ export function View(props: IViewProps): ReactNode { … }
1215
+ ```
1216
+
1217
+ - **Use when:** group and position native React HUD elements
1218
+
1219
+ ```ts
1220
+ <View style={{ centerX: 0, top: 24 }}><Text>READY</Text></View>
1221
+ ```
1222
+
1223
+ ## `@threenative/core/ui-layer`
1224
+
1225
+ ### `connectUiBridge`
1226
+
1227
+ `function` — Open the message channel between a game and its UI, whatever host is underneath.
1228
+
1229
+ ```ts
1230
+ export function connectUiBridge(options: IConnectOptions): IUiBridge { … }
1231
+ ```
1232
+
1233
+ - **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
1234
+ - **Constraints:** the transport is discovered, never configured; no game names the web view
1235
+
1236
+ ```ts
1237
+ const bridge = connectUiBridge({ end: "ui" });
1238
+ ```
1239
+
1240
+ ### `onUiIntent`
1241
+
1242
+ `function` — Handle the actions a UI sends back to the game.
1243
+
1244
+ ```ts
1245
+ export function onUiIntent( bridge: IUiBridge, listener: (intent: string, payload: unknown) => void, ): () => void { … }
1246
+ ```
1247
+
1248
+ - **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
1249
+ - **Constraints:** prefer game.ui.onIntent, which connects the bridge for you
1250
+
1251
+ ```ts
1252
+ onUiIntent(bridge, (intent) => { if (intent === "restart") game.goto("Play"); });
1253
+ ```
1254
+
1255
+ ### `publishHitRegions`
1256
+
1257
+ `function` — Tell the native input host where a UI's touchable controls are.
1258
+
1259
+ ```ts
1260
+ export function publishHitRegions(options: IRegistryOptions): IHitRegionRegistry { … }
1261
+ ```
1262
+
1263
+ - **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
1264
+ - **Constraints:** mark controls with data-tn-interactive; pointer-events is not the mechanism
1265
+
1266
+ ```ts
1267
+ publishHitRegions({ bridge });
1268
+ ```
1269
+
1270
+ ### `publishUiState`
1271
+
1272
+ `function` — Publish the game's state so a UI in another process can mirror it.
1273
+
1274
+ ```ts
1275
+ export function publishUiState<T>( bridge: IUiBridge, store: IPublishableStore<T>, options: IPublishOptions = { … }
1276
+ ```
1277
+
1278
+ - **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
1279
+ - **Constraints:** publishes at the store's throttled cadence, and not at all with no UI listening
1280
+
1281
+ ```ts
1282
+ publishUiState(bridge, game.state);
1283
+ ```
1284
+
1285
+ ### `sendUiIntent`
1286
+
1287
+ `function` — Send a player action from the UI back to the game.
1288
+
1289
+ ```ts
1290
+ export function sendUiIntent(bridge: IUiBridge, intent: string, payload?: unknown): void { … }
1291
+ ```
1292
+
1293
+ - **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
1294
+ - **Constraints:** one-way; the game decides what each name means and may ignore one
1295
+
1296
+ ```ts
1297
+ sendUiIntent(bridge, "restart");
1298
+ ```
1299
+
1300
+ ### `subscribeUiState`
1301
+
1302
+ `function` — Mirror the game's published state on the UI side.
1303
+
1304
+ ```ts
1305
+ export function subscribeUiState<T>(bridge: IUiBridge): IUiStateMirror<T> { … }
1306
+ ```
1307
+
1308
+ - **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
1309
+ - **Constraints:** returns undefined until the game publishes its first state
1310
+
1311
+ ```ts
1312
+ const mirror = subscribeUiState(bridge);
1313
+ ```
1314
+
1315
+ ## `@threenative/core/world`
1316
+
1317
+ ### `Heightfield`
1318
+
1319
+ `class` — One height buffer shared by world queries, rendered geometry, and a physics heightfield. The game supplies every value, so changing the terrain's shape never requires a package edit. `fromSampler` evaluates that game function exactly once at each vertex and retains only the resulting numbers. Queries interpolate those same numbers instead of evaluating the function again.
1320
+
1321
+ ```ts
1322
+ export class Heightfield { … }
1323
+ ```
1324
+
1325
+ - **Use when:** build terrain geometry and collision from one game-authored height function · query the same ground height or normal that a player sees and collides with · build islands and coastlines from terrain
1326
+ - **Constraints:** sampleHeight owns the terrain shape and stays in game source; the framework stores and interpolates its output · rows and columns are vertex counts; geometry is row-major z-then-x and collider export transposes once into Rapier's column-major matrix order
1327
+ - **Overrides:** rows, columns, width, depth, origin, and sampleHeight are explicit on every field
1328
+
1329
+ ```ts
1330
+ const field = Heightfield.fromSampler({ rows: 65, columns: 65, width: 64, depth: 64, origin: { x: 0, z: 0 }, sampleHeight: terrainHeight });
1331
+ ```
1332
+
1333
+ ## `@threenative/physics`
1334
+
1335
+ ### `Area3D`
1336
+
1337
+ `class` — Detect overlaps without turning the body into a moving collider.
1338
+
1339
+ ```ts
1340
+ export class Area3D { … }
1341
+ ```
1342
+
1343
+ - **Use when:** detect when an enemy enters a trigger area · react to a player entering a zone
1344
+ - **Constraints:** add the area to the physics context before stepping the world
1345
+
1346
+ ```ts
1347
+ const area = new Area3D({ context, shape });
1348
+ ```
1349
+
1350
+ ### `Buoyancy3D`
1351
+
1352
+ `class` — Float a rigid body on a game-owned height source with fixed-step force ordering.
1353
+
1354
+ ```ts
1355
+ export class Buoyancy3D { … }
1356
+ ```
1357
+
1358
+ - **Use when:** float a boat on waves · keep a hull above a moving water surface
1359
+ - **Constraints:** supply hull points, density, drag, and the height source
1360
+ - **Overrides:** buoyancy disables force application while submergedFraction remains measured
1361
+
1362
+ ```ts
1363
+ new Buoyancy3D({ body, surface: field, hullPoints, density: 1_000, drag: 4 });
1364
+ ```
1365
+
1366
+ ### `CharacterBody3D`
1367
+
1368
+ `class` — Move a character body with collision-aware sliding.
1369
+
1370
+ ```ts
1371
+ export class CharacterBody3D { … }
1372
+ ```
1373
+
1374
+ - **Use when:** move an enemy or player through a level · keep a character from walking through walls
1375
+ - **Constraints:** use moveAndSlide inside the physics update
1376
+
1377
+ ```ts
1378
+ const body = new CharacterBody3D({ context, object });
1379
+ ```
1380
+
1381
+ ### `CollisionShape3D`
1382
+
1383
+ `class` — Give a physics body a Three.js collision shape.
1384
+
1385
+ ```ts
1386
+ export class CollisionShape3D { … }
1387
+ ```
1388
+
1389
+ - **Use when:** add a capsule or box collider to a character · configure the shape used by a rigid body
1390
+ - **Constraints:** create shapes through the owning physics context
1391
+
1392
+ ```ts
1393
+ const shape = new CollisionShape3D({ context, shape: "capsule" });
1394
+ ```
1395
+
1396
+ ### `interactionGroups`
1397
+
1398
+ `function` — Encode collision layers and masks for Rapier groups.
1399
+
1400
+ ```ts
1401
+ export function interactionGroups(layer: number, mask: number): number { … }
1402
+ ```
1403
+
1404
+ - **Use when:** make an enemy collide with the world but not pickups · configure which physics layers interact
1405
+
1406
+ ```ts
1407
+ const groups = interactionGroups(1, 3);
1408
+ ```
1409
+
1410
+ ### `Joint3D`
1411
+
1412
+ `class` — Connect two physics bodies with a Godot-style joint.
1413
+
1414
+ ```ts
1415
+ export class Joint3D { … }
1416
+ ```
1417
+
1418
+ - **Use when:** constrain a rigid body to another body · build a hinge or pin mechanism
1419
+ - **Constraints:** both bodies must belong to the same physics context
1420
+
1421
+ ```ts
1422
+ const joint = new Joint3D({ context, kind: "hinge" });
1423
+ ```
1424
+
1425
+ ### `PhysicsDirectSpaceState3D`
1426
+
1427
+ `class` — Query the physics world without creating a body.
1428
+
1429
+ ```ts
1430
+ export class PhysicsDirectSpaceState3D { … }
1431
+ ```
1432
+
1433
+ - **Use when:** raycast for visibility or aiming · find bodies inside a shape or point query
1434
+ - **Constraints:** query results are bounded by the configured result limit
1435
+
1436
+ ```ts
1437
+ const space = new PhysicsDirectSpaceState3D(context);
1438
+ ```
1439
+
1440
+ ### `rapier`
1441
+
1442
+ `function` — Install the Rapier physics plugin and simulation backend.
1443
+
1444
+ ```ts
1445
+ export function rapier(options: IPhysicsOptions = { … }
1446
+ ```
1447
+
1448
+ - **Use when:** add physics to a portable game · provide the context used by character and rigid bodies
1449
+ - **Constraints:** place rapier() before recast() in the plugin list
1450
+
1451
+ ```ts
1452
+ const game = defineGame({ plugins: [rapier()] });
1453
+ ```
1454
+
1455
+ ### `RigidBody3D`
1456
+
1457
+ `class` — Simulate a dynamic or static rigid body.
1458
+
1459
+ ```ts
1460
+ export class RigidBody3D { … }
1461
+ ```
1462
+
1463
+ - **Use when:** give a crate or prop physical motion · create a body that collides with a character · fire physical cannonballs that collide with ships or scenery · fire a cannonball projectile with cannon smoke particles
1464
+ - **Constraints:** register rapier() in the game plugin list before using bodies
1465
+
1466
+ ```ts
1467
+ const crate = new RigidBody3D({ context, object, mode: "dynamic" });
1468
+ ```
1469
+
1470
+ ### `softBodyCollision`
1471
+
1472
+ `function` — Feed existing rigid-body boxes into `SoftBody3D` without inventing a second collider API.
1473
+
1474
+ ```ts
1475
+ export function softBodyCollision(...bodies: readonly RigidBody3D[]): ISoftBodyCollision { … }
1476
+ ```
1477
+
1478
+ - **Use when:** stop a cloth flag, cape, or curtain at an existing physics wall · collide SoftBody3D with fixed box bodies
1479
+ - **Constraints:** every body must use CollisionShape3D.box and retain its Three.js object transform · rotated boxes become conservative cloth-local axis-aligned bounds
1480
+
1481
+ ```ts
1482
+ const cloth = new SoftBody3D(mesh, { ...options, collision: softBodyCollision(wall) });
1483
+ ```
1484
+
1485
+ ## `@threenative/physics/navigation`
1486
+
1487
+ ### `NavigationAgent3D`
1488
+
1489
+ `class` — Move an agent along a baked navmesh toward a target.
1490
+
1491
+ ```ts
1492
+ export class NavigationAgent3D { … }
1493
+ ```
1494
+
1495
+ - **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
1496
+ - **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
1497
+
1498
+ ```ts
1499
+ import { NavigationAgent3D } from "@threenative/physics/navigation";
1500
+ import { Vector3 } from "three";
1501
+ const agent = new NavigationAgent3D({ navigation, object });
1502
+ agent.setTargetPosition(player.position);
1503
+ const reusableTarget = new Vector3();
1504
+ const next = agent.getNextPathPosition(reusableTarget);
1505
+ ```
1506
+
1507
+ ### `NavigationObstacle3D`
1508
+
1509
+ `class` — Add a non-moving crowd obstacle to a navmesh.
1510
+
1511
+ ```ts
1512
+ export class NavigationObstacle3D { … }
1513
+ ```
1514
+
1515
+ - **Use when:** keep navigation agents away from a blocking prop · make a stationary character affect crowd avoidance
1516
+ - **Constraints:** create it after recast() and dispose it with the scene
1517
+
1518
+ ```ts
1519
+ const obstacle = new NavigationObstacle3D({ navigation, object });
1520
+ ```
1521
+
1522
+ ### `NavigationRegion3D`
1523
+
1524
+ `class` — Bake walkable Three.js geometry into a navigation region.
1525
+
1526
+ ```ts
1527
+ export class NavigationRegion3D { … }
1528
+ ```
1529
+
1530
+ - **Use when:** let enemies walk around level geometry · create the baked navmesh required by NavigationAgent3D
1531
+ - **Constraints:** bake before creating agents or obstacles
1532
+
1533
+ ```ts
1534
+ const region = new NavigationRegion3D({ navigation, meshes: [floor] });
1535
+ ```
1536
+
1537
+ ### `recast`
1538
+
1539
+ `function` — Install navmesh pathfinding and crowd avoidance.
1540
+
1541
+ ```ts
1542
+ export function recast(): NavigationPlugin { … }
1543
+ ```
1544
+
1545
+ - **Use when:** enemy walks around a wall · NPC patrols a level and chases a player
1546
+ - **Constraints:** requires rapier() earlier in the plugins array
1547
+
1548
+ ```ts
1549
+ const game = defineGame({ plugins: [rapier(), recast()] });
1550
+ ```
1551
+
1552
+ ## `@threenative/playtest`
1553
+
1554
+ ### `assertJsonSafe`
1555
+
1556
+ `function` — Validate JSON-safe bridge messages and protocol sizes.
1557
+
1558
+ ```ts
1559
+ export function assertJsonSafe(value: unknown, path = "$"): asserts value is JsonValue { … }
1560
+ ```
1561
+
1562
+ - **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
1563
+ - **Constraints:** bridge values must be JSON-shaped · throws instead of silently dropping the offending field
1564
+
1565
+ ```ts
1566
+ assertJsonSafe({ score: 10 });
1567
+ ```
1568
+
1569
+ ### `DeviceMetricsError`
1570
+
1571
+ `class` — Measure and judge device thermal, power and battery state around a device playtest run.
1572
+
1573
+ ```ts
1574
+ export class DeviceMetricsError extends Error { … }
1575
+ ```
1576
+
1577
+ - **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
1578
+ - **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
1579
+
1580
+ ```ts
1581
+ const verdict = summarizeDeviceMetrics(observation.samples);
1582
+ ```
1583
+
1584
+ ### `DeviceMetricsRecorder`
1585
+
1586
+ `class` — Measure and judge device thermal, power and battery state around a device playtest run.
1587
+
1588
+ ```ts
1589
+ export class DeviceMetricsRecorder { … }
1590
+ ```
1591
+
1592
+ - **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
1593
+ - **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
1594
+
1595
+ ```ts
1596
+ const verdict = summarizeDeviceMetrics(observation.samples);
1597
+ ```
1598
+
1599
+ ### `evaluateRichPlaytestAssertions`
1600
+
1601
+ `function` — Evaluate rich semantic assertions against captured observations.
1602
+
1603
+ ```ts
1604
+ export function evaluateRichPlaytestAssertions(input: { … }
1605
+ ```
1606
+
1607
+ - **Use when:** assert movement, visibility, or diagnostics in a playtest · turn a scenario observation into a pass or failure
1608
+ - **Constraints:** malformed or empty assertions fail closed
1609
+
1610
+ ```ts
1611
+ const result = evaluateRichPlaytestAssertions(input);
1612
+ ```
1613
+
1614
+ ### `invalidScenario`
1615
+
1616
+ `function` — Load and validate a scenario, then control its tick steps.
1617
+
1618
+ ```ts
1619
+ export function invalidScenario(scenarioPath: string, message: string): PlaytestScenarioError { … }
1620
+ ```
1621
+
1622
+ - **Use when:** create a browser or device playtest scenario · wait or hold a game for a deterministic number of ticks
1623
+ - **Constraints:** unknown scenario keys fail closed
1624
+
1625
+ ```ts
1626
+ const scenario = await loadPlaytestScenario(project, file);
1627
+ ```
1628
+
1629
+ ### `jsonByteLength`
1630
+
1631
+ `function` — Validate JSON-safe bridge messages and protocol sizes.
1632
+
1633
+ ```ts
1634
+ export function jsonByteLength(value: JsonValue): number { … }
1635
+ ```
1636
+
1637
+ - **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
1638
+ - **Constraints:** bridge values must be JSON-shaped
1639
+
1640
+ ```ts
1641
+ assertJsonSafe({ score: 10 });
1642
+ ```
1643
+
1644
+ ### `loadPlaytestScenario`
1645
+
1646
+ `function` — Load and validate a scenario, then control its tick steps.
1647
+
1648
+ ```ts
1649
+ export async function loadPlaytestScenario(projectPath: string, scenarioPath: string): Promise<IPlaytestScenario> { … }
1650
+ ```
1651
+
1652
+ - **Use when:** create a browser or device playtest scenario · wait or hold a game for a deterministic number of ticks
1653
+ - **Constraints:** unknown scenario keys fail closed
1654
+
1655
+ ```ts
1656
+ const scenario = await loadPlaytestScenario(project, file);
1657
+ ```
1658
+
1659
+ ### `missingPlaytestCapabilities`
1660
+
1661
+ `function` — Validate and inspect playtest capability declarations.
1662
+
1663
+ ```ts
1664
+ export function missingPlaytestCapabilities(required: readonly string[], available: readonly string[]): string[] { … }
1665
+ ```
1666
+
1667
+ - **Use when:** check whether a scenario's required capabilities are installed · report unknown or missing playtest capabilities
1668
+
1669
+ ```ts
1670
+ const missing = missingPlaytestCapabilities(required, available);
1671
+ ```
1672
+
1673
+ ### `parseDeviceBattery`
1674
+
1675
+ `function` — Measure and judge device thermal, power and battery state around a device playtest run.
1676
+
1677
+ ```ts
1678
+ export function parseDeviceBattery(output: string): IPlaytestDeviceBattery { … }
1679
+ ```
1680
+
1681
+ - **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
1682
+ - **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
1683
+
1684
+ ```ts
1685
+ const verdict = summarizeDeviceMetrics(observation.samples);
1686
+ ```
1687
+
1688
+ ### `parseDeviceCurrent`
1689
+
1690
+ `function` — Measure and judge device thermal, power and battery state around a device playtest run.
1691
+
1692
+ ```ts
1693
+ export function parseDeviceCurrent(output: string): PlaytestDeviceMeasurement<number> { … }
1694
+ ```
1695
+
1696
+ - **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
1697
+ - **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
1698
+
1699
+ ```ts
1700
+ const verdict = summarizeDeviceMetrics(observation.samples);
1701
+ ```
1702
+
1703
+ ### `parseDevicePowerRails`
1704
+
1705
+ `function` — Measure and judge device thermal, power and battery state around a device playtest run.
1706
+
1707
+ ```ts
1708
+ export function parseDevicePowerRails(output: string): PlaytestDevicePowerRails { … }
1709
+ ```
1710
+
1711
+ - **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
1712
+ - **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
1713
+
1714
+ ```ts
1715
+ const verdict = summarizeDeviceMetrics(observation.samples);
1716
+ ```
1717
+
1718
+ ### `parseDeviceThermal`
1719
+
1720
+ `function` — Measure and judge device thermal, power and battery state around a device playtest run.
1721
+
1722
+ ```ts
1723
+ export function parseDeviceThermal(output: string): IPlaytestDeviceThermal { … }
1724
+ ```
1725
+
1726
+ - **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
1727
+ - **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
1728
+
1729
+ ```ts
1730
+ const verdict = summarizeDeviceMetrics(observation.samples);
1731
+ ```
1732
+
1733
+ ### `playtestDiagnostic`
1734
+
1735
+ `function` — Create a structured playtest diagnostic.
1736
+
1737
+ ```ts
1738
+ export function playtestDiagnostic( code: PlaytestDiagnosticCode, message: string, instruction: string, details: Pick<IPlaytestProtocolDiagnostic, "capability" | "path"> & { … }
1739
+ ```
1740
+
1741
+ - **Use when:** report a named runtime diagnostic to a scenario · explain why a playtest assertion cannot pass
1742
+
1743
+ ```ts
1744
+ playtestDiagnostic("physics", "body missing");
1745
+ ```
1746
+
1747
+ ### `PlaytestScenarioError`
1748
+
1749
+ `class` — Load and validate a scenario, then control its tick steps.
1750
+
1751
+ ```ts
1752
+ export class PlaytestScenarioError extends Error { … }
1753
+ ```
1754
+
1755
+ - **Use when:** create a browser or device playtest scenario · wait or hold a game for a deterministic number of ticks
1756
+ - **Constraints:** unknown scenario keys fail closed
1757
+
1758
+ ```ts
1759
+ const scenario = await loadPlaytestScenario(project, file);
1760
+ ```
1761
+
1762
+ ### `playtestStepHoldTicks`
1763
+
1764
+ `function` — Load and validate a scenario, then control its tick steps.
1765
+
1766
+ ```ts
1767
+ export function playtestStepHoldTicks(step: IPlaytestStep, fallback = 1): number { … }
1768
+ ```
1769
+
1770
+ - **Use when:** create a browser or device playtest scenario · wait or hold a game for a deterministic number of ticks
1771
+ - **Constraints:** unknown scenario keys fail closed
1772
+
1773
+ ```ts
1774
+ const scenario = await loadPlaytestScenario(project, file);
1775
+ ```
1776
+
1777
+ ### `playtestStepWaitTicks`
1778
+
1779
+ `function` — Load and validate a scenario, then control its tick steps.
1780
+
1781
+ ```ts
1782
+ export function playtestStepWaitTicks(step: IPlaytestStep): number { … }
1783
+ ```
1784
+
1785
+ - **Use when:** create a browser or device playtest scenario · wait or hold a game for a deterministic number of ticks
1786
+ - **Constraints:** unknown scenario keys fail closed
1787
+
1788
+ ```ts
1789
+ const scenario = await loadPlaytestScenario(project, file);
1790
+ ```
1791
+
1792
+ ### `rejectUnknownKeys`
1793
+
1794
+ `function` — Load and validate a scenario, then control its tick steps.
1795
+
1796
+ ```ts
1797
+ export function rejectUnknownKeys( value: Record<string, unknown>, allowedKeys: readonly string[], scenarioPath: string, objectPath: string, ): void { … }
1798
+ ```
1799
+
1800
+ - **Use when:** create a browser or device playtest scenario · wait or hold a game for a deterministic number of ticks
1801
+ - **Constraints:** unknown scenario keys fail closed
1802
+
1803
+ ```ts
1804
+ const scenario = await loadPlaytestScenario(project, file);
1805
+ ```
1806
+
1807
+ ### `requiredPlaytestCapabilities`
1808
+
1809
+ `function` — Evaluate rich semantic assertions against captured observations.
1810
+
1811
+ ```ts
1812
+ export function requiredPlaytestCapabilities(scenario: IPlaytestScenario): PlaytestCapability[] { … }
1813
+ ```
1814
+
1815
+ - **Use when:** assert movement, visibility, or diagnostics in a playtest · turn a scenario observation into a pass or failure
1816
+ - **Constraints:** malformed or empty assertions fail closed
1817
+
1818
+ ```ts
1819
+ const result = evaluateRichPlaytestAssertions(input);
1820
+ ```
1821
+
1822
+ ### `resolveDiagnosticsPolicy`
1823
+
1824
+ `function` — Resolve the effective diagnostics policy for a run, with fail-closed defaults applied.
1825
+
1826
+ ```ts
1827
+ export function resolveDiagnosticsPolicy( policy: IPlaytestDiagnosticsAssertion | undefined, ): IPlaytestDiagnosticsPolicy { … }
1828
+ ```
1829
+
1830
+ - **Use when:** judge captured console, network, or runtime diagnostics for a playtest
1831
+ - **Constraints:** absent policy fields default to rejecting errors
1832
+
1833
+ ```ts
1834
+ const policy = resolveDiagnosticsPolicy(scenario.assert?.diagnostics);
1835
+ ```
1836
+
1837
+ ### `summarizeDeviceMetrics`
1838
+
1839
+ `function` — Measure and judge device thermal, power and battery state around a device playtest run.
1840
+
1841
+ ```ts
1842
+ export function summarizeDeviceMetrics( samples: readonly IPlaytestDeviceMetricsSample[], ): IPlaytestDeviceMetricsVerdict { … }
1843
+ ```
1844
+
1845
+ - **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
1846
+ - **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
1847
+
1848
+ ```ts
1849
+ const verdict = summarizeDeviceMetrics(observation.samples);
1850
+ ```
1851
+
1852
+ ### `unknownPlaytestCapabilities`
1853
+
1854
+ `function` — Validate and inspect playtest capability declarations.
1855
+
1856
+ ```ts
1857
+ export function unknownPlaytestCapabilities(capabilities: readonly string[]): string[] { … }
1858
+ ```
1859
+
1860
+ - **Use when:** check whether a scenario's required capabilities are installed · report unknown or missing playtest capabilities
1861
+
1862
+ ```ts
1863
+ const missing = missingPlaytestCapabilities(required, available);
1864
+ ```
1865
+
1866
+ ## `@threenative/playtest/capture`
1867
+
1868
+ ### `assertCaptureNotBlank`
1869
+
1870
+ `function` — Fail closed when a screenshot is blank or uniform.
1871
+
1872
+ ```ts
1873
+ export function assertCaptureNotBlank(png: Buffer, label: string): ICaptureFrameStats { … }
1874
+ ```
1875
+
1876
+ - **Use when:** guard a visual playtest against a blank frame · prove a screenshot contains more than a loading surface
1877
+ - **Constraints:** the assertion throws instead of returning a false pass
1878
+
1879
+ ```ts
1880
+ assertCaptureNotBlank(png, "first frame");
1881
+ ```
1882
+
1883
+ ### `CaptureGuardError`
1884
+
1885
+ `class` — Explain why a captured frame failed the non-blank guard.
1886
+
1887
+ ```ts
1888
+ export class CaptureGuardError extends Error { … }
1889
+ ```
1890
+
1891
+ - **Use when:** fail a visual test when the rendered frame is blank · include capture statistics in a playtest error
1892
+
1893
+ ```ts
1894
+ throw new CaptureGuardError("menu", "no bright pixels");
1895
+ ```
1896
+
1897
+ ### `inspectFrame`
1898
+
1899
+ `function` — Inspect a PNG frame for visible pixels and luminance variation.
1900
+
1901
+ ```ts
1902
+ export function inspectFrame(png: Buffer): ICaptureFrameStats { … }
1903
+ ```
1904
+
1905
+ - **Use when:** measure whether a screenshot contains a rendered game · diagnose a uniform or blank capture
1906
+
1907
+ ```ts
1908
+ const stats = inspectFrame(png);
1909
+ ```
1910
+
1911
+ ## `@threenative/playtest/protocol`
1912
+
1913
+ ### `assertJsonSafe`
1914
+
1915
+ `function` — Reject any value that would not survive JSON serialization.
1916
+
1917
+ ```ts
1918
+ export function assertJsonSafe(value: unknown, path = "$"): asserts value is JsonValue { … }
1919
+ ```
1920
+
1921
+ - **Use when:** validate entity components and gameplay observations before crossing the bridge
1922
+ - **Constraints:** throws instead of silently dropping the offending field
1923
+
1924
+ ```ts
1925
+ assertJsonSafe(snapshot, "$.components");
1926
+ ```
1927
+
1928
+ ### `jsonByteLength`
1929
+
1930
+ `function` — Measure a payload's wire size in bytes.
1931
+
1932
+ ```ts
1933
+ export function jsonByteLength(value: JsonValue): number { … }
1934
+ ```
1935
+
1936
+ - **Use when:** check a runtime observation against the protocol payload limit before sampling
1937
+
1938
+ ```ts
1939
+ const bytes = jsonByteLength(observation);
1940
+ ```
1941
+
1942
+ ## `@threenative/playtest/runner`
1943
+
1944
+ ### `AdbAndroidDriver`
1945
+
1946
+ `class` — Drive and inspect Android playtest transport.
1947
+
1948
+ ```ts
1949
+ export class AdbAndroidDriver implements IAndroidDriver { … }
1950
+ ```
1951
+
1952
+ - **Use when:** run a scenario on an Android emulator or device · parse Android console diagnostics
1953
+ - **Constraints:** Android evidence must name its target and transport
1954
+
1955
+ ```ts
1956
+ const adb = discoverAdb(process.env);
1957
+ ```
1958
+
1959
+ ### `advanceFixedStep`
1960
+
1961
+ `function` — Execute scenario steps, assertions, and evidence capture.
1962
+
1963
+ ```ts
1964
+ export async function advanceFixedStep( page: Page, bridge: Pick<IPlaytestBridgeClient, "advance">, ticks: number, ): Promise<void> { … }
1965
+ ```
1966
+
1967
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
1968
+ - **Constraints:** missing observations and malformed assertions fail closed
1969
+
1970
+ ```ts
1971
+ const report = await runStandalonePlaytest(options);
1972
+ ```
1973
+
1974
+ ### `advanceTimeoutMs`
1975
+
1976
+ `function` — Connect a Playwright page to a playtest bridge.
1977
+
1978
+ ```ts
1979
+ export function advanceTimeoutMs( ticks: number, perTickMs: number = PLAYTEST_ADVANCE_TICK_BUDGET_MS, ): number { … }
1980
+ ```
1981
+
1982
+ - **Use when:** run a browser scenario against a game · inspect bridge diagnostics from a runner
1983
+ - **Constraints:** the bridge must answer the handshake or the run fails
1984
+
1985
+ ```ts
1986
+ const bridge = await connectPlaytestBridge(page);
1987
+ ```
1988
+
1989
+ ### `androidMailboxPaths`
1990
+
1991
+ `function` — Resolve a native device transport and its mailbox paths.
1992
+
1993
+ ```ts
1994
+ export function androidMailboxPaths( packageName: string, root = `/sdcard/Android/data/$ { … }
1995
+ ```
1996
+
1997
+ - **Use when:** connect a native host to the playtest runner · validate an Android or iOS device endpoint
1998
+ - **Constraints:** paths stay inside the managed artifact directory
1999
+
2000
+ ```ts
2001
+ const paths = deviceMailboxPaths(projectRoot);
2002
+ ```
2003
+
2004
+ ### `androidTouchBatches`
2005
+
2006
+ `function` — Drive and inspect Android playtest transport.
2007
+
2008
+ ```ts
2009
+ export function androidTouchBatches( identity: readonly string[], positions: readonly string[], ): string[][] { … }
2010
+ ```
2011
+
2012
+ - **Use when:** run a scenario on an Android emulator or device · parse Android console diagnostics
2013
+ - **Constraints:** Android evidence must name its target and transport
2014
+
2015
+ ```ts
2016
+ const adb = discoverAdb(process.env);
2017
+ ```
2018
+
2019
+ ### `batchArtifactDirectory`
2020
+
2021
+ `function` — Execute scenario steps, assertions, and evidence capture.
2022
+
2023
+ ```ts
2024
+ export function batchArtifactDirectory(base: string, scenarioPath: string, index: number): string { … }
2025
+ ```
2026
+
2027
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
2028
+ - **Constraints:** missing observations and malformed assertions fail closed
2029
+
2030
+ ```ts
2031
+ const report = await runStandalonePlaytest(options);
2032
+ ```
2033
+
2034
+ ### `boundedTeardownStep`
2035
+
2036
+ `function` — Execute scenario steps, assertions, and evidence capture.
2037
+
2038
+ ```ts
2039
+ export async function boundedTeardownStep( step: Promise<unknown> | undefined, timeoutMs: number, ): Promise<boolean> { … }
2040
+ ```
2041
+
2042
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
2043
+ - **Constraints:** missing observations and malformed assertions fail closed
2044
+
2045
+ ```ts
2046
+ const report = await runStandalonePlaytest(options);
2047
+ ```
2048
+
2049
+ ### `bridgeWaitTimeoutMs`
2050
+
2051
+ `function` — Connect a Playwright page to a playtest bridge.
2052
+
2053
+ ```ts
2054
+ export function bridgeWaitTimeoutMs( operationMs: number = PLAYTEST_PROTOCOL_LIMITS.operationTimeoutMs, ): number { … }
2055
+ ```
2056
+
2057
+ - **Use when:** run a browser scenario against a game · inspect bridge diagnostics from a runner
2058
+ - **Constraints:** the bridge must answer the handshake or the run fails
2059
+
2060
+ ```ts
2061
+ const bridge = await connectPlaytestBridge(page);
2062
+ ```
2063
+
2064
+ ### `buildReport`
2065
+
2066
+ `function` — Execute scenario steps, assertions, and evidence capture.
2067
+
2068
+ ```ts
2069
+ export function buildReport( config: IStandalonePlaytestConfig, scenario: IPlaytestScenario, beforeSnapshot: IPlaytestObservationSnapshot | undefined, afterSnapshot: IPlaytestObservationSnapshot | undefined, consoleEntries: IRunnerConsoleEntry[], networkEntries: Array< { … }
2070
+ ```
2071
+
2072
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
2073
+ - **Constraints:** missing observations and malformed assertions fail closed
2074
+
2075
+ ```ts
2076
+ const report = await runStandalonePlaytest(options);
2077
+ ```
2078
+
2079
+ ### `captureVisualSurface`
2080
+
2081
+ `function` — Execute scenario steps, assertions, and evidence capture.
2082
+
2083
+ ```ts
2084
+ export async function captureVisualSurface( page: Page, artifactPath?: string, ): Promise<Buffer | undefined> { … }
2085
+ ```
2086
+
2087
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
2088
+ - **Constraints:** missing observations and malformed assertions fail closed
2089
+
2090
+ ```ts
2091
+ const report = await runStandalonePlaytest(options);
2092
+ ```
2093
+
2094
+ ### `connectPlaytestBridge`
2095
+
2096
+ `function` — Connect a Playwright page to a playtest bridge.
2097
+
2098
+ ```ts
2099
+ export async function connectPlaytestBridge( page: Page, scenario: IPlaytestScenario, timeoutMs: number = PLAYTEST_PROTOCOL_LIMITS.operationTimeoutMs, ): Promise<IPlaytestBridgeClient | undefined> { … }
2100
+ ```
2101
+
2102
+ - **Use when:** run a browser scenario against a game · inspect bridge diagnostics from a runner
2103
+ - **Constraints:** the bridge must answer the handshake or the run fails
2104
+
2105
+ ```ts
2106
+ const bridge = await connectPlaytestBridge(page);
2107
+ ```
2108
+
2109
+ ### `connectPlaytestBridgeTransport`
2110
+
2111
+ `function` — Connect a Playwright page to a playtest bridge.
2112
+
2113
+ ```ts
2114
+ export async function connectPlaytestBridgeTransport( transport: IBridgeTransport, scenario: IPlaytestScenario, timeoutMs: number = bridgeWaitTimeoutMs(), ): Promise<IPlaytestBridgeClient | undefined> { … }
2115
+ ```
2116
+
2117
+ - **Use when:** run a browser scenario against a game · inspect bridge diagnostics from a runner
2118
+ - **Constraints:** the bridge must answer the handshake or the run fails
2119
+
2120
+ ```ts
2121
+ const bridge = await connectPlaytestBridge(page);
2122
+ ```
2123
+
2124
+ ### `DesktopPlaytestDriver`
2125
+
2126
+ `class` — Drive a local desktop playtest mailbox.
2127
+
2128
+ ```ts
2129
+ export class DesktopPlaytestDriver implements IDevicePlaytestDriver { … }
2130
+ ```
2131
+
2132
+ - **Use when:** run a desktop target through the playtest protocol · exchange observations with a native desktop host
2133
+ - **Constraints:** the mailbox lifecycle must be disposed after the run
2134
+
2135
+ ```ts
2136
+ const driver = new DesktopPlaytestDriver(options);
2137
+ ```
2138
+
2139
+ ### `DeviceBridgeTransport`
2140
+
2141
+ `class` — Resolve a native device transport and its mailbox paths.
2142
+
2143
+ ```ts
2144
+ export class DeviceBridgeTransport implements IDevicePlaytestTransport { … }
2145
+ ```
2146
+
2147
+ - **Use when:** connect a native host to the playtest runner · validate an Android or iOS device endpoint
2148
+ - **Constraints:** paths stay inside the managed artifact directory
2149
+
2150
+ ```ts
2151
+ const paths = deviceMailboxPaths(projectRoot);
2152
+ ```
2153
+
2154
+ ### `deviceMailboxPaths`
2155
+
2156
+ `function` — Resolve a native device transport and its mailbox paths.
2157
+
2158
+ ```ts
2159
+ export function deviceMailboxPaths(root: string): IDeviceMailboxPaths { … }
2160
+ ```
2161
+
2162
+ - **Use when:** connect a native host to the playtest runner · validate an Android or iOS device endpoint
2163
+ - **Constraints:** paths stay inside the managed artifact directory
2164
+
2165
+ ```ts
2166
+ const paths = deviceMailboxPaths(projectRoot);
2167
+ ```
2168
+
2169
+ ### `DeviceMailboxTransport`
2170
+
2171
+ `class` — Resolve a native device transport and its mailbox paths.
2172
+
2173
+ ```ts
2174
+ export class DeviceMailboxTransport implements IDevicePlaytestTransport { … }
2175
+ ```
2176
+
2177
+ - **Use when:** connect a native host to the playtest runner · validate an Android or iOS device endpoint
2178
+ - **Constraints:** paths stay inside the managed artifact directory
2179
+
2180
+ ```ts
2181
+ const paths = deviceMailboxPaths(projectRoot);
2182
+ ```
2183
+
2184
+ ### `deviceTimeoutDiagnostic`
2185
+
2186
+ `function` — Resolve a native device transport and its mailbox paths.
2187
+
2188
+ ```ts
2189
+ export function deviceTimeoutDiagnostic( diagnostic: IPlaytestProtocolDiagnostic, hostAlive: boolean | undefined, lastConsoleLines: readonly string[], ): IPlaytestProtocolDiagnostic { … }
2190
+ ```
2191
+
2192
+ - **Use when:** connect a native host to the playtest runner · validate an Android or iOS device endpoint
2193
+ - **Constraints:** paths stay inside the managed artifact directory
2194
+
2195
+ ```ts
2196
+ const paths = deviceMailboxPaths(projectRoot);
2197
+ ```
2198
+
2199
+ ### `discoverAdb`
2200
+
2201
+ `function` — Drive and inspect Android playtest transport.
2202
+
2203
+ ```ts
2204
+ export function discoverAdb(environment: NodeJS.ProcessEnv = process.env): string { … }
2205
+ ```
2206
+
2207
+ - **Use when:** run a scenario on an Android emulator or device · parse Android console diagnostics
2208
+ - **Constraints:** Android evidence must name its target and transport
2209
+
2210
+ ```ts
2211
+ const adb = discoverAdb(process.env);
2212
+ ```
2213
+
2214
+ ### `failedDiagnosticsAssertion`
2215
+
2216
+ `function` — Execute scenario steps, assertions, and evidence capture.
2217
+
2218
+ ```ts
2219
+ export function failedDiagnosticsAssertion(policy: IPlaytestDiagnosticsPolicy): IPlaytestAssertionResult { … }
2220
+ ```
2221
+
2222
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
2223
+ - **Constraints:** missing observations and malformed assertions fail closed
2224
+
2225
+ ```ts
2226
+ const report = await runStandalonePlaytest(options);
2227
+ ```
2228
+
2229
+ ### `formatUsage`
2230
+
2231
+ `function` — Parse standalone playtest runner configuration.
2232
+
2233
+ ```ts
2234
+ export function formatUsage(): string { … }
2235
+ ```
2236
+
2237
+ - **Use when:** invoke the playtest CLI from a scaffold · validate runner flags before launching a browser
2238
+ - **Constraints:** invalid flags throw a named usage error
2239
+
2240
+ ```ts
2241
+ const config = parseStandalonePlaytestArgs(argv);
2242
+ ```
2243
+
2244
+ ### `handlePlaytestSignal`
2245
+
2246
+ `function` — Execute scenario steps, assertions, and evidence capture.
2247
+
2248
+ ```ts
2249
+ export async function handlePlaytestSignal( teardown: (stopManagedServer: boolean) => Promise<void>, setExitCode: (code: number) => void = (code) => { … }
2250
+ ```
2251
+
2252
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
2253
+ - **Constraints:** missing observations and malformed assertions fail closed
2254
+
2255
+ ```ts
2256
+ const report = await runStandalonePlaytest(options);
2257
+ ```
2258
+
2259
+ ### `initStandalonePlaytest`
2260
+
2261
+ `function` — Initialize the standalone playtest files for a project.
2262
+
2263
+ ```ts
2264
+ export async function initStandalonePlaytest(projectPath = process.cwd()): Promise< { … }
2265
+ ```
2266
+
2267
+ - **Use when:** add the runner contract to a new game · create a starter scenario fixture
2268
+ - **Constraints:** generated scenarios must contain real assertions
2269
+
2270
+ ```ts
2271
+ await initStandalonePlaytest(projectPath);
2272
+ ```
2273
+
2274
+ ### `isRuntimeReadout`
2275
+
2276
+ `function` — Execute scenario steps, assertions, and evidence capture.
2277
+
2278
+ ```ts
2279
+ export function isRuntimeReadout(entry: unknown): boolean { … }
2280
+ ```
2281
+
2282
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
2283
+ - **Constraints:** missing observations and malformed assertions fail closed
2284
+
2285
+ ```ts
2286
+ const report = await runStandalonePlaytest(options);
2287
+ ```
2288
+
2289
+ ### `keyboardIsShown`
2290
+
2291
+ `function` — Drive and inspect Android playtest transport.
2292
+
2293
+ ```ts
2294
+ export function keyboardIsShown(dump: string): boolean { … }
2295
+ ```
2296
+
2297
+ - **Use when:** run a scenario on an Android emulator or device · parse Android console diagnostics
2298
+ - **Constraints:** Android evidence must name its target and transport
2299
+
2300
+ ```ts
2301
+ const adb = discoverAdb(process.env);
2302
+ ```
2303
+
2304
+ ### `LocalDeviceMailbox`
2305
+
2306
+ `class` — Drive a local desktop playtest mailbox.
2307
+
2308
+ ```ts
2309
+ export class LocalDeviceMailbox { … }
2310
+ ```
2311
+
2312
+ - **Use when:** run a desktop target through the playtest protocol · exchange observations with a native desktop host
2313
+ - **Constraints:** the mailbox lifecycle must be disposed after the run
2314
+
2315
+ ```ts
2316
+ const driver = new DesktopPlaytestDriver(options);
2317
+ ```
2318
+
2319
+ ### `ManagedServerError`
2320
+
2321
+ `class` — Execute scenario steps, assertions, and evidence capture.
2322
+
2323
+ ```ts
2324
+ export class ManagedServerError extends Error { … }
2325
+ ```
2326
+
2327
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
2328
+ - **Constraints:** missing observations and malformed assertions fail closed
2329
+
2330
+ ```ts
2331
+ const report = await runStandalonePlaytest(options);
2332
+ ```
2333
+
2334
+ ### `openPageAndConnectBridge`
2335
+
2336
+ `function` — Execute scenario steps, assertions, and evidence capture.
2337
+
2338
+ ```ts
2339
+ export async function openPageAndConnectBridge( page: Page, config: IStandalonePlaytestConfig, scenario: IPlaytestScenario, ): Promise<IPlaytestBridgeClient | undefined> { … }
2340
+ ```
2341
+
2342
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
2343
+ - **Constraints:** missing observations and malformed assertions fail closed
2344
+
2345
+ ```ts
2346
+ const report = await runStandalonePlaytest(options);
2347
+ ```
2348
+
2349
+ ### `pageLifecycleDiagnostic`
2350
+
2351
+ `function` — Execute scenario steps, assertions, and evidence capture.
2352
+
2353
+ ```ts
2354
+ export function pageLifecycleDiagnostic( error: unknown, lifecycle: IPageLifecycle, url: string, ): IPlaytestProtocolDiagnostic | undefined { … }
2355
+ ```
2356
+
2357
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
2358
+ - **Constraints:** missing observations and malformed assertions fail closed
2359
+
2360
+ ```ts
2361
+ const report = await runStandalonePlaytest(options);
2362
+ ```
2363
+
2364
+ ### `parseAndroidConsole`
2365
+
2366
+ `function` — Drive and inspect Android playtest transport.
2367
+
2368
+ ```ts
2369
+ export function parseAndroidConsole(output: string): Array< { … }
2370
+ ```
2371
+
2372
+ - **Use when:** run a scenario on an Android emulator or device · parse Android console diagnostics
2373
+ - **Constraints:** Android evidence must name its target and transport
2374
+
2375
+ ```ts
2376
+ const adb = discoverAdb(process.env);
2377
+ ```
2378
+
2379
+ ### `parseLaunchedPid`
2380
+
2381
+ `function` — Drive and inspect iOS simulator playtest transport.
2382
+
2383
+ ```ts
2384
+ export function parseLaunchedPid(output: string): string { … }
2385
+ ```
2386
+
2387
+ - **Use when:** run a scenario on the iOS simulator · parse the launched native process identifier
2388
+ - **Constraints:** simulator evidence does not claim physical-device proof
2389
+
2390
+ ```ts
2391
+ const driver = new XcrunIosDriver(options);
2392
+ ```
2393
+
2394
+ ### `parseStandalonePlaytestArgs`
2395
+
2396
+ `function` — Parse standalone playtest runner configuration.
2397
+
2398
+ ```ts
2399
+ export function parseStandalonePlaytestArgs(argv: readonly string[], cwd = process.cwd()): IStandalonePlaytestConfig { … }
2400
+ ```
2401
+
2402
+ - **Use when:** invoke the playtest CLI from a scaffold · validate runner flags before launching a browser
2403
+ - **Constraints:** invalid flags throw a named usage error
2404
+
2405
+ ```ts
2406
+ const config = parseStandalonePlaytestArgs(argv);
2407
+ ```
2408
+
2409
+ ### `PlaytestBridgeError`
2410
+
2411
+ `class` — Connect a Playwright page to a playtest bridge.
2412
+
2413
+ ```ts
2414
+ export class PlaytestBridgeError extends Error { … }
2415
+ ```
2416
+
2417
+ - **Use when:** run a browser scenario against a game · inspect bridge diagnostics from a runner
2418
+ - **Constraints:** the bridge must answer the handshake or the run fails
2419
+
2420
+ ```ts
2421
+ const bridge = await connectPlaytestBridge(page);
2422
+ ```
2423
+
2424
+ ### `PlaytestCliUsageError`
2425
+
2426
+ `class` — Parse standalone playtest runner configuration.
2427
+
2428
+ ```ts
2429
+ export class PlaytestCliUsageError extends Error { … }
2430
+ ```
2431
+
2432
+ - **Use when:** invoke the playtest CLI from a scaffold · validate runner flags before launching a browser
2433
+ - **Constraints:** invalid flags throw a named usage error
2434
+
2435
+ ```ts
2436
+ const config = parseStandalonePlaytestArgs(argv);
2437
+ ```
2438
+
2439
+ ### `playtestStepDrivesMovement`
2440
+
2441
+ `function` — Execute scenario steps, assertions, and evidence capture.
2442
+
2443
+ ```ts
2444
+ export function playtestStepDrivesMovement( step: IPlaytestScenario["steps"][number], hasHeldInput: boolean, ): boolean { … }
2445
+ ```
2446
+
2447
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
2448
+ - **Constraints:** missing observations and malformed assertions fail closed
2449
+
2450
+ ```ts
2451
+ const report = await runStandalonePlaytest(options);
2452
+ ```
2453
+
2454
+ ### `PlaywrightTransport`
2455
+
2456
+ `class` — Connect a Playwright page to a playtest bridge.
2457
+
2458
+ ```ts
2459
+ export class PlaywrightTransport implements IBridgeTransport { … }
2460
+ ```
2461
+
2462
+ - **Use when:** run a browser scenario against a game · inspect bridge diagnostics from a runner
2463
+ - **Constraints:** the bridge must answer the handshake or the run fails
2464
+
2465
+ ```ts
2466
+ const bridge = await connectPlaytestBridge(page);
2467
+ ```
2468
+
2469
+ ### `preflightDisplay`
2470
+
2471
+ `function` — Execute scenario steps, assertions, and evidence capture.
2472
+
2473
+ ```ts
2474
+ export function preflightDisplay( config: Pick<IStandalonePlaytestConfig, "headless">, scenario: Pick<IPlaytestScenario, "artifacts" | "assert" | "steps">, environment: NodeJS.ProcessEnv = process.env, platform = process.platform, ): IPlaytestDiagnostic | undefined { … }
2475
+ ```
2476
+
2477
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
2478
+ - **Constraints:** missing observations and malformed assertions fail closed
2479
+
2480
+ ```ts
2481
+ const report = await runStandalonePlaytest(options);
2482
+ ```
2483
+
2484
+ ### `reconcileBrowserPointers`
2485
+
2486
+ `function` — Select safe Chromium arguments for WebGPU playtests.
2487
+
2488
+ ```ts
2489
+ export function reconcileBrowserPointers( previous: ReadonlyMap<number, Required<IPlaytestPointer>>, next: readonly IPlaytestPointer[], ): IBrowserPointerChange[] { … }
2490
+ ```
2491
+
2492
+ - **Use when:** run a browser playtest with Vulkan WebGPU · reject a SwiftShader adapter as evidence
2493
+ - **Constraints:** inspect the adapter name before claiming GPU proof
2494
+
2495
+ ```ts
2496
+ const args = resolveBrowserArguments(undefined);
2497
+ ```
2498
+
2499
+ ### `recordToScenario`
2500
+
2501
+ `function` — Convert captured runner observations into a replay scenario.
2502
+
2503
+ ```ts
2504
+ export function recordToScenario( value: unknown, scenarioPath = "recording.json", oracleValue?: unknown, ): IPlaytestScenario { … }
2505
+ ```
2506
+
2507
+ - **Use when:** preserve a failing playtest as a replay fixture · require assertions before recording a scenario
2508
+ - **Constraints:** an empty assertion set is a failure
2509
+
2510
+ ```ts
2511
+ const scenario = recordToScenario(recording);
2512
+ ```
2513
+
2514
+ ### `requireAssertions`
2515
+
2516
+ `function` — Convert captured runner observations into a replay scenario.
2517
+
2518
+ ```ts
2519
+ export function requireAssertions( value: IPlaytestScenario["assert"], scenarioPath: string, ): NonNullable<IPlaytestScenario["assert"]> { … }
2520
+ ```
2521
+
2522
+ - **Use when:** preserve a failing playtest as a replay fixture · require assertions before recording a scenario
2523
+ - **Constraints:** an empty assertion set is a failure
2524
+
2525
+ ```ts
2526
+ const scenario = recordToScenario(recording);
2527
+ ```
2528
+
2529
+ ### `resolveBrowserArguments`
2530
+
2531
+ `function` — Select safe Chromium arguments for WebGPU playtests.
2532
+
2533
+ ```ts
2534
+ export function resolveBrowserArguments(browserArgs: readonly string[] | undefined): string[] { … }
2535
+ ```
2536
+
2537
+ - **Use when:** run a browser playtest with Vulkan WebGPU · reject a SwiftShader adapter as evidence
2538
+ - **Constraints:** inspect the adapter name before claiming GPU proof
2539
+
2540
+ ```ts
2541
+ const args = resolveBrowserArguments(undefined);
2542
+ ```
2543
+
2544
+ ### `resolveManagedServerCommand`
2545
+
2546
+ `function` — Execute scenario steps, assertions, and evidence capture.
2547
+
2548
+ ```ts
2549
+ export function resolveManagedServerCommand( config: IStandalonePlaytestConfig, dynamicPort?: number, ): string { … }
2550
+ ```
2551
+
2552
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
2553
+ - **Constraints:** missing observations and malformed assertions fail closed
2554
+
2555
+ ```ts
2556
+ const report = await runStandalonePlaytest(options);
2557
+ ```
2558
+
2559
+ ### `resolveManagedServerConfig`
2560
+
2561
+ `function` — Execute scenario steps, assertions, and evidence capture.
2562
+
2563
+ ```ts
2564
+ export async function resolveManagedServerConfig( config: IStandalonePlaytestConfig, ): Promise<IStandalonePlaytestConfig> { … }
2565
+ ```
2566
+
2567
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
2568
+ - **Constraints:** missing observations and malformed assertions fail closed
2569
+
2570
+ ```ts
2571
+ const report = await runStandalonePlaytest(options);
2572
+ ```
2573
+
2574
+ ### `rotatedTouchPosition`
2575
+
2576
+ `function` — Drive and inspect Android playtest transport.
2577
+
2578
+ ```ts
2579
+ export function rotatedTouchPosition(x: number, y: number, rotation: number): [number, number] { … }
2580
+ ```
2581
+
2582
+ - **Use when:** run a scenario on an Android emulator or device · parse Android console diagnostics
2583
+ - **Constraints:** Android evidence must name its target and transport
2584
+
2585
+ ```ts
2586
+ const adb = discoverAdb(process.env);
2587
+ ```
2588
+
2589
+ ### `runAndroidPlaytest`
2590
+
2591
+ `function` — Run a playtest on Android through the configured device transport.
2592
+
2593
+ ```ts
2594
+ export async function runAndroidPlaytest( config: IStandalonePlaytestConfig, dependencies: IAndroidPlaytestDependencies = { … }
2595
+ ```
2596
+
2597
+ - **Use when:** execute a scenario on an Android target · collect Android playtest artifacts
2598
+ - **Constraints:** the app bundle and device transport must be prepared
2599
+
2600
+ ```ts
2601
+ await runAndroidPlaytest(options);
2602
+ ```
2603
+
2604
+ ### `runDesktopPlaytest`
2605
+
2606
+ `function` — Run a desktop playtest and collect its report.
2607
+
2608
+ ```ts
2609
+ export async function runDesktopPlaytest( config: IStandalonePlaytestConfig, dependencies: IDesktopPlaytestDependencies = { … }
2610
+ ```
2611
+
2612
+ - **Use when:** execute a scenario against the desktop host · verify native desktop behavior from the same scenario
2613
+ - **Constraints:** the desktop host must be built before launching
2614
+
2615
+ ```ts
2616
+ await runDesktopPlaytest(options);
2617
+ ```
2618
+
2619
+ ### `runDevicePlaytest`
2620
+
2621
+ `function` — Run a playtest on Android through the configured device transport.
2622
+
2623
+ ```ts
2624
+ export async function runDevicePlaytest( config: IStandalonePlaytestConfig, target: IDevicePlaytestTarget, ): Promise<IStandalonePlaytestReport> { … }
2625
+ ```
2626
+
2627
+ - **Use when:** execute a scenario on an Android target · collect Android playtest artifacts
2628
+ - **Constraints:** the app bundle and device transport must be prepared
2629
+
2630
+ ```ts
2631
+ await runAndroidPlaytest(options);
2632
+ ```
2633
+
2634
+ ### `runIosPlaytest`
2635
+
2636
+ `function` — Run a playtest on the iOS simulator or device transport.
2637
+
2638
+ ```ts
2639
+ export async function runIosPlaytest( config: IStandalonePlaytestConfig, dependencies: IIosPlaytestDependencies = { … }
2640
+ ```
2641
+
2642
+ - **Use when:** execute a scenario on an iOS target · collect iOS playtest artifacts
2643
+ - **Constraints:** identify simulator versus physical transport in evidence
2644
+
2645
+ ```ts
2646
+ await runIosPlaytest(options);
2647
+ ```
2648
+
2649
+ ### `runStandalonePlaytest`
2650
+
2651
+ `function` — Execute scenario steps, assertions, and evidence capture.
2652
+
2653
+ ```ts
2654
+ export async function runStandalonePlaytest( config: IStandalonePlaytestConfig, options: IStandalonePlaytestRunOptions = { … }
2655
+ ```
2656
+
2657
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
2658
+ - **Constraints:** missing observations and malformed assertions fail closed
2659
+
2660
+ ```ts
2661
+ const report = await runStandalonePlaytest(options);
2662
+ ```
2663
+
2664
+ ### `runStandalonePlaytests`
2665
+
2666
+ `function` — Execute scenario steps, assertions, and evidence capture.
2667
+
2668
+ ```ts
2669
+ export async function runStandalonePlaytests( config: IStandalonePlaytestConfig, ): Promise<readonly IStandalonePlaytestReport[]> { … }
2670
+ ```
2671
+
2672
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
2673
+ - **Constraints:** missing observations and malformed assertions fail closed
2674
+
2675
+ ```ts
2676
+ const report = await runStandalonePlaytest(options);
2677
+ ```
2678
+
2679
+ ### `softwareAdapterName`
2680
+
2681
+ `function` — Select safe Chromium arguments for WebGPU playtests.
2682
+
2683
+ ```ts
2684
+ export function softwareAdapterName(adapter: Readonly<Record<string, string>> | undefined): string | undefined { … }
2685
+ ```
2686
+
2687
+ - **Use when:** run a browser playtest with Vulkan WebGPU · reject a SwiftShader adapter as evidence
2688
+ - **Constraints:** inspect the adapter name before claiming GPU proof
2689
+
2690
+ ```ts
2691
+ const args = resolveBrowserArguments(undefined);
2692
+ ```
2693
+
2694
+ ### `substituteManagedPort`
2695
+
2696
+ `function` — Execute scenario steps, assertions, and evidence capture.
2697
+
2698
+ ```ts
2699
+ export function substituteManagedPort(command: string, port: number): string { … }
2700
+ ```
2701
+
2702
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
2703
+ - **Constraints:** missing observations and malformed assertions fail closed
2704
+
2705
+ ```ts
2706
+ const report = await runStandalonePlaytest(options);
2707
+ ```
2708
+
2709
+ ### `tapCommand`
2710
+
2711
+ `function` — Drive and inspect Android playtest transport.
2712
+
2713
+ ```ts
2714
+ export function tapCommand(x: number, y: number): string[] { … }
2715
+ ```
2716
+
2717
+ - **Use when:** run a scenario on an Android emulator or device · parse Android console diagnostics
2718
+ - **Constraints:** Android evidence must name its target and transport
2719
+
2720
+ ```ts
2721
+ const adb = discoverAdb(process.env);
2722
+ ```
2723
+
2724
+ ### `touchRotationFromWindowDump`
2725
+
2726
+ `function` — Drive and inspect Android playtest transport.
2727
+
2728
+ ```ts
2729
+ export function touchRotationFromWindowDump(dump: string): number | undefined { … }
2730
+ ```
2731
+
2732
+ - **Use when:** run a scenario on an Android emulator or device · parse Android console diagnostics
2733
+ - **Constraints:** Android evidence must name its target and transport
2734
+
2735
+ ```ts
2736
+ const adb = discoverAdb(process.env);
2737
+ ```
2738
+
2739
+ ### `validateDeviceEndpoint`
2740
+
2741
+ `function` — Resolve a native device transport and its mailbox paths.
2742
+
2743
+ ```ts
2744
+ export function validateDeviceEndpoint(value: string): URL { … }
2745
+ ```
2746
+
2747
+ - **Use when:** connect a native host to the playtest runner · validate an Android or iOS device endpoint
2748
+ - **Constraints:** paths stay inside the managed artifact directory
2749
+
2750
+ ```ts
2751
+ const paths = deviceMailboxPaths(projectRoot);
2752
+ ```
2753
+
2754
+ ### `viewportPresentationCommands`
2755
+
2756
+ `function` — Drive and inspect Android playtest transport.
2757
+
2758
+ ```ts
2759
+ export function viewportPresentationCommands( viewport: { … }
2760
+ ```
2761
+
2762
+ - **Use when:** run a scenario on an Android emulator or device · parse Android console diagnostics
2763
+ - **Constraints:** Android evidence must name its target and transport
2764
+
2765
+ ```ts
2766
+ const adb = discoverAdb(process.env);
2767
+ ```
2768
+
2769
+ ### `viewportRestoreCommands`
2770
+
2771
+ `function` — Drive and inspect Android playtest transport.
2772
+
2773
+ ```ts
2774
+ export function viewportRestoreCommands(): string[][] { … }
2775
+ ```
2776
+
2777
+ - **Use when:** run a scenario on an Android emulator or device · parse Android console diagnostics
2778
+ - **Constraints:** Android evidence must name its target and transport
2779
+
2780
+ ```ts
2781
+ const adb = discoverAdb(process.env);
2782
+ ```
2783
+
2784
+ ### `writeCaptureProvenance`
2785
+
2786
+ `function` — Execute scenario steps, assertions, and evidence capture.
2787
+
2788
+ ```ts
2789
+ export async function writeCaptureProvenance( artifactDirectory: string, provenance: IPlaytestCaptureProvenance, ): Promise<void> { … }
2790
+ ```
2791
+
2792
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
2793
+ - **Constraints:** missing observations and malformed assertions fail closed
2794
+
2795
+ ```ts
2796
+ const report = await runStandalonePlaytest(options);
2797
+ ```
2798
+
2799
+ ### `writeObservationArtifacts`
2800
+
2801
+ `function` — Execute scenario steps, assertions, and evidence capture.
2802
+
2803
+ ```ts
2804
+ export async function writeObservationArtifacts( artifactDirectory: string, requested: IPlaytestArtifactRequest | undefined, observations: { … }
2805
+ ```
2806
+
2807
+ - **Use when:** run a complete browser or device playtest · capture diagnostics and screenshots from a managed server
2808
+ - **Constraints:** missing observations and malformed assertions fail closed
2809
+
2810
+ ```ts
2811
+ const report = await runStandalonePlaytest(options);
2812
+ ```
2813
+
2814
+ ### `XcrunIosDriver`
2815
+
2816
+ `class` — Drive and inspect iOS simulator playtest transport.
2817
+
2818
+ ```ts
2819
+ export class XcrunIosDriver implements IDevicePlaytestDriver { … }
2820
+ ```
2821
+
2822
+ - **Use when:** run a scenario on the iOS simulator · parse the launched native process identifier
2823
+ - **Constraints:** simulator evidence does not claim physical-device proof
2824
+
2825
+ ```ts
2826
+ const driver = new XcrunIosDriver(options);
2827
+ ```
2828
+
2829
+ ## `@threenative/playtest/three`
2830
+
2831
+ ### `adviseThreeRenderWorkload`
2832
+
2833
+ `function` — Explain which render workloads should be collapsed or retained.
2834
+
2835
+ ```ts
2836
+ export function adviseThreeRenderWorkload(input: IRenderAdvisorInput): IRenderAdvisorReport { … }
2837
+ ```
2838
+
2839
+ - **Use when:** diagnose a slow Three.js scene · choose a render optimization from observed workload data
2840
+ - **Constraints:** use measured input rather than visual guesses
2841
+
2842
+ ```ts
2843
+ const advice = adviseThreeRenderWorkload(input);
2844
+ ```
2845
+
2846
+ ### `connectDevicePlaytestBridge`
2847
+
2848
+ `function` — Connect a device-hosted game to the playtest bridge.
2849
+
2850
+ ```ts
2851
+ export function connectDevicePlaytestBridge( bridge: IPlaytestBridgeV1, endpoint: string, ): IDeviceBridgeInstallation { … }
2852
+ ```
2853
+
2854
+ - **Use when:** run the same playtest on an Android or iOS target · read the device bridge endpoint
2855
+ - **Constraints:** use the device transport selected by the runner
2856
+
2857
+ ```ts
2858
+ const connection = await connectDevicePlaytestBridge();
2859
+ ```
2860
+
2861
+ ### `installThreePlaytestBridge`
2862
+
2863
+ `function` — Install the playtest observation bridge for a plain Three.js game.
2864
+
2865
+ ```ts
2866
+ export function installThreePlaytestBridge(options: IThreePlaytestBridgeOptions): IThreePlaytestBridgeInstallation { … }
2867
+ ```
2868
+
2869
+ - **Use when:** expose a non-ThreeNative game to the scenario runner · add semantic observations to a browser playtest
2870
+ - **Constraints:** install once before the runner connects
2871
+
2872
+ ```ts
2873
+ const bridge = installThreePlaytestBridge(options);
2874
+ ```
2875
+
2876
+ ### `readPlaytestEndpoint`
2877
+
2878
+ `function` — Connect a device-hosted game to the playtest bridge.
2879
+
2880
+ ```ts
2881
+ export function readPlaytestEndpoint(): string | undefined { … }
2882
+ ```
2883
+
2884
+ - **Use when:** run the same playtest on an Android or iOS target · read the device bridge endpoint
2885
+ - **Constraints:** use the device transport selected by the runner
2886
+
2887
+ ```ts
2888
+ const connection = await connectDevicePlaytestBridge();
2889
+ ```
2890
+
2891
+ ### `ThreePlaytestPhysicsRecorder`
2892
+
2893
+ `class` — Record Three.js physics bodies for playtest observations.
2894
+
2895
+ ```ts
2896
+ export class ThreePlaytestPhysicsRecorder { … }
2897
+ ```
2898
+
2899
+ - **Use when:** assert physics contacts in a plain Three.js game · capture bounded body state for a scenario
2900
+ - **Constraints:** keep recorder limits within the documented caps
2901
+
2902
+ ```ts
2903
+ const physics = new ThreePlaytestPhysicsRecorder();
2904
+ ```
2905
+
2906
+ ## `@threenative/template/starter/src/render/effects/gradualBackground`
2907
+
2908
+ ### `gradualBackground`
2909
+
2910
+ `function` — ThreeNative equivalent for realism-effects gradualBackground.
2911
+
2912
+ ```ts
2913
+ function gradualBackground
2914
+ ```
2915
+
2916
+ - **Use when:** grade a background by distance
2917
+ - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
2918
+
2919
+ ```ts
2920
+ gradualBackground(...)
2921
+ ```
2922
+
2923
+ ## `@threenative/template/starter/src/render/effects/lensDistortion`
2924
+
2925
+ ### `lensDistortion`
2926
+
2927
+ `function` — ThreeNative equivalent for realism-effects lensDistortion.
2928
+
2929
+ ```ts
2930
+ function lensDistortion
2931
+ ```
2932
+
2933
+ - **Use when:** warp the image with radial lens distortion
2934
+ - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
2935
+
2936
+ ```ts
2937
+ lensDistortion(...)
2938
+ ```
2939
+
2940
+ ## `@threenative/template/starter/src/render/effects/sparkle`
2941
+
2942
+ ### `sparkle`
2943
+
2944
+ `function` — ThreeNative equivalent for realism-effects sparkle.
2945
+
2946
+ ```ts
2947
+ function sparkle
2948
+ ```
2949
+
2950
+ - **Use when:** add glints to bright highlights
2951
+ - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
2952
+
2953
+ ```ts
2954
+ sparkle(...)
2955
+ ```
2956
+
2957
+ ## `@threenative/ui`
2958
+
2959
+ ### `DebugOverlay`
2960
+
2961
+ `function` — Show framework diagnostics while developing a game.
2962
+
2963
+ ```ts
2964
+ export function DebugOverlay() { … }
2965
+ ```
2966
+
2967
+ - **Use when:** display runtime and playtest diagnostics in a React HUD · inspect a game without changing its scene
2968
+
2969
+ ```ts
2970
+ <DebugOverlay game={game} />
2971
+ ```
2972
+
2973
+ ### `GameCanvas`
2974
+
2975
+ `function` — Mount a ThreeNative game in a React canvas.
2976
+
2977
+ ```ts
2978
+ export function GameCanvas<TState extends Record<string, unknown>, TPhysics>( { … }
2979
+ ```
2980
+
2981
+ - **Use when:** add a game viewport to a React application · connect a game canvas to the web UI shell
2982
+ - **Constraints:** keep the portable game entry free of React DOM code
2983
+
2984
+ ```ts
2985
+ <GameCanvas game={game} />
2986
+ ```
2987
+
2988
+ ### `UiLayer`
2989
+
2990
+ `function` — Render a game's UI so the same source runs on web and on every native target.
2991
+
2992
+ ```ts
2993
+ export function UiLayer( { … }
2994
+ ```
2995
+
2996
+ - **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
2997
+ - **Constraints:** mark every control the player touches with data-tn-interactive
2998
+
2999
+ ```ts
3000
+ <UiLayer><Hud /></UiLayer>
3001
+ ```
3002
+
3003
+ ### `useGameState`
3004
+
3005
+ `function` — Read throttled game state from React.
3006
+
3007
+ ```ts
3008
+ export function useGameState<TState extends Record<string, unknown>, TPhysics, TSelected>( game: IGame<TState, TPhysics>, selector: GameSelector<TState, TSelected>, ): TSelected;
3009
+ ```
3010
+
3011
+ - **Use when:** bind a HUD component to game state · select a slice of state for a React panel
3012
+ - **Constraints:** use this hook only from the web UI entry
3013
+
3014
+ ```ts
3015
+ const score = useGameState(game, (state) => state.score);
3016
+ ```
3017
+
3018
+ ### `useUiIntent`
3019
+
3020
+ `function` — Send a player action from the UI back to the game.
3021
+
3022
+ ```ts
3023
+ export function useUiIntent(): (intent: string, payload?: unknown) => void { … }
3024
+ ```
3025
+
3026
+ - **Use when:** wire a Restart button in a HUD to the running game · pause a game from a menu rendered over its surface
3027
+ - **Constraints:** the game decides what each intent name means; it may ignore one
3028
+
3029
+ ```ts
3030
+ const send = useUiIntent(); send("restart");
3031
+ ```
3032
+
3033
+ ### `useUiState`
3034
+
3035
+ `function` — Read the game's published state from a UI that may be in another process.
3036
+
3037
+ ```ts
3038
+ export function useUiState<TState extends object>(): TState | undefined;
3039
+ ```
3040
+
3041
+ - **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
3042
+ - **Constraints:** returns undefined until the game publishes its first state
3043
+
3044
+ ```ts
3045
+ const score = useUiState((state) => state.score);
3046
+ ```
3047
+
3048
+ ## `three/addons/tsl/display/DenoiseNode.js`
3049
+
3050
+ ### `DenoiseNode`
3051
+
3052
+ `class` — ThreeNative equivalent for realism-effects DenoiseNode.
3053
+
3054
+ ```ts
3055
+ class DenoiseNode
3056
+ ```
3057
+
3058
+ - **Use when:** denoise a noisy screen-space pass
3059
+ - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
3060
+
3061
+ ```ts
3062
+ DenoiseNode(...)
3063
+ ```
3064
+
3065
+ ## `three/addons/tsl/display/MotionBlur.js`
3066
+
3067
+ ### `motionBlur`
3068
+
3069
+ `function` — ThreeNative equivalent for realism-effects motionBlur.
3070
+
3071
+ ```ts
3072
+ function motionBlur
3073
+ ```
3074
+
3075
+ - **Use when:** blur motion using a velocity buffer
3076
+ - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
3077
+
3078
+ ```ts
3079
+ motionBlur(...)
3080
+ ```
3081
+
3082
+ ## `three/addons/tsl/display/RecurrentDenoiseNode.js`
3083
+
3084
+ ### `RecurrentDenoiseNode`
3085
+
3086
+ `class` — ThreeNative equivalent for realism-effects RecurrentDenoiseNode.
3087
+
3088
+ ```ts
3089
+ class RecurrentDenoiseNode
3090
+ ```
3091
+
3092
+ - **Use when:** denoise a noisy screen-space pass
3093
+ - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
3094
+
3095
+ ```ts
3096
+ RecurrentDenoiseNode(...)
3097
+ ```
3098
+
3099
+ ## `three/addons/tsl/display/SharpenNode.js`
3100
+
3101
+ ### `SharpenNode`
3102
+
3103
+ `class` — ThreeNative equivalent for realism-effects SharpenNode.
3104
+
3105
+ ```ts
3106
+ class SharpenNode
3107
+ ```
3108
+
3109
+ - **Use when:** make the image sharper
3110
+ - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
3111
+
3112
+ ```ts
3113
+ SharpenNode(...)
3114
+ ```
3115
+
3116
+ ## `three/addons/tsl/display/SSAAPassNode.js`
3117
+
3118
+ ### `SSAAPassNode`
3119
+
3120
+ `class` — ThreeNative equivalent for realism-effects SSAAPassNode.
3121
+
3122
+ ```ts
3123
+ class SSAAPassNode
3124
+ ```
3125
+
3126
+ - **Use when:** anti-alias still and moving scenes
3127
+ - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
3128
+
3129
+ ```ts
3130
+ SSAAPassNode(...)
3131
+ ```
3132
+
3133
+ ## `three/addons/tsl/display/SSGINode.js`
3134
+
3135
+ ### `SSGINode`
3136
+
3137
+ `class` — ThreeNative equivalent for realism-effects SSGINode.
3138
+
3139
+ ```ts
3140
+ class SSGINode
3141
+ ```
3142
+
3143
+ - **Use when:** add screen-space global illumination
3144
+ - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
3145
+
3146
+ ```ts
3147
+ SSGINode(...)
3148
+ ```
3149
+
3150
+ ## `three/addons/tsl/display/SSRNode.js`
3151
+
3152
+ ### `SSRNode`
3153
+
3154
+ `class` — ThreeNative equivalent for realism-effects SSRNode.
3155
+
3156
+ ```ts
3157
+ class SSRNode
3158
+ ```
3159
+
3160
+ - **Use when:** add screen-space reflections
3161
+ - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
3162
+
3163
+ ```ts
3164
+ SSRNode(...)
3165
+ ```
3166
+
3167
+ ## `three/addons/tsl/display/TemporalReprojectNode.js`
3168
+
3169
+ ### `TemporalReprojectNode`
3170
+
3171
+ `class` — ThreeNative equivalent for realism-effects TemporalReprojectNode.
3172
+
3173
+ ```ts
3174
+ class TemporalReprojectNode
3175
+ ```
3176
+
3177
+ - **Use when:** reproject a temporal history
3178
+ - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
3179
+
3180
+ ```ts
3181
+ TemporalReprojectNode(...)
3182
+ ```
3183
+
3184
+ ## `three/addons/tsl/display/TRAANode.js`
3185
+
3186
+ ### `TRAANode`
3187
+
3188
+ `class` — ThreeNative equivalent for realism-effects TRAANode.
3189
+
3190
+ ```ts
3191
+ class TRAANode
3192
+ ```
3193
+
3194
+ - **Use when:** temporally resolve a moving image
3195
+ - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
3196
+
3197
+ ```ts
3198
+ TRAANode(...)
3199
+ ```
3200
+
3201
+ ## `three/tsl`
3202
+
3203
+ ### `depth`
3204
+
3205
+ `function` — ThreeNative equivalent for realism-effects depth.
3206
+
3207
+ ```ts
3208
+ function depth
3209
+ ```
3210
+
3211
+ - **Use when:** provide depth to screen-space effects
3212
+ - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
3213
+
3214
+ ```ts
3215
+ depth(...)
3216
+ ```
3217
+
3218
+ ### `mrt`
3219
+
3220
+ `function` — ThreeNative equivalent for realism-effects mrt.
3221
+
3222
+ ```ts
3223
+ function mrt
3224
+ ```
3225
+
3226
+ - **Use when:** provision velocity, normal, and depth render targets
3227
+ - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
3228
+
3229
+ ```ts
3230
+ mrt(...)
3231
+ ```
3232
+
3233
+ ### `normal`
3234
+
3235
+ `function` — ThreeNative equivalent for realism-effects normal.
3236
+
3237
+ ```ts
3238
+ function normal
3239
+ ```
3240
+
3241
+ - **Use when:** provide normals to screen-space effects
3242
+ - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
3243
+
3244
+ ```ts
3245
+ normal(...)
3246
+ ```
3247
+
3248
+ ### `velocity`
3249
+
3250
+ `function` — ThreeNative equivalent for realism-effects velocity.
3251
+
3252
+ ```ts
3253
+ function velocity
3254
+ ```
3255
+
3256
+ - **Use when:** provide motion vectors to temporal effects
3257
+ - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
3258
+
3259
+ ```ts
3260
+ velocity(...)
3261
+ ```
3262
+
3263
+ ## `three/webgpu`
3264
+
3265
+ ### `VelocityNode`
3266
+
3267
+ `class` — ThreeNative equivalent for realism-effects VelocityNode.
3268
+
3269
+ ```ts
3270
+ class VelocityNode
3271
+ ```
3272
+
3273
+ - **Use when:** provide motion vectors to temporal effects
3274
+ - **Constraints:** Use the running WebGPU renderer and keep appearance choices in template render source.
3275
+
3276
+ ```ts
3277
+ VelocityNode(...)
3278
+ ```
3279
+