@threenative/core 0.3.12 → 0.3.15

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 (165) hide show
  1. package/README.md +1 -1
  2. package/capabilities.json +1047 -44
  3. package/dist/{assets-YUbXa3-Y.d.ts → assets-CfMKnOsK.d.ts} +78 -1
  4. package/dist/{canvas-layer-CWuFRT7G.d.ts → canvas-layer-G7ttVy7y.d.ts} +1 -1
  5. package/dist/{chunk-7UUT3TY5.js → chunk-2GPHICV6.js} +1 -1
  6. package/dist/{chunk-GMHATRPW.js → chunk-GEMQJBY4.js} +1650 -383
  7. package/dist/{chunk-VAZM36TV.js → chunk-H4J6IAJE.js} +17 -10
  8. package/dist/{chunk-5O73CDMR.js → chunk-QAMSM3Z5.js} +415 -27
  9. package/dist/{chunk-2Z44XSI2.js → chunk-QAQHYOWY.js} +3 -7
  10. package/dist/{chunk-DBELTTTM.js → chunk-U4YHUKKL.js} +1 -1
  11. package/dist/{chunk-OKXUCASC.js → chunk-VBBYWGAT.js} +3 -4
  12. package/dist/chunk-VP43GIWW.js +18 -0
  13. package/dist/{chunk-N5LRP4BR.js → chunk-VQRPEOKY.js} +66 -3
  14. package/dist/{chunk-6KLNISRJ.js → chunk-XDTZ4QMO.js} +11 -4
  15. package/dist/default-tone-mapping-GgKPTiBP.d.ts +4 -0
  16. package/dist/{game-D7pAzZUY.d.ts → game-k8K3hZai.d.ts} +72 -8
  17. package/dist/hot.d.ts +5 -4
  18. package/dist/hot.js +5 -8
  19. package/dist/index.d.ts +871 -1018
  20. package/dist/index.js +4786 -1631
  21. package/dist/{model-lod-B6BMqS1r.d.ts → model-lod-DPTzeCcD.d.ts} +4 -2
  22. package/dist/playtest.d.ts +5 -4
  23. package/dist/playtest.js +6 -5
  24. package/dist/quality-BADStsTn.d.ts +868 -0
  25. package/dist/react.d.ts +3 -2
  26. package/dist/render-environment.d.ts +170 -0
  27. package/dist/render-environment.js +352 -0
  28. package/dist/{renderer-DvFVoAgj.d.ts → renderer-BtOSseYf.d.ts} +29 -31
  29. package/dist/spells/index.js +1 -1
  30. package/dist/ui-layer.js +3 -2
  31. package/dist/worker.js +12 -5
  32. package/dist/world.d.ts +280 -16
  33. package/dist/world.js +1529 -642
  34. package/mcp/animation-server.mjs +1 -1
  35. package/mcp/engine-server.mjs +135 -11
  36. package/mcp/servers.mjs +4 -4
  37. package/package.json +10 -6
  38. package/scripts/ensure-mcp.mjs +6 -1
  39. package/src/animation-batch.ts +193 -0
  40. package/src/animation-layers.ts +7 -3
  41. package/src/animation.ts +209 -29
  42. package/src/asset-cache.ts +3 -3
  43. package/src/asset-memo.ts +202 -0
  44. package/src/assets.ts +436 -131
  45. package/src/auto-batch.ts +190 -44
  46. package/src/clustered-batch.ts +146 -3
  47. package/src/clustered-mesh.ts +548 -20
  48. package/src/compute-driven.ts +1 -1
  49. package/src/config.ts +8 -0
  50. package/src/debug.ts +119 -22
  51. package/src/dev-global.ts +54 -0
  52. package/src/displaced-surface.ts +428 -0
  53. package/src/engine-hooks.ts +37 -0
  54. package/src/frame-budget.ts +35 -3
  55. package/src/game-boot-phase.ts +269 -0
  56. package/src/game-dev-tools.ts +7 -14
  57. package/src/game-frame-loop.ts +45 -82
  58. package/src/game-startup.ts +145 -70
  59. package/src/game-ui.ts +84 -0
  60. package/src/game.ts +168 -552
  61. package/src/gamepad-mappings.ts +269 -0
  62. package/src/generated/console-markers.ts +14 -0
  63. package/src/geometry-capture.ts +28 -4
  64. package/src/gpu-readings.ts +98 -0
  65. package/src/gpu-scene-bvh.ts +149 -36
  66. package/src/grass-field.ts +628 -0
  67. package/src/hot.ts +4 -7
  68. package/src/index.ts +227 -8
  69. package/src/input.ts +237 -25
  70. package/src/instanced-batch-lod.ts +3 -8
  71. package/src/interpolation.ts +171 -40
  72. package/src/look/ao-admission.ts +4 -3
  73. package/src/look/auto-exposure.ts +5 -16
  74. package/src/look/default-tone-mapping.ts +41 -5
  75. package/src/look/local-exposure.ts +2 -7
  76. package/src/look/quad-pass.ts +21 -0
  77. package/src/look/quality.ts +4 -0
  78. package/src/look/unreal-bloom.ts +4 -13
  79. package/src/look/world-environment.ts +58 -115
  80. package/src/merge-parts.ts +20 -24
  81. package/src/model-lod.ts +97 -14
  82. package/src/particle-significance.ts +12 -0
  83. package/src/particles.ts +19 -10
  84. package/src/platform.ts +23 -4
  85. package/src/profiling/FrameStages.ts +5 -6
  86. package/src/profiling/Spans.ts +3 -17
  87. package/src/profiling/debug-telemetry.ts +2 -6
  88. package/src/profiling/render-list-validate.ts +6 -15
  89. package/src/projection-marker.ts +2 -1
  90. package/src/quiet-markers.ts +3 -10
  91. package/src/render/cpu-bvh.ts +100 -0
  92. package/src/render/depth-pyramid.ts +6 -14
  93. package/src/render/environment/environmentContribution.ts +202 -0
  94. package/src/render/environment/environmentRadiance.ts +44 -0
  95. package/src/render/environment/environmentSampleCache.ts +56 -0
  96. package/src/render/environment/environmentSampling.ts +201 -0
  97. package/src/render/environment/environmentSnapshot.ts +71 -0
  98. package/src/render/environment/gate.ts +57 -0
  99. package/src/render/material-key.ts +21 -1
  100. package/src/render/mesh-pool.ts +3 -19
  101. package/src/render/probe-trace.ts +872 -0
  102. package/src/render/probe-volume.ts +780 -34
  103. package/src/render/radiance-cache.ts +17 -0
  104. package/src/render/screen-probe-gather.ts +303 -0
  105. package/src/render/short-range-ao.ts +274 -0
  106. package/src/render/virtual-shadow-partial.ts +13 -0
  107. package/src/render/virtual-shadow.ts +18 -16
  108. package/src/render/world-impostor-surface.ts +207 -9
  109. package/src/render/world-impostor.ts +5 -2
  110. package/src/render-camera-cull.ts +105 -4
  111. package/src/render-environment.ts +41 -0
  112. package/src/renderer-config.ts +36 -0
  113. package/src/renderer-facts.ts +37 -0
  114. package/src/renderer.ts +78 -32
  115. package/src/resolution-scaler.ts +3 -2
  116. package/src/scatter-field.ts +496 -0
  117. package/src/scene-entry-inspectors.ts +61 -0
  118. package/src/snow-field.ts +1 -0
  119. package/src/startup-offscreen-bytes.ts +84 -0
  120. package/src/state.ts +16 -3
  121. package/src/static-transform.ts +100 -25
  122. package/src/streamed-textures.ts +112 -0
  123. package/src/streaming.ts +68 -4
  124. package/src/texture-streaming.ts +331 -0
  125. package/src/tile-ring.ts +294 -0
  126. package/src/version.ts +1 -1
  127. package/src/warmup.ts +15 -2
  128. package/src/worker.ts +12 -2
  129. package/src/world-bundle-safety.ts +55 -10
  130. package/src/world-cell-batches.ts +166 -200
  131. package/src/world-cell-chunks.ts +3 -7
  132. package/src/world-cell-data.ts +7 -0
  133. package/src/world-cell-impostors.ts +20 -8
  134. package/src/world-cell-models.ts +36 -8
  135. package/src/world-cell-options.ts +2 -14
  136. package/src/world-cell-placements.ts +194 -90
  137. package/src/world-cell-prewarm.ts +39 -4
  138. package/src/world-cell-records.ts +401 -0
  139. package/src/world-cell-render-bundles.ts +2 -2
  140. package/src/world-cell-render-gpu-dress.ts +17 -19
  141. package/src/world-cell-render-main-cull.ts +73 -17
  142. package/src/world-cell-render-util.ts +18 -5
  143. package/src/world-cell-render.ts +13 -5
  144. package/src/world-cell-residency.ts +15 -6
  145. package/src/world-cell-stale.ts +238 -0
  146. package/src/world-cells.ts +23 -6
  147. package/src/world-gpu-flags.ts +18 -50
  148. package/src/world-gpu-reference.ts +22 -8
  149. package/src/world-gpu-scene.ts +44 -24
  150. package/src/world-gpu-shadow.ts +21 -8
  151. package/src/world-gpu-types.ts +41 -13
  152. package/src/world-load-limiter.ts +5 -0
  153. package/src/world-model-sections.ts +80 -0
  154. package/src/world-river-ribbon.ts +273 -0
  155. package/src/world-root-frame.ts +39 -0
  156. package/src/world-shore-field.ts +91 -0
  157. package/src/world-static-pose.ts +163 -0
  158. package/src/world-surface-sampler.ts +48 -0
  159. package/src/world-terrain-splat.ts +10 -18
  160. package/src/world-tile-budget.ts +4 -11
  161. package/src/world-tiles.ts +79 -12
  162. package/src/world-validate.ts +6 -14
  163. package/src/world-warm.ts +51 -0
  164. package/src/world-water-bodies.ts +113 -3
  165. package/src/world.ts +13 -0
