@threenative/core 0.3.11 → 0.3.13

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 (236) hide show
  1. package/README.md +1 -1
  2. package/capabilities.json +1988 -204
  3. package/dist/{assets-YUbXa3-Y.d.ts → assets-CfMKnOsK.d.ts} +78 -1
  4. package/dist/camera-shake-CZKOfGn4.d.ts +46 -0
  5. package/dist/{canvas-layer-vCtanIeB.d.ts → canvas-layer-G7ttVy7y.d.ts} +1 -1
  6. package/dist/chunk-4SRAQFTU.js +133 -0
  7. package/dist/chunk-CFGTPFUH.js +231 -0
  8. package/dist/chunk-DIPIJICH.js +8916 -0
  9. package/dist/chunk-EEABDLUC.js +2237 -0
  10. package/dist/chunk-EFWZWLPY.js +1895 -0
  11. package/dist/chunk-GXY7B3JG.js +46 -0
  12. package/dist/chunk-GYUZJQ7U.js +280 -0
  13. package/dist/chunk-H4J6IAJE.js +504 -0
  14. package/dist/chunk-KIRUKTBQ.js +187 -0
  15. package/dist/chunk-QWJEMUUT.js +94 -0
  16. package/dist/chunk-SV4QVUTQ.js +31 -0
  17. package/dist/chunk-U4YHUKKL.js +615 -0
  18. package/dist/chunk-VP43GIWW.js +18 -0
  19. package/dist/chunk-XDTZ4QMO.js +160 -0
  20. package/dist/default-tone-mapping-GgKPTiBP.d.ts +4 -0
  21. package/dist/{game-DzMcitDO.d.ts → game-k8K3hZai.d.ts} +85 -9
  22. package/dist/hot.d.ts +5 -4
  23. package/dist/hot.js +5 -52
  24. package/dist/index.d.ts +633 -1351
  25. package/dist/index.js +12873 -23068
  26. package/dist/{model-lod-CTpZ6imz.d.ts → model-lod-DPTzeCcD.d.ts} +35 -3
  27. package/dist/playtest.d.ts +5 -4
  28. package/dist/playtest.js +25 -75
  29. package/dist/quality-BYqKGAwo.d.ts +868 -0
  30. package/dist/react-css.js +1 -215
  31. package/dist/react.d.ts +3 -2
  32. package/dist/render-environment.d.ts +170 -0
  33. package/dist/render-environment.js +352 -0
  34. package/dist/{renderer-rZm0hVqq.d.ts → renderer-BtOSseYf.d.ts} +42 -35
  35. package/dist/spells/index.d.ts +643 -0
  36. package/dist/spells/index.js +1558 -0
  37. package/dist/spells/ultra/index.d.ts +1600 -0
  38. package/dist/spells/ultra/index.js +6804 -0
  39. package/dist/terrain-jobs-worker.js +1 -123
  40. package/dist/two-sided-foliage-W523J3UM.js +1 -0
  41. package/dist/ui-layer.js +6 -384
  42. package/dist/worker.js +13 -43
  43. package/dist/world.d.ts +988 -268
  44. package/dist/world.js +17464 -18290
  45. package/mcp/animation-server.mjs +1 -1
  46. package/mcp/animation.mjs +2 -3
  47. package/mcp/engine-server.mjs +245 -52
  48. package/mcp/servers.mjs +10 -3
  49. package/mcp/terrain.mjs +8 -0
  50. package/package.json +19 -7
  51. package/patches/three@0.187.0-prd269-upgrade.patch +2102 -0
  52. package/patches/three@0.187.0.patch +2004 -407
  53. package/src/animation-batch.ts +193 -0
  54. package/src/animation-layers.ts +7 -3
  55. package/src/animation.ts +209 -29
  56. package/src/asset-cache.ts +3 -3
  57. package/src/asset-memo.ts +202 -0
  58. package/src/assets.ts +437 -125
  59. package/src/auto-batch.ts +190 -44
  60. package/src/card-lod.ts +152 -0
  61. package/src/compressed-texture-preparation.ts +1008 -0
  62. package/src/compute-driven.ts +1 -1
  63. package/src/config.ts +8 -0
  64. package/src/debug.ts +103 -22
  65. package/src/dev-global.ts +54 -0
  66. package/src/engine-hooks.ts +37 -0
  67. package/src/frame-budget.ts +50 -23
  68. package/src/game-boot-phase.ts +269 -0
  69. package/src/game-dev-tools.ts +86 -0
  70. package/src/game-frame-loop.ts +958 -0
  71. package/src/game-renderer-metrics.ts +77 -0
  72. package/src/game-startup.ts +1076 -0
  73. package/src/game-ui.ts +84 -0
  74. package/src/game-validate.ts +70 -0
  75. package/src/game.ts +198 -2264
  76. package/src/gamepad-mappings.ts +269 -0
  77. package/src/generated/console-markers.ts +13 -0
  78. package/src/geometry-capture.ts +28 -4
  79. package/src/gpu-readings.ts +98 -0
  80. package/src/gpu-scene-bvh.ts +149 -36
  81. package/src/hot.ts +4 -7
  82. package/src/index.ts +141 -9
  83. package/src/input.ts +237 -25
  84. package/src/instanced-batch-lod.ts +3 -8
  85. package/src/interpolation.ts +171 -40
  86. package/src/launch-diagnostics.ts +22 -12
  87. package/src/look/ao-admission.ts +25 -0
  88. package/src/look/auto-exposure.ts +5 -16
  89. package/src/look/default-tone-mapping.ts +41 -5
  90. package/src/look/filmic-tone-mapping.ts +15 -13
  91. package/src/look/local-exposure.ts +2 -7
  92. package/src/look/look-diagnostics.ts +3 -3
  93. package/src/look/quad-pass.ts +21 -0
  94. package/src/look/quality.ts +14 -5
  95. package/src/look/unreal-bloom.ts +4 -13
  96. package/src/look/world-environment.ts +113 -103
  97. package/src/loop.ts +29 -0
  98. package/src/merge-parts.ts +20 -24
  99. package/src/model-lod.ts +139 -17
  100. package/src/particle-kinds.ts +515 -0
  101. package/src/particle-significance.ts +12 -0
  102. package/src/particles.ts +19 -10
  103. package/src/picking.ts +17 -3
  104. package/src/platform.ts +23 -4
  105. package/src/playtest.ts +27 -1
  106. package/src/profiling/FrameStages.ts +5 -6
  107. package/src/profiling/Spans.ts +3 -17
  108. package/src/profiling/debug-telemetry.ts +2 -6
  109. package/src/profiling/render-list-validate.ts +6 -15
  110. package/src/projection-apply.ts +4 -1
  111. package/src/projection-marker.ts +2 -1
  112. package/src/projection-plan.ts +9 -6
  113. package/src/quiet-markers.ts +3 -10
  114. package/src/render/cpu-bvh.ts +100 -0
  115. package/src/render/depth-pyramid.ts +6 -14
  116. package/src/render/environment/environmentContribution.ts +202 -0
  117. package/src/render/environment/environmentRadiance.ts +44 -0
  118. package/src/render/environment/environmentSampleCache.ts +56 -0
  119. package/src/render/environment/environmentSampling.ts +201 -0
  120. package/src/render/environment/environmentSnapshot.ts +71 -0
  121. package/src/render/environment/gate.ts +57 -0
  122. package/src/render/mesh-pool.ts +4 -20
  123. package/src/render/probe-trace.ts +872 -0
  124. package/src/render/probe-volume.ts +780 -34
  125. package/src/render/radiance-cache.ts +17 -0
  126. package/src/render/resolution-subrect.ts +2 -0
  127. package/src/render/rough-diffuse.ts +46 -12
  128. package/src/render/soft-shadow.ts +27 -12
  129. package/src/render/virtual-shadow-adaptive.ts +55 -0
  130. package/src/render/virtual-shadow-casters.ts +175 -0
  131. package/src/render/virtual-shadow-layers.ts +76 -0
  132. package/src/render/virtual-shadow-level.ts +224 -0
  133. package/src/render/virtual-shadow-markers.ts +193 -0
  134. package/src/render/virtual-shadow-options.ts +370 -0
  135. package/src/render/virtual-shadow-pages.ts +5 -0
  136. package/src/render/virtual-shadow-partial.ts +13 -0
  137. package/src/render/virtual-shadow.ts +231 -1008
  138. package/src/render/world-impostor-surface.ts +402 -40
  139. package/src/render/world-impostor.ts +5 -2
  140. package/src/render-camera-cull.ts +98 -3
  141. package/src/render-environment.ts +41 -0
  142. package/src/render-pass-budget.ts +34 -7
  143. package/src/renderProjection.ts +22 -0
  144. package/src/renderer-config.ts +36 -0
  145. package/src/renderer-facts.ts +37 -0
  146. package/src/renderer.ts +144 -65
  147. package/src/resolution-scaler.ts +3 -2
  148. package/src/scene-entry-inspectors.ts +61 -0
  149. package/src/snow-field.ts +2 -1
  150. package/src/spells/cast-pool.ts +361 -0
  151. package/src/spells/index.ts +177 -0
  152. package/src/spells/mechanisms.ts +295 -0
  153. package/src/spells/reaction-field.ts +415 -0
  154. package/src/spells/spell-lights.ts +139 -0
  155. package/src/spells/spell-world.ts +187 -0
  156. package/src/spells/spell.ts +397 -0
  157. package/src/spells/spells.ts +283 -0
  158. package/src/spells/ultra/engine/camera.ts +184 -0
  159. package/src/spells/ultra/engine/quality.ts +96 -0
  160. package/src/spells/ultra/index.ts +52 -0
  161. package/src/spells/ultra/main.ts +305 -0
  162. package/src/spells/ultra/scene/arenaMaterial.ts +325 -0
  163. package/src/spells/ultra/spells/cast.ts +233 -0
  164. package/src/spells/ultra/spells/fire.ts +1267 -0
  165. package/src/spells/ultra/vfx/FluidVolume.ts +816 -0
  166. package/src/spells/ultra/vfx/FluidVolume.tsl.ts +855 -0
  167. package/src/spells/ultra/vfx/FxTarget.ts +61 -0
  168. package/src/spells/ultra/vfx/GroundField.ts +1399 -0
  169. package/src/spells/ultra/vfx/Particles.ts +1475 -0
  170. package/src/spells/ultra/vfx/Ribbons.ts +645 -0
  171. package/src/spells/ultra/vfx/Shockwaves.ts +286 -0
  172. package/src/spells/ultra/vfx/Volumes.ts +489 -0
  173. package/src/spells/ultra/vfx/common.ts +1195 -0
  174. package/src/spells/ultra/vfx/noise.ts +441 -0
  175. package/src/startup-offscreen-bytes.ts +78 -0
  176. package/src/startup-readiness.ts +128 -34
  177. package/src/static-transform.ts +25 -19
  178. package/src/streamed-textures.ts +112 -0
  179. package/src/streaming.ts +68 -4
  180. package/src/texture-streaming.ts +331 -0
  181. package/src/version.ts +1 -1
  182. package/src/warmup.ts +56 -8
  183. package/src/water-surface.ts +9 -3
  184. package/src/worker.ts +12 -2
  185. package/src/world-bundle-safety.ts +446 -0
  186. package/src/world-cell-batches.ts +1178 -0
  187. package/src/world-cell-chunks.ts +1128 -0
  188. package/src/world-cell-data.ts +995 -0
  189. package/src/world-cell-impostors.ts +1461 -0
  190. package/src/world-cell-lod-bias.ts +151 -0
  191. package/src/world-cell-models.ts +1074 -0
  192. package/src/world-cell-options.ts +177 -0
  193. package/src/world-cell-placements.ts +798 -0
  194. package/src/world-cell-prewarm.ts +592 -0
  195. package/src/world-cell-readiness.ts +357 -0
  196. package/src/world-cell-records.ts +401 -0
  197. package/src/world-cell-render-bundles.ts +459 -0
  198. package/src/world-cell-render-gpu-dress.ts +710 -0
  199. package/src/world-cell-render-main-cull.ts +540 -0
  200. package/src/world-cell-render-shadow-claims.ts +198 -0
  201. package/src/world-cell-render-util.ts +259 -0
  202. package/src/world-cell-render.ts +1501 -0
  203. package/src/world-cell-residency.ts +754 -0
  204. package/src/world-cell-stale.ts +238 -0
  205. package/src/world-cells.ts +1335 -10418
  206. package/src/world-chunk-shadow.ts +308 -0
  207. package/src/world-collar.ts +315 -0
  208. package/src/world-gpu-flags.ts +131 -0
  209. package/src/world-gpu-readback.ts +881 -0
  210. package/src/world-gpu-reference.ts +524 -0
  211. package/src/world-gpu-scene.ts +256 -2286
  212. package/src/world-gpu-shadow.ts +203 -0
  213. package/src/world-gpu-types.ts +409 -0
  214. package/src/world-gpu-validation.ts +518 -0
  215. package/src/world-heightfield.ts +802 -0
  216. package/src/world-load-limiter.ts +111 -0
  217. package/src/world-model-sections.ts +80 -0
  218. package/src/world-noise.ts +241 -0
  219. package/src/world-package.ts +42 -0
  220. package/src/world-region.ts +1 -1
  221. package/src/world-river-ribbon.ts +282 -0
  222. package/src/world-root-frame.ts +39 -0
  223. package/src/world-shore-field.ts +91 -0
  224. package/src/world-static-pose.ts +163 -0
  225. package/src/world-surface-sampler.ts +48 -0
  226. package/src/world-terrain-splat.ts +361 -153
  227. package/src/world-tile-budget.ts +249 -0
  228. package/src/world-tile-geometry.ts +469 -0
  229. package/src/world-tile-lod.ts +408 -0
  230. package/src/world-tile-observation.ts +566 -0
  231. package/src/world-tile-stitch.ts +166 -0
  232. package/src/world-tiles.ts +247 -1755
  233. package/src/world-validate.ts +6 -14
  234. package/src/world-warm.ts +51 -0
  235. package/src/world-water-bodies.ts +359 -0
  236. package/src/world.ts +48 -741
package/capabilities.json CHANGED
@@ -84,6 +84,23 @@
84
84
  "supersedes": [],
85
85
  "symbol": "compileAssets"
86
86
  },
87
+ {
88
+ "aliases": [],
89
+ "constraints": [],
90
+ "example": "await cookTerrainWorld({ state, species, out: \"assets/world\" });",
91
+ "importPath": "@threenative/assets",
92
+ "kind": "function",
93
+ "overrides": [],
94
+ "package": "@threenative/assets",
95
+ "signature": "export function cookTerrainWorld( options: IPreparedTerrainWorldOptions, ): Promise< { … }",
96
+ "situations": [
97
+ "bake a terrain world headlessly into a GLB with instanced trees and rocks",
98
+ "generate a forest world for my game"
99
+ ],
100
+ "summary": "Bake evaluated terrain and static species into an instanced GLB and streaming world package.",
101
+ "supersedes": [],
102
+ "symbol": "cookTerrainWorld"
103
+ },
87
104
  {
88
105
  "aliases": [],
89
106
  "constraints": [
@@ -254,17 +271,27 @@
254
271
  {
255
272
  "aliases": [],
256
273
  "constraints": [
257
- "the pass self-verifies reachable geometry, animation, bounds, and embedded texture bindings before returning output"
274
+ "the pass self-verifies reachable geometry, animation, bounds, and embedded texture bindings before returning output",
275
+ "each colour texture climbs a codec ladder (ETC1S, then UASTC with RDO, then plain UASTC) and keeps the smallest rung that meets the quality floor (SSIM 0.95, ΔE00 3); a data slot such as a normal or metallic-roughness map takes UASTC only, as ETC1S is forbidden there (`TN_ASSETS_TEXTURE_SLOT_CODEC`); a result is kept only when it is smaller than the source, else the source stays and the report says `not-smaller`",
276
+ "a PNG or JPEG source can always be kept; a WebP source can be kept only on a web target, whose runtimes all decode WebP, so on desktop and mobile it always becomes KTX2"
258
277
  ],
259
278
  "example": "const pass = modelPass({ simplify: { ratio: 0.5 } });",
260
279
  "importPath": "@threenative/assets",
261
280
  "kind": "function",
262
- "overrides": [],
281
+ "overrides": [
282
+ "`textures: { overrides: [{ slot: \"baseColorTexture\", codec: \"uastc\" }] }` forces one glTF slot's codec (`etc1s`, `uastc` or `none`); `textures: { floor }` moves the quality floor; `textures: \"none\"` keeps every embedded texture as authored"
283
+ ],
263
284
  "package": "@threenative/assets",
264
285
  "signature": "export function modelPass(options: IModelPassOptions = { … }",
265
286
  "situations": [
266
287
  "reduce a model's download and GPU footprint",
267
- "optimize a GLB before shipping it with a game"
288
+ "optimize a GLB before shipping it with a game",
289
+ "texture bytes too big after the model cook",
290
+ "a KTX2 model texture came out larger than its WebP or JPEG source",
291
+ "choose ETC1S or UASTC for a model's embedded textures",
292
+ "model texture codec ladder",
293
+ "keep smaller source texture",
294
+ "TN_ASSETS_COMPRESSION_SKIPPED"
268
295
  ],
269
296
  "summary": "Optimizes self-contained GLB models through the configured geometry and embedded-texture passes.",
270
297
  "supersedes": [],
@@ -431,6 +458,22 @@
431
458
  "supersedes": [],
432
459
  "symbol": "texturePass"
433
460
  },
461
+ {
462
+ "aliases": [],
463
+ "constraints": [
464
+ "mutates the supplied document; rejects unsupported MASK topology and invalid ratios"
465
+ ],
466
+ "example": "thinFoliageCards(document, 0.14);",
467
+ "importPath": "@threenative/assets",
468
+ "kind": "function",
469
+ "overrides": [],
470
+ "package": "@threenative/assets",
471
+ "signature": "export function thinFoliageCards(document: Document, keepRatio: number): number { … }",
472
+ "situations": ["prepare a far foliage mesh by thinning whole cards instead of triangles"],
473
+ "summary": "Build a standalone card-thinned foliage mesh, preserving opaque parts and vertex attributes.",
474
+ "supersedes": [],
475
+ "symbol": "thinFoliageCards"
476
+ },
434
477
  {
435
478
  "aliases": [],
436
479
  "constraints": [
@@ -569,7 +612,7 @@
569
612
  "add hundreds of built objects to the scene without one multi-second frame",
570
613
  "stream a detail tier in behind a loading curtain without the page looking hung"
571
614
  ],
572
- "summary": "Attach hundreds of built objects to the scene in slices, presenting a frame between each.",
615
+ "summary": "Attach hundreds of built objects to the scene in slices with an 8 ms default budget, presenting a frame between each.",
573
616
  "supersedes": [],
574
617
  "symbol": "addInSlices"
575
618
  },
@@ -1291,13 +1334,24 @@
1291
1334
  "constraints": [
1292
1335
  "reuse the loader handed to scenes as `ctx.assets` instead of building parallel caches",
1293
1336
  "await everything the spawn camera sees before the reveal; `ctx.assets.prefetch` and the background fill are for content out of view, or the player spawns into a half-built world",
1294
- "web only: a native host reads installed files, so `ctx.assets.cache` reports `enabled: false` with the reason and `prefetch` resolves at once"
1337
+ "a whole-file load requested after the reveal that the game had not `prefetch`ed logs one `TN_ASSET_LATE` line with its bytes, so a pop-in is countable from a playtest",
1338
+ "web only: a native host reads installed files, so `ctx.assets.cache` reports `enabled: false` with the reason and `prefetch` resolves at once",
1339
+ "streaming is engine-owned and on by default: a cooked LOD-chained model loads its `.coarse.<digest>.glb` companion first, then the full file at \"soon\" priority, and the full geometry replaces the coarse in place (clones and the projection mirror included); a failed coarse load falls back to the whole file and logs `TN_ASSETS_STREAM_FAILED`",
1340
+ "texture streaming rides on the coarse parse: each shared `.ktx2` of that model is read by `Range` as its resident mips (the header and the tail), and the whole files replace them when the full model lands; a host without `Range` sends the whole file and keeps it whole. `TN_STREAMING_POOL` reports `files`, `residentBytes`, `fullBytes`, `deferredBytes` and `upgraded` once, two seconds after the last change",
1341
+ "the whole texture keeps what the game set on the resident one (`anisotropy`, wrap, filters, offset, repeat, `userData`), so the swap changes the mips and nothing else",
1342
+ "every web build cooks meshopt geometry and KTX2 textures for both engines (`webRuntimeDecoders` in create-threenative answers `{ ktx2: true, meshopt: true }`); the owned engine's glTF loader decodes both itself, with no JS decoder",
1343
+ "the owned engine transcodes a KTX2 image to BC7 on a device with `texture-compression-bc`, else ETC2, else RGBA8 with an engine mip chain, and prints `TN_TEXTURE_TRANSCODE_TARGET <target>` once; a block format needs a width and height that are multiples of 4, so any other size stays RGBA8 and the same line names it",
1344
+ "a three `CompressedTexture` (format plus `mipmaps`) uploads one GPU write per level; a block format the device lacks throws `TN_NATIVE_TEXTURE_UNSUPPORTED` by name instead of drawing garbage",
1345
+ "levels are coarse-first: a level whose `mipmaps[i].data` is null is not resident and the texture samples its finest resident level; set `mipmaps[i].data` and `needsUpdate = true` to write that one finer level in place, without re-creating the texture or rewriting the other levels"
1295
1346
  ],
1296
1347
  "example": "const assets = createAssetLoader({ basePath: \"/assets\" });\nconst rock = await assets.texture(\"rock.png\");",
1297
1348
  "importPath": "@threenative/core",
1298
1349
  "kind": "function",
1299
1350
  "overrides": [
1300
- "`assets.cache: false` turns the disk cache off and `assets.backgroundFill: false` turns the post-reveal fill off; both are reported on `ctx.assets.cache`"
1351
+ "`assets.cache: false` turns the disk cache off and `assets.backgroundFill: false` turns the post-reveal fill off; both are reported on `ctx.assets.cache`",
1352
+ "`ctx.assets.model(path, { whole: true })` resolves only once the full file has replaced the coarse companion, for a collider or navmesh that copies vertices once",
1353
+ "`assets.streamMeshes: false` loads every model whole (reported once as `TN_ASSETS_STREAM_MESHES_OFF`); `assets.streamTextures: false` loads every model texture whole (`TN_ASSETS_STREAM_TEXTURES_OFF`)",
1354
+ "`engine: \"threejs\"` runs three's own `KTX2Loader` and `MeshoptDecoder` in JS instead of the owned engine's decoders"
1301
1355
  ],
1302
1356
  "package": "@threenative/core",
1303
1357
  "signature": "export function createAssetLoader(options: IAssetLoaderOptions = { … }",
@@ -1307,7 +1361,27 @@
1307
1361
  "download the next scene before the player gets there",
1308
1362
  "free the disk cache from a settings menu",
1309
1363
  "prefetch assets into the Cache Storage disk cache of a large web game",
1310
- "load assets from a nonstandard base path or a compiled asset manifest"
1364
+ "load assets from a nonstandard base path or a compiled asset manifest",
1365
+ "stream a large game: boot on the spawn bytes and prefetch the rest",
1366
+ "make the first scene play before the whole game finishes downloading",
1367
+ "draw a heavy model's coarsest level first and its full detail when the file lands",
1368
+ "draw a model's textures at their resident mips first and the whole files later",
1369
+ "coarse first model streaming",
1370
+ "streamMeshes and streamTextures: stream the meshes and textures of a model",
1371
+ "mip streaming textures",
1372
+ "TN_STREAMING_POOL",
1373
+ "TN_ASSET_LATE",
1374
+ "an asset pops in after the reveal and the game needs to count it",
1375
+ "a model texture looks blurry or low resolution right after load, then sharpens",
1376
+ "build a collider or navmesh from a streamed model only once its full file landed",
1377
+ "compressed texture upload on the owned engine (KTX2 to BC7 or ETC2 on the GPU)",
1378
+ "load a model with KHR_texture_basisu or EXT_meshopt_compression on the owned engine",
1379
+ "stream a finer mip level into a CompressedTexture that already draws",
1380
+ "KTX2Loader on the owned engine",
1381
+ "CompressedTexture upload",
1382
+ "TN_TEXTURE_TRANSCODE_TARGET",
1383
+ "TN_NATIVE_TEXTURE_UNSUPPORTED",
1384
+ "webRuntimeDecoders meshopt ktx2"
1311
1385
  ],
1312
1386
  "summary": "Create the portable asset loader a scene also receives as `ctx.assets`.",
1313
1387
  "supersedes": [],
@@ -1405,7 +1479,9 @@
1405
1479
  "overrides": [],
1406
1480
  "package": "@threenative/core",
1407
1481
  "signature": "export function debugFlag(name: string): boolean { … }",
1408
- "situations": ["read a debug toggle from the URL or an environment variable"],
1482
+ "situations": [
1483
+ "read a debug toggle from the URL, an environment variable or a harness global"
1484
+ ],
1409
1485
  "summary": "Read a debug switch from the URL, or from `TN_DEBUG_*` in the environment on a native launch.",
1410
1486
  "supersedes": [],
1411
1487
  "symbol": "debugFlag"
@@ -1480,6 +1556,22 @@
1480
1556
  "supersedes": [],
1481
1557
  "symbol": "describeSceneWarning"
1482
1558
  },
