@threenative/core 0.3.12 → 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 (150) hide show
  1. package/README.md +1 -1
  2. package/capabilities.json +746 -32
  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-4SRAQFTU.js} +1 -1
  6. package/dist/{chunk-GMHATRPW.js → chunk-DIPIJICH.js} +1590 -375
  7. package/dist/{chunk-OKXUCASC.js → chunk-EEABDLUC.js} +3 -4
  8. package/dist/{chunk-5O73CDMR.js → chunk-EFWZWLPY.js} +62 -16
  9. package/dist/{chunk-N5LRP4BR.js → chunk-GYUZJQ7U.js} +63 -3
  10. package/dist/{chunk-VAZM36TV.js → chunk-H4J6IAJE.js} +17 -10
  11. package/dist/{chunk-2Z44XSI2.js → chunk-SV4QVUTQ.js} +3 -7
  12. package/dist/{chunk-DBELTTTM.js → chunk-U4YHUKKL.js} +1 -1
  13. package/dist/chunk-VP43GIWW.js +18 -0
  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 +289 -1034
  20. package/dist/index.js +3096 -1305
  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-BYqKGAwo.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 +269 -15
  33. package/dist/world.js +1372 -628
  34. package/mcp/animation-server.mjs +1 -1
  35. package/mcp/engine-server.mjs +105 -7
  36. package/mcp/servers.mjs +4 -4
  37. package/package.json +10 -6
  38. package/src/animation-batch.ts +193 -0
  39. package/src/animation-layers.ts +7 -3
  40. package/src/animation.ts +209 -29
  41. package/src/asset-cache.ts +3 -3
  42. package/src/asset-memo.ts +202 -0
  43. package/src/assets.ts +436 -131
  44. package/src/auto-batch.ts +190 -44
  45. package/src/compute-driven.ts +1 -1
  46. package/src/config.ts +8 -0
  47. package/src/debug.ts +103 -22
  48. package/src/dev-global.ts +54 -0
  49. package/src/engine-hooks.ts +37 -0
  50. package/src/frame-budget.ts +19 -3
  51. package/src/game-boot-phase.ts +269 -0
  52. package/src/game-dev-tools.ts +7 -14
  53. package/src/game-frame-loop.ts +45 -82
  54. package/src/game-startup.ts +145 -70
  55. package/src/game-ui.ts +84 -0
  56. package/src/game.ts +168 -552
  57. package/src/gamepad-mappings.ts +269 -0
  58. package/src/generated/console-markers.ts +13 -0
  59. package/src/geometry-capture.ts +28 -4
  60. package/src/gpu-readings.ts +98 -0
  61. package/src/gpu-scene-bvh.ts +149 -36
  62. package/src/hot.ts +4 -7
  63. package/src/index.ts +115 -8
  64. package/src/input.ts +237 -25
  65. package/src/instanced-batch-lod.ts +3 -8
  66. package/src/interpolation.ts +171 -40
  67. package/src/look/ao-admission.ts +4 -3
  68. package/src/look/auto-exposure.ts +5 -16
  69. package/src/look/default-tone-mapping.ts +41 -5
  70. package/src/look/local-exposure.ts +2 -7
  71. package/src/look/quad-pass.ts +21 -0
  72. package/src/look/quality.ts +4 -0
  73. package/src/look/unreal-bloom.ts +4 -13
  74. package/src/look/world-environment.ts +58 -115
  75. package/src/merge-parts.ts +20 -24
  76. package/src/model-lod.ts +97 -14
  77. package/src/particle-significance.ts +12 -0
  78. package/src/particles.ts +19 -10
  79. package/src/platform.ts +23 -4
  80. package/src/profiling/FrameStages.ts +5 -6
  81. package/src/profiling/Spans.ts +3 -17
  82. package/src/profiling/debug-telemetry.ts +2 -6
  83. package/src/profiling/render-list-validate.ts +6 -15
  84. package/src/projection-marker.ts +2 -1
  85. package/src/quiet-markers.ts +3 -10
  86. package/src/render/cpu-bvh.ts +100 -0
  87. package/src/render/depth-pyramid.ts +6 -14
  88. package/src/render/environment/environmentContribution.ts +202 -0
  89. package/src/render/environment/environmentRadiance.ts +44 -0
  90. package/src/render/environment/environmentSampleCache.ts +56 -0
  91. package/src/render/environment/environmentSampling.ts +201 -0
  92. package/src/render/environment/environmentSnapshot.ts +71 -0
  93. package/src/render/environment/gate.ts +57 -0
  94. package/src/render/mesh-pool.ts +3 -19
  95. package/src/render/probe-trace.ts +872 -0
  96. package/src/render/probe-volume.ts +780 -34
  97. package/src/render/radiance-cache.ts +17 -0
  98. package/src/render/virtual-shadow-partial.ts +13 -0
  99. package/src/render/virtual-shadow.ts +18 -16
  100. package/src/render/world-impostor-surface.ts +109 -6
  101. package/src/render/world-impostor.ts +5 -2
  102. package/src/render-camera-cull.ts +98 -3
  103. package/src/render-environment.ts +41 -0
  104. package/src/renderer-config.ts +36 -0
  105. package/src/renderer-facts.ts +37 -0
  106. package/src/renderer.ts +52 -28
  107. package/src/resolution-scaler.ts +3 -2
  108. package/src/scene-entry-inspectors.ts +61 -0
  109. package/src/snow-field.ts +1 -0
  110. package/src/startup-offscreen-bytes.ts +78 -0
  111. package/src/static-transform.ts +25 -19
  112. package/src/streamed-textures.ts +112 -0
  113. package/src/streaming.ts +68 -4
  114. package/src/texture-streaming.ts +331 -0
  115. package/src/version.ts +1 -1
  116. package/src/worker.ts +12 -2
  117. package/src/world-bundle-safety.ts +55 -10
  118. package/src/world-cell-batches.ts +162 -200
  119. package/src/world-cell-chunks.ts +3 -7
  120. package/src/world-cell-impostors.ts +20 -8
  121. package/src/world-cell-options.ts +2 -14
  122. package/src/world-cell-placements.ts +194 -90
  123. package/src/world-cell-prewarm.ts +39 -4
  124. package/src/world-cell-records.ts +401 -0
  125. package/src/world-cell-render-bundles.ts +2 -2
  126. package/src/world-cell-render-gpu-dress.ts +13 -17
  127. package/src/world-cell-render-main-cull.ts +73 -17
  128. package/src/world-cell-render-util.ts +17 -4
  129. package/src/world-cell-render.ts +13 -5
  130. package/src/world-cell-residency.ts +15 -6
  131. package/src/world-cell-stale.ts +238 -0
  132. package/src/world-cells.ts +22 -5
  133. package/src/world-gpu-flags.ts +18 -50
  134. package/src/world-gpu-reference.ts +22 -8
  135. package/src/world-gpu-scene.ts +44 -24
  136. package/src/world-gpu-shadow.ts +21 -8
  137. package/src/world-gpu-types.ts +41 -13
  138. package/src/world-load-limiter.ts +5 -0
  139. package/src/world-model-sections.ts +80 -0
  140. package/src/world-river-ribbon.ts +282 -0
  141. package/src/world-root-frame.ts +39 -0
  142. package/src/world-shore-field.ts +91 -0
  143. package/src/world-static-pose.ts +163 -0
  144. package/src/world-surface-sampler.ts +48 -0
  145. package/src/world-terrain-splat.ts +10 -18
  146. package/src/world-tile-budget.ts +4 -11
  147. package/src/world-tiles.ts +79 -12
  148. package/src/world-validate.ts +6 -14
  149. package/src/world-warm.ts +51 -0
  150. 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-4SRAQFTU.js';
