create-threenative 0.2.8 → 0.2.10

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 (431) hide show
  1. package/agent-docs/references/assertion-reference.md +87 -35
  2. package/agent-docs/references/auto-exposure.md +57 -0
  3. package/agent-docs/references/capability-reference.md +1097 -23
  4. package/agent-docs/references/debug-surface.md +6 -0
  5. package/agent-docs/references/finding-assets.md +46 -10
  6. package/agent-docs/references/performance-basics.md +5 -4
  7. package/agent-docs/references/terrain-authoring.md +140 -0
  8. package/agent-files/.agents/skills/threenative-assets/SKILL.md +2 -1
  9. package/capabilities.json +1210 -27
  10. package/dist/index.d.ts +28 -3
  11. package/dist/index.js +396 -166
  12. package/dist/threenative.js +986 -235
  13. package/dist/web-engine-buffer-geometry-utils.js +281 -0
  14. package/dist/web-engine-decal-geometry.js +184 -0
  15. package/dist/web-engine-gltf-loader.js +196 -0
  16. package/dist/web-engine-hdr-loader.js +190 -0
  17. package/dist/web-engine-lut-cube-loader.js +122 -0
  18. package/dist/web-engine-mesh-bvh-webgpu.js +29 -0
  19. package/dist/web-engine-mesh-bvh.js +32 -0
  20. package/dist/web-engine-post-effects.js +168 -0
  21. package/dist/web-engine-runtime.js +42506 -0
  22. package/package.json +11 -8
  23. package/template-assets/autoExposure.ts +225 -0
  24. package/template-assets/exposure.ts +111 -0
  25. package/template-assets/exposureGraph.ts +178 -0
  26. package/template-assets/exposureReadback.ts +79 -0
  27. package/template-assets/patches/@tailwindcss__node@4.3.3.patch +22 -0
  28. package/template-assets/patches/three@0.185.1.patch +6594 -700
  29. package/template-assets/patches/vite@8.2.0.patch +422 -0
  30. package/template-assets/worldEnvironment.ts +433 -30
  31. package/templates/action-rpg/AGENTS.md +11 -10
  32. package/templates/action-rpg/CLAUDE.md +11 -10
  33. package/templates/action-rpg/package.json +13 -10
  34. package/templates/action-rpg/playtests/performance.playtest.json +7 -1
  35. package/templates/action-rpg/src/progress.ts +0 -4
  36. package/templates/action-rpg/src/render/autoExposure.ts +225 -0
  37. package/templates/action-rpg/src/render/backlightControls.ts +66 -0
  38. package/templates/action-rpg/src/render/backlightMaterial.ts +147 -0
  39. package/templates/action-rpg/src/render/environmentContribution.ts +188 -0
  40. package/templates/action-rpg/src/render/environmentRadiance.ts +36 -0
  41. package/templates/action-rpg/src/render/environmentSampleCache.ts +43 -0
  42. package/templates/action-rpg/src/render/environmentSampling.ts +193 -0
  43. package/templates/action-rpg/src/render/environmentSnapshot.ts +53 -0
  44. package/templates/action-rpg/src/render/exposure.ts +111 -0
  45. package/templates/action-rpg/src/render/exposureGraph.ts +178 -0
  46. package/templates/action-rpg/src/render/exposureReadback.ts +79 -0
  47. package/templates/action-rpg/src/render/heightFog.ts +118 -0
  48. package/templates/action-rpg/src/render/lighting.ts +26 -1
  49. package/templates/action-rpg/src/render/materialAssignments.ts +160 -0
  50. package/templates/action-rpg/src/render/materialLighting.ts +155 -0
  51. package/templates/action-rpg/src/render/postprocessing.ts +17 -2
  52. package/templates/action-rpg/src/render/quality.ts +61 -2
  53. package/templates/action-rpg/src/render/sky.ts +21 -1
  54. package/templates/action-rpg/src/render/vfx.ts +133 -58
  55. package/templates/action-rpg/src/render/worldEnvironment.ts +433 -30
  56. package/templates/action-rpg/src/scenes/Play.ts +81 -16
  57. package/templates/action-rpg/threenative.config.ts +3 -0
  58. package/templates/action-rpg/vite.config.ts +10 -2
  59. package/templates/minimal/AGENTS.md +9 -10
  60. package/templates/minimal/CLAUDE.md +9 -10
  61. package/templates/minimal/package.json +11 -9
  62. package/templates/minimal/playtests/play.playtest.json +7 -1
  63. package/templates/minimal/playtests/sky.playtest.json +10 -1
  64. package/templates/minimal/src/render/autoExposure.ts +225 -0
  65. package/templates/minimal/src/render/backlightControls.ts +66 -0
  66. package/templates/minimal/src/render/backlightMaterial.ts +147 -0
  67. package/templates/minimal/src/render/environmentContribution.ts +188 -0
  68. package/templates/minimal/src/render/environmentRadiance.ts +36 -0
  69. package/templates/minimal/src/render/environmentSampleCache.ts +43 -0
  70. package/templates/minimal/src/render/environmentSampling.ts +193 -0
  71. package/templates/minimal/src/render/environmentSnapshot.ts +53 -0
  72. package/templates/minimal/src/render/exposure.ts +111 -0
  73. package/templates/minimal/src/render/exposureGraph.ts +178 -0
  74. package/templates/minimal/src/render/exposureReadback.ts +79 -0
  75. package/templates/minimal/src/render/heightFog.ts +118 -0
  76. package/templates/minimal/src/render/lighting.ts +25 -1
  77. package/templates/minimal/src/render/materialAssignments.ts +102 -0
  78. package/templates/minimal/src/render/materialLighting.ts +146 -0
  79. package/templates/minimal/src/render/postprocessing.ts +16 -2
  80. package/templates/minimal/src/render/quality.ts +60 -2
  81. package/templates/minimal/src/render/sky.ts +21 -1
  82. package/templates/minimal/src/render/worldEnvironment.ts +433 -30
  83. package/templates/minimal/src/scenes/Play.ts +50 -1
  84. package/templates/minimal/vite.config.ts +10 -2
  85. package/templates/platformer/AGENTS.md +7 -5
  86. package/templates/platformer/CLAUDE.md +7 -5
  87. package/templates/platformer/package.json +13 -10
  88. package/templates/platformer/playtests/performance.playtest.json +7 -1
  89. package/templates/platformer/src/render/autoExposure.ts +225 -0
  90. package/templates/platformer/src/render/backlightControls.ts +66 -0
  91. package/templates/platformer/src/render/backlightMaterial.ts +147 -0
  92. package/templates/platformer/src/render/environmentContribution.ts +188 -0
  93. package/templates/platformer/src/render/environmentRadiance.ts +36 -0
  94. package/templates/platformer/src/render/environmentSampleCache.ts +43 -0
  95. package/templates/platformer/src/render/environmentSampling.ts +193 -0
  96. package/templates/platformer/src/render/environmentSnapshot.ts +53 -0
  97. package/templates/platformer/src/render/exposure.ts +111 -0
  98. package/templates/platformer/src/render/exposureGraph.ts +178 -0
  99. package/templates/platformer/src/render/exposureReadback.ts +79 -0
  100. package/templates/platformer/src/render/heightFog.ts +118 -0
  101. package/templates/platformer/src/render/lighting.ts +26 -1
  102. package/templates/platformer/src/render/materialAssignments.ts +160 -0
  103. package/templates/platformer/src/render/materialLighting.ts +155 -0
  104. package/templates/platformer/src/render/materials.ts +7 -2
  105. package/templates/platformer/src/render/palette.ts +3 -3
  106. package/templates/platformer/src/render/postprocessing.ts +17 -2
  107. package/templates/platformer/src/render/quality.ts +61 -2
  108. package/templates/platformer/src/render/sky.ts +72 -23
  109. package/templates/platformer/src/render/skyEnvironment.ts +50 -0
  110. package/templates/platformer/src/render/worldEnvironment.ts +433 -30
  111. package/templates/platformer/src/scenes/Play.ts +70 -6
  112. package/templates/platformer/vite.config.ts +10 -2
  113. package/templates/puzzle/AGENTS.md +10 -9
  114. package/templates/puzzle/CLAUDE.md +10 -9
  115. package/templates/puzzle/package.json +13 -10
  116. package/templates/puzzle/playtests/boot-failure.playtest.json +2 -2
  117. package/templates/puzzle/playtests/lit.playtest.json +7 -1
  118. package/templates/puzzle/playtests/performance.playtest.json +7 -1
  119. package/templates/puzzle/src/render/autoExposure.ts +225 -0
  120. package/templates/puzzle/src/render/backlightControls.ts +66 -0
  121. package/templates/puzzle/src/render/backlightMaterial.ts +147 -0
  122. package/templates/puzzle/src/render/environmentContribution.ts +188 -0
  123. package/templates/puzzle/src/render/environmentRadiance.ts +36 -0
  124. package/templates/puzzle/src/render/environmentSampleCache.ts +43 -0
  125. package/templates/puzzle/src/render/environmentSampling.ts +193 -0
  126. package/templates/puzzle/src/render/environmentSnapshot.ts +53 -0
  127. package/templates/puzzle/src/render/exposure.ts +111 -0
  128. package/templates/puzzle/src/render/exposureGraph.ts +178 -0
  129. package/templates/puzzle/src/render/exposureReadback.ts +79 -0
  130. package/templates/puzzle/src/render/heightFog.ts +118 -0
  131. package/templates/puzzle/src/render/lighting.ts +33 -1
  132. package/templates/puzzle/src/render/materialAssignments.ts +160 -0
  133. package/templates/puzzle/src/render/materialLighting.ts +155 -0
  134. package/templates/puzzle/src/render/materials.ts +1 -1
  135. package/templates/puzzle/src/render/postprocessing.ts +8 -2
  136. package/templates/puzzle/src/render/quality.ts +62 -1
  137. package/templates/puzzle/src/render/sky.ts +20 -1
  138. package/templates/puzzle/src/render/worldEnvironment.ts +433 -30
  139. package/templates/puzzle/src/scenes/Play.ts +51 -2
  140. package/templates/puzzle/vite.config.ts +10 -2
  141. package/templates/racing/AGENTS.md +8 -7
  142. package/templates/racing/CLAUDE.md +8 -7
  143. package/templates/racing/package.json +13 -10
  144. package/templates/racing/playtests/performance.playtest.json +7 -1
  145. package/templates/racing/playtests/survives.playtest.json +6 -0
  146. package/templates/racing/src/render/autoExposure.ts +225 -0
  147. package/templates/racing/src/render/backlightControls.ts +66 -0
  148. package/templates/racing/src/render/backlightMaterial.ts +147 -0
  149. package/templates/racing/src/render/environmentContribution.ts +188 -0
  150. package/templates/racing/src/render/environmentRadiance.ts +36 -0
  151. package/templates/racing/src/render/environmentSampleCache.ts +43 -0
  152. package/templates/racing/src/render/environmentSampling.ts +193 -0
  153. package/templates/racing/src/render/environmentSnapshot.ts +53 -0
  154. package/templates/racing/src/render/exposure.ts +111 -0
  155. package/templates/racing/src/render/exposureGraph.ts +178 -0
  156. package/templates/racing/src/render/exposureReadback.ts +79 -0
  157. package/templates/racing/src/render/heightFog.ts +118 -0
  158. package/templates/racing/src/render/lighting.ts +29 -1
  159. package/templates/racing/src/render/materialAssignments.ts +160 -0
  160. package/templates/racing/src/render/materialLighting.ts +155 -0
  161. package/templates/racing/src/render/palette.ts +1 -10
  162. package/templates/racing/src/render/postprocessing.ts +17 -2
  163. package/templates/racing/src/render/quality.ts +61 -2
  164. package/templates/racing/src/render/shapes.ts +0 -25
  165. package/templates/racing/src/render/sky.ts +25 -5
  166. package/templates/racing/src/render/worldEnvironment.ts +433 -30
  167. package/templates/racing/src/scenes/Race.ts +110 -13
  168. package/templates/racing/src/track/circuit.ts +0 -9
  169. package/templates/racing/vite.config.ts +10 -2
  170. package/templates/rain/AGENTS.md +8 -9
  171. package/templates/rain/CLAUDE.md +8 -9
  172. package/templates/rain/native-playtests/boot.playtest.json +11 -1
  173. package/templates/rain/package.json +14 -10
  174. package/templates/rain/playtests/automation.playtest.json +1 -1
  175. package/templates/rain/playtests/performance.playtest.json +11 -1
  176. package/templates/rain/playtests/tiers.playtest.json +15 -0
  177. package/templates/rain/playtests/weather.playtest.json +1 -1
  178. package/templates/rain/src/game.ts +1 -34
  179. package/templates/rain/src/render/autoExposure.ts +225 -0
  180. package/templates/rain/src/render/exposure.ts +111 -0
  181. package/templates/rain/src/render/exposureGraph.ts +178 -0
  182. package/templates/rain/src/render/exposureReadback.ts +79 -0
  183. package/templates/rain/src/render/postprocessing.ts +3 -0
  184. package/templates/rain/src/render/quality.ts +27 -1
  185. package/templates/rain/src/render/worldEnvironment.ts +433 -30
  186. package/templates/rain/src/scenes/Boot.ts +14 -0
  187. package/templates/rain/src/state.ts +5 -1
  188. package/templates/rain/src/ui/GameUi.tsx +6 -6
  189. package/templates/rain/tools/generate-shaders.mjs +1 -1
  190. package/templates/rain/vite.config.ts +10 -2
  191. package/templates/rts/AGENTS.md +10 -11
  192. package/templates/rts/CLAUDE.md +10 -11
  193. package/templates/rts/package.json +12 -9
  194. package/templates/rts/playtests/performance.playtest.json +7 -1
  195. package/templates/rts/playtests/rts-ai-attack.playtest.json +10 -1
  196. package/templates/rts/playtests/rts-attack.playtest.json +10 -1
  197. package/templates/rts/playtests/rts-build.playtest.json +10 -1
  198. package/templates/rts/playtests/rts-orders.playtest.json +7 -1
  199. package/templates/rts/playtests/rts-train.playtest.json +10 -1
  200. package/templates/rts/src/render/army.ts +10 -2
  201. package/templates/rts/src/render/autoExposure.ts +225 -0
  202. package/templates/rts/src/render/backlightControls.ts +66 -0
  203. package/templates/rts/src/render/backlightMaterial.ts +147 -0
  204. package/templates/rts/src/render/environmentContribution.ts +188 -0
  205. package/templates/rts/src/render/environmentRadiance.ts +36 -0
  206. package/templates/rts/src/render/environmentSampleCache.ts +43 -0
  207. package/templates/rts/src/render/environmentSampling.ts +193 -0
  208. package/templates/rts/src/render/environmentSnapshot.ts +53 -0
  209. package/templates/rts/src/render/exposure.ts +111 -0
  210. package/templates/rts/src/render/exposureGraph.ts +178 -0
  211. package/templates/rts/src/render/exposureReadback.ts +79 -0
  212. package/templates/rts/src/render/heightFog.ts +118 -0
  213. package/templates/rts/src/render/lighting.ts +26 -1
  214. package/templates/rts/src/render/materialAssignments.ts +160 -0
  215. package/templates/rts/src/render/materialLighting.ts +155 -0
  216. package/templates/rts/src/render/postprocessing.ts +8 -2
  217. package/templates/rts/src/render/quality.ts +61 -2
  218. package/templates/rts/src/render/sky.ts +21 -1
  219. package/templates/rts/src/render/worldEnvironment.ts +433 -30
  220. package/templates/rts/src/scenes/Play.ts +54 -3
  221. package/templates/rts/src/sim/ai.ts +0 -1
  222. package/templates/rts/src/sim/terrain.ts +0 -4
  223. package/templates/rts/vite.config.ts +10 -2
  224. package/templates/runner/AGENTS.md +10 -8
  225. package/templates/runner/CLAUDE.md +10 -8
  226. package/templates/runner/package.json +13 -10
  227. package/templates/runner/playtests/performance.playtest.json +10 -1
  228. package/templates/runner/src/physics.ts +0 -1
  229. package/templates/runner/src/render/autoExposure.ts +225 -0
  230. package/templates/runner/src/render/backlightControls.ts +66 -0
  231. package/templates/runner/src/render/backlightMaterial.ts +147 -0
  232. package/templates/runner/src/render/environmentContribution.ts +188 -0
  233. package/templates/runner/src/render/environmentRadiance.ts +36 -0
  234. package/templates/runner/src/render/environmentSampleCache.ts +43 -0
  235. package/templates/runner/src/render/environmentSampling.ts +193 -0
  236. package/templates/runner/src/render/environmentSnapshot.ts +53 -0
  237. package/templates/runner/src/render/exposure.ts +111 -0
  238. package/templates/runner/src/render/exposureGraph.ts +178 -0
  239. package/templates/runner/src/render/exposureReadback.ts +79 -0
  240. package/templates/runner/src/render/heightFog.ts +118 -0
  241. package/templates/runner/src/render/lighting.ts +26 -1
  242. package/templates/runner/src/render/materialAssignments.ts +160 -0
  243. package/templates/runner/src/render/materialLighting.ts +155 -0
  244. package/templates/runner/src/render/postprocessing.ts +17 -2
  245. package/templates/runner/src/render/quality.ts +61 -2
  246. package/templates/runner/src/render/sky.ts +21 -1
  247. package/templates/runner/src/render/worldEnvironment.ts +433 -30
  248. package/templates/runner/src/scenes/Run.ts +67 -2
  249. package/templates/runner/threenative.config.ts +3 -0
  250. package/templates/runner/vite.config.ts +10 -2
  251. package/templates/sailing/AGENTS.md +14 -13
  252. package/templates/sailing/CLAUDE.md +14 -13
  253. package/templates/sailing/native-playtests/survives.playtest.json +7 -0
  254. package/templates/sailing/package.json +13 -10
  255. package/templates/sailing/playtests/live/render-motion.playtest.json +30 -0
  256. package/templates/sailing/src/entities/Ship.ts +38 -18
  257. package/templates/sailing/src/render/autoExposure.ts +225 -0
  258. package/templates/sailing/src/render/backlightControls.ts +66 -0
  259. package/templates/sailing/src/render/backlightMaterial.ts +147 -0
  260. package/templates/sailing/src/render/camera.ts +12 -4
  261. package/templates/sailing/src/render/environmentContribution.ts +188 -0
  262. package/templates/sailing/src/render/environmentRadiance.ts +36 -0
  263. package/templates/sailing/src/render/environmentSampleCache.ts +43 -0
  264. package/templates/sailing/src/render/environmentSampling.ts +193 -0
  265. package/templates/sailing/src/render/environmentSetup.ts +24 -0
  266. package/templates/sailing/src/render/environmentSnapshot.ts +53 -0
  267. package/templates/sailing/src/render/exposure.ts +111 -0
  268. package/templates/sailing/src/render/exposureGraph.ts +178 -0
  269. package/templates/sailing/src/render/exposureReadback.ts +79 -0
  270. package/templates/sailing/src/render/heightFog.ts +118 -0
  271. package/templates/sailing/src/render/lighting.ts +26 -1
  272. package/templates/sailing/src/render/materialAssignments.ts +160 -0
  273. package/templates/sailing/src/render/materialLighting.ts +155 -0
  274. package/templates/sailing/src/render/ocean.ts +71 -53
  275. package/templates/sailing/src/render/postprocessing.ts +16 -2
  276. package/templates/sailing/src/render/props.ts +0 -45
  277. package/templates/sailing/src/render/quality.ts +61 -1
  278. package/templates/sailing/src/render/sky.ts +21 -1
  279. package/templates/sailing/src/render/worldEnvironment.ts +433 -30
  280. package/templates/sailing/src/scenes/Boot.ts +12 -1
  281. package/templates/sailing/src/scenes/Sailing.ts +87 -2
  282. package/templates/sailing/src/scenes/ocean-readiness.ts +68 -0
  283. package/templates/sailing/threenative.config.ts +3 -0
  284. package/templates/sailing/vite.config.ts +10 -2
  285. package/templates/shooter/AGENTS.md +8 -6
  286. package/templates/shooter/CLAUDE.md +8 -6
  287. package/templates/shooter/package.json +13 -10
  288. package/templates/shooter/playtests/performance.playtest.json +7 -1
  289. package/templates/shooter/src/entities/Enemy.ts +0 -15
  290. package/templates/shooter/src/entities/Rifle.ts +38 -1
  291. package/templates/shooter/src/render/autoExposure.ts +225 -0
  292. package/templates/shooter/src/render/backlightControls.ts +66 -0
  293. package/templates/shooter/src/render/backlightMaterial.ts +147 -0
  294. package/templates/shooter/src/render/camera.ts +1 -12
  295. package/templates/shooter/src/render/decals.ts +299 -5
  296. package/templates/shooter/src/render/environmentContribution.ts +188 -0
  297. package/templates/shooter/src/render/environmentRadiance.ts +36 -0
  298. package/templates/shooter/src/render/environmentSampleCache.ts +43 -0
  299. package/templates/shooter/src/render/environmentSampling.ts +193 -0
  300. package/templates/shooter/src/render/environmentSnapshot.ts +53 -0
  301. package/templates/shooter/src/render/exposure.ts +111 -0
  302. package/templates/shooter/src/render/exposureGraph.ts +178 -0
  303. package/templates/shooter/src/render/exposureReadback.ts +79 -0
  304. package/templates/shooter/src/render/gunfx.ts +0 -1
  305. package/templates/shooter/src/render/heightFog.ts +118 -0
  306. package/templates/shooter/src/render/lighting.ts +26 -1
  307. package/templates/shooter/src/render/materialAssignments.ts +160 -0
  308. package/templates/shooter/src/render/materialLighting.ts +155 -0
  309. package/templates/shooter/src/render/postprocessing.ts +17 -2
  310. package/templates/shooter/src/render/quality.ts +61 -2
  311. package/templates/shooter/src/render/scale.ts +2 -93
  312. package/templates/shooter/src/render/sky.ts +21 -1
  313. package/templates/shooter/src/render/vehicles.ts +0 -17
  314. package/templates/shooter/src/render/worldEnvironment.ts +433 -30
  315. package/templates/shooter/src/scenes/Play.ts +64 -2
  316. package/templates/shooter/vite.config.ts +10 -2
  317. package/templates/snow/AGENTS.md +8 -6
  318. package/templates/snow/CLAUDE.md +8 -6
  319. package/templates/snow/package.json +13 -10
  320. package/templates/snow/src/render/autoExposure.ts +225 -0
  321. package/templates/snow/src/render/backlightControls.ts +66 -0
  322. package/templates/snow/src/render/backlightMaterial.ts +147 -0
  323. package/templates/snow/src/render/environmentContribution.ts +188 -0
  324. package/templates/snow/src/render/environmentRadiance.ts +36 -0
  325. package/templates/snow/src/render/environmentSampleCache.ts +43 -0
  326. package/templates/snow/src/render/environmentSampling.ts +193 -0
  327. package/templates/snow/src/render/environmentSnapshot.ts +53 -0
  328. package/templates/snow/src/render/exposure.ts +111 -0
  329. package/templates/snow/src/render/exposureGraph.ts +178 -0
  330. package/templates/snow/src/render/exposureReadback.ts +79 -0
  331. package/templates/snow/src/render/heightFog.ts +118 -0
  332. package/templates/snow/src/render/lighting.ts +33 -1
  333. package/templates/snow/src/render/materialAssignments.ts +160 -0
  334. package/templates/snow/src/render/materialLighting.ts +155 -0
  335. package/templates/snow/src/render/postprocessing.ts +16 -2
  336. package/templates/snow/src/render/quality.ts +59 -1
  337. package/templates/snow/src/render/sky.ts +21 -2
  338. package/templates/snow/src/render/worldEnvironment.ts +433 -30
  339. package/templates/snow/src/scenes/Snow.ts +29 -1
  340. package/templates/snow/threenative.config.ts +3 -0
  341. package/templates/snow/vite.config.ts +10 -2
  342. package/templates/starter/AGENTS.md +11 -16
  343. package/templates/starter/CLAUDE.md +11 -16
  344. package/templates/starter/native-playtests/react-hud.playtest.json +1 -1
  345. package/templates/starter/native-playtests/render-chain.playtest.json +51 -8
  346. package/templates/starter/native-playtests/smooth-motion.playtest.json +64 -0
  347. package/templates/starter/package.json +13 -10
  348. package/templates/starter/playtests/live/smooth-motion.playtest.json +63 -0
  349. package/templates/starter/playtests/movement.playtest.json +192 -0
  350. package/templates/starter/playtests/play.playtest.json +18 -2
  351. package/templates/starter/playtests/production-readiness.playtest.json +43 -1
  352. package/templates/starter/public/grade.cube +735 -0
  353. package/templates/starter/src/entities/Crate.ts +4 -0
  354. package/templates/starter/src/entities/Player.ts +79 -18
  355. package/templates/starter/src/game.ts +1 -0
  356. package/templates/starter/src/render/adaptiveQuality.ts +28 -41
  357. package/templates/starter/src/render/autoExposure.ts +225 -0
  358. package/templates/starter/src/render/backlightControls.ts +66 -0
  359. package/templates/starter/src/render/backlightMaterial.ts +147 -0
  360. package/templates/starter/src/render/environmentContribution.ts +188 -0
  361. package/templates/starter/src/render/environmentRadiance.ts +36 -0
  362. package/templates/starter/src/render/environmentSampleCache.ts +43 -0
  363. package/templates/starter/src/render/environmentSampling.ts +193 -0
  364. package/templates/starter/src/render/environmentSnapshot.ts +53 -0
  365. package/templates/starter/src/render/exposure.ts +111 -0
  366. package/templates/starter/src/render/exposureGraph.ts +178 -0
  367. package/templates/starter/src/render/exposureReadback.ts +79 -0
  368. package/templates/starter/src/render/grade.ts +157 -0
  369. package/templates/starter/src/render/heightFog.ts +118 -0
  370. package/templates/starter/src/render/lighting.ts +26 -1
  371. package/templates/starter/src/render/materialAssignments.ts +160 -0
  372. package/templates/starter/src/render/materialLighting.ts +155 -0
  373. package/templates/starter/src/render/postprocessing.ts +90 -4
  374. package/templates/starter/src/render/quality.ts +80 -8
  375. package/templates/starter/src/render/qualityPolicy.ts +54 -0
  376. package/templates/starter/src/render/rendererGate.ts +36 -0
  377. package/templates/starter/src/render/sky.ts +23 -1
  378. package/templates/starter/src/render/temporalAA.ts +197 -0
  379. package/templates/starter/src/render/temporalAAFrame.ts +179 -0
  380. package/templates/starter/src/render/temporalAAHooks.ts +101 -0
  381. package/templates/starter/src/render/temporalAAInput.ts +56 -0
  382. package/templates/starter/src/render/temporalAAResolve.ts +65 -0
  383. package/templates/starter/src/render/temporalAAStage.ts +76 -0
  384. package/templates/starter/src/render/temporalCurrentArea.ts +31 -0
  385. package/templates/starter/src/render/temporalCurrentFootprint.ts +198 -0
  386. package/templates/starter/src/render/temporalCurrentFootprintMath.ts +41 -0
  387. package/templates/starter/src/render/temporalCurrentProducer.ts +161 -0
  388. package/templates/starter/src/render/temporalCurrentReplay.ts +160 -0
  389. package/templates/starter/src/render/temporalCurrentSelection.ts +89 -0
  390. package/templates/starter/src/render/temporalCurrentVisibility.ts +170 -0
  391. package/templates/starter/src/render/temporalDepthSamples.ts +34 -0
  392. package/templates/starter/src/render/temporalRejectionCounter.ts +179 -0
  393. package/templates/starter/src/render/temporalResolve.ts +139 -0
  394. package/templates/starter/src/render/temporalResolveDepth.ts +193 -0
  395. package/templates/starter/src/render/temporalResolveMath.ts +196 -0
  396. package/templates/starter/src/render/volumetricFog.ts +124 -0
  397. package/templates/starter/src/render/volumetricFogOptions.ts +96 -0
  398. package/templates/starter/src/render/volumetricFogTransport.ts +176 -0
  399. package/templates/starter/src/render/volumetricFogVolume.ts +139 -0
  400. package/templates/starter/src/render/worldEnvironment.ts +433 -30
  401. package/templates/starter/src/scenes/Play.ts +110 -1
  402. package/templates/starter/src/state.ts +1 -0
  403. package/templates/starter/src/ui/Hud.tsx +1 -1
  404. package/templates/starter/src/ui/Menu.tsx +1 -1
  405. package/templates/starter/tools/make-grade-lut.mjs +101 -0
  406. package/templates/starter/vite.config.ts +10 -2
  407. package/templates/tower-defense/AGENTS.md +10 -9
  408. package/templates/tower-defense/CLAUDE.md +10 -9
  409. package/templates/tower-defense/package.json +13 -10
  410. package/templates/tower-defense/playtests/performance.playtest.json +7 -1
  411. package/templates/tower-defense/src/render/autoExposure.ts +225 -0
  412. package/templates/tower-defense/src/render/backlightControls.ts +66 -0
  413. package/templates/tower-defense/src/render/backlightMaterial.ts +147 -0
  414. package/templates/tower-defense/src/render/environmentContribution.ts +188 -0
  415. package/templates/tower-defense/src/render/environmentRadiance.ts +36 -0
  416. package/templates/tower-defense/src/render/environmentSampleCache.ts +43 -0
  417. package/templates/tower-defense/src/render/environmentSampling.ts +193 -0
  418. package/templates/tower-defense/src/render/environmentSnapshot.ts +53 -0
  419. package/templates/tower-defense/src/render/exposure.ts +111 -0
  420. package/templates/tower-defense/src/render/exposureGraph.ts +178 -0
  421. package/templates/tower-defense/src/render/exposureReadback.ts +79 -0
  422. package/templates/tower-defense/src/render/lighting.ts +33 -1
  423. package/templates/tower-defense/src/render/materialAssignments.ts +160 -0
  424. package/templates/tower-defense/src/render/materialLighting.ts +155 -0
  425. package/templates/tower-defense/src/render/postprocessing.ts +8 -2
  426. package/templates/tower-defense/src/render/quality.ts +61 -2
  427. package/templates/tower-defense/src/render/shapes.ts +0 -3
  428. package/templates/tower-defense/src/render/worldEnvironment.ts +433 -30
  429. package/templates/tower-defense/src/scenes/Battle.ts +65 -2
  430. package/templates/tower-defense/vite.config.ts +10 -2
  431. package/templates/minimal/src/scenes/Boot.ts +0 -5