1559
+ {
1560
+ "aliases": [],
1561
+ "constraints": [
1562
+ "every dev surface publishes under this key; the worker's typed mirror tuple names it too"
1563
+ ],
1564
+ "example": "import { DEV_GLOBAL_KEY, devGlobal } from \"@threenative/core\";\nconst tools = devGlobal(globalThis);",
1565
+ "importPath": "@threenative/core",
1566
+ "kind": "function",
1567
+ "overrides": [],
1568
+ "package": "@threenative/core",
1569
+ "signature": "export function devGlobal(scope: unknown): DevGlobal | undefined { … }",
1570
+ "situations": ["read or extend the `__THREENATIVE__` object a dev launch publishes"],
1571
+ "summary": "The one name every dev surface publishes under, and the reader/writer for it.",
1572
+ "supersedes": [],
1573
+ "symbol": "devGlobal"
1574
+ },
1483
1575
  {
1484
1576
  "aliases": [],
1485
1577
  "constraints": ["pass a non-zero direction; coefficients and radii come from the game"],
@@ -1664,6 +1756,23 @@
1664
1756
  "supersedes": [],
1665
1757
  "symbol": "exposureFromEv100"
1666
1758
  },
1759
+ {
1760
+ "aliases": [],
1761
+ "constraints": ["reads the response once; call `.json()` or `.arrayBuffer()` on the result"],
1762
+ "example": "const heights = new Float32Array(await (await fetchAsset(ctx.assets, \"world/forest.bin\")).arrayBuffer());",
1763
+ "importPath": "@threenative/core",
1764
+ "kind": "function",
1765
+ "overrides": [],
1766
+ "package": "@threenative/core",
1767
+ "signature": "export async function fetchAsset( assets: Pick<IAssetLoader, \"resolve\">, path: string, ): Promise<Response> { … }",
1768
+ "situations": [
1769
+ "load a baked JSON or binary file (a heightmap, a placement buffer, a data table) that the loader has no typed method for",
1770
+ "a data file loads in dev but 404s in the built game"
1771
+ ],
1772
+ "summary": "Fetch a data file the asset loader serves: each url `assets.resolve(path)` names, in order, until one answers ok. A built game serves the hashed output and a dev server the source path, so taking only the first url 404s on one of them. When none answers it throws `TN_ASSET_NOT_SERVED` naming every url tried and why, so a missing file is never a half-drawn world.",
1773
+ "supersedes": [],
1774
+ "symbol": "fetchAsset"
1775
+ },
1667
1776
  {
1668
1777
  "aliases": [],
1669
1778
  "constraints": [
@@ -1903,7 +2012,7 @@
1903
2012
  "a native desktop host with ray tracing hardware traces ray batches with `mystralRT.traceRayBatch`, which writes hit records into a typed array you own; read `mystralRT.capabilities().rayBatch` first, and keep the software BVH trace for the web and every other host",
1904
2013
  "when `mystralRT.capabilities().sharedTransport` is true, `mystralRT.traceRayBatchGpu({ tlas, rays, hits, rayCount })` traces between two GPUBuffers with no copy through CPU memory; `rays` needs the CopySrc usage and `hits` the CopyDst usage, and each call costs CPU time, so measure it against the software trace for your batch size"
1905
2014
  ],
1906
- "example": "if (isMobile()) showTouchControls();",
2015
+ "example": "if (isMobile()) showTouchControls();\nif (isConsole()) showPadPrompts(isPs4() ? \"dualshock\" : \"generic\");",
1907
2016
  "importPath": "@threenative/core",
1908
2017
  "kind": "function",
1909
2018
  "overrides": [],
@@ -1912,7 +2021,8 @@
1912
2021
  "situations": [
1913
2022
  "branch a portable game on web or native",
1914
2023
  "choose touch controls for a mobile device",
1915
- "can I raytrace on native"
2024
+ "can I raytrace on native",
2025
+ "show gamepad prompts and bind pad buttons on a games console such as the PS4"
1916
2026
  ],
1917
2027
  "summary": "Read the host platform without reaching for browser globals.",
1918
2028
  "supersedes": [],
@@ -2065,21 +2175,28 @@
2065
2175
  "symbol": "GroundSnap"
2066
2176
  },
2067
2177
  {
2068
- "aliases": [],
2178
+ "aliases": ["gamepad", "controller", "joypad", "xbox", "8bitdo", "steam deck"],
2069
2179
  "constraints": [
2070
2180
  "`buttons` is the gamepad and `mouseButtons` the mouse; `up`/`down`/`left`/`right` are the directions of `vector(name)`, not the keys that press it",
2071
- "scroll, pinch and pointer-relative sources are declared on the binding and read through `axis(name)`; a game adds no window listener of its own"
2181
+ "scroll, pinch and pointer-relative sources are declared on the binding and read through `axis(name)`; a game adds no window listener of its own",
2182
+ "gamepad buttons are W3C standard indices on every pad: 0 south (A/Cross), 1 east, 2 west, 3 north, 4/5 shoulders, 6/7 triggers, 8 select, 9 start, 10/11 stick clicks; axes 0..3 are the sticks",
2183
+ "both sticks carry a radial dead zone, `0.2` by default, reported per connected pad as `TN_GAMEPAD`; a pad the browser reports unmapped and the table does not know is ignored, never read with raw indices",
2184
+ "a pad claims the input when a button goes down or a stick travels past half tilt, and keeps it while idle so its releases read; a stick resting past the dead zone or jittering across it claims nothing, so an idle pad in the first slot cannot steal input"
2072
2185
  ],
2073
2186
  "example": "const game = defineGame({ input: { move: { up: [\"KeyW\"], down: [\"KeyS\"], left: [\"KeyA\"], right: [\"KeyD\"] } }, scenes: { Play } });\n// inside the scene, per frame: ctx.input.axis(\"move\") is 0 at rest and 1 at full tilt",
2074
2187
  "importPath": "@threenative/core",
2075
2188
  "kind": "class",
2076
- "overrides": [],
2189
+ "overrides": ["defineGame({ gamepadDeadZone: 0 }) publishes raw axes"],
2077
2190
  "package": "@threenative/core",
2078
2191
  "signature": "export class InputMap { … }",
2079
2192
  "situations": [
2080
2193
  "map WASD keys to a movement axis instead of reading the held key set in the update loop",
2081
2194
  "read a jump, a fire or a reload as one named action bound to key, gamepad button and mouse button together",
2082
- "read mouse look, wheel zoom or a two-finger pinch as an axis the frame loop already ticks"
2195
+ "read mouse look, wheel zoom or a two-finger pinch as an axis the frame loop already ticks",
2196
+ "support an Xbox pad, a generic XInput clone, an 8BitDo or a Steam Deck controller",
2197
+ "the character drifts while the controller stick is idle",
2198
+ "the controller does nothing in Firefox on Linux",
2199
+ "a second controller or a wheel steals the input from the pad the player holds"
2083
2200
  ],
2084
2201
  "summary": "The map a game reads input through: named actions, 2D vectors and scalar axes resolved from keyboard, gamepad, mouse, wheel, pinch and touch. `defineGame({ input })` builds one and hands it to the running game as `ctx.input`, so the usual route is a binding in the config and `ctx.input.axis(\"move\")` in the update. Construct one directly to drive a menu, a replay or a test outside a running game.",
2085
2202
  "supersedes": [],
@@ -2182,7 +2299,31 @@
2182
2299
  "a native desktop host with ray tracing hardware traces ray batches with `mystralRT.traceRayBatch`, which writes hit records into a typed array you own; read `mystralRT.capabilities().rayBatch` first, and keep the software BVH trace for the web and every other host",
2183
2300
  "when `mystralRT.capabilities().sharedTransport` is true, `mystralRT.traceRayBatchGpu({ tlas, rays, hits, rayCount })` traces between two GPUBuffers with no copy through CPU memory; `rays` needs the CopySrc usage and `hits` the CopyDst usage, and each call costs CPU time, so measure it against the software trace for your batch size"
2184
2301
  ],
2185
- "example": "if (isMobile()) showTouchControls();",
2302
+ "example": "if (isMobile()) showTouchControls();\nif (isConsole()) showPadPrompts(isPs4() ? \"dualshock\" : \"generic\");",
2303
+ "importPath": "@threenative/core",
2304
+ "kind": "function",
2305
+ "overrides": [],
2306
+ "package": "@threenative/core",
2307
+ "signature": "export function isConsole(): boolean { … }",
2308
+ "situations": [
2309
+ "branch a portable game on web or native",
2310
+ "choose touch controls for a mobile device",
2311
+ "can I raytrace on native",
2312
+ "show gamepad prompts and bind pad buttons on a games console such as the PS4"
2313
+ ],
2314
+ "summary": "Read the host platform without reaching for browser globals.",
2315
+ "supersedes": [],
2316
+ "symbol": "isConsole"
2317
+ },
2318
+ {
2319
+ "aliases": [],
2320
+ "constraints": [
2321
+ "only use the returned platform facts; native globals are host-owned",
2322
+ "image ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result",
2323
+ "a native desktop host with ray tracing hardware traces ray batches with `mystralRT.traceRayBatch`, which writes hit records into a typed array you own; read `mystralRT.capabilities().rayBatch` first, and keep the software BVH trace for the web and every other host",
2324
+ "when `mystralRT.capabilities().sharedTransport` is true, `mystralRT.traceRayBatchGpu({ tlas, rays, hits, rayCount })` traces between two GPUBuffers with no copy through CPU memory; `rays` needs the CopySrc usage and `hits` the CopyDst usage, and each call costs CPU time, so measure it against the software trace for your batch size"
2325
+ ],
2326
+ "example": "if (isMobile()) showTouchControls();\nif (isConsole()) showPadPrompts(isPs4() ? \"dualshock\" : \"generic\");",
2186
2327
  "importPath": "@threenative/core",
2187
2328
  "kind": "function",
2188
2329
  "overrides": [],
@@ -2191,7 +2332,8 @@
2191
2332
  "situations": [
2192
2333
  "branch a portable game on web or native",
2193
2334
  "choose touch controls for a mobile device",
2194
- "can I raytrace on native"
2335
+ "can I raytrace on native",
2336
+ "show gamepad prompts and bind pad buttons on a games console such as the PS4"
2195
2337
  ],
2196
2338
  "summary": "Read the host platform without reaching for browser globals.",
2197
2339
  "supersedes": [],
@@ -2205,7 +2347,7 @@
2205
2347
  "a native desktop host with ray tracing hardware traces ray batches with `mystralRT.traceRayBatch`, which writes hit records into a typed array you own; read `mystralRT.capabilities().rayBatch` first, and keep the software BVH trace for the web and every other host",
2206
2348
  "when `mystralRT.capabilities().sharedTransport` is true, `mystralRT.traceRayBatchGpu({ tlas, rays, hits, rayCount })` traces between two GPUBuffers with no copy through CPU memory; `rays` needs the CopySrc usage and `hits` the CopyDst usage, and each call costs CPU time, so measure it against the software trace for your batch size"
2207
2349
  ],
2208
- "example": "if (isMobile()) showTouchControls();",
2350
+ "example": "if (isMobile()) showTouchControls();\nif (isConsole()) showPadPrompts(isPs4() ? \"dualshock\" : \"generic\");",
2209
2351
  "importPath": "@threenative/core",
2210
2352
  "kind": "function",
2211
2353
  "overrides": [],
@@ -2214,12 +2356,37 @@
2214
2356
  "situations": [
2215
2357
  "branch a portable game on web or native",
2216
2358
  "choose touch controls for a mobile device",
2217
- "can I raytrace on native"
2359
+ "can I raytrace on native",
2360
+ "show gamepad prompts and bind pad buttons on a games console such as the PS4"
2218
2361
  ],
2219
2362
  "summary": "Read the host platform without reaching for browser globals.",
2220
2363
  "supersedes": [],
2221
2364
  "symbol": "isNative"
2222
2365
  },
2366
+ {
2367
+ "aliases": [],
2368
+ "constraints": [
2369
+ "only use the returned platform facts; native globals are host-owned",
2370
+ "image ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result",
2371
+ "a native desktop host with ray tracing hardware traces ray batches with `mystralRT.traceRayBatch`, which writes hit records into a typed array you own; read `mystralRT.capabilities().rayBatch` first, and keep the software BVH trace for the web and every other host",
2372
+ "when `mystralRT.capabilities().sharedTransport` is true, `mystralRT.traceRayBatchGpu({ tlas, rays, hits, rayCount })` traces between two GPUBuffers with no copy through CPU memory; `rays` needs the CopySrc usage and `hits` the CopyDst usage, and each call costs CPU time, so measure it against the software trace for your batch size"
2373
+ ],
2374
+ "example": "if (isMobile()) showTouchControls();\nif (isConsole()) showPadPrompts(isPs4() ? \"dualshock\" : \"generic\");",
2375
+ "importPath": "@threenative/core",
2376
+ "kind": "function",
2377
+ "overrides": [],
2378
+ "package": "@threenative/core",
2379
+ "signature": "export function isPs4(): boolean { … }",
2380
+ "situations": [
2381
+ "branch a portable game on web or native",
2382
+ "choose touch controls for a mobile device",
2383
+ "can I raytrace on native",
2384
+ "show gamepad prompts and bind pad buttons on a games console such as the PS4"
2385
+ ],
2386
+ "summary": "Read the host platform without reaching for browser globals.",
2387
+ "supersedes": [],
2388
+ "symbol": "isPs4"
2389
+ },
2223
2390
  {
2224
2391
  "aliases": [],
2225
2392
  "constraints": [
@@ -2241,6 +2408,27 @@
2241
2408
  "supersedes": [],
2242
2409
  "symbol": "isStatic"
2243
2410
  },
2411
+ {
2412
+ "aliases": [],
2413
+ "constraints": [
2414
+ "`CollisionShape3D.fromMesh` with \"trimesh\" or \"convexHull\" on a streamed geometry warns `TN_COLLIDER_COARSE` naming the mesh and the `{ whole: true }` override, and still builds"
2415
+ ],
2416
+ "example": "const coarse = isStreamedGeometry(mesh.geometry);",
2417
+ "importPath": "@threenative/core",
2418
+ "kind": "function",
2419
+ "overrides": [],
2420
+ "package": "@threenative/core",
2421
+ "signature": "export function isStreamedGeometry(geometry: BufferGeometry): boolean { … }",
2422
+ "situations": [
2423
+ "collider or navmesh built from a model is coarser than what is drawn",
2424
+ "wait for the full model before copying its vertices",
2425
+ "whole model before collision",
2426
+ "TN_COLLIDER_COARSE"
2427
+ ],
2428
+ "summary": "True while a geometry is the coarse companion a streamed model draws first (PRD-860), before its full file replaces it in place. A caller that copies vertices (a trimesh collider, a navmesh bake, a merge) waits with `ctx.assets.model(path, { whole: true })` instead of copying the coarse ones.",
2429
+ "supersedes": [],
2430
+ "symbol": "isStreamedGeometry"
2431
+ },
2244
2432
  {
2245
2433
  "aliases": [],
2246
2434
  "constraints": [
@@ -2249,7 +2437,7 @@
2249
2437
  "a native desktop host with ray tracing hardware traces ray batches with `mystralRT.traceRayBatch`, which writes hit records into a typed array you own; read `mystralRT.capabilities().rayBatch` first, and keep the software BVH trace for the web and every other host",
2250
2438
  "when `mystralRT.capabilities().sharedTransport` is true, `mystralRT.traceRayBatchGpu({ tlas, rays, hits, rayCount })` traces between two GPUBuffers with no copy through CPU memory; `rays` needs the CopySrc usage and `hits` the CopyDst usage, and each call costs CPU time, so measure it against the software trace for your batch size"
2251
2439
  ],
2252
- "example": "if (isMobile()) showTouchControls();",
2440
+ "example": "if (isMobile()) showTouchControls();\nif (isConsole()) showPadPrompts(isPs4() ? \"dualshock\" : \"generic\");",
2253
2441
  "importPath": "@threenative/core",
2254
2442
  "kind": "function",
2255
2443
  "overrides": [],
@@ -2258,7 +2446,8 @@
2258
2446
  "situations": [
2259
2447
  "branch a portable game on web or native",
2260
2448
  "choose touch controls for a mobile device",
2261
- "can I raytrace on native"
2449
+ "can I raytrace on native",
2450
+ "show gamepad prompts and bind pad buttons on a games console such as the PS4"
2262
2451
  ],
2263
2452
  "summary": "Read the host platform without reaching for browser globals.",
2264
2453
  "supersedes": [],
@@ -2272,7 +2461,7 @@
2272
2461
  "a native desktop host with ray tracing hardware traces ray batches with `mystralRT.traceRayBatch`, which writes hit records into a typed array you own; read `mystralRT.capabilities().rayBatch` first, and keep the software BVH trace for the web and every other host",
2273
2462
  "when `mystralRT.capabilities().sharedTransport` is true, `mystralRT.traceRayBatchGpu({ tlas, rays, hits, rayCount })` traces between two GPUBuffers with no copy through CPU memory; `rays` needs the CopySrc usage and `hits` the CopyDst usage, and each call costs CPU time, so measure it against the software trace for your batch size"
2274
2463
  ],
2275
- "example": "if (isMobile()) showTouchControls();",
2464
+ "example": "if (isMobile()) showTouchControls();\nif (isConsole()) showPadPrompts(isPs4() ? \"dualshock\" : \"generic\");",
2276
2465
  "importPath": "@threenative/core",
2277
2466
  "kind": "function",
2278
2467
  "overrides": [],
@@ -2281,7 +2470,8 @@
2281
2470
  "situations": [
2282
2471
  "branch a portable game on web or native",
2283
2472
  "choose touch controls for a mobile device",
2284
- "can I raytrace on native"
2473
+ "can I raytrace on native",
2474
+ "show gamepad prompts and bind pad buttons on a games console such as the PS4"
2285
2475
  ],
2286
2476
  "summary": "Read the host platform without reaching for browser globals.",
2287
2477
  "supersedes": [],
@@ -2343,6 +2533,22 @@
2343
2533
  "supersedes": [],
2344
2534
  "symbol": "loadAll"
2345
2535
  },