2
+ import './chunk-GYUZJQ7U.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-SV4QVUTQ.js';
2
+ import { debugRequested, countDebug } from './chunk-GYUZJQ7U.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,68 @@ 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 water at a corner get triangles,
458
+ * so the surface does not hover over dry hillside and the shore follows the ground's contour. The
459
+ * rings pack towards the middle, so an irregular basin costs vertices where the camera sees them.
460
+ * Returns `undefined` when the basin holds no water at its level.
461
+ *
462
+ * @situation draw a lake's water surface from the baked level and seed
463
+ * @situation a lake's drawn water and the swimmer's water disagree
464
+ * @constraint the lake row and field come from the game's bake; the game's material shades the geometry
465
+ * @example const geometry = lakeSurfaceGeometry({ ...lake, margin: 1.12 }, field, { maxDepth: 1.6 });
466
+ */
467
+ declare function lakeSurfaceGeometry(lake: IWaterLake, field: Heightfield, options?: ILakeSurfaceOptions): BufferGeometry | undefined;
468
+
406
469
  /**
407
470
  * The terrain geometry `TerrainTiles` builds and keeps: level meshes, skirts, edges, stitch strips and
408
471
  merged blocks. Split out of `world-tiles.ts` verbatim (PRD-797).
@@ -493,6 +556,17 @@ interface IWorldTilesOptions {
493
556
  readonly minX: number;
494
557
  readonly minZ: number;
495
558
  };
559
+ /**
560
+ * A region another surface already draws and collides, in tile-local metres: a tile wholly inside
561
+ * it is never meshed and gets no collider. A tile that only overlaps it is meshed whole; the game
562
+ * hides the overlap in its own surface.
563
+ */
564
+ readonly hole?: {
565
+ readonly maxX: number;
566
+ readonly maxZ: number;
567
+ readonly minX: number;
568
+ readonly minZ: number;
569
+ };
496
570
  /** How deep each edge skirt extends below its surface. Defaults to one tile width. */