package/capabilities.json CHANGED
@@ -544,7 +544,7 @@
544
544
  "importPath": "@threenative/core",
545
545
  "kind": "function",
546
546
  "overrides": [
547
- "sliceSize defaults to 256; `marker: false` silences the TN_ADD_SLICES line, not the report"
547
+ "a slice ends on an 8 ms budget unless the game gives `sliceSize`, and the reported sliceSize is then the measured average; `marker: false` silences the TN_ADD_SLICES line, not the report"
548
548
  ],
549
549
  "package": "@threenative/core",
550
550
  "signature": "export async function addInSlices<T>( objects: Iterable<T>, add: (object: T, index: number) => void, options: IAddInSlicesOptions = { … }",
@@ -684,6 +684,30 @@
684
684
  "supersedes": [],
685
685
  "symbol": "alwaysRender"
686
686
  },
687
+ {
688
+ "aliases": [],
689
+ "constraints": [
690
+ "one base phase, one masked override, at most two additive layers and eight actions",
691
+ "root motion requires a separate rig below the body; advance, CharacterBody3D.move, finish with observed accepted motion after physics, then existing IK",
692
+ "root motion excludes velocity-driven stride sync; unsupported parent transforms throw",
693
+ "source clips remain immutable; dispose at scene exit"
694
+ ],
695
+ "example": "const animation = new AnimationComposer({ root: rig, clips, samples: [\"walk\", \"run\"] });\nanimation.setWeights([0.5, 0.5]); animation.update(dt);",
696
+ "importPath": "@threenative/core",
697
+ "kind": "class",
698
+ "overrides": [],
699
+ "package": "@threenative/core",
700
+ "signature": "export class AnimationComposer { … }",
701
+ "situations": [
702
+ "synchronize walk/run/strafe clips with different durations",
703
+ "reload with the upper body while locomotion continues",
704
+ "apply an additive recoil clip with an explicit reference pose",
705
+ "route root motion through collision-aware character movement"
706
+ ],
707
+ "summary": "Compose game-authored locomotion and masked actions on one Three.js mixer.",
708
+ "supersedes": [],
709
+ "symbol": "AnimationComposer"
710
+ },
687
711
  {
688
712
  "aliases": [],
689
713
  "constraints": [
@@ -712,7 +736,7 @@
712
736
  "symbol": "AnimationPlayer"
713
737
  },
714
738
  {
715
- "aliases": ["bright sky saturated green platforms"],
739
+ "aliases": ["green platforms bright saturated sky"],
716
740
  "constraints": [
717
741
  "supply rayleigh, mie, ozone, planetRadius, and atmosphereRadius; there is no Earth fallback",
718
742
  "the game creates the sky object, surface, and sun from the returned nodes"
@@ -872,6 +896,46 @@
872
896
  "supersedes": [],
873
897
  "symbol": "Billboard3D"
874
898
  },
899
+ {
900
+ "aliases": [],
901
+ "constraints": [
902
+ "duplicate samples, collinear triangles and invalid/incomplete triangulations throw at initialization",
903
+ "outside 2D queries project to the nearest boundary subedge; output is borrowed scratch"
904
+ ],
905
+ "example": "const blend = new BlendSpace1D([0, 2]); animation.setWeights(blend.sample(speed));",
906
+ "importPath": "@threenative/core",
907
+ "kind": "class",
908
+ "overrides": [],
909
+ "package": "@threenative/core",
910
+ "signature": "export class BlendSpace1D { … }",
911
+ "situations": [
912
+ "calculate 1D walk/run blend weights from speed",
913
+ "calculate 2D locomotion weights from forward and strafe intent"
914
+ ],
915
+ "summary": "Select finite, normalized locomotion weights from sorted thresholds or a fixed triangulation.",
916
+ "supersedes": [],
917
+ "symbol": "BlendSpace1D"
918
+ },
919
+ {
920
+ "aliases": [],
921
+ "constraints": [
922
+ "duplicate samples, collinear triangles and invalid/incomplete triangulations throw at initialization",
923
+ "outside 2D queries project to the nearest boundary subedge; output is borrowed scratch"
924
+ ],
925
+ "example": "const blend = new BlendSpace1D([0, 2]); animation.setWeights(blend.sample(speed));",
926
+ "importPath": "@threenative/core",
927
+ "kind": "class",
928
+ "overrides": [],
929
+ "package": "@threenative/core",
930
+ "signature": "export class BlendSpace2D { … }",
931
+ "situations": [
932
+ "calculate 1D walk/run blend weights from speed",
933
+ "calculate 2D locomotion weights from forward and strafe intent"
934
+ ],
935
+ "summary": "Select finite, normalized locomotion weights from sorted thresholds or a fixed triangulation.",
936
+ "supersedes": [],
937
+ "symbol": "BlendSpace2D"
938
+ },
875
939
  {
876
940
  "aliases": [],
877
941
  "constraints": [
@@ -1159,7 +1223,7 @@
1159
1223
  "symbol": "counterDeviceOf"
1160
1224
  },
1161
1225
  {
1162
- "aliases": ["different props in each area", "first playable screen external assets"],
1226
+ "aliases": ["different area props", "first playable screen external assets"],
1163
1227
  "constraints": [
1164
1228
  "reuse the loader handed to scenes as `ctx.assets` instead of building parallel caches"
1165
1229
  ],
@@ -1276,9 +1340,9 @@
1276
1340
  },
1277
1341
  {
1278
1342
  "aliases": [
1279
- "firing line nearest target crosshair",
1343
+ "nearest target crosshair spawns",
1280
1344
  "third-person camera",
1281
- "restart the run without a page reload",
1345
+ "restart run without page reload",
1282
1346
  "field of view while aiming"
1283
1347
  ],
1284
1348
  "constraints": [
@@ -1498,6 +1562,33 @@
1498
1562
  "supersedes": [],
1499
1563
  "symbol": "FluidField2D"
1500
1564
  },
1565
+ {
1566
+ "aliases": [],
1567
+ "constraints": [
1568
+ "add the fluid through `ctx.add` so renderer attachment, fixed-step dispatch, and release are automatic",
1569
+ "a renderer without WebGPU compute throws a named error at attach; it never draws nothing",
1570
+ "`emit` recycles the oldest slot once `capacity` slots have been used; `fill` stops at capacity",
1571
+ "`sample` and `stats` read a throttled GPU copy and report `staleFrames`; they are never live"
1572
+ ],
1573
+ "example": "const water = new FluidParticles3D({ capacity: 6000 });\nctx.add(water);\nwater.fill([-2.8, 0.1, -1.5], [-0.6, 3, 1.5]);",
1574
+ "importPath": "@threenative/core",
1575
+ "kind": "class",
1576
+ "overrides": [
1577
+ "iterations, viscosity, cohesion, vorticity, gravity and maxSpeed tune the solver without changing its pass order"
1578
+ ],
1579
+ "package": "@threenative/core",
1580
+ "signature": "export class FluidParticles3D extends Group { … }",
1581
+ "situations": [
1582
+ "pour, splash, or dam-break water that fills a container and flows around obstacles",
1583
+ "simulate water or another liquid as particles in a fluid simulation",
1584
+ "drop a ball or box into liquid and let it displace and float on the water",
1585
+ "emit a stream or waterfall of particle fluid and drain it somewhere else",
1586
+ "sample particle-fluid density or surface height in a game-owned render node"
1587
+ ],
1588
+ "summary": "Simulate liquid as GPU particles (pour, splash, dam break, waterfall) and expose positions, a density volume and a surface height while the game owns every look.",
1589
+ "supersedes": [],
1590
+ "symbol": "FluidParticles3D"
1591
+ },
1501
1592
  {
1502
1593
  "aliases": [],
1503
1594
  "constraints": [
@@ -1541,6 +1632,28 @@
1541
1632
  "supersedes": [],
1542
1633
  "symbol": "formatSpansWindow"
1543
1634
  },
1635
+ {
1636
+ "aliases": [],
1637
+ "constraints": [
1638
+ "derived from the scene graph, not from a constant: cutout PBR with no environment in the scene and none on the material",
1639
+ "it changes nothing and never throws — the environment is appearance, so setting it stays the game's decision"
1640
+ ],
1641
+ "example": "defineGame({ scenes: { Forest } }); // one TN_UNLIT_FOLIAGE line when the forest has no sky",
1642
+ "importPath": "@threenative/core",
1643
+ "kind": "function",
1644
+ "overrides": [
1645
+ "`material.userData.tnUnlitOk = true` on a material a game deliberately renders unlit (the same `userData.tn*` naming the alpha and impostor conventions use)"
1646
+ ],
1647
+ "package": "@threenative/core",
1648
+ "signature": "export function formatUnlitFoliageWarning(warning: IUnlitFoliageWarning): string { … }",
1649
+ "situations": [
1650
+ "catch the \"why does my forest look like cardboard\" question before a human plays it",
1651
+ "audit a scene a game built from imported GLB foliage"
1652
+ ],
1653
+ "summary": "Tell the agent that built the scene that its imported foliage is drawing with no image-based light: an alpha-cutout `MeshStandardMaterial` (or its Node twin) with `scene.environment` unset and no `envMap` of its own gets a hemisphere fill and one flat dark value, which is cardboard. Printed once per scene entry as `TN_UNLIT_FOLIAGE`, after `enter()`, with the fix in the same line.",
1654
+ "supersedes": [],
1655
+ "symbol": "formatUnlitFoliageWarning"
1656
+ },
1544
1657
  {
1545
1658
  "aliases": [],
1546
1659
  "constraints": [
@@ -1567,7 +1680,10 @@
1567
1680
  "constraints": [
1568
1681
  "on by default and printed as TN_FRAME_BUDGET; defineGame({ frameBudget: false }) silences the marker, not the measurement",
1569
1682
  "per-pass numbers are attributed to the innermost active render call, so nested shadow and reflection passes do not read as main",
1570
- "GPU is a mean/p50/p95/max series over resolved frames (`gpu`) with `gpuStale` counting frames that had no fresh reading; absent means no timestamps, never zero"
1683
+ "GPU is a mean/p50/p95/max series over resolved frames (`gpu`) with `gpuStale` counting frames that had no fresh reading; absent means no timestamps, never zero",
1684
+ "`ctx.renderer.observeGpuFrames({ maxFrames, maxQueries })` is opt-in, bounded and fail-closed; `take()` delivers immutable complete render-query groups once, while `status()` reports pending/undrained/queued membership and losses",
1685
+ "observation preserves ordinary sampling; a complete benchmark explicitly requests `renderer.gpuTimestampFrameInterval: 1` and joins Three query IDs to actual world renders, including separate overlay IDs",
1686
+ "`stop()` fences allocated frames and drains existing resolver work; `dispose()` invalidates late completions, and a failed observation must be disposed before replacement"
1571
1687
  ],
1572
1688
  "example": "defineGame({ frameBudget: { reportEvery: 120 }, scenes: { Play } });",
1573
1689
  "importPath": "@threenative/core",
@@ -1581,7 +1697,8 @@
1581
1697
  "attribute a frame to present wait, simulation, three.js render, or overlay",
1582
1698
  "tell whether the GPU is the frame's constraint from a per-frame series, not one lagged timestamp",
1583
1699
  "split a frame's draw calls and triangles per render pass (main, shadow, reflection)",
1584
- "tell a shadow or reflection pass's cost from the main colour pass"
1700
+ "tell a shadow or reflection pass's cost from the main colour pass",
1701
+ "retain every asynchronous GPU render frame for a complete paired benchmark"
1585
1702
  ],
1586
1703
  "summary": "Read where the frame's milliseconds went, per presented frame, on any platform; each `TN_FRAME_BUDGET` window also carries the GPU time per resolved frame and the draw calls and triangles each render pass submitted.",
1587
1704
  "supersedes": [],
@@ -1652,11 +1769,24 @@
1652
1769
  },
1653
1770
  {
1654
1771
  "aliases": [],
1655
- "constraints": ["geometry, color, and timing remain supplied by the game"],
1656
- "example": "const particles = new GPUParticles3D(particleOptions);",
1772
+ "constraints": [
1773
+ "geometry, color, and timing remain supplied by the game",
1774
+ "a `spawn` kernel makes bursts requests: `emitParticle({ count, origin })` reserves ring slots, the engine stamps `buffers.births` and `process` reads age as `runtime.time - births[i]`; there is no readback",
1775
+ "a spawn emitter is world space (identity world matrix); `localCoords: true` follows the parent",
1776
+ "requests over `amount` or `maxSpawnPerFrame` clamp, add to `stats.clamped` and warn once; `stats.recycledLive` is `undefined` without the `lifetime` option",
1777
+ "the emitter measures its own bounds and stops computing and drawing after graceSeconds outside the camera view",
1778
+ "a game needs no emitting = visible gate, and an emitter with no measured bounds is never culled for leaving the view",
1779
+ "when measured GPU cost passes the frame budget, the smallest projected emitters pause first, and cull.reason reads outside-view or over-budget"
1780
+ ],
1781
+ "example": "const particles = new GPUParticles3D(particleOptions);\nparticles.emitParticle({ count: 220, origin: hit.position });",
1657
1782
  "importPath": "@threenative/core",
1658
1783
  "kind": "class",
1659
- "overrides": [],
1784
+ "overrides": [
1785
+ "localCoords, maxSpawnPerFrame and lifetime tune a spawn emitter; `restart()` kills every particle and rewinds the ring",
1786
+ "onCull: \"clear\" restarts a returning effect, the default \"pause\" resumes it with buffers intact",
1787
+ "bounds supplies a fixed local Box3 and skips GPU measurement, padding enlarges the world box, boundsEveryFrames sets the measurement cadence",
1788
+ "graceSeconds sets the seconds outside the view before culling, and Infinity disables view culling"
1789
+ ],
1660
1790
  "package": "@threenative/core",
1661
1791
  "signature": "export class GPUParticles3D extends Sprite implements IComputeDriven { … }",
1662
1792
  "situations": [
@@ -1665,8 +1795,12 @@
1665
1795
  "trail dust, exhaust, or spray behind a moving object",
1666
1796
  "emit cannon smoke and muzzle flash particles",
1667
1797
  "fire a cannonball projectile with cannon smoke particles",
1798
+ "splash spray droplets with lifetime and gravity",
1799
+ "spawn water droplets, mist, or foam bubbles above a fluid surface",
1668
1800
  "falling snowflakes, rain or ash around the player that thicken into a windy storm or blizzard",
1669
- "kick up a spray of powder snow or dust where a foot or a ball lands"
1801
+ "kick up a spray of powder snow or dust where a foot or a ball lands",
1802
+ "a hit, impact or explosion burst that starts at the point and moment it is asked for, and a second hit that must not move the first hit's live particles",
1803
+ "emitParticle a burst of GPU particles at a world position with its own free slots"
1670
1804
  ],
1671
1805
  "summary": "Dispatch a game-owned particle surface and process function through a pooled system.",
1672
1806
  "supersedes": [],
@@ -1783,12 +1917,15 @@
1783
1917
  "constraints": [
1784
1918
  "geometry and material are required and come from the game; the batch chooses neither",
1785
1919
  "span stretches along +Y, so its geometry must be unit-height and centred on the origin",
1786
- "placing after build() throws, and build() returns undefined when nothing was placed"
1920
+ "placing after build() throws, and build() returns undefined when nothing was placed",
1921
+ "baked AutoLOD chains survive geometry clone/transform preparation and partition instances automatically into spatially bounded draws in the engine frame loop at 4 px projected error; public instance slots remain stable",
1922
+ "unavailable authored levels report TN_INSTANCED_LOD_FAILED once naming the batch; a million-triangle batch with no chain reports TN_INSTANCED_LOD_UNAVAILABLE"
1787
1923
  ],
1788
1924
  "example": "const curbs = new InstancedBatch({ geometry: new BoxGeometry(1, 1, 1), material });\ncurbs.place({ position: [x, 0.08, z], rotation: [0, angle, 0], scale: [length, 0.18, 0.42] });\ncurbs.build({ castShadow: true, name: \"curbs\", parent: ctx.scene });",
1789
1925
  "importPath": "@threenative/core",
1790
1926
  "kind": "class",
1791
1927
  "overrides": [
1928
+ "autoLod: false leaves selection to the game; autoLod.maxPixelError and hysteresis override the measured-camera budget; lods supplies authored distance/geometry levels and wins over the baked chain",
1792
1929
  "castShadow and receiveShadow pass through to the built mesh and default to Three.js's own false"
1793
1930
  ],
1794
1931
  "package": "@threenative/core",
@@ -1796,6 +1933,7 @@
1796
1933
  "situations": [
1797
1934
  "draw hundreds of repeated props without hundreds of draw calls",
1798
1935
  "draw thousands of identical instanced blocks or obstacles in one mesh",
1936
+ "automatically select instanced prop detail from projected screen error using baked AutoLOD chains",
1799
1937
  "place repeated props when the count is not known until the layout has been walked",
1800
1938
  "build a chain, railing, cable, or tie rod out of point-to-point segments"
1801
1939
  ],
@@ -2488,6 +2626,26 @@
2488
2626
  "supersedes": [],
2489
2627
  "symbol": "RenderListValidator"
2490
2628
  },
2629
+ {
2630
+ "aliases": [],
2631
+ "constraints": [
2632
+ "structural scene reads only, one visible-tree walk per entry, at most five material examples",
2633
+ "the audit itself changes no scene state; the game loop's opacity convention is the only writer"
2634
+ ],
2635
+ "example": "renderTrapAudit(ctx.scene); // marker lines with the fixes, or an empty array",
2636
+ "importPath": "@threenative/core",
2637
+ "kind": "function",
2638
+ "overrides": [],
2639
+ "package": "@threenative/core",
2640
+ "signature": "export function renderTrapAudit(scene: Object3D & { … }",
2641
+ "situations": [
2642
+ "audit an equirectangular sky too narrow for three's WebGPU PMREM",
2643
+ "find visible opaque materials whose authored opacity is ignored"
2644
+ ],
2645
+ "summary": "Catch scene state that silently loses environment fill or ignores authored opacity. After `enter()` the game first applies the opacity convention: a drawn material with `opacity < 1` turns transparent and one `TN_OPACITY_TRANSPARENT` console warning names it (override: `alphaHash: true`, or `opacity: 1`). It then prints `TN_ENVIRONMENT_TOO_SMALL` as a console error with the fix, so playtest `noConsoleErrors` rejects it.",
2646
+ "supersedes": [],
2647
+ "symbol": "renderTrapAudit"
2648
+ },
2491
2649
  {
2492
2650
  "aliases": ["fixed seed fixed-step simulation"],
2493
2651
  "constraints": [
@@ -3054,6 +3212,28 @@
3054
3212
  "supersedes": [],
3055
3213
  "symbol": "TracerPool3D"
3056
3214
  },
3215
+ {
3216
+ "aliases": [],
3217
+ "constraints": [
3218
+ "derived from the scene graph, not from a constant: cutout PBR with no environment in the scene and none on the material",
3219
+ "it changes nothing and never throws — the environment is appearance, so setting it stays the game's decision"
3220
+ ],
3221
+ "example": "defineGame({ scenes: { Forest } }); // one TN_UNLIT_FOLIAGE line when the forest has no sky",
3222
+ "importPath": "@threenative/core",
3223
+ "kind": "function",
3224
+ "overrides": [
3225
+ "`material.userData.tnUnlitOk = true` on a material a game deliberately renders unlit (the same `userData.tn*` naming the alpha and impostor conventions use)"
3226
+ ],
3227
+ "package": "@threenative/core",
3228
+ "signature": "export function unlitFoliageWarning( scene: Object3D & { … }",
3229
+ "situations": [
3230
+ "catch the \"why does my forest look like cardboard\" question before a human plays it",
3231
+ "audit a scene a game built from imported GLB foliage"
3232
+ ],
3233
+ "summary": "Tell the agent that built the scene that its imported foliage is drawing with no image-based light: an alpha-cutout `MeshStandardMaterial` (or its Node twin) with `scene.environment` unset and no `envMap` of its own gets a hemisphere fill and one flat dark value, which is cardboard. Printed once per scene entry as `TN_UNLIT_FOLIAGE`, after `enter()`, with the fix in the same line.",
3234
+ "supersedes": [],
3235
+ "symbol": "unlitFoliageWarning"
3236
+ },
3057
3237
  {
3058
3238
  "aliases": [],
3059
3239
  "constraints": [
@@ -3197,7 +3377,8 @@
3197
3377
  "constraints": [
3198
3378
  "the light must be a DirectionalLight with `castShadow` and a target in the scene",
3199
3379
  "clipExtents are half-widths in world units, finest first, strictly increasing",
3200
- "call `trackCaster(object)` for movers; it enables layer `VIRTUAL_SHADOW_MOVER_LAYER` on the object and its descendants, tracking or untracking refreshes cached levels once, and subsequent mover movement refreshes only when a window moves",
3380
+ "movers sort themselves: a layer-0 caster whose world matrix, instance matrix or deformation changed draws through the mover maps and leaves the cached levels, and returns to them after `staticAfterFrames` quiet frames; the cache redraws only the region it left",
3381
+ "`trackCaster(object)` is the override that pins an object as a mover for good (it enables layer `VIRTUAL_SHADOW_MOVER_LAYER` on the object and its descendants), and `pinStatic(object)` opts an object out of detection; tracking or untracking refreshes only that object's region",
3201
3382
  "call `object.layers.set(VIRTUAL_SHADOW_CASTER_LAYER)` for a mesh that exists only to cast; the level cameras already render that layer and the main camera never does"
3202
3383
  ],
3203
3384
  "example": "const sun = new DirectionalLight(0xffffff, 3);\nsun.castShadow = true;\nsun.shadow.shadowNode = new VirtualShadowNode(sun, { clipExtents: [12, 40, 120] });",
@@ -3205,7 +3386,8 @@
3205
3386
  "kind": "class",
3206
3387
  "overrides": [
3207
3388
  "bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults, and `marker: false` silences the TN_VIRTUAL_SHADOW line, not the measurement",
3208
- "bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults"
3389
+ "bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults",
3390
+ "followViewFocus: false keeps eye follow; receiverPlaneBias: false uses only authored bias"
3209
3391
  ],
3210
3392
  "package": "@threenative/core",
3211
3393
  "signature": "export class VirtualShadowNode extends ShadowBaseNode { … }",
@@ -3243,14 +3425,16 @@
3243
3425
  "the material must be transparent so the frame beneath it is already drawn",
3244
3426
  "thickness is metres, saturating at maxThickness; sky behind the surface reads deep",
3245
3427
  "one reflection is a second draw of the world; resolutionScale is its pixels only",
3246
- "on a crowded scene the mirrored pass is draw-bound: name reflection.layers or pay twice",
3428
+ "omitted reflection.layers automatically reflects terrain-sized surfaces and large non-instanced casters, excluding instanced/skinned props; TN_WATER_REFLECTION_DEFAULT reports the set once",
3247
3429
  "reflection.refreshInterval is in presented frames; 1 is every frame, and the default",
3248
3430
  "the mirror plane is level, from level alone; do not parent target to a scaled mesh"
3249
3431
  ],
3250
- "example": "const REFLECTED = 1; // the layer the big silhouettes sit on\nconst surface = new WaterSurface3D({ level: 0, maxThickness: 3, reflection: { resolutionScale: 0.5, layers: (1 << 0) | (1 << REFLECTED) } });\nmaterial.colorNode = mix(surface.refractionAt(offset), surface.reflectionAt(offset), fresnel);",
3432
+ "example": "const surface = new WaterSurface3D({ level: 0, maxThickness: 3, reflection: { resolutionScale: 0.5 } });\nmaterial.colorNode = mix(surface.refractionAt(offset), surface.reflectionAt(offset), fresnel);",
3251
3433
  "importPath": "@threenative/core",
3252
3434
  "kind": "class",
3253
- "overrides": [],
3435
+ "overrides": [
3436
+ "reflection.layers is an explicit Three Layers mask and wins over automatic filtering, including layer-0 mask 1; reflection.minSize overrides the default 10 metre minimum extent"
3437
+ ],
3254
3438
  "package": "@threenative/core",
3255
3439
  "signature": "export class WaterSurface3D { … }",
3256
3440
  "situations": [
@@ -3259,7 +3443,8 @@
3259
3443
  "know how deep the water is under a pixel without a second render pass",
3260
3444
  "stop a water surface repeating in visible bands or stripes",
3261
3445
  "keep a crowd of small actors out of the water's reflection so the frame can afford it",
3262
- "stop the water reflection redrawing the whole world every frame"
3446
+ "stop the water reflection redrawing the whole world every frame",
3447
+ "automatically reflect terrain and large casters without redrawing instanced small props"
3263
3448
  ],
3264
3449
  "summary": "Give a horizontal water surface the world mirrored in it, the world beneath it, and the metres of water between them.",
3265
3450
  "supersedes": [],
@@ -3399,6 +3584,27 @@
3399
3584
  "supersedes": [],
3400
3585
  "symbol": "playtest"
3401
3586
  },
3587
+ {
3588
+ "aliases": [],
3589
+ "constraints": [
3590
+ "desktop only, and the game host must be built with the CSS backend (`TN_ENABLE_CSS_UI=1`); Android, iOS and web phones render a React HUD in a web overlay instead",
3591
+ "import `react`, never `react-dom`, from a native entry",
3592
+ "styling is CSS resolved by the native engine; JS only mirrors the element tree"
3593
+ ],
3594
+ "example": "const root = createCssUiRoot();\nroot.render(createElement(\"section\", { className: \"fixed inset-0 bg-zinc-900/90\" }, \"READY\"));",
3595
+ "importPath": "@threenative/core/react-css",
3596
+ "kind": "function",
3597
+ "overrides": [],
3598
+ "package": "@threenative/core",
3599
+ "signature": "export function createCssUiRoot(options: ICssUiRootOptions = { … }",
3600
+ "situations": [
3601
+ "mount a React HUD on the desktop host with no DOM in the runtime",
3602
+ "write one React component and run it on the web and on the desktop host"
3603
+ ],
3604
+ "summary": "Mount React into a native CSS engine.",
3605
+ "supersedes": [],
3606
+ "symbol": "createCssUiRoot"
3607
+ },
3402
3608
  {
3403
3609
  "aliases": [],
3404
3610
  "constraints": [
@@ -3693,10 +3899,10 @@
3693
3899
  {
3694
3900
  "aliases": [],
3695
3901
  "constraints": [
3696
- "the package's world.json must carry `terrain.layers.table` and `terrain.layers.splat`, written by the `export_terrain_layers.py` recipe",
3697
- "WebGPU allows 16 sampled textures per stage: planes + diffuse maps + normal maps must fit"
3902
+ "the package's world.json must carry `terrain.layers.table` and `terrain.layers.splat`, written by `export_terrain_layers` in the `export_world.py` recipe",
3903
+ "WebGPU allows 16 sampled textures per stage: same-size layers stack into one array texture per set, and `TN_TERRAIN_SPLAT samplers=<n>` reports what is left"
3698
3904
  ],
3699
- "example": "const surface = await loadTerrainSplat({ assets: ctx.assets, url: \"world/world.json\" });\nconst world = await WorldCells.load({ assets: ctx.assets, url: \"world/world.json\", surface, follow, ring: 2 });",
3905
+ "example": "const surface = await loadTerrainSplat({ assets: ctx.assets, renderer: ctx.renderer, url: \"world/world.json\" });\nconst world = await WorldCells.load({ assets: ctx.assets, url: \"world/world.json\", surface, follow, ring: 2 });",
3700
3906
  "importPath": "@threenative/core/world",
3701
3907
  "kind": "function",
3702
3908
  "overrides": [
@@ -3708,7 +3914,7 @@
3708
3914
  "terrain textured by splat masks exported from Blender with the world package",
3709
3915
  "the game's terrain should match the DCC's terrain material without a second copy"
3710
3916
  ],
3711
- "summary": "The splat terrain surface a world package describes, for `WorldCells.load({ surface })`. Layers blend over a base by mask channels read as linear data (the masks ship raw, beside the heightmap, so no cook moves a blend threshold), with noise-broken edges and macro brightness variation. Texture sets tile in world metres on the package's ground plane (x, -z: a Z-up authoring tool's x and y), cliffs can be triplanar, and the base plus any layer that asks carries a normal map. Nothing here is a look choice: textures, tiles, tints, thresholds and noise scales all come from the package's table, which the game authors once and its DCC shares.",
3917
+ "summary": "The splat terrain surface a world package describes, for `WorldCells.load({ surface })`. Layers blend over a base by mask channels read as linear data (the masks ship raw, beside the heightmap, so no cook moves a blend threshold), with noise-broken edges and macro brightness variation. Texture sets tile in world metres on the package's ground plane (x, -z: a Z-up authoring tool's x and y), cliffs can be triplanar, and the base plus any layer that asks carries a normal map. Each layer answers light from its own ORM map where the table ships one and from the table's own roughness and metalness where it does not; a layer that states neither is matte and dielectric, and named in a warning. Nothing here is a look choice: textures, tiles, tints, thresholds, surface response and noise scales all come from the package's table, which the game authors once and its DCC shares.",
3712
3918
  "supersedes": [],
3713
3919
  "symbol": "loadTerrainSplat"
3714
3920
  },
@@ -3781,7 +3987,7 @@
3781
3987
  "importPath": "@threenative/core/world",
3782
3988
  "kind": "class",
3783
3989
  "overrides": [
3784
- "tileSize, tileResolution, lodFactors, lodDistances, skirtDepth, streamRadius, colliderRadius, validate, and budgets"
3990
+ "tileSize, tileResolution, lodFactors, lodDistances, skirtDepth, streamRadius, colliderRadius, mergeTiles, validate, and budgets"
3785
3991
  ],
3786
3992
  "package": "@threenative/core",
3787
3993
  "signature": "export class TerrainTiles extends Object3D implements IComputeDriven { … }",
@@ -3839,7 +4045,8 @@
3839
4045
  "refilters are bounded by `rebuildsPerUpdate` (default 16) per update, nearest cell first",
3840
4046
  "admission is bounded by `admissionBudgetMs` (default 2) per update across every path, plus at most one unit each for terrain and props; while props are queued terrain takes at most half, so neither starves the other, and a deferred cell keeps drawing what it has",
3841
4047
  "SkinnedMesh parts are skipped; an instanced copy would draw one rest pose",
3842
- "a baked chain's switch distances are measured against `autoLod` (default 4 px of error over 60° and 1080 raster rows), because an instanced draw cannot select a level per instance; an asset with authored `lods` never consults it",
4048
+ "a baked chain's switch distances are measured against `autoLod` (default 4 px of error over 60° and 1080 raster rows), because an instanced draw cannot select a level per instance; an asset with nonempty authored `lods` never consults it; explicit empty lists enroll only unchanged static geometry/material parts",
4049
+ "eligible static sources can use cooked HLOD (chunk-only alongside GPU scatter, whole-cell on CPU) after compilation and an observed main-context backend submission; projected-error hysteresis requires actual source triangle reduction and no extra material draws, unsupported or shared source stays resident, and collision/shadow paths retain source representations; stats().hlod counts lifecycle and charged resources, not GPU timing or physical allocation",
3843
4050
  "`prewarmed` resolves once every prewarmed shared batch has been drawn; a game with a loading screen waits on it, and `stats().pendingPrewarm` is the same gate as a number",
3844
4051
  "every `asset:level:part` is one InstancedMesh for the main pass, plus one caster InstancedMesh per world-grid square of `clusterSize` on the shadow caster layer, so the main pass draws one mesh per key and a shadow level submits only the squares it covers",
3845
4052
  "two definitions the asset loader resolves to one model — the same cooked `glb`, the same `lods` at the same distances, the same `maxDistance` and bounds — are one asset under the lexicographically smallest id: one model load, one set of `asset:level:part` keys, one prewarm and one refcount, released when the last cell holding any member of the group leaves the ring; `TN_WORLD_ASSET_ALIAS` reports how many of the package's assets are really distinct",
@@ -3851,7 +4058,7 @@
3851
4058
  "importPath": "@threenative/core/world",
3852
4059
  "kind": "class",
3853
4060
  "overrides": [
3854
- "ring, budgets, terrain tile size/resolution, terrain stream and collider radius, `transparentScatter`, `clusterSize` and `shadows.invalidate`, load `concurrency`, `rebuildsPerUpdate`, `admissionBudgetMs` and the package's per-asset maxDistance"
4061
+ "`hlod: false` keeps source rendering; ring, budgets, terrain tile size/resolution, terrain stream and collider radius, `transparentScatter`, `clusterSize` and `shadows.invalidate`, load `concurrency`, `rebuildsPerUpdate`, `admissionBudgetMs` and the package's per-asset maxDistance"
3855
4062
  ],
3856
4063
  "package": "@threenative/core",
3857
4064
  "signature": "export class WorldCells extends Group implements IComputeDriven { … }",
@@ -3860,7 +4067,7 @@
3860
4067
  "keep scattered props and hand-placed chunks resident around a moving player",
3861
4068
  "honour per-asset draw distances and hard streaming budgets without a mid-frame throw"
3862
4069
  ],
3863
- "summary": "Stream a Blender-authored world package by cell and keep it resident around a followed point. The class composes `TerrainTiles` for the package's heightmap, builds one `InstancedBatch` per resident cell asset run, distance level and mesh part, and loads hand-placed chunk GLBs through `loadAll` + `addInSlices`. Ring residency, per-asset `maxDistance` filtering, the per-asset `lods` levels, hard budgets and generation-tokened cancellation all live here; every geometry, material and surface still comes from the package's GLBs and the game. An asset is drawn per part, not per model: a GLB with several primitives is one `InstancedBatch` each, and a scattered part whose own material is transparent draws as an alpha cutout unless the game asks for blending, because an `InstancedMesh` cannot sort its instances. An asset whose package entry names no `lods` is drawn at the levels its own model carries a baked AutoLOD chain for: the levels an instanced draw cannot reach by itself, switched at the distance their error projects over the `autoLod` viewport. Authored `lods` win; a chain is only a fallback.",
4070
+ "summary": "Stream a Blender-authored world package by cell and keep it resident around a followed point. The class composes `TerrainTiles` for the package's heightmap, builds one `InstancedBatch` per resident cell asset run, distance level and mesh part, and loads hand-placed chunk GLBs through `loadAll` + `addInSlices`. Ring residency, CPU per-asset `maxDistance` filtering, GPU dispatch culling, the per-asset `lods` levels, hard budgets and generation-tokened cancellation all live here; every geometry, material and surface still comes from the package's GLBs and the game. An asset is drawn per part, not per model: a GLB with several primitives is one `InstancedBatch` each, and a scattered part whose own material is transparent draws as an alpha cutout unless the game asks for blending, because an `InstancedMesh` cannot sort its instances. An asset with no nonempty authored `lods` can draw its own model's baked AutoLOD chain at distances measured over the `autoLod` viewport. An explicit empty list enrolls only unchanged static parts; section ranges, custom attributes, alpha foliage and vertex deformation retain source geometry.",
3864
4071
  "supersedes": [],
3865
4072
  "symbol": "WorldCells"
3866
4073
  },
@@ -3970,6 +4177,7 @@
3970
4177
  "kind": "class",
3971
4178
  "overrides": [],
3972
4179
  "package": "@threenative/physics",
4180
+ "requires": ["npm i @threenative/physics"],
3973
4181
  "signature": "export class Area3D { … }",
3974
4182
  "situations": [
3975
4183
  "detect when an enemy enters a trigger area",
@@ -4015,6 +4223,7 @@
4015
4223
  "kind": "function",
4016
4224
  "overrides": [],
4017
4225
  "package": "@threenative/physics",
4226
+ "requires": ["npm i @threenative/physics"],
4018
4227
  "signature": "export function boxFootprint(halfWidth: number, halfDepth: number): ISnowFootprint { … }",
4019
4228
  "situations": [
4020
4229
  "let a crate, platform or plank press a rectangular pit into snow",
@@ -4035,6 +4244,7 @@
4035
4244
  "kind": "function",
4036
4245
  "overrides": [],
4037
4246
  "package": "@threenative/physics",
4247
+ "requires": ["npm i @threenative/physics"],
4038
4248
  "signature": "export function buildStaticColliders( context: IStaticColliderContext, root: Object3D, filter?: StaticColliderFilter, ): readonly RigidBody3D[] { … }",
4039
4249
  "situations": [
4040
4250
  "make the level I built stop the player",
@@ -4052,6 +4262,7 @@
4052
4262
  "kind": "class",
4053
4263
  "overrides": ["buoyancy disables force application while submergedFraction remains measured"],
4054
4264
  "package": "@threenative/physics",
4265
+ "requires": ["npm i @threenative/physics"],
4055
4266
  "signature": "export class Buoyancy3D { … }",
4056
4267
  "situations": ["float a boat on waves", "keep a hull above a moving water surface"],
4057
4268
  "summary": "Float a rigid body on a game-owned height source with fixed-step force ordering.",
@@ -4066,6 +4277,7 @@
4066
4277
  "kind": "function",
4067
4278
  "overrides": [],
4068
4279
  "package": "@threenative/physics",
4280
+ "requires": ["npm i @threenative/physics"],
4069
4281
  "signature": "export function capsuleFootprint(halfHeight: number, radius: number): ISnowFootprint { … }",
4070
4282
  "situations": [
4071
4283
  "let a fallen capsule, limb or barrel leave a linear imprint in snow",
@@ -4092,6 +4304,7 @@
4092
4304
  "kind": "class",
4093
4305
  "overrides": [],
4094
4306
  "package": "@threenative/physics",
4307
+ "requires": ["npm i @threenative/physics"],
4095
4308
  "signature": "export class CharacterBody3D { … }",
4096
4309
  "situations": [
4097
4310
  "move an enemy or player through a level",
@@ -4109,6 +4322,7 @@
4109
4322
  "kind": "class",
4110
4323
  "overrides": [],
4111
4324
  "package": "@threenative/physics",
4325
+ "requires": ["npm i @threenative/physics"],
4112
4326
  "signature": "export class CollisionShape3D { … }",
4113
4327
  "situations": [
4114
4328
  "add a capsule or box collider to a character",
@@ -4126,6 +4340,7 @@
4126
4340
  "kind": "function",
4127
4341
  "overrides": [],
4128
4342
  "package": "@threenative/physics",
4343
+ "requires": ["npm i @threenative/physics"],
4129
4344
  "signature": "export function interactionGroups(layer: number, mask: number): number { … }",
4130
4345
  "situations": [
4131
4346
  "make an enemy collide with the world but not pickups",
@@ -4146,6 +4361,7 @@
4146
4361
  "kind": "class",
4147
4362
  "overrides": [],
4148
4363
  "package": "@threenative/physics",
4364
+ "requires": ["npm i @threenative/physics"],
4149
4365
  "signature": "export class Joint3D { … }",
4150
4366
  "situations": [
4151
4367
  "constrain a rigid body to another body",
@@ -4164,6 +4380,7 @@
4164
4380
  "kind": "class",
4165
4381
  "overrides": [],
4166
4382
  "package": "@threenative/physics",
4383
+ "requires": ["npm i @threenative/physics"],
4167
4384
  "signature": "export class PhysicsDirectSpaceState3D { … }",
4168
4385
  "situations": [
4169
4386
  "raycast for visibility or aiming",
@@ -4181,6 +4398,7 @@
4181
4398
  "kind": "function",
4182
4399
  "overrides": [],
4183
4400
  "package": "@threenative/physics",
4401
+ "requires": ["npm i @threenative/physics"],
4184
4402
  "signature": "export function rapier(options: IPhysicsOptions = { … }",
4185
4403
  "situations": [
4186
4404
  "add physics to a portable game",
@@ -4203,6 +4421,7 @@
4203
4421
  "continuousCollision: false opts one body out while body.continuousCollision still reports the effective setting"
4204
4422
  ],
4205
4423
  "package": "@threenative/physics",
4424
+ "requires": ["npm i @threenative/physics"],
4206
4425
  "signature": "export class RigidBody3D { … }",
4207
4426
  "situations": [
4208
4427
  "give a crate or prop physical motion",
@@ -4226,6 +4445,7 @@
4226
4445
  "kind": "function",
4227
4446
  "overrides": [],
4228
4447
  "package": "@threenative/physics",
4448
+ "requires": ["npm i @threenative/physics"],
4229
4449
  "signature": "export function softBodyCollision(...bodies: readonly RigidBody3D[]): ISoftBodyCollision { … }",
4230
4450
  "situations": [
4231
4451
  "stop a cloth flag, cape, or curtain at an existing physics wall",
@@ -4254,6 +4474,7 @@
4254
4474
  "continuousCollision is on for the chassis, so a fast car cannot tunnel through a wall"
4255
4475
  ],
4256
4476
  "package": "@threenative/physics",
4477
+ "requires": ["npm i @threenative/physics"],
4257
4478
  "signature": "export class VehicleBody3D extends RigidBody3D { … }",
4258
4479
  "situations": [
4259
4480
  "drive a car, truck or bike around a track",
@@ -4273,6 +4494,7 @@
4273
4494
  "kind": "class",
4274
4495
  "overrides": [],
4275
4496
  "package": "@threenative/physics",
4497
+ "requires": ["npm i @threenative/physics"],
4276
4498
  "signature": "export class NavigationAgent3D { … }",
4277
4499
  "situations": [
4278
4500
  "enemy walks around a wall",
@@ -4295,6 +4517,7 @@
4295
4517
  "kind": "class",
4296
4518
  "overrides": [],
4297
4519
  "package": "@threenative/physics",
4520
+ "requires": ["npm i @threenative/physics"],
4298
4521
  "signature": "export class NavigationObstacle3D { … }",
4299
4522
  "situations": [
4300
4523
  "keep navigation agents away from a blocking prop",
@@ -4312,6 +4535,7 @@
4312
4535
  "kind": "class",
4313
4536
  "overrides": [],
4314
4537
  "package": "@threenative/physics",
4538
+ "requires": ["npm i @threenative/physics"],
4315
4539
  "signature": "export class NavigationRegion3D { … }",
4316
4540
  "situations": [
4317
4541
  "let enemies walk around level geometry",
@@ -4329,6 +4553,7 @@
4329
4553
  "kind": "function",
4330
4554
  "overrides": [],
4331
4555
  "package": "@threenative/physics",
4556
+ "requires": ["npm i @threenative/physics"],
4332
4557
  "signature": "export function recast(): NavigationPlugin { … }",
4333
4558
  "situations": ["enemy walks around a wall", "NPC patrols a level and chases a player"],
4334
4559
  "summary": "Install navmesh pathfinding and crowd avoidance.",
@@ -4722,6 +4947,20 @@
4722
4947
  "supersedes": [],
4723
4948
  "symbol": "assertCaptureNotBlank"
4724
4949
  },
4950
+ {
4951
+ "aliases": [],
4952
+ "constraints": ["keeps the uniform-frame checks and replaces only the bright-pixel floor"],
4953
+ "example": "assertDesktopCaptureNotBlank(png, \"panned-culled.png\");",
4954
+ "importPath": "@threenative/playtest/capture",
4955
+ "kind": "function",
4956
+ "overrides": [],
4957
+ "package": "@threenative/playtest",
4958
+ "signature": "export function assertDesktopCaptureNotBlank(png: Buffer, label: string): ICaptureFrameStats { … }",
4959
+ "situations": ["guard a native desktop capture of a 3D scene"],
4960
+ "summary": "Fail closed when a desktop-host frame shows no rendered content. A native desktop frame has no HTML overlay, so the browser bright-pixel floor does not apply.",
4961
+ "supersedes": [],
4962
+ "symbol": "assertDesktopCaptureNotBlank"
4963
+ },
4725
4964
  {
4726
4965
  "aliases": [],
4727
4966
  "constraints": ["the assertion throws instead of returning a false pass"],
@@ -4756,6 +4995,20 @@
4756
4995
  "supersedes": [],
4757
4996
  "symbol": "CaptureGuardError"
4758
4997
  },
4998
+ {
4999
+ "aliases": [],
5000
+ "constraints": ["does not acquire another screenshot or alter frame timing"],
5001
+ "example": "collectRegionalTone(png, assertions, \"character\", \"posed\");",
5002
+ "importPath": "@threenative/playtest/capture",
5003
+ "kind": "function",
5004
+ "overrides": [],
5005
+ "package": "@threenative/playtest",
5006
+ "signature": "export function collectRegionalTone( png: Buffer, assertions: readonly IPlaytestToneAssertion[], label: string, atStep?: string, ): IPlaytestRegionalToneObservation[] { … }",
5007
+ "situations": ["measure a specified pixel crop in a captured playtest frame"],
5008
+ "summary": "Collect opt-in regional tone observations from the same acquired PNG.",
5009
+ "supersedes": [],
5010
+ "symbol": "collectRegionalTone"
5011
+ },
4759
5012
  {
4760
5013
  "aliases": [],
4761
5014
  "constraints": [],
@@ -4805,6 +5058,24 @@
4805
5058
  "supersedes": [],
4806
5059
  "symbol": "jsonByteLength"
4807
5060
  },
5061
+ {
5062
+ "aliases": [],
5063
+ "constraints": [
5064
+ "throws on an unrecognised value instead of falling back to a fixed-step run"
5065
+ ],
5066
+ "example": "if (requestedPlaytestClockMode() === \"wall-clock\") host.pumpDrivesTheSimulation();",
5067
+ "importPath": "@threenative/playtest/protocol",
5068
+ "kind": "function",
5069
+ "overrides": [],
5070
+ "package": "@threenative/playtest",
5071
+ "signature": "export function requestedPlaytestClockMode(): PlaytestClockMode | undefined { … }",
5072
+ "situations": [
5073
+ "report which clock a playtest producer is really running on, before judging its ticks"
5074
+ ],
5075
+ "summary": "The clock the host asked for, or `undefined` for the default deterministic run. `wall-clock` is the production profile's opt-in and the only one this protocol has. An unrecognised value throws instead of falling back, because a misspelling that quietly left the loop frozen would publish a frame rate for a game that was not playing. Read at the moment it is needed rather than once at install: a request that arrives after the producer was installed is still a request, and a producer that missed it would judge a live frame pump by a count it never asked for.",
5076
+ "supersedes": [],
5077
+ "symbol": "requestedPlaytestClockMode"
5078
+ },
4808
5079
  {
4809
5080
  "aliases": [],
4810
5081
  "constraints": ["Android evidence must name its target and transport"],
@@ -4830,7 +5101,7 @@
4830
5101
  "kind": "function",
4831
5102
  "overrides": [],
4832
5103
  "package": "@threenative/playtest",
4833
- "signature": "export async function advanceFixedStep( page: Page, bridge: Pick<IPlaytestBridgeClient, \"advance\">, ticks: number, ): Promise<void> { … }",
5104
+ "signature": "export async function advanceFixedStep( page: Page, bridge: Pick<IPlaytestBridgeClient, \"advance\">, ticks: number, render = false, ): Promise<void> { … }",
4834
5105
  "situations": [
4835
5106
  "run a complete browser or device playtest",
4836
5107
  "capture diagnostics and screenshots from a managed server"
@@ -5023,6 +5294,23 @@
5023
5294
  "supersedes": [],
5024
5295
  "symbol": "decideDisplayStrategy"
5025
5296
  },
5297
+ {
5298
+ "aliases": [],
5299
+ "constraints": ["the mailbox lifecycle must be disposed after the run"],
5300
+ "example": "const driver = new DesktopPlaytestDriver(options);",
5301
+ "importPath": "@threenative/playtest/runner",
5302
+ "kind": "function",
5303
+ "overrides": [],
5304
+ "package": "@threenative/playtest",
5305
+ "signature": "export function desktopConsoleType(stream: \"stderr\" | \"stdout\", line: string): string { … }",
5306
+ "situations": [
5307
+ "run a desktop target through the playtest protocol",
5308
+ "exchange observations with a native desktop host"
5309
+ ],
5310
+ "summary": "Drive a local desktop playtest mailbox.",
5311
+ "supersedes": [],
5312
+ "symbol": "desktopConsoleType"
5313
+ },
5026
5314
  {
5027
5315
  "aliases": [],
5028
5316
  "constraints": ["the mailbox lifecycle must be disposed after the run"],
@@ -6060,6 +6348,125 @@
6060
6348
  "supersedes": [],
6061
6349
  "symbol": "ThreePlaytestPhysicsRecorder"
6062
6350
  },
6351
+ {
6352
+ "aliases": [],
6353
+ "constraints": [
6354
+ "identity parent required; material and motion are editable game source; no move/Mixer/composer writer exists"
6355
+ ],
6356
+ "example": "const wolf = createAnimalActor(bake, { motion, material, ground });",
6357
+ "importPath": "@threenative/procedural-animals",
6358
+ "kind": "function",
6359
+ "overrides": [],
6360
+ "package": "@threenative/procedural-animals",
6361
+ "requires": ["npm i @threenative/procedural-animals"],
6362
+ "signature": "export function createAnimalActor(bake: IAnimalBake, options: IAnimalActorOptions) { … }",
6363
+ "situations": ["follow a baked animal from accepted fixed-step Rapier state"],
6364
+ "summary": "Own one actor's pose/lifetime, accepting the completed physics state as its only root writer.",
6365
+ "supersedes": [],
6366
+ "symbol": "createAnimalActor"
6367
+ },
6368
+ {
6369
+ "aliases": [],
6370
+ "constraints": [
6371
+ "this creates bind geometry only; game-owned DQS material and animated bounds remain required"
6372
+ ],
6373
+ "example": "const { bake, geometry } = createAnimalGeometry(bytes);",
6374
+ "importPath": "@threenative/procedural-animals",
6375
+ "kind": "function",
6376
+ "overrides": [],
6377
+ "package": "@threenative/procedural-animals",
6378
+ "requires": ["npm i @threenative/procedural-animals"],
6379
+ "signature": "export function createAnimalGeometry(buffer: ArrayBuffer): { … }",
6380
+ "situations": ["construct a Three.js geometry from a validated procedural wolf bake"],
6381
+ "summary": "Validates all bytes before constructing geometry with the bake's skin and rig attributes.",
6382
+ "supersedes": [],
6383
+ "symbol": "createAnimalGeometry"
6384
+ },
6385
+ {
6386
+ "aliases": [],
6387
+ "constraints": ["a corrupt served bake rejects rather than falling back to a different file"],
6388
+ "example": "const bake = await loadAnimalBake(ctx.assets, \"wolf.animal\");",
6389
+ "importPath": "@threenative/procedural-animals",
6390
+ "kind": "function",
6391
+ "overrides": [],
6392
+ "package": "@threenative/procedural-animals",
6393
+ "requires": ["npm i @threenative/procedural-animals"],
6394
+ "signature": "export async function loadAnimalBake( assets: IAnimalAssetResolver, logicalPath: string, options: { … }",
6395
+ "situations": ["load a cooked animal from ctx.assets without runtime generation"],
6396
+ "summary": "Resolves and loads a prebuilt wolf through the game's ordinary asset resolver.",
6397
+ "supersedes": [],
6398
+ "symbol": "loadAnimalBake"
6399
+ },
6400
+ {
6401
+ "aliases": [],
6402
+ "constraints": [
6403
+ "unknown revisions, malformed sections, indices and skin weights throw by name"
6404
+ ],
6405
+ "example": "const bake = parseAnimalBake(bytes);",
6406
+ "importPath": "@threenative/procedural-animals",
6407
+ "kind": "function",
6408
+ "overrides": [],
6409
+ "package": "@threenative/procedural-animals",
6410
+ "requires": ["npm i @threenative/procedural-animals"],
6411
+ "signature": "export function parseAnimalBake(buffer: ArrayBuffer): IAnimalBake { … }",
6412
+ "situations": ["validate a baked procedural animal before allocating geometry"],
6413
+ "summary": "Validates a pinned wolf PANM bake before constructing any renderer resource.",
6414
+ "supersedes": [],
6415
+ "symbol": "parseAnimalBake"
6416
+ },
6417
+ {
6418
+ "aliases": [],
6419
+ "constraints": [
6420
+ "only .animal inputs are interpreted; corruption fails the cook, without regeneration"
6421
+ ],
6422
+ "example": "await compileAssets({ passes: [animalBakePass()] });",
6423
+ "importPath": "@threenative/procedural-animals/build",
6424
+ "kind": "function",
6425
+ "overrides": [],
6426
+ "package": "@threenative/procedural-animals",
6427
+ "requires": ["npm i @threenative/procedural-animals"],
6428
+ "signature": "export function animalBakePass() { … }",
6429
+ "situations": ["cook staged animal bakes through the ordinary asset pipeline"],
6430
+ "summary": "Validate staged PANM sources inside the existing asset compiler; it owns the hashed manifest.",
6431
+ "supersedes": [],
6432
+ "symbol": "animalBakePass"
6433
+ },
6434
+ {
6435
+ "aliases": [],
6436
+ "constraints": [
6437
+ "exact pinned Node runtime, donor revision, options and generated bytes are validated; no worker is created"
6438
+ ],
6439
+ "example": "const bytes = await bakeWolf({ seed: 7, tier: \"crowd\" });",
6440
+ "importPath": "@threenative/procedural-animals/build",
6441
+ "kind": "function",
6442
+ "overrides": [],
6443
+ "package": "@threenative/procedural-animals",
6444
+ "requires": ["npm i @threenative/procedural-animals"],
6445
+ "signature": "export async function bakeWolf(options: IWolfBakeOptions): Promise<ArrayBuffer> { … }",
6446
+ "situations": ["bake high and crowd wolf geometry before the ordinary asset cook"],
6447
+ "summary": "Bake the pinned wolf on the build machine, never on the portable runtime path.",
6448
+ "supersedes": [],
6449
+ "symbol": "bakeWolf"
6450
+ },
6451
+ {
6452
+ "aliases": [],
6453
+ "constraints": [
6454
+ "validation and generation complete before the destination is touched; temporary files are removed on failure"
6455
+ ],
6456
+ "example": "await bakeWolfToFile({ seed: 7, tier: \"crowd\" }, \"assets/wolf-crowd.animal\");",
6457
+ "importPath": "@threenative/procedural-animals/build",
6458
+ "kind": "function",
6459
+ "overrides": [],
6460
+ "package": "@threenative/procedural-animals",
6461
+ "requires": ["npm i @threenative/procedural-animals"],
6462
+ "signature": "export async function bakeWolfToFile( options: IWolfBakeOptions, destination: string, ): Promise<string> { … }",
6463
+ "situations": [
6464
+ "publish a generated wolf without replacing the last valid bake on interruption"
6465
+ ],
6466
+ "summary": "Stage a validated source bake with a same-directory atomic rename, then use compileAssets.",
6467
+ "supersedes": [],
6468
+ "symbol": "bakeWolfToFile"
6469
+ },
6063
6470
  {
6064
6471
  "aliases": [],
6065
6472
  "constraints": [
@@ -6510,6 +6917,776 @@
6510
6917
  "symbol": "sparkle",
6511
6918
  "aliases": []
6512
6919
  },
6920
+ {
6921
+ "aliases": [],
6922
+ "constraints": [
6923
+ "headless authoring; game applies transforms against its model bounds and actual terrain surface"
6924
+ ],
6925
+ "example": "const state = applyPlacementOverrides(terrain.evaluate(), document.placementOverrides ?? {});",
6926
+ "importPath": "@threenative/terrain",
6927
+ "kind": "function",
6928
+ "overrides": [
6929
+ "transform.grounding=false preserves requested Y while the game still measures clearance"
6930
+ ],
6931
+ "package": "@threenative/terrain",
6932
+ "requires": ["npm i -D @threenative/terrain"],
6933
+ "signature": "export function applyPlacementOverrides(state: ITerrainState, value: unknown): ITerrainState { … }",
6934
+ "situations": ["retain manual prop transforms across terrain scatter re-evaluation"],
6935
+ "summary": "Attach manual transforms to raw evaluated candidates and report orphan keys.",
6936
+ "supersedes": [],
6937
+ "symbol": "applyPlacementOverrides"
6938
+ },
6939
+ {
6940
+ "aliases": [],
6941
+ "constraints": [
6942
+ "no material is chosen; vertex colours exist only with a caller-supplied palette"
6943
+ ],
6944
+ "example": "const mesh = bakeMesh(new Terrain({ resolution: 17 }).evaluate());",
6945
+ "importPath": "@threenative/terrain",
6946
+ "kind": "function",
6947
+ "overrides": ["step, chunk bounds, skirtDepth and palette belong to the caller"],
6948
+ "package": "@threenative/terrain",
6949
+ "requires": ["npm i @threenative/terrain"],
6950
+ "signature": "export function bakeMesh( state: ITerrainState, { … }",
6951
+ "situations": ["bake an authored terrain into portable indexed mesh arrays"],
6952
+ "summary": "Bakes the recovered indexed top surface and optional vertical skirts into caller-owned arrays.",
6953
+ "supersedes": [],
6954
+ "symbol": "bakeMesh"
6955
+ },
6956
+ {
6957
+ "aliases": [],
6958
+ "constraints": [
6959
+ "collision origin is the southwest corner; engine Heightfield origin is its centre"
6960
+ ],
6961
+ "example": "const baked = bakeTerrain(new Terrain({ resolution: 129 }).evaluate(), { chunkCells: 64 });",
6962
+ "importPath": "@threenative/terrain",
6963
+ "kind": "function",
6964
+ "overrides": ["chunkCells, lodSteps, skirtDepth and palette are explicit authoring choices"],
6965
+ "package": "@threenative/terrain",
6966
+ "requires": ["npm i @threenative/terrain"],
6967
+ "signature": "export function bakeTerrain( state: ITerrainState, { … }",
6968
+ "situations": ["prepare terrain arrays and collision before a game starts"],
6969
+ "summary": "Bakes finite LOD chunks, the same collision samples and resolved placements.",
6970
+ "supersedes": [],
6971
+ "symbol": "bakeTerrain"
6972
+ },
6973
+ {
6974
+ "aliases": [],
6975
+ "constraints": [
6976
+ "headless authoring; no three, no DOM, and nothing here decides how the world looks"
6977
+ ],
6978
+ "example": "const { manifest, files } = bakeWorldPackage(state, { assets });",
6979
+ "importPath": "@threenative/terrain",
6980
+ "kind": "function",
6981
+ "overrides": [
6982
+ "every asset path, bound, LOD distance and cell size comes from the caller's options"
6983
+ ],
6984
+ "package": "@threenative/terrain",
6985
+ "requires": ["npm i -D @threenative/terrain"],
6986
+ "signature": "export function bakeWorldPackage( state: ITerrainState, options: IBakeWorldPackageOptions, ): IBakedWorldPackage { … }",
6987
+ "situations": ["hand an evaluated Strata terrain to a game without a Blender round trip"],
6988
+ "summary": "Bake an evaluated terrain into the engine's world package: a `world.json` manifest, a uint16 heightmap, a splat mask array, a placement buffer of eight float32 per instance, and the square cells that stream them. The encodings and row orders are the ones the Blender recipe `export_world.py` writes, so one runtime streams both without a second reader.",
6989
+ "supersedes": [],
6990
+ "symbol": "bakeWorldPackage"
6991
+ },
6992
+ {
6993
+ "aliases": [],
6994
+ "constraints": [
6995
+ "returns candidates only; the caller applies its own exact distance and level test"
6996
+ ],
6997
+ "example": "const rivers = createSegmentIndex(segments, 32); const wet = rivers.nearby(x, z).some(isWet);",
6998
+ "importPath": "@threenative/terrain",
6999
+ "kind": "function",
7000
+ "overrides": [],
7001
+ "package": "@threenative/terrain",
7002
+ "requires": ["npm i @threenative/terrain"],
7003
+ "signature": "export function createSegmentIndex<T>( segments: readonly IWaterSegment<T>[], cellSize: number, ): ISegmentIndex<T> { … }",
7004
+ "situations": [
7005
+ "test scatter candidates or terrain vertices against rivers and lakes without scanning every segment",
7006
+ "find which river stations can reach a heightfield vertex when baking a wet margin"
7007
+ ],
7008
+ "summary": "Build the index once per world; ask `nearby` per scatter candidate or heightfield vertex.",
7009
+ "supersedes": [],
7010
+ "symbol": "createSegmentIndex"
7011
+ },
7012
+ {
7013
+ "aliases": [],
7014
+ "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
7015
+ "example": "const png = await encodeHeightPNG(new Terrain({ resolution: 17 }).evaluate()); const heights = await decodeHeightPNG(png);",
7016
+ "importPath": "@threenative/terrain",
7017
+ "kind": "function",
7018
+ "overrides": [],
7019
+ "package": "@threenative/terrain",
7020
+ "requires": ["npm i @threenative/terrain"],
7021
+ "signature": "export async function decodeHeightPNG( input: Uint8Array | ArrayBuffer, options: IDecodeHeightPngOptions = { … }",
7022
+ "situations": ["import numerical PNG8 or PNG16 terrain elevations"],
7023
+ "summary": "CRC-checked bounded non-interlaced grayscale PNG height decoder.",
7024
+ "supersedes": [],
7025
+ "symbol": "decodeHeightPNG"
7026
+ },
7027
+ {
7028
+ "aliases": [],
7029
+ "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
7030
+ "example": "const decoded = decodeRAW16(new Uint8Array(8), { width: 2, height: 2, min: 0, max: 1 });",
7031
+ "importPath": "@threenative/terrain",
7032
+ "kind": "function",
7033
+ "overrides": [],
7034
+ "package": "@threenative/terrain",
7035
+ "requires": ["npm i @threenative/terrain"],
7036
+ "signature": "export function decodeRAW16( input: Uint8Array | ArrayBuffer, { … }",
7037
+ "situations": ["import a RAW16 terrain height buffer with explicit dimensions"],
7038
+ "summary": "Validates dimensions and range before decoding numerical height samples.",
7039
+ "supersedes": [],
7040
+ "symbol": "decodeRAW16"
7041
+ },
7042
+ {
7043
+ "aliases": [],
7044
+ "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
7045
+ "example": "const glb = encodeGLB(bakeMesh(new Terrain({ resolution: 17 }).evaluate()));",
7046
+ "importPath": "@threenative/terrain",
7047
+ "kind": "function",
7048
+ "overrides": [],
7049
+ "package": "@threenative/terrain",
7050
+ "requires": ["npm i @threenative/terrain"],
7051
+ "signature": "export function encodeGLB(input: IBakedMesh | readonly IBakedMesh[]) { … }",
7052
+ "situations": ["export baked terrain geometry without engine extensions"],
7053
+ "summary": "Legacy terrain-only GLB encoding with embedded mesh arrays and no chosen material.",
7054
+ "supersedes": [],
7055
+ "symbol": "encodeGLB"
7056
+ },
7057
+ {
7058
+ "aliases": [],
7059
+ "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
7060
+ "example": "const png = await encodeHeightPNG(new Terrain({ resolution: 17 }).evaluate());",
7061
+ "importPath": "@threenative/terrain",
7062
+ "kind": "function",
7063
+ "overrides": [],
7064
+ "package": "@threenative/terrain",
7065
+ "requires": ["npm i @threenative/terrain"],
7066
+ "signature": "export async function encodeHeightPNG(state: ITerrainState, options: Partial<IHeightRange> = { … }",
7067
+ "situations": ["export a terrain heightmap without an eight-bit colour conversion"],
7068
+ "summary": "Encodes numerical grayscale PNG16 with embedded elevation range.",
7069
+ "supersedes": [],
7070
+ "symbol": "encodeHeightPNG"
7071
+ },
7072
+ {
7073
+ "aliases": [],
7074
+ "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
7075
+ "example": "const raw = encodeRAW16(new Float32Array([0, 1]), { min: 0, max: 1 });",
7076
+ "importPath": "@threenative/terrain",
7077
+ "kind": "function",
7078
+ "overrides": [],
7079
+ "package": "@threenative/terrain",
7080
+ "requires": ["npm i @threenative/terrain"],
7081
+ "signature": "export function encodeRAW16( values: ArrayLike<number> & Iterable<number>, options: IRaw16Options = { … }",
7082
+ "situations": ["export terrain heights with a numerical range sidecar"],
7083
+ "summary": "Encodes finite metre elevations as an explicit-range RAW16 buffer.",
7084
+ "supersedes": [],
7085
+ "symbol": "encodeRAW16"
7086
+ },
7087
+ {
7088
+ "aliases": [],
7089
+ "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
7090
+ "example": "const maps = await encodeSplatPNGs(new Terrain({ resolution: 17 }).evaluate());",
7091
+ "importPath": "@threenative/terrain",
7092
+ "kind": "function",
7093
+ "overrides": [],
7094
+ "package": "@threenative/terrain",
7095
+ "requires": ["npm i @threenative/terrain"],
7096
+ "signature": "export async function encodeSplatPNGs(state: ITerrainState) { … }",
7097
+ "situations": ["export terrain splat weights as linear data"],
7098
+ "summary": "Encodes the eight linear material-weight channels as two RGBA images.",
7099
+ "supersedes": [],
7100
+ "symbol": "encodeSplatPNGs"
7101
+ },
7102
+ {
7103
+ "aliases": [],
7104
+ "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
7105
+ "example": "const archive = encodeZIP([{ name: \"height.raw\", bytes: new Uint8Array(8) }]);",
7106
+ "importPath": "@threenative/terrain",
7107
+ "kind": "function",
7108
+ "overrides": [],
7109
+ "package": "@threenative/terrain",
7110
+ "requires": ["npm i @threenative/terrain"],
7111
+ "signature": "export function encodeZIP(files: readonly IExportFile[]) { … }",
7112
+ "situations": ["archive derived terrain files without another dependency"],
7113
+ "summary": "Deterministic store-method ZIP with safe unique relative filenames.",
7114
+ "supersedes": [],
7115
+ "symbol": "encodeZIP"
7116
+ },
7117
+ {
7118
+ "aliases": [],
7119
+ "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
7120
+ "example": "const gradient = gradientAt(new Terrain({ resolution: 17 }).evaluate(), 0, 0);",
7121
+ "importPath": "@threenative/terrain",
7122
+ "kind": "function",
7123
+ "overrides": [],
7124
+ "package": "@threenative/terrain",
7125
+ "requires": ["npm i @threenative/terrain"],
7126
+ "signature": "export function gradientAt(grid: ISampledGrid, x: number, z: number): [number, number] { … }",
7127
+ "situations": ["measure an authored terrain gradient in metres"],
7128
+ "summary": "World-space height gradient from the canonical samples.",
7129
+ "supersedes": [],
7130
+ "symbol": "gradientAt"
7131
+ },
7132
+ {
7133
+ "aliases": [],
7134
+ "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
7135
+ "example": "const terrain = new Terrain({ resolution: 17 }); const file = await makeExport(terrain.evaluate(), terrain.toJSON(), \"project\");",
7136
+ "importPath": "@threenative/terrain",
7137
+ "kind": "function",
7138
+ "overrides": [],
7139
+ "package": "@threenative/terrain",
7140
+ "requires": ["npm i @threenative/terrain"],
7141
+ "signature": "export async function makeExport( state: ITerrainState, recipe: ITerrainDocument, kind: ExportKind, ): Promise<IExportArchive> { … }",
7142
+ "situations": ["export a terrain recipe and its numerical runtime data"],
7143
+ "summary": "Recovered numerical/project exports; GLB/runtime outputs contain terrain only.",
7144
+ "supersedes": [],
7145
+ "symbol": "makeExport"
7146
+ },
7147
+ {
7148
+ "aliases": [],
7149
+ "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
7150
+ "example": "const height = sampleHeight(new Terrain({ resolution: 17 }).evaluate(), 0, 0);",
7151
+ "importPath": "@threenative/terrain",
7152
+ "kind": "function",
7153
+ "overrides": [],
7154
+ "package": "@threenative/terrain",
7155
+ "requires": ["npm i @threenative/terrain"],
7156
+ "signature": "sampleHeight = (grid: ISampledGrid, x: number, z: number): number => sampleGrid( grid.height, grid.resolution, grid.resolution, x / grid.size + 0.5, z / grid.size + 0.5, )",
7157
+ "situations": ["query an authored heightfield at world coordinates"],
7158
+ "summary": "Bilinear query of canonical height samples; triangle sampling is a separate contract.",
7159
+ "supersedes": [],
7160
+ "symbol": "sampleHeight"
7161
+ },
7162
+ {
7163
+ "aliases": [],
7164
+ "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
7165
+ "example": "const slope = slopeAtIndex(new Terrain({ resolution: 17 }).evaluate(), 0);",
7166
+ "importPath": "@threenative/terrain",
7167
+ "kind": "function",
7168
+ "overrides": [],
7169
+ "package": "@threenative/terrain",
7170
+ "requires": ["npm i @threenative/terrain"],
7171
+ "signature": "export function slopeAtIndex(grid: ISampledGrid, i: number): number { … }",
7172
+ "situations": ["measure terrain slope for authoring diagnostics"],
7173
+ "summary": "Slope in degrees at a heightfield sample.",
7174
+ "supersedes": [],
7175
+ "symbol": "slopeAtIndex"
7176
+ },
7177
+ {
7178
+ "aliases": [],
7179
+ "constraints": [
7180
+ "interior vertices only (edges have one-sided differences); quantile must be in [0, 1]"
7181
+ ],
7182
+ "example": "const steep = slopeQuantile(grid, 0.98); if (slopeAt(x, z) > Math.min(30, steep)) placeRock(x, z);",
7183
+ "importPath": "@threenative/terrain",
7184
+ "kind": "function",
7185
+ "overrides": [],
7186
+ "package": "@threenative/terrain",
7187
+ "requires": ["npm i @threenative/terrain"],
7188
+ "signature": "export function slopeQuantile(grid: ISampledGrid, quantile: number): number { … }",
7189
+ "situations": [
7190
+ "place rocks or cliffs on a terrain's own steepest ground instead of a fixed slope in degrees"
7191
+ ],
7192
+ "summary": "A slope, in degrees, that the given share of this terrain's interior vertices lie at or below. Placement rules keyed to fixed degrees break when a world is rebaked smoother or rougher: an outcrop rule of \"over 30 degrees\" placed nothing on a forest whose 98th percentile is 22. Asking the terrain for its own steepest share keeps the rule meaning the same thing on every world.",
7193
+ "supersedes": [],
7194
+ "symbol": "slopeQuantile"
7195
+ },
7196
+ {
7197
+ "aliases": [],
7198
+ "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
7199
+ "example": "const points = splinePoints([[0, 4, 0], [10, 2, 10]], 3, false);",
7200
+ "importPath": "@threenative/terrain",
7201
+ "kind": "function",
7202
+ "overrides": [],
7203
+ "package": "@threenative/terrain",
7204
+ "requires": ["npm i @threenative/terrain"],
7205
+ "signature": "export function splinePoints( points: readonly (readonly [number, number, number])[], step = 3, smooth = true, ): [number, number, number][] { … }",
7206
+ "situations": ["sample a road or river profile without vertical overshoot"],
7207
+ "summary": "Recovered horizontal Catmull–Rom and vertically linear profile sampler.",
7208
+ "supersedes": [],
7209
+ "symbol": "splinePoints"
7210
+ },
7211
+ {
7212
+ "aliases": [],
7213
+ "constraints": [
7214
+ "authoring stays outside the game's steady-play graph; no renderer or physics is created",
7215
+ "units are metres with Y up; `size` is the world edge in metres (1 to 100000), centred on the origin",
7216
+ "`resolution` counts vertices per edge and must be one of 17, 33, 65, 129, 257, 513 or 1025",
7217
+ "`seed` is an integer from 0 to 4294967295; one document and seed evaluate to the same arrays",
7218
+ "`evaluate()` is synchronous on the calling thread: run it in a build script, never per frame",
7219
+ "no art is chosen or shipped: materials, models and texture paths belong to the game"
7220
+ ],
7221
+ "example": "const terrain = new Terrain({ size: 512, resolution: 257, seed: 73 }).noise({ id: \"hills\", amplitude: 35 });",
7222
+ "importPath": "@threenative/terrain",
7223
+ "kind": "class",
7224
+ "overrides": ["size, resolution, seed and all layer parameters are caller choices"],
7225
+ "package": "@threenative/terrain",
7226
+ "requires": ["npm i @threenative/terrain"],
7227
+ "signature": "export class Terrain { … }",
7228
+ "situations": [
7229
+ "author seeded terrain with noise, sculpting, erosion, roads, rivers and scatter",
7230
+ "generate a procedural heightmap landscape or island for a game"
7231
+ ],
7232
+ "summary": "Ordered, stable-ID terrain authoring with synchronous atomic transactions.",
7233
+ "supersedes": [],
7234
+ "symbol": "Terrain"
7235
+ },
7236
+ {
7237
+ "aliases": [],
7238
+ "constraints": ["evaluates authoring documents only; games consume pre-baked arrays"],
7239
+ "example": "const terrain = new Terrain({ resolution: 17 }); const evaluator = new TerrainEvaluator(); const state = evaluator.evaluate(terrain.toJSON());",
7240
+ "importPath": "@threenative/terrain",
7241
+ "kind": "class",
7242
+ "overrides": ["cacheMB bounds retained prefix data"],
7243
+ "package": "@threenative/terrain",
7244
+ "requires": ["npm i @threenative/terrain"],
7245
+ "signature": "export class TerrainEvaluator { … }",
7246
+ "situations": ["reuse terrain evaluation prefixes while authoring a finite heightfield"],
7247
+ "summary": "Recovered prefix-caching authoring evaluator. Returned buffers belong to the caller.",
7248
+ "supersedes": [],
7249
+ "symbol": "TerrainEvaluator"
7250
+ },
7251
+ {
7252
+ "aliases": [],
7253
+ "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
7254
+ "example": "validateDocument(new Terrain({ resolution: 17 }).toJSON());",
7255
+ "importPath": "@threenative/terrain",
7256
+ "kind": "function",
7257
+ "overrides": [],
7258
+ "package": "@threenative/terrain",
7259
+ "requires": ["npm i @threenative/terrain"],
7260
+ "signature": "export function validateDocument(doc: ITerrainDocument): void { … }",
7261
+ "situations": ["validate a terrain document before accepting an authoring write"],
7262
+ "summary": "Validates the recovered recipe schema, operation allow-lists and numeric bounds.",
7263
+ "supersedes": [],
7264
+ "symbol": "validateDocument"
7265
+ },
7266
+ {
7267
+ "aliases": [],
7268
+ "constraints": [
7269
+ "grounding defaults on only when omitted; position and scale have three components and quaternion is unit length"
7270
+ ],
7271
+ "example": "const transforms = validatePlacementOverrides(document.placementOverrides);",
7272
+ "importPath": "@threenative/terrain",
7273
+ "kind": "function",
7274
+ "overrides": ["grounding=false preserves authored Y and keeps clearance observable"],
7275
+ "package": "@threenative/terrain",
7276
+ "requires": ["npm i -D @threenative/terrain"],
7277
+ "signature": "export function validatePlacementOverrides( value: unknown = { … }",
7278
+ "situations": [
7279
+ "validate finite positive manual prop transforms before a terrain authoring transaction"
7280
+ ],
7281
+ "summary": "Validate and clone stable-key placement transforms before saving or previewing them.",
7282
+ "supersedes": [],
7283
+ "symbol": "validatePlacementOverrides"
7284
+ },
7285
+ {
7286
+ "aliases": [],
7287
+ "constraints": [
7288
+ "throws by name; HDR/EXR environment files and ordinary images are accepted, models are not"
7289
+ ],
7290
+ "example": "checkEnvironmentAssets({ sky: { image: \"dusk\" } }, document.assets ?? []);",
7291
+ "importPath": "@threenative/terrain/editor",
7292
+ "kind": "function",
7293
+ "overrides": ["the project owns which images it registers"],
7294
+ "package": "@threenative/terrain",
7295
+ "requires": ["npm i -D @threenative/terrain"],
7296
+ "signature": "export function checkEnvironmentAssets( environment: IEnvironment, assets: readonly { … }",
7297
+ "situations": [
7298
+ "refuse a saved environment whose sky or lighting image is not a registered file"
7299
+ ],
7300
+ "summary": "Check that the images an environment names are registered environment or image assets. @summary Validate the assets a preview environment refers to",
7301
+ "supersedes": [],
7302
+ "symbol": "checkEnvironmentAssets"
7303
+ },
7304
+ {
7305
+ "aliases": [],
7306
+ "constraints": ["framing only; an unknown target returns a named diagnostic and no camera"],
7307
+ "example": "const outcome = focusCamera(camera, { target: { kind: \"prop\", id: \"pine-3\" }, aspect: 16 / 9 }, resolve);",
7308
+ "importPath": "@threenative/terrain/editor",
7309
+ "kind": "function",
7310
+ "overrides": ["the view supplies target bounds, the live aspect and the camera to keep"],
7311
+ "package": "@threenative/terrain",
7312
+ "requires": ["npm i -D @threenative/terrain"],
7313
+ "signature": "export function focusCamera( camera: ISavedCamera, request: IFocusRequest, resolve: IFocusResolver, ): IFocusOutcome { … }",
7314
+ "situations": [
7315
+ "frame one selected prop, a registered landmark, a terrain region or a local point"
7316
+ ],
7317
+ "summary": "Frame a point, prop, landmark or region for the live viewport and projection. @summary Frame a focus target with an editor observation camera",
7318
+ "supersedes": [],
7319
+ "symbol": "focusCamera"
7320
+ },
7321
+ {
7322
+ "aliases": [],
7323
+ "constraints": [
7324
+ "headers and checksums only; throws by name for a damaged, truncated or oversize file"
7325
+ ],
7326
+ "example": "const report = inspectImage(bytes, \"png\", { maxDimension: 8192 });",
7327
+ "importPath": "@threenative/terrain/editor",
7328
+ "kind": "function",
7329
+ "overrides": ["the project sets the dimension limit"],
7330
+ "package": "@threenative/terrain",
7331
+ "requires": ["npm i -D @threenative/terrain"],
7332
+ "signature": "export function inspectImage( bytes: Uint8Array, format: string, limits: { … }",
7333
+ "situations": [
7334
+ "check an imported surface or environment image for damage and for the project's size limit"
7335
+ ],
7336
+ "summary": "Validate a PNG, JPEG, WebP, Radiance HDR or OpenEXR container and read its pixel size. @summary Inspect an image file's container and pixel size without decoding it",
7337
+ "supersedes": [],
7338
+ "symbol": "inspectImage"
7339
+ },
7340
+ {
7341
+ "aliases": [],
7342
+ "constraints": [
7343
+ "authoring data only; queries outside the extent or without observations throw"
7344
+ ],
7345
+ "example": "const observation = inspectSpatial(state, revision, { kind: \"point\", at: [0, 0] });",
7346
+ "importPath": "@threenative/terrain/editor",
7347
+ "kind": "function",
7348
+ "overrides": [
7349
+ "the caller owns the revision identity and the evaluated state being inspected"
7350
+ ],
7351
+ "package": "@threenative/terrain",
7352
+ "requires": ["npm i -D @threenative/terrain"],
7353
+ "signature": "export function inspectSpatial( state: ITerrainState, revision: string, query: ISpatialQuery, ): ISpatialObservation { … }",
7354
+ "situations": [
7355
+ "measure a point, profile a transect or score a saved reference against the world"
7356
+ ],
7357
+ "summary": "Read-only spatial inspection of one evaluated terrain revision.",
7358
+ "supersedes": [],
7359
+ "symbol": "inspectSpatial"
7360
+ },
7361
+ {
7362
+ "aliases": [],
7363
+ "constraints": [
7364
+ "browser authoring only; createView and materialColours are required game choices"
7365
+ ],
7366
+ "example": "await mountTerrainEditor({ createView: createEditorView, materialColours: terrainPalette });",
7367
+ "importPath": "@threenative/terrain/editor",
7368
+ "kind": "function",
7369
+ "overrides": ["createView owns the renderer scene, materials, lighting and camera"],
7370
+ "package": "@threenative/terrain",
7371
+ "requires": ["npm i -D @threenative/terrain"],
7372
+ "signature": "export async function mountTerrainEditor(options: { … }",
7373
+ "situations": ["open the terrain brush and layer GUI around game-owned rendering"],
7374
+ "summary": "Mount recovered terrain controls around the project-owned ThreeNative view.",
7375
+ "supersedes": [],
7376
+ "symbol": "mountTerrainEditor"
7377
+ },
7378
+ {
7379
+ "aliases": [],
7380
+ "constraints": ["authoring data only; non-finite, malformed and out-of-extent queries throw"],
7381
+ "example": "const probe = probeTerrain(state, revision, [12, -4]);",
7382
+ "importPath": "@threenative/terrain/editor",
7383
+ "kind": "function",
7384
+ "overrides": [
7385
+ "the caller owns the revision identity and the evaluated state being inspected"
7386
+ ],
7387
+ "package": "@threenative/terrain",
7388
+ "requires": ["npm i -D @threenative/terrain"],
7389
+ "signature": "export function probeTerrain( state: ITerrainState, revision: string, at: readonly number[], ): IPointObservation { … }",
7390
+ "situations": ["measure an authored terrain point with provenance and a revision identity"],
7391
+ "summary": "Probe the evaluated surface at one world point, separating bilinear from triangle values.",
7392
+ "supersedes": [],
7393
+ "symbol": "probeTerrain"
7394
+ },
7395
+ {
7396
+ "aliases": [],
7397
+ "constraints": [
7398
+ "pure: the input set is never mutated, an unknown id throws, and deleting the live camera falls back"
7399
+ ],
7400
+ "example": "const next = runCameraOperation(set, { op: \"activate\", id: \"survey\" });",
7401
+ "importPath": "@threenative/terrain/editor",
7402
+ "kind": "function",
7403
+ "overrides": ["the caller persists the returned set against its own revision"],
7404
+ "package": "@threenative/terrain",
7405
+ "requires": ["npm i -D @threenative/terrain"],
7406
+ "signature": "export function runCameraOperation(set: ICameraSet, operation: unknown): ICameraResult { … }",
7407
+ "situations": [
7408
+ "drive the terrain editor camera list from an agent or the GUI through one shared dispatch"
7409
+ ],
7410
+ "summary": "Run one create / get / list / update / delete / activate operation over saved cameras. @summary Apply an editor camera operation to a saved camera set",
7411
+ "supersedes": [],
7412
+ "symbol": "runCameraOperation"
7413
+ },
7414
+ {
7415
+ "aliases": [],
7416
+ "constraints": ["authoring metadata only; a null field returns to the project's own value"],
7417
+ "example": "const result = runEnvironmentOperation({}, { op: \"patch\", values: { sun: { elevation: 25 } } });",
7418
+ "importPath": "@threenative/terrain/editor",
7419
+ "kind": "function",
7420
+ "overrides": ["the project's render source decides what each value does"],
7421
+ "package": "@threenative/terrain",
7422
+ "requires": ["npm i -D @threenative/terrain"],
7423
+ "signature": "export function runEnvironmentOperation( current: IEnvironment, operation: unknown, ): IEnvironmentResult { … }",
7424
+ "situations": [
7425
+ "patch sun, haze, exposure or sea overrides from a controller or the editor GUI"
7426
+ ],
7427
+ "summary": "Apply one get / patch / reset against the saved environment overrides; the caller commits it. @summary Run one preview-environment operation",
7428
+ "supersedes": [],
7429
+ "symbol": "runEnvironmentOperation"
7430
+ },
7431
+ {
7432
+ "aliases": [],
7433
+ "constraints": [
7434
+ "reads only the first bytes; a file it cannot name returns undefined and must be refused"
7435
+ ],
7436
+ "example": "const kind = sniff(new Uint8Array(await file.arrayBuffer()))?.kind;",
7437
+ "importPath": "@threenative/terrain/editor",
7438
+ "kind": "function",
7439
+ "overrides": ["the caller decides what to do with an unknown file"],
7440
+ "package": "@threenative/terrain",
7441
+ "requires": ["npm i -D @threenative/terrain"],
7442
+ "signature": "export function sniff( bytes: Uint8Array, ): { … }",
7443
+ "situations": [
7444
+ "decide whether a dropped or downloaded file is a model, surface image or environment image"
7445
+ ],
7446
+ "summary": "The kind and format a file's own bytes declare, whatever its name says. @summary Identify a GLB, PNG, JPEG, WebP, HDR or EXR file by its header",
7447
+ "supersedes": [],
7448
+ "symbol": "sniff"
7449
+ },
7450
+ {
7451
+ "aliases": [],
7452
+ "constraints": [
7453
+ "throws by name for an input that is not <surface>.<channel> with a known channel"
7454
+ ],
7455
+ "example": "const space = surfaceSpace(\"bark.normal\");",
7456
+ "importPath": "@threenative/terrain/editor",
7457
+ "kind": "function",
7458
+ "overrides": ["the project owns which surface inputs exist"],
7459
+ "package": "@threenative/terrain",
7460
+ "requires": ["npm i -D @threenative/terrain"],
7461
+ "signature": "export function surfaceSpace(input: string): \"srgb\" | \"linear\" { … }",
7462
+ "situations": ["decide how an imported image bound to a named surface input must be sampled"],
7463
+ "summary": "The colour space an input's pixels are read in, from the channel its name ends with. @summary Resolve a surface input name to sRGB or linear",
7464
+ "supersedes": [],
7465
+ "symbol": "surfaceSpace"
7466
+ },
7467
+ {
7468
+ "aliases": [],
7469
+ "constraints": [
7470
+ "optional tooling; only subscribe/mount touches DOM; stale revisions fail explicitly"
7471
+ ],
7472
+ "example": "const controller = new TerrainEditorController(editorUrl); const snapshot = await controller.snapshot();",
7473
+ "importPath": "@threenative/terrain/editor",
7474
+ "kind": "class",
7475
+ "overrides": ["editorUrl is the activation-returned project URL"],
7476
+ "package": "@threenative/terrain",
7477
+ "requires": ["npm i -D @threenative/terrain"],
7478
+ "signature": "export class TerrainEditorController { … }",
7479
+ "situations": ["inspect and atomically edit the terrain editor from an agent"],
7480
+ "summary": "HTTP controller for the project-local terrain editor.",
7481
+ "supersedes": [],
7482
+ "symbol": "TerrainEditorController"
7483
+ },
7484
+ {
7485
+ "aliases": [],
7486
+ "constraints": [
7487
+ "authoring metadata only; ids, content-hashed paths, bounds and unit adjustments are checked, files are not read"
7488
+ ],
7489
+ "example": "const asset = validateAsset({ id: \"oak\", kind: \"model\", name: \"oak.glb\", path: \"models/0123456789ab-oak.glb\", sha256: \"0123456789ab\".padEnd(64, \"0\"), bytes: 2180, status: \"ready\" });",
7490
+ "importPath": "@threenative/terrain/editor",
7491
+ "kind": "function",
7492
+ "overrides": ["the project owns its asset directory and which entries it keeps"],
7493
+ "package": "@threenative/terrain",
7494
+ "requires": ["npm i -D @threenative/terrain"],
7495
+ "signature": "export function validateAsset(input: unknown): IProjectAsset { … }",
7496
+ "situations": [
7497
+ "check a model, image or environment asset entry before saving it in the authoring document"
7498
+ ],
7499
+ "summary": "Validate one saved asset registration exactly as a document commit stores it. @summary Validate a registered terrain-editor asset entry",
7500
+ "supersedes": [],
7501
+ "symbol": "validateAsset"
7502
+ },
7503
+ {
7504
+ "aliases": [],
7505
+ "constraints": ["at most 64 entries; unique ids; each entry as validateAsset"],
7506
+ "example": "const assets = validateAssets(document.assets ?? []);",
7507
+ "importPath": "@threenative/terrain/editor",
7508
+ "kind": "function",
7509
+ "overrides": ["the project owns its asset directory and which entries it keeps"],
7510
+ "package": "@threenative/terrain",
7511
+ "requires": ["npm i -D @threenative/terrain"],
7512
+ "signature": "export function validateAssets(input: unknown): IProjectAsset[] { … }",
7513
+ "situations": [
7514
+ "check every registered model, image and environment entry together, with unique ids"
7515
+ ],
7516
+ "summary": "Validate the whole asset list of an authoring document. @summary Validate the registered terrain-editor assets",
7517
+ "supersedes": [],
7518
+ "symbol": "validateAssets"
7519
+ },
7520
+ {
7521
+ "aliases": [],
7522
+ "constraints": [
7523
+ "authoring metadata only; finite noncoincident poses, usable up, valid projection, ordered planes"
7524
+ ],
7525
+ "example": "const camera = validateCamera({ id: \"survey\", name: \"Survey\", position: [40, 60, 40], target: [0, 12, 0], up: [0, 1, 0], projection: \"perspective\", fov: 50, near: 0.5, far: 900 });",
7526
+ "importPath": "@threenative/terrain/editor",
7527
+ "kind": "function",
7528
+ "overrides": ["the caller owns the document revision and the live viewport aspect"],
7529
+ "package": "@threenative/terrain",
7530
+ "requires": ["npm i -D @threenative/terrain"],
7531
+ "signature": "export function validateCamera( input: unknown, existing: readonly ISavedCamera[] = [], ): ISavedCamera { … }",
7532
+ "situations": [
7533
+ "create or update a named terrain-editor camera in the shared authoring document"
7534
+ ],
7535
+ "summary": "Normalise and validate one saved camera, exactly as a document commit would store it. @summary Validate an editor observation camera bookmark",
7536
+ "supersedes": [],
7537
+ "symbol": "validateCamera"
7538
+ },
7539
+ {
7540
+ "aliases": [],
7541
+ "constraints": ["authoring metadata only; the same validation the camera operations apply"],
7542
+ "example": "const cameras = validateCameras(JSON.parse(saved).cameras ?? []);",
7543
+ "importPath": "@threenative/terrain/editor",
7544
+ "kind": "function",
7545
+ "overrides": [
7546
+ "the document owns how many cameras it keeps; the list bound is the editor's own"
7547
+ ],
7548
+ "package": "@threenative/terrain",
7549
+ "requires": ["npm i -D @threenative/terrain"],
7550
+ "signature": "export function validateCameras(input: unknown): ISavedCamera[] { … }",
7551
+ "situations": ["reject a disk document whose saved cameras are malformed or duplicated"],
7552
+ "summary": "Validate a document's saved camera list, keeping ids unique across it. @summary Validate the saved editor camera list of an authoring document",
7553
+ "supersedes": [],
7554
+ "symbol": "validateCameras"
7555
+ },
7556
+ {
7557
+ "aliases": [],
7558
+ "constraints": [
7559
+ "authoring metadata only; unknown fields and unsupported fog modes are refused by name"
7560
+ ],
7561
+ "example": "const environment = validateEnvironment({ sun: { elevation: 25, intensity: 3 } });",
7562
+ "importPath": "@threenative/terrain/editor",
7563
+ "kind": "function",
7564
+ "overrides": [
7565
+ "the project's render source defines what each value does; absent fields keep its own"
7566
+ ],
7567
+ "package": "@threenative/terrain",
7568
+ "requires": ["npm i -D @threenative/terrain"],
7569
+ "signature": "export function validateEnvironment(input: unknown): IEnvironment { … }",
7570
+ "situations": [
7571
+ "save sun, sky, haze, exposure or ocean overrides in the shared authoring document"
7572
+ ],
7573
+ "summary": "Validate a complete overrides object exactly as a document commit stores it. @summary Validate preview environment overrides",
7574
+ "supersedes": [],
7575
+ "symbol": "validateEnvironment"
7576
+ },
7577
+ {
7578
+ "aliases": [],
7579
+ "constraints": [
7580
+ "authoring metadata only; rejects unknown fields, malformed points and unknown scale"
7581
+ ],
7582
+ "example": "const reference = validateSpatialReference(JSON.parse(saved));",
7583
+ "importPath": "@threenative/terrain/editor",
7584
+ "kind": "function",
7585
+ "overrides": [
7586
+ "a project owns the image file; only its hash and provenance travel in the document"
7587
+ ],
7588
+ "package": "@threenative/terrain",
7589
+ "requires": ["npm i -D @threenative/terrain"],
7590
+ "signature": "export function validateSpatialReference(input: unknown): ISavedSpatialReference { … }",
7591
+ "situations": [
7592
+ "accept a bounded local reference image registration into the shared document"
7593
+ ],
7594
+ "summary": "Normalise and validate one saved reference, exactly as a document commit would store it.",
7595
+ "supersedes": [],
7596
+ "symbol": "validateSpatialReference"
7597
+ },
7598
+ {
7599
+ "aliases": [],
7600
+ "constraints": [
7601
+ "authoring metadata only; each input is <surface>.<channel>; every asset must be a registered image"
7602
+ ],
7603
+ "example": "const surfaces = validateSurfaces({ \"bark.normal\": { asset: \"my-normal\" } }, document.assets ?? []);",
7604
+ "importPath": "@threenative/terrain/editor",
7605
+ "kind": "function",
7606
+ "overrides": [
7607
+ "the project's render source defines which surface inputs exist and what they draw"
7608
+ ],
7609
+ "package": "@threenative/terrain",
7610
+ "requires": ["npm i -D @threenative/terrain"],
7611
+ "signature": "export function validateSurfaces( input: unknown, assets: readonly IProjectAsset[], ): ISurfaceMappings { … }",
7612
+ "situations": [
7613
+ "save which imported PBR image replaces which named surface input of the project's render source"
7614
+ ],
7615
+ "summary": "Validate surface mappings against the registered images they name. @summary Validate terrain-editor surface image mappings",
7616
+ "supersedes": [],
7617
+ "symbol": "validateSurfaces"
7618
+ },
7619
+ {
7620
+ "aliases": [],
7621
+ "constraints": [
7622
+ "dev tooling only; serve a project-owned /terrain-editor/index.html; no runtime import"
7623
+ ],
7624
+ "example": "const editor = terrainEditor({ documentPath: resolve(\"terrain/world.json\") });",
7625
+ "importPath": "@threenative/terrain/editor/server",
7626
+ "kind": "function",
7627
+ "overrides": ["documentPath and optional configured viewerUrl belong to the project"],
7628
+ "package": "@threenative/terrain",
7629
+ "requires": ["npm i -D @threenative/terrain vite"],
7630
+ "signature": "export function terrainEditor(options: { … }",
7631
+ "situations": ["share terrain recipe edits between an agent and the live terrain editor"],
7632
+ "summary": "Mount the optional terrain document API on an existing loopback Vite server.",
7633
+ "supersedes": [],
7634
+ "symbol": "terrainEditor"
7635
+ },
7636
+ {
7637
+ "aliases": [],
7638
+ "constraints": [
7639
+ "Node authoring only; documentPath is a configured absolute regular file; input is bounded to 64 MiB"
7640
+ ],
7641
+ "example": "const document = new TerrainEditorDocument(\"/project/terrain/world.json\"); const snapshot = document.snapshot();",
7642
+ "importPath": "@threenative/terrain/editor/server",
7643
+ "kind": "class",
7644
+ "overrides": ["the project chooses its document path; revisions come from validated content"],
7645
+ "package": "@threenative/terrain",
7646
+ "requires": ["npm i -D @threenative/terrain"],
7647
+ "signature": "export class TerrainEditorDocument { … }",
7648
+ "situations": ["validate atomic revision-based project-local terrain document edits"],
7649
+ "summary": "Project-local terrain document authority; no renderer or game dependency.",
7650
+ "supersedes": [],
7651
+ "symbol": "TerrainEditorDocument"
7652
+ },
7653
+ {
7654
+ "aliases": [],
7655
+ "constraints": [
7656
+ "browser authoring (FileReader/canvas); caller supplies all appearance and coherent baked water; root and /three remain headless"
7657
+ ],
7658
+ "example": "const output = await exportWorldGLB({ revision, snapshotTime: 0, state, terrain, assets, transforms });",
7659
+ "importPath": "@threenative/terrain/export",
7660
+ "kind": "function",
7661
+ "overrides": [
7662
+ "actual static models, final matrices and baked PBR maps are supplied by the game"
7663
+ ],
7664
+ "package": "@threenative/terrain",
7665
+ "requires": ["npm i -D @threenative/terrain"],
7666
+ "signature": "export async function exportWorldGLB(input: IWorldGLBInput): Promise<IWorldGLBExport> { … }",
7667
+ "situations": [
7668
+ "export terrain, resolved models and final manual placement transforms as a portable GLB",
7669
+ "export the whole terrain world as one glb for another three.js project"
7670
+ ],
7671
+ "summary": "Export a committed evaluated world using ordinary glTF 2.0 nodes and embedded PBR images.",
7672
+ "supersedes": [],
7673
+ "symbol": "exportWorldGLB"
7674
+ },
7675
+ {
7676
+ "aliases": [],
7677
+ "constraints": ["creates only geometry; the caller owns its material, scene and disposal"],
7678
+ "example": "const geometry = toGeometry(bakeMesh(new Terrain({ resolution: 17 }).evaluate()));",
7679
+ "importPath": "@threenative/terrain/three",
7680
+ "kind": "function",
7681
+ "overrides": ["every surface choice remains in game source"],
7682
+ "package": "@threenative/terrain",
7683
+ "requires": ["npm i @threenative/terrain"],
7684
+ "signature": "export function toGeometry(mesh: IBakedMesh): BufferGeometry { … }",
7685
+ "situations": ["put an authored terrain mesh in a game-owned Three.js scene"],
7686
+ "summary": "Converts baked arrays to ordinary geometry using the consumer's installed Three.js.",
7687
+ "supersedes": [],
7688
+ "symbol": "toGeometry"
7689
+ },
6513
7690
  {
6514
7691
  "aliases": [],
6515
7692
  "constraints": [
@@ -6643,6 +7820,7 @@
6643
7820
  "kind": "function",
6644
7821
  "overrides": [],
6645
7822
  "package": "@threenative/ui",
7823
+ "requires": ["npm i @threenative/ui"],
6646
7824
  "signature": "export function DebugOverlay() { … }",
6647
7825
  "situations": [
6648
7826
  "display runtime and playtest diagnostics in a React HUD",
@@ -6662,6 +7840,7 @@
6662
7840
  "kind": "function",
6663
7841
  "overrides": [],
6664
7842
  "package": "@threenative/ui",
7843
+ "requires": ["npm i @threenative/ui"],
6665
7844
  "signature": "export function GameCanvas<TState extends Record<string, unknown>, TPhysics>( { … }",
6666
7845
  "situations": [
6667
7846
  "add a game viewport to a React application",
@@ -6679,6 +7858,7 @@
6679
7858
  "kind": "function",
6680
7859
  "overrides": [],
6681
7860
  "package": "@threenative/ui",
7861
+ "requires": ["npm i @threenative/ui"],
6682
7862
  "signature": "export function UiLayer( { … }",
6683
7863
  "situations": [
6684
7864
  "write one HUD that looks the same on the web build and on a phone",
@@ -6696,6 +7876,7 @@
6696
7876
  "kind": "function",
6697
7877
  "overrides": [],
6698
7878
  "package": "@threenative/ui",
7879
+ "requires": ["npm i @threenative/ui"],
6699
7880
  "signature": "export function useGameState<TState extends Record<string, unknown>, TPhysics, TSelected>( game: IGame<TState, TPhysics>, selector: GameSelector<TState, TSelected>, ): TSelected;",
6700
7881
  "situations": [
6701
7882
  "bind a HUD component to game state",
@@ -6713,6 +7894,7 @@
6713
7894
  "kind": "function",
6714
7895
  "overrides": [],
6715
7896
  "package": "@threenative/ui",
7897
+ "requires": ["npm i @threenative/ui"],
6716
7898
  "signature": "export function useUiIntent(): (intent: string, payload?: unknown) => void { … }",
6717
7899
  "situations": [
6718
7900
  "wire a Restart button in a HUD to the running game",
@@ -6730,6 +7912,7 @@
6730
7912
  "kind": "function",
6731
7913
  "overrides": [],
6732
7914
  "package": "@threenative/ui",
7915
+ "requires": ["npm i @threenative/ui"],
6733
7916
  "signature": "export function useUiState<TState extends object>(): TState | undefined;",
6734
7917
  "situations": [
6735
7918
  "bind a HUD to game state on web and native alike",