@threenative/core 0.3.11 → 0.3.12
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 +1096 -26
- package/dist/camera-shake-CZKOfGn4.d.ts +46 -0
- package/dist/{canvas-layer-vCtanIeB.d.ts → canvas-layer-CWuFRT7G.d.ts} +1 -1
- package/dist/chunk-2Z44XSI2.js +35 -0
- package/dist/chunk-5O73CDMR.js +1849 -0
- package/dist/chunk-6KLNISRJ.js +153 -0
- package/dist/chunk-7UUT3TY5.js +133 -0
- package/dist/chunk-CFGTPFUH.js +231 -0
- package/dist/chunk-DBELTTTM.js +615 -0
- package/dist/chunk-GMHATRPW.js +7701 -0
- package/dist/chunk-GXY7B3JG.js +46 -0
- package/dist/chunk-KIRUKTBQ.js +187 -0
- package/dist/chunk-N5LRP4BR.js +220 -0
- package/dist/chunk-OKXUCASC.js +2238 -0
- package/dist/chunk-QWJEMUUT.js +94 -0
- package/dist/chunk-VAZM36TV.js +497 -0
- package/dist/{game-DzMcitDO.d.ts → game-D7pAzZUY.d.ts} +15 -3
- package/dist/hot.d.ts +3 -3
- package/dist/hot.js +2 -46
- package/dist/index.d.ts +329 -302
- package/dist/index.js +10566 -22552
- package/dist/{model-lod-CTpZ6imz.d.ts → model-lod-B6BMqS1r.d.ts} +33 -3
- package/dist/playtest.d.ts +3 -3
- package/dist/playtest.js +24 -75
- package/dist/react-css.js +1 -215
- package/dist/react.d.ts +2 -2
- package/dist/{renderer-rZm0hVqq.d.ts → renderer-DvFVoAgj.d.ts} +13 -4
- package/dist/spells/index.d.ts +643 -0
- package/dist/spells/index.js +1558 -0
- package/dist/spells/ultra/index.d.ts +1600 -0
- package/dist/spells/ultra/index.js +6804 -0
- package/dist/terrain-jobs-worker.js +1 -123
- package/dist/two-sided-foliage-W523J3UM.js +1 -0
- package/dist/ui-layer.js +5 -384
- package/dist/worker.js +4 -41
- package/dist/world.d.ts +725 -259
- package/dist/world.js +16714 -18284
- package/mcp/animation-server.mjs +1 -1
- package/mcp/animation.mjs +2 -3
- package/mcp/engine-server.mjs +142 -47
- package/mcp/servers.mjs +9 -2
- package/mcp/terrain.mjs +8 -0
- package/package.json +14 -6
- package/patches/three@0.187.0-prd269-upgrade.patch +2102 -0
- package/patches/three@0.187.0.patch +2004 -407
- package/src/assets.ts +9 -2
- package/src/card-lod.ts +152 -0
- package/src/compressed-texture-preparation.ts +1008 -0
- package/src/frame-budget.ts +31 -20
- package/src/game-dev-tools.ts +93 -0
- package/src/game-frame-loop.ts +995 -0
- package/src/game-renderer-metrics.ts +77 -0
- package/src/game-startup.ts +1001 -0
- package/src/game-validate.ts +70 -0
- package/src/game.ts +253 -1935
- package/src/index.ts +27 -2
- package/src/launch-diagnostics.ts +22 -12
- package/src/look/ao-admission.ts +24 -0
- package/src/look/filmic-tone-mapping.ts +15 -13
- package/src/look/look-diagnostics.ts +3 -3
- package/src/look/quality.ts +10 -5
- package/src/look/world-environment.ts +76 -9
- package/src/loop.ts +29 -0
- package/src/model-lod.ts +42 -3
- package/src/particle-kinds.ts +515 -0
- package/src/picking.ts +17 -3
- package/src/playtest.ts +27 -1
- package/src/projection-apply.ts +4 -1
- package/src/projection-plan.ts +9 -6
- package/src/render/mesh-pool.ts +1 -1
- package/src/render/resolution-subrect.ts +2 -0
- package/src/render/rough-diffuse.ts +46 -12
- package/src/render/soft-shadow.ts +27 -12
- package/src/render/virtual-shadow-adaptive.ts +55 -0
- package/src/render/virtual-shadow-casters.ts +175 -0
- package/src/render/virtual-shadow-layers.ts +76 -0
- package/src/render/virtual-shadow-level.ts +224 -0
- package/src/render/virtual-shadow-markers.ts +193 -0
- package/src/render/virtual-shadow-options.ts +370 -0
- package/src/render/virtual-shadow-pages.ts +5 -0
- package/src/render/virtual-shadow.ts +213 -992
- package/src/render/world-impostor-surface.ts +293 -34
- package/src/render-pass-budget.ts +34 -7
- package/src/renderProjection.ts +22 -0
- package/src/renderer.ts +92 -37
- package/src/snow-field.ts +1 -1
- package/src/spells/cast-pool.ts +361 -0
- package/src/spells/index.ts +177 -0
- package/src/spells/mechanisms.ts +295 -0
- package/src/spells/reaction-field.ts +415 -0
- package/src/spells/spell-lights.ts +139 -0
- package/src/spells/spell-world.ts +187 -0
- package/src/spells/spell.ts +397 -0
- package/src/spells/spells.ts +283 -0
- package/src/spells/ultra/engine/camera.ts +184 -0
- package/src/spells/ultra/engine/quality.ts +96 -0
- package/src/spells/ultra/index.ts +52 -0
- package/src/spells/ultra/main.ts +305 -0
- package/src/spells/ultra/scene/arenaMaterial.ts +325 -0
- package/src/spells/ultra/spells/cast.ts +233 -0
- package/src/spells/ultra/spells/fire.ts +1267 -0
- package/src/spells/ultra/vfx/FluidVolume.ts +816 -0
- package/src/spells/ultra/vfx/FluidVolume.tsl.ts +855 -0
- package/src/spells/ultra/vfx/FxTarget.ts +61 -0
- package/src/spells/ultra/vfx/GroundField.ts +1399 -0
- package/src/spells/ultra/vfx/Particles.ts +1475 -0
- package/src/spells/ultra/vfx/Ribbons.ts +645 -0
- package/src/spells/ultra/vfx/Shockwaves.ts +286 -0
- package/src/spells/ultra/vfx/Volumes.ts +489 -0
- package/src/spells/ultra/vfx/common.ts +1195 -0
- package/src/spells/ultra/vfx/noise.ts +441 -0
- package/src/startup-readiness.ts +128 -34
- package/src/version.ts +1 -1
- package/src/warmup.ts +56 -8
- package/src/water-surface.ts +9 -3
- package/src/world-bundle-safety.ts +401 -0
- package/src/world-cell-batches.ts +1216 -0
- package/src/world-cell-chunks.ts +1132 -0
- package/src/world-cell-data.ts +995 -0
- package/src/world-cell-impostors.ts +1449 -0
- package/src/world-cell-lod-bias.ts +151 -0
- package/src/world-cell-models.ts +1074 -0
- package/src/world-cell-options.ts +189 -0
- package/src/world-cell-placements.ts +694 -0
- package/src/world-cell-prewarm.ts +557 -0
- package/src/world-cell-readiness.ts +357 -0
- package/src/world-cell-render-bundles.ts +459 -0
- package/src/world-cell-render-gpu-dress.ts +714 -0
- package/src/world-cell-render-main-cull.ts +484 -0
- package/src/world-cell-render-shadow-claims.ts +198 -0
- package/src/world-cell-render-util.ts +246 -0
- package/src/world-cell-render.ts +1493 -0
- package/src/world-cell-residency.ts +745 -0
- package/src/world-cells.ts +1318 -10418
- package/src/world-chunk-shadow.ts +308 -0
- package/src/world-collar.ts +315 -0
- package/src/world-gpu-flags.ts +163 -0
- package/src/world-gpu-readback.ts +881 -0
- package/src/world-gpu-reference.ts +510 -0
- package/src/world-gpu-scene.ts +214 -2264
- package/src/world-gpu-shadow.ts +190 -0
- package/src/world-gpu-types.ts +381 -0
- package/src/world-gpu-validation.ts +518 -0
- package/src/world-heightfield.ts +802 -0
- package/src/world-load-limiter.ts +106 -0
- package/src/world-noise.ts +241 -0
- package/src/world-package.ts +42 -0
- package/src/world-region.ts +1 -1
- package/src/world-terrain-splat.ts +365 -149
- package/src/world-tile-budget.ts +256 -0
- package/src/world-tile-geometry.ts +469 -0
- package/src/world-tile-lod.ts +408 -0
- package/src/world-tile-observation.ts +566 -0
- package/src/world-tile-stitch.ts +166 -0
- package/src/world-tiles.ts +170 -1745
- package/src/world-water-bodies.ts +359 -0
- package/src/world.ts +35 -741
|
@@ -0,0 +1,415 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Where the world keeps what a spell did to it.
|
|
3
|
+
*
|
|
4
|
+
* A fireball that only draws a fireball has not landed anywhere. Upstream keeps this in
|
|
5
|
+
* `GroundField.js`: every spell paints a patch of floor with heat, char, water, frost, a crack or a
|
|
6
|
+
* residual glow, and the floor's own shader reads those channels back. The arena SDF is what makes
|
|
7
|
+
* that file impossible to reuse, so this is the same idea with the arena removed — the game says
|
|
8
|
+
* where the floor is, and the game's material decides what heat looks like.
|
|
9
|
+
*
|
|
10
|
+
* Same contract as `RippleField`: it draws nothing, owns no mesh and no colour. It reports values,
|
|
11
|
+
* the game reads them, and a game that never looks at a channel pays a float array for it and
|
|
12
|
+
* nothing else.
|
|
13
|
+
*
|
|
14
|
+
* The solve is a CPU grid because a game reads it for combos: "cast ice on wet floor" has to be a
|
|
15
|
+
* branch, not a GPU readback that arrives two frames late.
|
|
16
|
+
*/
|
|
17
|
+
|
|
18
|
+
/** The channels a spell writes. Each is independent and decays on its own clock. */
|
|
19
|
+
export const REACTION_CHANNELS = [
|
|
20
|
+
/** Fire, lightning and lava: what a floor reads as "still burning". */
|
|
21
|
+
"heat",
|
|
22
|
+
/** Burnt floor. Decays far slower than heat and is what a scorch looks like. */
|
|
23
|
+
"char",
|
|
24
|
+
/** Water and ice melt: a puddle a lightning spell spreads across. */
|
|
25
|
+
"wet",
|
|
26
|
+
/** Ice. Reads cold, and a fire spell wants to melt it back. */
|
|
27
|
+
"frost",
|
|
28
|
+
/** A fissure or a shattered floor: a crack pattern whose strength fades. */
|
|
29
|
+
"crack",
|
|
30
|
+
/** Residual magic light, for a floor that glows after impact. */
|
|
31
|
+
"glow",
|
|
32
|
+
] as const;
|
|
33
|
+
|
|
34
|
+
export type ReactionChannel = (typeof REACTION_CHANNELS)[number];
|
|
35
|
+
|
|
36
|
+
/** Where a splat landed and how much of it the spell laid down. Every channel is 0..1. */
|
|
37
|
+
export interface IReactionSplat {
|
|
38
|
+
readonly x: number;
|
|
39
|
+
readonly z: number;
|
|
40
|
+
/** Metres. The Gaussian reaches about three of these. */
|
|
41
|
+
readonly radius: number;
|
|
42
|
+
/** `radial` fades from the centre; `ring` leaves a rim; `streak` is stretched along `angle`. */
|
|
43
|
+
readonly pattern?: ReactionPattern;
|
|
44
|
+
/** Radians. Turns the `streak` axis, and is ignored by every other pattern. */
|
|
45
|
+
readonly angle?: number;
|
|
46
|
+
/** Pattern seed, so two impacts of the same spell are not the same mark. */
|
|
47
|
+
readonly seed?: number;
|
|
48
|
+
readonly heat?: number;
|
|
49
|
+
readonly char?: number;
|
|
50
|
+
readonly wet?: number;
|
|
51
|
+
readonly frost?: number;
|
|
52
|
+
readonly crack?: number;
|
|
53
|
+
readonly glow?: number;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
export type ReactionPattern = "radial" | "ring" | "streak";
|
|
57
|
+
|
|
58
|
+
/** A whole-cell rectangle of changed cells, in grid indices. */
|
|
59
|
+
export interface IReactionDirty {
|
|
60
|
+
readonly x: number;
|
|
61
|
+
readonly z: number;
|
|
62
|
+
readonly width: number;
|
|
63
|
+
readonly height: number;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
export interface IReactionFieldOptions {
|
|
67
|
+
/** Cells per side. Cost is quadratic in this; 96 over a 120 m patch is ~1.25 m per cell. */
|
|
68
|
+
readonly resolution?: number;
|
|
69
|
+
/** Width of the patch in metres. */
|
|
70
|
+
readonly size?: number;
|
|
71
|
+
/** Per-channel seconds for a full-strength value to halve. `char` is the slow one. */
|
|
72
|
+
readonly halfLife?: Partial<Readonly<Record<ReactionChannel, number>>>;
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
const DEFAULT_HALF_LIFE: Readonly<Record<ReactionChannel, number>> = {
|
|
76
|
+
// ponytail: one half-life per channel and no wave transport. Upgrade to a GPU solve with
|
|
77
|
+
// advection if a game needs fire to spread uphill or water to run across a floor.
|
|
78
|
+
heat: 3.5,
|
|
79
|
+
char: 24,
|
|
80
|
+
crack: 40,
|
|
81
|
+
frost: 8,
|
|
82
|
+
glow: 1.6,
|
|
83
|
+
wet: 12,
|
|
84
|
+
};
|
|
85
|
+
|
|
86
|
+
const clamp01 = (value: number): number => (value < 0 ? 0 : value > 1 ? 1 : value);
|
|
87
|
+
|
|
88
|
+
const finite = (value: number, label: string): number => {
|
|
89
|
+
if (!Number.isFinite(value)) throw new TypeError(`${label} must be finite`);
|
|
90
|
+
return value;
|
|
91
|
+
};
|
|
92
|
+
|
|
93
|
+
/** A small integer hash, so a seed alone reproduces the mark without touching `Math.random`. */
|
|
94
|
+
const hash2 = (x: number, y: number, seed: number): number => {
|
|
95
|
+
let h = Math.imul(x, 0x27d4eb2d) ^ Math.imul(y, 0x165667b1) ^ Math.imul(seed, 0x9e3779b1);
|
|
96
|
+
h = Math.imul(h ^ (h >>> 15), 0x2545f491);
|
|
97
|
+
return (h ^ (h >>> 13)) >>> 0;
|
|
98
|
+
};
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* A patch of world that spells leave marks on.
|
|
102
|
+
*
|
|
103
|
+
* One float array per channel, decayed on `update`, written by `splat`. `consumeDirty` reports the
|
|
104
|
+
* cells that changed since the last call, so a material uploads a strip instead of the whole grid.
|
|
105
|
+
*/
|
|
106
|
+
export class ReactionField {
|
|
107
|
+
readonly resolution: number;
|
|
108
|
+
readonly size: number;
|
|
109
|
+
readonly dx: number;
|
|
110
|
+
/** Patch centre in world metres. */
|
|
111
|
+
centerX = 0;
|
|
112
|
+
centerZ = 0;
|
|
113
|
+
/** Bumped whenever any cell changes, so an upload can skip an unchanged frame. */
|
|
114
|
+
version = 0;
|
|
115
|
+
|
|
116
|
+
readonly #channels: Record<ReactionChannel, Float32Array>;
|
|
117
|
+
readonly #halfLife: Record<ReactionChannel, number>;
|
|
118
|
+
#dirty: { minX: number; minZ: number; maxX: number; maxZ: number } | undefined;
|
|
119
|
+
#empty = true;
|
|
120
|
+
|
|
121
|
+
constructor(options: IReactionFieldOptions = {}) {
|
|
122
|
+
const resolution = options.resolution ?? 96;
|
|
123
|
+
if (!Number.isInteger(resolution) || resolution < 16 || resolution > 512)
|
|
124
|
+
throw new RangeError("resolution must be an integer in 16..512");
|
|
125
|
+
const size = options.size ?? 120;
|
|
126
|
+
if (!Number.isFinite(size) || size <= 0) throw new RangeError("size must be a positive length");
|
|
127
|
+
this.resolution = resolution;
|
|
128
|
+
this.size = size;
|
|
129
|
+
this.dx = size / resolution;
|
|
130
|
+
const count = resolution * resolution;
|
|
131
|
+
this.#channels = {} as Record<ReactionChannel, Float32Array>;
|
|
132
|
+
this.#halfLife = { ...DEFAULT_HALF_LIFE };
|
|
133
|
+
for (const channel of REACTION_CHANNELS) {
|
|
134
|
+
this.#channels[channel] = new Float32Array(count);
|
|
135
|
+
const halfLife = options.halfLife?.[channel];
|
|
136
|
+
if (halfLife !== undefined) {
|
|
137
|
+
if (!Number.isFinite(halfLife) || halfLife <= 0)
|
|
138
|
+
throw new RangeError(`halfLife.${channel} must be positive and finite`);
|
|
139
|
+
this.#halfLife[channel] = halfLife;
|
|
140
|
+
}
|
|
141
|
+
}
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
/** The live values of one channel, row-major from the patch's -x/-z corner. Read-only to a game. */
|
|
145
|
+
data(channel: ReactionChannel): Float32Array {
|
|
146
|
+
return this.#channels[channel];
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
/** True while every cell of every channel is exactly zero. */
|
|
150
|
+
get empty(): boolean {
|
|
151
|
+
return this.#empty;
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
/** True while the point is inside the patch, `margin` metres in from its rim. */
|
|
155
|
+
contains(x: number, z: number, margin = 0): boolean {
|
|
156
|
+
const half = this.size / 2 - margin;
|
|
157
|
+
return Math.abs(x - this.centerX) < half && Math.abs(z - this.centerZ) < half;
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
/** Nearest-neighbour read at a world point, 0 outside the patch. Cheap enough for a combo check. */
|
|
161
|
+
sample(channel: ReactionChannel, x: number, z: number): number {
|
|
162
|
+
if (!this.contains(x, z)) return 0;
|
|
163
|
+
const n = this.resolution;
|
|
164
|
+
const i = Math.min(n - 1, Math.max(0, Math.floor(((x - this.centerX) / this.size + 0.5) * n)));
|
|
165
|
+
const j = Math.min(n - 1, Math.max(0, Math.floor(((z - this.centerZ) / this.size + 0.5) * n)));
|
|
166
|
+
return (this.#channels[channel] as Float32Array)[j * n + i] as number;
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
/** Strongest channel at a point, for a game that only asks "is anything happening here". */
|
|
170
|
+
strongest(x: number, z: number): ReactionChannel | undefined {
|
|
171
|
+
let best: ReactionChannel | undefined;
|
|
172
|
+
let bestValue = 0;
|
|
173
|
+
for (const channel of REACTION_CHANNELS) {
|
|
174
|
+
const value = this.sample(channel, x, z);
|
|
175
|
+
if (value > bestValue) {
|
|
176
|
+
bestValue = value;
|
|
177
|
+
best = channel;
|
|
178
|
+
}
|
|
179
|
+
}
|
|
180
|
+
return best;
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
/**
|
|
184
|
+
* Lay a mark on the patch. Every channel is additive and saturates at 1, so two fireballs on the
|
|
185
|
+
* same cell burn hotter than one but never past the top of the range. Off-patch splats return
|
|
186
|
+
* false and change nothing.
|
|
187
|
+
*/
|
|
188
|
+
splat(splat: IReactionSplat): boolean {
|
|
189
|
+
// Validate before anything else: off-patch and malformed are different answers, and a caller
|
|
190
|
+
// that hands in a NaN must be told so rather than silently told "off patch".
|
|
191
|
+
const radius = validateSplat(splat);
|
|
192
|
+
if (!this.contains(splat.x, splat.z)) return false;
|
|
193
|
+
const amounts = amountsOf(splat);
|
|
194
|
+
if (amounts === undefined) return true;
|
|
195
|
+
const { cells, hiX, hiZ, ix, iz, loX, loZ } = this.#cellRect(splat, radius);
|
|
196
|
+
const seed = splat.seed ?? 0;
|
|
197
|
+
const shape = {
|
|
198
|
+
angleCos: Math.cos(splat.angle ?? 0),
|
|
199
|
+
angleSin: Math.sin(splat.angle ?? 0),
|
|
200
|
+
cells,
|
|
201
|
+
pattern: splat.pattern ?? "radial",
|
|
202
|
+
};
|
|
203
|
+
const n = this.resolution;
|
|
204
|
+
for (let j = loZ; j <= hiZ; j++) {
|
|
205
|
+
for (let i = loX; i <= hiX; i++) {
|
|
206
|
+
const shaped = cellShape(shape, i - ix, j - iz);
|
|
207
|
+
if (shaped <= 0.002) continue;
|
|
208
|
+
// A per-cell wobble keeps a mark from reading as an airbrushed circle.
|
|
209
|
+
const grain = 0.7 + 0.6 * ((hash2(i, j, seed) & 0xffff) / 0xffff);
|
|
210
|
+
const index = j * n + i;
|
|
211
|
+
for (const [channel, amount] of amounts) {
|
|
212
|
+
const data = this.#channels[channel];
|
|
213
|
+
data[index] = clamp01((data[index] as number) + amount * shaped * grain);
|
|
214
|
+
}
|
|
215
|
+
}
|
|
216
|
+
}
|
|
217
|
+
this.#markDirty(loX, loZ, hiX, hiZ);
|
|
218
|
+
this.#empty = false;
|
|
219
|
+
return true;
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
/** Forget everything now, and report one last full-patch upload. */
|
|
223
|
+
clear(): void {
|
|
224
|
+
for (const channel of REACTION_CHANNELS) (this.#channels[channel] as Float32Array).fill(0);
|
|
225
|
+
this.#empty = true;
|
|
226
|
+
this.#markDirty(0, 0, this.resolution - 1, this.resolution - 1);
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
/** Move the patch with the action. Newly exposed cells arrive clean. */
|
|
230
|
+
recenter(x: number, z: number): void {
|
|
231
|
+
finite(x, "x");
|
|
232
|
+
finite(z, "z");
|
|
233
|
+
const di = Math.round((x - this.centerX) / this.dx);
|
|
234
|
+
const dj = Math.round((z - this.centerZ) / this.dx);
|
|
235
|
+
if (di === 0 && dj === 0) return;
|
|
236
|
+
this.centerX += di * this.dx;
|
|
237
|
+
this.centerZ += dj * this.dx;
|
|
238
|
+
if (this.#empty) return;
|
|
239
|
+
if (Math.abs(di) >= this.resolution || Math.abs(dj) >= this.resolution) {
|
|
240
|
+
for (const channel of REACTION_CHANNELS) (this.#channels[channel] as Float32Array).fill(0);
|
|
241
|
+
this.#empty = true;
|
|
242
|
+
} else {
|
|
243
|
+
const scratch = new Float32Array(this.resolution * this.resolution);
|
|
244
|
+
for (const channel of REACTION_CHANNELS)
|
|
245
|
+
shift(this.#channels[channel], this.resolution, di, dj, scratch);
|
|
246
|
+
}
|
|
247
|
+
this.#markDirty(0, 0, this.resolution - 1, this.resolution - 1);
|
|
248
|
+
}
|
|
249
|
+
|
|
250
|
+
/** Decay every channel on its own half-life. Time passing on a clean patch changes no cell. */
|
|
251
|
+
update(dt: number): void {
|
|
252
|
+
if (!Number.isFinite(dt) || dt < 0)
|
|
253
|
+
throw new RangeError("ReactionField.update delta must be finite and non-negative");
|
|
254
|
+
if (this.#empty || dt === 0) return;
|
|
255
|
+
let live = false;
|
|
256
|
+
for (const channel of REACTION_CHANNELS) live = this.#decay(channel, dt) || live;
|
|
257
|
+
if (!live) this.#empty = true;
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
/**
|
|
261
|
+
* Hand back the cells that changed since the last call, and forget them.
|
|
262
|
+
* `undefined` means nothing changed, so an upload can be skipped whole.
|
|
263
|
+
*/
|
|
264
|
+
consumeDirty(): IReactionDirty | undefined {
|
|
265
|
+
const dirty = this.#dirty;
|
|
266
|
+
this.#dirty = undefined;
|
|
267
|
+
if (dirty === undefined) return undefined;
|
|
268
|
+
return {
|
|
269
|
+
height: dirty.maxZ - dirty.minZ + 1,
|
|
270
|
+
width: dirty.maxX - dirty.minX + 1,
|
|
271
|
+
x: dirty.minX,
|
|
272
|
+
z: dirty.minZ,
|
|
273
|
+
};
|
|
274
|
+
}
|
|
275
|
+
|
|
276
|
+
/** The cells a splat can reach, and the splat's centre in grid coordinates. */
|
|
277
|
+
#cellRect(
|
|
278
|
+
splat: IReactionSplat,
|
|
279
|
+
radius: number,
|
|
280
|
+
): {
|
|
281
|
+
ix: number;
|
|
282
|
+
iz: number;
|
|
283
|
+
cells: number;
|
|
284
|
+
loX: number;
|
|
285
|
+
hiX: number;
|
|
286
|
+
loZ: number;
|
|
287
|
+
hiZ: number;
|
|
288
|
+
} {
|
|
289
|
+
const n = this.resolution;
|
|
290
|
+
const ix = ((splat.x - this.centerX) / this.size + 0.5) * n - 0.5;
|
|
291
|
+
const iz = ((splat.z - this.centerZ) / this.size + 0.5) * n - 0.5;
|
|
292
|
+
const cells = Math.max(0.75, radius / this.dx);
|
|
293
|
+
// A streak stretches 2.4x along its axis, so its reach has to cover that or the mark is cut off.
|
|
294
|
+
const reach = 2.2 * cells * (splat.pattern === "streak" ? 2.4 : 1);
|
|
295
|
+
return {
|
|
296
|
+
cells,
|
|
297
|
+
hiX: Math.min(n - 1, Math.ceil(ix + reach)),
|
|
298
|
+
hiZ: Math.min(n - 1, Math.ceil(iz + reach)),
|
|
299
|
+
ix,
|
|
300
|
+
iz,
|
|
301
|
+
loX: Math.max(0, Math.floor(ix - reach)),
|
|
302
|
+
loZ: Math.max(0, Math.floor(iz - reach)),
|
|
303
|
+
};
|
|
304
|
+
}
|
|
305
|
+
|
|
306
|
+
/** Decay one channel for a step. True while any cell is still lit. */
|
|
307
|
+
#decay(channel: ReactionChannel, dt: number): boolean {
|
|
308
|
+
const data = this.#channels[channel];
|
|
309
|
+
// exp2(-dt / halfLife): the fraction still left after this step.
|
|
310
|
+
const keep = 2 ** (-dt / (this.#halfLife[channel] as number));
|
|
311
|
+
const extent = { hiX: -1, hiZ: -1, loX: this.resolution, loZ: this.resolution };
|
|
312
|
+
const live = decayCells(data, keep, this.resolution, extent);
|
|
313
|
+
// Only the cells that were lit changed, so an upload stays a strip and not the whole patch.
|
|
314
|
+
if (extent.hiX >= 0) this.#markDirty(extent.loX, extent.loZ, extent.hiX, extent.hiZ);
|
|
315
|
+
return live;
|
|
316
|
+
}
|
|
317
|
+
|
|
318
|
+
#markDirty(minX: number, minZ: number, maxX: number, maxZ: number): void {
|
|
319
|
+
this.version += 1;
|
|
320
|
+
const dirty = this.#dirty;
|
|
321
|
+
if (dirty === undefined) this.#dirty = { maxX, maxZ, minX, minZ };
|
|
322
|
+
else {
|
|
323
|
+
dirty.minX = Math.min(dirty.minX, minX);
|
|
324
|
+
dirty.minZ = Math.min(dirty.minZ, minZ);
|
|
325
|
+
dirty.maxX = Math.max(dirty.maxX, maxX);
|
|
326
|
+
dirty.maxZ = Math.max(dirty.maxZ, maxZ);
|
|
327
|
+
}
|
|
328
|
+
}
|
|
329
|
+
}
|
|
330
|
+
|
|
331
|
+
/** Decay one channel's cells in place, recording the lit rectangle and whether anything survives. */
|
|
332
|
+
function decayCells(
|
|
333
|
+
data: Float32Array,
|
|
334
|
+
keep: number,
|
|
335
|
+
n: number,
|
|
336
|
+
extent: { loX: number; loZ: number; hiX: number; hiZ: number },
|
|
337
|
+
): boolean {
|
|
338
|
+
let live = false;
|
|
339
|
+
for (let index = 0; index < data.length; index++) {
|
|
340
|
+
const value = data[index] as number;
|
|
341
|
+
if (value === 0) continue;
|
|
342
|
+
const next = value * keep;
|
|
343
|
+
data[index] = next < 1e-4 ? 0 : next;
|
|
344
|
+
const i = index % n;
|
|
345
|
+
const j = (index - i) / n;
|
|
346
|
+
if (i < extent.loX) extent.loX = i;
|
|
347
|
+
if (i > extent.hiX) extent.hiX = i;
|
|
348
|
+
if (j < extent.loZ) extent.loZ = j;
|
|
349
|
+
if (j > extent.hiZ) extent.hiZ = j;
|
|
350
|
+
if (data[index] !== 0) live = true;
|
|
351
|
+
}
|
|
352
|
+
return live;
|
|
353
|
+
}
|
|
354
|
+
|
|
355
|
+
/** Reject a splat that is not a real mark, before any of it is applied. */
|
|
356
|
+
function validateSplat(splat: IReactionSplat): number {
|
|
357
|
+
const radius = finite(splat.radius, "splat.radius");
|
|
358
|
+
if (!(radius > 0)) throw new RangeError("splat.radius must be positive");
|
|
359
|
+
if (!Number.isFinite(splat.x)) throw new TypeError("splat.x must be finite");
|
|
360
|
+
if (!Number.isFinite(splat.z)) throw new TypeError("splat.z must be finite");
|
|
361
|
+
if (splat.angle !== undefined && !Number.isFinite(splat.angle))
|
|
362
|
+
throw new TypeError("splat.angle must be finite");
|
|
363
|
+
// A NaN amount would saturate nothing and never decay, leaving the patch permanently dirty.
|
|
364
|
+
for (const channel of REACTION_CHANNELS) {
|
|
365
|
+
const amount = splat[channel];
|
|
366
|
+
if (amount !== undefined && !Number.isFinite(amount))
|
|
367
|
+
throw new TypeError(`splat.${channel} must be finite`);
|
|
368
|
+
}
|
|
369
|
+
return radius;
|
|
370
|
+
}
|
|
371
|
+
|
|
372
|
+
/** The channels a splat actually writes, or undefined when it asks for none. */
|
|
373
|
+
function amountsOf(splat: IReactionSplat): [ReactionChannel, number][] | undefined {
|
|
374
|
+
const amounts: [ReactionChannel, number][] = [];
|
|
375
|
+
for (const channel of REACTION_CHANNELS) {
|
|
376
|
+
const amount = splat[channel] ?? 0;
|
|
377
|
+
if (amount !== 0) amounts.push([channel, amount]);
|
|
378
|
+
}
|
|
379
|
+
return amounts.length === 0 ? undefined : amounts;
|
|
380
|
+
}
|
|
381
|
+
|
|
382
|
+
/** How much of a splat lands on one cell, from the pattern and the distance to its centre. */
|
|
383
|
+
function cellShape(
|
|
384
|
+
shape: {
|
|
385
|
+
readonly pattern: ReactionPattern;
|
|
386
|
+
readonly cells: number;
|
|
387
|
+
readonly angleCos: number;
|
|
388
|
+
readonly angleSin: number;
|
|
389
|
+
},
|
|
390
|
+
ddx: number,
|
|
391
|
+
ddz: number,
|
|
392
|
+
): number {
|
|
393
|
+
const { cells, pattern } = shape;
|
|
394
|
+
if (pattern === "streak") {
|
|
395
|
+
// Stretch along the impact direction, so a slid-in spell leaves a line, not a disc.
|
|
396
|
+
const along = (ddx * shape.angleCos + ddz * shape.angleSin) / 2.4;
|
|
397
|
+
const across = (-ddx * shape.angleSin + ddz * shape.angleCos) / 0.8;
|
|
398
|
+
return Math.exp(-((along * along + across * across) / (cells * cells)));
|
|
399
|
+
}
|
|
400
|
+
const q = (ddx * ddx + ddz * ddz) / (cells * cells);
|
|
401
|
+
return pattern === "ring" ? Math.exp(-((Math.sqrt(q) - 0.8) ** 2) * 6) : Math.exp(-q);
|
|
402
|
+
}
|
|
403
|
+
|
|
404
|
+
function shift(data: Float32Array, n: number, di: number, dj: number, scratch: Float32Array): void {
|
|
405
|
+
scratch.fill(0);
|
|
406
|
+
const i0 = Math.max(0, -di);
|
|
407
|
+
const i1 = Math.min(n, n - di);
|
|
408
|
+
const j0 = Math.max(0, -dj);
|
|
409
|
+
const j1 = Math.min(n, n - dj);
|
|
410
|
+
for (let j = j0; j < j1; j++) {
|
|
411
|
+
const source = (j + dj) * n + i0 + di;
|
|
412
|
+
scratch.set(data.subarray(source, source + (i1 - i0)), j * n + i0);
|
|
413
|
+
}
|
|
414
|
+
data.set(scratch);
|
|
415
|
+
}
|
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The lights a spell throws, without the light count ever moving.
|
|
3
|
+
*
|
|
4
|
+
* A point light added at cast time is a shader recompile and a lighting-state change in the middle
|
|
5
|
+
* of a fight. This pool creates its lights once, parks every one of them at zero intensity, and
|
|
6
|
+
* hands them out for the duration of an impact. A cast therefore changes what the lights do and
|
|
7
|
+
* never what they are. Niagara submits spell-sized lights as plain simple lights for the same
|
|
8
|
+
* reason (UE 5.8.3: Engine/Plugins/FX/Niagara/Source/Niagara/Private/NiagaraRendererLights.cpp:100,
|
|
9
|
+
* :201).
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
import { type Color, type Object3D, PointLight } from "three";
|
|
13
|
+
|
|
14
|
+
export interface ISpellLightsOptions {
|
|
15
|
+
/** Where the lights are added. A scene, or any object that outlives the casts. */
|
|
16
|
+
readonly parent: Object3D;
|
|
17
|
+
/** Lights in the pool. Defaults to 4: a charge glow, an impact flash, and two in flight. */
|
|
18
|
+
readonly count?: number;
|
|
19
|
+
/** Lights are cheaper than shadows for a flash; a spell never casts one. */
|
|
20
|
+
readonly shadows?: boolean;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
interface ISlotState {
|
|
24
|
+
/** Seconds left on the current flash. */
|
|
25
|
+
remaining: number;
|
|
26
|
+
/** Seconds the current flash was asked for. */
|
|
27
|
+
duration: number;
|
|
28
|
+
/** Intensity the current flash started at. */
|
|
29
|
+
peak: number;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** One light, and the game-owned look it was given. */
|
|
33
|
+
export interface ISpellLightFlash {
|
|
34
|
+
/** World position of the flash. */
|
|
35
|
+
readonly x: number;
|
|
36
|
+
readonly y: number;
|
|
37
|
+
readonly z: number;
|
|
38
|
+
readonly color: Color;
|
|
39
|
+
/** Peak intensity in candela. */
|
|
40
|
+
readonly intensity: number;
|
|
41
|
+
/** Metres the light reaches. */
|
|
42
|
+
readonly range: number;
|
|
43
|
+
/** Seconds the flash takes to decay to zero. */
|
|
44
|
+
readonly seconds: number;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
const finite = (value: number, label: string): number => {
|
|
48
|
+
if (!Number.isFinite(value)) throw new TypeError(`${label} must be finite`);
|
|
49
|
+
return value;
|
|
50
|
+
};
|
|
51
|
+
|
|
52
|
+
/**
|
|
53
|
+
* A fixed pool of spell lights.
|
|
54
|
+
*
|
|
55
|
+
* `flash` returns false when every light is busy: a spell reports that and carries on without
|
|
56
|
+
* one rather than growing the pool. Intensity decays linearly to zero, which reads as a flash
|
|
57
|
+
* rather than a lamp fading, and Update runs on the same fixed delta as the casts.
|
|
58
|
+
*/
|
|
59
|
+
export class SpellLights {
|
|
60
|
+
readonly lights: readonly PointLight[];
|
|
61
|
+
readonly #slots: ISlotState[];
|
|
62
|
+
|
|
63
|
+
constructor(options: ISpellLightsOptions) {
|
|
64
|
+
if (options.parent === undefined || options.parent === null)
|
|
65
|
+
throw new Error("SpellLights.parent is required.");
|
|
66
|
+
const count = options.count ?? 4;
|
|
67
|
+
if (!Number.isInteger(count) || count < 1 || count > 32)
|
|
68
|
+
throw new RangeError("SpellLights.count must be an integer in 1..32");
|
|
69
|
+
this.lights = Array.from({ length: count }, (_, index) => {
|
|
70
|
+
const light = new PointLight(0xffffff, 0, 10, 2);
|
|
71
|
+
light.name = `spell-light-${index}`;
|
|
72
|
+
light.intensity = 0;
|
|
73
|
+
light.castShadow = options.shadows ?? false;
|
|
74
|
+
// Never toggle `visible`: Three.js drops an invisible object before it collects lights, so the
|
|
75
|
+
// frame would see a different light count and recompile. A dark light is intensity 0.
|
|
76
|
+
options.parent.add(light);
|
|
77
|
+
return light;
|
|
78
|
+
});
|
|
79
|
+
this.#slots = this.lights.map(() => ({ duration: 1, peak: 0, remaining: 0 }));
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/** True while at least one light is lit, so a game can skip its own light bookkeeping. */
|
|
83
|
+
get active(): boolean {
|
|
84
|
+
return this.#slots.some((slot) => slot.remaining > 0);
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/** The light this flash took, or undefined when the pool was full. */
|
|
88
|
+
flash(request: ISpellLightFlash): PointLight | undefined {
|
|
89
|
+
const seconds = finite(request.seconds, "flash.seconds");
|
|
90
|
+
if (seconds <= 0) throw new RangeError("flash.seconds must be positive");
|
|
91
|
+
// Validate before a slot is claimed: a throw must not leave a light marked busy.
|
|
92
|
+
const intensity = finite(request.intensity, "flash.intensity");
|
|
93
|
+
const range = finite(request.range, "flash.range");
|
|
94
|
+
const x = finite(request.x, "flash.x");
|
|
95
|
+
const y = finite(request.y, "flash.y");
|
|
96
|
+
const z = finite(request.z, "flash.z");
|
|
97
|
+
const index = this.#slots.findIndex((slot) => slot.remaining <= 0);
|
|
98
|
+
if (index < 0) return undefined;
|
|
99
|
+
const light = this.lights[index] as PointLight;
|
|
100
|
+
const slot = this.#slots[index] as ISlotState;
|
|
101
|
+
slot.peak = Math.max(0, intensity);
|
|
102
|
+
slot.duration = seconds;
|
|
103
|
+
slot.remaining = seconds;
|
|
104
|
+
light.position.set(x, y, z);
|
|
105
|
+
light.color.copy(request.color);
|
|
106
|
+
light.distance = Math.max(0, range);
|
|
107
|
+
light.intensity = slot.peak;
|
|
108
|
+
return light;
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/** Put every light out now, without waiting for its decay. */
|
|
112
|
+
clear(): void {
|
|
113
|
+
for (let index = 0; index < this.#slots.length; index++) {
|
|
114
|
+
const slot = this.#slots[index] as ISlotState;
|
|
115
|
+
slot.remaining = 0;
|
|
116
|
+
slot.peak = 0;
|
|
117
|
+
(this.lights[index] as PointLight).intensity = 0;
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
update(dt: number): void {
|
|
122
|
+
if (!Number.isFinite(dt) || dt < 0)
|
|
123
|
+
throw new RangeError("SpellLights.update delta must be finite and non-negative");
|
|
124
|
+
// Indexed loops: this runs every frame and allocating an entry iterator per light is waste.
|
|
125
|
+
for (let index = 0; index < this.#slots.length; index++) {
|
|
126
|
+
const slot = this.#slots[index] as ISlotState;
|
|
127
|
+
if (slot.remaining <= 0) continue;
|
|
128
|
+
const light = this.lights[index] as PointLight;
|
|
129
|
+
slot.remaining -= dt;
|
|
130
|
+
if (slot.remaining <= 0) {
|
|
131
|
+
slot.remaining = 0;
|
|
132
|
+
slot.peak = 0;
|
|
133
|
+
light.intensity = 0;
|
|
134
|
+
continue;
|
|
135
|
+
}
|
|
136
|
+
light.intensity = slot.peak * (slot.remaining / slot.duration);
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
}
|