@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
@@ -0,0 +1,39 @@
1
+ import { type Camera, Matrix4, type Vector3 } from "three";
2
+
3
+ /**
4
+ * The world's own records and the camera are in two different frames, and this is where they meet.
5
+ *
6
+ * `WorldCells` is an `Object3D`, and every placement, cell volume, terrain tile and GPU record under
7
+ * it is written in the package's own coordinates — the root's local frame. A camera is in world
8
+ * space. A game may move the root (`world.position.y = -11.45` sinks the whole ring), so a per-frame
9
+ * read that compares the two has to be taken in the root's frame: clip space from a local point is
10
+ * `projection × view × root`, and a world point read locally is the camera's world position through
11
+ * the root's inverse world matrix.
12
+ *
13
+ * The unmoved root is the common case, and it is free: its `matrixWorld` is the identity, so the
14
+ * multiply and the inverse are skipped and the numbers are exactly the ones they always were, with
15
+ * no scratch vector or matrix allocated either way.
16
+ */
17
+
18
+ /** The root's inverse world matrix, reused per read. */
19
+ const _inverse = new Matrix4();
20
+
21
+ /** Whether `matrix` is exactly the identity, so a local-frame read is the read it always was. */
22
+ function isIdentity(matrix: Matrix4): boolean {
23
+ const elements = matrix.elements;
24
+ for (let at = 0; at < 16; at += 1) if (elements[at] !== (at % 5 === 0 ? 1 : 0)) return false;
25
+ return true;
26
+ }
27
+
28
+ /** `projection × view × root` into `out`: clip space, from a point in the root's local frame. */
29
+ export function localClip(out: Matrix4, camera: Camera, root: Matrix4 | undefined): Matrix4 {
30
+ out.multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse);
31
+ if (root === undefined || isIdentity(root)) return out;
32
+ return out.multiply(root);
33
+ }
34
+
35
+ /** `point`, in world space, read in the root's local frame — in place, so a frame allocates nothing. */
36
+ export function localPoint(point: Vector3, root: Matrix4 | undefined): Vector3 {
37
+ if (root === undefined || isIdentity(root)) return point;
38
+ return point.applyMatrix4(_inverse.copy(root).invert());
39
+ }
@@ -0,0 +1,91 @@
1
+ /** How the shore field reads open water; every default is the Strata coastal world's. */
2
+ export interface IShoreFieldOptions {
3
+ /** Water must be this many metres deep for open-sea exposure to flood through it. Default 2. */
4
+ readonly openDepth?: number;
5
+ /** Metres of shallow water that exposure still carries into, never across dry ground. Default 18. */
6
+ readonly carry?: number;
7
+ }
8
+
9
+ /** Per grid node: metres to the nearest dry node, and 1 where the open sea reaches. */
10
+ export interface IShoreField {
11
+ readonly distance: Float32Array;
12
+ readonly exposed: Uint8Array;
13
+ }
14
+
15
+ /**
16
+ * Distance to the shore and open-sea exposure for every node of a square height grid, measured once
17
+ * from the bake. `distance` is a two-pass chamfer distance to the nearest node at or above `level`
18
+ * (0 on dry ground). `exposed` floods from the grid's edge through water deeper than `openDepth`,
19
+ * then `carry` metres further into shallow water, so a sheltered lagoon behind a sand bar stays out
20
+ * of it. Both feed the game's surf and shore masks; neither decides a colour.
21
+ *
22
+ * @situation surf breaks only on water open to the sea, not in a sheltered lagoon
23
+ * @situation distance from each water cell to the shore, for a foam or depth mask
24
+ * @constraint heights are row-major, `resolution` by `resolution`, across `size` metres; measured once, never per frame
25
+ * @example const { distance, exposed } = shoreField(world.heights, world.resolution, world.size, world.waterLevel);
26
+ */
27
+ export function shoreField(
28
+ heights: ArrayLike<number>,
29
+ resolution: number,
30
+ size: number,
31
+ level: number,
32
+ options: IShoreFieldOptions = {},
33
+ ): IShoreField {
34
+ const n = resolution;
35
+ const openDepth = options.openDepth ?? 2;
36
+ const carry = options.carry ?? 18;
37
+ if (!Number.isInteger(n) || n < 2 || heights.length !== n * n)
38
+ throw new Error(
39
+ `TN_SHORE_FIELD_INVALID: heights must hold resolution² values, received ${heights.length} for ${n}.`,
40
+ );
41
+ if (!(size > 0) || !Number.isFinite(level) || !(openDepth >= 0) || !(carry >= 0))
42
+ throw new Error(
43
+ "TN_SHORE_FIELD_INVALID: size must be positive, level finite, openDepth and carry not negative.",
44
+ );
45
+ const cell = size / (n - 1);
46
+ const height = (i: number): number => heights[i] ?? 0;
47
+ const distance = new Float32Array(n * n);
48
+ for (let i = 0; i < n * n; i++) distance[i] = height(i) >= level ? 0 : 1e4;
49
+ const exposed = new Uint8Array(n * n);
50
+ const queue: number[] = [];
51
+ for (let i = 0; i < n * n; i++) {
52
+ const row = Math.floor(i / n);
53
+ const col = i % n;
54
+ if (
55
+ (row === 0 || col === 0 || row === n - 1 || col === n - 1) &&
56
+ height(i) < level - openDepth
57
+ ) {
58
+ exposed[i] = 1;
59
+ queue.push(i);
60
+ }
61
+ if (col > 0) distance[i] = Math.min(distance[i] ?? 0, (distance[i - 1] ?? 0) + cell);
62
+ if (row > 0) distance[i] = Math.min(distance[i] ?? 0, (distance[i - n] ?? 0) + cell);
63
+ }
64
+ for (let i = n * n - 1; i >= 0; i--) {
65
+ if (i % n < n - 1) distance[i] = Math.min(distance[i] ?? 0, (distance[i + 1] ?? 0) + cell);
66
+ if (i < n * (n - 1)) distance[i] = Math.min(distance[i] ?? 0, (distance[i + n] ?? 0) + cell);
67
+ }
68
+ for (let head = 0; head < queue.length; head++) {
69
+ const i = queue[head] ?? 0;
70
+ for (const next of [i % n > 0 ? i - 1 : -1, i % n < n - 1 ? i + 1 : -1, i - n, i + n]) {
71
+ if (next < 0 || next >= exposed.length || exposed[next] || height(next) >= level - openDepth)
72
+ continue;
73
+ exposed[next] = 1;
74
+ queue.push(next);
75
+ }
76
+ }
77
+ for (let pass = 0; pass < Math.ceil(carry / cell); pass++) {
78
+ const previous = exposed.slice();
79
+ for (let i = 0; i < exposed.length; i++) {
80
+ if (height(i) >= level) continue;
81
+ if (
82
+ (i % n > 0 && previous[i - 1]) ||
83
+ (i % n < n - 1 && previous[i + 1]) ||
84
+ previous[i - n] ||
85
+ previous[i + n]
86
+ )
87
+ exposed[i] = 1;
88
+ }
89
+ }
90
+ return { distance, exposed };
91
+ }
@@ -0,0 +1,163 @@
1
+ import { type BufferGeometry, type Matrix4, Vector3 } from "three";
2
+
3
+ /** Ground height under a world point, or `null` where no ground answers. */
4
+ export type StaticGroundQuery = (x: number, z: number) => number | null;
5
+
6
+ const bottomFirst = new WeakMap<BufferGeometry, { xyz: Float32Array; reach: number }>();
7
+
8
+ function verticesBottomFirst(geometry: BufferGeometry): { xyz: Float32Array; reach: number } {
9
+ const cached = bottomFirst.get(geometry);
10
+ if (cached) return cached;
11
+ const position = geometry.getAttribute("position");
12
+ const order = Array.from({ length: position.count }, (_, i) => i).sort(
13
+ (a, b) => position.getY(a) - position.getY(b),
14
+ );
15
+ const xyz = new Float32Array(position.count * 3);
16
+ let reach = 0;
17
+ order.forEach((i, k) => {
18
+ xyz[k * 3] = position.getX(i);
19
+ xyz[k * 3 + 1] = position.getY(i);
20
+ xyz[k * 3 + 2] = position.getZ(i);
21
+ reach = Math.max(reach, Math.hypot(position.getX(i), position.getZ(i)));
22
+ });
23
+ const entry = { xyz, reach };
24
+ bottomFirst.set(geometry, entry);
25
+ return entry;
26
+ }
27
+
28
+ /**
29
+ * Exact lowest world Y of a static geometry under `matrix`, the precise measurement `GroundSnap`
30
+ * audits against, cheap enough for a load that poses hundreds of thousands of props. An upright
31
+ * pose reads the bounding box. A tilted pose scans the vertices bottom first (sorted once per
32
+ * geometry) and stops once no later vertex can be lower: `|x e1 + z e9| <= reach * hypot(e1, e9)`.
33
+ *
34
+ * @situation stand a scattered rock, tree or crate on the ground by its lowest point, not its origin
35
+ * @situation props hover or sink because their pivot is not at their base
36
+ * @constraint static geometry only; a skinned model uses `GroundSnap`; the sort is cached per geometry, so do not mutate its positions
37
+ * @example placed.position.y += ground - staticLowestY(geometry, matrix);
38
+ */
39
+ export function staticLowestY(geometry: BufferGeometry, matrix: Matrix4): number {
40
+ const e = matrix.elements;
41
+ if (e[1] === 0 && e[9] === 0) {
42
+ if (geometry.boundingBox === null) geometry.computeBoundingBox();
43
+ const box = geometry.boundingBox;
44
+ if (box) return (e[5] < 0 ? box.max.y : box.min.y) * e[5] + e[13];
45
+ }
46
+ const { xyz, reach } = verticesBottomFirst(geometry);
47
+ const tilt = reach * Math.hypot(e[1], e[9]);
48
+ const upright = e[5] > 0;
49
+ let lowest = Number.POSITIVE_INFINITY;
50
+ for (let k = 0; k < xyz.length; k += 3) {
51
+ const y = xyz[k + 1] as number;
52
+ if (upright && y * e[5] + e[13] - tilt >= lowest) break;
53
+ lowest = Math.min(
54
+ lowest,
55
+ (xyz[k] as number) * e[1] + y * e[5] + (xyz[k + 2] as number) * e[9] + e[13],
56
+ );
57
+ }
58
+ return lowest;
59
+ }
60
+
61
+ /**
62
+ * How far the flat underside of a static geometry rises above the ground at its highest point.
63
+ * Snapping the lowest point leaves the downhill side of a flat-bottomed rock hanging; sinking the
64
+ * pose by this much buries the whole footprint. Returns 0 when the footprint is already buried.
65
+ *
66
+ * @situation a rock snapped to a slope shows a lip or a gap under its downhill side
67
+ * @constraint the footprint is every vertex at the geometry's lowest local y; throws `TN_STATIC_POSE_GROUND` where the ground does not answer
68
+ * @example matrix.elements[13] -= footprintGap(geometry, matrix, ground, 0.08);
69
+ */
70
+ export function footprintGap(
71
+ geometry: BufferGeometry,
72
+ matrix: Matrix4,
73
+ ground: StaticGroundQuery,
74
+ margin = 0,
75
+ ): number {
76
+ if (geometry.boundingBox === null) geometry.computeBoundingBox();
77
+ const base = geometry.boundingBox?.min.y ?? Number.POSITIVE_INFINITY;
78
+ const positions = geometry.getAttribute("position");
79
+ const point = new Vector3();
80
+ let gap = 0;
81
+ for (let i = 0; i < positions.count; i++) {
82
+ if (Math.abs(positions.getY(i) - base) > 1e-5) continue;
83
+ point.fromBufferAttribute(positions, i).applyMatrix4(matrix);
84
+ const height = ground(point.x, point.z);
85
+ if (height === null)
86
+ throw new Error(
87
+ `TN_STATIC_POSE_GROUND: no ground under the footprint at ${point.x}, ${point.z}.`,
88
+ );
89
+ gap = Math.max(gap, point.y - height + margin);
90
+ }
91
+ return gap;
92
+ }
93
+
94
+ /** What `baseRingGap` measured around a wide static model. */
95
+ export interface IBaseRing {
96
+ /** The largest height of a sector's lowest rim vertex above its ground, in metres. */
97
+ readonly gap: number;
98
+ /** Sectors that held a rim vertex. */
99
+ readonly samples: number;
100
+ }
101
+
102
+ /**
103
+ * The highest gap between a wide model's rim and the ground, one sample per angular sector: in
104
+ * each sector, the lowest vertex beyond `rim` of that sector's reach. A narrow buried stem then
105
+ * cannot hold a wide base up in the air on the downhill side. Sink the pose by `gap` (plus any
106
+ * burial the game wants) to close it.
107
+ *
108
+ * @situation a cliff or crag model rests on a buried stem while its wide base hangs over the downhill ground
109
+ * @constraint throws `TN_STATIC_POSE_GROUND` where the ground does not answer; check `samples` before trusting `gap`
110
+ * @example const ring = baseRingGap(geometry, matrix, ground); if (ring.samples >= 4) matrix.elements[13] -= ring.gap + 0.5;
111
+ */
112
+ export function baseRingGap(
113
+ geometry: BufferGeometry,
114
+ matrix: Matrix4,
115
+ ground: StaticGroundQuery,
116
+ options: { readonly sectors?: number; readonly rim?: number } = {},
117
+ ): IBaseRing {
118
+ const count = options.sectors ?? 16;
119
+ const rim = options.rim ?? 0.75;
120
+ if (!Number.isInteger(count) || count < 1 || !(rim >= 0 && rim <= 1))
121
+ throw new Error(
122
+ "TN_STATIC_POSE_INVALID: sectors must be a positive integer and rim within 0..1.",
123
+ );
124
+ if (geometry.boundingBox === null) geometry.computeBoundingBox();
125
+ const box = geometry.boundingBox;
126
+ if (!box) throw new Error("TN_STATIC_POSE_INVALID: the geometry has no bounds.");
127
+ const centre = box.getCenter(new Vector3()).applyMatrix4(matrix);
128
+ const sectors = Array.from({ length: count }, () => ({ reach: 0, vertices: [] as Vector3[] }));
129
+ const vertices = geometry.getAttribute("position");
130
+ for (let i = 0; i < vertices.count; i++) {
131
+ const point = new Vector3().fromBufferAttribute(vertices, i).applyMatrix4(matrix);
132
+ const dx = point.x - centre.x;
133
+ const dz = point.z - centre.z;
134
+ const bin = Math.min(
135
+ count - 1,
136
+ Math.floor(((Math.atan2(dz, dx) + Math.PI) / (2 * Math.PI)) * count),
137
+ );
138
+ const sector = sectors[bin];
139
+ if (!sector) continue;
140
+ sector.reach = Math.max(sector.reach, Math.hypot(dx, dz));
141
+ sector.vertices.push(point);
142
+ }
143
+ let gap = Number.NEGATIVE_INFINITY;
144
+ let samples = 0;
145
+ for (const sector of sectors) {
146
+ let lowest: Vector3 | undefined;
147
+ for (const point of sector.vertices)
148
+ if (
149
+ Math.hypot(point.x - centre.x, point.z - centre.z) >= sector.reach * rim &&
150
+ (!lowest || point.y < lowest.y)
151
+ )
152
+ lowest = point;
153
+ if (!lowest) continue;
154
+ const contact = ground(lowest.x, lowest.z);
155
+ if (contact === null)
156
+ throw new Error(
157
+ `TN_STATIC_POSE_GROUND: no ground under the base ring at ${lowest.x}, ${lowest.z}.`,
158
+ );
159
+ gap = Math.max(gap, lowest.y - contact);
160
+ samples++;
161
+ }
162
+ return { gap, samples };
163
+ }
@@ -0,0 +1,48 @@
1
+ import { type Matrix4, Quaternion, Vector3 } from "three";
2
+ import type { Heightfield } from "./world-heightfield.js";
3
+
4
+ /** The drawn surface's height under a world point, or `null` where the sampler cannot answer. */
5
+ export type SurfaceSampler = (x: number, z: number) => number | null;
6
+
7
+ /**
8
+ * `Heightfield.surfaceAt` under the transform the game draws the field's mesh with, so a prop or a
9
+ * player stands on the triangles the eye sees rather than on the bilinear field between them.
10
+ * Answers `null` outside the field and for a transform it does not model (any rotation, or an
11
+ * unequal scale), so the caller keeps its own fallback there.
12
+ *
13
+ * @situation stand props or a player on the drawn terrain triangles under a moved or scaled mesh
14
+ * @situation props float or sink where the terrain mesh is drawn under a transform
15
+ * @constraint the mesh is `field.toGeometry()` drawn upright under a uniform scale; read `matrixWorld` after it settles
16
+ * @example const ground = surfaceSampler(field, mesh.matrixWorld); const y = ground(x, z) ?? fallback;
17
+ */
18
+ export function surfaceSampler(field: Heightfield, matrixWorld: Matrix4): SurfaceSampler {
19
+ const translation = new Vector3();
20
+ const rotation = new Quaternion();
21
+ const scale = new Vector3();
22
+ matrixWorld.decompose(translation, rotation, scale);
23
+ const upright =
24
+ Math.abs(rotation.x) < 1e-6 &&
25
+ Math.abs(rotation.y) < 1e-6 &&
26
+ Math.abs(rotation.z) < 1e-6 &&
27
+ Math.abs(rotation.w - 1) < 1e-6 &&
28
+ scale.x > 0 &&
29
+ scale.x === scale.y &&
30
+ scale.y === scale.z;
31
+ if (!upright) return () => null;
32
+ const { origin, width, depth } = field;
33
+ // A drawn vertex is float32 and the field's extent float64: the mesh's own edge can land a hair
34
+ // outside the ground it was built from. That much is the same ground; further out is not.
35
+ const slack = 1e-5;
36
+ const minX = origin.x - width / 2;
37
+ const maxX = origin.x + width / 2;
38
+ const minZ = origin.z - depth / 2;
39
+ const maxZ = origin.z + depth / 2;
40
+ return (worldX, worldZ) => {
41
+ const x = (worldX - translation.x) / scale.x;
42
+ const z = (worldZ - translation.z) / scale.z;
43
+ if (x < minX - slack || x > maxX + slack || z < minZ - slack || z > maxZ + slack) return null;
44
+ const clampedX = Math.min(maxX, Math.max(minX, x));
45
+ const clampedZ = Math.min(maxZ, Math.max(minZ, z));
46
+ return field.surfaceAt(clampedX, clampedZ) * scale.y + translation.y;
47
+ };
48
+ }
@@ -33,7 +33,7 @@ import {
33
33
  } from "three/tsl";