package/dist/ui-layer.js CHANGED
@@ -1,5 +1,6 @@
1
- export { onUiIntent, publishUiState, sendUiIntent, subscribeUiState } from './chunk-7UUT3TY5.js';
2
- import './chunk-N5LRP4BR.js';
1
+ export { onUiIntent, publishUiState, sendUiIntent, subscribeUiState } from './chunk-2GPHICV6.js';
2
+ import './chunk-VQRPEOKY.js';
3
+ import './chunk-VP43GIWW.js';
3
4
  import { HIT_REGIONS_MESSAGE } from './chunk-CFGTPFUH.js';
4
5
  export { GAME_STATE_MESSAGE, HIT_REGIONS_MESSAGE, UI_BRIDGE_GLOBALS, UI_DEV_METRICS_MESSAGE, UI_INTENT_MESSAGE, UI_READY_INTENT, UI_STARTUP_MESSAGE, connectUiBridge } from './chunk-CFGTPFUH.js';
5
6
 
package/dist/worker.js CHANGED
@@ -1,6 +1,7 @@
1
- import { markerLogRequested } from './chunk-2Z44XSI2.js';
2
- import { hostWindow, hostDocument, hostResizeObserver } from './chunk-6KLNISRJ.js';
3
- import { debugRequested, countDebug } from './chunk-N5LRP4BR.js';
1
+ import { markerLogRequested } from './chunk-QAQHYOWY.js';
2
+ import { debugRequested, countDebug } from './chunk-VQRPEOKY.js';
3
+ import { hostWindow, hostDocument, hostResizeObserver } from './chunk-XDTZ4QMO.js';
4
+ import './chunk-VP43GIWW.js';
4
5
  import { GAME_STATE_MESSAGE } from './chunk-CFGTPFUH.js';