497
571
  readonly skirtDepth?: number;
498
572
  /** Square tile neighborhood to consider around the followed point. Defaults to 1. */
@@ -532,6 +606,8 @@ interface IWorldTilesOptions {
532
606
  * @situation stream terrain without cracks
533
607
  * @situation keep generated terrain resident around a moving player
534
608
  * @situation put a generated terrain tile into a game-owned physics world
609
+ * @situation a hole or a flicker where streamed terrain tiles are still building (`settledHalf`)
610
+ * @situation split the ground between streamed tiles and a far mesh around the player (`settledHalf`)
535
611
  * @alias stream terrain across chunks
536
612
  * @constraint sampleHeight and surface are required game choices; no landform or surface preset is installed
537
613
  * @constraint residentTileBudget and residentByteBudget are hard caps; a tile that cannot fit throws
@@ -626,6 +702,19 @@ declare class TerrainTiles extends Object3D implements IComputeDriven {
626
702
  get deferredAdmissions(): number;
627
703
  get warmupNodes(): readonly unknown[];
628
704
  getTile(key: string): IWorldTile | undefined;
705
+ /**
706
+ * Half-width, in metres, of the largest square of tiles around `position`'s tile that is fully
707
+ * settled: each tile in it is resident, or is one the stream never draws (wholly inside `hole` or
708
+ * past `extent`). Zero while the tile under `position` is still building. A game that draws other
709
+ * ground where the tiles have not arrived (a collar, a far mesh) clips it to this square, so a tile
710
+ * still building shows that ground, never a hole.
711
+ *
712
+ * @situation a hole or a flicker where streamed terrain tiles are still building
713
+ * @situation split the ground between streamed tiles and a far mesh around the player
714
+ * @constraint reads residency only; call it after `follow` in the same frame
715
+ * @example split.half.value = tiles.settledHalf(player.position);
716
+ */
717
+ settledHalf(position: Pick<Vector3, "x" | "z">): number;
629
718
  /**
630
719
  * Move residency to the followed point: admit, evict and re-level every tile.
631
720
  *
@@ -656,19 +745,183 @@ declare class TerrainTiles extends Object3D implements IComputeDriven {
656
745
  }
657
746
 
658
747
  /**
659
- * The oracle for terrain geometry that is otherwise trusted every frame.
748
+ * One frame's admission allowance, shared by every path that puts streamed content on screen.
749
+ *
750
+ * A streaming world has no frame-time ceiling anywhere else: a cell row arriving builds a batch per
751
+ * asset run over every placement in it, a terrain tile builds every LOD level, and the game's
752
+ * `createCollider` runs for every resident tile — all in the one frame that discovers them. That is
753
+ * the 100-330 ms hitch a 60 m/s camera feels every time the ring moves, and it is admission cost,
754
+ * not streaming: the loads never fail.
755
+ *
756
+ * The budget is opened once per `update` and drawn down by the units it admits. A unit always
757
+ * finishes, so a frame spends at most the limit plus the unit that crossed it, and the rest of the
758
+ * backlog waits for the next frame rather than being dropped.
759
+ *
760
+ * @situation streamed terrain tiles or cells hitch the frame that admits them
761
+ * @situation cap how many milliseconds a frame spends building streamed content
762
+ * @constraint open a new budget each frame; a unit always finishes, so one unit can cross the limit
763
+ * @example tiles.follow(player.position, new AdmissionBudget(2, () => performance.now()));
764
+ */
765
+ declare class AdmissionBudget implements IAdmissionBudget {
766
+ #private;
767
+ constructor(limitMs: number, now: () => number);
768
+ get spentMs(): number;
769
+ admit(work: () => void): boolean;
770
+ }
771
+
772
+ /** How the shore field reads open water; every default is the Strata coastal world's. */
773
+ interface IShoreFieldOptions {
774
+ /** Water must be this many metres deep for open-sea exposure to flood through it. Default 2. */
775
+ readonly openDepth?: number;
776
+ /** Metres of shallow water that exposure still carries into, never across dry ground. Default 18. */
777
+ readonly carry?: number;
778
+ }
779
+ /** Per grid node: metres to the nearest dry node, and 1 where the open sea reaches. */
780
+ interface IShoreField {
781
+ readonly distance: Float32Array;
782
+ readonly exposed: Uint8Array;
783
+ }
784
+ /**
785
+ * Distance to the shore and open-sea exposure for every node of a square height grid, measured once
786
+ * from the bake. `distance` is a two-pass chamfer distance to the nearest node at or above `level`
787
+ * (0 on dry ground). `exposed` floods from the grid's edge through water deeper than `openDepth`,
788
+ * then `carry` metres further into shallow water, so a sheltered lagoon behind a sand bar stays out
789
+ * of it. Both feed the game's surf and shore masks; neither decides a colour.
790
+ *
791
+ * @situation surf breaks only on water open to the sea, not in a sheltered lagoon
792
+ * @situation distance from each water cell to the shore, for a foam or depth mask
793
+ * @constraint heights are row-major, `resolution` by `resolution`, across `size` metres; measured once, never per frame
794
+ * @example const { distance, exposed } = shoreField(world.heights, world.resolution, world.size, world.waterLevel);
795
+ */
796
+ declare function shoreField(heights: ArrayLike<number>, resolution: number, size: number, level: number, options?: IShoreFieldOptions): IShoreField;
797
+
798
+ /** The drawn surface's height under a world point, or `null` where the sampler cannot answer. */
799
+ type SurfaceSampler = (x: number, z: number) => number | null;
800
+ /**
801
+ * `Heightfield.surfaceAt` under the transform the game draws the field's mesh with, so a prop or a
802
+ * player stands on the triangles the eye sees rather than on the bilinear field between them.
803
+ * Answers `null` outside the field and for a transform it does not model (any rotation, or an
804
+ * unequal scale), so the caller keeps its own fallback there.
660
805
  *
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.
806
+ * @situation stand props or a player on the drawn terrain triangles under a moved or scaled mesh
807
+ * @situation props float or sink where the terrain mesh is drawn under a transform
808
+ * @constraint the mesh is `field.toGeometry()` drawn upright under a uniform scale; read `matrixWorld` after it settles
809
+ * @example const ground = surfaceSampler(field, mesh.matrixWorld); const y = ground(x, z) ?? fallback;
810
+ */
811
+ declare function surfaceSampler(field: Heightfield, matrixWorld: Matrix4): SurfaceSampler;
812
+
813
+ /** Ground height under a world point, or `null` where no ground answers. */
814
+ type StaticGroundQuery = (x: number, z: number) => number | null;
815
+ /**
816
+ * Exact lowest world Y of a static geometry under `matrix`, the precise measurement `GroundSnap`
817
+ * audits against, cheap enough for a load that poses hundreds of thousands of props. An upright
818
+ * pose reads the bounding box. A tilted pose scans the vertices bottom first (sorted once per
819
+ * geometry) and stops once no later vertex can be lower: `|x e1 + z e9| <= reach * hypot(e1, e9)`.
667
820
  *
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.
821
+ * @situation stand a scattered rock, tree or crate on the ground by its lowest point, not its origin
822
+ * @situation props hover or sink because their pivot is not at their base
823
+ * @constraint static geometry only; a skinned model uses `GroundSnap`; the sort is cached per geometry, so do not mutate its positions
824
+ * @example placed.position.y += ground - staticLowestY(geometry, matrix);
671
825
  */
826
+ declare function staticLowestY(geometry: BufferGeometry, matrix: Matrix4): number;
827
+ /**
828
+ * How far the flat underside of a static geometry rises above the ground at its highest point.
829
+ * Snapping the lowest point leaves the downhill side of a flat-bottomed rock hanging; sinking the
830
+ * pose by this much buries the whole footprint. Returns 0 when the footprint is already buried.
831
+ *
832
+ * @situation a rock snapped to a slope shows a lip or a gap under its downhill side
833
+ * @constraint the footprint is every vertex at the geometry's lowest local y; throws `TN_STATIC_POSE_GROUND` where the ground does not answer
834
+ * @example matrix.elements[13] -= footprintGap(geometry, matrix, ground, 0.08);
835
+ */
836
+ declare function footprintGap(geometry: BufferGeometry, matrix: Matrix4, ground: StaticGroundQuery, margin?: number): number;
837
+ /** What `baseRingGap` measured around a wide static model. */
838
+ interface IBaseRing {
839
+ /** The largest height of a sector's lowest rim vertex above its ground, in metres. */
840
+ readonly gap: number;
841
+ /** Sectors that held a rim vertex. */
842
+ readonly samples: number;
843
+ }
844
+ /**
845
+ * The highest gap between a wide model's rim and the ground, one sample per angular sector: in
846
+ * each sector, the lowest vertex beyond `rim` of that sector's reach. A narrow buried stem then
847
+ * cannot hold a wide base up in the air on the downhill side. Sink the pose by `gap` (plus any
848
+ * burial the game wants) to close it.
849
+ *
850
+ * @situation a cliff or crag model rests on a buried stem while its wide base hangs over the downhill ground
851
+ * @constraint throws `TN_STATIC_POSE_GROUND` where the ground does not answer; check `samples` before trusting `gap`
852
+ * @example const ring = baseRingGap(geometry, matrix, ground); if (ring.samples >= 4) matrix.elements[13] -= ring.gap + 0.5;
853
+ */
854
+ declare function baseRingGap(geometry: BufferGeometry, matrix: Matrix4, ground: StaticGroundQuery, options?: {
855
+ readonly sectors?: number;
856
+ readonly rim?: number;
857
+ }): IBaseRing;
858
+
859
+ /** One material section of a mesh: the whole mesh, or one group of a multi-material mesh. */
860
+ interface IMeshSection {
861
+ readonly material: Material;
862
+ readonly group?: {
863
+ readonly start: number;
864
+ readonly count: number;
865
+ };
866
+ }
867
+ /**
868
+ * A mesh's material sections: one per geometry group for a material array, else the whole mesh.
869
+ * Instanced props draw one batch per material, so an imported model splits here first.
870
+ *
871
+ * @situation scatter or instance an imported glTF model that has several materials
872
+ * @constraint a section's `material` can be `undefined` for a group naming a missing material slot; skip it
873
+ * @example for (const section of meshSections(mesh)) parts.push(sectionGeometry(mesh, box, section));
874
+ */
875
+ declare function meshSections(mesh: Mesh): IMeshSection[];
876
+ /**
877
+ * One section's geometry in model space, standing on y = 0. Every section of a model takes the same
878
+ * base from the whole model's `box`, so a crown keeps its place on its trunk: basing each section on
879
+ * its own bounds detaches them. The mesh's LOD0 geometry is cloned under its world matrix, and a
880
+ * group becomes the clone's draw range.
881
+ *
882
+ * @situation the crown of an instanced tree floats off its trunk, or the parts of a model separate
883
+ * @situation turn each part of an imported model into a geometry for an instanced prop batch
884
+ * @constraint `box` is the whole model's world bounds after any unit normalisation; call `mesh.updateWorldMatrix` first
885
+ * @example const box = new Box3().setFromObject(root); const geometry = sectionGeometry(mesh, box, section);
886
+ */
887
+ declare function sectionGeometry(mesh: Mesh, box: Box3, section: IMeshSection, options?: {
888
+ readonly centreXZ?: boolean;
889
+ }): BufferGeometry;
890
+ /**
891
+ * Recompute the normals of a geometry whose normals are missing, zero or not finite, and leave
892
+ * authored normals alone. Some exported art ships zero normals and draws black under any light.
893
+ * Run it after any reshape, so the recomputed normals fit the final shape.
894
+ *
895
+ * @situation an imported model draws black or unlit because it ships zero normals
896
+ * @constraint one bad normal recomputes them all; an intentionally hard-edged model loses its authored split normals only if one is bad
897
+ * @example geometry.scale(1.1, 1, 1.1); repairZeroNormals(geometry);
898
+ */
899
+ declare function repairZeroNormals(geometry: BufferGeometry): boolean;
900
+
901
+ /** How long `warmUnculled` keeps a subtree drawing whole. */
902
+ interface IWarmUnculledOptions {
903
+ /** World draws to spend once `when` holds before the subtree is culled again. Default 2. */
904
+ readonly draws?: number;
905
+ /** Counts a draw only while this holds, such as "every tile around the spawn is resident". */
906
+ readonly when?: () => boolean;
907
+ }
908
+ /**
909
+ * Draw `root` with frustum culling off until it has drawn `draws` times, then cull it again and
910
+ * resolve. A pipeline is built by its first real draw (a startup warm-up compiles a different pass),
911
+ * so content the spawn view does not see — streamed tiles behind the player, a mirror that draws only
912
+ * when its water does — builds its pipelines after the reveal and hitches the first frames that see
913
+ * it. Join the promise to the loading curtain to build them behind it. Objects that join `root`
914
+ * while it warms draw unculled too.
915
+ *
916
+ * @situation the first frames after the loading curtain hitch on pipeline builds for content behind the camera
917
+ * @situation streamed terrain or a lake compiles its pipelines after the reveal
918
+ * @constraint `ctx.beforeRender` runs on every world draw, also behind the curtain; join the promise to the curtain's hold
919
+ * @example const warm = warmUnculled(ctx, lake.mesh); ctx.startup.hold("lake", () => warm);
920
+ */
921
+ declare function warmUnculled(ctx: {
922
+ beforeRender(callback: () => void): void;
923
+ }, root: Object3D, options?: IWarmUnculledOptions): Promise<void>;
924
+
672
925
  /** Marker printed when terrain validation is on, so a log says which mode produced it. */
673
926
  declare const TERRAIN_VALIDATE_MARKER = "TN_TERRAIN_VALIDATE";
674
927
  /** The launch flag. */
@@ -943,6 +1196,7 @@ declare function snowDiscFootprint(radius: number, options?: ISnowDiscFootprintO
943
1196
  * recovery. It is a heightfield approximation — not granular snow, displaced-volume
944
1197
  * conservation, avalanches, melting or a calibrated material law.
945
1198
  * @situation leave footprints, tracks and tyre ruts in snow that persist and fill in over time
1199
+ * @situation let a fresh snowfall slowly fill older tracks back in as the field recovers
946
1200
  * @situation let a pushed sphere carve a connected track and a dropped one settle into a crater
947
1201
  * @situation store snow deformation that rendered geometry and collision both read
948
1202
  * @situation reset a snowfield between rounds or change its depth at runtime
@@ -2304,4 +2558,4 @@ declare class WorldCells extends Group implements IComputeDriven {
2304
2558
  dispose(): void;
2305
2559
  }
2306
2560
 
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 };
2561
+ 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 };