@threenative/core 0.3.11 → 0.3.13
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/capabilities.json +1988 -204
- package/dist/{assets-YUbXa3-Y.d.ts → assets-CfMKnOsK.d.ts} +78 -1
- package/dist/camera-shake-CZKOfGn4.d.ts +46 -0
- package/dist/{canvas-layer-vCtanIeB.d.ts → canvas-layer-G7ttVy7y.d.ts} +1 -1
- package/dist/chunk-4SRAQFTU.js +133 -0
- package/dist/chunk-CFGTPFUH.js +231 -0
- package/dist/chunk-DIPIJICH.js +8916 -0
- package/dist/chunk-EEABDLUC.js +2237 -0
- package/dist/chunk-EFWZWLPY.js +1895 -0
- package/dist/chunk-GXY7B3JG.js +46 -0
- package/dist/chunk-GYUZJQ7U.js +280 -0
- package/dist/chunk-H4J6IAJE.js +504 -0
- package/dist/chunk-KIRUKTBQ.js +187 -0
- package/dist/chunk-QWJEMUUT.js +94 -0
- package/dist/chunk-SV4QVUTQ.js +31 -0
- package/dist/chunk-U4YHUKKL.js +615 -0
- package/dist/chunk-VP43GIWW.js +18 -0
- package/dist/chunk-XDTZ4QMO.js +160 -0
- package/dist/default-tone-mapping-GgKPTiBP.d.ts +4 -0
- package/dist/{game-DzMcitDO.d.ts → game-k8K3hZai.d.ts} +85 -9
- package/dist/hot.d.ts +5 -4
- package/dist/hot.js +5 -52
- package/dist/index.d.ts +633 -1351
- package/dist/index.js +12873 -23068
- package/dist/{model-lod-CTpZ6imz.d.ts → model-lod-DPTzeCcD.d.ts} +35 -3
- package/dist/playtest.d.ts +5 -4
- package/dist/playtest.js +25 -75
- package/dist/quality-BYqKGAwo.d.ts +868 -0
- package/dist/react-css.js +1 -215
- package/dist/react.d.ts +3 -2
- package/dist/render-environment.d.ts +170 -0
- package/dist/render-environment.js +352 -0
- package/dist/{renderer-rZm0hVqq.d.ts → renderer-BtOSseYf.d.ts} +42 -35
- 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 +6 -384
- package/dist/worker.js +13 -43
- package/dist/world.d.ts +988 -268
- package/dist/world.js +17464 -18290
- package/mcp/animation-server.mjs +1 -1
- package/mcp/animation.mjs +2 -3
- package/mcp/engine-server.mjs +245 -52
- package/mcp/servers.mjs +10 -3
- package/mcp/terrain.mjs +8 -0
- package/package.json +19 -7
- package/patches/three@0.187.0-prd269-upgrade.patch +2102 -0
- package/patches/three@0.187.0.patch +2004 -407
- package/src/animation-batch.ts +193 -0
- package/src/animation-layers.ts +7 -3
- package/src/animation.ts +209 -29
- package/src/asset-cache.ts +3 -3
- package/src/asset-memo.ts +202 -0
- package/src/assets.ts +437 -125
- package/src/auto-batch.ts +190 -44
- package/src/card-lod.ts +152 -0
- package/src/compressed-texture-preparation.ts +1008 -0
- package/src/compute-driven.ts +1 -1
- package/src/config.ts +8 -0
- package/src/debug.ts +103 -22
- package/src/dev-global.ts +54 -0
- package/src/engine-hooks.ts +37 -0
- package/src/frame-budget.ts +50 -23
- package/src/game-boot-phase.ts +269 -0
- package/src/game-dev-tools.ts +86 -0
- package/src/game-frame-loop.ts +958 -0
- package/src/game-renderer-metrics.ts +77 -0
- package/src/game-startup.ts +1076 -0
- package/src/game-ui.ts +84 -0
- package/src/game-validate.ts +70 -0
- package/src/game.ts +198 -2264
- package/src/gamepad-mappings.ts +269 -0
- package/src/generated/console-markers.ts +13 -0
- package/src/geometry-capture.ts +28 -4
- package/src/gpu-readings.ts +98 -0
- package/src/gpu-scene-bvh.ts +149 -36
- package/src/hot.ts +4 -7
- package/src/index.ts +141 -9
- package/src/input.ts +237 -25
- package/src/instanced-batch-lod.ts +3 -8
- package/src/interpolation.ts +171 -40
- package/src/launch-diagnostics.ts +22 -12
- package/src/look/ao-admission.ts +25 -0
- package/src/look/auto-exposure.ts +5 -16
- package/src/look/default-tone-mapping.ts +41 -5
- package/src/look/filmic-tone-mapping.ts +15 -13
- package/src/look/local-exposure.ts +2 -7
- package/src/look/look-diagnostics.ts +3 -3
- package/src/look/quad-pass.ts +21 -0
- package/src/look/quality.ts +14 -5
- package/src/look/unreal-bloom.ts +4 -13
- package/src/look/world-environment.ts +113 -103
- package/src/loop.ts +29 -0
- package/src/merge-parts.ts +20 -24
- package/src/model-lod.ts +139 -17
- package/src/particle-kinds.ts +515 -0
- package/src/particle-significance.ts +12 -0
- package/src/particles.ts +19 -10
- package/src/picking.ts +17 -3
- package/src/platform.ts +23 -4
- package/src/playtest.ts +27 -1
- package/src/profiling/FrameStages.ts +5 -6
- package/src/profiling/Spans.ts +3 -17
- package/src/profiling/debug-telemetry.ts +2 -6
- package/src/profiling/render-list-validate.ts +6 -15
- package/src/projection-apply.ts +4 -1
- package/src/projection-marker.ts +2 -1
- package/src/projection-plan.ts +9 -6
- package/src/quiet-markers.ts +3 -10
- package/src/render/cpu-bvh.ts +100 -0
- package/src/render/depth-pyramid.ts +6 -14
- package/src/render/environment/environmentContribution.ts +202 -0
- package/src/render/environment/environmentRadiance.ts +44 -0
- package/src/render/environment/environmentSampleCache.ts +56 -0
- package/src/render/environment/environmentSampling.ts +201 -0
- package/src/render/environment/environmentSnapshot.ts +71 -0
- package/src/render/environment/gate.ts +57 -0
- package/src/render/mesh-pool.ts +4 -20
- package/src/render/probe-trace.ts +872 -0
- package/src/render/probe-volume.ts +780 -34
- package/src/render/radiance-cache.ts +17 -0
- package/src/render/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-partial.ts +13 -0
- package/src/render/virtual-shadow.ts +231 -1008
- package/src/render/world-impostor-surface.ts +402 -40
- package/src/render/world-impostor.ts +5 -2
- package/src/render-camera-cull.ts +98 -3
- package/src/render-environment.ts +41 -0
- package/src/render-pass-budget.ts +34 -7
- package/src/renderProjection.ts +22 -0
- package/src/renderer-config.ts +36 -0
- package/src/renderer-facts.ts +37 -0
- package/src/renderer.ts +144 -65
- package/src/resolution-scaler.ts +3 -2
- package/src/scene-entry-inspectors.ts +61 -0
- package/src/snow-field.ts +2 -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-offscreen-bytes.ts +78 -0
- package/src/startup-readiness.ts +128 -34
- package/src/static-transform.ts +25 -19
- package/src/streamed-textures.ts +112 -0
- package/src/streaming.ts +68 -4
- package/src/texture-streaming.ts +331 -0
- package/src/version.ts +1 -1
- package/src/warmup.ts +56 -8
- package/src/water-surface.ts +9 -3
- package/src/worker.ts +12 -2
- package/src/world-bundle-safety.ts +446 -0
- package/src/world-cell-batches.ts +1178 -0
- package/src/world-cell-chunks.ts +1128 -0
- package/src/world-cell-data.ts +995 -0
- package/src/world-cell-impostors.ts +1461 -0
- package/src/world-cell-lod-bias.ts +151 -0
- package/src/world-cell-models.ts +1074 -0
- package/src/world-cell-options.ts +177 -0
- package/src/world-cell-placements.ts +798 -0
- package/src/world-cell-prewarm.ts +592 -0
- package/src/world-cell-readiness.ts +357 -0
- package/src/world-cell-records.ts +401 -0
- package/src/world-cell-render-bundles.ts +459 -0
- package/src/world-cell-render-gpu-dress.ts +710 -0
- package/src/world-cell-render-main-cull.ts +540 -0
- package/src/world-cell-render-shadow-claims.ts +198 -0
- package/src/world-cell-render-util.ts +259 -0
- package/src/world-cell-render.ts +1501 -0
- package/src/world-cell-residency.ts +754 -0
- package/src/world-cell-stale.ts +238 -0
- package/src/world-cells.ts +1335 -10418
- package/src/world-chunk-shadow.ts +308 -0
- package/src/world-collar.ts +315 -0
- package/src/world-gpu-flags.ts +131 -0
- package/src/world-gpu-readback.ts +881 -0
- package/src/world-gpu-reference.ts +524 -0
- package/src/world-gpu-scene.ts +256 -2286
- package/src/world-gpu-shadow.ts +203 -0
- package/src/world-gpu-types.ts +409 -0
- package/src/world-gpu-validation.ts +518 -0
- package/src/world-heightfield.ts +802 -0
- package/src/world-load-limiter.ts +111 -0
- package/src/world-model-sections.ts +80 -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-river-ribbon.ts +282 -0
- package/src/world-root-frame.ts +39 -0
- package/src/world-shore-field.ts +91 -0
- package/src/world-static-pose.ts +163 -0
- package/src/world-surface-sampler.ts +48 -0
- package/src/world-terrain-splat.ts +361 -153
- package/src/world-tile-budget.ts +249 -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 +247 -1755
- package/src/world-validate.ts +6 -14
- package/src/world-warm.ts +51 -0
- package/src/world-water-bodies.ts +359 -0
- package/src/world.ts +48 -741
|
@@ -0,0 +1,361 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A spell is not an effect: it is a timeline. Charge, release, travel, impact and linger drive
|
|
3
|
+
* several systems in turn, and the sequence is the same every cast, so the engine owns the clock
|
|
4
|
+
* and the spell only answers "what does this phase look like".
|
|
5
|
+
*
|
|
6
|
+
* This is the upstream Ultra Elements `cast.js` phase machine, with the arena removed: a cast
|
|
7
|
+
* never asks where the floor is. It integrates a projectile in a straight line, hands the spell
|
|
8
|
+
* every frame to steer, and retires each record back into a fixed pool. Nothing is allocated per
|
|
9
|
+
* cast, so a game that casts on every frame at 60 Hz allocates nothing at all.
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
import { Vector3 } from "three";
|
|
13
|
+
|
|
14
|
+
/** The beats of a spell, in order. `release` is instantaneous and never observed by a game. */
|
|
15
|
+
export type CastPhase = "charge" | "travel" | "impact" | "linger" | "done";
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* How a spell reaches its target.
|
|
19
|
+
* - `projectile` integrates a velocity through `travel`, and lands on the target or on `groundAt`.
|
|
20
|
+
* - `beam` holds at the target while `held`, then lands.
|
|
21
|
+
* - `strike`, `area` and `self` skip travel and land on `release`.
|
|
22
|
+
*/
|
|
23
|
+
export type CastShape = "projectile" | "beam" | "strike" | "area" | "self";
|
|
24
|
+
|
|
25
|
+
const PHASES: readonly CastPhase[] = ["charge", "travel", "impact", "linger", "done"];
|
|
26
|
+
|
|
27
|
+
export interface ICastTiming {
|
|
28
|
+
/** Seconds of wind-up. Defaults to 0.5. */
|
|
29
|
+
readonly charge?: number;
|
|
30
|
+
/** Longest seconds of travel before the spell lands anyway. Defaults to 4. */
|
|
31
|
+
readonly travel?: number;
|
|
32
|
+
/** Seconds the impact reads on screen. Defaults to 0.2. */
|
|
33
|
+
readonly impact?: number;
|
|
34
|
+
/** Seconds the aftermath stays. Defaults to 2. */
|
|
35
|
+
readonly linger?: number;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/** One cast's worth of reusable state. The spell owns what goes in `data`. */
|
|
39
|
+
export interface ICast {
|
|
40
|
+
/** Pool slot, stable for the pool's lifetime: a spell may key per-slot state by it. */
|
|
41
|
+
readonly index: number;
|
|
42
|
+
spell: ISpell;
|
|
43
|
+
shape: CastShape;
|
|
44
|
+
phase: CastPhase;
|
|
45
|
+
/** Seconds inside the current phase, reset on every `enter`. */
|
|
46
|
+
t: number;
|
|
47
|
+
/** Seconds since the cast started. The pool recycles the largest `age` when it is full. */
|
|
48
|
+
age: number;
|
|
49
|
+
seed: number;
|
|
50
|
+
/** Where the spell was released from. */
|
|
51
|
+
readonly from: Vector3;
|
|
52
|
+
/** The target the game asked for. */
|
|
53
|
+
readonly to: Vector3;
|
|
54
|
+
/** Current world position: `from` while charging, integrated through travel. */
|
|
55
|
+
readonly pos: Vector3;
|
|
56
|
+
readonly vel: Vector3;
|
|
57
|
+
/** Unit vector `from` -> `to`. */
|
|
58
|
+
readonly dir: Vector3;
|
|
59
|
+
/** A held beam stays in `travel` until the game releases it. */
|
|
60
|
+
held: boolean;
|
|
61
|
+
/** Metres travelled. A spell may read it, the pool only accumulates it. */
|
|
62
|
+
travelled: number;
|
|
63
|
+
/** Impact radius in metres, validated once when the cast started. */
|
|
64
|
+
radius: number;
|
|
65
|
+
readonly durations: {
|
|
66
|
+
charge: number;
|
|
67
|
+
impact: number;
|
|
68
|
+
linger: number;
|
|
69
|
+
travel: number;
|
|
70
|
+
};
|
|
71
|
+
/** Spell-owned per-slot scratch, preallocated with the record and reset by the spell at charge. */
|
|
72
|
+
readonly data: Record<string, unknown>;
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/**
|
|
76
|
+
* A spell as the pool sees it. Every factory on `@threenative/core/spells` returns one of these:
|
|
77
|
+
* it is the only shape the pool drives, and the spell reads the world through `SpellWorld`.
|
|
78
|
+
*/
|
|
79
|
+
export interface ISpell {
|
|
80
|
+
/** The factory name without its `create` prefix, lowercase: `fireball`. */
|
|
81
|
+
readonly name: string;
|
|
82
|
+
/** How the spell reaches its target. Defaults to `projectile`. */
|
|
83
|
+
readonly shape?: CastShape;
|
|
84
|
+
/** Per-spell beat lengths. Missing beats take the pool defaults. */
|
|
85
|
+
readonly timing?: ICastTiming;
|
|
86
|
+
/** Metres per second for a projectile. Defaults to 15. */
|
|
87
|
+
readonly speed?: number;
|
|
88
|
+
/** Metres of collision radius at impact. Defaults to 0.3. */
|
|
89
|
+
readonly radius?: number;
|
|
90
|
+
/** Called on each beat change, including `done`. */
|
|
91
|
+
readonly phase?: (cast: ICast, phase: CastPhase) => void;
|
|
92
|
+
/**
|
|
93
|
+
* Owns the travel step for a spell that steers or arcs. The pool then skips its own straight-line
|
|
94
|
+
* integration and floor test for this cast; return true to land it. A spell with no `travel` hook
|
|
95
|
+
* is integrated by the pool and cannot miss.
|
|
96
|
+
*/
|
|
97
|
+
readonly travel?: (cast: ICast, dt: number) => boolean | undefined;
|
|
98
|
+
/** Called once per frame while the cast is alive, in every phase. */
|
|
99
|
+
readonly update?: (cast: ICast, dt: number) => void;
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
export interface ICastOptions {
|
|
103
|
+
/** World point to travel from. Defaults to the world's `focus`. */
|
|
104
|
+
readonly from?: Vector3;
|
|
105
|
+
/** Hold a beam open past its sustain time. Defaults to false. */
|
|
106
|
+
readonly held?: boolean;
|
|
107
|
+
/** Override the generated seed, so a replay reproduces the same scatter. */
|
|
108
|
+
readonly seed?: number;
|
|
109
|
+
/** Override `spell.shape`, for a spell that carries several forms. */
|
|
110
|
+
readonly shape?: CastShape;
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
/** What a pool needs from the world: the floor, and how many records to keep. */
|
|
114
|
+
export interface ICastEnvironment {
|
|
115
|
+
/** Floor height under a point, so a projectile lands on a hill and not at y = 0. */
|
|
116
|
+
readonly groundAt?: (x: number, z: number) => number;
|
|
117
|
+
/** Records in the pool. Defaults to 16. */
|
|
118
|
+
readonly castSlots?: number;
|
|
119
|
+
/**
|
|
120
|
+
* Where a cast with no `from` starts: the caster's hand. `SpellWorld` supplies its own `focus`,
|
|
121
|
+
* so a game that moves that point gets it here with no extra wiring.
|
|
122
|
+
*/
|
|
123
|
+
readonly focus?: Vector3;
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
const finite = (value: number, label: string): number => {
|
|
127
|
+
if (!Number.isFinite(value)) throw new TypeError(`${label} must be finite`);
|
|
128
|
+
return value;
|
|
129
|
+
};
|
|
130
|
+
|
|
131
|
+
/** Deterministic 32-bit hash, so a seed alone reproduces a scatter without touching `Math.random`. */
|
|
132
|
+
const mixSeed = (seed: number, salt: number): number => {
|
|
133
|
+
let x = (seed ^ (salt * 0x9e3779b1)) | 0;
|
|
134
|
+
x = Math.imul(x ^ (x >>> 16), 0x21f0aaad);
|
|
135
|
+
x = Math.imul(x ^ (x >>> 15), 0x735a2d97);
|
|
136
|
+
return (x ^ (x >>> 15)) >>> 0;
|
|
137
|
+
};
|
|
138
|
+
|
|
139
|
+
/** The spell a retired record reports, so `spell` is never undefined and never a cast. */
|
|
140
|
+
const IDLE_SPELL: ISpell = { name: "idle", shape: "self" };
|
|
141
|
+
|
|
142
|
+
function emptyRecord(index: number): ICast {
|
|
143
|
+
return {
|
|
144
|
+
age: 0,
|
|
145
|
+
data: {},
|
|
146
|
+
dir: new Vector3(),
|
|
147
|
+
durations: { charge: 0.5, impact: 0.2, linger: 2, travel: 4 },
|
|
148
|
+
from: new Vector3(),
|
|
149
|
+
held: false,
|
|
150
|
+
index,
|
|
151
|
+
phase: "done",
|
|
152
|
+
pos: new Vector3(),
|
|
153
|
+
seed: 0,
|
|
154
|
+
shape: "projectile",
|
|
155
|
+
spell: IDLE_SPELL,
|
|
156
|
+
t: 0,
|
|
157
|
+
to: new Vector3(),
|
|
158
|
+
radius: 0.3,
|
|
159
|
+
travelled: 0,
|
|
160
|
+
vel: new Vector3(),
|
|
161
|
+
};
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
const scratch = new Vector3();
|
|
165
|
+
/** Where a cast starts when neither the call nor the world named a point. */
|
|
166
|
+
const ORIGIN = new Vector3();
|
|
167
|
+
|
|
168
|
+
/**
|
|
169
|
+
* Drive spell timelines from a fixed pool of records.
|
|
170
|
+
*
|
|
171
|
+
* The pool is full at capacity and never grows: a full pool recycles the record that has been alive
|
|
172
|
+
* longest, which is the cast the player has already stopped watching. Every record keeps its
|
|
173
|
+
* identity across casts, so a spell's per-slot state and any pooled mesh it binds stay warm.
|
|
174
|
+
*/
|
|
175
|
+
export class CastPool {
|
|
176
|
+
/** Every slot, alive or not. Read `phase !== "done"` for the live ones. */
|
|
177
|
+
readonly casts: readonly ICast[];
|
|
178
|
+
readonly #groundAt: ((x: number, z: number) => number) | undefined;
|
|
179
|
+
readonly #focus: Vector3 | undefined;
|
|
180
|
+
/** The newest live cast, or undefined. */
|
|
181
|
+
#last: ICast | undefined;
|
|
182
|
+
#seed = 0;
|
|
183
|
+
|
|
184
|
+
constructor(world: ICastEnvironment = {}) {
|
|
185
|
+
const capacity = world.castSlots ?? 16;
|
|
186
|
+
if (!Number.isInteger(capacity) || capacity < 1 || capacity > 256)
|
|
187
|
+
throw new RangeError("CastPool capacity must be an integer in 1..256");
|
|
188
|
+
this.#groundAt = world.groundAt;
|
|
189
|
+
this.#focus = world.focus;
|
|
190
|
+
this.casts = Array.from({ length: capacity }, (_, index) => emptyRecord(index));
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
/** The newest live cast. What a HUD reads for the phase strip. */
|
|
194
|
+
get active(): ICast | undefined {
|
|
195
|
+
return this.#last?.phase === "done" ? undefined : this.#last;
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
get count(): number {
|
|
199
|
+
let live = 0;
|
|
200
|
+
for (const cast of this.casts) live += cast.phase === "done" ? 0 : 1;
|
|
201
|
+
return live;
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
/** Start a spell. Returns the record, which the caller may read but the pool advances. */
|
|
205
|
+
cast(spell: ISpell, to: Vector3, options: ICastOptions = {}): ICast {
|
|
206
|
+
const record = this.#reserve();
|
|
207
|
+
// A cast with no origin starts at the caster's hand, never at whatever the slot last held.
|
|
208
|
+
const from = options.from ?? this.#focus ?? ORIGIN;
|
|
209
|
+
this.#validate(spell, to, from);
|
|
210
|
+
this.#arm(record, spell, to, from, options);
|
|
211
|
+
this.#enter(record, "charge");
|
|
212
|
+
this.#last = record;
|
|
213
|
+
return record;
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
/** The record this cast will use: a free slot, else the stale one, never a held beam if avoidable. */
|
|
217
|
+
#reserve(): ICast {
|
|
218
|
+
const free = this.casts.find((candidate) => candidate.phase === "done");
|
|
219
|
+
if (free !== undefined) return free;
|
|
220
|
+
// The cast alive longest is the one the player stopped watching, but a held beam is still under
|
|
221
|
+
// their finger, so it is only recycled when nothing else is left.
|
|
222
|
+
const unheld = this.casts.filter((candidate) => !candidate.held);
|
|
223
|
+
const pool = unheld.length > 0 ? unheld : this.casts;
|
|
224
|
+
const oldest = pool.reduce((a, b) => (b.age > a.age ? b : a));
|
|
225
|
+
this.#enter(oldest, "done");
|
|
226
|
+
return oldest;
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
/** Reject a cast the pool cannot honour, before any record is touched. */
|
|
230
|
+
#validate(spell: ISpell, to: Vector3, from: Vector3): void {
|
|
231
|
+
finite(to.x, "to.x");
|
|
232
|
+
finite(to.y, "to.y");
|
|
233
|
+
finite(to.z, "to.z");
|
|
234
|
+
finite(from.x, "from.x");
|
|
235
|
+
finite(from.y, "from.y");
|
|
236
|
+
finite(from.z, "from.z");
|
|
237
|
+
const radius = spell.radius ?? 0.3;
|
|
238
|
+
if (!Number.isFinite(radius) || radius < 0)
|
|
239
|
+
throw new RangeError(`${spell.name}.radius must be finite and non-negative`);
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
/** Fill a reserved record for a new cast. */
|
|
243
|
+
#arm(record: ICast, spell: ISpell, to: Vector3, from: Vector3, options: ICastOptions): void {
|
|
244
|
+
const durations = record.durations;
|
|
245
|
+
const timing = spell.timing ?? {};
|
|
246
|
+
durations.charge = finite(timing.charge ?? 0.5, "timing.charge");
|
|
247
|
+
durations.travel = finite(timing.travel ?? 4, "timing.travel");
|
|
248
|
+
durations.impact = finite(timing.impact ?? 0.2, "timing.impact");
|
|
249
|
+
durations.linger = finite(timing.linger ?? 2, "timing.linger");
|
|
250
|
+
record.spell = spell;
|
|
251
|
+
record.shape = options.shape ?? spell.shape ?? "projectile";
|
|
252
|
+
record.radius = spell.radius ?? 0.3;
|
|
253
|
+
record.held = options.held ?? false;
|
|
254
|
+
record.t = 0;
|
|
255
|
+
record.age = 0;
|
|
256
|
+
record.travelled = 0;
|
|
257
|
+
record.seed = options.seed ?? mixSeed(++this.#seed, 0x51ed);
|
|
258
|
+
record.from.copy(from);
|
|
259
|
+
record.to.copy(to);
|
|
260
|
+
record.pos.copy(from);
|
|
261
|
+
record.dir.subVectors(to, from);
|
|
262
|
+
if (record.dir.lengthSq() > 0) record.dir.normalize();
|
|
263
|
+
else record.dir.set(0, 0, 1);
|
|
264
|
+
record.vel.set(0, 0, 0);
|
|
265
|
+
}
|
|
266
|
+
|
|
267
|
+
/** End every held beam. A game calls this when the button comes up. */
|
|
268
|
+
releaseHeld(): void {
|
|
269
|
+
for (const cast of this.casts) cast.held = false;
|
|
270
|
+
}
|
|
271
|
+
|
|
272
|
+
/** Retire every live cast without running linger. */
|
|
273
|
+
clear(): void {
|
|
274
|
+
for (const cast of this.casts) if (cast.phase !== "done") this.#enter(cast, "done");
|
|
275
|
+
}
|
|
276
|
+
|
|
277
|
+
/**
|
|
278
|
+
* Advance every live cast. A projectile lands on the target, on the world's floor, or when its
|
|
279
|
+
* travel time runs out, whichever comes first.
|
|
280
|
+
*/
|
|
281
|
+
update(dt: number): void {
|
|
282
|
+
if (!Number.isFinite(dt) || dt < 0)
|
|
283
|
+
throw new RangeError("CastPool.update delta must be finite and non-negative");
|
|
284
|
+
for (const cast of this.casts) {
|
|
285
|
+
if (cast.phase === "done") continue;
|
|
286
|
+
cast.t += dt;
|
|
287
|
+
cast.age += dt;
|
|
288
|
+
const state = this.#advanceBeat(cast, dt);
|
|
289
|
+
if (state === "retired") continue;
|
|
290
|
+
cast.spell.update?.(cast, dt);
|
|
291
|
+
// A spell can only ask to land while it is in the air. Honouring the request in charge or
|
|
292
|
+
// linger would land it every frame and its impact callback would never stop firing.
|
|
293
|
+
if (state === "landed") this.#enter(cast, "impact");
|
|
294
|
+
}
|
|
295
|
+
}
|
|
296
|
+
|
|
297
|
+
/** Advance one record's beat: still running, landed on the spell's own word, or retired. */
|
|
298
|
+
#advanceBeat(cast: ICast, dt: number): "running" | "landed" | "retired" {
|
|
299
|
+
if (cast.phase === "charge") this.#advanceCharge(cast);
|
|
300
|
+
else if (cast.phase === "travel") return this.#advanceTravel(cast, dt) ? "landed" : "running";
|
|
301
|
+
else if (cast.phase === "impact") {
|
|
302
|
+
if (cast.t >= cast.durations.impact) this.#enter(cast, "linger");
|
|
303
|
+
} else if (cast.t >= cast.durations.linger) {
|
|
304
|
+
this.#enter(cast, "done");
|
|
305
|
+
return "retired";
|
|
306
|
+
}
|
|
307
|
+
return "running";
|
|
308
|
+
}
|
|
309
|
+
|
|
310
|
+
#advanceCharge(cast: ICast): void {
|
|
311
|
+
cast.pos.copy(cast.from);
|
|
312
|
+
if (cast.t < cast.durations.charge) return;
|
|
313
|
+
const spell = cast.spell;
|
|
314
|
+
if (cast.shape === "projectile") {
|
|
315
|
+
cast.vel.copy(cast.dir).multiplyScalar(finite(spell.speed ?? 15, `${spell.name}.speed`));
|
|
316
|
+
this.#enter(cast, "travel");
|
|
317
|
+
} else if (cast.shape === "beam") this.#enter(cast, "travel");
|
|
318
|
+
else {
|
|
319
|
+
if (cast.shape !== "self") cast.pos.copy(cast.to);
|
|
320
|
+
this.#enter(cast, "impact");
|
|
321
|
+
}
|
|
322
|
+
}
|
|
323
|
+
|
|
324
|
+
/** True only when the spell's own travel hook says it landed; the pool lands its own shots. */
|
|
325
|
+
#advanceTravel(cast: ICast, dt: number): boolean {
|
|
326
|
+
const spell = cast.spell;
|
|
327
|
+
if (cast.shape !== "projectile") {
|
|
328
|
+
if (!cast.held && cast.t >= cast.durations.travel) this.#enter(cast, "impact");
|
|
329
|
+
return false;
|
|
330
|
+
}
|
|
331
|
+
// A spell with a `travel` hook owns its own integration (a homing ball, a lobbed arc); the pool
|
|
332
|
+
// then only steps the rest of the record and waits to be told it landed.
|
|
333
|
+
if (spell.travel !== undefined) return spell.travel(cast, dt) === true;
|
|
334
|
+
cast.pos.addScaledVector(cast.vel, dt);
|
|
335
|
+
cast.travelled += cast.vel.length() * dt;
|
|
336
|
+
const radius = cast.radius;
|
|
337
|
+
const past = scratch.subVectors(cast.to, cast.pos).dot(cast.dir) <= 0;
|
|
338
|
+
const groundAt = this.#groundAt;
|
|
339
|
+
// A floor the game cannot answer for is not a floor: a NaN would make `buried` false forever and
|
|
340
|
+
// the cast would fly until its travel time ran out.
|
|
341
|
+
const floor =
|
|
342
|
+
groundAt === undefined ? Number.NEGATIVE_INFINITY : groundAt(cast.pos.x, cast.pos.z);
|
|
343
|
+
const buried = Number.isFinite(floor) && cast.travelled > 1 && cast.pos.y < floor + radius;
|
|
344
|
+
// A ball that has passed its target lands on it, however late the frame notices. Only a spell
|
|
345
|
+
// that never reached the target spends its whole travel time and stops where it is.
|
|
346
|
+
if (past) {
|
|
347
|
+
cast.pos.copy(cast.to);
|
|
348
|
+
this.#enter(cast, "impact");
|
|
349
|
+
return false;
|
|
350
|
+
}
|
|
351
|
+
if (buried || cast.t >= cast.durations.travel) this.#enter(cast, "impact");
|
|
352
|
+
return false;
|
|
353
|
+
}
|
|
354
|
+
|
|
355
|
+
#enter(cast: ICast, phase: CastPhase): void {
|
|
356
|
+
if (!PHASES.includes(phase)) throw new RangeError(`unknown cast phase ${phase}`);
|
|
357
|
+
cast.phase = phase;
|
|
358
|
+
cast.t = 0;
|
|
359
|
+
cast.spell.phase?.(cast, phase);
|
|
360
|
+
}
|
|
361
|
+
}
|
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Spells: a timeline that changes the world it lands in.
|
|
3
|
+
*
|
|
4
|
+
* A spell is not an emitter. It charges, releases, travels, impacts and lingers, and each beat
|
|
5
|
+
* drives several systems at once. This subpath holds that machinery.
|
|
6
|
+
*
|
|
7
|
+
* Kept off the main entry on purpose: `@threenative/core` declares `sideEffects: false` and this is
|
|
8
|
+
* its own module, so a game that never casts a spell ships none of it.
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* Step a spell's timeline: charge, release, travel, impact, linger, done.
|
|
13
|
+
* @situation a fireball or a lightning bolt that charges, flies, lands and lingers
|
|
14
|
+
* @situation several spells mid-flight, with no allocation per cast
|
|
15
|
+
* @constraint the pool is fixed and recycles the cast alive longest; it never grows
|
|
16
|
+
* @constraint a ball that has passed its target lands on the target, however late the frame notices
|
|
17
|
+
* @override timing, shape, speed and radius come from the spell; a cast may override shape and seed
|
|
18
|
+
* @example const casts = new CastPool(world);
|
|
19
|
+
* casts.cast(fireball, target, { from: hand });
|
|
20
|
+
* casts.update(dt);
|
|
21
|
+
*/
|
|
22
|
+
export { CastPool } from "./cast-pool.js";
|
|
23
|
+
export type {
|
|
24
|
+
CastPhase,
|
|
25
|
+
CastShape,
|
|
26
|
+
ICast,
|
|
27
|
+
ICastEnvironment,
|
|
28
|
+
ICastOptions,
|
|
29
|
+
ICastTiming,
|
|
30
|
+
ISpell,
|
|
31
|
+
} from "./cast-pool.js";
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* The marks a spell leaves on the floor: heat, char, wet, frost, crack and glow.
|
|
35
|
+
* @situation a fireball impact that leaves a scorch and fades over time
|
|
36
|
+
* @situation ice that melts where lightning spread, or a lava geyser's crack
|
|
37
|
+
* @constraint it draws nothing; the game decides what a mark looks like
|
|
38
|
+
* @constraint the patch is finite and every channel decays on its own half-life
|
|
39
|
+
* @override halfLife, resolution and size tune the patch; pattern, radius, seed and angle set each mark
|
|
40
|
+
* @example field.splat({ heat: 1, char: 0.6, radius: 2.5, x: hit.x, z: hit.z });
|
|
41
|
+
* field.update(dt);
|
|
42
|
+
*/
|
|
43
|
+
export { REACTION_CHANNELS, ReactionField } from "./reaction-field.js";
|
|
44
|
+
export type {
|
|
45
|
+
IReactionDirty,
|
|
46
|
+
IReactionFieldOptions,
|
|
47
|
+
IReactionSplat,
|
|
48
|
+
ReactionChannel,
|
|
49
|
+
ReactionPattern,
|
|
50
|
+
} from "./reaction-field.js";
|
|
51
|
+
|
|
52
|
+
/**
|
|
53
|
+
* A fixed pool of spell lights, created once at zero intensity.
|
|
54
|
+
* @situation a spell impact that glows without changing the light count
|
|
55
|
+
* @situation a charge glow or a falling meteor lighting what it passes
|
|
56
|
+
* @constraint the whole pool exists before the first cast; a cast changes intensity, never the list
|
|
57
|
+
* @constraint flash returns undefined when the pool is busy; a spell carries on without one
|
|
58
|
+
* @override count is the pool size; each flash supplies position, colour, intensity, range and seconds
|
|
59
|
+
* @example lights.flash({ x, y, z, color, intensity: 40, range: 12, seconds: 0.35 });
|
|
60
|
+
*/
|
|
61
|
+
export { SpellLights } from "./spell-lights.js";
|
|
62
|
+
export type { ISpellLightFlash, ISpellLightsOptions } from "./spell-lights.js";
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* Everything a spell may touch: the scene, the floor, the light pool, the surface field, one shake
|
|
66
|
+
* and one flash limiter.
|
|
67
|
+
* @situation cast an engine spell without passing a scene into every call
|
|
68
|
+
* @situation honour an accessibility setting that limits flashing
|
|
69
|
+
* @constraint damage, mana, cooldowns and who the target is stay in the game
|
|
70
|
+
* @constraint with reducedFlashes on, a fourth flash inside one second is refused, never dimmed
|
|
71
|
+
* @override groundAt, castSlots, lightCount, reaction, shake and reducedFlashes are named options
|
|
72
|
+
* @example const world = new SpellWorld({ scene, groundAt });
|
|
73
|
+
* const casts = new CastPool(world);
|
|
74
|
+
*/
|
|
75
|
+
export { SpellWorld } from "./spell-world.js";
|
|
76
|
+
export type { ISpellWorldOptions, ISpellWorldShakeOptions } from "./spell-world.js";
|
|
77
|
+
|
|
78
|
+
/**
|
|
79
|
+
* A ball of fire that charges, crosses the room and leaves the floor burning.
|
|
80
|
+
* @situation a fireball spell the player casts at an enemy
|
|
81
|
+
* @situation a burning projectile that explodes and scorches the ground
|
|
82
|
+
* @situation a wizard's fire attack with a wind-up, a flight and an aftermath
|
|
83
|
+
* @situation make a fireball
|
|
84
|
+
* @constraint every colour, size, count and timing is a named override on the call
|
|
85
|
+
* @constraint the first cast costs what the hundredth does: nothing is built at cast time
|
|
86
|
+
* @override core, highlight, speed, charge, impact, linger, radius, burst, trail, lingerBurst, light, shake, scorch
|
|
87
|
+
* @example const fireball = createFireball(world);
|
|
88
|
+
* casts.cast(fireball, target);
|
|
89
|
+
*/
|
|
90
|
+
export { createFireball, type IFireSpellOverrides } from "./spells.js";
|
|
91
|
+
|
|
92
|
+
/**
|
|
93
|
+
* A bolt out of the sky: it charges, strikes the point instantly, and the ground remembers it.
|
|
94
|
+
* @situation a lightning strike spell that hits a point immediately
|
|
95
|
+
* @situation a thunderbolt with a wind-up and a burnt mark where it lands
|
|
96
|
+
* @situation make a lightning spell
|
|
97
|
+
* @constraint every colour, size, count and timing is a named override on the call
|
|
98
|
+
* @override core, highlight, charge, impact, linger, radius, light, shake, scorch
|
|
99
|
+
* @example const bolt = createThunderstrike(world);
|
|
100
|
+
* casts.cast(bolt, target);
|
|
101
|
+
*/
|
|
102
|
+
export { createThunderstrike } from "./spells.js";
|
|
103
|
+
|
|
104
|
+
/**
|
|
105
|
+
* A shard of ice that flies flat and fast, and freezes the ground it breaks on.
|
|
106
|
+
* @situation an ice spike spell that flies at a target and shatters
|
|
107
|
+
* @situation a freezing projectile that leaves frost on the floor
|
|
108
|
+
* @situation make an ice spell
|
|
109
|
+
* @constraint every colour, size, count and timing is a named override on the call
|
|
110
|
+
* @override core, highlight, speed, charge, impact, linger, radius, burst, trail, light
|
|
111
|
+
* @example const spike = createGlacialSpike(world);
|
|
112
|
+
* casts.cast(spike, target);
|
|
113
|
+
*/
|
|
114
|
+
export { createGlacialSpike } from "./spells.js";
|
|
115
|
+
|
|
116
|
+
/**
|
|
117
|
+
* A volley of arcane missiles: fast, precise, and each one pops on arrival.
|
|
118
|
+
* @situation an arcane missile spell that fires projectiles at a target
|
|
119
|
+
* @situation a magic barrage a mage class spams
|
|
120
|
+
* @situation a magic missile spell
|
|
121
|
+
* @situation make an arcane bolt spell
|
|
122
|
+
* @constraint every colour, size, count and timing is a named override on the call
|
|
123
|
+
* @override core, highlight, speed, charge, impact, linger, radius, burst, light
|
|
124
|
+
* @example const barrage = createArcaneBarrage(world);
|
|
125
|
+
* casts.cast(barrage, target);
|
|
126
|
+
*/
|
|
127
|
+
export { createArcaneBarrage } from "./spells.js";
|
|
128
|
+
|
|
129
|
+
/**
|
|
130
|
+
* A ward around the caster: it forms, holds, and breaks outward when it expires.
|
|
131
|
+
* @situation a shield spell a player casts on themselves
|
|
132
|
+
* @situation a magic barrier that forms around the caster
|
|
133
|
+
* @situation make a protective bubble spell
|
|
134
|
+
* @constraint every colour, size, count and timing is a named override on the call
|
|
135
|
+
* @override core, highlight, charge, impact, linger, radius, light
|
|
136
|
+
* @example const aegis = createAegis(world);
|
|
137
|
+
* casts.cast(aegis, world.focus);
|
|
138
|
+
*/
|
|
139
|
+
export { createAegis } from "./spells.js";
|
|
140
|
+
|
|
141
|
+
/**
|
|
142
|
+
* A pillar of fire that erupts where it lands and keeps burning.
|
|
143
|
+
* @situation a fire area spell that erupts at a point and burns there
|
|
144
|
+
* @situation an inferno column a boss drops on the arena
|
|
145
|
+
* @situation make a sustained fire area spell
|
|
146
|
+
* @constraint every colour, size, count and timing is a named override on the call
|
|
147
|
+
* @override core, highlight, charge, impact, linger, radius, burst, trail, light, shake, scorch
|
|
148
|
+
* @example const inferno = createInferno(world);
|
|
149
|
+
* casts.cast(inferno, target);
|
|
150
|
+
*/
|
|
151
|
+
export { createInferno } from "./spells.js";
|
|
152
|
+
|
|
153
|
+
/**
|
|
154
|
+
* Build a spell from a recipe: four beats, a tint, and the numbers between them.
|
|
155
|
+
* @situation author a spell the catalog does not cover, out of the same beats
|
|
156
|
+
* @constraint read the world through SpellWorld only, so a game can swap the scene and the floor
|
|
157
|
+
* @example const spell = createSpell(world, recipe);
|
|
158
|
+
*/
|
|
159
|
+
export {
|
|
160
|
+
createSpell,
|
|
161
|
+
type ISpellEmitter,
|
|
162
|
+
type ISpellImpact,
|
|
163
|
+
type ISpellRecipe,
|
|
164
|
+
type ISpellTint,
|
|
165
|
+
} from "./spell.js";
|
|
166
|
+
/**
|
|
167
|
+
* Tune what a particle kind does, as data rather than a shader.
|
|
168
|
+
* @situation retune a spell's particles at run time from a settings screen
|
|
169
|
+
* @situation change how long, how fast or how heavy a kind of particle is without a new pipeline
|
|
170
|
+
* @constraint set writes uniforms; no kernel, material or pipeline is rebuilt
|
|
171
|
+
* @constraint a table knows only the kinds it was asked for, so an unused kind costs nothing
|
|
172
|
+
* @override lifetime, size, speed, cone, gravity, drag, buoyancy, alpha, colour and highlight
|
|
173
|
+
* @example const kinds = new ParticleKindTable(["flame", "smoke"]);
|
|
174
|
+
* kinds.set("flame", { lifetime: [0.3, 0.6], colour: [0.4, 0.8, 1] });
|
|
175
|
+
*/
|
|
176
|
+
export { type IParticleKindValues, ParticleKindTable } from "../particle-kinds.js";
|
|
177
|
+
export type { ParticleKindName } from "../particle-kinds.js";
|