@threenative/core 0.3.3 → 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 +2019 -59
- package/dist/{assets-CYKk2WTu.d.ts → assets-CqvE429w.d.ts} +45 -3
- package/dist/{audio-7i3Xl0l3.d.ts → audio-DIJE5HTr.d.ts} +43 -3
- package/dist/{canvas-layer-C1SnMoJ-.d.ts → canvas-layer-C1-5CviZ.d.ts} +5 -1
- package/dist/{game-D_6r-k4Y.d.ts → game-Bj8G1wmD.d.ts} +242 -17
- package/dist/hot.d.ts +5 -5
- package/dist/index.d.ts +1131 -105
- package/dist/index.js +15201 -4782
- package/dist/model-lod-BDAUYgsS.d.ts +197 -0
- package/dist/playtest.d.ts +6 -4
- package/dist/playtest.js +84 -11
- 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-Cy4qeBOA.d.ts → renderer-9yEo9hPa.d.ts} +676 -21
- package/dist/terrain-jobs-worker.d.ts +2 -0
- package/dist/terrain-jobs-worker.js +130 -0
- package/dist/ui-layer.d.ts +5 -3
- package/dist/ui-layer.js +59 -8
- package/dist/world.d.ts +1596 -17
- package/dist/world.js +17035 -521
- package/gpl/fixtures/make_world_fixture.py +184 -0
- package/gpl/recipes/_common.py +11 -0
- package/gpl/recipes/decimate.py +11 -5
- package/gpl/recipes/export_world.py +699 -0
- package/mcp/blender-server.mjs +61 -4
- package/mcp/blender.mjs +3 -4
- package/mcp/engine-server.mjs +55 -21
- 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 +8246 -389
- package/scripts/apply-three-patch.mjs +123 -41
- 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
- package/dist/gpu-readback-CMklJs6r.d.ts +0 -112
|
@@ -0,0 +1,744 @@
|
|
|
1
|
+
import type { Vector3 } from "three";
|
|
2
|
+
import { unionBounds } from "./world-region.js";
|
|
3
|
+
import type { Heightfield, IHeightfieldRegionBounds } from "./world.js";
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* What one contact footprint wants at a local offset, sampled in the contact's own frame.
|
|
7
|
+
*
|
|
8
|
+
* A footprint describes a shape, never a load: the same sole sinks deeper under a heavier
|
|
9
|
+
* contact. Every field is 0..1 except `relief`, which is metres.
|
|
10
|
+
*/
|
|
11
|
+
export interface ISnowFootprintSample {
|
|
12
|
+
/** 0..1 fraction of the footprint touching snow here; erases displaced bank and adds compaction. */
|
|
13
|
+
readonly coverage: number;
|
|
14
|
+
/** 0..1 relative depth at this offset, so a toe can press deeper than a heel. */
|
|
15
|
+
readonly shape: number;
|
|
16
|
+
/** Metres of tread relief subtracted from the impression at this offset. */
|
|
17
|
+
readonly relief: number;
|
|
18
|
+
/** 0..1 raised snow pushed out beside the contact at this offset. */
|
|
19
|
+
readonly bank: number;
|
|
20
|
+
/** 0..1 surface disturbance at this offset, for render shading and game queries. */
|
|
21
|
+
readonly disturbance: number;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/** A game-authored contact shape: a boot sole, a tyre, a hull, a sphere. */
|
|
25
|
+
export interface ISnowFootprint {
|
|
26
|
+
/** Half-width of the square sampled around the contact centre, in metres. */
|
|
27
|
+
readonly extent: number;
|
|
28
|
+
/** Local contact-space sample; +z runs forward along the contact's orientation. */
|
|
29
|
+
readonly sample: (x: number, z: number) => ISnowFootprintSample;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** One contact between a supported object and the snow surface. */
|
|
33
|
+
export interface ISnowContact {
|
|
34
|
+
readonly x: number;
|
|
35
|
+
readonly z: number;
|
|
36
|
+
/** Game-authored imprint shape. */
|
|
37
|
+
readonly footprint: ISnowFootprint;
|
|
38
|
+
/** Supported contact area in square metres. Pressure is load over area, never a fixed constant. */
|
|
39
|
+
readonly area: number;
|
|
40
|
+
/** Normal load in newtons. */
|
|
41
|
+
readonly load: number;
|
|
42
|
+
/** Orientation about +y in radians. Default 0. */
|
|
43
|
+
readonly rotation?: number;
|
|
44
|
+
/** 0..1 snow hardness. Defaults to the field's hardness. */
|
|
45
|
+
readonly hardness?: number;
|
|
46
|
+
/** Seconds the contact is applied. Defaults to the field's response time. */
|
|
47
|
+
readonly duration?: number;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/** The four snow channels at one world position. */
|
|
51
|
+
export interface ISnowFieldSample {
|
|
52
|
+
readonly indent: number;
|
|
53
|
+
readonly bank: number;
|
|
54
|
+
readonly compaction: number;
|
|
55
|
+
readonly disturbance: number;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
export interface ISnowFieldOptions {
|
|
59
|
+
/** The canonical terrain. Snow composes onto it; there is no second terrain representation. */
|
|
60
|
+
readonly field: Heightfield;
|
|
61
|
+
/** Snow depth in metres. Zero is bare ground. Default 0.28. */
|
|
62
|
+
readonly depth?: number;
|
|
63
|
+
/** 0..1 snow hardness used by contacts that do not override it. Default 0.3. */
|
|
64
|
+
readonly hardness?: number;
|
|
65
|
+
/** Fraction of its target impression a contact reaches in one response time. Default 0.9. */
|
|
66
|
+
readonly yieldFraction?: number;
|
|
67
|
+
/** Metres of raised bank allowed beside a contact. Default 0.085. */
|
|
68
|
+
readonly maxBank?: number;
|
|
69
|
+
/** Seconds a fully-loaded contact takes to reach its full impression. Default 0.1. */
|
|
70
|
+
readonly responseTime?: number;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
export interface ISnowDiscFootprintOptions {
|
|
74
|
+
/** 0..1 width of the falloff at the disc's edge, as a fraction of the radius. Default 0.25. */
|
|
75
|
+
readonly softness?: number;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/** Resistance of snow to a contact at hardness 0, in pascals. Approximate, not a calibrated law. */
|
|
79
|
+
const PRESSURE_RESISTANCE_BASE = 18_000;
|
|
80
|
+
/** Extra resistance a fully hard contact meets at hardness 1, in pascals. */
|
|
81
|
+
const PRESSURE_RESISTANCE_HARDNESS = 140_000;
|
|
82
|
+
/** Fraction of the snow depth a contact reaches before it is fully loaded. */
|
|
83
|
+
const PRESSURE_DEPTH_FLOOR = 0.16;
|
|
84
|
+
/** Deepest fraction of the snow depth any single contact can reach. */
|
|
85
|
+
const MAX_PENETRATION_FRACTION = 0.82;
|
|
86
|
+
/** Deepest fraction of the snow depth indentation may reach before a contact stops compacting. */
|
|
87
|
+
const MAX_INDENT_FRACTION = 0.88;
|
|
88
|
+
/** Fraction of a contact's penetration that becomes raised bank height. */
|
|
89
|
+
const BANK_LOAD_SCALE = 0.38;
|
|
90
|
+
/** Below these channel values a recovered cell is fully buried and leaves the active set. */
|
|
91
|
+
const RECOVERED_INDENT = 0.0004;
|
|
92
|
+
const RECOVERED_COMPACTION = 0.008;
|
|
93
|
+
/** Wind decay per metre per second of wind, matched to the source study's feel. */
|
|
94
|
+
const WIND_EROSION = 0.00065;
|
|
95
|
+
/** Deposition burial rate per metre of fill. */
|
|
96
|
+
const DEPOSITION_BURIAL = 26;
|
|
97
|
+
/** Hard ceiling on cells one contact may span, so a malformed extent fails instead of allocating. */
|
|
98
|
+
const MAX_CONTACT_CELLS = 1 << 20;
|
|
99
|
+
|
|
100
|
+
const EMPTY_SAMPLE: ISnowFootprintSample = Object.freeze({
|
|
101
|
+
bank: 0,
|
|
102
|
+
coverage: 0,
|
|
103
|
+
disturbance: 0,
|
|
104
|
+
relief: 0,
|
|
105
|
+
shape: 0,
|
|
106
|
+
});
|
|
107
|
+
|
|
108
|
+
/** The single-cell window a grid index covers. */
|
|
109
|
+
function cellBounds(index: number, columns: number): IHeightfieldRegionBounds {
|
|
110
|
+
const row = Math.floor(index / columns);
|
|
111
|
+
return { column: index - row * columns, columns: 1, row, rows: 1 };
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/** The smallest window covering both inputs. */
|
|
115
|
+
|
|
116
|
+
function finite(value: number, name: string): number {
|
|
117
|
+
if (!Number.isFinite(value)) throw new Error(`SnowField ${name} must be finite.`);
|
|
118
|
+
return value;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
function nonNegative(value: number, name: string): number {
|
|
122
|
+
finite(value, name);
|
|
123
|
+
if (value < 0) throw new Error(`SnowField ${name} must not be negative.`);
|
|
124
|
+
return value;
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
function positive(value: number, name: string): number {
|
|
128
|
+
nonNegative(value, name);
|
|
129
|
+
if (value === 0) throw new Error(`SnowField ${name} must be greater than zero.`);
|
|
130
|
+
return value;
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
function clamp(value: number, minimum: number, maximum: number): number {
|
|
134
|
+
return Math.max(minimum, Math.min(maximum, value));
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
function lerp(from: number, to: number, amount: number): number {
|
|
138
|
+
return from + (to - from) * amount;
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
function smoothstep(edge0: number, edge1: number, value: number): number {
|
|
142
|
+
const t = clamp((value - edge0) / (edge1 - edge0), 0, 1);
|
|
143
|
+
return t * t * (3 - 2 * t);
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
function unit(sample: ISnowFootprintSample, name: string): ISnowFootprintSample {
|
|
147
|
+
const coverage = finite(sample.coverage, `${name}.coverage`);
|
|
148
|
+
const shape = finite(sample.shape, `${name}.shape`);
|
|
149
|
+
const relief = finite(sample.relief, `${name}.relief`);
|
|
150
|
+
const bank = finite(sample.bank, `${name}.bank`);
|
|
151
|
+
const disturbance = finite(sample.disturbance, `${name}.disturbance`);
|
|
152
|
+
if (relief < 0) throw new Error(`SnowField ${name}.relief must not be negative.`);
|
|
153
|
+
return {
|
|
154
|
+
bank: clamp(bank, 0, 1),
|
|
155
|
+
coverage: clamp(coverage, 0, 1),
|
|
156
|
+
disturbance: clamp(disturbance, 0, 1),
|
|
157
|
+
relief,
|
|
158
|
+
shape: clamp(shape, 0, 1),
|
|
159
|
+
};
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
/**
|
|
163
|
+
* A circular contact footprint, sized from a radius the caller measures.
|
|
164
|
+
*
|
|
165
|
+
* The shape a sphere, a ball, a wheel or a probe presses into snow, and the default the physics
|
|
166
|
+
* binding derives from a sphere's contact geometry. Flat inside the radius, eased over the
|
|
167
|
+
* softness band, with a raised rim just outside it.
|
|
168
|
+
* @situation press a ball, wheel or probe into snow
|
|
169
|
+
* @situation give a sphere a physically sized snow contact instead of a boot shape
|
|
170
|
+
* @constraint radius is metres; the footprint never grows with load, only deeper
|
|
171
|
+
* @override softness widens the eased edge without changing the contact radius
|
|
172
|
+
* @example const footprint = snowDiscFootprint(0.25);
|
|
173
|
+
*/
|
|
174
|
+
export function snowDiscFootprint(
|
|
175
|
+
radius: number,
|
|
176
|
+
options: ISnowDiscFootprintOptions = {},
|
|
177
|
+
): ISnowFootprint {
|
|
178
|
+
positive(radius, "disc radius");
|
|
179
|
+
const softness = clamp(finite(options.softness ?? 0.25, "disc softness"), 0.01, 1);
|
|
180
|
+
const inner = 1 - softness;
|
|
181
|
+
const outer = 1 + softness;
|
|
182
|
+
return {
|
|
183
|
+
extent: radius * outer,
|
|
184
|
+
sample: (x, z) => {
|
|
185
|
+
const distance = Math.hypot(x, z) / radius;
|
|
186
|
+
if (distance >= outer) return EMPTY_SAMPLE;
|
|
187
|
+
const coverage = distance <= inner ? 1 : 1 - smoothstep(inner, 1, distance);
|
|
188
|
+
const bank = distance > 1 ? Math.exp(-(((distance - 1) / (softness * 0.75)) ** 2)) : 0;
|
|
189
|
+
return {
|
|
190
|
+
bank,
|
|
191
|
+
coverage,
|
|
192
|
+
disturbance: Math.max(coverage, bank * 0.5),
|
|
193
|
+
relief: 0,
|
|
194
|
+
shape: 1,
|
|
195
|
+
};
|
|
196
|
+
},
|
|
197
|
+
};
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
/**
|
|
201
|
+
* Persistent snow deformation over one canonical heightfield.
|
|
202
|
+
*
|
|
203
|
+
* Snow keeps four channels per cell — indentation, displaced bank, compaction and disturbance —
|
|
204
|
+
* and writes the combined surface (`terrain + depth + bank - indent`) back into the heightfield
|
|
205
|
+
* it was given. Queries, rendered geometry and collider export therefore all read one surface,
|
|
206
|
+
* and no second terrain representation exists.
|
|
207
|
+
*
|
|
208
|
+
* The field is numeric only: it never chooses a boot, a tread, a particle, a material or a
|
|
209
|
+
* camera. Games supply terrain heights, the snow depth, the contact profile and the response
|
|
210
|
+
* coefficients; this class owns the storage, the load-dependent penetration and the bounded
|
|
211
|
+
* recovery. It is a heightfield approximation — not granular snow, displaced-volume
|
|
212
|
+
* conservation, avalanches, melting or a calibrated material law.
|
|
213
|
+
* @situation leave footprints, tracks and tyre ruts in snow that persist and fill in over time
|
|
214
|
+
* @situation let a pushed sphere carve a connected track and a dropped one settle into a crater
|
|
215
|
+
* @situation store snow deformation that rendered geometry and collision both read
|
|
216
|
+
* @situation reset a snowfield between rounds or change its depth at runtime
|
|
217
|
+
* @situation show how packed the snow is where people have walked or objects have rested
|
|
218
|
+
* @constraint the field composes onto a Heightfield; construct the terrain first and let this own the surface
|
|
219
|
+
* @constraint zero depth is bare ground: contacts register no indentation at all
|
|
220
|
+
* @constraint out-of-region heightAt and normalAt follow Heightfield's error contract; sample returns zeros
|
|
221
|
+
* @override depth, hardness, yieldFraction, maxBank and responseTime name the response coefficients
|
|
222
|
+
* @requires @threenative/core/world Heightfield as the canonical terrain and surface
|
|
223
|
+
* @example import { Heightfield } from "@threenative/core/world";
|
|
224
|
+
* const terrain = Heightfield.fromSampler({ rows: 129, columns: 129, width: 64, depth: 64, origin: { x: 0, z: 0 }, sampleHeight: (x, z) => Math.sin(x * 0.1) * 0.5 });
|
|
225
|
+
* const snow = new SnowField({ field: terrain, depth: 0.28, hardness: 0.3 });
|
|
226
|
+
* snow.stamp({ x: 0, z: 0, area: 0.074, load: 784, duration: 0.1, footprint: snowDiscFootprint(0.12) });
|
|
227
|
+
* snow.recover(1 / 60, 0.0012, 0.4);
|
|
228
|
+
*/
|
|
229
|
+
export class SnowField {
|
|
230
|
+
/** Canonical terrain and the surface snow composes onto. */
|
|
231
|
+
readonly field: Heightfield;
|
|
232
|
+
readonly columns: number;
|
|
233
|
+
readonly rows: number;
|
|
234
|
+
readonly cellWidth: number;
|
|
235
|
+
readonly cellDepth: number;
|
|
236
|
+
/** World x of column 0. */
|
|
237
|
+
readonly minimumX: number;
|
|
238
|
+
/** World z of row 0. */
|
|
239
|
+
readonly minimumZ: number;
|
|
240
|
+
/** 0..1 snow hardness used by contacts that do not override it. */
|
|
241
|
+
hardness: number;
|
|
242
|
+
/** Fraction of its target impression a contact reaches in one response time. */
|
|
243
|
+
readonly yieldFraction: number;
|
|
244
|
+
/** Metres of raised bank allowed beside a contact. */
|
|
245
|
+
readonly maxBank: number;
|
|
246
|
+
/** Seconds a fully-loaded contact takes to reach its full impression. */
|
|
247
|
+
readonly responseTime: number;
|
|
248
|
+
#depth: number;
|
|
249
|
+
readonly #base: Float32Array;
|
|
250
|
+
readonly #indent: Float32Array;
|
|
251
|
+
readonly #bank: Float32Array;
|
|
252
|
+
readonly #compaction: Float32Array;
|
|
253
|
+
readonly #disturbance: Float32Array;
|
|
254
|
+
readonly #active = new Set<number>();
|
|
255
|
+
#steps = 0;
|
|
256
|
+
#lastSink = 0;
|
|
257
|
+
#version = 0;
|
|
258
|
+
#dirty: IHeightfieldRegionBounds | undefined;
|
|
259
|
+
#untaken: IHeightfieldRegionBounds | undefined;
|
|
260
|
+
#scratch = new Float32Array(0);
|
|
261
|
+
|
|
262
|
+
constructor(options: ISnowFieldOptions) {
|
|
263
|
+
const field = options.field;
|
|
264
|
+
if (typeof field?.updateHeights !== "function")
|
|
265
|
+
throw new Error("SnowField requires a Heightfield as its canonical terrain.");
|
|
266
|
+
this.field = field;
|
|
267
|
+
this.columns = field.columns;
|
|
268
|
+
this.rows = field.rows;
|
|
269
|
+
this.cellWidth = field.width / (field.columns - 1);
|
|
270
|
+
this.cellDepth = field.depth / (field.rows - 1);
|
|
271
|
+
this.minimumX = field.origin.x - field.width / 2;
|
|
272
|
+
this.minimumZ = field.origin.z - field.depth / 2;
|
|
273
|
+
this.#depth = nonNegative(options.depth ?? 0.28, "depth");
|
|
274
|
+
this.hardness = clamp(finite(options.hardness ?? 0.3, "hardness"), 0, 1);
|
|
275
|
+
this.yieldFraction = clamp(finite(options.yieldFraction ?? 0.9, "yieldFraction"), 0, 1);
|
|
276
|
+
this.maxBank = nonNegative(options.maxBank ?? 0.085, "maxBank");
|
|
277
|
+
this.responseTime = positive(options.responseTime ?? 0.1, "responseTime");
|
|
278
|
+
this.#base = field.heights;
|
|
279
|
+
const cells = this.columns * this.rows;
|
|
280
|
+
this.#indent = new Float32Array(cells);
|
|
281
|
+
this.#bank = new Float32Array(cells);
|
|
282
|
+
this.#compaction = new Float32Array(cells);
|
|
283
|
+
this.#disturbance = new Float32Array(cells);
|
|
284
|
+
// The untouched surface already stands `depth` above the terrain, before any contact.
|
|
285
|
+
this.#flush({ column: 0, columns: this.columns, row: 0, rows: this.rows });
|
|
286
|
+
}
|
|
287
|
+
|
|
288
|
+
/** Snow depth in metres. Zero is bare ground. */
|
|
289
|
+
get depth(): number {
|
|
290
|
+
return this.#depth;
|
|
291
|
+
}
|
|
292
|
+
|
|
293
|
+
/** Contacts applied since construction or the last reset. */
|
|
294
|
+
get steps(): number {
|
|
295
|
+
return this.#steps;
|
|
296
|
+
}
|
|
297
|
+
|
|
298
|
+
/** Penetration the most recent contact reached, in metres. */
|
|
299
|
+
get lastSink(): number {
|
|
300
|
+
return this.#lastSink;
|
|
301
|
+
}
|
|
302
|
+
|
|
303
|
+
/** Cells still carrying deformation. Recovery drops a cell once it is fully buried. */
|
|
304
|
+
get activeCells(): number {
|
|
305
|
+
return this.#active.size;
|
|
306
|
+
}
|
|
307
|
+
|
|
308
|
+
/** Monotonic version, incremented once per batch that changed the canonical surface. */
|
|
309
|
+
get version(): number {
|
|
310
|
+
return this.#version;
|
|
311
|
+
}
|
|
312
|
+
|
|
313
|
+
/** Window of the canonical field the last change wrote, or undefined before the first change. */
|
|
314
|
+
get dirtyRegion(): IHeightfieldRegionBounds | undefined {
|
|
315
|
+
return this.#dirty === undefined ? undefined : { ...this.#dirty };
|
|
316
|
+
}
|
|
317
|
+
|
|
318
|
+
/**
|
|
319
|
+
* Union of every window written since the previous call, then forgotten.
|
|
320
|
+
*
|
|
321
|
+
* One fixed step can write several windows — each contact, then recovery — and `dirtyRegion`
|
|
322
|
+
* keeps only the last, so a renderer that refreshes geometry once per drawn frame takes this
|
|
323
|
+
* instead. It has one owner: two consumers taking it would each miss the other's windows.
|
|
324
|
+
*/
|
|
325
|
+
takeDirtyRegion(): IHeightfieldRegionBounds | undefined {
|
|
326
|
+
const region = this.#untaken;
|
|
327
|
+
this.#untaken = undefined;
|
|
328
|
+
return region;
|
|
329
|
+
}
|
|
330
|
+
|
|
331
|
+
/** Bytes retained by the four snow channels and the base terrain copy. */
|
|
332
|
+
get memoryBytes(): number {
|
|
333
|
+
return (4 * this.#indent.length + this.#base.length) * Float32Array.BYTES_PER_ELEMENT;
|
|
334
|
+
}
|
|
335
|
+
|
|
336
|
+
/**
|
|
337
|
+
* The four snow channels at a world position, bilinearly interpolated.
|
|
338
|
+
*
|
|
339
|
+
* Returns zeros outside the field rather than throwing, so a caller sweeping a broad area does
|
|
340
|
+
* not have to bounds-check first. `heightAt` keeps the strict contract.
|
|
341
|
+
*/
|
|
342
|
+
sample(x: number, z: number): ISnowFieldSample {
|
|
343
|
+
finite(x, "query x");
|
|
344
|
+
finite(z, "query z");
|
|
345
|
+
const column = (x - this.minimumX) / this.cellWidth;
|
|
346
|
+
const row = (z - this.minimumZ) / this.cellDepth;
|
|
347
|
+
if (column < 0 || row < 0 || column > this.columns - 1 || row > this.rows - 1)
|
|
348
|
+
return { bank: 0, compaction: 0, disturbance: 0, indent: 0 };
|
|
349
|
+
const column0 = Math.floor(column);
|
|
350
|
+
const row0 = Math.floor(row);
|
|
351
|
+
const column1 = Math.min(this.columns - 1, column0 + 1);
|
|
352
|
+
const row1 = Math.min(this.rows - 1, row0 + 1);
|
|
353
|
+
const columnMix = column - column0;
|
|
354
|
+
const rowMix = row - row0;
|
|
355
|
+
const channel = (values: Float32Array): number =>
|
|
356
|
+
lerp(
|
|
357
|
+
lerp(
|
|
358
|
+
values[row0 * this.columns + column0] as number,
|
|
359
|
+
values[row0 * this.columns + column1] as number,
|
|
360
|
+
columnMix,
|
|
361
|
+
),
|
|
362
|
+
lerp(
|
|
363
|
+
values[row1 * this.columns + column0] as number,
|
|
364
|
+
values[row1 * this.columns + column1] as number,
|
|
365
|
+
columnMix,
|
|
366
|
+
),
|
|
367
|
+
rowMix,
|
|
368
|
+
);
|
|
369
|
+
return {
|
|
370
|
+
bank: channel(this.#bank),
|
|
371
|
+
compaction: channel(this.#compaction),
|
|
372
|
+
disturbance: channel(this.#disturbance),
|
|
373
|
+
indent: channel(this.#indent),
|
|
374
|
+
};
|
|
375
|
+
}
|
|
376
|
+
|
|
377
|
+
/**
|
|
378
|
+
* One channel over a window of cells, row-major, written into `target` (allocated when absent
|
|
379
|
+
* or too small) and returned. The bulk read a renderer uses to encode a refreshed window: a
|
|
380
|
+
* `sample` per vertex costs a bilinear lookup and an object each, and a refill window is
|
|
381
|
+
* thousands of vertices. A window outside the field throws.
|
|
382
|
+
*/
|
|
383
|
+
copyChannel(
|
|
384
|
+
channel: keyof ISnowFieldSample,
|
|
385
|
+
bounds: IHeightfieldRegionBounds,
|
|
386
|
+
target?: Float32Array,
|
|
387
|
+
): Float32Array {
|
|
388
|
+
const values =
|
|
389
|
+
channel === "indent"
|
|
390
|
+
? this.#indent
|
|
391
|
+
: channel === "bank"
|
|
392
|
+
? this.#bank
|
|
393
|
+
: channel === "compaction"
|
|
394
|
+
? this.#compaction
|
|
395
|
+
: channel === "disturbance"
|
|
396
|
+
? this.#disturbance
|
|
397
|
+
: undefined;
|
|
398
|
+
if (values === undefined) throw new Error(`SnowField has no channel '${String(channel)}'.`);
|
|
399
|
+
const { column, columns, row, rows } = bounds;
|
|
400
|
+
if (
|
|
401
|
+
!Number.isInteger(column) ||
|
|
402
|
+
!Number.isInteger(row) ||
|
|
403
|
+
!Number.isInteger(columns) ||
|
|
404
|
+
!Number.isInteger(rows) ||
|
|
405
|
+
column < 0 ||
|
|
406
|
+
row < 0 ||
|
|
407
|
+
columns < 1 ||
|
|
408
|
+
rows < 1 ||
|
|
409
|
+
column + columns > this.columns ||
|
|
410
|
+
row + rows > this.rows
|
|
411
|
+
)
|
|
412
|
+
throw new Error("SnowField.copyChannel window must lie inside the field.");
|
|
413
|
+
const output =
|
|
414
|
+
target !== undefined && target.length >= columns * rows
|
|
415
|
+
? target
|
|
416
|
+
: new Float32Array(columns * rows);
|
|
417
|
+
for (let index = 0; index < rows; index += 1) {
|
|
418
|
+
const start = (row + index) * this.columns + column;
|
|
419
|
+
output.set(values.subarray(start, start + columns), index * columns);
|
|
420
|
+
}
|
|
421
|
+
return output;
|
|
422
|
+
}
|
|
423
|
+
|
|
424
|
+
/** Snow surface height at a world position, from the same samples geometry and collision read. */
|
|
425
|
+
heightAt(x: number, z: number): number {
|
|
426
|
+
return this.field.heightAt(x, z);
|
|
427
|
+
}
|
|
428
|
+
|
|
429
|
+
/** Surface normal at a world position. */
|
|
430
|
+
normalAt(x: number, z: number, target?: Vector3): Vector3 {
|
|
431
|
+
return target === undefined ? this.field.normalAt(x, z) : this.field.normalAt(x, z, target);
|
|
432
|
+
}
|
|
433
|
+
|
|
434
|
+
/**
|
|
435
|
+
* How far towards its target impression a contact has travelled after `seconds`.
|
|
436
|
+
*
|
|
437
|
+
* The remaining distance shrinks geometrically, so the same total contact time reaches the same
|
|
438
|
+
* depth however it is split across ticks. That is what keeps deformation independent of
|
|
439
|
+
* presentation rate without touching the fixed physics timestep.
|
|
440
|
+
*/
|
|
441
|
+
#fraction(seconds: number): number {
|
|
442
|
+
if (seconds <= 0) return 0;
|
|
443
|
+
if (this.yieldFraction >= 1) return 1;
|
|
444
|
+
return 1 - (1 - this.yieldFraction) ** (seconds / this.responseTime);
|
|
445
|
+
}
|
|
446
|
+
|
|
447
|
+
/**
|
|
448
|
+
* Press one contact into the snow and return the penetration it reached, in metres.
|
|
449
|
+
*
|
|
450
|
+
* Pressure is `load / area`, so the same profile responds to how much weight it carries and how
|
|
451
|
+
* widely that weight is spread. `duration` scales how far the contact gets towards its target
|
|
452
|
+
* impression, which is what makes a run of shorter contacts agree with one long one. A contact
|
|
453
|
+
* entirely outside the field returns 0 and leaves the version unchanged.
|
|
454
|
+
*/
|
|
455
|
+
stamp(contact: ISnowContact): number {
|
|
456
|
+
const resolved = this.#requireContact(contact);
|
|
457
|
+
if (this.#depth <= 0) return 0;
|
|
458
|
+
const penetration = this.#penetration(resolved.hardness, contact.load, contact.area);
|
|
459
|
+
if (penetration <= 0) return 0;
|
|
460
|
+
const fraction = this.#fraction(contact.duration ?? this.responseTime);
|
|
461
|
+
if (fraction <= 0) return 0;
|
|
462
|
+
if (!this.#overlaps(resolved)) return 0;
|
|
463
|
+
const window = this.#contactWindow(resolved.x, resolved.z, resolved.extent);
|
|
464
|
+
if (!this.#pressWindow(window, resolved, penetration, fraction)) return 0;
|
|
465
|
+
this.#steps += 1;
|
|
466
|
+
this.#lastSink = penetration;
|
|
467
|
+
this.#flush({
|
|
468
|
+
column: window.firstColumn,
|
|
469
|
+
columns: window.lastColumn - window.firstColumn + 1,
|
|
470
|
+
row: window.firstRow,
|
|
471
|
+
rows: window.lastRow - window.firstRow + 1,
|
|
472
|
+
});
|
|
473
|
+
return penetration;
|
|
474
|
+
}
|
|
475
|
+
|
|
476
|
+
/** Depth a contact reaches: pressure against snow resistance, bounded by the snow depth. */
|
|
477
|
+
#penetration(hardness: number, load: number, area: number): number {
|
|
478
|
+
const resistance = PRESSURE_RESISTANCE_BASE + hardness ** 1.5 * PRESSURE_RESISTANCE_HARDNESS;
|
|
479
|
+
return clamp(
|
|
480
|
+
this.#depth * (PRESSURE_DEPTH_FLOOR + load / area / resistance),
|
|
481
|
+
0,
|
|
482
|
+
this.#depth * MAX_PENETRATION_FRACTION,
|
|
483
|
+
);
|
|
484
|
+
}
|
|
485
|
+
|
|
486
|
+
/** Whether a contact's bounding square reaches any part of the field. */
|
|
487
|
+
#overlaps(contact: { readonly extent: number; readonly x: number; readonly z: number }): boolean {
|
|
488
|
+
if (
|
|
489
|
+
contact.x + contact.extent < this.minimumX ||
|
|
490
|
+
contact.x - contact.extent > this.minimumX + this.field.width
|
|
491
|
+
)
|
|
492
|
+
return false;
|
|
493
|
+
return !(
|
|
494
|
+
contact.z + contact.extent < this.minimumZ ||
|
|
495
|
+
contact.z - contact.extent > this.minimumZ + this.field.depth
|
|
496
|
+
);
|
|
497
|
+
}
|
|
498
|
+
|
|
499
|
+
/** Sample the footprint across its window, returning whether any cell changed. */
|
|
500
|
+
#pressWindow(
|
|
501
|
+
window: {
|
|
502
|
+
readonly firstColumn: number;
|
|
503
|
+
readonly firstRow: number;
|
|
504
|
+
readonly lastColumn: number;
|
|
505
|
+
readonly lastRow: number;
|
|
506
|
+
},
|
|
507
|
+
contact: {
|
|
508
|
+
readonly cosine: number;
|
|
509
|
+
readonly footprint: ISnowFootprint;
|
|
510
|
+
readonly hardness: number;
|
|
511
|
+
readonly sine: number;
|
|
512
|
+
readonly x: number;
|
|
513
|
+
readonly z: number;
|
|
514
|
+
},
|
|
515
|
+
penetration: number,
|
|
516
|
+
fraction: number,
|
|
517
|
+
): boolean {
|
|
518
|
+
let touched = false;
|
|
519
|
+
for (let row = window.firstRow; row <= window.lastRow; row += 1) {
|
|
520
|
+
const localZ = this.minimumZ + row * this.cellDepth - contact.z;
|
|
521
|
+
for (let column = window.firstColumn; column <= window.lastColumn; column += 1) {
|
|
522
|
+
const localX = this.minimumX + column * this.cellWidth - contact.x;
|
|
523
|
+
const sample = unit(
|
|
524
|
+
contact.footprint.sample(
|
|
525
|
+
localX * contact.cosine - localZ * contact.sine,
|
|
526
|
+
localX * contact.sine + localZ * contact.cosine,
|
|
527
|
+
),
|
|
528
|
+
"footprint sample",
|
|
529
|
+
);
|
|
530
|
+
if (sample.coverage <= 0 && sample.bank <= 0) continue;
|
|
531
|
+
this.#applySample(
|
|
532
|
+
row * this.columns + column,
|
|
533
|
+
sample,
|
|
534
|
+
penetration,
|
|
535
|
+
fraction,
|
|
536
|
+
contact.hardness,
|
|
537
|
+
);
|
|
538
|
+
touched = true;
|
|
539
|
+
}
|
|
540
|
+
}
|
|
541
|
+
return touched;
|
|
542
|
+
}
|
|
543
|
+
|
|
544
|
+
/** Reject a malformed contact before any part of the surface changes. */
|
|
545
|
+
#requireContact(contact: ISnowContact): {
|
|
546
|
+
readonly cosine: number;
|
|
547
|
+
readonly extent: number;
|
|
548
|
+
readonly footprint: ISnowFootprint;
|
|
549
|
+
readonly hardness: number;
|
|
550
|
+
readonly sine: number;
|
|
551
|
+
readonly x: number;
|
|
552
|
+
readonly z: number;
|
|
553
|
+
} {
|
|
554
|
+
const x = finite(contact.x, "contact x");
|
|
555
|
+
const z = finite(contact.z, "contact z");
|
|
556
|
+
positive(contact.area, "contact area");
|
|
557
|
+
nonNegative(contact.load, "contact load");
|
|
558
|
+
const rotation = finite(contact.rotation ?? 0, "contact rotation");
|
|
559
|
+
nonNegative(contact.duration ?? this.responseTime, "contact duration");
|
|
560
|
+
const footprint = contact.footprint;
|
|
561
|
+
if (typeof footprint?.sample !== "function")
|
|
562
|
+
throw new Error("SnowField contact requires a footprint with a sample function.");
|
|
563
|
+
return {
|
|
564
|
+
cosine: Math.cos(rotation),
|
|
565
|
+
extent: positive(footprint.extent, "footprint extent"),
|
|
566
|
+
footprint,
|
|
567
|
+
hardness: clamp(finite(contact.hardness ?? this.hardness, "contact hardness"), 0, 1),
|
|
568
|
+
sine: Math.sin(rotation),
|
|
569
|
+
x,
|
|
570
|
+
z,
|
|
571
|
+
};
|
|
572
|
+
}
|
|
573
|
+
|
|
574
|
+
/**
|
|
575
|
+
* The grid window a contact covers, rejected when its footprint spans more cells than allowed.
|
|
576
|
+
*
|
|
577
|
+
* The span is measured before clipping to the grid: a footprint larger than the field is
|
|
578
|
+
* malformed rather than merely wasteful, and must fail instead of allocating a window for it.
|
|
579
|
+
*/
|
|
580
|
+
#contactWindow(
|
|
581
|
+
x: number,
|
|
582
|
+
z: number,
|
|
583
|
+
extent: number,
|
|
584
|
+
): {
|
|
585
|
+
readonly firstColumn: number;
|
|
586
|
+
readonly firstRow: number;
|
|
587
|
+
readonly lastColumn: number;
|
|
588
|
+
readonly lastRow: number;
|
|
589
|
+
} {
|
|
590
|
+
const lowColumn = Math.floor((x - extent - this.minimumX) / this.cellWidth);
|
|
591
|
+
const highColumn = Math.ceil((x + extent - this.minimumX) / this.cellWidth);
|
|
592
|
+
const lowRow = Math.floor((z - extent - this.minimumZ) / this.cellDepth);
|
|
593
|
+
const highRow = Math.ceil((z + extent - this.minimumZ) / this.cellDepth);
|
|
594
|
+
const spanned = (highColumn - lowColumn + 1) * (highRow - lowRow + 1);
|
|
595
|
+
if (spanned > MAX_CONTACT_CELLS)
|
|
596
|
+
throw new Error(
|
|
597
|
+
`SnowField contact footprint spans ${String(spanned)} cells, above the ${String(MAX_CONTACT_CELLS)}-cell limit.`,
|
|
598
|
+
);
|
|
599
|
+
return {
|
|
600
|
+
firstColumn: clamp(lowColumn, 0, this.columns - 1),
|
|
601
|
+
firstRow: clamp(lowRow, 0, this.rows - 1),
|
|
602
|
+
lastColumn: clamp(highColumn, 0, this.columns - 1),
|
|
603
|
+
lastRow: clamp(highRow, 0, this.rows - 1),
|
|
604
|
+
};
|
|
605
|
+
}
|
|
606
|
+
|
|
607
|
+
/**
|
|
608
|
+
* Apply one footprint sample to one cell.
|
|
609
|
+
*
|
|
610
|
+
* Contact first erases displaced bank and records compaction and disturbance; the rim then
|
|
611
|
+
* raises bank beside the contact. That order is the source study's and is what keeps its
|
|
612
|
+
* regression fixture reproducible.
|
|
613
|
+
*/
|
|
614
|
+
#applySample(
|
|
615
|
+
index: number,
|
|
616
|
+
sample: ISnowFootprintSample,
|
|
617
|
+
penetration: number,
|
|
618
|
+
fraction: number,
|
|
619
|
+
hardness: number,
|
|
620
|
+
): void {
|
|
621
|
+
if (sample.coverage > 0) {
|
|
622
|
+
const target = Math.max(0, penetration * sample.shape - sample.relief) * sample.coverage;
|
|
623
|
+
const oldIndent = this.#indent[index] as number;
|
|
624
|
+
this.#indent[index] = Math.min(
|
|
625
|
+
this.#depth * MAX_INDENT_FRACTION,
|
|
626
|
+
Math.max(oldIndent, lerp(oldIndent, target, fraction)),
|
|
627
|
+
);
|
|
628
|
+
this.#bank[index] = (this.#bank[index] as number) * (1 - sample.coverage);
|
|
629
|
+
this.#compaction[index] = Math.min(
|
|
630
|
+
1,
|
|
631
|
+
Math.max(this.#compaction[index] as number, sample.coverage * (0.72 + 0.23 * hardness)),
|
|
632
|
+
);
|
|
633
|
+
this.#disturbance[index] = Math.max(this.#disturbance[index] as number, sample.coverage);
|
|
634
|
+
}
|
|
635
|
+
if (sample.bank > 0) {
|
|
636
|
+
this.#bank[index] = Math.min(
|
|
637
|
+
this.maxBank,
|
|
638
|
+
Math.max(this.#bank[index] as number, penetration * BANK_LOAD_SCALE * sample.bank),
|
|
639
|
+
);
|
|
640
|
+
this.#disturbance[index] = Math.max(this.#disturbance[index] as number, sample.disturbance);
|
|
641
|
+
}
|
|
642
|
+
this.#active.add(index);
|
|
643
|
+
}
|
|
644
|
+
|
|
645
|
+
/**
|
|
646
|
+
* Let snowfall fill depressions and wind soften banks over `seconds`.
|
|
647
|
+
*
|
|
648
|
+
* Deposition and wind are rates, so this is presentation-rate independent: a second of
|
|
649
|
+
* simulation recovers the same amount however many ticks it was split into. It accelerates
|
|
650
|
+
* deposition only — never gravity, movement, falling flakes or the physics timestep.
|
|
651
|
+
*/
|
|
652
|
+
recover(seconds: number, deposition: number, wind: number): void {
|
|
653
|
+
const dt = nonNegative(seconds, "recovery seconds");
|
|
654
|
+
if (dt === 0) return;
|
|
655
|
+
const depositionRate = nonNegative(deposition, "recovery deposition");
|
|
656
|
+
const windRate = nonNegative(wind, "recovery wind");
|
|
657
|
+
if ((depositionRate === 0 && windRate === 0) || this.#active.size === 0) return;
|
|
658
|
+
const raise = depositionRate * dt;
|
|
659
|
+
const erosion = Math.exp(-windRate * dt * WIND_EROSION);
|
|
660
|
+
const burial = Math.exp(-raise * DEPOSITION_BURIAL);
|
|
661
|
+
let dirty: IHeightfieldRegionBounds | undefined;
|
|
662
|
+
for (const index of this.#active) {
|
|
663
|
+
this.#recoverCell(index, raise, erosion, burial);
|
|
664
|
+
dirty = unionBounds(dirty, cellBounds(index, this.columns));
|
|
665
|
+
}
|
|
666
|
+
if (dirty === undefined) return;
|
|
667
|
+
this.#flush(dirty);
|
|
668
|
+
}
|
|
669
|
+
|
|
670
|
+
/**
|
|
671
|
+
* Apply one tick of deposition and wind to one cell, releasing it once it is fully buried.
|
|
672
|
+
*/
|
|
673
|
+
#recoverCell(index: number, raise: number, erosion: number, burial: number): void {
|
|
674
|
+
const indent = Math.max(0, (this.#indent[index] as number) - raise);
|
|
675
|
+
const bank = (this.#bank[index] as number) * erosion;
|
|
676
|
+
const compaction = (this.#compaction[index] as number) * burial;
|
|
677
|
+
const disturbance = (this.#disturbance[index] as number) * burial * erosion;
|
|
678
|
+
this.#indent[index] = indent;
|
|
679
|
+
this.#bank[index] = bank;
|
|
680
|
+
this.#compaction[index] = compaction;
|
|
681
|
+
this.#disturbance[index] = disturbance;
|
|
682
|
+
if (
|
|
683
|
+
indent >= RECOVERED_INDENT ||
|
|
684
|
+
bank >= RECOVERED_INDENT ||
|
|
685
|
+
compaction >= RECOVERED_COMPACTION
|
|
686
|
+
)
|
|
687
|
+
return;
|
|
688
|
+
this.#indent[index] = 0;
|
|
689
|
+
this.#bank[index] = 0;
|
|
690
|
+
this.#compaction[index] = 0;
|
|
691
|
+
this.#disturbance[index] = 0;
|
|
692
|
+
this.#active.delete(index);
|
|
693
|
+
}
|
|
694
|
+
|
|
695
|
+
/**
|
|
696
|
+
* Change the snow depth in metres and push the new surface through the canonical field.
|
|
697
|
+
*
|
|
698
|
+
* Existing indentation is capped to the new depth rather than scaled, so deepening snow does
|
|
699
|
+
* not erase tracks and shallowing it buries them.
|
|
700
|
+
*/
|
|
701
|
+
setDepth(depth: number): void {
|
|
702
|
+
const next = nonNegative(depth, "depth");
|
|
703
|
+
if (next === this.#depth) return;
|
|
704
|
+
this.#depth = next;
|
|
705
|
+
const limit = next * MAX_INDENT_FRACTION;
|
|
706
|
+
for (const index of this.#active)
|
|
707
|
+
this.#indent[index] = Math.min(this.#indent[index] as number, limit);
|
|
708
|
+
this.#flush({ column: 0, columns: this.columns, row: 0, rows: this.rows });
|
|
709
|
+
}
|
|
710
|
+
|
|
711
|
+
/** Clear every track, bank and compaction record and return the surface to bare snow. */
|
|
712
|
+
reset(): void {
|
|
713
|
+
this.#indent.fill(0);
|
|
714
|
+
this.#bank.fill(0);
|
|
715
|
+
this.#compaction.fill(0);
|
|
716
|
+
this.#disturbance.fill(0);
|
|
717
|
+
this.#active.clear();
|
|
718
|
+
this.#steps = 0;
|
|
719
|
+
this.#lastSink = 0;
|
|
720
|
+
this.#flush({ column: 0, columns: this.columns, row: 0, rows: this.rows });
|
|
721
|
+
}
|
|
722
|
+
|
|
723
|
+
/** Combine one window of channels with the base terrain and hand it to the canonical field. */
|
|
724
|
+
#flush(bounds: IHeightfieldRegionBounds): void {
|
|
725
|
+
const samples = bounds.columns * bounds.rows;
|
|
726
|
+
if (this.#scratch.length < samples) this.#scratch = new Float32Array(samples);
|
|
727
|
+
const heights = this.#scratch.subarray(0, samples);
|
|
728
|
+
for (let row = 0; row < bounds.rows; row += 1) {
|
|
729
|
+
for (let column = 0; column < bounds.columns; column += 1) {
|
|
730
|
+
const source = (bounds.row + row) * this.columns + (bounds.column + column);
|
|
731
|
+
heights[row * bounds.columns + column] =
|
|
732
|
+
(this.#base[source] as number) +
|
|
733
|
+
this.#depth +
|
|
734
|
+
(this.#bank[source] as number) -
|
|
735
|
+
(this.#indent[source] as number);
|
|
736
|
+
}
|
|
737
|
+
}
|
|
738
|
+
// The scratch buffer is written straight through: updateHeights copies before it returns.
|
|
739
|
+
this.field.updateHeights({ ...bounds, heights });
|
|
740
|
+
this.#dirty = { ...bounds };
|
|
741
|
+
this.#untaken = unionBounds(this.#untaken, bounds);
|
|
742
|
+
this.#version += 1;
|
|
743
|
+
}
|
|
744
|
+
}
|