2536
+ {
2537
+ "aliases": [],
2538
+ "constraints": ["a geometry the loader built no chain for returns undefined"],
2539
+ "example": "const chain = lodChainOf(baseGeometryOf(mesh)); const far = chain?.levels.at(-1);",
2540
+ "importPath": "@threenative/core",
2541
+ "kind": "function",
2542
+ "overrides": [],
2543
+ "package": "@threenative/core",
2544
+ "signature": "export function lodChainOf(geometry: BufferGeometry): ILodChain | undefined { … }",
2545
+ "situations": [
2546
+ "draw a cooked reduced level of a model in an instanced batch or streamed world level"
2547
+ ],
2548
+ "summary": "The cooked automatic LOD chain (`TN_discrete_lod`) a loaded geometry carries, or `undefined`. Its levels share the base's vertex attributes and differ only in index, and `errors` are each level's world-unit error in the base's own space. A caller that draws one geometry many times (an instanced batch, a streamed world level) reads the reduced shapes here instead of re-cooking.",
2549
+ "supersedes": [],
2550
+ "symbol": "lodChainOf"
2551
+ },
2346
2552
  {
2347
2553
  "aliases": [],
2348
2554
  "constraints": [
@@ -2653,6 +2859,22 @@
2653
2859
  "supersedes": [],
2654
2860
  "symbol": "ProbeVolume"
2655
2861
  },
2862
+ {
2863
+ "aliases": [],
2864
+ "constraints": [
2865
+ "every dev surface publishes under this key; the worker's typed mirror tuple names it too"
2866
+ ],
2867
+ "example": "import { DEV_GLOBAL_KEY, devGlobal } from \"@threenative/core\";\nconst tools = devGlobal(globalThis);",
2868
+ "importPath": "@threenative/core",
2869
+ "kind": "function",
2870
+ "overrides": [],
2871
+ "package": "@threenative/core",
2872
+ "signature": "export function publishDevGlobal(name: string, value: unknown, scope: unknown): void { … }",
2873
+ "situations": ["read or extend the `__THREENATIVE__` object a dev launch publishes"],
2874
+ "summary": "The one name every dev surface publishes under, and the reader/writer for it.",
2875
+ "supersedes": [],
2876
+ "symbol": "publishDevGlobal"
2877
+ },
2656
2878
  {
2657
2879
  "aliases": [],
2658
2880
  "constraints": ["an unknown tier name throws with the names it expected"],
@@ -2672,6 +2894,30 @@
2672
2894
  "supersedes": [],
2673
2895
  "symbol": "qualityPreset"
2674
2896
  },
2897
+ {
2898
+ "aliases": ["lumen radiance cache", "radiance cache", "irradiance field", "dynamic probe gi"],
2899
+ "constraints": [
2900
+ "build a GPUSceneBVH of the static meshes first and pass it as trace.bvh; the cache reads colour and emissive from each material, a texture or a node is counted as ignored",
2901
+ "add the cache with ctx.add() so its refresh is measured in the render phase, and read it with sampleNode(position, normal) from a game-owned material",
2902
+ "a one-sided material is not seen from behind, as a cube capture would not draw it"
2903
+ ],
2904
+ "example": "const bvh = new GPUSceneBVH(ctx.scene); ctx.add(bvh); const cache = new RadianceCache({ bounds, density: 0.5, trace: { bvh, sun, sky, camera: ctx.camera } }); ctx.add(cache);",
2905
+ "importPath": "@threenative/core",
2906
+ "kind": "class",
2907
+ "overrides": [
2908
+ "numProbesToTraceBudget (100), probeResolution (8, so 64 rays a probe; 32 for a small emitter), bounds, density, bounces and the sun and sky values are game-owned"
2909
+ ],
2910
+ "package": "@threenative/core",
2911
+ "signature": "export class RadianceCache extends ProbeVolume { … }",
2912
+ "situations": [
2913
+ "light follows a lamp that switches on and off in a room",
2914
+ "bounce light that updates when the sun moves, with no baked lightmap",
2915
+ "global illumination that refreshes fast enough to read as dynamic"
2916
+ ],
2917
+ "summary": "A probe field of diffuse irradiance that refreshes by tracing the packed scene, with no scene draw: the radiance cache of a dynamic global-illumination pass. Probes in view refresh first, oldest first, within `numProbesToTraceBudget` a frame; a lamp toggled in game code or a sun that steps more than one degree re-traces them while the old values keep lighting the frame.",
2918
+ "supersedes": [],
2919
+ "symbol": "RadianceCache"
2920
+ },
2675
2921
  {
2676
2922
  "aliases": [],
2677
2923
  "constraints": ["non-marker lines and malformed markers return `undefined`"],
@@ -3677,6 +3923,24 @@
3677
3923
  "supersedes": [],
3678
3924
  "symbol": "SurfaceLights"
3679
3925
  },
3926
+ {
3927
+ "aliases": [],
3928
+ "constraints": [
3929
+ "the geometry must be indexed and carry no material groups, else it throws",
3930
+ "keep is in (0, 1]; a share that drops nothing returns the same geometry",
3931
+ "the choice is deterministic, and the source geometry is left untouched"
3932
+ ],
3933
+ "example": "const far = thinCards(needles.geometry, 0.4); // 40% of the cards, same area",
3934
+ "importPath": "@threenative/core",
3935
+ "kind": "function",
3936
+ "overrides": [],
3937
+ "package": "@threenative/core",
3938
+ "signature": "export function thinCards(geometry: BufferGeometry, keep: number): BufferGeometry { … }",
3939
+ "situations": ["far trees draw too many alpha-tested needle or leaf card triangles"],
3940
+ "summary": "A far level for a card mesh (needle or leaf quads): keep a share of its cards and grow each kept card about its own centre, so the crown holds its total surface area, as Unreal's Nanite \"Preserve Area\" foliage does. A simplifier cannot reduce disconnected cards, so the cooked chain leaves them at full count.",
3941
+ "supersedes": [],
3942
+ "symbol": "thinCards"
3943
+ },
3680
3944
  {
3681
3945
  "aliases": ["lumen reflections", "dedicated reflection rays"],
3682
3946
  "constraints": [
@@ -3920,6 +4184,7 @@
3920
4184
  "overrides": [
3921
4185
  "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",
3922
4186
  "bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults",
4187
+ "setFocus(point) centres every window on a subject (a third-person hero) instead of the eye, so an orbiting eye moves no shadow; setFocus(undefined) hands them back",
3923
4188
  "followViewFocus: false keeps eye follow; receiverPlaneBias: false uses only authored bias",
3924
4189
  "minWindowAspect: below 1, a level is as high as `sin(sun elevation)` times its width, never under this, so a low sun's floor shadows keep the texel density of a high sun's; the default 1 keeps square levels"
3925
4190
  ],
@@ -3929,7 +4194,8 @@
3929
4194
  "crisp shadows close to the player across a large outdoor level",
3930
4195
  "shadow map too coarse over a big terrain",
3931
4196
  "one directional light shadow for a whole open world",
3932
- "shadows shimmer when the camera moves"
4197
+ "shadows shimmer when the camera moves",
4198
+ "shadow edges, tree lighting or level sharpness change while a third-person camera turns around its hero"
3933
4199
  ],
3934
4200
  "summary": "One directional shadow for a whole open world: camera-centred clip levels, each snapped to its own texel grid and re-rendered only when its window moves. Tracked casters draw into a per-level mover map every frame, so animated casters do not invalidate the cached levels after the one refresh caused by tracking or untracking them. Plugs into three's own `light.shadow.shadowNode` slot, so every material receives it.",
3935
4201
  "supersedes": [],
@@ -4256,179 +4522,786 @@
4256
4522
  },
4257
4523
  {
4258
4524
  "aliases": [],
4259
- "constraints": ["the transport is discovered, never configured; no game names the web view"],
4260
- "example": "const bridge = connectUiBridge({ end: \"ui\" });",
4261
- "importPath": "@threenative/core/ui-layer",
4525
+ "constraints": [
4526
+ "a sample whose source texture or intensity moved is dropped, so a stale one never reaches a material"
4527
+ ],
4528
+ "example": "const hit = cachedEnvironmentSample(renderer, scene);",
4529
+ "importPath": "@threenative/core/render/environment",
4262
4530
  "kind": "function",
4263
4531
  "overrides": [],
4264
4532
  "package": "@threenative/core",
4265
- "signature": "export function connectUiBridge(options: IConnectOptions): IUiBridge { … }",
4266
- "situations": [
4267
- "write a UI that talks to the game on web and on a phone alike",
4268
- "send a message from a HUD rendered over the game surface",
4269
- "connect game code to a platform-owned UI realm",
4270
- "share one UI bridge implementation across web, Android, iOS, and desktop"
4271
- ],
4272
- "summary": "Open the message channel between a game and its UI, whatever host is underneath.",
4533
+ "signature": "export function cachedEnvironmentSample( renderer: object, scene: Scene, ): IEnvironmentSample | undefined { … }",
4534
+ "situations": ["skip a second environment readback in the same frame"],
4535
+ "summary": "The sample this renderer took of `scene`'s environment, if it is still current.",
4273
4536
  "supersedes": [],
4274
- "symbol": "connectUiBridge"
4537
+ "symbol": "cachedEnvironmentSample"
4275
4538
  },
4276
4539
  {
4277
4540
  "aliases": [],
4278
- "constraints": ["prefer game.ui.onIntent, which connects the bridge for you"],
4279
- "example": "onUiIntent(bridge, (intent) => { if (intent === \"restart\") game.goto(\"Play\"); });",
4280
- "importPath": "@threenative/core/ui-layer",
4541
+ "constraints": [],
4542
+ "example": "cacheEnvironmentSample(renderer, scene, sample);",
4543
+ "importPath": "@threenative/core/render/environment",
4281
4544
  "kind": "function",
4282
4545
  "overrides": [],
4283
4546
  "package": "@threenative/core",
4284
- "signature": "export function onUiIntent( bridge: IUiBridge, listener: (intent: string, payload: unknown) => void, ): () => void { … }",
4285
- "situations": [
4286
- "restart or pause a game from a button in its HUD",
4287
- "handle a HUD button action in game code",
4288
- "route native and web UI commands through one listener"
4289
- ],
4290
- "summary": "Handle the actions a UI sends back to the game.",
4547
+ "signature": "export function cacheEnvironmentSample( renderer: object, scene: Scene, sample: IEnvironmentSample, ): void { … }",
4548
+ "situations": ["reuse one environment readback across the materials of a scene"],
4549
+ "summary": "Remembers `sample` as this renderer's reading of `scene`'s environment.",
4291
4550
  "supersedes": [],
4292
- "symbol": "onUiIntent"
4551
+ "symbol": "cacheEnvironmentSample"
4293
4552
  },
4294
4553
  {
4295
4554
  "aliases": [],
4296
- "constraints": [
4297
- "mark controls with data-tn-interactive; pointer-events is not the mechanism"
4298
- ],
4299
- "example": "publishHitRegions({ bridge });",
4300
- "importPath": "@threenative/core/ui-layer",
4555
+ "constraints": [],
4556
+ "example": "const snapshot = captureEnvironmentSnapshot(scene);",
4557
+ "importPath": "@threenative/core/render/environment",
4301
4558
  "kind": "function",
4302
4559
  "overrides": [],
4303
4560
  "package": "@threenative/core",
4304
- "signature": "export function publishHitRegions(options: IRegistryOptions): IHitRegionRegistry { … }",
4305
- "situations": [
4306
- "let a touch on empty HUD space reach the game instead of the UI",
4307
- "make a HUD button receive taps on a phone",
4308
- "give native input hosts the rectangles claimed by UI controls",
4309
- "keep touch hit testing aligned with a moving web or native HUD"
4310
- ],
4311
- "summary": "Tell the native input host where a UI's touchable controls are.",
4561
+ "signature": "export function captureEnvironmentSnapshot(scene: Scene): IEnvironmentSourceSnapshot { … }",
4562
+ "situations": ["reject an environment readback that belongs to a different sky"],
4563
+ "summary": "The provenance of a scene's environment: which texture, at which intensity, in which colour space.",
4312
4564
  "supersedes": [],
4313
- "symbol": "publishHitRegions"
4565
+ "symbol": "captureEnvironmentSnapshot"
4314
4566
  },
4315
4567
  {
4316
- "aliases": ["journal objective panel", "readable HUD"],
4317
- "constraints": [
4318
- "publishes once per rendered frame unless stateFlushMs selects a slower interval, and not at all with no UI listening"
4319
- ],
4320
- "example": "publishUiState(bridge, game.state);",
4321
- "importPath": "@threenative/core/ui-layer",
4568
+ "aliases": [],
4569
+ "constraints": [],
4570
+ "example": "if (environmentSnapshotCurrent(scene, snapshot)) draw(snapshot);",
4571
+ "importPath": "@threenative/core/render/environment",
4322
4572
  "kind": "function",
4323
4573
  "overrides": [],
4324
4574
  "package": "@threenative/core",
4325
- "signature": "export function publishUiState<T>( bridge: IUiBridge, store: IPublishableStore<T>, options: IPublishOptions = { … }",
4326
- "situations": [
4327
- "show score or health in a UI rendered over the game surface",
4328
- "keep a HUD in step with the game without re-rendering on the loop",
4329
- "publish game state to a HUD in another realm",
4330
- "keep a web and native UI mirror on the same coalesced state stream"
4331
- ],
4332
- "summary": "Publish the game's state so a UI in another process can mirror it.",
4575
+ "signature": "export function environmentSnapshotCurrent( scene: Scene, snapshot: IEnvironmentSourceSnapshot, ): boolean { … }",
4576
+ "situations": ["hold a material's fill light to the sky that is on screen now"],
4577
+ "summary": "Whether the scene's environment still matches the snapshot a sample was taken from.",
4333
4578
  "supersedes": [],
4334
- "symbol": "publishUiState"
4579
+ "symbol": "environmentSnapshotCurrent"
4335
4580
  },
4336
4581
  {
4337
4582
  "aliases": [],
4338
- "constraints": ["one-way; the game decides what each name means and may ignore one"],
4339
- "example": "sendUiIntent(bridge, \"restart\");",
4340
- "importPath": "@threenative/core/ui-layer",
4583
+ "constraints": [],
4584
+ "example": "if (isWebGLFallbackRenderer(renderer)) skipMaterialLane();",
4585
+ "importPath": "@threenative/core/render/environment",
4341
4586
  "kind": "function",
4342
4587
  "overrides": [],
4343
4588
  "package": "@threenative/core",
4344
- "signature": "export function sendUiIntent(bridge: IUiBridge, intent: string, payload?: unknown): void { … }",
4589
+ "signature": "export function isWebGLFallbackRenderer(renderer: unknown): boolean { … }",
4345
4590
  "situations": [
4346
- "wire a Restart button in a HUD to the running game",
4347
- "pause a game from a menu drawn over its surface",
4348
- "send a button or menu action from a UI HUD to game code",
4349
- "keep UI input portable across web and native hosts"
4591
+ "refuse a GPU-only lane on a WebGL fallback instead of drawing something wrong"
4350
4592
  ],
4351
- "summary": "Send a player action from the UI back to the game.",
4593
+ "summary": "Whether a `WebGPURenderer` wrapper is running three's WebGL backend behind it.",
4352
4594
  "supersedes": [],
4353
- "symbol": "sendUiIntent"
4595
+ "symbol": "isWebGLFallbackRenderer"
4354
4596
  },
4355
4597
  {
4356
4598
  "aliases": [],
4357
- "constraints": ["returns undefined until the game publishes its first state"],
4358
- "example": "const mirror = subscribeUiState(bridge);",
4359
- "importPath": "@threenative/core/ui-layer",
4599
+ "constraints": [
4600
+ "high tier, browser, hardware WebGPU, not mobile, not software, not a WebGL fallback"
4601
+ ],
4602
+ "example": "if (materialLightingEnabled(\"high\", env)) lightMaterials();",
4603
+ "importPath": "@threenative/core/render/environment",
4360
4604
  "kind": "function",
4361
4605
  "overrides": [],
4362
4606
  "package": "@threenative/core",
4363
- "signature": "export function subscribeUiState<T>(bridge: IUiBridge): IUiStateMirror<T> { … }",
4364
- "situations": [
4365
- "read game state from a HUD that runs in the platform's web view",
4366
- "read published game state from a UI HUD",
4367
- "subscribe a web or native UI to the game's mirrored state"
4368
- ],
4369
- "summary": "Mirror the game's published state on the UI side.",
4607
+ "signature": "export function materialLightingEnabled( tier: QualityTier, environment: IMaterialLightingEnvironment, ): boolean { … }",
4608
+ "situations": ["decide whether this renderer is the admitted material lane"],
4609
+ "summary": "Whether `tier` may run the material-lighting lane in `environment`.",
4370
4610
  "supersedes": [],
4371
- "symbol": "subscribeUiState"
4611
+ "symbol": "materialLightingEnabled"
4372
4612
  },
4373
4613
  {
4374
4614
  "aliases": [],
4375
4615
  "constraints": [],
4376
- "example": "serveWorkerGame(game);",
4377
- "importPath": "@threenative/core/worker",
4616
+ "example": "const m = measureEnvironment(scene, 2048);",
4617
+ "importPath": "@threenative/core/render/environment",
4378
4618
  "kind": "function",
4379
4619
  "overrides": [],
4380
4620
  "package": "@threenative/core",
4381
- "signature": "export function serveWorkerGame( game: { … }",
4382
- "situations": ["run the game loop in a web worker so a busy page cannot stall its frames"],
4383
- "summary": "Runs inside the worker: wire the page's messages to the unchanged portable game. Call it last in the worker entry, after the game module evaluated: it posts the ready message the page waits for before it sends the canvas.",
4621
+ "signature": "export function measureEnvironment(scene: Scene, maxSourceTexels: number): IEnvironmentMeasurement { … }",
4622
+ "situations": [
4623
+ "measure what a scene's environment actually contributes",
4624
+ "sample the environment on the GPU without stalling the frame",
4625
+ "keep an environment readback from reaching a frame it does not belong to"
4626
+ ],
4627
+ "summary": "The environment measure-and-sample mechanism every kit repeats: what the scene's environment actually contributes, a bounded GPU sample of it with a cache and a readback deadline, the provenance a stale readback is rejected by, and the gate that decides which renderer may run the material lane. The backlight itself is a shader with fixed constants, so it stays in each kit's `src/render/` (stamped from one source there) where the game can change how it looks. This is machinery, not a look: every colour, gain and threshold arrives as an argument, and a kit that wants a different bound passes a different one. It lives here because twelve kits held byte-identical copies — 9 084 lines — so a fix to one left eleven wrong with every gate green (`c93b427d0` touched 552 files for one look change).",
4384
4628
  "supersedes": [],
4385
- "symbol": "serveWorkerGame"
4629
+ "symbol": "measureEnvironment"
4386
4630
  },
4387
4631
  {
4388
4632
  "aliases": [],
4389
4633
  "constraints": [],
4390
- "example": "const handle = startWorkerGame(new Worker(new URL(\"./worker.ts\", import.meta.url), { type: \"module\" }), root);",
4391
- "importPath": "@threenative/core/worker",
4634
+ "example": "reportEnvironmentContribution(scene, {\n darkThreshold: 0.02, fillAdmitted: true, fillColor: new Color(1, 1, 1), fillGain: 0.4,\n maxSourceTexels: 2048, rimGain: 0.6,\n});",
4635
+ "importPath": "@threenative/core/render/environment",
4392
4636
  "kind": "function",
4393
4637
  "overrides": [],
4394
4638
  "package": "@threenative/core",
4395
- "signature": "export function startWorkerGame( worker: Worker, container: HTMLElement, ): { … }",
4396
- "situations": ["host a worker-run game's canvas, input and HUD on the page"],
4397
- "summary": "Runs on the page: own the canvas and the DOM, and feed the worker game. Call it before the UI mounts: the HUD's bridge host globals exist from this call on.",
4639
+ "signature": "export function reportEnvironmentContribution( scene: Scene, options: IContributionControls, measurement?: IEnvironmentMeasurement, ) { … }",
4640
+ "situations": [
4641
+ "measure what a scene's environment actually contributes",
4642
+ "sample the environment on the GPU without stalling the frame",
4643
+ "keep an environment readback from reaching a frame it does not belong to"
4644
+ ],
4645
+ "summary": "The environment measure-and-sample mechanism every kit repeats: what the scene's environment actually contributes, a bounded GPU sample of it with a cache and a readback deadline, the provenance a stale readback is rejected by, and the gate that decides which renderer may run the material lane. The backlight itself is a shader with fixed constants, so it stays in each kit's `src/render/` (stamped from one source there) where the game can change how it looks. This is machinery, not a look: every colour, gain and threshold arrives as an argument, and a kit that wants a different bound passes a different one. It lives here because twelve kits held byte-identical copies — 9 084 lines — so a fix to one left eleven wrong with every gate green (`c93b427d0` touched 552 files for one look change).",
4398
4646
  "supersedes": [],
4399
- "symbol": "startWorkerGame"
4647
+ "symbol": "reportEnvironmentContribution"
4400
4648
  },
4401
4649
  {
4402
4650
  "aliases": [],
4403
4651
  "constraints": [
4404
- "the returned view aliases the caller's buffer; writing to it mutates the source"
4652
+ "the sample must be the qualified 64x32 float RGBA readback; anything else is refused by name"
4405
4653
  ],
4406
- "example": "const records = cellPlacements(buffer, { asset: \"tree\", offset: 0, count: 120 });",
4407
- "importPath": "@threenative/core/world",
4654
+ "example": "const m = sampledRadiance(readback, 1);",
4655
+ "importPath": "@threenative/core/render/environment",
4408
4656
  "kind": "function",
4409
4657
  "overrides": [],
4410
4658
  "package": "@threenative/core",
4411
- "signature": "export function cellPlacements(placements: ArrayBuffer, run: IWorldRun): Float32Array { … }",
4412
- "situations": ["feed one cell's instance transforms into a batch without copying"],
4413
- "summary": "Borrow the run's placement records as a live view over the placement buffer.",
4659
+ "signature": "export function sampledRadiance(samples: unknown, intensity: number): IEnvironmentMeasurement { … }",
4660
+ "situations": [
4661
+ "turn an environment readback into the radiance a material's fill light needs",
4662
+ "know why an environment sample could not be measured"
4663
+ ],
4664
+ "summary": "The mean radiance and colour of a bounded linear sample, or `unknown` with the reason.",
4414
4665
  "supersedes": [],
4415
- "symbol": "cellPlacements"
4666
+ "symbol": "sampledRadiance"
4416
4667
  },
4417
4668
  {
4418
4669
  "aliases": [],
4419
4670
  "constraints": [
4420
- "unsupported is returned when compute limits are unknown or below the requirement; callers must not silently continue"
4671
+ "off unless the renderer is the admitted high-tier WebGPU lane; every refusal is reported by name",
4672
+ "the readback is abandoned after the deadline and the frame keeps the previous answer"
4421
4673
  ],
4422
- "example": "const capabilities = getWorldCapabilities({ limits: adapter.limits, cpuFallbackIterations: 8 });",
4423
- "importPath": "@threenative/core/world",
4674
+ "example": "const sample = await sampleEnvironment(renderer, scene, env);",
4675
+ "importPath": "@threenative/core/render/environment",
4424
4676
  "kind": "function",
4425
- "overrides": [
4426
- "minimumWorkgroupsPerDimension, minimumStorageBufferBindingSize, and cpuFallbackIterations"
4427
- ],
4677
+ "overrides": [],
4428
4678
  "package": "@threenative/core",
4429
- "signature": "export function getWorldCapabilities(options: IWorldCapabilitiesOptions = { … }",
4679
+ "signature": "export async function sampleEnvironment( renderer: unknown, scene: Scene, environment: IMaterialLightingEnvironment, ): Promise<IEnvironmentSample> { … }",
4430
4680
  "situations": [
4431
- "decide whether generated terrain can use GPU compute",
4681
+ "measure what a scene's environment actually contributes without stalling the frame",
4682
+ "give a material's fill light the environment's own radiance"
4683
+ ],
4684
+ "summary": "Measures and samples the scene's real environment on the GPU, bounded by a readback deadline.",
4685
+ "supersedes": [],
4686
+ "symbol": "sampleEnvironment"
4687
+ },
4688
+ {
4689
+ "aliases": [],
4690
+ "constraints": [],
4691
+ "example": "if (samplingSourceSupported(source)) sample(source);",
4692
+ "importPath": "@threenative/core/render/environment",
4693
+ "kind": "function",
4694
+ "overrides": [],
4695
+ "package": "@threenative/core",
4696
+ "signature": "export function samplingSourceSupported(source: NonNullable<Scene[\"environment\"]>): boolean { … }",
4697
+ "situations": ["know why an environment was not sampled on the GPU"],
4698
+ "summary": "Whether an environment texture's mapping and colour space are qualified for the bounded GPU sample.",
4699
+ "supersedes": [],
4700
+ "symbol": "samplingSourceSupported"
4701
+ },
4702
+ {
4703
+ "aliases": [],
4704
+ "constraints": [
4705
+ "the pool is fixed and recycles the cast alive longest; it never grows",
4706
+ "a ball that has passed its target lands on the target, however late the frame notices"
4707
+ ],
4708
+ "example": "const casts = new CastPool(world);\ncasts.cast(fireball, target, { from: hand });\ncasts.update(dt);",
4709
+ "importPath": "@threenative/core/spells",
4710
+ "kind": "class",
4711
+ "overrides": [
4712
+ "timing, shape, speed and radius come from the spell; a cast may override shape and seed"
4713
+ ],
4714
+ "package": "@threenative/core",
4715
+ "signature": "export class CastPool { … }",
4716
+ "situations": [
4717
+ "a fireball or a lightning bolt that charges, flies, lands and lingers",
4718
+ "several spells mid-flight, with no allocation per cast"
4719
+ ],
4720
+ "summary": "Step a spell's timeline: charge, release, travel, impact, linger, done.",
4721
+ "supersedes": [],
4722
+ "symbol": "CastPool"
4723
+ },
4724
+ {
4725
+ "aliases": [],
4726
+ "constraints": ["every colour, size, count and timing is a named override on the call"],
4727
+ "example": "const aegis = createAegis(world);\ncasts.cast(aegis, world.focus);",
4728
+ "importPath": "@threenative/core/spells",
4729
+ "kind": "function",
4730
+ "overrides": [
4731
+ "core, highlight, charge, impact, linger, radius, light",
4732
+ "core, highlight, charge, impact, linger, radius, light, shake"
4733
+ ],
4734
+ "package": "@threenative/core",
4735
+ "signature": "export function createAegis(world: SpellWorld, overrides: IFireSpellOverrides = { … }",
4736
+ "situations": [
4737
+ "a shield spell a player casts on themselves",
4738
+ "a magic barrier that forms around the caster",
4739
+ "make a protective bubble spell",
4740
+ "a defensive bubble that flashes when it breaks"
4741
+ ],
4742
+ "summary": "A ward around the caster: it forms, holds, and breaks outward when it expires.",
4743
+ "supersedes": [],
4744
+ "symbol": "createAegis"
4745
+ },
4746
+ {
4747
+ "aliases": [],
4748
+ "constraints": ["every colour, size, count and timing is a named override on the call"],
4749
+ "example": "const barrage = createArcaneBarrage(world);\ncasts.cast(barrage, target);",
4750
+ "importPath": "@threenative/core/spells",
4751
+ "kind": "function",
4752
+ "overrides": ["core, highlight, speed, charge, impact, linger, radius, burst, light"],
4753
+ "package": "@threenative/core",
4754
+ "signature": "export function createArcaneBarrage(world: SpellWorld, overrides: IFireSpellOverrides = { … }",
4755
+ "situations": [
4756
+ "an arcane missile spell that fires projectiles at a target",
4757
+ "a magic barrage a mage class spams",
4758
+ "a magic missile spell",
4759
+ "make an arcane bolt spell",
4760
+ "an arcane missile spell that fires several projectiles at a target",
4761
+ "a pink energy bolt with a short charge"
4762
+ ],
4763
+ "summary": "A volley of arcane missiles: fast, precise, and each one pops on arrival.",
4764
+ "supersedes": [],
4765
+ "symbol": "createArcaneBarrage"
4766
+ },
4767
+ {
4768
+ "aliases": [],
4769
+ "constraints": [
4770
+ "every colour, size, count and timing is a named override on the call",
4771
+ "the first cast costs what the hundredth does: nothing is built at cast time",
4772
+ "the stock look ships as the default, and no override rebuilds a pipeline"
4773
+ ],
4774
+ "example": "const fireball = createFireball(world);\ncasts.cast(fireball, target);",
4775
+ "importPath": "@threenative/core/spells",
4776
+ "kind": "function",
4777
+ "overrides": [
4778
+ "core, highlight, speed, charge, impact, linger, radius, burst, trail, lingerBurst, light, shake, scorch"
4779
+ ],
4780
+ "package": "@threenative/core",
4781
+ "signature": "export function createFireball(world: SpellWorld, overrides: IFireSpellOverrides = { … }",
4782
+ "situations": [
4783
+ "a fireball spell the player casts at an enemy",
4784
+ "a burning projectile that explodes and scorches the ground",
4785
+ "a wizard's fire attack with a wind-up, a flight and an aftermath",
4786
+ "make a fireball",
4787
+ "a fireball spell a player casts at an enemy"
4788
+ ],
4789
+ "summary": "A ball of fire that charges, crosses the room and leaves the floor burning.",
4790
+ "supersedes": [],
4791
+ "symbol": "createFireball"
4792
+ },
4793
+ {
4794
+ "aliases": [],
4795
+ "constraints": ["every colour, size, count and timing is a named override on the call"],
4796
+ "example": "const spike = createGlacialSpike(world);\ncasts.cast(spike, target);",
4797
+ "importPath": "@threenative/core/spells",
4798
+ "kind": "function",
4799
+ "overrides": ["core, highlight, speed, charge, impact, linger, radius, burst, trail, light"],
4800
+ "package": "@threenative/core",
4801
+ "signature": "export function createGlacialSpike(world: SpellWorld, overrides: IFireSpellOverrides = { … }",
4802
+ "situations": [
4803
+ "an ice spike spell that flies at a target and shatters",
4804
+ "a freezing projectile that leaves frost on the floor",
4805
+ "make an ice spell",
4806
+ "a cold spell with a charge, a flight and a lingering chill"
4807
+ ],
4808
+ "summary": "A shard of ice that flies flat and fast, and freezes the ground it breaks on.",
4809
+ "supersedes": [],
4810
+ "symbol": "createGlacialSpike"
4811
+ },
4812
+ {
4813
+ "aliases": [],
4814
+ "constraints": ["every colour, size, count and timing is a named override on the call"],
4815
+ "example": "const inferno = createInferno(world);\ncasts.cast(inferno, target);",
4816
+ "importPath": "@threenative/core/spells",
4817
+ "kind": "function",
4818
+ "overrides": [
4819
+ "core, highlight, charge, impact, linger, radius, burst, trail, light, shake, scorch"
4820
+ ],
4821
+ "package": "@threenative/core",
4822
+ "signature": "export function createInferno(world: SpellWorld, overrides: IFireSpellOverrides = { … }",
4823
+ "situations": [
4824
+ "a fire area spell that erupts at a point and burns there",
4825
+ "an inferno column a boss drops on the arena",
4826
+ "make a sustained fire area spell",
4827
+ "a sustained flame that scorches the ground for seconds"
4828
+ ],
4829
+ "summary": "A pillar of fire that erupts where it lands and keeps burning.",
4830
+ "supersedes": [],
4831
+ "symbol": "createInferno"
4832
+ },
4833
+ {
4834
+ "aliases": [],
4835
+ "constraints": [
4836
+ "read the world through SpellWorld only, so a game can swap the scene and the floor"
4837
+ ],
4838
+ "example": "const spell = createSpell(world, recipe);",
4839
+ "importPath": "@threenative/core/spells",
4840
+ "kind": "function",
4841
+ "overrides": [],
4842
+ "package": "@threenative/core",
4843
+ "signature": "export function createSpell(world: SpellWorld, recipe: ISpellRecipe): ISpell { … }",
4844
+ "situations": ["author a spell the catalog does not cover, out of the same beats"],
4845
+ "summary": "Build a spell from a recipe: four beats, a tint, and the numbers between them.",
4846
+ "supersedes": [],
4847
+ "symbol": "createSpell"
4848
+ },
4849
+ {
4850
+ "aliases": [],
4851
+ "constraints": ["every colour, size, count and timing is a named override on the call"],
4852
+ "example": "const bolt = createThunderstrike(world);\ncasts.cast(bolt, target);",
4853
+ "importPath": "@threenative/core/spells",
4854
+ "kind": "function",
4855
+ "overrides": ["core, highlight, charge, impact, linger, radius, light, shake, scorch"],
4856
+ "package": "@threenative/core",
4857
+ "signature": "export function createThunderstrike(world: SpellWorld, overrides: IFireSpellOverrides = { … }",
4858
+ "situations": [
4859
+ "a lightning strike spell that hits a point immediately",
4860
+ "a thunderbolt with a wind-up and a burnt mark where it lands",
4861
+ "make a lightning spell",
4862
+ "an electrical spell with a column of light from above"
4863
+ ],
4864
+ "summary": "A bolt out of the sky: it charges, strikes the point instantly, and the ground remembers it.",
4865
+ "supersedes": [],
4866
+ "symbol": "createThunderstrike"
4867
+ },
4868
+ {
4869
+ "aliases": [],
4870
+ "constraints": [
4871
+ "set writes uniforms; no kernel, material or pipeline is rebuilt",
4872
+ "a table knows only the kinds it was asked for, so an unused kind costs nothing"
4873
+ ],
4874
+ "example": "const kinds = new ParticleKindTable([\"flame\", \"smoke\"]);\nkinds.set(\"flame\", { lifetime: [0.3, 0.6], colour: [0.4, 0.8, 1] });",
4875
+ "importPath": "@threenative/core/spells",
4876
+ "kind": "class",
4877
+ "overrides": [
4878
+ "lifetime, size, speed, cone, gravity, drag, buoyancy, alpha, colour and highlight"
4879
+ ],
4880
+ "package": "@threenative/core",
4881
+ "signature": "export class ParticleKindTable { … }",
4882
+ "situations": [
4883
+ "retune a spell's particles at run time from a settings screen",
4884
+ "change how long, how fast or how heavy a kind of particle is without a new pipeline"
4885
+ ],
4886
+ "summary": "Tune what a particle kind does, as data rather than a shader.",
4887
+ "supersedes": [],
4888
+ "symbol": "ParticleKindTable"
4889
+ },
4890
+ {
4891
+ "aliases": [],
4892
+ "constraints": [
4893
+ "it draws nothing; the game decides what a mark looks like",
4894
+ "the patch is finite and every channel decays on its own half-life"
4895
+ ],
4896
+ "example": "field.splat({ heat: 1, char: 0.6, radius: 2.5, x: hit.x, z: hit.z });\nfield.update(dt);",
4897
+ "importPath": "@threenative/core/spells",
4898
+ "kind": "class",
4899
+ "overrides": [
4900
+ "halfLife, resolution and size tune the patch; pattern, radius, seed and angle set each mark"
4901
+ ],
4902
+ "package": "@threenative/core",
4903
+ "signature": "export class ReactionField { … }",
4904
+ "situations": [
4905
+ "a fireball impact that leaves a scorch and fades over time",
4906
+ "ice that melts where lightning spread, or a lava geyser's crack"
4907
+ ],
4908
+ "summary": "The marks a spell leaves on the floor: heat, char, wet, frost, crack and glow.",
4909
+ "supersedes": [],
4910
+ "symbol": "ReactionField"
4911
+ },
4912
+ {
4913
+ "aliases": [],
4914
+ "constraints": [
4915
+ "the whole pool exists before the first cast; a cast changes intensity, never the list",
4916
+ "flash returns undefined when the pool is busy; a spell carries on without one"
4917
+ ],
4918
+ "example": "lights.flash({ x, y, z, color, intensity: 40, range: 12, seconds: 0.35 });",
4919
+ "importPath": "@threenative/core/spells",
4920
+ "kind": "class",
4921
+ "overrides": [
4922
+ "count is the pool size; each flash supplies position, colour, intensity, range and seconds"
4923
+ ],
4924
+ "package": "@threenative/core",
4925
+ "signature": "export class SpellLights { … }",
4926
+ "situations": [
4927
+ "a spell impact that glows without changing the light count",
4928
+ "a charge glow or a falling meteor lighting what it passes"
4929
+ ],
4930
+ "summary": "A fixed pool of spell lights, created once at zero intensity.",
4931
+ "supersedes": [],
4932
+ "symbol": "SpellLights"
4933
+ },
4934
+ {
4935
+ "aliases": [],
4936
+ "constraints": [
4937
+ "damage, mana, cooldowns and who the target is stay in the game",
4938
+ "with reducedFlashes on, a fourth flash inside one second is refused, never dimmed"
4939
+ ],
4940
+ "example": "const world = new SpellWorld({ scene, groundAt });\nconst casts = new CastPool(world);",
4941
+ "importPath": "@threenative/core/spells",
4942
+ "kind": "class",
4943
+ "overrides": [
4944
+ "groundAt, castSlots, lightCount, reaction, shake and reducedFlashes are named options"
4945
+ ],
4946
+ "package": "@threenative/core",
4947
+ "signature": "export class SpellWorld implements ICastEnvironment { … }",
4948
+ "situations": [
4949
+ "cast an engine spell without passing a scene into every call",
4950
+ "honour an accessibility setting that limits flashing"
4951
+ ],
4952
+ "summary": "Everything a spell may touch: the scene, the floor, the light pool, the surface field, one shake and one flash limiter.",
4953
+ "supersedes": [],
4954
+ "symbol": "SpellWorld"
4955
+ },
4956
+ {
4957
+ "aliases": [],
4958
+ "constraints": [
4959
+ "costs about 0.6 s at 64^3 and about 5 s at 128^3 on the main thread; bake once at load"
4960
+ ],
4961
+ "example": "bakeNoise({ noiseSize: 64 }); // once at load, before createFx draws",
4962
+ "importPath": "@threenative/core/spells/ultra",
4963
+ "kind": "function",
4964
+ "overrides": [],
4965
+ "package": "@threenative/core",
4966
+ "signature": "export function bakeNoise( { … }",
4967
+ "situations": [
4968
+ "the noise and blackbody textures an Ultra Elements spell needs before it first draws"
4969
+ ],
4970
+ "summary": "CPU bake of the Ultra Elements 3D noise, curl and blackbody textures that every spell volume samples.",
4971
+ "supersedes": [],
4972
+ "symbol": "bakeNoise"
4973
+ },
4974
+ {
4975
+ "aliases": [],
4976
+ "constraints": [
4977
+ "call bakeNoise first: the volume shaders sample its noise, curl and blackbody textures"
4978
+ ],
4979
+ "example": "const ultra = createFx({ camera, size: () => ({ width: innerWidth, height: innerHeight }), seed: 777 }); const fireball = ultra.addSpell(fire); scene.add(ultra.fx.scenes.fx);",
4980
+ "importPath": "@threenative/core/spells/ultra",
4981
+ "kind": "function",
4982
+ "overrides": [],
4983
+ "package": "@threenative/core",
4984
+ "signature": "export function createFx(o: IFxOptions) { … }",
4985
+ "situations": [
4986
+ "an Ultra Elements spell such as the raymarched teardrop Fireball cast at a target",
4987
+ "a volumetric fire spell drawn through the Three.js TSL node API on WebGPU"
4988
+ ],
4989
+ "summary": "The shared Ultra Elements spell world: casts, volumes, spell lights and the per-frame CPU tick. Add `fx.scenes.fx` to the scene, `addSpell` each ported spell, call `renderFrame(dt)` each frame.",
4990
+ "supersedes": [],
4991
+ "symbol": "createFx"
4992
+ },
4993
+ {
4994
+ "aliases": [],
4995
+ "constraints": [],
4996
+ "example": "const shade = groundShade(positionWorld, { albedo, rough: float(0.85), metal: float(0) }); floor.colorNode = vec4(shade.color, 1);",
4997
+ "importPath": "@threenative/core/spells/ultra",
4998
+ "kind": "function",
4999
+ "overrides": [],
5000
+ "package": "@threenative/core",
5001
+ "signature": "export function groundShade(wp: V3, surface: IGroundSurface) { … }",
5002
+ "situations": [
5003
+ "a floor that shows the Fireball's scorch and hot ground cooling over seconds"
5004
+ ],
5005
+ "summary": "The Ultra Elements arena floor's response to the ground field and spell impacts (scorch, char, wet, glowing hot ground) as nodes for a game's own floor material: `color`, `roughness`, `metalness`, `emissive` from the floor's own surface at a world position.",
5006
+ "supersedes": [],
5007
+ "symbol": "groundShade"
5008
+ },
5009
+ {
5010
+ "aliases": [],
5011
+ "constraints": [],
5012
+ "example": "const flames = ultra.fx.particles.emitter(\"fire.flame\"); // ultra from createFx",
5013
+ "importPath": "@threenative/core/spells/ultra",
5014
+ "kind": "class",
5015
+ "overrides": [],
5016
+ "package": "@threenative/core",
5017
+ "signature": "export class Particles { … }",
5018
+ "situations": [
5019
+ "the flames, embers, sparks, smoke and debris an Ultra Elements spell emits as it charges, flies and hits"
5020
+ ],
5021
+ "summary": "The Ultra Elements GPU particle system behind `fx.particles`: a spell's kinds, emitters and field emitters.",
5022
+ "supersedes": [],
5023
+ "symbol": "Particles"
5024
+ },
5025
+ {
5026
+ "aliases": [],
5027
+ "constraints": ["the transport is discovered, never configured; no game names the web view"],
5028
+ "example": "const bridge = connectUiBridge({ end: \"ui\" });",
5029
+ "importPath": "@threenative/core/ui-layer",
5030
+ "kind": "function",
5031
+ "overrides": [],
5032
+ "package": "@threenative/core",
5033
+ "signature": "export function connectUiBridge(options: IConnectOptions): IUiBridge { … }",
5034
+ "situations": [
5035
+ "write a UI that talks to the game on web and on a phone alike",
5036
+ "send a message from a HUD rendered over the game surface",
5037
+ "connect game code to a platform-owned UI realm",
5038
+ "share one UI bridge implementation across web, Android, iOS, and desktop"
5039
+ ],
5040
+ "summary": "Open the message channel between a game and its UI, whatever host is underneath.",
5041
+ "supersedes": [],
5042
+ "symbol": "connectUiBridge"
5043
+ },
5044
+ {
5045
+ "aliases": [],
5046
+ "constraints": ["prefer game.ui.onIntent, which connects the bridge for you"],
5047
+ "example": "onUiIntent(bridge, (intent) => { if (intent === \"restart\") game.goto(\"Play\"); });",
5048
+ "importPath": "@threenative/core/ui-layer",
5049
+ "kind": "function",
5050
+ "overrides": [],
5051
+ "package": "@threenative/core",
5052
+ "signature": "export function onUiIntent( bridge: IUiBridge, listener: (intent: string, payload: unknown) => void, ): () => void { … }",
5053
+ "situations": [
5054
+ "restart or pause a game from a button in its HUD",
5055
+ "handle a HUD button action in game code",
5056
+ "route native and web UI commands through one listener"
5057
+ ],
5058
+ "summary": "Handle the actions a UI sends back to the game.",
5059
+ "supersedes": [],
5060
+ "symbol": "onUiIntent"
5061
+ },
5062
+ {
5063
+ "aliases": [],
5064
+ "constraints": [
5065
+ "mark controls with data-tn-interactive; pointer-events is not the mechanism"
5066
+ ],
5067
+ "example": "publishHitRegions({ bridge });",
5068
+ "importPath": "@threenative/core/ui-layer",
5069
+ "kind": "function",
5070
+ "overrides": [],
5071
+ "package": "@threenative/core",
5072
+ "signature": "export function publishHitRegions(options: IRegistryOptions): IHitRegionRegistry { … }",
5073
+ "situations": [
5074
+ "let a touch on empty HUD space reach the game instead of the UI",
5075
+ "make a HUD button receive taps on a phone",
5076
+ "give native input hosts the rectangles claimed by UI controls",
5077
+ "keep touch hit testing aligned with a moving web or native HUD"
5078
+ ],
5079
+ "summary": "Tell the native input host where a UI's touchable controls are.",
5080
+ "supersedes": [],
5081
+ "symbol": "publishHitRegions"
5082
+ },
5083
+ {
5084
+ "aliases": ["journal objective panel", "readable HUD"],
5085
+ "constraints": [
5086
+ "publishes once per rendered frame unless stateFlushMs selects a slower interval, and not at all with no UI listening"
5087
+ ],
5088
+ "example": "publishUiState(bridge, game.state);",
5089
+ "importPath": "@threenative/core/ui-layer",
5090
+ "kind": "function",
5091
+ "overrides": [],
5092
+ "package": "@threenative/core",
5093
+ "signature": "export function publishUiState<T>( bridge: IUiBridge, store: IPublishableStore<T>, options: IPublishOptions = { … }",
5094
+ "situations": [
5095
+ "show score or health in a UI rendered over the game surface",
5096
+ "keep a HUD in step with the game without re-rendering on the loop",
5097
+ "publish game state to a HUD in another realm",
5098
+ "keep a web and native UI mirror on the same coalesced state stream"
5099
+ ],
5100
+ "summary": "Publish the game's state so a UI in another process can mirror it.",
5101
+ "supersedes": [],
5102
+ "symbol": "publishUiState"
5103
+ },
5104
+ {
5105
+ "aliases": [],
5106
+ "constraints": ["one-way; the game decides what each name means and may ignore one"],
5107
+ "example": "sendUiIntent(bridge, \"restart\");",
5108
+ "importPath": "@threenative/core/ui-layer",
5109
+ "kind": "function",
5110
+ "overrides": [],
5111
+ "package": "@threenative/core",
5112
+ "signature": "export function sendUiIntent(bridge: IUiBridge, intent: string, payload?: unknown): void { … }",
5113
+ "situations": [
5114
+ "wire a Restart button in a HUD to the running game",
5115
+ "pause a game from a menu drawn over its surface",
5116
+ "send a button or menu action from a UI HUD to game code",
5117
+ "keep UI input portable across web and native hosts"
5118
+ ],
5119
+ "summary": "Send a player action from the UI back to the game.",
5120
+ "supersedes": [],
5121
+ "symbol": "sendUiIntent"
5122
+ },
5123
+ {
5124
+ "aliases": [],
5125
+ "constraints": ["returns undefined until the game publishes its first state"],
5126
+ "example": "const mirror = subscribeUiState(bridge);",
5127
+ "importPath": "@threenative/core/ui-layer",
5128
+ "kind": "function",
5129
+ "overrides": [],
5130
+ "package": "@threenative/core",
5131
+ "signature": "export function subscribeUiState<T>(bridge: IUiBridge): IUiStateMirror<T> { … }",
5132
+ "situations": [
5133
+ "read game state from a HUD that runs in the platform's web view",
5134
+ "read published game state from a UI HUD",
5135
+ "subscribe a web or native UI to the game's mirrored state"
5136
+ ],
5137
+ "summary": "Mirror the game's published state on the UI side.",
5138
+ "supersedes": [],
5139
+ "symbol": "subscribeUiState"
5140
+ },
5141
+ {
5142
+ "aliases": [],
5143
+ "constraints": [],
5144
+ "example": "serveWorkerGame(game);",
5145
+ "importPath": "@threenative/core/worker",
5146
+ "kind": "function",
5147
+ "overrides": [],
5148
+ "package": "@threenative/core",
5149
+ "signature": "export function serveWorkerGame( game: { … }",
5150
+ "situations": ["run the game loop in a web worker so a busy page cannot stall its frames"],
5151
+ "summary": "Runs inside the worker: wire the page's messages to the unchanged portable game. Call it last in the worker entry, after the game module evaluated: it posts the ready message the page waits for before it sends the canvas.",
5152
+ "supersedes": [],
5153
+ "symbol": "serveWorkerGame"
5154
+ },
5155
+ {
5156
+ "aliases": [],
5157
+ "constraints": [],
5158
+ "example": "const handle = startWorkerGame(new Worker(new URL(\"./worker.ts\", import.meta.url), { type: \"module\" }), root);",
5159
+ "importPath": "@threenative/core/worker",
5160
+ "kind": "function",
5161
+ "overrides": [],
5162
+ "package": "@threenative/core",
5163
+ "signature": "export function startWorkerGame( worker: Worker, container: HTMLElement, ): { … }",
5164
+ "situations": ["host a worker-run game's canvas, input and HUD on the page"],
5165
+ "summary": "Runs on the page: own the canvas and the DOM, and feed the worker game. Call it before the UI mounts: the HUD's bridge host globals exist from this call on.",
5166
+ "supersedes": [],
5167
+ "symbol": "startWorkerGame"
5168
+ },
5169
+ {
5170
+ "aliases": [],
5171
+ "constraints": [
5172
+ "open a new budget each frame; a unit always finishes, so one unit can cross the limit"
5173
+ ],
5174
+ "example": "tiles.follow(player.position, new AdmissionBudget(2, () => performance.now()));",
5175
+ "importPath": "@threenative/core/world",
5176
+ "kind": "class",
5177
+ "overrides": [],
5178
+ "package": "@threenative/core",
5179
+ "signature": "export class AdmissionBudget implements IAdmissionBudget { … }",
5180
+ "situations": [
5181
+ "streamed terrain tiles or cells hitch the frame that admits them",
5182
+ "cap how many milliseconds a frame spends building streamed content"
5183
+ ],
5184
+ "summary": "One frame's admission allowance, shared by every path that puts streamed content on screen. A streaming world has no frame-time ceiling anywhere else: a cell row arriving builds a batch per asset run over every placement in it, a terrain tile builds every LOD level, and the game's `createCollider` runs for every resident tile — all in the one frame that discovers them. That is the 100-330 ms hitch a 60 m/s camera feels every time the ring moves, and it is admission cost, not streaming: the loads never fail. The budget is opened once per `update` and drawn down by the units it admits. A unit always finishes, so a frame spends at most the limit plus the unit that crossed it, and the rest of the backlog waits for the next frame rather than being dropped.",
5185
+ "supersedes": [],
5186
+ "symbol": "AdmissionBudget"
5187
+ },
5188
+ {
5189
+ "aliases": [],
5190
+ "constraints": [
5191
+ "url names the loaded GLB; tnTerrainSurface extras name a relative world package JSON"
5192
+ ],
5193
+ "example": "await applyTerrainSurface(world.scene, { assets: ctx.assets, renderer: ctx.renderer, url: \"world/world.glb\" });",
5194
+ "importPath": "@threenative/core/world",
5195
+ "kind": "function",
5196
+ "overrides": [
5197
+ "`table` may replace `base`, `breakup`, `macro` and `layers`; baked `splat` and `textures` stay package-owned"
5198
+ ],
5199
+ "package": "@threenative/core",
5200
+ "signature": "export async function applyTerrainSurface( root: Object3D, options: ILoadTerrainSplatOptions, ): Promise<void> { … }",
5201
+ "situations": ["apply the authored layered terrain surface after loading a cooked world GLB"],
5202
+ "summary": "Apply a cooked GLB's package-authored layered surface to its marked terrain meshes. `url` is the loaded GLB URL; extras pointers are relative to it. Uses the same asset/fetch path as loadTerrainSplat on web and native. The caller owns the assigned materials' lifetime.",
5203
+ "supersedes": [],
5204
+ "symbol": "applyTerrainSurface"
5205
+ },
5206
+ {
5207
+ "aliases": [],
5208
+ "constraints": ["octaves is a build-time number; each octave is one filtered volume read"],
5209
+ "example": "const macro = bakedFractalNoise(vec3(positionWorld.x, 0, positionWorld.z).mul(0.014), 3);",
5210
+ "importPath": "@threenative/core/world",
5211
+ "kind": "function",
5212
+ "overrides": [],
5213
+ "package": "@threenative/core",
5214
+ "signature": "export function bakedFractalNoise( p: Node<\"vec3\">, octaves = 3, lacunarity = 2, diminish = 0.5, amplitude: Scalar = 1, ): Node<\"float\"> { … }",
5215
+ "situations": ["fractal or fbm noise in a material costs too much GPU time per pixel"],
5216
+ "summary": "Drop-in for `mx_fractal_noise_float(p, octaves, lacunarity, diminish, amplitude)`: one read an octave.",
5217
+ "supersedes": [],
5218
+ "symbol": "bakedFractalNoise"
5219
+ },
5220
+ {
5221
+ "aliases": [],
5222
+ "constraints": [
5223
+ "the field tiles every NOISE_PERIOD units of p; at p = world metres x 2.6 that is a 3 m repeat",
5224
+ "vec3 input only: three's 2D Perlin is another function"
5225
+ ],
5226
+ "example": "const patch = smoothstep(-0.35, 0.35, bakedNoise(positionWorld.mul(0.025)));",
5227
+ "importPath": "@threenative/core/world",
5228
+ "kind": "function",
5229
+ "overrides": ["keep mx_noise_float where exact analytic noise matters more than the frame"],
5230
+ "package": "@threenative/core",
5231
+ "signature": "export function bakedNoise( p: Node<\"vec3\">, amplitude: Scalar = 1, pivot: Scalar = 0, channel: 0 | 1 | 2 | 3 = 0, ): Node<\"float\"> { … }",
5232
+ "situations": [
5233
+ "a terrain, foliage or water shader calls mx_noise_float per pixel and the frame is GPU bound",
5234
+ "open world ground material with procedural variation that must hold 60 FPS"
5235
+ ],
5236
+ "summary": "Drop-in for `mx_noise_float(p, amplitude, pivot)` on a vec3 `p`: one filtered read of the baked volume instead of the per-pixel Perlin. Only the 3D form: three's 2D Perlin is another function (0.66 scale), so a vec2 caller keeps `mx_noise_float`. `channel` 1 to 3 are independent fields.",
5237
+ "supersedes": [],
5238
+ "symbol": "bakedNoise"
5239
+ },
5240
+ {
5241
+ "aliases": [],
5242
+ "constraints": [
5243
+ "throws `TN_STATIC_POSE_GROUND` where the ground does not answer; check `samples` before trusting `gap`"
5244
+ ],
5245
+ "example": "const ring = baseRingGap(geometry, matrix, ground); if (ring.samples >= 4) matrix.elements[13] -= ring.gap + 0.5;",
5246
+ "importPath": "@threenative/core/world",
5247
+ "kind": "function",
5248
+ "overrides": [],
5249
+ "package": "@threenative/core",
5250
+ "signature": "export function baseRingGap( geometry: BufferGeometry, matrix: Matrix4, ground: StaticGroundQuery, options: { … }",
5251
+ "situations": [
5252
+ "a cliff or crag model rests on a buried stem while its wide base hangs over the downhill ground"
5253
+ ],
5254
+ "summary": "The highest gap between a wide model's rim and the ground, one sample per angular sector: in each sector, the lowest vertex beyond `rim` of that sector's reach. A narrow buried stem then cannot hold a wide base up in the air on the downhill side. Sink the pose by `gap` (plus any burial the game wants) to close it.",
5255
+ "supersedes": [],
5256
+ "symbol": "baseRingGap"
5257
+ },
5258
+ {
5259
+ "aliases": [],
5260
+ "constraints": [
5261
+ "the returned view aliases the caller's buffer; writing to it mutates the source"
5262
+ ],
5263
+ "example": "const records = cellPlacements(buffer, { asset: \"tree\", offset: 0, count: 120 });",
5264
+ "importPath": "@threenative/core/world",
5265
+ "kind": "function",
5266
+ "overrides": [],
5267
+ "package": "@threenative/core",
5268
+ "signature": "export function cellPlacements(placements: ArrayBuffer, run: IWorldRun): Float32Array { … }",
5269
+ "situations": ["feed one cell's instance transforms into a batch without copying"],
5270
+ "summary": "Borrow the run's placement records as a live view over the placement buffer.",
5271
+ "supersedes": [],
5272
+ "symbol": "cellPlacements"
5273
+ },
5274
+ {
5275
+ "aliases": [],
5276
+ "constraints": [
5277
+ "the footprint is every vertex at the geometry's lowest local y; throws `TN_STATIC_POSE_GROUND` where the ground does not answer"
5278
+ ],
5279
+ "example": "matrix.elements[13] -= footprintGap(geometry, matrix, ground, 0.08);",
5280
+ "importPath": "@threenative/core/world",
5281
+ "kind": "function",
5282
+ "overrides": [],
5283
+ "package": "@threenative/core",
5284
+ "signature": "export function footprintGap( geometry: BufferGeometry, matrix: Matrix4, ground: StaticGroundQuery, margin = 0, ): number { … }",
5285
+ "situations": ["a rock snapped to a slope shows a lip or a gap under its downhill side"],
5286
+ "summary": "How far the flat underside of a static geometry rises above the ground at its highest point. Snapping the lowest point leaves the downhill side of a flat-bottomed rock hanging; sinking the pose by this much buries the whole footprint. Returns 0 when the footprint is already buried.",
5287
+ "supersedes": [],
5288
+ "symbol": "footprintGap"
5289
+ },
5290
+ {
5291
+ "aliases": [],
5292
+ "constraints": [
5293
+ "unsupported is returned when compute limits are unknown or below the requirement; callers must not silently continue"
5294
+ ],
5295
+ "example": "const capabilities = getWorldCapabilities({ limits: adapter.limits, cpuFallbackIterations: 8 });",
5296
+ "importPath": "@threenative/core/world",
5297
+ "kind": "function",
5298
+ "overrides": [
5299
+ "minimumWorkgroupsPerDimension, minimumStorageBufferBindingSize, and cpuFallbackIterations"
5300
+ ],
5301
+ "package": "@threenative/core",
5302
+ "signature": "export function getWorldCapabilities(options: IWorldCapabilitiesOptions = { … }",
5303
+ "situations": [
5304
+ "decide whether generated terrain can use GPU compute",
4432
5305
  "report why terrain generation is using a reduced CPU fallback"
4433
5306
  ],
4434
5307
  "summary": "Resolve the active world-generation path from host capability facts. The function accepts the adapter facts instead of reaching through a renderer-specific global, so browser and native hosts can report the same object. Missing limits are not treated as infinite: a host must either provide a valid GPU limit report or explicitly choose CPU fallback. GPU generation remains unavailable until a GPU readback can own the canonical field; a host adapter report therefore never upgrades a CPU fallback into a GPU generation claim.",
@@ -4461,6 +5334,26 @@
4461
5334
  "supersedes": [],
4462
5335
  "symbol": "Heightfield"
4463
5336
  },
5337
+ {
5338
+ "aliases": [],
5339
+ "constraints": [
5340
+ "every ring vertex asks the game's `height` callback; core owns no terrain look",
5341
+ "the collar is a ring of triangles, not a field: `heightAt` answers on it and null off it"
5342
+ ],
5343
+ "example": "const collar = new HeightfieldCollar({ resolution: 129, size: 512, rings: 384, ringDistance: (ring) => (ring / 384) ** 1.65 * 2100, walkBand: 200, height: ({ x, z }) => surveyed.heightAt(x, z) });",
5344
+ "importPath": "@threenative/core/world",
5345
+ "kind": "class",
5346
+ "overrides": [],
5347
+ "package": "@threenative/core",
5348
+ "signature": "export class HeightfieldCollar { … }",
5349
+ "situations": [
5350
+ "draw the terrain past the playable square without hand-building a ring grid",
5351
+ "ground a character past the square, out to the walk band, on drawn triangles"
5352
+ ],
5353
+ "summary": "A heightfield's far ring: `rings` square rings past its playable square, one vertex per boundary sample, and the index grid that draws them.",
5354
+ "supersedes": [],
5355
+ "symbol": "HeightfieldCollar"
5356
+ },
4464
5357
  {
4465
5358
  "aliases": [],
4466
5359
  "constraints": [
@@ -4480,6 +5373,56 @@
4480
5373
  "supersedes": [],
4481
5374
  "symbol": "heightSamplerFromHeightmap"
4482
5375
  },
5376
+ {
5377
+ "aliases": [],
5378
+ "constraints": [],
5379
+ "example": "const phase = instanceRandom().mul(6.2831);",
5380
+ "importPath": "@threenative/core/world",
5381
+ "kind": "function",
5382
+ "overrides": [],
5383
+ "package": "@threenative/core",
5384
+ "signature": "export function instanceRandom(): Node<\"float\"> { … }",
5385
+ "situations": [
5386
+ "a per-instance random number that stays with each streamed placement as WorldCells repacks",
5387
+ "replace instanceIndex in a WorldCells part material, which WorldCells refuses"
5388
+ ],
5389
+ "summary": "A random in [0, 1) that stays with its instance, as UE 5.8.3's PerInstanceRandom: hashed from the instance's world origin, never from its draw slot. WorldCells repacks instances on every refilter, main-pass cull and LOD switch, so `instanceIndex` names another tree from one frame to the next; a wind phase hashed from it re-rolled each crown about every 0.7 s of a walk and snapped its top by a median 0.37 m. Parts of one placement share its translation, so its bark and needles read one value.",
5390
+ "supersedes": [],
5391
+ "symbol": "instanceRandom"
5392
+ },
5393
+ {
5394
+ "aliases": [],
5395
+ "constraints": ["reads the heightfield at every bearing, once per lake, never per frame"],
5396
+ "example": "const reach = lakeReach(field, { ...lake, margin: 1.12 });",
5397
+ "importPath": "@threenative/core/world",
5398
+ "kind": "function",
5399
+ "overrides": [],
5400
+ "package": "@threenative/core",
5401
+ "signature": "export function lakeReach(field: Heightfield, lake: IWaterLake): number { … }",
5402
+ "situations": ["size a lake's footprint from its basin and the cap its biome row names"],
5403
+ "summary": "How far a lake's water reaches: the waterline its basin measures, `margin` times out, capped. The drawn surface and the swim footprint both size themselves here, so the shore a player sees is the shore they stop at.",
5404
+ "supersedes": [],
5405
+ "symbol": "lakeReach"
5406
+ },
5407
+ {
5408
+ "aliases": [],
5409
+ "constraints": [
5410
+ "the lake row and field come from the game's bake; the game's material shades the geometry"
5411
+ ],
5412
+ "example": "const geometry = lakeSurfaceGeometry({ ...lake, margin: 1.12 }, field, { maxDepth: 1.6 });",
5413
+ "importPath": "@threenative/core/world",
5414
+ "kind": "function",
5415
+ "overrides": [],
5416
+ "package": "@threenative/core",
5417
+ "signature": "export function lakeSurfaceGeometry( lake: IWaterLake, field: Heightfield, options: ILakeSurfaceOptions = { … }",
5418
+ "situations": [
5419
+ "draw a lake's water surface from the baked level and seed",
5420
+ "a lake's drawn water and the swimmer's water disagree"
5421
+ ],
5422
+ "summary": "A lake's water surface: a level disc out to `lakeReach`, the footprint `WaterBodies` floods, with a `metres` attribute (water depth over the ground). Only cells with water at a corner get triangles, so the surface does not hover over dry hillside and the shore follows the ground's contour. The rings pack towards the middle, so an irregular basin costs vertices where the camera sees them. Returns `undefined` when the basin holds no water at its level.",
5423
+ "supersedes": [],
5424
+ "symbol": "lakeSurfaceGeometry"
5425
+ },
4483
5426
  {
4484
5427
  "aliases": [],
4485
5428
  "constraints": [
@@ -4490,7 +5433,7 @@
4490
5433
  "importPath": "@threenative/core/world",
4491
5434
  "kind": "function",
4492
5435
  "overrides": [
4493
- "every value comes from the package's table; the returned material is the game's to adjust"
5436
+ "`table` may replace `base`, `breakup`, `macro` and `layers` from game source; baked `splat` and `textures` stay package-owned"
4494
5437
  ],
4495
5438
  "package": "@threenative/core",
4496
5439
  "signature": "export async function loadTerrainSplat(options: ILoadTerrainSplatOptions): Promise<Material> { … }",
@@ -4516,6 +5459,113 @@
4516
5459
  "supersedes": [],
4517
5460
  "symbol": "loadWorldHeightmap"
4518
5461
  },
5462
+ {
5463
+ "aliases": [],
5464
+ "constraints": [
5465
+ "a section's `material` can be `undefined` for a group naming a missing material slot; skip it"
5466
+ ],
5467
+ "example": "for (const section of meshSections(mesh)) parts.push(sectionGeometry(mesh, box, section));",
5468
+ "importPath": "@threenative/core/world",
5469
+ "kind": "function",
5470
+ "overrides": [],
5471
+ "package": "@threenative/core",
5472
+ "signature": "export function meshSections(mesh: Mesh): IMeshSection[] { … }",
5473
+ "situations": ["scatter or instance an imported glTF model that has several materials"],
5474
+ "summary": "A mesh's material sections: one per geometry group for a material array, else the whole mesh. Instanced props draw one batch per material, so an imported model splits here first.",
5475
+ "supersedes": [],
5476
+ "symbol": "meshSections"
5477
+ },
5478
+ {
5479
+ "aliases": [],
5480
+ "constraints": [
5481
+ "baked once per page on the main thread (about 0.15 s); every channel is an independent field"
5482
+ ],
5483
+ "example": "const volume = noiseVolume();",
5484
+ "importPath": "@threenative/core/world",
5485
+ "kind": "function",
5486
+ "overrides": [],
5487
+ "package": "@threenative/core",
5488
+ "signature": "export function noiseVolume(): Data3DTexture { … }",
5489
+ "situations": ["a material needs the raw baked noise texture to sample in its own TSL"],
5490
+ "summary": "The one volume every material shares: baked on first use, 1 MiB of RGBA8 (it stays in L2).",
5491
+ "supersedes": [],
5492
+ "symbol": "noiseVolume"
5493
+ },
5494
+ {
5495
+ "aliases": [],
5496
+ "constraints": [
5497
+ "one bad normal recomputes them all; an intentionally hard-edged model loses its authored split normals only if one is bad"
5498
+ ],
5499
+ "example": "geometry.scale(1.1, 1, 1.1); repairZeroNormals(geometry);",
5500
+ "importPath": "@threenative/core/world",
5501
+ "kind": "function",
5502
+ "overrides": [],
5503
+ "package": "@threenative/core",
5504
+ "signature": "export function repairZeroNormals(geometry: BufferGeometry): boolean { … }",
5505
+ "situations": ["an imported model draws black or unlit because it ships zero normals"],
5506
+ "summary": "Recompute the normals of a geometry whose normals are missing, zero or not finite, and leave authored normals alone. Some exported art ships zero normals and draws black under any light. Run it after any reshape, so the recomputed normals fit the final shape.",
5507
+ "supersedes": [],
5508
+ "symbol": "repairZeroNormals"
5509
+ },
5510
+ {
5511
+ "aliases": [],
5512
+ "constraints": [
5513
+ "stations, width and reach come from the game's bake; the game's material shades the geometry"
5514
+ ],
5515
+ "example": "const geometry = riverRibbonGeometry(rivers, field, { maxDepth: 1.6 });",
5516
+ "importPath": "@threenative/core/world",
5517
+ "kind": "function",
5518
+ "overrides": [],
5519
+ "package": "@threenative/core",
5520
+ "signature": "export function riverRibbonGeometry( rivers: readonly { … }",
5521
+ "situations": [
5522
+ "draw a river's water surface from the baked stations",
5523
+ "a river's water stops in a straight edge, or a swimmer floats where no water is drawn",
5524
+ "share one river shape between the drawn water and the swimmer",
5525
+ "river water hangs over dry ground past the river's head or tail"
5526
+ ],
5527
+ "summary": "The water surface of every river, as one geometry with one group per river. Each station is a row across the river at its own surface height, out to `reach` widths either side of the centreline, the reach `WaterBodies` floods; one more row a reach past each end stands where `WaterBodies` clamps a segment, so the water a swimmer finds past a river's end is drawn there too (cut at the end station, the surface stopped in a straight edge with its carved bed dry beyond). Quads dry on both rows against `field` are dropped, so the surface ends at the shore. Past an end where the ground falls below the end's bed, the water would run off: that cap is not drawn, and the end stays cut at its last station. Attributes for the game's water material: `flow` (the unit downstream heading), `flowUv` (metres down the centreline, metres across it) and `metres` (water depth over the ground). It decides no colour, ripple or opacity: the game shades it.",
5528
+ "supersedes": [],
5529
+ "symbol": "riverRibbonGeometry"
5530
+ },
5531
+ {
5532
+ "aliases": [],
5533
+ "constraints": [
5534
+ "`box` is the whole model's world bounds after any unit normalisation; call `mesh.updateWorldMatrix` first"
5535
+ ],
5536
+ "example": "const box = new Box3().setFromObject(root); const geometry = sectionGeometry(mesh, box, section);",
5537
+ "importPath": "@threenative/core/world",
5538
+ "kind": "function",
5539
+ "overrides": [],
5540
+ "package": "@threenative/core",
5541
+ "signature": "export function sectionGeometry( mesh: Mesh, box: Box3, section: IMeshSection, options: { … }",
5542
+ "situations": [
5543
+ "the crown of an instanced tree floats off its trunk, or the parts of a model separate",
5544
+ "turn each part of an imported model into a geometry for an instanced prop batch"
5545
+ ],
5546
+ "summary": "One section's geometry in model space, standing on y = 0. Every section of a model takes the same base from the whole model's `box`, so a crown keeps its place on its trunk: basing each section on its own bounds detaches them. The mesh's LOD0 geometry is cloned under its world matrix, and a group becomes the clone's draw range.",
5547
+ "supersedes": [],
5548
+ "symbol": "sectionGeometry"
5549
+ },
5550
+ {
5551
+ "aliases": [],
5552
+ "constraints": [
5553
+ "heights are row-major, `resolution` by `resolution`, across `size` metres; measured once, never per frame"
5554
+ ],
5555
+ "example": "const { distance, exposed } = shoreField(world.heights, world.resolution, world.size, world.waterLevel);",
5556
+ "importPath": "@threenative/core/world",
5557
+ "kind": "function",
5558
+ "overrides": [],
5559
+ "package": "@threenative/core",
5560
+ "signature": "export function shoreField( heights: ArrayLike<number>, resolution: number, size: number, level: number, options: IShoreFieldOptions = { … }",
5561
+ "situations": [
5562
+ "surf breaks only on water open to the sea, not in a sheltered lagoon",
5563
+ "distance from each water cell to the shore, for a foam or depth mask"
5564
+ ],
5565
+ "summary": "Distance to the shore and open-sea exposure for every node of a square height grid, measured once from the bake. `distance` is a two-pass chamfer distance to the nearest node at or above `level` (0 on dry ground). `exposed` floods from the grid's edge through water deeper than `openDepth`, then `carry` metres further into shallow water, so a sheltered lagoon behind a sand bar stays out of it. Both feed the game's surf and shore masks; neither decides a colour.",
5566
+ "supersedes": [],
5567
+ "symbol": "shoreField"
5568
+ },
4519
5569
  {
4520
5570
  "aliases": [],
4521
5571
  "constraints": ["radius is metres; the footprint never grows with load, only deeper"],
@@ -4551,6 +5601,7 @@
4551
5601
  "signature": "export class SnowField { … }",
4552
5602
  "situations": [
4553
5603
  "leave footprints, tracks and tyre ruts in snow that persist and fill in over time",
5604
+ "let a fresh snowfall slowly fill older tracks back in as the field recovers",
4554
5605
  "let a pushed sphere carve a connected track and a dropped one settle into a crater",
4555
5606
  "store snow deformation that rendered geometry and collision both read",
4556
5607
  "reset a snowfield between rounds or change its depth at runtime",
@@ -4560,6 +5611,44 @@
4560
5611
  "supersedes": [],
4561
5612
  "symbol": "SnowField"
4562
5613
  },
5614
+ {
5615
+ "aliases": [],
5616
+ "constraints": [
5617
+ "static geometry only; a skinned model uses `GroundSnap`; the sort is cached per geometry, so do not mutate its positions"
5618
+ ],
5619
+ "example": "placed.position.y += ground - staticLowestY(geometry, matrix);",
5620
+ "importPath": "@threenative/core/world",
5621
+ "kind": "function",
5622
+ "overrides": [],
5623
+ "package": "@threenative/core",
5624
+ "signature": "export function staticLowestY(geometry: BufferGeometry, matrix: Matrix4): number { … }",
5625
+ "situations": [
5626
+ "stand a scattered rock, tree or crate on the ground by its lowest point, not its origin",
5627
+ "props hover or sink because their pivot is not at their base"
5628
+ ],
5629
+ "summary": "Exact lowest world Y of a static geometry under `matrix`, the precise measurement `GroundSnap` audits against, cheap enough for a load that poses hundreds of thousands of props. An upright pose reads the bounding box. A tilted pose scans the vertices bottom first (sorted once per geometry) and stops once no later vertex can be lower: `|x e1 + z e9| <= reach * hypot(e1, e9)`.",
5630
+ "supersedes": [],
5631
+ "symbol": "staticLowestY"
5632
+ },
5633
+ {
5634
+ "aliases": [],
5635
+ "constraints": [
5636
+ "the mesh is `field.toGeometry()` drawn upright under a uniform scale; read `matrixWorld` after it settles"
5637
+ ],
5638
+ "example": "const ground = surfaceSampler(field, mesh.matrixWorld); const y = ground(x, z) ?? fallback;",
5639
+ "importPath": "@threenative/core/world",
5640
+ "kind": "function",
5641
+ "overrides": [],
5642
+ "package": "@threenative/core",
5643
+ "signature": "export function surfaceSampler(field: Heightfield, matrixWorld: Matrix4): SurfaceSampler { … }",
5644
+ "situations": [
5645
+ "stand props or a player on the drawn terrain triangles under a moved or scaled mesh",
5646
+ "props float or sink where the terrain mesh is drawn under a transform"
5647
+ ],
5648
+ "summary": "`Heightfield.surfaceAt` under the transform the game draws the field's mesh with, so a prop or a player stands on the triangles the eye sees rather than on the bilinear field between them. Answers `null` outside the field and for a transform it does not model (any rotation, or an unequal scale), so the caller keeps its own fallback there.",
5649
+ "supersedes": [],
5650
+ "symbol": "surfaceSampler"
5651
+ },
4563
5652
  {
4564
5653
  "aliases": ["stream terrain across chunks"],
4565
5654
  "constraints": [
@@ -4578,7 +5667,9 @@
4578
5667
  "situations": [
4579
5668
  "stream terrain without cracks",
4580
5669
  "keep generated terrain resident around a moving player",
4581
- "put a generated terrain tile into a game-owned physics world"
5670
+ "put a generated terrain tile into a game-owned physics world",
5671
+ "a hole or a flicker where streamed terrain tiles are still building (`settledHalf`)",
5672
+ "split the ground between streamed tiles and a far mesh around the player (`settledHalf`)"
4582
5673
  ],
4583
5674
  "summary": "Stream a bounded square of game-authored heightfields and keep their render and physics units together. The class composes ordinary THREE.LOD objects and leaves frustum/projection culling to the renderer's existing scene path.",
4584
5675
  "supersedes": [],
@@ -4611,14 +5702,71 @@
4611
5702
  "kind": "function",
4612
5703
  "overrides": [],
4613
5704
  "package": "@threenative/core",
4614
- "signature": "export function validateWorldPackage( manifest: unknown, options: IWorldPackageValidationOptions, ): { … }",
5705
+ "signature": "export function validateWorldPackage( manifest: unknown, options: IWorldPackageValidationOptions, ): { … }",
5706
+ "situations": [
5707
+ "check a Blender-exported world package before the runtime attaches anything",
5708
+ "report why a world package cannot be streamed"
5709
+ ],
5710
+ "summary": "Validate a `world.json` manifest against the v1 contract. Never throws on garbage input: a non-object manifest is `WORLD_MALFORMED`. Every problem is collected, so an exporter sees the complete list at once.",
5711
+ "supersedes": [],
5712
+ "symbol": "validateWorldPackage"
5713
+ },
5714
+ {
5715
+ "aliases": [],
5716
+ "constraints": [
5717
+ "`ctx.beforeRender` runs on every world draw, also behind the curtain; join the promise to the curtain's hold"
5718
+ ],
5719
+ "example": "const warm = warmUnculled(ctx, lake.mesh); ctx.startup.hold(\"lake\", () => warm);",
5720
+ "importPath": "@threenative/core/world",
5721
+ "kind": "function",
5722
+ "overrides": [],
5723
+ "package": "@threenative/core",
5724
+ "signature": "export function warmUnculled( ctx: { … }",
5725
+ "situations": [
5726
+ "the first frames after the loading curtain hitch on pipeline builds for content behind the camera",
5727
+ "streamed terrain or a lake compiles its pipelines after the reveal"
5728
+ ],
5729
+ "summary": "Draw `root` with frustum culling off until it has drawn `draws` times, then cull it again and resolve. A pipeline is built by its first real draw (a startup warm-up compiles a different pass), so content the spawn view does not see — streamed tiles behind the player, a mirror that draws only when its water does — builds its pipelines after the reveal and hitches the first frames that see it. Join the promise to the loading curtain to build them behind it. Objects that join `root` while it warms draw unculled too.",
5730
+ "supersedes": [],
5731
+ "symbol": "warmUnculled"
5732
+ },
5733
+ {
5734
+ "aliases": [],
5735
+ "constraints": [
5736
+ "every station, level, extent and speed comes from the game's own bake; a lake is measured on the field passed in"
5737
+ ],
5738
+ "example": "const water = new WaterBodies({ ribbons, lakes, field }); const height = water.surfaceAt(x, z);",
5739
+ "importPath": "@threenative/core/world",
5740
+ "kind": "class",
5741
+ "overrides": [],
5742
+ "package": "@threenative/core",
5743
+ "signature": "export class WaterBodies { … }",
5744
+ "situations": [
5745
+ "ask how high the water is where a player swims",
5746
+ "ask which way a current carries a body",
5747
+ "ask which water body covers a point, and how high its surface is",
5748
+ "share one water store between rendering and physics"
5749
+ ],
5750
+ "summary": "One world's water, queried: surface height, current and footprint from the baked arrays. Rendering and physics read the same store, as they do for `Heightfield`, so the surface a player sees and the surface a swimmer rests on cannot disagree. Every station, level, extent and speed comes from the game, and the shading stays in the game's own `src/render/`. A river's segments sit in a uniform grid, so a query tests the few that can reach its cell instead of every station of every river.",
5751
+ "supersedes": [],
5752
+ "symbol": "WaterBodies"
5753
+ },
5754
+ {
5755
+ "aliases": [],
5756
+ "constraints": ["returns metres on the furthest bearing; the caller applies its own cap"],
5757
+ "example": "const reach = waterlineRadius(field, lake.at, lake.level) * 1.12;",
5758
+ "importPath": "@threenative/core/world",
5759
+ "kind": "function",
5760
+ "overrides": [],
5761
+ "package": "@threenative/core",
5762
+ "signature": "export function waterlineRadius( field: Heightfield, centre: readonly number[], level: number, ): number { … }",
4615
5763
  "situations": [
4616
- "check a Blender-exported world package before the runtime attaches anything",
4617
- "report why a world package cannot be streamed"
5764
+ "measure where a lake's water meets the ground it floods",
5765
+ "size a lake's drawn surface or the footprint a swimmer may enter"
4618
5766
  ],
4619
- "summary": "Validate a `world.json` manifest against the v1 contract. Never throws on garbage input: a non-object manifest is `WORLD_MALFORMED`. Every problem is collected, so an exporter sees the complete list at once.",
5767
+ "summary": "The furthest a lake's basin reaches on a bearing: where the drawn ground crosses its level. Twenty-four bearings step outwards and stop at the first bank, because binary-searching the whole ray can jump a dry ridge into another pond. Eighteen halvings land inside two centimetres at this scale, well under the ground's own sample spacing.",
4620
5768
  "supersedes": [],
4621
- "symbol": "validateWorldPackage"
5769
+ "symbol": "waterlineRadius"
4622
5770
  },
4623
5771
  {
4624
5772
  "aliases": [],
@@ -4626,8 +5774,10 @@
4626
5774
  "surface is the game's; this class creates no material, colour or geometry",
4627
5775
  "a cell's model loads at `soon` priority, so a file the running scene awaits through `ctx.assets` starts first",
4628
5776
  "budgets are hard caps that report pressure instead of over-committing",
5777
+ "`whenSpawnReady(position, radius, timeoutMs)` snapshots a fixed region and settles from existing updates or disposal; it does not drive streaming, and `prewarmed` remains the separate draw gate",
4629
5778
  "model loads are bounded by `concurrency` (default 12) across every resident cell, not per cell",
4630
5779
  "refilters are bounded by `rebuildsPerUpdate` (default 16) per update, nearest cell first",
5780
+ "residency and `placementReach` follow `follow`; levels and `maxDistance` are graded from the render camera, as UE picks instance LODs per view; `lodFrom: \"follow\"`, `?tnLodFromCamera=0` or `TN_LOD_FROM_CAMERA=0` grade from `follow`, reported as `TN_WORLD_MAIN_CULL lodFrom=`",
4631
5781
  "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",
4632
5782
  "SkinnedMesh parts are skipped; an instanced copy would draw one rest pose",
4633
5783
  "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",
@@ -4643,7 +5793,7 @@
4643
5793
  "importPath": "@threenative/core/world",
4644
5794
  "kind": "class",
4645
5795
  "overrides": [
4646
- "`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"
5796
+ "`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; `impostorFar: \"always\"` keeps the far aggregate the near ring's guaranteed radius made unnecessary"
4647
5797
  ],
4648
5798
  "package": "@threenative/core",
4649
5799
  "signature": "export class WorldCells extends Group implements IComputeDriven { … }",
@@ -4878,22 +6028,31 @@
4878
6028
  "enemy targets cooldown reload win condition",
4879
6029
  "platformer double jump",
4880
6030
  "first person",
4881
- "run jump coins goal"
6031
+ "run jump coins goal",
6032
+ "swimming buoyancy water volume wade"
6033
+ ],
6034
+ "constraints": [
6035
+ "use moveAndSlide inside the physics update",
6036
+ "pass `water: (x, z) => surfaceHeight | undefined`; the body reads `swimming`, `immersionDepth` and `waterSurface` each moveAndSlide",
6037
+ "pass `waterCurrent: (x, z) => { x, z } | undefined` in m/s to have the water carry the body; it reads `currentVelocity` back"
4882
6038
  ],
4883
- "constraints": ["use moveAndSlide inside the physics update"],
4884
6039
  "deprecated": [
4885
6040
  "Constructor option `world` is deprecated; pass an IPhysicsContext as `physics` instead. CharacterBody3D itself is not deprecated."
4886
6041
  ],
4887
6042
  "example": "const body = new CharacterBody3D({ object: hero, physics: ctx.physics, shape: CollisionShape3D.capsule(0.5, 0.35) });",
4888
6043
  "importPath": "@threenative/physics",
4889
6044
  "kind": "class",
4890
- "overrides": [],
6045
+ "overrides": [
6046
+ "buoyancy (1.6, floats; Unreal 1.0 sinks), maxSwimSpeed (3 m/s) and fluidFriction (12) tune the Unreal MOVE_Swimming defaults"
6047
+ ],
4891
6048
  "package": "@threenative/physics",
4892
6049
  "requires": ["npm i @threenative/physics"],
4893
6050
  "signature": "export class CharacterBody3D { … }",
4894
6051
  "situations": [
4895
6052
  "move an enemy or player through a level",
4896
- "keep a character from walking through walls"
6053
+ "keep a character from walking through walls",
6054
+ "swim in a river, lake or sea; float at the surface and wade slower in shallow water",
6055
+ "river current carries a swimmer downstream while it floats"
4897
6056
  ],
4898
6057
  "summary": "Move a character body with collision-aware sliding.",
4899
6058
  "supersedes": [],
@@ -4982,7 +6141,10 @@
4982
6141
  },
4983
6142
  {
4984
6143
  "aliases": [],
4985
- "constraints": ["place rapier() before recast() in the plugin list"],
6144
+ "constraints": [
6145
+ "place rapier() before recast() in the plugin list",
6146
+ "ctx.physics is set before Scene.enter(), not during load(): Rapier initializes while the scene loads, so create bodies in enter() or later (TN_PHYSICS_NOT_READY)"
6147
+ ],
4986
6148
  "example": "const game = defineGame({ plugins: [rapier()] });",
4987
6149
  "importPath": "@threenative/physics",
4988
6150
  "kind": "function",
@@ -5015,6 +6177,7 @@
5015
6177
  "signature": "export class RigidBody3D { … }",
5016
6178
  "situations": [
5017
6179
  "give a crate or prop physical motion",
6180
+ "a ball rolls across the floor",
5018
6181
  "create a body that collides with a character",
5019
6182
  "fire physical cannonballs that collide with ships or scenery",
5020
6183
  "fire a cannonball projectile with cannon smoke particles",
@@ -5024,6 +6187,28 @@
5024
6187
  "supersedes": [],
5025
6188
  "symbol": "RigidBody3D"
5026
6189
  },
6190
+ {
6191
+ "aliases": [],
6192
+ "constraints": [
6193
+ "pass each instance's solid part (stone, bark), not its leaves; shapes are measured: a slender base is a trunk capsule, the rest an 18-DOP hull, and pieces under 0.25 m get none",
6194
+ "call update() every frame; it rescans only after the follow point moves a quarter of `radius` (default 40 m)",
6195
+ "`collision: \"hull\" | \"trunk\" | \"none\"` on an instance overrides the measured shape"
6196
+ ],
6197
+ "example": "const solids = new ScatterColliders({ physics: ctx.physics, follow: player, collisionLayer: 4, instances: rocks.map((matrix) => ({ geometry: rockGeometry, matrix })) });",
6198
+ "importPath": "@threenative/physics",
6199
+ "kind": "class",
6200
+ "overrides": [],
6201
+ "package": "@threenative/physics",
6202
+ "requires": ["npm i @threenative/physics"],
6203
+ "signature": "export class ScatterColliders { … }",
6204
+ "situations": [
6205
+ "stop the player walking through scattered rocks and trees",
6206
+ "give instanced or streamed foliage props collision in an open world"
6207
+ ],
6208
+ "summary": "Make scattered props solid: fixed bodies for rocks and trunks near a followed point, streamed with it.",
6209
+ "supersedes": [],
6210
+ "symbol": "ScatterColliders"
6211
+ },
5027
6212
  {
5028
6213
  "aliases": [],
5029
6214
  "constraints": [
@@ -5666,6 +6851,22 @@
5666
6851
  "supersedes": [],
5667
6852
  "symbol": "requestedPlaytestClockMode"
5668
6853
  },
6854
+ {
6855
+ "aliases": [],
6856
+ "constraints": [
6857
+ "an unreadable load is a refusal, not a silence: an unmeasured machine cannot vouch"
6858
+ ],
6859
+ "example": "import { absolutesVerdict, readHostLoad } from \"@threenative/playtest/runner\";\nconst load = readHostLoad();\nif (absolutesVerdict(load) === \"invalid-absolute\") ignoreAbsoluteMilliseconds();",
6860
+ "importPath": "@threenative/playtest/runner",
6861
+ "kind": "function",
6862
+ "overrides": [],
6863
+ "package": "@threenative/playtest",
6864
+ "signature": "export function absolutesVerdict(reading: IPerfHostLoadReading): IPerfHostLoad[\"absolutes\"] { … }",
6865
+ "situations": ["mark a benchmark run invalid because the machine was busy"],
6866
+ "summary": "The host-load reading and the rule that decides whether absolute milliseconds are trustworthy: absolutes are invalid once the one-minute load passes half the cores.",
6867
+ "supersedes": [],
6868
+ "symbol": "absolutesVerdict"
6869
+ },
5669
6870
  {
5670
6871
  "aliases": [],
5671
6872
  "constraints": ["Android evidence must name its target and transport"],
@@ -6374,6 +7575,22 @@
6374
7575
  "supersedes": [],
6375
7576
  "symbol": "preflightDisplay"
6376
7577
  },
7578
+ {
7579
+ "aliases": [],
7580
+ "constraints": [
7581
+ "an unreadable load is a refusal, not a silence: an unmeasured machine cannot vouch"
7582
+ ],
7583
+ "example": "import { absolutesVerdict, readHostLoad } from \"@threenative/playtest/runner\";\nconst load = readHostLoad();\nif (absolutesVerdict(load) === \"invalid-absolute\") ignoreAbsoluteMilliseconds();",
7584
+ "importPath": "@threenative/playtest/runner",
7585
+ "kind": "function",
7586
+ "overrides": [],
7587
+ "package": "@threenative/playtest",
7588
+ "signature": "export function readHostLoad( source: IPerfHostLoadSource = { … }",
7589
+ "situations": ["mark a benchmark run invalid because the machine was busy"],
7590
+ "summary": "The host-load reading and the rule that decides whether absolute milliseconds are trustworthy: absolutes are invalid once the one-minute load passes half the cores.",
7591
+ "supersedes": [],
7592
+ "symbol": "readHostLoad"
7593
+ },
6377
7594
  {
6378
7595
  "aliases": [],
6379
7596
  "constraints": [
@@ -6528,18 +7745,17 @@
6528
7745
  },
6529
7746
  {
6530
7747
  "aliases": [],
6531
- "constraints": ["the app bundle and device transport must be prepared"],
6532
- "example": "await runAndroidPlaytest(options);",
7748
+ "constraints": [
7749
+ "the driver must prepare the app bundle and the transport must answer the handshake"
7750
+ ],
7751
+ "example": "await runDevicePlaytest(config, { name: \"android\", driver, transport, processName, mailboxPaths });",
6533
7752
  "importPath": "@threenative/playtest/runner",
6534
7753
  "kind": "function",
6535
7754
  "overrides": [],
6536
7755
  "package": "@threenative/playtest",
6537
7756
  "signature": "export async function runDevicePlaytest( config: IStandalonePlaytestConfig, target: IDevicePlaytestTarget, ): Promise<IStandalonePlaytestReport> { … }",
6538
- "situations": [
6539
- "execute a scenario on an Android target",
6540
- "collect Android playtest artifacts"
6541
- ],
6542
- "summary": "Run a playtest on Android through the configured device transport.",
7757
+ "situations": ["execute a scenario on a device target with a custom driver"],
7758
+ "summary": "Run a playtest on any device lane (Android, desktop or iOS) through its driver and transport.",
6543
7759
  "supersedes": [],
6544
7760
  "symbol": "runDevicePlaytest"
6545
7761
  },
@@ -7543,6 +8759,30 @@
7543
8759
  "supersedes": [],
7544
8760
  "symbol": "applyPlacementOverrides"
7545
8761
  },
8762
+ {
8763
+ "aliases": [],
8764
+ "constraints": [
8765
+ "every instance's asset must be in `assets`; every instance must land in exactly one cell run"
8766
+ ],
8767
+ "example": "const baked = bakeBiome({ state: terrain.evaluate(), spec: validateBiome(json, \"savanna\"), assets });",
8768
+ "importPath": "@threenative/terrain",
8769
+ "kind": "function",
8770
+ "overrides": [],
8771
+ "package": "@threenative/terrain",
8772
+ "requires": ["npm i -D @threenative/terrain"],
8773
+ "signature": "export function bakeBiome(options: IBakeBiomeOptions): IBakedBiome { … }",
8774
+ "situations": [
8775
+ "bake one biome's world package from an evaluated recipe and a biome file",
8776
+ "generate terrain with mountains, hills, a river, a lake or an island from a request in words",
8777
+ "generate a landscape or open world map for a game",
8778
+ "procedural terrain for a level: a volcanic island, a mountain valley or a coast",
8779
+ "make a canyon, a volcano, a fjord, a desert, a tundra or a forest world",
8780
+ "cook the real terrain of a place on Earth from its latitude and longitude"
8781
+ ],
8782
+ "summary": "Bake one biome: the recipe's evaluated state and the world package it streams. This is the composition `terrain_generate` and a game's build script both call, so the file layout a player streams is decided in one place. The biome is validated first — an inline spec from a request is checked here, not trusted — and the package's own placement runs are checked against the state they came from, so a bake can never ship a cell list that lost instances. An agent does not write this call to get a world: the `threenative-terrain` MCP tool `terrain_generate` takes the request in words (\"a pine forest under snowy mountains with a river\", \"a volcanic island\", or `ground: { location }` for a real place) and cooks the world.glb, recipe.json and world.json a game loads with `ctx.assets.model`.",
8783
+ "supersedes": [],
8784
+ "symbol": "bakeBiome"
8785
+ },
7546
8786
  {
7547
8787
  "aliases": [],
7548
8788
  "constraints": [
@@ -7592,10 +8832,46 @@
7592
8832
  "requires": ["npm i -D @threenative/terrain"],
7593
8833
  "signature": "export function bakeWorldPackage( state: ITerrainState, options: IBakeWorldPackageOptions, ): IBakedWorldPackage { … }",
7594
8834
  "situations": ["hand an evaluated Strata terrain to a game without a Blender round trip"],
7595
- "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.",
8835
+ "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, a placement ID sidecar 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.",
7596
8836
  "supersedes": [],
7597
8837
  "symbol": "bakeWorldPackage"
7598
8838
  },
8839
+ {
8840
+ "aliases": [],
8841
+ "constraints": [
8842
+ "the collar decides where a tree stands; this sampler never resamples the square"
8843
+ ],
8844
+ "example": "const sampler = collarSampler(collar); const height = sampler.at(x, z);",
8845
+ "importPath": "@threenative/terrain",
8846
+ "kind": "function",
8847
+ "overrides": [],
8848
+ "package": "@threenative/terrain",
8849
+ "requires": ["npm i -D @threenative/terrain"],
8850
+ "signature": "export function collarSampler(collar: HeightfieldCollar) { … }",
8851
+ "situations": ["plant a far field on a drawn collar and paint the canopy its crowns cover"],
8852
+ "summary": "The collar's height at any (x, z), and a way to raise one of its per-vertex attributes at a placement: both read the collar's own quad grid, so a lane that reshapes the collar moves the trees with it.",
8853
+ "supersedes": [],
8854
+ "symbol": "collarSampler"
8855
+ },
8856
+ {
8857
+ "aliases": [],
8858
+ "constraints": [
8859
+ "headless; the caller decides every placement, its streamed world, its reach and its pose"
8860
+ ],
8861
+ "example": "const pkg = compilePropBuckets(entries, { bounds });",
8862
+ "importPath": "@threenative/terrain",
8863
+ "kind": "function",
8864
+ "overrides": ["cellSize and the base extent; the bucket, reach and kind of every entry"],
8865
+ "package": "@threenative/terrain",
8866
+ "requires": ["npm i -D @threenative/terrain"],
8867
+ "signature": "export function compilePropBuckets( entries: readonly IPropBucketEntry[], options: ICompilePropBucketsOptions = { … }",
8868
+ "situations": [
8869
+ "bake the prop worlds a game streams, once, instead of compiling them at load"
8870
+ ],
8871
+ "summary": "Group placements into their streamed worlds and write each world's cells and records. The order is the streamed one: cells sorted by `x` then `z`, assets sorted by name inside a cell, and records in the order the entries arrived inside a run. Same-cell, same-asset placements keep their input order, so a re-run of a seeded bake reproduces the buffer byte for byte.",
8872
+ "supersedes": [],
8873
+ "symbol": "compilePropBuckets"
8874
+ },
7599
8875
  {
7600
8876
  "aliases": [],
7601
8877
  "constraints": [
@@ -7631,6 +8907,25 @@
7631
8907
  "supersedes": [],
7632
8908
  "symbol": "decodeHeightPNG"
7633
8909
  },
8910
+ {
8911
+ "aliases": [],
8912
+ "constraints": [
8913
+ "throws `TN_PROP_BUCKET_INVALID` when the record buffer, the IDs and the runs disagree"
8914
+ ],
8915
+ "example": "for (const record of decodePropBucket(bucket)) pose(record.key, record.position, record.quaternion);",
8916
+ "importPath": "@threenative/terrain",
8917
+ "kind": "function",
8918
+ "overrides": [],
8919
+ "package": "@threenative/terrain",
8920
+ "requires": ["npm i -D @threenative/terrain"],
8921
+ "signature": "export function decodePropBucket(bucket: IPropBucketPackage): IPropBucketRecord[] { … }",
8922
+ "situations": [
8923
+ "read a baked prop bucket back into placements to ground them on this machine's terrain"
8924
+ ],
8925
+ "summary": "The records of one compiled prop bucket, read back in record order: the inverse of `compilePropBuckets`, so a loader that fetched a bake's files gets each record's ID, model, pose and reach without re-deriving the container layout.",
8926
+ "supersedes": [],
8927
+ "symbol": "decodePropBucket"
8928
+ },
7634
8929
  {
7635
8930
  "aliases": [],
7636
8931
  "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
@@ -7644,112 +8939,315 @@
7644
8939
  "situations": ["import a RAW16 terrain height buffer with explicit dimensions"],
7645
8940
  "summary": "Validates dimensions and range before decoding numerical height samples.",
7646
8941
  "supersedes": [],
7647
- "symbol": "decodeRAW16"
8942
+ "symbol": "decodeRAW16"
8943
+ },
8944
+ {
8945
+ "aliases": [],
8946
+ "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
8947
+ "example": "const glb = encodeGLB(bakeMesh(new Terrain({ resolution: 17 }).evaluate()));",
8948
+ "importPath": "@threenative/terrain",
8949
+ "kind": "function",
8950
+ "overrides": [],
8951
+ "package": "@threenative/terrain",
8952
+ "requires": ["npm i @threenative/terrain"],
8953
+ "signature": "export function encodeGLB(input: IBakedMesh | readonly IBakedMesh[]) { … }",
8954
+ "situations": ["export baked terrain geometry without engine extensions"],
8955
+ "summary": "Legacy terrain-only GLB encoding with embedded mesh arrays and no chosen material.",
8956
+ "supersedes": [],
8957
+ "symbol": "encodeGLB"
8958
+ },
8959
+ {
8960
+ "aliases": [],
8961
+ "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
8962
+ "example": "const png = await encodeHeightPNG(new Terrain({ resolution: 17 }).evaluate());",
8963
+ "importPath": "@threenative/terrain",
8964
+ "kind": "function",
8965
+ "overrides": [],
8966
+ "package": "@threenative/terrain",
8967
+ "requires": ["npm i @threenative/terrain"],
8968
+ "signature": "export async function encodeHeightPNG(state: ITerrainState, options: Partial<IHeightRange> = { … }",
8969
+ "situations": ["export a terrain heightmap without an eight-bit colour conversion"],
8970
+ "summary": "Encodes numerical grayscale PNG16 with embedded elevation range.",
8971
+ "supersedes": [],
8972
+ "symbol": "encodeHeightPNG"
8973
+ },
8974
+ {
8975
+ "aliases": [],
8976
+ "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
8977
+ "example": "const raw = encodeRAW16(new Float32Array([0, 1]), { min: 0, max: 1 });",
8978
+ "importPath": "@threenative/terrain",
8979
+ "kind": "function",
8980
+ "overrides": [],
8981
+ "package": "@threenative/terrain",
8982
+ "requires": ["npm i @threenative/terrain"],
8983
+ "signature": "export function encodeRAW16( values: ArrayLike<number> & Iterable<number>, options: IRaw16Options = { … }",
8984
+ "situations": ["export terrain heights with a numerical range sidecar"],
8985
+ "summary": "Encodes finite metre elevations as an explicit-range RAW16 buffer.",
8986
+ "supersedes": [],
8987
+ "symbol": "encodeRAW16"
8988
+ },
8989
+ {
8990
+ "aliases": [],
8991
+ "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
8992
+ "example": "const maps = await encodeSplatPNGs(new Terrain({ resolution: 17 }).evaluate());",
8993
+ "importPath": "@threenative/terrain",
8994
+ "kind": "function",
8995
+ "overrides": [],
8996
+ "package": "@threenative/terrain",
8997
+ "requires": ["npm i @threenative/terrain"],
8998
+ "signature": "export async function encodeSplatPNGs(state: ITerrainState) { … }",
8999
+ "situations": ["export terrain splat weights as linear data"],
9000
+ "summary": "Encodes the eight linear material-weight channels as two RGBA images.",
9001
+ "supersedes": [],
9002
+ "symbol": "encodeSplatPNGs"
9003
+ },
9004
+ {
9005
+ "aliases": [],
9006
+ "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
9007
+ "example": "const archive = encodeZIP([{ name: \"height.raw\", bytes: new Uint8Array(8) }]);",
9008
+ "importPath": "@threenative/terrain",
9009
+ "kind": "function",
9010
+ "overrides": [],
9011
+ "package": "@threenative/terrain",
9012
+ "requires": ["npm i @threenative/terrain"],
9013
+ "signature": "export function encodeZIP(files: readonly IExportFile[]) { … }",
9014
+ "situations": ["archive derived terrain files without another dependency"],
9015
+ "summary": "Deterministic store-method ZIP with safe unique relative filenames.",
9016
+ "supersedes": [],
9017
+ "symbol": "encodeZIP"
9018
+ },
9019
+ {
9020
+ "aliases": [],
9021
+ "constraints": [
9022
+ "the row's `far` block decides every density; the caller supplies the collar and layer"
9023
+ ],
9024
+ "example": "const trees = farForestPlacements({ size, resolution, collar, treeline, rules, asset, layer });",
9025
+ "importPath": "@threenative/terrain",
9026
+ "kind": "function",
9027
+ "overrides": [],
9028
+ "package": "@threenative/terrain",
9029
+ "requires": ["npm i -D @threenative/terrain"],
9030
+ "signature": "export function farForestPlacements(options: IFarFieldOptions): IPlacement[] { … }",
9031
+ "situations": ["plant the stand past a game's playable square, out to the drawn collar"],
9032
+ "summary": "Far-field placements on the collar; also paints the collar's `canopy` attribute under each crown.",
9033
+ "supersedes": [],
9034
+ "symbol": "farForestPlacements"
9035
+ },
9036
+ {
9037
+ "aliases": [],
9038
+ "constraints": [
9039
+ "the field is a value, so two worlds sample the same formula with their own numbers"
9040
+ ],
9041
+ "example": "const stand = fieldWeight(STAND_FIELD, x, z);",
9042
+ "importPath": "@threenative/terrain",
9043
+ "kind": "function",
9044
+ "overrides": [],
9045
+ "package": "@threenative/terrain",
9046
+ "requires": ["npm i -D @threenative/terrain"],
9047
+ "signature": "export function fieldWeight(field: ICoverField, x: number, z: number): number { … }",
9048
+ "situations": [
9049
+ "sample the stand field a biome's trees and cover thin on",
9050
+ "measure the drift a biome's blades grow by, or the mat field its cover follows"
9051
+ ],
9052
+ "summary": "A field's weight at (x, z), clamped to 0..1.",
9053
+ "supersedes": [],
9054
+ "symbol": "fieldWeight"
9055
+ },
9056
+ {
9057
+ "aliases": [],
9058
+ "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
9059
+ "example": "const gradient = gradientAt(new Terrain({ resolution: 17 }).evaluate(), 0, 0);",
9060
+ "importPath": "@threenative/terrain",
9061
+ "kind": "function",
9062
+ "overrides": [],
9063
+ "package": "@threenative/terrain",
9064
+ "requires": ["npm i @threenative/terrain"],
9065
+ "signature": "export function gradientAt(grid: ISampledGrid, x: number, z: number): [number, number] { … }",
9066
+ "situations": ["measure an authored terrain gradient in metres"],
9067
+ "summary": "World-space height gradient from the canonical samples.",
9068
+ "supersedes": [],
9069
+ "symbol": "gradientAt"
9070
+ },
9071
+ {
9072
+ "aliases": [],
9073
+ "constraints": [
9074
+ "returns an ordinary `Terrain`: add roads, rivers, scatter or more layers, then `evaluate()` in a build script",
9075
+ "shape only; materials, colours and textures belong to the game",
9076
+ "calibrated at size 5000, resolution 513; other sizes keep the same slopes and scale the relief with `size`"
9077
+ ],
9078
+ "example": "const terrain = landform(\"alpine\", { size: 5000, resolution: 513, seed: 4 }); const state = terrain.evaluate();",
9079
+ "importPath": "@threenative/terrain",
9080
+ "kind": "function",
9081
+ "overrides": [
9082
+ "`relief` is the highest-minus-lowest height in metres before the finishing passes shave a few percent; `size`, `resolution` and `seed` as in `Terrain`"
9083
+ ],
9084
+ "package": "@threenative/terrain",
9085
+ "requires": ["npm i @threenative/terrain"],
9086
+ "signature": "export function landform(kind: LandformKind, options: ILandformOptions = { … }",
9087
+ "situations": [
9088
+ "start an open world, a distant backdrop or a mountain level from a kind of place"
9089
+ ],
9090
+ "summary": "One call, one landscape: a calibrated layer recipe for a kind of environment.",
9091
+ "supersedes": [],
9092
+ "symbol": "landform"
9093
+ },
9094
+ {
9095
+ "aliases": [],
9096
+ "constraints": [
9097
+ "resolution up to 513: the window is cut from a world twice as wide at the same spacing; build script only",
9098
+ "shape only; the game places, colours and fades it"
9099
+ ],
9100
+ "example": "const { size, resolution, heights } = landformBackdrop(\"temperateMountains\", { seed: 7, centerHeight: 13 });",
9101
+ "importPath": "@threenative/terrain",
9102
+ "kind": "function",
9103
+ "overrides": [
9104
+ "`relief` and `centerHeight` in metres; `size`, `resolution` and `seed` as in `landform`"
9105
+ ],
9106
+ "package": "@threenative/terrain",
9107
+ "requires": ["npm i @threenative/terrain"],
9108
+ "signature": "export function landformBackdrop( kind: LandformKind, options: IBackdropOptions = { … }",
9109
+ "situations": [
9110
+ "add a mountain backdrop around a playable area that the game's detail terrain covers"
9111
+ ],
9112
+ "summary": "Distant mountains around a playable area: a landform window with a valley floor at its centre.",
9113
+ "supersedes": [],
9114
+ "symbol": "landformBackdrop"
9115
+ },
9116
+ {
9117
+ "aliases": [],
9118
+ "constraints": ["the tile must cover the whole mountain; a summit crop lifts as a cone"],
9119
+ "example": "const lifted = liftMassif({ id: \"hill\", size: 400, resolution: 3, heights: [0, 0, 0, 0, 90, 0, 0, 0, 0] });",
9120
+ "importPath": "@threenative/terrain",
9121
+ "kind": "function",
9122
+ "overrides": [],
9123
+ "package": "@threenative/terrain",
9124
+ "requires": ["npm i -D @threenative/terrain"],
9125
+ "signature": "export function liftMassif(tile: IMassifTile): Float32Array { … }",
9126
+ "situations": [
9127
+ "measure how tall a surveyed mountain stands above the valley floor around it"
9128
+ ],
9129
+ "summary": "A tile's mountain above its own foot: the heights minus a smooth surface through its border, so its edge is exactly zero and stands on any ground with no wall or ramp. Signed: a valley inside the mountain cuts below the foot, as it does in the survey.",
9130
+ "supersedes": [],
9131
+ "symbol": "liftMassif"
7648
9132
  },
7649
9133
  {
7650
9134
  "aliases": [],
7651
9135
  "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
7652
- "example": "const glb = encodeGLB(bakeMesh(new Terrain({ resolution: 17 }).evaluate()));",
9136
+ "example": "const terrain = new Terrain({ resolution: 17 }); const file = await makeExport(terrain.evaluate(), terrain.toJSON(), \"project\");",
7653
9137
  "importPath": "@threenative/terrain",
7654
9138
  "kind": "function",
7655
9139
  "overrides": [],
7656
9140
  "package": "@threenative/terrain",
7657
9141
  "requires": ["npm i @threenative/terrain"],
7658
- "signature": "export function encodeGLB(input: IBakedMesh | readonly IBakedMesh[]) { … }",
7659
- "situations": ["export baked terrain geometry without engine extensions"],
7660
- "summary": "Legacy terrain-only GLB encoding with embedded mesh arrays and no chosen material.",
9142
+ "signature": "export function makeExport( state: ITerrainState | null, recipe: ITerrainDocument, kind: \"project\", ): Promise<IExportArchive>;",
9143
+ "situations": ["export a terrain recipe and its numerical runtime data"],
9144
+ "summary": "Recovered numerical/project exports; GLB/runtime outputs contain terrain only.",
7661
9145
  "supersedes": [],
7662
- "symbol": "encodeGLB"
9146
+ "symbol": "makeExport"
7663
9147
  },
7664
9148
  {
7665
9149
  "aliases": [],
7666
- "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
7667
- "example": "const png = await encodeHeightPNG(new Terrain({ resolution: 17 }).evaluate());",
9150
+ "constraints": [
9151
+ "samples are finite and at least one; a flat field resolves every band onto its one height"
9152
+ ],
9153
+ "example": "const bands = measureBands(spec.layers, state.height);",
7668
9154
  "importPath": "@threenative/terrain",
7669
9155
  "kind": "function",
7670
9156
  "overrides": [],
7671
9157
  "package": "@threenative/terrain",
7672
- "requires": ["npm i @threenative/terrain"],
7673
- "signature": "export async function encodeHeightPNG(state: ITerrainState, options: Partial<IHeightRange> = { … }",
7674
- "situations": ["export a terrain heightmap without an eight-bit colour conversion"],
7675
- "summary": "Encodes numerical grayscale PNG16 with embedded elevation range.",
9158
+ "requires": ["npm i -D @threenative/terrain"],
9159
+ "signature": "export function measureBands( layers: readonly ILayerInfo[], heights: ArrayLike<number>, ): IMeasuredBands { … }",
9160
+ "situations": [
9161
+ "turn a biome file's height fractions into the metres a world actually measured"
9162
+ ],
9163
+ "summary": "Resolve a biome's fraction bands against this world's own height samples.",
7676
9164
  "supersedes": [],
7677
- "symbol": "encodeHeightPNG"
9165
+ "symbol": "measureBands"
7678
9166
  },
7679
9167
  {
7680
9168
  "aliases": [],
7681
- "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
7682
- "example": "const raw = encodeRAW16(new Float32Array([0, 1]), { min: 0, max: 1 });",
9169
+ "constraints": ["the file carries one foliage row, one grass row and a cover block"],
9170
+ "example": "const rules = orderedScatterRules(spec);",
7683
9171
  "importPath": "@threenative/terrain",
7684
9172
  "kind": "function",
7685
9173
  "overrides": [],
7686
9174
  "package": "@threenative/terrain",
7687
- "requires": ["npm i @threenative/terrain"],
7688
- "signature": "export function encodeRAW16( values: ArrayLike<number> & Iterable<number>, options: IRaw16Options = { … }",
7689
- "situations": ["export terrain heights with a numerical range sidecar"],
7690
- "summary": "Encodes finite metre elevations as an explicit-range RAW16 buffer.",
9175
+ "requires": ["npm i -D @threenative/terrain"],
9176
+ "signature": "export function orderedScatterRules(spec: IBiomeSpec): IOrderedScatterRules { … }",
9177
+ "situations": ["run a biome file's rows through the ordered scatter"],
9178
+ "summary": "A biome's rows as the ordered generators read them. The rule is short and shared; only these numbers differ between a wood, a barren shoulder, a dune field and a tundra, so the biome file names them rather than the code. A biome whose tree is not one this generator has art for fails here, naming the species, rather than planting nothing.",
7691
9179
  "supersedes": [],
7692
- "symbol": "encodeRAW16"
9180
+ "symbol": "orderedScatterRules"
7693
9181
  },
7694
9182
  {
7695
9183
  "aliases": [],
7696
- "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
7697
- "example": "const maps = await encodeSplatPNGs(new Terrain({ resolution: 17 }).evaluate());",
9184
+ "constraints": [
9185
+ "the tile must be a whole mountain whose border is valley floor; erosion after it carves the survey"
9186
+ ],
9187
+ "example": "const { terrain, placement } = placeMassif(new Terrain({ size: 5000, resolution: 129 }), { seed: 3, tile: { id: \"cone\", size: 2000, resolution: 3, heights: [0, 0, 0, 0, 900, 0, 0, 0, 0] } });",
7698
9188
  "importPath": "@threenative/terrain",
7699
9189
  "kind": "function",
7700
- "overrides": [],
9190
+ "overrides": [
9191
+ "`at`, `bearing`, `distance`, `height`, `top`, `face` and `keepOut` on the same call"
9192
+ ],
7701
9193
  "package": "@threenative/terrain",
7702
- "requires": ["npm i @threenative/terrain"],
7703
- "signature": "export async function encodeSplatPNGs(state: ITerrainState) { … }",
7704
- "situations": ["export terrain splat weights as linear data"],
7705
- "summary": "Encodes the eight linear material-weight channels as two RGBA images.",
9194
+ "requires": ["npm i -D @threenative/terrain"],
9195
+ "signature": "export function placeMassif( terrain: Terrain, options: IPlaceMassifOptions, ): { … }",
9196
+ "situations": [
9197
+ "put a real-shaped mountain behind a generated world, a different one per seed"
9198
+ ],
9199
+ "summary": "Stands one surveyed mountain behind a world, chosen and posed by a seed: the tile from a list, a point on a bearing and distance, a turn that faces its steepest wall to the centre within 20 degrees, a mirror and a summit height. It stands on the host's own foot (a smooth surface through the host under its border), replacing the host's hills inside its square, and leaves the centre square untouched. Appends one `heightmap` layer; the placement carries the tile-spacing heights a relief map reads.",
7706
9200
  "supersedes": [],
7707
- "symbol": "encodeSplatPNGs"
9201
+ "symbol": "placeMassif"
7708
9202
  },
7709
9203
  {
7710
9204
  "aliases": [],
7711
- "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
7712
- "example": "const archive = encodeZIP([{ name: \"height.raw\", bytes: new Uint8Array(8) }]);",
9205
+ "constraints": [],
9206
+ "example": "const asset = propAssetOf(\"spruce:2\"); // \"spruce\"",
7713
9207
  "importPath": "@threenative/terrain",
7714
9208
  "kind": "function",
7715
9209
  "overrides": [],
7716
9210
  "package": "@threenative/terrain",
7717
- "requires": ["npm i @threenative/terrain"],
7718
- "signature": "export function encodeZIP(files: readonly IExportFile[]) { … }",
7719
- "situations": ["archive derived terrain files without another dependency"],
7720
- "summary": "Deterministic store-method ZIP with safe unique relative filenames.",
9211
+ "requires": ["npm i -D @threenative/terrain"],
9212
+ "signature": "export function propAssetOf(modelKey: string): string { … }",
9213
+ "situations": [
9214
+ "count one species across a world's prop buckets, or name the asset a run draws"
9215
+ ],
9216
+ "summary": "The asset a package run names. A prop run names the model it draws, `asset:variant[@shape]`; a container written by `bakeWorldPackage` names the asset alone. Both reduce to the asset here, which is what a count, a material or a placement's own `asset` field holds.",
7721
9217
  "supersedes": [],
7722
- "symbol": "encodeZIP"
9218
+ "symbol": "propAssetOf"
7723
9219
  },
7724
9220
  {
7725
9221
  "aliases": [],
7726
- "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
7727
- "example": "const gradient = gradientAt(new Terrain({ resolution: 17 }).evaluate(), 0, 0);",
9222
+ "constraints": [],
9223
+ "example": "const file = propPackageFile(\"forest\", \"local:true\", \"props.bin\"); // \"forest.local-true.props.bin\"",
7728
9224
  "importPath": "@threenative/terrain",
7729
9225
  "kind": "function",
7730
9226
  "overrides": [],
7731
9227
  "package": "@threenative/terrain",
7732
- "requires": ["npm i @threenative/terrain"],
7733
- "signature": "export function gradientAt(grid: ISampledGrid, x: number, z: number): [number, number] { … }",
7734
- "situations": ["measure an authored terrain gradient in metres"],
7735
- "summary": "World-space height gradient from the canonical samples.",
9228
+ "requires": ["npm i -D @threenative/terrain"],
9229
+ "signature": "export function propPackageFile(world: string, bucket: string, suffix: string): string { … }",
9230
+ "situations": ["name one of a bucket's three files without a bucket key that breaks a path"],
9231
+ "summary": "A path under `world/` that no bucket name can break: `local:true` becomes `local-true`. The bucket's own name is kept in the manifest, so this rename is only a file-system concern.",
7736
9232
  "supersedes": [],
7737
- "symbol": "gradientAt"
9233
+ "symbol": "propPackageFile"
7738
9234
  },
7739
9235
  {
7740
9236
  "aliases": [],
7741
- "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
7742
- "example": "const terrain = new Terrain({ resolution: 17 }); const file = await makeExport(terrain.evaluate(), terrain.toJSON(), \"project\");",
9237
+ "constraints": ["the manifest names the files; nothing here touches a file system"],
9238
+ "example": "const { manifest, files } = propPackageFiles(pkg, \"forest\");",
7743
9239
  "importPath": "@threenative/terrain",
7744
9240
  "kind": "function",
7745
9241
  "overrides": [],
7746
9242
  "package": "@threenative/terrain",
7747
- "requires": ["npm i @threenative/terrain"],
7748
- "signature": "export async function makeExport( state: ITerrainState, recipe: ITerrainDocument, kind: ExportKind, ): Promise<IExportArchive> { … }",
7749
- "situations": ["export a terrain recipe and its numerical runtime data"],
7750
- "summary": "Recovered numerical/project exports; GLB/runtime outputs contain terrain only.",
9243
+ "requires": ["npm i -D @threenative/terrain"],
9244
+ "signature": "export function propPackageFiles(pkg: IPropPackage, world: string): IPropPackageFiles { … }",
9245
+ "situations": [
9246
+ "write a compiled package to disk: one manifest and three files per streamed world"
9247
+ ],
9248
+ "summary": "Write a compiled package as the manifest the game fetches and one set of files per bucket. The manifest names the files rather than embedding them, so a loader fetches only the buckets its query flags keep (`?farForest=on` keeps the far field, `?meadow=off` drops the vista cover).",
7751
9249
  "supersedes": [],
7752
- "symbol": "makeExport"
9250
+ "symbol": "propPackageFiles"
7753
9251
  },
7754
9252
  {
7755
9253
  "aliases": [],
@@ -7766,6 +9264,23 @@
7766
9264
  "supersedes": [],
7767
9265
  "symbol": "sampleHeight"
7768
9266
  },
9267
+ {
9268
+ "aliases": [],
9269
+ "constraints": [
9270
+ "`data.rules` is the biome's rows, and `data.field` the ground they were graded on"
9271
+ ],
9272
+ "example": "const { placements, counts } = scatterProps(data, focus, clearings);",
9273
+ "importPath": "@threenative/terrain",
9274
+ "kind": "function",
9275
+ "overrides": [],
9276
+ "package": "@threenative/terrain",
9277
+ "requires": ["npm i -D @threenative/terrain"],
9278
+ "signature": "export function scatterProps( data: IOrderedScatterField, focus: { … }",
9279
+ "situations": ["bake a biome that says `\"stream\": \"ordered\"`"],
9280
+ "summary": "Every placement, for one world, from one seed: the game's own rule set, in its own draw order.",
9281
+ "supersedes": [],
9282
+ "symbol": "scatterProps"
9283
+ },
7769
9284
  {
7770
9285
  "aliases": [],
7771
9286
  "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
@@ -7834,7 +9349,8 @@
7834
9349
  "signature": "export class Terrain { … }",
7835
9350
  "situations": [
7836
9351
  "author seeded terrain with noise, sculpting, erosion, roads, rivers and scatter",
7837
- "generate a procedural heightmap landscape or island for a game"
9352
+ "generate a procedural heightmap landscape or island for a game",
9353
+ "make realistic mountains, hills, desert, coast, tundra or volcano terrain: start from `landform(kind)`, or add `erode({ method: \"fluvial\" })` for dendritic valleys"
7838
9354
  ],
7839
9355
  "summary": "Ordered, stable-ID terrain authoring with synchronous atomic transactions.",
7840
9356
  "supersedes": [],
@@ -7855,6 +9371,42 @@
7855
9371
  "supersedes": [],
7856
9372
  "symbol": "TerrainEvaluator"
7857
9373
  },
9374
+ {
9375
+ "aliases": [],
9376
+ "constraints": [
9377
+ "square grids only; compare crops of equal spacing, because slope and curvature depend on it"
9378
+ ],
9379
+ "example": "const stats = terrainStats(state.height, state.resolution, state.size);",
9380
+ "importPath": "@threenative/terrain",
9381
+ "kind": "function",
9382
+ "overrides": [],
9383
+ "package": "@threenative/terrain",
9384
+ "requires": ["npm i @threenative/terrain"],
9385
+ "signature": "export function terrainStats(height: ArrayLike<number>, n: number, size: number): ITerrainStats { … }",
9386
+ "situations": ["compare generated terrain with a USGS or SRTM crop on the same footprint"],
9387
+ "summary": "Landform statistics used to calibrate generators against real DEMs.",
9388
+ "supersedes": [],
9389
+ "symbol": "terrainStats"
9390
+ },
9391
+ {
9392
+ "aliases": [],
9393
+ "constraints": [
9394
+ "The file carries no appearance; colours, materials and shading stay game source"
9395
+ ],
9396
+ "example": "const spec = validateBiome(JSON.parse(text), \"forest\");",
9397
+ "importPath": "@threenative/terrain",
9398
+ "kind": "function",
9399
+ "overrides": [],
9400
+ "package": "@threenative/terrain",
9401
+ "requires": ["npm i @threenative/terrain"],
9402
+ "signature": "export function validateBiome(spec: unknown, name: string): IBiomeSpec { … }",
9403
+ "situations": [
9404
+ "read a biome's rules from `starter/<biome>/biome.data.json` before a game or a cook uses them"
9405
+ ],
9406
+ "summary": "One biome file, checked field by field. The file is `biome.data.json`: `biome.json` is Biome's own configuration name, and a data file called that is parsed as a project config and fails the lint.",
9407
+ "supersedes": [],
9408
+ "symbol": "validateBiome"
9409
+ },
7858
9410
  {
7859
9411
  "aliases": [],
7860
9412
  "constraints": ["authoring data only; the game owns appearance, physics and rendering"],
@@ -7908,6 +9460,89 @@
7908
9460
  "supersedes": [],
7909
9461
  "symbol": "checkEnvironmentAssets"
7910
9462
  },
9463
+ {
9464
+ "aliases": [],
9465
+ "constraints": [
9466
+ "the caller supplies the TransformControls, proxy, controller and every drawing callback"
9467
+ ],
9468
+ "example": "const selection = createEditorSelection({ gizmo, proxy, controller, grounding, surface, defaultFootprintSize, refreshPose, drawFootprint, restorePlacement, previewPlacement, setSaving, selectedChanged, setNavigation, message });",
9469
+ "importPath": "@threenative/terrain/editor",
9470
+ "kind": "function",
9471
+ "overrides": [],
9472
+ "package": "@threenative/terrain",
9473
+ "requires": ["npm i -D @threenative/terrain"],
9474
+ "signature": "export function createEditorSelection( { … }",
9475
+ "situations": ["drive terrain-editor selection, gizmo drags, undo and saved transactions"],
9476
+ "summary": "Gesture and transaction mechanics; the caller owns the controls, proxy and all rendering.",
9477
+ "supersedes": [],
9478
+ "symbol": "createEditorSelection"
9479
+ },
9480
+ {
9481
+ "aliases": [],
9482
+ "constraints": [],
9483
+ "example": "const box = createTweakBox({ title: \"Fog\", knobs: { density: { min: 0, max: 0.1, value: 0.02 } }, onChange: (name, value) => console.info(name, value) });",
9484
+ "importPath": "@threenative/terrain/editor",
9485
+ "kind": "function",
9486
+ "overrides": [],
9487
+ "package": "@threenative/terrain",
9488
+ "requires": ["npm i -D @threenative/terrain"],
9489
+ "signature": "export function createTweakBox<K extends string>(options: ITweakBoxOptions<K>): ITweakBox<K> { … }",
9490
+ "situations": [
9491
+ "tune look numbers by eye with live range bars and colour pickers while the game runs"
9492
+ ],
9493
+ "summary": "A box of range bars and colour pickers over the running game, for tuning numbers by eye. The game names its knobs and applies each change itself; the box owns the page elements, the stored values and the Copy button, whose JSON is what gets pasted back and written into the game's own source. With no `document` (a native launch, a test) it draws nothing and still holds the values, so the game code that reads them is the same on every target.",
9494
+ "supersedes": [],
9495
+ "symbol": "createTweakBox"
9496
+ },
9497
+ {
9498
+ "aliases": [],
9499
+ "constraints": [
9500
+ "the point is multiplied in place; the pose needs finite position, quaternion and scale"
9501
+ ],
9502
+ "example": "const centre = editorPlacementCenter(localCentre.clone(), placement);",
9503
+ "importPath": "@threenative/terrain/editor",
9504
+ "kind": "function",
9505
+ "overrides": [],
9506
+ "package": "@threenative/terrain",
9507
+ "requires": ["npm i -D @threenative/terrain"],
9508
+ "signature": "export function editorPlacementCenter(point: Vector3, pose: IPlacementOverride): Vector3 { … }",
9509
+ "situations": ["find the world-space centre of a placed terrain-editor instance"],
9510
+ "summary": "Transform the caller's measured geometry centre into the evaluated placement's world space.",
9511
+ "supersedes": [],
9512
+ "symbol": "editorPlacementCenter"
9513
+ },
9514
+ {
9515
+ "aliases": [],
9516
+ "constraints": ["the point is projected in place; pass a clone to keep the original"],
9517
+ "example": "const [x, y] = editorPointToClient(point.clone(), camera, canvas.getBoundingClientRect());",
9518
+ "importPath": "@threenative/terrain/editor",
9519
+ "kind": "function",
9520
+ "overrides": [],
9521
+ "package": "@threenative/terrain",
9522
+ "requires": ["npm i -D @threenative/terrain"],
9523
+ "signature": "export function editorPointToClient( point: Vector3, camera: Camera, box: { … }",
9524
+ "situations": ["convert a terrain-editor world point to viewport client pixels"],
9525
+ "summary": "Project an injected world point to client pixels in the caller's viewport.",
9526
+ "supersedes": [],
9527
+ "symbol": "editorPointToClient"
9528
+ },
9529
+ {
9530
+ "aliases": [],
9531
+ "constraints": [
9532
+ "the supplied mesh and raycast determine the surface; missing intersections return undefined"
9533
+ ],
9534
+ "example": "const height = editorSurfaceHeight(ctx, terrainMesh, x, z);",
9535
+ "importPath": "@threenative/terrain/editor",
9536
+ "kind": "function",
9537
+ "overrides": [],
9538
+ "package": "@threenative/terrain",
9539
+ "requires": ["npm i -D @threenative/terrain"],
9540
+ "signature": "export function editorSurfaceHeight( ctx: { … }",
9541
+ "situations": ["query terrain-editor surface elevation at world X/Z coordinates"],
9542
+ "summary": "Query the rendered heightfield, including its triangulation rather than an interpolated bake.",
9543
+ "supersedes": [],
9544
+ "symbol": "editorSurfaceHeight"
9545
+ },
7911
9546
  {
7912
9547
  "aliases": [],
7913
9548
  "constraints": ["framing only; an unknown target returns a named diagnostic and no camera"],
@@ -7965,6 +9600,23 @@
7965
9600
  "supersedes": [],
7966
9601
  "symbol": "inspectSpatial"
7967
9602
  },
9603
+ {
9604
+ "aliases": [],
9605
+ "constraints": [
9606
+ "the caller supplies world and default footprint sizes; unsupported layers return undefined"
9607
+ ],
9608
+ "example": "const pose = landformPose(layer, terrain.size, footprintSize);",
9609
+ "importPath": "@threenative/terrain/editor",
9610
+ "kind": "function",
9611
+ "overrides": [],
9612
+ "package": "@threenative/terrain",
9613
+ "requires": ["npm i -D @threenative/terrain"],
9614
+ "signature": "export function landformPose(layer: Layer, worldSize: number, defaultSize: number) { … }",
9615
+ "situations": ["derive a terrain-editor gizmo pose from a landform layer"],
9616
+ "summary": "Recipe footprints are heights over X/Z, never independently transformed solids.",
9617
+ "supersedes": [],
9618
+ "symbol": "landformPose"
9619
+ },
7968
9620
  {
7969
9621
  "aliases": [],
7970
9622
  "constraints": [
@@ -7982,6 +9634,40 @@
7982
9634
  "supersedes": [],
7983
9635
  "symbol": "mountTerrainEditor"
7984
9636
  },
9637
+ {
9638
+ "aliases": [],
9639
+ "constraints": [
9640
+ "the caller supplies the raycast context, terrain mesh, instanced meshes and evaluated placements"
9641
+ ],
9642
+ "example": "const id = pickEditorPlacement(ctx, terrainMesh, meshes, placements, event.clientX, event.clientY);",
9643
+ "importPath": "@threenative/terrain/editor",
9644
+ "kind": "function",
9645
+ "overrides": [],
9646
+ "package": "@threenative/terrain",
9647
+ "requires": ["npm i -D @threenative/terrain"],
9648
+ "signature": "export function pickEditorPlacement( ctx: Parameters<typeof pickEditorSurface>[0], terrain: Mesh, meshes: readonly Object3D[], placements: Iterable< { … }",
9649
+ "situations": [
9650
+ "pick a placed instance in the terrain editor from viewport client coordinates"
9651
+ ],
9652
+ "summary": "A foreground terrain hit occludes placements; matching uses the evaluated world position.",
9653
+ "supersedes": [],
9654
+ "symbol": "pickEditorPlacement"
9655
+ },
9656
+ {
9657
+ "aliases": [],
9658
+ "constraints": ["the caller supplies the raycast implementation and ordered targets"],
9659
+ "example": "const hit = pickEditorSurface(ctx, [terrainMesh], event.clientX, event.clientY);",
9660
+ "importPath": "@threenative/terrain/editor",
9661
+ "kind": "function",
9662
+ "overrides": [],
9663
+ "package": "@threenative/terrain",
9664
+ "requires": ["npm i -D @threenative/terrain"],
9665
+ "signature": "export function pickEditorSurface( ctx: { … }",
9666
+ "situations": ["pick a terrain-editor surface from viewport client coordinates"],
9667
+ "summary": "Convert viewport client coordinates once; the installed picker owns ray intersection.",
9668
+ "supersedes": [],
9669
+ "symbol": "pickEditorSurface"
9670
+ },
7985
9671
  {
7986
9672
  "aliases": [],
7987
9673
  "constraints": ["authoring data only; non-finite, malformed and out-of-extent queries throw"],
@@ -8088,6 +9774,23 @@
8088
9774
  "supersedes": [],
8089
9775
  "symbol": "TerrainEditorController"
8090
9776
  },
9777
+ {
9778
+ "aliases": [],
9779
+ "constraints": [
9780
+ "finite coordinates and positive scales are required; X/Z rotations that overhang throw"
9781
+ ],
9782
+ "example": "const next = transformedLandform(layer, position, quaternion, scale, surfaceHeight);",
9783
+ "importPath": "@threenative/terrain/editor",
9784
+ "kind": "function",
9785
+ "overrides": [],
9786
+ "package": "@threenative/terrain",
9787
+ "requires": ["npm i -D @threenative/terrain"],
9788
+ "signature": "export function transformedLandform( layer: Layer, position: Vector3, quaternion: Quaternion, scale: Vector3, anchor: number, ): Layer { … }",
9789
+ "situations": ["apply a terrain-editor gizmo transform to a landform layer"],
9790
+ "summary": "Convert a terrain-editor gizmo pose into a heightfield landform footprint.",
9791
+ "supersedes": [],
9792
+ "symbol": "transformedLandform"
9793
+ },
8091
9794
  {
8092
9795
  "aliases": [],
8093
9796
  "constraints": [
@@ -8260,24 +9963,105 @@
8260
9963
  {
8261
9964
  "aliases": [],
8262
9965
  "constraints": [
8263
- "browser authoring (FileReader/canvas); caller supplies all appearance and coherent baked water; root and /three remain headless"
9966
+ "browser authoring FileReader/canvas; all appearance and coherent water come from the game"
8264
9967
  ],
8265
- "example": "const output = await exportWorldGLB({ revision, snapshotTime: 0, state, terrain, assets, transforms });",
9968
+ "example": "const prepared = await prepareWorldGLTF(input);",
8266
9969
  "importPath": "@threenative/terrain/export",
8267
9970
  "kind": "function",
9971
+ "overrides": [],
9972
+ "package": "@threenative/terrain",
9973
+ "requires": ["npm i -D @threenative/terrain"],
9974
+ "signature": "export async function prepareWorldGLTF(input: IWorldGLBInput): Promise< { … }",
9975
+ "situations": [
9976
+ "export the terrain as a glb for another three.js project via the headless cook",
9977
+ "prepare the terrain editor's resolved world for headless portable GLB cooking"
9978
+ ],
9979
+ "summary": "Prepare the game's validated, frozen portable scene; the server cook owns GLB encoding.",
9980
+ "supersedes": [],
9981
+ "symbol": "prepareWorldGLTF"
9982
+ },
9983
+ {
9984
+ "aliases": [],
9985
+ "constraints": ["Node authoring only; recipes, asset tables and sky paths stay in the game"],
9986
+ "example": "await bakeKit(import.meta.url, { sky: \"hdri/game-sky.hdr\" });",
9987
+ "importPath": "@threenative/terrain/kit",
9988
+ "kind": "function",
9989
+ "overrides": [],
9990
+ "package": "@threenative/terrain",
9991
+ "requires": ["npm i -D @threenative/terrain"],
9992
+ "signature": "export async function bakeKit( url: string, { … }",
9993
+ "situations": ["bake a copied terrain starter kit into its offline world package"],
9994
+ "summary": "Bake a copied kit, optionally using the caller's installed world cook.",
9995
+ "supersedes": [],
9996
+ "symbol": "bakeKit"
9997
+ },
9998
+ {
9999
+ "aliases": [],
10000
+ "constraints": [
10001
+ "Node authoring only; verifies archive size and SHA256 before atomic extraction"
10002
+ ],
10003
+ "example": "const assets = await starterAssetsDir();",
10004
+ "importPath": "@threenative/terrain/kit",
10005
+ "kind": "function",
10006
+ "overrides": [],
10007
+ "package": "@threenative/terrain",
10008
+ "requires": ["npm i -D @threenative/terrain"],
10009
+ "signature": "export async function starterAssetsDir(): Promise<string> { … }",
10010
+ "situations": ["resolve terrain kit models and textures for offline baking"],
10011
+ "summary": "Resolve shared starter assets locally, or download the package's pinned archive on demand.",
10012
+ "supersedes": [],
10013
+ "symbol": "starterAssetsDir"
10014
+ },
10015
+ {
10016
+ "aliases": [],
10017
+ "constraints": ["Runtime subpath; the game supplies every appearance and collision choice"],
10018
+ "example": "await addStarterWorld(ctx, follow, spec);",
10019
+ "importPath": "@threenative/terrain/starter",
10020
+ "kind": "function",
10021
+ "overrides": [],
10022
+ "package": "@threenative/terrain",
10023
+ "requires": ["npm i -D @threenative/terrain"],
10024
+ "signature": "export async function addStarterWorld<Extra extends { … }",
10025
+ "situations": [
10026
+ "attach a baked starter world with game-owned surfaces, prop dressing and water"
10027
+ ],
10028
+ "summary": "Load caller-authored starter data with one scene lifetime; all appearance comes from spec.",
10029
+ "supersedes": [],
10030
+ "symbol": "addStarterWorld"
10031
+ },
10032
+ {
10033
+ "aliases": [],
10034
+ "constraints": [],
10035
+ "example": "const edited = editWorldPlacements(data, { remove: [\"scree:candidate:7:41\"] }, (x, z) => field.heightAt(x, z));",
10036
+ "importPath": "@threenative/terrain/starter",
10037
+ "kind": "function",
8268
10038
  "overrides": [
8269
- "actual static models, final matrices and baked PBR maps are supplied by the game"
10039
+ "grounding defaults on, while `grounding: false` preserves the authored Y coordinate"
8270
10040
  ],
8271
10041
  "package": "@threenative/terrain",
8272
10042
  "requires": ["npm i -D @threenative/terrain"],
8273
- "signature": "export async function exportWorldGLB(input: IWorldGLBInput): Promise<IWorldGLBExport> { … }",
10043
+ "signature": "export function editWorldPlacements( data: { … }",
8274
10044
  "situations": [
8275
- "export terrain, resolved models and final manual placement transforms as a portable GLB",
8276
- "export the whole terrain world as one glb for another three.js project"
10045
+ "change generated terrain composition from game source without rebaking the world"
8277
10046
  ],
8278
- "summary": "Export a committed evaluated world using ordinary glTF 2.0 nodes and embedded PBR images.",
10047
+ "summary": "Apply deterministic startup edits to the decoded placement data before a world is loaded.",
10048
+ "supersedes": [],
10049
+ "symbol": "editWorldPlacements"
10050
+ },
10051
+ {
10052
+ "aliases": [],
10053
+ "constraints": ["Shapes and reach are supplied by the game; detach releases every body"],
10054
+ "example": "new PropColliders(ctx, follow, manifest, records, shapes, reach, name);",
10055
+ "importPath": "@threenative/terrain/starter",
10056
+ "kind": "class",
10057
+ "overrides": [],
10058
+ "package": "@threenative/terrain",
10059
+ "requires": ["npm i -D @threenative/terrain"],
10060
+ "signature": "export class PropColliders extends Object3D implements IComputeDriven { … }",
10061
+ "situations": ["attach nearby prop collision bodies from baked placement records"],
10062
+ "summary": "Stream caller-specified fixed collision shapes around a moving follow object.",
8279
10063
  "supersedes": [],
8280
- "symbol": "exportWorldGLB"
10064
+ "symbol": "PropColliders"
8281
10065
  },
8282
10066
  {
8283
10067
  "aliases": [],
@@ -9091,7 +10875,7 @@
9091
10875
  "procedural trees",
9092
10876
  "swaying trees",
9093
10877
  "tree foliage wind sway",
9094
- "generate a forest of trees"
10878
+ "grow procedural tree meshes"
9095
10879
  ]
9096
10880
  },
9097
10881
  {
@@ -9112,7 +10896,7 @@
9112
10896
  "blurb": "A three-room grid dungeon of mannequin fighters: melee, the Arcane Surge, loot, equipment, persistence, and a real character sheet.",
9113
10897
  "name": "action-rpg",
9114
10898
  "title": "Action RPG",
9115
- "words": ["action-rpg"]
10899
+ "words": ["action-rpg", "diablo", "arpg", "hack-and-slash", "dungeon-crawler"]
9116
10900
  },
9117
10901
  {
9118
10902
  "blurb": "Wren crosses a sunlit clearing and a three-room moss dungeon with lock-on sword combat, a shield, a block-and-switch puzzle, a small key and the Stone Warden mini-boss.",