@threenative/core 0.3.4 → 0.3.5
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/capabilities.json +1505 -79
- package/dist/{audio-7i3Xl0l3.d.ts → audio-DIJE5HTr.d.ts} +43 -3
- package/dist/{canvas-layer-DDmC_VVF.d.ts → canvas-layer-C1-5CviZ.d.ts} +5 -1
- package/dist/{game-CljaDv4D.d.ts → game-Bj8G1wmD.d.ts} +102 -11
- package/dist/hot.d.ts +4 -4
- package/dist/index.d.ts +712 -118
- package/dist/index.js +12423 -4955
- package/dist/{gpu-readback-CqJEfWNQ.d.ts → model-lod-BDAUYgsS.d.ts} +80 -5
- package/dist/playtest.d.ts +6 -10
- package/dist/playtest.js +47 -24
- package/dist/react-css.d.ts +62 -0
- package/dist/react-css.js +591 -0
- package/dist/react.d.ts +2 -2
- package/dist/{renderer-CfsS2hxi.d.ts → renderer-9yEo9hPa.d.ts} +489 -22
- package/dist/terrain-jobs-worker.d.ts +2 -0
- package/dist/terrain-jobs-worker.js +130 -0
- package/dist/ui-layer.js +59 -8
- package/dist/world.d.ts +766 -73
- package/dist/world.js +9307 -3543
- package/gpl/recipes/export_world.py +18 -1
- package/mcp/blender-server.mjs +7 -4
- package/mcp/blender.mjs +3 -4
- package/mcp/engine-server.mjs +2 -2
- package/mcp/servers.mjs +4 -4
- package/package.json +15 -9
- package/patches/three@0.185.1-prd269-upgrade.patch +22418 -0
- package/patches/three@0.185.1.patch +6594 -700
- package/scripts/apply-three-patch.mjs +62 -4
- package/src/animation-blend.ts +264 -0
- package/src/animation-composition.ts +362 -0
- package/src/animation-layers.ts +260 -0
- package/src/animation-root-motion.ts +283 -0
- package/src/animation.ts +896 -0
- package/src/assets.ts +1303 -0
- package/src/atmosphere/index.ts +335 -0
- package/src/atmosphere/luts.ts +298 -0
- package/src/atmosphere/params.ts +323 -0
- package/src/audio.ts +912 -0
- package/src/billboard.ts +124 -0
- package/src/bone-lengths.ts +157 -0
- package/src/camera-shake.ts +116 -0
- package/src/canvas-layer.ts +47 -0
- package/src/clip-audit.ts +401 -0
- package/src/clustered-batch.ts +492 -0
- package/src/clustered-mesh.ts +638 -0
- package/src/compute-driven.ts +176 -0
- package/src/compute-timing.ts +318 -0
- package/src/config.ts +593 -0
- package/src/debug.ts +82 -0
- package/src/engine-render-hook.ts +25 -0
- package/src/entities.ts +79 -0
- package/src/entity-snapshot.ts +53 -0
- package/src/flight.ts +683 -0
- package/src/fluid-field.ts +748 -0
- package/src/fluid-particles.ts +1253 -0
- package/src/frame-budget.ts +1368 -0
- package/src/game.ts +2390 -0
- package/src/geometry-capture.ts +1098 -0
- package/src/gpu-class.ts +160 -0
- package/src/gpu-frame-observation.ts +424 -0
- package/src/gpu-readback.ts +143 -0
- package/src/gpu-scene-bvh.ts +464 -0
- package/src/grounding.ts +100 -0
- package/src/hot.ts +161 -0
- package/src/import-meta.d.ts +13 -0
- package/src/index.ts +1536 -0
- package/src/input.ts +690 -0
- package/src/instanced-batch-lod.ts +283 -0
- package/src/instanced-batch.ts +274 -0
- package/src/interpolation.ts +129 -0
- package/src/launch-diagnostics.ts +161 -0
- package/src/loop.ts +564 -0
- package/src/matrix-world.ts +245 -0
- package/src/merge-parts.ts +812 -0
- package/src/model-lod.ts +1315 -0
- package/src/net-protocol.ts +333 -0
- package/src/net-session.ts +477 -0
- package/src/net.ts +80 -0
- package/src/ocean/fft.ts +72 -0
- package/src/ocean/spectral.ts +728 -0
- package/src/particle-significance.ts +102 -0
- package/src/particles.ts +648 -0
- package/src/path-follow.ts +175 -0
- package/src/picking.ts +250 -0
- package/src/pipeline-census.ts +1566 -0
- package/src/platform.ts +210 -0
- package/src/playtest.ts +839 -0
- package/src/pointer-events.ts +411 -0
- package/src/pose-measure.ts +435 -0
- package/src/profiling/FrameCounters.ts +231 -0
- package/src/profiling/Spans.ts +548 -0
- package/src/profiling/opacity-convention.ts +21 -0
- package/src/profiling/render-list-validate.ts +175 -0
- package/src/profiling/render-trap-audit.ts +84 -0
- package/src/profiling/scene-warning.ts +190 -0
- package/src/profiling/span-probes.ts +191 -0
- package/src/profiling/unlit-foliage-warning.ts +149 -0
- package/src/projection-apply.ts +1529 -0
- package/src/projection-marker.ts +142 -0
- package/src/projection-plan.ts +1258 -0
- package/src/projection-skinned.ts +419 -0
- package/src/projection-stability.ts +409 -0
- package/src/projection-uniform.ts +328 -0
- package/src/random.ts +41 -0
- package/src/react-css.ts +604 -0
- package/src/react-glyphs.ts +114 -0
- package/src/react-host.ts +576 -0
- package/src/react-layout.ts +265 -0
- package/src/react.ts +60 -0
- package/src/render/alpha-antialiasing.ts +159 -0
- package/src/render/batched-velocity.ts +126 -0
- package/src/render/chain.ts +1021 -0
- package/src/render/daylight.ts +189 -0
- package/src/render/depth-pyramid.ts +596 -0
- package/src/render/foliage-alpha.ts +166 -0
- package/src/render/material-key.ts +60 -0
- package/src/render/mesh-pool.ts +144 -0
- package/src/render/probe-volume.ts +1668 -0
- package/src/render/resolution-subrect.ts +253 -0
- package/src/render/velocity.ts +442 -0
- package/src/render/virtual-shadow-pages.ts +827 -0
- package/src/render/virtual-shadow-partial.ts +174 -0
- package/src/render/virtual-shadow.ts +3330 -0
- package/src/render/world-impostor-surface.ts +722 -0
- package/src/render/world-impostor.ts +558 -0
- package/src/render-camera-cull.ts +441 -0
- package/src/render-pass-budget.ts +501 -0
- package/src/renderProjection.ts +758 -0
- package/src/renderer-config.ts +127 -0
- package/src/renderer.ts +1847 -0
- package/src/replay-protocol.ts +85 -0
- package/src/replay.ts +205 -0
- package/src/resolution-scaler.ts +819 -0
- package/src/rig-preparation.ts +271 -0
- package/src/ripple-field.ts +432 -0
- package/src/scale.ts +109 -0
- package/src/scene.ts +239 -0
- package/src/schedule.ts +155 -0
- package/src/skeletal-mesh.ts +61 -0
- package/src/skeleton.ts +100 -0
- package/src/snow-field.ts +744 -0
- package/src/softbody-topology.ts +269 -0
- package/src/softbody.ts +516 -0
- package/src/sprite-animator.ts +222 -0
- package/src/startup-readiness.ts +386 -0
- package/src/state.ts +66 -0
- package/src/static-transform.ts +274 -0
- package/src/storage-buffer.ts +253 -0
- package/src/streaming.ts +308 -0
- package/src/target-fps.ts +92 -0
- package/src/terrain-jobs-worker.ts +17 -0
- package/src/terrain-jobs.ts +353 -0
- package/src/textures.ts +39 -0
- package/src/tracers.ts +237 -0
- package/src/ui-bridge.ts +368 -0
- package/src/ui-hit-regions.ts +380 -0
- package/src/ui-layer.ts +83 -0
- package/src/ui-state.ts +220 -0
- package/src/version.ts +2 -0
- package/src/viewport.ts +253 -0
- package/src/warmup.ts +1357 -0
- package/src/water-surface.ts +384 -0
- package/src/wave-field.ts +524 -0
- package/src/world-capabilities.ts +131 -0
- package/src/world-cell-proxy.ts +392 -0
- package/src/world-cells.ts +10564 -0
- package/src/world-gpu-scene.ts +3354 -0
- package/src/world-heightmap.ts +82 -0
- package/src/world-package.ts +469 -0
- package/src/world-passes.ts +582 -0
- package/src/world-region.ts +17 -0
- package/src/world-terrain-splat.ts +564 -0
- package/src/world-tiles.ts +3826 -0
- package/src/world-topology.ts +370 -0
- package/src/world-validate.ts +48 -0
- package/src/world.ts +805 -0
|
@@ -0,0 +1,432 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A disturbance that propagates. `WaveField` in this same package evaluates a fixed analytic
|
|
3
|
+
* swell: it is the sea a game always has, and nothing a game does changes it. This is the other
|
|
4
|
+
* half — a square patch of surface that is flat until something hits it, carries the rings
|
|
5
|
+
* outward at a real celerity, and forgets them again.
|
|
6
|
+
*
|
|
7
|
+
* The solve is the 2-D wave equation on a regular grid, plus an advected foam density. It owns no
|
|
8
|
+
* Three.js object, no material and no colour: it reports height, foam and horizontal flow, and the
|
|
9
|
+
* game decides what those look like. Add its height to an analytic swell; do not replace one.
|
|
10
|
+
*
|
|
11
|
+
* There is deliberately no obstacle or hull mask. A mask is only correct for a body that does not
|
|
12
|
+
* move, and a game whose hulls move is better served drawing the displacement those hulls make
|
|
13
|
+
* than re-rasterising a mask every time one of them advances a metre.
|
|
14
|
+
*/
|
|
15
|
+
|
|
16
|
+
const clamp = (x: number, lo: number, hi: number): number => Math.max(lo, Math.min(hi, x));
|
|
17
|
+
|
|
18
|
+
const finite = (value: number, label: string): number => {
|
|
19
|
+
if (!Number.isFinite(value)) throw new TypeError(`${label} must be finite`);
|
|
20
|
+
return value;
|
|
21
|
+
};
|
|
22
|
+
|
|
23
|
+
export interface IRippleFieldFlow {
|
|
24
|
+
x: number;
|
|
25
|
+
z: number;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
export interface IRippleFieldOptions {
|
|
29
|
+
/** Cells per side. Cost is quadratic in this; 128 over a 400 m patch is ~3 m per cell. */
|
|
30
|
+
readonly resolution: number;
|
|
31
|
+
/** Width of the patch in metres. */
|
|
32
|
+
readonly size: number;
|
|
33
|
+
/** Wave celerity in metres per second. Sets both ring speed and the stable step. */
|
|
34
|
+
readonly speed?: number;
|
|
35
|
+
/** Bulk damping. Higher forgets a disturbance sooner. */
|
|
36
|
+
readonly damping?: number;
|
|
37
|
+
/** Seconds for undisturbed foam to halve. */
|
|
38
|
+
readonly foamHalfLife?: number;
|
|
39
|
+
/** Steady surface drift in metres per second, added to the solved flow. */
|
|
40
|
+
readonly current?: IRippleFieldFlow;
|
|
41
|
+
/**
|
|
42
|
+
* Integration step in seconds. Defaults to 1/60 s, or the CFL limit for this cell size and
|
|
43
|
+
* celerity where that is smaller.
|
|
44
|
+
*/
|
|
45
|
+
readonly step?: number;
|
|
46
|
+
/** Substeps one `advance` will run before it drops the rest of the frame's time. */
|
|
47
|
+
readonly maxSteps?: number;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
export class RippleField {
|
|
51
|
+
readonly resolution: number;
|
|
52
|
+
readonly size: number;
|
|
53
|
+
readonly dx: number;
|
|
54
|
+
readonly speed: number;
|
|
55
|
+
readonly damping: number;
|
|
56
|
+
readonly step: number;
|
|
57
|
+
readonly maxSteps: number;
|
|
58
|
+
foamHalfLife: number;
|
|
59
|
+
current: IRippleFieldFlow;
|
|
60
|
+
|
|
61
|
+
/** Surface height per cell, row-major from the patch's -x/-z corner. Read-only to the game. */
|
|
62
|
+
height: Float32Array;
|
|
63
|
+
/** Foam density per cell in 0..1. */
|
|
64
|
+
foam: Float32Array;
|
|
65
|
+
/** Horizontal flow per cell, metres per second, excluding `current`. */
|
|
66
|
+
readonly flowX: Float32Array;
|
|
67
|
+
readonly flowZ: Float32Array;
|
|
68
|
+
|
|
69
|
+
/** Patch centre in world metres, always snapped to a whole cell. */
|
|
70
|
+
centerX = 0;
|
|
71
|
+
centerZ = 0;
|
|
72
|
+
/** Simulated seconds elapsed. */
|
|
73
|
+
time = 0;
|
|
74
|
+
/** Bumped whenever a cell changes, so a texture upload can skip an unchanged frame. */
|
|
75
|
+
version = 0;
|
|
76
|
+
|
|
77
|
+
#velocity: Float32Array;
|
|
78
|
+
#scratch: Float32Array;
|
|
79
|
+
#foamScratch: Float32Array;
|
|
80
|
+
#loss: Float32Array;
|
|
81
|
+
#remainder = 0;
|
|
82
|
+
#foamClock = 0;
|
|
83
|
+
/**
|
|
84
|
+
* Exactly, provably flat: every cell of every array is zero. Not "small", not "quiet", not "no
|
|
85
|
+
* recent events" — an epsilon or an energy threshold would delete a real wave that had simply got
|
|
86
|
+
* far from the camera, and an event clock would delete a foam trail that is still drifting. This
|
|
87
|
+
* is only ever true because the field was constructed, reset, or cleared whole; the first
|
|
88
|
+
* accepted impulse or foam deposit ends it immediately.
|
|
89
|
+
*/
|
|
90
|
+
#empty = true;
|
|
91
|
+
|
|
92
|
+
constructor(options: IRippleFieldOptions) {
|
|
93
|
+
const { resolution, size } = options;
|
|
94
|
+
if (!Number.isInteger(resolution) || resolution < 16 || resolution > 1024)
|
|
95
|
+
throw new RangeError("resolution must be an integer in 16..1024");
|
|
96
|
+
if (!Number.isFinite(size) || size <= 0) throw new RangeError("size must be a positive length");
|
|
97
|
+
this.resolution = resolution;
|
|
98
|
+
this.size = size;
|
|
99
|
+
this.dx = size / (resolution - 1);
|
|
100
|
+
this.speed = finite(options.speed ?? 22, "speed");
|
|
101
|
+
this.damping = finite(options.damping ?? 0.27, "damping");
|
|
102
|
+
if (this.speed <= 0 || this.damping < 0)
|
|
103
|
+
throw new RangeError("speed must be positive and damping non-negative");
|
|
104
|
+
this.foamHalfLife = finite(options.foamHalfLife ?? 7, "foamHalfLife");
|
|
105
|
+
this.current = { x: options.current?.x ?? 0, z: options.current?.z ?? 0 };
|
|
106
|
+
// The 2-D CFL limit is c·dt/dx <= 1/sqrt(2); above it the solve explodes. On a coarse patch
|
|
107
|
+
// that limit is a long way above 1/60 s, and taking it makes the field correct and visibly
|
|
108
|
+
// steppy — a ring that expands five times a second under a screen refreshing sixty. The
|
|
109
|
+
// default is therefore the smaller of a display-rate step and what stability allows.
|
|
110
|
+
const limit = this.dx / (this.speed * Math.SQRT2);
|
|
111
|
+
this.step = options.step ?? Math.min(limit * 0.9, 1 / 60);
|
|
112
|
+
if (!(this.step > 0) || this.step > limit)
|
|
113
|
+
throw new RangeError(`step must be positive and at most the CFL limit ${limit.toFixed(5)}s`);
|
|
114
|
+
this.maxSteps = options.maxSteps ?? 8;
|
|
115
|
+
if (!Number.isInteger(this.maxSteps) || this.maxSteps < 1)
|
|
116
|
+
throw new RangeError("maxSteps must be a positive integer");
|
|
117
|
+
|
|
118
|
+
const count = resolution * resolution;
|
|
119
|
+
this.height = new Float32Array(count);
|
|
120
|
+
this.foam = new Float32Array(count);
|
|
121
|
+
this.flowX = new Float32Array(count);
|
|
122
|
+
this.flowZ = new Float32Array(count);
|
|
123
|
+
this.#velocity = new Float32Array(count);
|
|
124
|
+
this.#scratch = new Float32Array(count);
|
|
125
|
+
this.#foamScratch = new Float32Array(count);
|
|
126
|
+
// A sponge band at the rim absorbs what reaches it, so a ring leaves the patch instead of
|
|
127
|
+
// bouncing off a wall the player cannot see.
|
|
128
|
+
this.#loss = new Float32Array(count);
|
|
129
|
+
for (let j = 0; j < resolution; j++)
|
|
130
|
+
for (let i = 0; i < resolution; i++) {
|
|
131
|
+
const edge = Math.min(i, j, resolution - 1 - i, resolution - 1 - j);
|
|
132
|
+
const sponge = 1 - clamp(edge / 12, 0, 1);
|
|
133
|
+
this.#loss[j * resolution + i] = this.damping + 6 * sponge * sponge;
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
/** True while the point is inside the patch, `margin` metres in from its rim. */
|
|
138
|
+
contains(x: number, z: number, margin = 0): boolean {
|
|
139
|
+
const half = this.size / 2 - margin;
|
|
140
|
+
return Math.abs(x - this.centerX) < half && Math.abs(z - this.centerZ) < half;
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
/**
|
|
144
|
+
* Move the patch so it covers the action. The grid shifts by whole cells and the newly exposed
|
|
145
|
+
* band arrives flat, which is what the sponge rim had already damped it to.
|
|
146
|
+
*/
|
|
147
|
+
recenter(x: number, z: number): void {
|
|
148
|
+
finite(x, "x");
|
|
149
|
+
finite(z, "z");
|
|
150
|
+
const di = Math.round((x - this.centerX) / this.dx);
|
|
151
|
+
const dj = Math.round((z - this.centerZ) / this.dx);
|
|
152
|
+
if (di === 0 && dj === 0) return;
|
|
153
|
+
this.centerX += di * this.dx;
|
|
154
|
+
this.centerZ += dj * this.dx;
|
|
155
|
+
// Shifting zeros produces zeros. An empty patch moving with the camera therefore touches no
|
|
156
|
+
// array and its texture data does not change; the centre uniform is what tells a material the
|
|
157
|
+
// patch moved, and that is updated by the game either way.
|
|
158
|
+
if (this.#empty) return;
|
|
159
|
+
if (Math.abs(di) >= this.resolution || Math.abs(dj) >= this.resolution) {
|
|
160
|
+
this.height.fill(0);
|
|
161
|
+
this.#velocity.fill(0);
|
|
162
|
+
this.foam.fill(0);
|
|
163
|
+
this.flowX.fill(0);
|
|
164
|
+
this.flowZ.fill(0);
|
|
165
|
+
// Cleared whole, from a patch that was not flat: exactly empty again, and the version must
|
|
166
|
+
// still move once so the previous image is cleared off the GPU.
|
|
167
|
+
this.#empty = true;
|
|
168
|
+
} else {
|
|
169
|
+
for (const data of [this.height, this.#velocity, this.foam, this.flowX, this.flowZ])
|
|
170
|
+
this.#shift(data, di, dj);
|
|
171
|
+
}
|
|
172
|
+
this.version++;
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
#shift(data: Float32Array, di: number, dj: number): void {
|
|
176
|
+
const n = this.resolution;
|
|
177
|
+
const scratch = this.#scratch;
|
|
178
|
+
scratch.fill(0);
|
|
179
|
+
const i0 = Math.max(0, -di);
|
|
180
|
+
const i1 = Math.min(n, n - di);
|
|
181
|
+
const j0 = Math.max(0, -dj);
|
|
182
|
+
const j1 = Math.min(n, n - dj);
|
|
183
|
+
for (let j = j0; j < j1; j++) {
|
|
184
|
+
const source = (j + dj) * n + i0 + di;
|
|
185
|
+
scratch.set(data.subarray(source, source + (i1 - i0)), j * n + i0);
|
|
186
|
+
}
|
|
187
|
+
data.set(scratch);
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
/**
|
|
191
|
+
* Push the surface at a point: a Gaussian of the given radius, with the kernel corrected so the
|
|
192
|
+
* disturbance injects no net volume. Without that correction every splash slowly raises the sea.
|
|
193
|
+
* Returns false when the point is outside the patch.
|
|
194
|
+
*/
|
|
195
|
+
impulse(x: number, z: number, radius: number, amplitude: number, foam = 0): boolean {
|
|
196
|
+
finite(x, "x");
|
|
197
|
+
finite(z, "z");
|
|
198
|
+
finite(amplitude, "amplitude");
|
|
199
|
+
finite(foam, "foam");
|
|
200
|
+
if (!(radius > 0)) throw new RangeError("radius must be positive");
|
|
201
|
+
if (!this.contains(x, z)) return false;
|
|
202
|
+
// A push of nothing, carrying no foam, is in bounds and accepted — and changes no cell. It must
|
|
203
|
+
// not announce a new texture image, and it must not end an exactly empty patch: a game that
|
|
204
|
+
// scales its impulse by a frame delta hands this exact call in on every paused frame.
|
|
205
|
+
if (amplitude === 0 && foam === 0) return true;
|
|
206
|
+
const n = this.resolution;
|
|
207
|
+
const ix = ((x - this.centerX) / this.size + 0.5) * (n - 1);
|
|
208
|
+
const iz = ((z - this.centerZ) / this.size + 0.5) * (n - 1);
|
|
209
|
+
const r = Math.max(0.75, radius / this.dx);
|
|
210
|
+
const loX = Math.max(1, Math.floor(ix - 3 * r));
|
|
211
|
+
const hiX = Math.min(n - 2, Math.ceil(ix + 3 * r));
|
|
212
|
+
const loZ = Math.max(1, Math.floor(iz - 3 * r));
|
|
213
|
+
const hiZ = Math.min(n - 2, Math.ceil(iz + 3 * r));
|
|
214
|
+
let kernelSum = 0;
|
|
215
|
+
let weightSum = 0;
|
|
216
|
+
for (let j = loZ; j <= hiZ; j++)
|
|
217
|
+
for (let i = loX; i <= hiX; i++) {
|
|
218
|
+
const q = ((i - ix) ** 2 + (j - iz) ** 2) / (r * r);
|
|
219
|
+
const g = Math.exp(-q);
|
|
220
|
+
kernelSum += (1 - q) * g;
|
|
221
|
+
weightSum += g;
|
|
222
|
+
}
|
|
223
|
+
const correction = weightSum > 0 ? kernelSum / weightSum : 0;
|
|
224
|
+
for (let j = loZ; j <= hiZ; j++)
|
|
225
|
+
for (let i = loX; i <= hiX; i++) {
|
|
226
|
+
const k = j * n + i;
|
|
227
|
+
const q = ((i - ix) ** 2 + (j - iz) ** 2) / (r * r);
|
|
228
|
+
const g = Math.exp(-q);
|
|
229
|
+
this.#velocity[k] = (this.#velocity[k] as number) + amplitude * (1 - q - correction) * g;
|
|
230
|
+
if (foam !== 0) this.foam[k] = clamp((this.foam[k] as number) + g * foam, 0, 1);
|
|
231
|
+
}
|
|
232
|
+
this.#empty = false;
|
|
233
|
+
this.version++;
|
|
234
|
+
return true;
|
|
235
|
+
}
|
|
236
|
+
|
|
237
|
+
/** Lay down entrained air without claiming a pressure impulse happened. */
|
|
238
|
+
depositFoam(x: number, z: number, radius: number, amount: number): boolean {
|
|
239
|
+
finite(x, "x");
|
|
240
|
+
finite(z, "z");
|
|
241
|
+
if (!(radius > 0) || !(amount >= 0))
|
|
242
|
+
throw new RangeError("radius must be positive and amount non-negative");
|
|
243
|
+
if (!this.contains(x, z)) return false;
|
|
244
|
+
// Laying down no foam is the same non-event: accepted, in bounds, and not a change.
|
|
245
|
+
if (amount === 0) return true;
|
|
246
|
+
const n = this.resolution;
|
|
247
|
+
const ix = ((x - this.centerX) / this.size + 0.5) * (n - 1);
|
|
248
|
+
const iz = ((z - this.centerZ) / this.size + 0.5) * (n - 1);
|
|
249
|
+
const r = Math.max(0.65, radius / this.dx);
|
|
250
|
+
for (
|
|
251
|
+
let j = Math.max(1, Math.floor(iz - 2 * r));
|
|
252
|
+
j <= Math.min(n - 2, Math.ceil(iz + 2 * r));
|
|
253
|
+
j++
|
|
254
|
+
)
|
|
255
|
+
for (
|
|
256
|
+
let i = Math.max(1, Math.floor(ix - 2 * r));
|
|
257
|
+
i <= Math.min(n - 2, Math.ceil(ix + 2 * r));
|
|
258
|
+
i++
|
|
259
|
+
) {
|
|
260
|
+
const k = j * n + i;
|
|
261
|
+
const g = Math.exp(-(((i - ix) ** 2 + (j - iz) ** 2) / (r * r)));
|
|
262
|
+
this.foam[k] = clamp((this.foam[k] as number) + g * amount, 0, 1);
|
|
263
|
+
}
|
|
264
|
+
this.#empty = false;
|
|
265
|
+
this.version++;
|
|
266
|
+
return true;
|
|
267
|
+
}
|
|
268
|
+
|
|
269
|
+
/** Run whole fixed steps to consume `dt`, and report how many ran. */
|
|
270
|
+
advance(dt: number): number {
|
|
271
|
+
if (!Number.isFinite(dt) || dt < 0) throw new RangeError("dt must be finite and non-negative");
|
|
272
|
+
this.#remainder += Math.min(dt, this.step * this.maxSteps);
|
|
273
|
+
let steps = 0;
|
|
274
|
+
while (this.#remainder + 1e-10 >= this.step && steps < this.maxSteps) {
|
|
275
|
+
this.#remainder -= this.step;
|
|
276
|
+
this.time += this.step;
|
|
277
|
+
this.#integrate(this.step);
|
|
278
|
+
steps++;
|
|
279
|
+
}
|
|
280
|
+
this.#remainder = Math.max(0, this.#remainder);
|
|
281
|
+
// Time passing over a flat patch changes no cell, so it is not a new texture image.
|
|
282
|
+
if (steps > 0 && !this.#empty) this.version++;
|
|
283
|
+
return steps;
|
|
284
|
+
}
|
|
285
|
+
|
|
286
|
+
#integrate(dt: number): void {
|
|
287
|
+
if (this.#empty) {
|
|
288
|
+
// The wave equation on a patch of zeros returns zeros: the laplacian is zero, the velocity
|
|
289
|
+
// stays zero, no crest can break, and semi-Lagrangian transport of no foam moves no foam.
|
|
290
|
+
// The step still happened — `time` and the foam cadence advance above and here — so the
|
|
291
|
+
// first impulse after a long calm lands on exactly the phase it would have landed on.
|
|
292
|
+
this.#foamClock += dt;
|
|
293
|
+
if (this.#foamClock >= 1 / 30 - 1e-8) this.#foamClock = 0;
|
|
294
|
+
return;
|
|
295
|
+
}
|
|
296
|
+
const n = this.resolution;
|
|
297
|
+
const h = this.height;
|
|
298
|
+
const v = this.#velocity;
|
|
299
|
+
const next = this.#scratch;
|
|
300
|
+
const { foam, flowX, flowZ, dx } = this;
|
|
301
|
+
const loss = this.#loss;
|
|
302
|
+
const c = (this.speed * this.speed) / (dx * dx);
|
|
303
|
+
for (let j = 1; j < n - 1; j++)
|
|
304
|
+
for (let i = 1; i < n - 1; i++) {
|
|
305
|
+
const k = j * n + i;
|
|
306
|
+
const a = h[k - 1] as number;
|
|
307
|
+
const b = h[k + 1] as number;
|
|
308
|
+
const d = h[k - n] as number;
|
|
309
|
+
const e = h[k + n] as number;
|
|
310
|
+
const lap = a + b + d + e - 4 * (h[k] as number);
|
|
311
|
+
v[k] = ((v[k] as number) + c * lap * dt) / (1 + (loss[k] as number) * dt);
|
|
312
|
+
next[k] = (h[k] as number) + (v[k] as number) * dt;
|
|
313
|
+
// Horizontal flow is the surface gradient relaxing under gravity — enough to drift foam
|
|
314
|
+
// down the face of a wave, and far short of a three-dimensional solve.
|
|
315
|
+
const gx = (b - a) / (2 * dx);
|
|
316
|
+
const gz = (e - d) / (2 * dx);
|
|
317
|
+
flowX[k] = clamp(((flowX[k] as number) - 9.81 * gx * dt) / (1 + 0.65 * dt), -9, 9);
|
|
318
|
+
flowZ[k] = clamp(((flowZ[k] as number) - 9.81 * gz * dt) / (1 + 0.65 * dt), -9, 9);
|
|
319
|
+
// A crest that is both steep and collapsing is a crest that is breaking, and a breaking
|
|
320
|
+
// crest is white. Calm swell never satisfies both and so never invents foam.
|
|
321
|
+
// `Math.sqrt` of the squares, not `Math.hypot`: V8's hypot pays for an overflow-safe
|
|
322
|
+
// scaling pass this loop can never need, and it ran 6.4x slower per cell, which made it the
|
|
323
|
+
// single largest cost in the whole solver. The two are not bit-identical — sqrt-of-squares
|
|
324
|
+
// loses up to 2 ulp when one component is negligible beside the other — and that is
|
|
325
|
+
// licensed only because this magnitude reaches `foam` alone, never `height` or `velocity`,
|
|
326
|
+
// so no float, hull pose or height query can observe it. `__tests__` pins the 2-ulp bound.
|
|
327
|
+
const breaking =
|
|
328
|
+
lap < 0
|
|
329
|
+
? Math.max(0, Math.sqrt(gx * gx + gz * gz) - 0.3) *
|
|
330
|
+
Math.min(3, Math.abs(v[k] as number))
|
|
331
|
+
: 0;
|
|
332
|
+
if (breaking > 0) foam[k] = clamp((foam[k] as number) + breaking * dt * 0.55, 0, 1);
|
|
333
|
+
}
|
|
334
|
+
this.height = next;
|
|
335
|
+
this.#scratch = h;
|
|
336
|
+
this.#foamClock += dt;
|
|
337
|
+
if (this.#foamClock >= 1 / 30 - 1e-8) {
|
|
338
|
+
this.#transportFoam(this.#foamClock);
|
|
339
|
+
this.#foamClock = 0;
|
|
340
|
+
}
|
|
341
|
+
}
|
|
342
|
+
|
|
343
|
+
/** Semi-Lagrangian transport at 30 Hz. Foam drifts and spreads; it does not sit where it fell. */
|
|
344
|
+
#transportFoam(dt: number): void {
|
|
345
|
+
const n = this.resolution;
|
|
346
|
+
const { foam, flowX, flowZ, dx, current } = this;
|
|
347
|
+
const next = this.#foamScratch;
|
|
348
|
+
const decay = Math.exp((-Math.LN2 * dt) / this.foamHalfLife);
|
|
349
|
+
next.fill(0);
|
|
350
|
+
for (let j = 1; j < n - 1; j++)
|
|
351
|
+
for (let i = 1; i < n - 1; i++) {
|
|
352
|
+
const k = j * n + i;
|
|
353
|
+
const x = clamp(i - ((current.x + (flowX[k] as number)) * dt) / dx, 0, n - 1.001);
|
|
354
|
+
const z = clamp(j - ((current.z + (flowZ[k] as number)) * dt) / dx, 0, n - 1.001);
|
|
355
|
+
const a = Math.floor(x);
|
|
356
|
+
const b = Math.floor(z);
|
|
357
|
+
const q = b * n + a;
|
|
358
|
+
const u = x - a;
|
|
359
|
+
const w = z - b;
|
|
360
|
+
const back =
|
|
361
|
+
((foam[q] as number) * (1 - u) + (foam[q + 1] as number) * u) * (1 - w) +
|
|
362
|
+
((foam[q + n] as number) * (1 - u) + (foam[q + n + 1] as number) * u) * w;
|
|
363
|
+
const lap =
|
|
364
|
+
(foam[k - 1] as number) +
|
|
365
|
+
(foam[k + 1] as number) +
|
|
366
|
+
(foam[k - n] as number) +
|
|
367
|
+
(foam[k + n] as number) -
|
|
368
|
+
4 * (foam[k] as number);
|
|
369
|
+
next[k] = clamp((back + lap * 0.06 * dt) * decay, 0, 1);
|
|
370
|
+
}
|
|
371
|
+
this.foam = next;
|
|
372
|
+
this.#foamScratch = foam;
|
|
373
|
+
}
|
|
374
|
+
|
|
375
|
+
#sample(x: number, z: number, data: Float32Array): number {
|
|
376
|
+
const n = this.resolution;
|
|
377
|
+
const fx = ((x - this.centerX) / this.size + 0.5) * (n - 1);
|
|
378
|
+
const fz = ((z - this.centerZ) / this.size + 0.5) * (n - 1);
|
|
379
|
+
if (fx < 0 || fz < 0 || fx >= n - 1 || fz >= n - 1) return 0;
|
|
380
|
+
const ix = Math.floor(fx);
|
|
381
|
+
const iz = Math.floor(fz);
|
|
382
|
+
const a = fx - ix;
|
|
383
|
+
const b = fz - iz;
|
|
384
|
+
const k = iz * n + ix;
|
|
385
|
+
return (
|
|
386
|
+
((data[k] as number) * (1 - a) + (data[k + 1] as number) * a) * (1 - b) +
|
|
387
|
+
((data[k + n] as number) * (1 - a) + (data[k + n + 1] as number) * a) * b
|
|
388
|
+
);
|
|
389
|
+
}
|
|
390
|
+
|
|
391
|
+
/** Disturbance height in metres at a world point, zero outside the patch. */
|
|
392
|
+
heightAt(x: number, z: number): number {
|
|
393
|
+
return this.#sample(x, z, this.height);
|
|
394
|
+
}
|
|
395
|
+
|
|
396
|
+
/** Foam density in 0..1 at a world point. */
|
|
397
|
+
foamAt(x: number, z: number): number {
|
|
398
|
+
return this.#sample(x, z, this.foam);
|
|
399
|
+
}
|
|
400
|
+
|
|
401
|
+
/** Surface flow in metres per second at a world point, including `current`. */
|
|
402
|
+
flowAt(x: number, z: number, out: IRippleFieldFlow = { x: 0, z: 0 }): IRippleFieldFlow {
|
|
403
|
+
out.x = this.current.x + this.#sample(x, z, this.flowX);
|
|
404
|
+
out.z = this.current.z + this.#sample(x, z, this.flowZ);
|
|
405
|
+
return out;
|
|
406
|
+
}
|
|
407
|
+
|
|
408
|
+
/** Total disturbance energy. Zero on an undisturbed patch; useful as a test oracle. */
|
|
409
|
+
energy(): number {
|
|
410
|
+
let total = 0;
|
|
411
|
+
for (let i = 0; i < this.height.length; i++)
|
|
412
|
+
total +=
|
|
413
|
+
(this.height[i] as number) ** 2 +
|
|
414
|
+
(this.#velocity[i] as number) ** 2 / (this.speed * this.speed);
|
|
415
|
+
return total;
|
|
416
|
+
}
|
|
417
|
+
|
|
418
|
+
/** Flatten the patch and forget every disturbance. Position, options and time survive. */
|
|
419
|
+
reset(): void {
|
|
420
|
+
this.height.fill(0);
|
|
421
|
+
this.foam.fill(0);
|
|
422
|
+
this.flowX.fill(0);
|
|
423
|
+
this.flowZ.fill(0);
|
|
424
|
+
this.#velocity.fill(0);
|
|
425
|
+
this.#scratch.fill(0);
|
|
426
|
+
this.#foamScratch.fill(0);
|
|
427
|
+
this.#remainder = 0;
|
|
428
|
+
this.#foamClock = 0;
|
|
429
|
+
this.#empty = true;
|
|
430
|
+
this.version++;
|
|
431
|
+
}
|
|
432
|
+
}
|
package/src/scale.ts
ADDED
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
import { Box3, type Object3D } from "three";
|
|
2
|
+
|
|
3
|
+
export type NormaliseAxis = "height" | "longest";
|
|
4
|
+
|
|
5
|
+
export interface INormaliseToMetresOptions {
|
|
6
|
+
readonly metres: number;
|
|
7
|
+
readonly axis: NormaliseAxis;
|
|
8
|
+
/** Crown bone to use for a skinned height measurement. Defaults to a named/highest bone. */
|
|
9
|
+
readonly top?: Object3D | string;
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* Scale an asset to a real-world size and return the factor applied.
|
|
14
|
+
*
|
|
15
|
+
* Height for a skinned asset comes from its crown bone, not its bind-pose Box3. Longest-axis
|
|
16
|
+
* normalization remains a geometry measurement because it is used for rigid props and weapons.
|
|
17
|
+
*/
|
|
18
|
+
export function normaliseToMetres(object: Object3D, options: INormaliseToMetresOptions): number {
|
|
19
|
+
if (!Number.isFinite(options.metres) || options.metres <= 0) {
|
|
20
|
+
throw new Error("normaliseToMetres metres must be finite and positive.");
|
|
21
|
+
}
|
|
22
|
+
if (options.axis !== "height" && options.axis !== "longest") {
|
|
23
|
+
throw new Error("normaliseToMetres axis must be 'height' or 'longest'.");
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
object.updateWorldMatrix(true, true);
|
|
27
|
+
const current =
|
|
28
|
+
options.axis === "height" ? measuredHeight(object, options.top) : measuredLongestAxis(object);
|
|
29
|
+
const factor = current > 0 && Number.isFinite(current) ? options.metres / current : 1;
|
|
30
|
+
object.scale.multiplyScalar(factor);
|
|
31
|
+
object.updateWorldMatrix(true, true);
|
|
32
|
+
return factor;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
function measuredHeight(object: Object3D, requestedTop: Object3D | string | undefined): number {
|
|
36
|
+
const originY = object.matrixWorld.elements[13];
|
|
37
|
+
const skinned = hasSkinnedMesh(object);
|
|
38
|
+
const top = resolveTop(object, requestedTop, skinned);
|
|
39
|
+
if (top !== undefined) return top.matrixWorld.elements[13] - originY;
|
|
40
|
+
if (skinned) return 0;
|
|
41
|
+
|
|
42
|
+
const bounds = new Box3().setFromObject(object, true);
|
|
43
|
+
return bounds.isEmpty() ? 0 : bounds.max.y - bounds.min.y;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
function measuredLongestAxis(object: Object3D): number {
|
|
47
|
+
const bounds = new Box3().setFromObject(object);
|
|
48
|
+
if (bounds.isEmpty()) return 0;
|
|
49
|
+
return Math.max(
|
|
50
|
+
bounds.max.x - bounds.min.x,
|
|
51
|
+
bounds.max.y - bounds.min.y,
|
|
52
|
+
bounds.max.z - bounds.min.z,
|
|
53
|
+
);
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
function hasSkinnedMesh(object: Object3D): boolean {
|
|
57
|
+
let found = false;
|
|
58
|
+
object.traverse((child) => {
|
|
59
|
+
if ((child as { isSkinnedMesh?: boolean }).isSkinnedMesh === true) found = true;
|
|
60
|
+
});
|
|
61
|
+
return found;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
function resolveTop(
|
|
65
|
+
object: Object3D,
|
|
66
|
+
requestedTop: Object3D | string | undefined,
|
|
67
|
+
skinned: boolean,
|
|
68
|
+
): Object3D | undefined {
|
|
69
|
+
if (requestedTop !== undefined && typeof requestedTop !== "string") return requestedTop;
|
|
70
|
+
if (typeof requestedTop === "string") {
|
|
71
|
+
const named = object.getObjectByName(requestedTop);
|
|
72
|
+
if (named !== undefined) return named;
|
|
73
|
+
throw new Error(`normaliseToMetres could not find top bone '${requestedTop}'.`);
|
|
74
|
+
}
|
|
75
|
+
if (!skinned) return undefined;
|
|
76
|
+
|
|
77
|
+
let crown: { readonly bone: Object3D; readonly rank: number } | undefined;
|
|
78
|
+
let highest: Object3D | undefined;
|
|
79
|
+
object.traverse((child) => {
|
|
80
|
+
if ((child as { isBone?: boolean }).isBone !== true) return;
|
|
81
|
+
if (
|
|
82
|
+
highest === undefined ||
|
|
83
|
+
child.matrixWorld.elements[13] > highest.matrixWorld.elements[13]
|
|
84
|
+
) {
|
|
85
|
+
highest = child;
|
|
86
|
+
}
|
|
87
|
+
const rank = crownRank(child.name);
|
|
88
|
+
if (
|
|
89
|
+
rank > 0 &&
|
|
90
|
+
(crown === undefined ||
|
|
91
|
+
rank > crown.rank ||
|
|
92
|
+
(rank === crown.rank &&
|
|
93
|
+
(child.matrixWorld.elements[13] > crown.bone.matrixWorld.elements[13] ||
|
|
94
|
+
(child.matrixWorld.elements[13] === crown.bone.matrixWorld.elements[13] &&
|
|
95
|
+
child.name.localeCompare(crown.bone.name) < 0))))
|
|
96
|
+
) {
|
|
97
|
+
crown = { bone: child, rank };
|
|
98
|
+
}
|
|
99
|
+
});
|
|
100
|
+
return crown?.bone ?? highest;
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
function crownRank(name: string): number {
|
|
104
|
+
const normalized = name.toLowerCase().replace(/[^a-z0-9]/gu, "");
|
|
105
|
+
if (normalized.includes("crown")) return 3;
|
|
106
|
+
if (normalized.endsWith("headtopend") || normalized.endsWith("headend")) return 3;
|
|
107
|
+
if (normalized.includes("headtop")) return 2;
|
|
108
|
+
return 0;
|
|
109
|
+
}
|