5
6
 
6
7
  // src/worker-audio.ts
@@ -925,6 +926,7 @@ function startWorkerGame(worker, container) {
925
926
  if (isStateFrame(event.data)) uiPort.postMessage({ type: "tn-worker-ui-ack" });
926
927
  }
927
928
  };
929
+ let started = false;
928
930
  let resolveReady = () => void 0;
929
931
  let rejectReady = () => void 0;
930
932
  const ready = new Promise((resolve, reject) => {
@@ -998,6 +1000,7 @@ function startWorkerGame(worker, container) {
998
1000
  installMirror(message.name, message.epoch);
999
1001
  break;
1000
1002
  case "tn-worker-started":
1003
+ started = true;
1001
1004
  resolveReady();
1002
1005
  break;
1003
1006
  case "tn-worker-failed":
@@ -1040,8 +1043,12 @@ function startWorkerGame(worker, container) {
1040
1043
  };
1041
1044
  listen(worker, "message", onWorkerMessage);
1042
1045
  const onWorkerError = (event) => {
1043
- const message = event.message;
1044
- stop(new Error(message || `TN_WORKER_FAILED: worker ${event.type}.`));
1046
+ const error = event;
1047
+ const origin = [error.filename, error.lineno, error.colno].filter(Boolean).join(":");
1048
+ const message = `${error.message || `worker ${event.type}`}${origin ? ` (${origin})` : ""}`;
1049
+ if (started && !stopped)
1050
+ console.error(`TN_WORKER_FAILED: the running worker game stopped: ${message}`);
1051
+ stop(new Error(message));
1045
1052
  };
1046
1053
  listen(worker, "error", onWorkerError);
1047
1054
  listen(worker, "messageerror", onWorkerError);
package/dist/world.d.ts CHANGED
@@ -1,8 +1,9 @@
1
- import { Group, Vector3, BufferGeometry, Mesh, Object3D, LOD, Camera, Texture, Material, Data3DTexture, Box3 } from 'three';
2
- import { I as IComputeDriven, a as IGPUReadbackSample, b as ILodView, c as IModelLodPolicy } from './model-lod-B6BMqS1r.js';
3
- import { I as IRendererLike } from './renderer-DvFVoAgj.js';
4
- import { I as IAssetLoader } from './assets-YUbXa3-Y.js';
1
+ import { Group, Vector3, BufferGeometry, Mesh, Object3D, LOD, Camera, Matrix4, Material, Box3, Texture, Data3DTexture } from 'three';
2
+ import { I as IComputeDriven, a as IGPUReadbackSample, b as ILodView, c as IModelLodPolicy } from './model-lod-DPTzeCcD.js';
3
+ import { I as IRendererLike } from './renderer-BtOSseYf.js';
4
+ import { I as IAssetLoader } from './assets-CfMKnOsK.js';
5
5
  import { Node } from 'three/webgpu';
6
+ import './default-tone-mapping-GgKPTiBP.js';
6
7
 
7
8
  interface IWorldErosionOptions {
8
9
  readonly depositionRate: number;
@@ -403,6 +404,71 @@ declare class WaterBodies {
403
404
  footprintAt(x: number, z: number): IWaterFootprint | undefined;
404
405
  }
405
406
 
407
+ /** How a ribbon is cut; every value has the default `WaterBodies` and the Strata preview use. */
408
+ interface IRiverRibbonOptions {
409
+ /** Vertices across each station. Default 25. */
410
+ readonly columns?: number;
411
+ /** Reach either side of the centreline, per metre of channel width. Default `WATER_RIBBON_REACH`. */
412
+ readonly reach?: number;
413
+ /** Deepest water the `metres` attribute records. Default unbounded. */
414
+ readonly maxDepth?: number;
415
+ /** Metres of depth lost per metre toward the ribbon's edge, so the edges read shallow. Default 0.2. */
416
+ readonly edgeSlope?: number;
417
+ }
418
+ /**
419
+ * The water surface of every river, as one geometry with one group per river.
420
+ *
421
+ * Each station is a row across the river at its own surface height, out to `reach` widths either side
422
+ * of the centreline, the reach `WaterBodies` floods; one more row a reach past each end stands where
423
+ * `WaterBodies` clamps a segment, so the water a swimmer finds past a river's end is drawn there too
424
+ * (cut at the end station, the surface stopped in a straight edge with its carved bed dry beyond).
425
+ * Quads dry on both rows against `field` are dropped, so the surface ends at the shore.
426
+ * Past an end where the ground falls below the end's bed, the water would run off: that cap is not
427
+ * drawn, and the end stays cut at its last station.
428
+ *
429
+ * Attributes for the game's water material: `flow` (the unit downstream heading), `flowUv` (metres
430
+ * down the centreline, metres across it) and `metres` (water depth over the ground). It decides no
431
+ * colour, ripple or opacity: the game shades it.
432
+ *
433
+ * @situation draw a river's water surface from the baked stations
434
+ * @situation a river's water stops in a straight edge, or a swimmer floats where no water is drawn
435
+ * @situation share one river shape between the drawn water and the swimmer
436
+ * @situation river water hangs over dry ground past the river's head or tail
437
+ * @constraint stations, width and reach come from the game's bake; the game's material shades the geometry
438
+ * @example const geometry = riverRibbonGeometry(rivers, field, { maxDepth: 1.6 });
439
+ */
440
+ declare function riverRibbonGeometry(rivers: readonly {
441
+ readonly points: readonly (readonly number[])[];
442
+ readonly width: number;
443
+ }[], field: Heightfield, options?: IRiverRibbonOptions): BufferGeometry;
444
+ /** How a lake's disc is meshed; every default is the Strata preview's. */
445
+ interface ILakeSurfaceOptions {
446
+ /** Rings from the centre to the reach. Default 44. */
447
+ readonly rings?: number;
448
+ /** Vertices around each ring. Default 88. */
449
+ readonly spokes?: number;
450
+ /** How the ring spacing grows outwards; above 1 packs vertices into the near water. Default 1.7. */
451
+ readonly packing?: number;
452
+ /** Deepest water the `metres` attribute records. Default unbounded. */
453
+ readonly maxDepth?: number;
454
+ }
455
+ /**
456
+ * A lake's water surface: a level disc out to `lakeReach`, the footprint `WaterBodies` floods, with a
457
+ * `metres` attribute (water depth over the ground). Only cells with a corner the seed's water reaches
458
+ * get triangles, so the surface does not hover over dry hillside, a hollow past the basin's rim (a
459
+ * river valley beyond the dam) stays dry instead of standing under a sheet that stops where the reach
460
+ * does, and the shore follows the ground's contour. The
461
+ * rings pack towards the middle, so an irregular basin costs vertices where the camera sees them.
462
+ * Returns `undefined` when the basin holds no water at its level.
463
+ *
464
+ * @situation draw a lake's water surface from the baked level and seed
465
+ * @situation a lake's drawn water and the swimmer's water disagree
466
+ * @situation lake water ends in a straight edge over a valley past the basin's rim
467
+ * @constraint the lake row and field come from the game's bake; the game's material shades the geometry
468
+ * @example const geometry = lakeSurfaceGeometry({ ...lake, margin: 1.12 }, field, { maxDepth: 1.6 });
469
+ */
470
+ declare function lakeSurfaceGeometry(lake: IWaterLake, field: Heightfield, options?: ILakeSurfaceOptions): BufferGeometry | undefined;
471
+
406
472
  /**
407
473
  * The terrain geometry `TerrainTiles` builds and keeps: level meshes, skirts, edges, stitch strips and
408
474
  merged blocks. Split out of `world-tiles.ts` verbatim (PRD-797).
@@ -493,6 +559,17 @@ interface IWorldTilesOptions {
493
559
  readonly minX: number;
494
560
  readonly minZ: number;
495
561
  };
562
+ /**
563
+ * A region another surface already draws and collides, in tile-local metres: a tile wholly inside
564
+ * it is never meshed and gets no collider. A tile that only overlaps it is meshed whole; the game
565
+ * hides the overlap in its own surface.
566
+ */
567
+ readonly hole?: {
568
+ readonly maxX: number;
569
+ readonly maxZ: number;
570
+ readonly minX: number;
571
+ readonly minZ: number;
572
+ };
496
573
  /** How deep each edge skirt extends below its surface. Defaults to one tile width. */
497
574
  readonly skirtDepth?: number;
498
575
  /** Square tile neighborhood to consider around the followed point. Defaults to 1. */
@@ -532,6 +609,8 @@ interface IWorldTilesOptions {
532
609
  * @situation stream terrain without cracks
533
610
  * @situation keep generated terrain resident around a moving player
534
611
  * @situation put a generated terrain tile into a game-owned physics world
612
+ * @situation a hole or a flicker where streamed terrain tiles are still building (`settledHalf`)
613
+ * @situation split the ground between streamed tiles and a far mesh around the player (`settledHalf`)
535
614
  * @alias stream terrain across chunks
536
615
  * @constraint sampleHeight and surface are required game choices; no landform or surface preset is installed
537
616
  * @constraint residentTileBudget and residentByteBudget are hard caps; a tile that cannot fit throws
@@ -626,6 +705,19 @@ declare class TerrainTiles extends Object3D implements IComputeDriven {
626
705
  get deferredAdmissions(): number;
627
706
  get warmupNodes(): readonly unknown[];
628
707
  getTile(key: string): IWorldTile | undefined;
708
+ /**
709
+ * Half-width, in metres, of the largest square of tiles around `position`'s tile that is fully
710
+ * settled: each tile in it is resident, or is one the stream never draws (wholly inside `hole` or
711
+ * past `extent`). Zero while the tile under `position` is still building. A game that draws other
712
+ * ground where the tiles have not arrived (a collar, a far mesh) clips it to this square, so a tile
713
+ * still building shows that ground, never a hole.
714
+ *
715
+ * @situation a hole or a flicker where streamed terrain tiles are still building
716
+ * @situation split the ground between streamed tiles and a far mesh around the player
717
+ * @constraint reads residency only; call it after `follow` in the same frame
718
+ * @example split.half.value = tiles.settledHalf(player.position);
719
+ */
720
+ settledHalf(position: Pick<Vector3, "x" | "z">): number;
629
721
  /**
630
722
  * Move residency to the followed point: admit, evict and re-level every tile.
631
723
  *
@@ -656,19 +748,183 @@ declare class TerrainTiles extends Object3D implements IComputeDriven {
656
748
  }
657
749
 
658
750
  /**
659
- * The oracle for terrain geometry that is otherwise trusted every frame.
751
+ * One frame's admission allowance, shared by every path that puts streamed content on screen.
752
+ *
753
+ * A streaming world has no frame-time ceiling anywhere else: a cell row arriving builds a batch per
754
+ * asset run over every placement in it, a terrain tile builds every LOD level, and the game's
755
+ * `createCollider` runs for every resident tile — all in the one frame that discovers them. That is
756
+ * the 100-330 ms hitch a 60 m/s camera feels every time the ring moves, and it is admission cost,
757
+ * not streaming: the loads never fail.
758
+ *
759
+ * The budget is opened once per `update` and drawn down by the units it admits. A unit always
760
+ * finishes, so a frame spends at most the limit plus the unit that crossed it, and the rest of the
761
+ * backlog waits for the next frame rather than being dropped.
762
+ *
763
+ * @situation streamed terrain tiles or cells hitch the frame that admits them
764
+ * @situation cap how many milliseconds a frame spends building streamed content
765
+ * @constraint open a new budget each frame; a unit always finishes, so one unit can cross the limit
766
+ * @example tiles.follow(player.position, new AdmissionBudget(2, () => performance.now()));
767
+ */
768
+ declare class AdmissionBudget implements IAdmissionBudget {
769
+ #private;
770
+ constructor(limitMs: number, now: () => number);
771
+ get spentMs(): number;
772
+ admit(work: () => void): boolean;
773
+ }
774
+
775
+ /** How the shore field reads open water; every default is the Strata coastal world's. */
776
+ interface IShoreFieldOptions {
777
+ /** Water must be this many metres deep for open-sea exposure to flood through it. Default 2. */
778
+ readonly openDepth?: number;
779
+ /** Metres of shallow water that exposure still carries into, never across dry ground. Default 18. */
780
+ readonly carry?: number;
781
+ }
782
+ /** Per grid node: metres to the nearest dry node, and 1 where the open sea reaches. */
783
+ interface IShoreField {
784
+ readonly distance: Float32Array;
785
+ readonly exposed: Uint8Array;
786
+ }
787
+ /**
788
+ * Distance to the shore and open-sea exposure for every node of a square height grid, measured once
789
+ * from the bake. `distance` is a two-pass chamfer distance to the nearest node at or above `level`
790
+ * (0 on dry ground). `exposed` floods from the grid's edge through water deeper than `openDepth`,
791
+ * then `carry` metres further into shallow water, so a sheltered lagoon behind a sand bar stays out
792
+ * of it. Both feed the game's surf and shore masks; neither decides a colour.
793
+ *
794
+ * @situation surf breaks only on water open to the sea, not in a sheltered lagoon
795
+ * @situation distance from each water cell to the shore, for a foam or depth mask
796
+ * @constraint heights are row-major, `resolution` by `resolution`, across `size` metres; measured once, never per frame
797
+ * @example const { distance, exposed } = shoreField(world.heights, world.resolution, world.size, world.waterLevel);
798
+ */
799
+ declare function shoreField(heights: ArrayLike<number>, resolution: number, size: number, level: number, options?: IShoreFieldOptions): IShoreField;
800
+
801
+ /** The drawn surface's height under a world point, or `null` where the sampler cannot answer. */
802
+ type SurfaceSampler = (x: number, z: number) => number | null;
803
+ /**
804
+ * `Heightfield.surfaceAt` under the transform the game draws the field's mesh with, so a prop or a
805
+ * player stands on the triangles the eye sees rather than on the bilinear field between them.
806
+ * Answers `null` outside the field and for a transform it does not model (any rotation, or an
807
+ * unequal scale), so the caller keeps its own fallback there.
808
+ *
809
+ * @situation stand props or a player on the drawn terrain triangles under a moved or scaled mesh
810
+ * @situation props float or sink where the terrain mesh is drawn under a transform
811
+ * @constraint the mesh is `field.toGeometry()` drawn upright under a uniform scale; read `matrixWorld` after it settles
812
+ * @example const ground = surfaceSampler(field, mesh.matrixWorld); const y = ground(x, z) ?? fallback;
813
+ */
814
+ declare function surfaceSampler(field: Heightfield, matrixWorld: Matrix4): SurfaceSampler;
815
+
816
+ /** Ground height under a world point, or `null` where no ground answers. */
817
+ type StaticGroundQuery = (x: number, z: number) => number | null;
818
+ /**
819
+ * Exact lowest world Y of a static geometry under `matrix`, the precise measurement `GroundSnap`
820
+ * audits against, cheap enough for a load that poses hundreds of thousands of props. An upright
821
+ * pose reads the bounding box. A tilted pose scans the vertices bottom first (sorted once per
822
+ * geometry) and stops once no later vertex can be lower: `|x e1 + z e9| <= reach * hypot(e1, e9)`.
823
+ *
824
+ * @situation stand a scattered rock, tree or crate on the ground by its lowest point, not its origin
825
+ * @situation props hover or sink because their pivot is not at their base
826
+ * @constraint static geometry only; a skinned model uses `GroundSnap`; the sort is cached per geometry, so do not mutate its positions
827
+ * @example placed.position.y += ground - staticLowestY(geometry, matrix);
828
+ */
829
+ declare function staticLowestY(geometry: BufferGeometry, matrix: Matrix4): number;
830
+ /**
831
+ * How far the flat underside of a static geometry rises above the ground at its highest point.
832
+ * Snapping the lowest point leaves the downhill side of a flat-bottomed rock hanging; sinking the
833
+ * pose by this much buries the whole footprint. Returns 0 when the footprint is already buried.
834
+ *
835
+ * @situation a rock snapped to a slope shows a lip or a gap under its downhill side
836
+ * @constraint the footprint is every vertex at the geometry's lowest local y; throws `TN_STATIC_POSE_GROUND` where the ground does not answer
837
+ * @example matrix.elements[13] -= footprintGap(geometry, matrix, ground, 0.08);
838
+ */
839
+ declare function footprintGap(geometry: BufferGeometry, matrix: Matrix4, ground: StaticGroundQuery, margin?: number): number;
840
+ /** What `baseRingGap` measured around a wide static model. */
841
+ interface IBaseRing {
842
+ /** The largest height of a sector's lowest rim vertex above its ground, in metres. */
843
+ readonly gap: number;
844
+ /** Sectors that held a rim vertex. */
845
+ readonly samples: number;
846
+ }
847
+ /**
848
+ * The highest gap between a wide model's rim and the ground, one sample per angular sector: in
849
+ * each sector, the lowest vertex beyond `rim` of that sector's reach. A narrow buried stem then
850
+ * cannot hold a wide base up in the air on the downhill side. Sink the pose by `gap` (plus any
851
+ * burial the game wants) to close it.
852
+ *
853
+ * @situation a cliff or crag model rests on a buried stem while its wide base hangs over the downhill ground
854
+ * @constraint throws `TN_STATIC_POSE_GROUND` where the ground does not answer; check `samples` before trusting `gap`
855
+ * @example const ring = baseRingGap(geometry, matrix, ground); if (ring.samples >= 4) matrix.elements[13] -= ring.gap + 0.5;
856
+ */
857
+ declare function baseRingGap(geometry: BufferGeometry, matrix: Matrix4, ground: StaticGroundQuery, options?: {
858
+ readonly sectors?: number;
859
+ readonly rim?: number;
860
+ }): IBaseRing;
861
+
862
+ /** One material section of a mesh: the whole mesh, or one group of a multi-material mesh. */
863
+ interface IMeshSection {
864
+ readonly material: Material;
865
+ readonly group?: {
866
+ readonly start: number;
867
+ readonly count: number;
868
+ };
869
+ }
870
+ /**
871
+ * A mesh's material sections: one per geometry group for a material array, else the whole mesh.
872
+ * Instanced props draw one batch per material, so an imported model splits here first.
660
873
  *
661
- * `TerrainTiles` re-derives what it already knows — every rendered vertex checked for finiteness,
662
- * every resident seam re-measured, every LOD blend's visible displacement sampled — and that is a
663
- * measurement, not a mechanism: on a 289-tile ring a six-second walk paid ~270 ms in three loops
664
- * that only throw when something is already broken. So it is off by default and the shipped frame
665
- * trusts the cheap change detector instead, which compares buffer versions and the residency and
666
- * LOD state the class writes itself.
874
+ * @situation scatter or instance an imported glTF model that has several materials
875
+ * @constraint a section's `material` can be `undefined` for a group naming a missing material slot; skip it
876
+ * @example for (const section of meshSections(mesh)) parts.push(sectionGeometry(mesh, box, section));
877
+ */
878
+ declare function meshSections(mesh: Mesh): IMeshSection[];
879
+ /**
880
+ * One section's geometry in model space, standing on y = 0. Every section of a model takes the same
881
+ * base from the whole model's `box`, so a crown keeps its place on its trunk: basing each section on
882
+ * its own bounds detaches them. The mesh's LOD0 geometry is cloned under its world matrix, and a
883
+ * group becomes the clone's draw range.
884
+ *
885
+ * @situation the crown of an instanced tree floats off its trunk, or the parts of a model separate
886
+ * @situation turn each part of an imported model into a geometry for an instanced prop batch
887
+ * @constraint `box` is the whole model's world bounds after any unit normalisation; call `mesh.updateWorldMatrix` first
888
+ * @example const box = new Box3().setFromObject(root); const geometry = sectionGeometry(mesh, box, section);
889
+ */
890
+ declare function sectionGeometry(mesh: Mesh, box: Box3, section: IMeshSection, options?: {
891
+ readonly centreXZ?: boolean;
892
+ }): BufferGeometry;
893
+ /**
894
+ * Recompute the normals of a geometry whose normals are missing, zero or not finite, and leave
895
+ * authored normals alone. Some exported art ships zero normals and draws black under any light.
896
+ * Run it after any reshape, so the recomputed normals fit the final shape.
667
897
  *
668
- * `TN_TERRAIN_VALIDATE=1`, `?tnTerrainValidate=1`, or `validate: true` on the constructor puts the
669
- * loops back and every assertion with them. It is a validation mode, not a proof: it proves the
670
- * frames it ran on.
898
+ * @situation an imported model draws black or unlit because it ships zero normals
899
+ * @constraint one bad normal recomputes them all; an intentionally hard-edged model loses its authored split normals only if one is bad
900
+ * @example geometry.scale(1.1, 1, 1.1); repairZeroNormals(geometry);
671
901
  */
902
+ declare function repairZeroNormals(geometry: BufferGeometry): boolean;
903
+
904
+ /** How long `warmUnculled` keeps a subtree drawing whole. */
905
+ interface IWarmUnculledOptions {
906
+ /** World draws to spend once `when` holds before the subtree is culled again. Default 2. */
907
+ readonly draws?: number;
908
+ /** Counts a draw only while this holds, such as "every tile around the spawn is resident". */
909
+ readonly when?: () => boolean;
910
+ }
911
+ /**
912
+ * Draw `root` with frustum culling off until it has drawn `draws` times, then cull it again and
913
+ * resolve. A pipeline is built by its first real draw (a startup warm-up compiles a different pass),
914
+ * so content the spawn view does not see — streamed tiles behind the player, a mirror that draws only
915
+ * when its water does — builds its pipelines after the reveal and hitches the first frames that see
916
+ * it. Join the promise to the loading curtain to build them behind it. Objects that join `root`
917
+ * while it warms draw unculled too.
918
+ *
919
+ * @situation the first frames after the loading curtain hitch on pipeline builds for content behind the camera
920
+ * @situation streamed terrain or a lake compiles its pipelines after the reveal
921
+ * @constraint `ctx.beforeRender` runs on every world draw, also behind the curtain; join the promise to the curtain's hold
922
+ * @example const warm = warmUnculled(ctx, lake.mesh); ctx.startup.hold("lake", () => warm);
923
+ */
924
+ declare function warmUnculled(ctx: {
925
+ beforeRender(callback: () => void): void;
926
+ }, root: Object3D, options?: IWarmUnculledOptions): Promise<void>;
927
+
672
928
  /** Marker printed when terrain validation is on, so a log says which mode produced it. */
673
929
  declare const TERRAIN_VALIDATE_MARKER = "TN_TERRAIN_VALIDATE";
674
930
  /** The launch flag. */
@@ -943,6 +1199,7 @@ declare function snowDiscFootprint(radius: number, options?: ISnowDiscFootprintO
943
1199
  * recovery. It is a heightfield approximation — not granular snow, displaced-volume
944
1200
  * conservation, avalanches, melting or a calibrated material law.
945
1201
  * @situation leave footprints, tracks and tyre ruts in snow that persist and fill in over time
1202
+ * @situation let a fresh snowfall slowly fill older tracks back in as the field recovers
946
1203
  * @situation let a pushed sphere carve a connected track and a dropped one settle into a crater
947
1204
  * @situation store snow deformation that rendered geometry and collision both read
948
1205
  * @situation reset a snowfield between rounds or change its depth at runtime
@@ -1685,6 +1942,13 @@ interface IWorldCellsLoadOptions {
1685
1942
  * loader works. The url is the authored one, so a compiled package wants `assets` instead.
1686
1943
  */
1687
1944
  readonly loadModel?: (url: string) => Promise<Object3D>;
1945
+ /**
1946
+ * The game's surface for one loaded part, given the authored material and the part's geometry: a
1947
+ * swaying tree returns its own node material reading the baked wind attribute. Return the material
1948
+ * passed in to keep it. The game memoises per source material, so every level and placement of an
1949
+ * asset shares one surface; this world releases it with the asset's own.
1950
+ */
1951
+ readonly partMaterial?: (material: Material, geometry: BufferGeometry) => Material;
1688
1952
  /**
1689
1953
  * Model loads in flight at once, assets and chunks together. Defaults to `loadAll`'s
1690
1954
  * `concurrency`, six.
@@ -2190,7 +2454,7 @@ declare function instanceRandom(): Node<"float">;
2190
2454
  * @constraint SkinnedMesh parts are skipped; an instanced copy would draw one rest pose
2191
2455
  * @constraint 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
2192
2456
  * @constraint eligible static sources can use cooked HLOD (chunk-only alongside GPU scatter, whole-cell on CPU) after compilation and an observed main-context backend submission; projected-error hysteresis requires actual source triangle reduction and no extra material draws, unsupported or shared source stays resident, and collision/shadow paths retain source representations; stats().hlod counts lifecycle and charged resources, not GPU timing or physical allocation
2193
- * @override `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
2457
+ * @override `hlod: false` keeps source rendering; `partMaterial` gives a part the game's own surface (a swaying tree); 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
2194
2458
  * @constraint `prewarmed` resolves once every prewarmed shared batch has been drawn; a game with a loading screen waits on it, and `stats().pendingPrewarm` is the same gate as a number
2195
2459
  * @constraint every `asset:level:part` is one InstancedMesh for the main pass, plus one caster InstancedMesh per world-grid square of `clusterSize` on the shadow caster layer, so the main pass draws one mesh per key and a shadow level submits only the squares it covers
2196
2460
  * @constraint two definitions the asset loader resolves to one model — the same cooked `glb`, the same `lods` at the same distances, the same `maxDistance` and bounds — are one asset under the lexicographically smallest id: one model load, one set of `asset:level:part` keys, one prewarm and one refcount, released when the last cell holding any member of the group leaves the ring; `TN_WORLD_ASSET_ALIAS` reports how many of the package's assets are really distinct
@@ -2304,4 +2568,4 @@ declare class WorldCells extends Group implements IComputeDriven {
2304
2568
  dispose(): void;
2305
2569
  }
2306
2570
 
2307
- export { Heightfield, HeightfieldCollar, type IAdmissionBudget, type IHeightfieldChangeTracker, type IHeightfieldCollarOptions, type IHeightfieldCollarQuad, type IHeightfieldCollarSite, type IHeightfieldCollarWalk, type IHeightfieldOptions, type IHeightfieldOrigin, type IHeightfieldRegion, type IHeightfieldRegionBounds, type IHeightfieldSamplerOptions, type IHeightfieldWorldPassOptions, type ILoadTerrainSplatOptions, type IShadowRegion, type ISnowContact, type ISnowFieldOptions, type ISnowFieldSample, type ISnowFootprint, type ISnowFootprintSample, type ITerrainSplatLayer, type ITerrainSplatMaskedLayer, type ITerrainSplatMaterialContext, type ITerrainSplatSample, type ITerrainSplatSampleContext, type ITerrainSplatTable, type ITerrainSplatWeightContext, type IWaterBodiesOptions, type IWaterCurrent, type IWaterFootprint, type IWaterLake, type IWaterOcean, type IWaterRibbon, type IWorldAsset, type IWorldAssetBounds, type IWorldAssetLod, type IWorldCapabilities, type IWorldCell, type IWorldCellProxy, type IWorldCellsBudget, type IWorldCellsFollow, type IWorldCellsLoadOptions, type IWorldCellsStats, type IWorldCellsTerrainOptions, type IWorldExtent, type IWorldGpuFrameValidation, type IWorldPackage, type IWorldPackageError, type IWorldPackageValidationOptions, type IWorldRegionReadiness, type IWorldRun, type IWorldTerrain, type IWorldTileColliderInput, type IWorldTilesTopologyObservation, NOISE_PERIOD, NOISE_TEXELS, SnowField, TERRAIN_VALIDATE_FLAG, TERRAIN_VALIDATE_MARKER, TerrainTiles, WATER_RIBBON_REACH, WaterBodies, type WaterBodyKind, WorldCells, type WorldPackageErrorCode, applyTerrainSurface, bakedFractalNoise, bakedNoise, cellPlacements, getWorldCapabilities, heightSamplerFromHeightmap, instanceRandom, lakeReach, loadTerrainSplat, loadWorldHeightmap, noiseVolume, snowDiscFootprint, terrainValidationRequested, validateWorldPackage, waterlineRadius };
2571
+ export { AdmissionBudget, Heightfield, HeightfieldCollar, type IAdmissionBudget, type IBaseRing, type IHeightfieldChangeTracker, type IHeightfieldCollarOptions, type IHeightfieldCollarQuad, type IHeightfieldCollarSite, type IHeightfieldCollarWalk, type IHeightfieldOptions, type IHeightfieldOrigin, type IHeightfieldRegion, type IHeightfieldRegionBounds, type IHeightfieldSamplerOptions, type IHeightfieldWorldPassOptions, type ILakeSurfaceOptions, type ILoadTerrainSplatOptions, type IMeshSection, type IRiverRibbonOptions, type IShadowRegion, type IShoreField, type IShoreFieldOptions, type ISnowContact, type ISnowFieldOptions, type ISnowFieldSample, type ISnowFootprint, type ISnowFootprintSample, type ITerrainSplatLayer, type ITerrainSplatMaskedLayer, type ITerrainSplatMaterialContext, type ITerrainSplatSample, type ITerrainSplatSampleContext, type ITerrainSplatTable, type ITerrainSplatWeightContext, type IWarmUnculledOptions, type IWaterBodiesOptions, type IWaterCurrent, type IWaterFootprint, type IWaterLake, type IWaterOcean, type IWaterRibbon, type IWorldAsset, type IWorldAssetBounds, type IWorldAssetLod, type IWorldCapabilities, type IWorldCell, type IWorldCellProxy, type IWorldCellsBudget, type IWorldCellsFollow, type IWorldCellsLoadOptions, type IWorldCellsStats, type IWorldCellsTerrainOptions, type IWorldExtent, type IWorldGpuFrameValidation, type IWorldPackage, type IWorldPackageError, type IWorldPackageValidationOptions, type IWorldRegionReadiness, type IWorldRun, type IWorldTerrain, type IWorldTileColliderInput, type IWorldTilesTopologyObservation, NOISE_PERIOD, NOISE_TEXELS, SnowField, type StaticGroundQuery, type SurfaceSampler, TERRAIN_VALIDATE_FLAG, TERRAIN_VALIDATE_MARKER, TerrainTiles, WATER_RIBBON_REACH, WaterBodies, type WaterBodyKind, WorldCells, type WorldPackageErrorCode, applyTerrainSurface, bakedFractalNoise, bakedNoise, baseRingGap, cellPlacements, footprintGap, getWorldCapabilities, heightSamplerFromHeightmap, instanceRandom, lakeReach, lakeSurfaceGeometry, loadTerrainSplat, loadWorldHeightmap, meshSections, noiseVolume, repairZeroNormals, riverRibbonGeometry, sectionGeometry, shoreField, snowDiscFootprint, staticLowestY, surfaceSampler, terrainValidationRequested, validateWorldPackage, warmUnculled, waterlineRadius };