@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.
- package/README.md +1 -1
- package/capabilities.json +746 -32
- package/dist/{assets-YUbXa3-Y.d.ts → assets-CfMKnOsK.d.ts} +78 -1
- package/dist/{canvas-layer-CWuFRT7G.d.ts → canvas-layer-G7ttVy7y.d.ts} +1 -1
- package/dist/{chunk-7UUT3TY5.js → chunk-4SRAQFTU.js} +1 -1
- package/dist/{chunk-GMHATRPW.js → chunk-DIPIJICH.js} +1590 -375
- package/dist/{chunk-OKXUCASC.js → chunk-EEABDLUC.js} +3 -4
- package/dist/{chunk-5O73CDMR.js → chunk-EFWZWLPY.js} +62 -16
- package/dist/{chunk-N5LRP4BR.js → chunk-GYUZJQ7U.js} +63 -3
- package/dist/{chunk-VAZM36TV.js → chunk-H4J6IAJE.js} +17 -10
- package/dist/{chunk-2Z44XSI2.js → chunk-SV4QVUTQ.js} +3 -7
- package/dist/{chunk-DBELTTTM.js → chunk-U4YHUKKL.js} +1 -1
- package/dist/chunk-VP43GIWW.js +18 -0
- package/dist/{chunk-6KLNISRJ.js → chunk-XDTZ4QMO.js} +11 -4
- package/dist/default-tone-mapping-GgKPTiBP.d.ts +4 -0
- package/dist/{game-D7pAzZUY.d.ts → game-k8K3hZai.d.ts} +72 -8
- package/dist/hot.d.ts +5 -4
- package/dist/hot.js +5 -8
- package/dist/index.d.ts +289 -1034
- package/dist/index.js +3096 -1305
- package/dist/{model-lod-B6BMqS1r.d.ts → model-lod-DPTzeCcD.d.ts} +4 -2
- package/dist/playtest.d.ts +5 -4
- package/dist/playtest.js +6 -5
- package/dist/quality-BYqKGAwo.d.ts +868 -0
- package/dist/react.d.ts +3 -2
- package/dist/render-environment.d.ts +170 -0
- package/dist/render-environment.js +352 -0
- package/dist/{renderer-DvFVoAgj.d.ts → renderer-BtOSseYf.d.ts} +29 -31
- package/dist/spells/index.js +1 -1
- package/dist/ui-layer.js +3 -2
- package/dist/worker.js +12 -5
- package/dist/world.d.ts +269 -15
- package/dist/world.js +1372 -628
- package/mcp/animation-server.mjs +1 -1
- package/mcp/engine-server.mjs +105 -7
- package/mcp/servers.mjs +4 -4
- package/package.json +10 -6
- package/src/animation-batch.ts +193 -0
- package/src/animation-layers.ts +7 -3
- package/src/animation.ts +209 -29
- package/src/asset-cache.ts +3 -3
- package/src/asset-memo.ts +202 -0
- package/src/assets.ts +436 -131
- package/src/auto-batch.ts +190 -44
- package/src/compute-driven.ts +1 -1
- package/src/config.ts +8 -0
- package/src/debug.ts +103 -22
- package/src/dev-global.ts +54 -0
- package/src/engine-hooks.ts +37 -0
- package/src/frame-budget.ts +19 -3
- package/src/game-boot-phase.ts +269 -0
- package/src/game-dev-tools.ts +7 -14
- package/src/game-frame-loop.ts +45 -82
- package/src/game-startup.ts +145 -70
- package/src/game-ui.ts +84 -0
- package/src/game.ts +168 -552
- package/src/gamepad-mappings.ts +269 -0
- package/src/generated/console-markers.ts +13 -0
- package/src/geometry-capture.ts +28 -4
- package/src/gpu-readings.ts +98 -0
- package/src/gpu-scene-bvh.ts +149 -36
- package/src/hot.ts +4 -7
- package/src/index.ts +115 -8
- package/src/input.ts +237 -25
- package/src/instanced-batch-lod.ts +3 -8
- package/src/interpolation.ts +171 -40
- package/src/look/ao-admission.ts +4 -3
- package/src/look/auto-exposure.ts +5 -16
- package/src/look/default-tone-mapping.ts +41 -5
- package/src/look/local-exposure.ts +2 -7
- package/src/look/quad-pass.ts +21 -0
- package/src/look/quality.ts +4 -0
- package/src/look/unreal-bloom.ts +4 -13
- package/src/look/world-environment.ts +58 -115
- package/src/merge-parts.ts +20 -24
- package/src/model-lod.ts +97 -14
- package/src/particle-significance.ts +12 -0
- package/src/particles.ts +19 -10
- package/src/platform.ts +23 -4
- package/src/profiling/FrameStages.ts +5 -6
- package/src/profiling/Spans.ts +3 -17
- package/src/profiling/debug-telemetry.ts +2 -6
- package/src/profiling/render-list-validate.ts +6 -15
- package/src/projection-marker.ts +2 -1
- package/src/quiet-markers.ts +3 -10
- package/src/render/cpu-bvh.ts +100 -0
- package/src/render/depth-pyramid.ts +6 -14
- package/src/render/environment/environmentContribution.ts +202 -0
- package/src/render/environment/environmentRadiance.ts +44 -0
- package/src/render/environment/environmentSampleCache.ts +56 -0
- package/src/render/environment/environmentSampling.ts +201 -0
- package/src/render/environment/environmentSnapshot.ts +71 -0
- package/src/render/environment/gate.ts +57 -0
- package/src/render/mesh-pool.ts +3 -19
- package/src/render/probe-trace.ts +872 -0
- package/src/render/probe-volume.ts +780 -34
- package/src/render/radiance-cache.ts +17 -0
- package/src/render/virtual-shadow-partial.ts +13 -0
- package/src/render/virtual-shadow.ts +18 -16
- package/src/render/world-impostor-surface.ts +109 -6
- package/src/render/world-impostor.ts +5 -2
- package/src/render-camera-cull.ts +98 -3
- package/src/render-environment.ts +41 -0
- package/src/renderer-config.ts +36 -0
- package/src/renderer-facts.ts +37 -0
- package/src/renderer.ts +52 -28
- package/src/resolution-scaler.ts +3 -2
- package/src/scene-entry-inspectors.ts +61 -0
- package/src/snow-field.ts +1 -0
- package/src/startup-offscreen-bytes.ts +78 -0
- package/src/static-transform.ts +25 -19
- package/src/streamed-textures.ts +112 -0
- package/src/streaming.ts +68 -4
- package/src/texture-streaming.ts +331 -0
- package/src/version.ts +1 -1
- package/src/worker.ts +12 -2
- package/src/world-bundle-safety.ts +55 -10
- package/src/world-cell-batches.ts +162 -200
- package/src/world-cell-chunks.ts +3 -7
- package/src/world-cell-impostors.ts +20 -8
- package/src/world-cell-options.ts +2 -14
- package/src/world-cell-placements.ts +194 -90
- package/src/world-cell-prewarm.ts +39 -4
- package/src/world-cell-records.ts +401 -0
- package/src/world-cell-render-bundles.ts +2 -2
- package/src/world-cell-render-gpu-dress.ts +13 -17
- package/src/world-cell-render-main-cull.ts +73 -17
- package/src/world-cell-render-util.ts +17 -4
- package/src/world-cell-render.ts +13 -5
- package/src/world-cell-residency.ts +15 -6
- package/src/world-cell-stale.ts +238 -0
- package/src/world-cells.ts +22 -5
- package/src/world-gpu-flags.ts +18 -50
- package/src/world-gpu-reference.ts +22 -8
- package/src/world-gpu-scene.ts +44 -24
- package/src/world-gpu-shadow.ts +21 -8
- package/src/world-gpu-types.ts +41 -13
- package/src/world-load-limiter.ts +5 -0
- package/src/world-model-sections.ts +80 -0
- package/src/world-river-ribbon.ts +282 -0
- package/src/world-root-frame.ts +39 -0
- package/src/world-shore-field.ts +91 -0
- package/src/world-static-pose.ts +163 -0
- package/src/world-surface-sampler.ts +48 -0
- package/src/world-terrain-splat.ts +10 -18
- package/src/world-tile-budget.ts +4 -11
- package/src/world-tiles.ts +79 -12
- package/src/world-validate.ts +6 -14
- package/src/world-warm.ts +51 -0
- 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
|
|
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
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
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. */
|
package/src/world-tile-budget.ts
CHANGED
|
@@ -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
|
-
|
|
33
|
-
|
|
34
|
-
|
|
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
|
|
package/src/world-tiles.ts
CHANGED
|
@@ -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 =
|
|
1049
|
+
const { degenerate, depth } = selectLodFor(
|
|
999
1050
|
view.camera,
|
|
1000
|
-
sphere
|
|
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
|
|
1058
|
+
depth,
|
|
1009
1059
|
);
|
|
1010
|
-
projection = {
|
|
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
|
-
/**
|
|
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
|
-
|
|
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
|
|
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,
|
|
1501
|
+
{ ...view, degenerate, depth },
|
|
1435
1502
|
]);
|
|
1436
1503
|
}
|
|
1437
1504
|
|
package/src/world-validate.ts
CHANGED
|
@@ -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
|
-
|
|
35
|
-
|
|
36
|
-
__tnTerrainValidate
|
|
37
|
-
|
|
38
|
-
|
|
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
|
+
}
|