34
34
  import type { Node } from "three/webgpu";
35
35
  import { MeshStandardNodeMaterial } from "three/webgpu";
36
- import type { IAssetLoader } from "./assets.js";
36
+ import { type IAssetLoader, fetchAsset } from "./assets.js";
37
37
  import type { IRendererLike } from "./renderer.js";
38
38
  import type { IWorldExtent } from "./world-package.js";
39
39
 
@@ -229,24 +229,16 @@ function packageAssetPath(directory: string, path: string): string {
229
229
  }
230
230
 
231
231
  async function fetchResolved(assets: IAssetLoader, path: string): Promise<Response> {
232
- let attempted = false;
233
- let everyFetchRejected = true;
234
- let lastFetchError: unknown;
235
- for (const candidate of await assets.resolve(path)) {
236
- attempted = true;
237
- let response: Response;
238
- try {
239
- response = await fetch(candidate);
240
- } catch (error) {
241
- lastFetchError = error;
242
- continue;
243
- }
244
- everyFetchRejected = false;
245
- if (response.ok) return response;
232
+ try {
233
+ return await fetchAsset(assets, path);
234
+ } catch (error) {
235
+ // The native fetch error, when every candidate rejected, stays the cause a caller reads.
236
+ const cause = error instanceof Error ? error.cause : undefined;
237
+ throw new Error(
238
+ `loadTerrainSplat: '${path}' is not served.`,
239
+ cause === undefined ? undefined : { cause },
240
+ );
246
241
  }
247
- if (attempted && everyFetchRejected)
248
- throw new Error(`loadTerrainSplat: '${path}' is not served.`, { cause: lastFetchError });
249
- throw new Error(`loadTerrainSplat: '${path}' is not served.`);
250
242
  }
251
243
 
252
244
  /** Every splat plane in one array texture: one sampler, whatever the plane count. */
@@ -2,6 +2,7 @@
2
2
  * TerrainTiles' constants, admission byte estimates and the input guards they share. Split out of
3
3
  `world-tiles.ts` verbatim (PRD-797), so the estimator can be read and tested without the class.
4
4
  */
5
+ import { readLaunchFlag } from "./debug.js";
5
6
 
6
7
  import { type SpanId, addSpan, spanNow, spanRecorder } from "./profiling/Spans.js";
7
8
  import type { IHeightfieldWorldPassOptions } from "./world-heightfield.js";
@@ -29,17 +30,9 @@ export const TERRAIN_TILE_MARKER_MS = 5_000;
29
30
  * switch — or one that still carries the `=1` that used to ask for the merge — stays on.
30
31
  */
31
32
  export function terrainMergeOptedOut(): boolean {
32
- const host = globalThis as { process?: { env?: Record<string, unknown> } } & Record<
33
- string,
34
- unknown
35
- >;
36
- const fromEnv = host.process?.env?.[TERRAIN_MERGE_FLAG];
37
- if (fromEnv === "0" || fromEnv === "false") return true;
38
- const query = globalThis.location?.search;
39
- if (typeof query === "string" && /[?&]tnTerrainMerge=(?:0|false)(?:&|$)/u.test(query))
40
- return true;
41
- return (
42
- host.__tnTerrainMerge === false || host.__tnTerrainMerge === 0 || host.__tnTerrainMerge === "0"
33
+ return readLaunchFlag(
34
+ { environment: TERRAIN_MERGE_FLAG, global: "__tnTerrainMerge", query: "tnTerrainMerge" },
35
+ "off",
43
36
  );
44
37
  }
45
38
 
@@ -31,8 +31,8 @@ import type { IComputeDriven } from "./compute-driven.js";
31
31
  import {
32
32
  type ILodView,
33
33
  type IModelLodPolicy,
34
- conservativeViewDepth,
35
34
  projectedLodError,
35
+ selectLodFor,
36
36
  selectLodLevel,
37
37
  worldSphere,
38
38
  } from "./model-lod.js";
@@ -212,6 +212,17 @@ export interface IWorldTilesOptions {
212
212
  readonly minX: number;
213
213
  readonly minZ: number;
214
214
  };
215
+ /**
216
+ * A region another surface already draws and collides, in tile-local metres: a tile wholly inside
217
+ * it is never meshed and gets no collider. A tile that only overlaps it is meshed whole; the game
218
+ * hides the overlap in its own surface.
219
+ */
220
+ readonly hole?: {
221
+ readonly maxX: number;
222
+ readonly maxZ: number;
223
+ readonly minX: number;
224
+ readonly minZ: number;
225
+ };
215
226
  /** How deep each edge skirt extends below its surface. Defaults to one tile width. */
216
227
  readonly skirtDepth?: number;
217
228
  /** Square tile neighborhood to consider around the followed point. Defaults to 1. */
@@ -332,6 +343,8 @@ export type NeighborPair = readonly [IResidentTile, IResidentTile];
332
343
  * @situation stream terrain without cracks
333
344
  * @situation keep generated terrain resident around a moving player
334
345
  * @situation put a generated terrain tile into a game-owned physics world
346
+ * @situation a hole or a flicker where streamed terrain tiles are still building (`settledHalf`)
347
+ * @situation split the ground between streamed tiles and a far mesh around the player (`settledHalf`)
335
348
  * @alias stream terrain across chunks
336
349
  * @constraint sampleHeight and surface are required game choices; no landform or surface preset is installed
337
350
  * @constraint residentTileBudget and residentByteBudget are hard caps; a tile that cannot fit throws
@@ -359,6 +372,7 @@ export class TerrainTiles extends Object3D implements IComputeDriven {
359
372
  readonly #sampleHeight: IWorldTilesOptions["sampleHeight"];
360
373
  readonly #streamRadius: number;
361
374
  readonly #extent: IWorldTilesOptions["extent"];
375
+ readonly #hole: IWorldTilesOptions["hole"];
362
376
  /** Diagnostics outlive construction; their canonical field is never used by resident tiles. */
363
377
  #topology:
364
378
  | (Pick<Heightfield, "columns" | "depth" | "origin" | "rows" | "width"> & {
@@ -462,6 +476,7 @@ export class TerrainTiles extends Object3D implements IComputeDriven {
462
476
  this.skirtDepth = positive(options.skirtDepth ?? this.tileSize, "skirtDepth");
463
477
  this.#streamRadius = integerAtLeast(options.streamRadius ?? 1, 0, "streamRadius");
464
478
  this.#extent = options.extent;
479
+ this.#hole = options.hole;
465
480
  this.#receiveShadow = options.receiveShadow === true;
466
481
  this.#colliderRadius = integerAtLeast(
467
482
  options.colliderRadius ?? this.#streamRadius,
@@ -724,6 +739,42 @@ export class TerrainTiles extends Object3D implements IComputeDriven {
724
739
  return this.#resident.get(key);
725
740
  }
726
741
 
742
+ /**
743
+ * Half-width, in metres, of the largest square of tiles around `position`'s tile that is fully
744
+ * settled: each tile in it is resident, or is one the stream never draws (wholly inside `hole` or
745
+ * past `extent`). Zero while the tile under `position` is still building. A game that draws other
746
+ * ground where the tiles have not arrived (a collar, a far mesh) clips it to this square, so a tile
747
+ * still building shows that ground, never a hole.
748
+ *
749
+ * @situation a hole or a flicker where streamed terrain tiles are still building
750
+ * @situation split the ground between streamed tiles and a far mesh around the player
751
+ * @constraint reads residency only; call it after `follow` in the same frame
752
+ * @example split.half.value = tiles.settledHalf(player.position);
753
+ */
754
+ settledHalf(position: Pick<Vector3, "x" | "z">): number {
755
+ const centerX = Math.floor(
756
+ (finite(position.x, "settled x") + this.tileSize / 2) / this.tileSize,
757
+ );
758
+ const centerZ = Math.floor(
759
+ (finite(position.z, "settled z") + this.tileSize / 2) / this.tileSize,
760
+ );
761
+ const settled = (tileX: number, tileZ: number): boolean =>
762
+ this.#resident.has(keyFor(tileX, tileZ)) || !this.#touchesExtent(tileX, tileZ);
763
+ let ring = -1;
764
+ for (let k = 0; k <= this.#streamRadius; k += 1) {
765
+ for (let d = -k; d <= k; d += 1)
766
+ if (
767
+ !settled(centerX + d, centerZ - k) ||
768
+ !settled(centerX + d, centerZ + k) ||
769
+ !settled(centerX - k, centerZ + d) ||
770
+ !settled(centerX + k, centerZ + d)
771
+ )
772
+ return ring < 0 ? 0 : (ring + 0.5) * this.tileSize;
773
+ ring = k;
774
+ }
775
+ return (ring + 0.5) * this.tileSize;
776
+ }
777
+
727
778
  /**
728
779
  * Move residency to the followed point: admit, evict and re-level every tile.
729
780
  *
@@ -995,19 +1046,22 @@ export class TerrainTiles extends Object3D implements IComputeDriven {
995
1046
  if (view !== undefined && next !== undefined && finest !== undefined && bounds != null) {
996
1047
  finest.mesh.updateWorldMatrix(true, false);
997
1048
  const sphere = worldSphere(bounds, finest.mesh);
998
- const depth = conservativeViewDepth(
1049
+ const { degenerate, depth } = selectLodFor(
999
1050
  view.camera,
1000
- sphere.center,
1001
- sphere.radius,
1051
+ sphere,
1002
1052
  (view.camera as Camera & { near?: number }).near ?? 0,
1003
1053
  );
1004
1054
  const errorPixels = projectedLodError(
1005
1055
  next.surfaceError * finest.mesh.matrixWorld.getMaxScaleOnAxis(),
1006
1056
  view.camera,
1007
1057
  view.viewportHeight,
1008
- depth.depth,
1058
+ depth,
1009
1059
  );
1010
- projection = { ...depth, ...(Number.isFinite(errorPixels) ? { errorPixels } : {}) };
1060
+ projection = {
1061
+ degenerate,
1062
+ depth,
1063
+ ...(Number.isFinite(errorPixels) ? { errorPixels } : {}),
1064
+ };
1011
1065
  }
1012
1066
  return {
1013
1067
  key: tile.key,
@@ -1379,11 +1433,23 @@ export class TerrainTiles extends Object3D implements IComputeDriven {
1379
1433
  this.#setLodLevel(tile, this.#targetLod(tile, distance), countTransition);
1380
1434
  }
1381
1435
 
1382
- /** Whether the tile's square overlaps the ground at all; always true when no extent was given. */
1436
+ /**
1437
+ * Whether the tile's square overlaps the ground at all and is not wholly inside the hole; always
1438
+ * true when neither was given.
1439
+ */
1383
1440
  #touchesExtent(tileX: number, tileZ: number): boolean {
1441
+ const half = this.tileSize / 2;
1442
+ const hole = this.#hole;
1443
+ if (
1444
+ hole !== undefined &&
1445
+ tileX * this.tileSize - half >= hole.minX &&
1446
+ tileX * this.tileSize + half <= hole.maxX &&
1447
+ tileZ * this.tileSize - half >= hole.minZ &&
1448
+ tileZ * this.tileSize + half <= hole.maxZ
1449
+ )
1450
+ return false;
1384
1451
  const extent = this.#extent;
1385
1452
  if (extent === undefined) return true;
1386
- const half = this.tileSize / 2;
1387
1453
  return (
1388
1454
  tileX * this.tileSize + half > extent.minX &&
1389
1455
  tileX * this.tileSize - half < extent.maxX &&
@@ -1419,10 +1485,11 @@ export class TerrainTiles extends Object3D implements IComputeDriven {
1419
1485
  if (finest === undefined || bounds == null) return 0;
1420
1486
  finest.mesh.updateWorldMatrix(true, false);
1421
1487
  const sphere = worldSphere(bounds, finest.mesh);
1422
- const depth = conservativeViewDepth(
1488
+ // The raw depth, deliberately: terrain selection never took the adaptive LOD bias, and passing
1489
+ // `biased` here moved a tile's level whenever `setLodBias` raised it.
1490
+ const { depth, degenerate } = selectLodFor(
1423
1491
  view.camera,
1424
- sphere.center,
1425
- sphere.radius,
1492
+ sphere,
1426
1493
  (view.camera as Camera & { near?: number }).near ?? 0,
1427
1494
  );
1428
1495
  const scale = finest.mesh.matrixWorld.getMaxScaleOnAxis();
@@ -1431,7 +1498,7 @@ export class TerrainTiles extends Object3D implements IComputeDriven {
1431
1498
  this.#lodErrors[index] = (tile.levels[index] as ILevelGeometry).surfaceError * scale;
1432
1499
  this.#lodErrors.length = floor + 1;
1433
1500
  return selectLodLevel(this.#lodErrors, tile.lodLevel, view.maxPixelError, view.hysteresis, [
1434
- { ...view, ...depth },
1501
+ { ...view, degenerate, depth },
1435
1502
  ]);
1436
1503
  }
1437
1504
 
@@ -12,6 +12,7 @@
12
12
  * loops back and every assertion with them. It is a validation mode, not a proof: it proves the
13
13
  * frames it ran on.
14
14
  */
15
+ import { readLaunchFlag } from "./debug.js";
15
16
 
16
17
  /** Marker printed when terrain validation is on, so a log says which mode produced it. */
17
18
  export const TERRAIN_VALIDATE_MARKER = "TN_TERRAIN_VALIDATE";
@@ -31,18 +32,9 @@ export const TERRAIN_VALIDATE_FLAG = "TN_TERRAIN_VALIDATE";
31
32
  * const tiles = new TerrainTiles({ ...options, validate: terrainValidationRequested() });
32
33
  */
33
34
  export function terrainValidationRequested(): boolean {
34
- const host = globalThis as {
35
- process?: { env?: Record<string, unknown> };
36
- __tnTerrainValidate?: unknown;
37
- };
38
- const fromEnv = host.process?.env?.[TERRAIN_VALIDATE_FLAG];
39
- if (typeof fromEnv === "string" && fromEnv !== "" && fromEnv !== "0" && fromEnv !== "false")
40
- return true;
41
- const query = globalThis.location?.search;
42
- if (
43
- typeof query === "string" &&
44
- /[?&]tnTerrainValidate=(?!0(?:&|$))(?!false(?:&|$))[^&]/u.test(query)
45
- )
46
- return true;
47
- return host.__tnTerrainValidate === true || host.__tnTerrainValidate === "1";
35
+ return readLaunchFlag({
36
+ environment: TERRAIN_VALIDATE_FLAG,
37
+ global: "__tnTerrainValidate",
38
+ query: "tnTerrainValidate",
39
+ });
48
40
  }
@@ -0,0 +1,51 @@
1
+ import type { Object3D } from "three";
2
+
3
+ /** How long `warmUnculled` keeps a subtree drawing whole. */
4
+ export interface IWarmUnculledOptions {
5
+ /** World draws to spend once `when` holds before the subtree is culled again. Default 2. */
6
+ readonly draws?: number;
7
+ /** Counts a draw only while this holds, such as "every tile around the spawn is resident". */
8
+ readonly when?: () => boolean;
9
+ }
10
+
11
+ /**
12
+ * Draw `root` with frustum culling off until it has drawn `draws` times, then cull it again and
13
+ * resolve. A pipeline is built by its first real draw (a startup warm-up compiles a different pass),
14
+ * so content the spawn view does not see — streamed tiles behind the player, a mirror that draws only
15
+ * when its water does — builds its pipelines after the reveal and hitches the first frames that see
16
+ * it. Join the promise to the loading curtain to build them behind it. Objects that join `root`
17
+ * while it warms draw unculled too.
18
+ *
19
+ * @situation the first frames after the loading curtain hitch on pipeline builds for content behind the camera
20
+ * @situation streamed terrain or a lake compiles its pipelines after the reveal
21
+ * @constraint `ctx.beforeRender` runs on every world draw, also behind the curtain; join the promise to the curtain's hold
22
+ * @example const warm = warmUnculled(ctx, lake.mesh); ctx.startup.hold("lake", () => warm);
23
+ */
24
+ export function warmUnculled(
25
+ ctx: { beforeRender(callback: () => void): void },
26
+ root: Object3D,
27
+ options: IWarmUnculledOptions = {},
28
+ ): Promise<void> {
29
+ const draws = options.draws ?? 2;
30
+ if (!Number.isInteger(draws) || draws < 1)
31
+ throw new Error(
32
+ `TN_WARM_UNCULLED_INVALID: draws must be a positive integer, received ${draws}.`,
33
+ );
34
+ const when = options.when ?? (() => true);
35
+ const cull = (culled: boolean): void =>
36
+ root.traverse((object) => {
37
+ object.frustumCulled = culled;
38
+ });
39
+ return new Promise((resolve) => {
40
+ let counted = 0; // -1 once warm
41
+ ctx.beforeRender(() => {
42
+ if (counted < 0) return;
43
+ cull(false);
44
+ if (when()) counted += 1;
45
+ if (counted <= draws) return;
46
+ counted = -1;
47
+ cull(true);
48
+ resolve();
49
+ });
50
+ });
51
+ }