@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.
Files changed (157) hide show
  1. package/capabilities.json +1096 -26
  2. package/dist/camera-shake-CZKOfGn4.d.ts +46 -0
  3. package/dist/{canvas-layer-vCtanIeB.d.ts → canvas-layer-CWuFRT7G.d.ts} +1 -1
  4. package/dist/chunk-2Z44XSI2.js +35 -0
  5. package/dist/chunk-5O73CDMR.js +1849 -0
  6. package/dist/chunk-6KLNISRJ.js +153 -0
  7. package/dist/chunk-7UUT3TY5.js +133 -0
  8. package/dist/chunk-CFGTPFUH.js +231 -0
  9. package/dist/chunk-DBELTTTM.js +615 -0
  10. package/dist/chunk-GMHATRPW.js +7701 -0
  11. package/dist/chunk-GXY7B3JG.js +46 -0
  12. package/dist/chunk-KIRUKTBQ.js +187 -0
  13. package/dist/chunk-N5LRP4BR.js +220 -0
  14. package/dist/chunk-OKXUCASC.js +2238 -0
  15. package/dist/chunk-QWJEMUUT.js +94 -0
  16. package/dist/chunk-VAZM36TV.js +497 -0
  17. package/dist/{game-DzMcitDO.d.ts → game-D7pAzZUY.d.ts} +15 -3
  18. package/dist/hot.d.ts +3 -3
  19. package/dist/hot.js +2 -46
  20. package/dist/index.d.ts +329 -302
  21. package/dist/index.js +10566 -22552
  22. package/dist/{model-lod-CTpZ6imz.d.ts → model-lod-B6BMqS1r.d.ts} +33 -3
  23. package/dist/playtest.d.ts +3 -3
  24. package/dist/playtest.js +24 -75
  25. package/dist/react-css.js +1 -215
  26. package/dist/react.d.ts +2 -2
  27. package/dist/{renderer-rZm0hVqq.d.ts → renderer-DvFVoAgj.d.ts} +13 -4
  28. package/dist/spells/index.d.ts +643 -0
  29. package/dist/spells/index.js +1558 -0
  30. package/dist/spells/ultra/index.d.ts +1600 -0
  31. package/dist/spells/ultra/index.js +6804 -0
  32. package/dist/terrain-jobs-worker.js +1 -123
  33. package/dist/two-sided-foliage-W523J3UM.js +1 -0
  34. package/dist/ui-layer.js +5 -384
  35. package/dist/worker.js +4 -41
  36. package/dist/world.d.ts +725 -259
  37. package/dist/world.js +16714 -18284
  38. package/mcp/animation-server.mjs +1 -1
  39. package/mcp/animation.mjs +2 -3
  40. package/mcp/engine-server.mjs +142 -47
  41. package/mcp/servers.mjs +9 -2
  42. package/mcp/terrain.mjs +8 -0
  43. package/package.json +14 -6
  44. package/patches/three@0.187.0-prd269-upgrade.patch +2102 -0
  45. package/patches/three@0.187.0.patch +2004 -407
  46. package/src/assets.ts +9 -2
  47. package/src/card-lod.ts +152 -0
  48. package/src/compressed-texture-preparation.ts +1008 -0
  49. package/src/frame-budget.ts +31 -20
  50. package/src/game-dev-tools.ts +93 -0
  51. package/src/game-frame-loop.ts +995 -0
  52. package/src/game-renderer-metrics.ts +77 -0
  53. package/src/game-startup.ts +1001 -0
  54. package/src/game-validate.ts +70 -0
  55. package/src/game.ts +253 -1935
  56. package/src/index.ts +27 -2
  57. package/src/launch-diagnostics.ts +22 -12
  58. package/src/look/ao-admission.ts +24 -0
  59. package/src/look/filmic-tone-mapping.ts +15 -13
  60. package/src/look/look-diagnostics.ts +3 -3
  61. package/src/look/quality.ts +10 -5
  62. package/src/look/world-environment.ts +76 -9
  63. package/src/loop.ts +29 -0
  64. package/src/model-lod.ts +42 -3
  65. package/src/particle-kinds.ts +515 -0
  66. package/src/picking.ts +17 -3
  67. package/src/playtest.ts +27 -1
  68. package/src/projection-apply.ts +4 -1
  69. package/src/projection-plan.ts +9 -6
  70. package/src/render/mesh-pool.ts +1 -1
  71. package/src/render/resolution-subrect.ts +2 -0
  72. package/src/render/rough-diffuse.ts +46 -12
  73. package/src/render/soft-shadow.ts +27 -12
  74. package/src/render/virtual-shadow-adaptive.ts +55 -0
  75. package/src/render/virtual-shadow-casters.ts +175 -0
  76. package/src/render/virtual-shadow-layers.ts +76 -0
  77. package/src/render/virtual-shadow-level.ts +224 -0
  78. package/src/render/virtual-shadow-markers.ts +193 -0
  79. package/src/render/virtual-shadow-options.ts +370 -0
  80. package/src/render/virtual-shadow-pages.ts +5 -0
  81. package/src/render/virtual-shadow.ts +213 -992
  82. package/src/render/world-impostor-surface.ts +293 -34
  83. package/src/render-pass-budget.ts +34 -7
  84. package/src/renderProjection.ts +22 -0
  85. package/src/renderer.ts +92 -37
  86. package/src/snow-field.ts +1 -1
  87. package/src/spells/cast-pool.ts +361 -0
  88. package/src/spells/index.ts +177 -0
  89. package/src/spells/mechanisms.ts +295 -0
  90. package/src/spells/reaction-field.ts +415 -0
  91. package/src/spells/spell-lights.ts +139 -0
  92. package/src/spells/spell-world.ts +187 -0
  93. package/src/spells/spell.ts +397 -0
  94. package/src/spells/spells.ts +283 -0
  95. package/src/spells/ultra/engine/camera.ts +184 -0
  96. package/src/spells/ultra/engine/quality.ts +96 -0
  97. package/src/spells/ultra/index.ts +52 -0
  98. package/src/spells/ultra/main.ts +305 -0
  99. package/src/spells/ultra/scene/arenaMaterial.ts +325 -0
  100. package/src/spells/ultra/spells/cast.ts +233 -0
  101. package/src/spells/ultra/spells/fire.ts +1267 -0
  102. package/src/spells/ultra/vfx/FluidVolume.ts +816 -0
  103. package/src/spells/ultra/vfx/FluidVolume.tsl.ts +855 -0
  104. package/src/spells/ultra/vfx/FxTarget.ts +61 -0
  105. package/src/spells/ultra/vfx/GroundField.ts +1399 -0
  106. package/src/spells/ultra/vfx/Particles.ts +1475 -0
  107. package/src/spells/ultra/vfx/Ribbons.ts +645 -0
  108. package/src/spells/ultra/vfx/Shockwaves.ts +286 -0
  109. package/src/spells/ultra/vfx/Volumes.ts +489 -0
  110. package/src/spells/ultra/vfx/common.ts +1195 -0
  111. package/src/spells/ultra/vfx/noise.ts +441 -0
  112. package/src/startup-readiness.ts +128 -34
  113. package/src/version.ts +1 -1
  114. package/src/warmup.ts +56 -8
  115. package/src/water-surface.ts +9 -3
  116. package/src/world-bundle-safety.ts +401 -0
  117. package/src/world-cell-batches.ts +1216 -0
  118. package/src/world-cell-chunks.ts +1132 -0
  119. package/src/world-cell-data.ts +995 -0
  120. package/src/world-cell-impostors.ts +1449 -0
  121. package/src/world-cell-lod-bias.ts +151 -0
  122. package/src/world-cell-models.ts +1074 -0
  123. package/src/world-cell-options.ts +189 -0
  124. package/src/world-cell-placements.ts +694 -0
  125. package/src/world-cell-prewarm.ts +557 -0
  126. package/src/world-cell-readiness.ts +357 -0
  127. package/src/world-cell-render-bundles.ts +459 -0
  128. package/src/world-cell-render-gpu-dress.ts +714 -0
  129. package/src/world-cell-render-main-cull.ts +484 -0
  130. package/src/world-cell-render-shadow-claims.ts +198 -0
  131. package/src/world-cell-render-util.ts +246 -0
  132. package/src/world-cell-render.ts +1493 -0
  133. package/src/world-cell-residency.ts +745 -0
  134. package/src/world-cells.ts +1318 -10418
  135. package/src/world-chunk-shadow.ts +308 -0
  136. package/src/world-collar.ts +315 -0
  137. package/src/world-gpu-flags.ts +163 -0
  138. package/src/world-gpu-readback.ts +881 -0
  139. package/src/world-gpu-reference.ts +510 -0
  140. package/src/world-gpu-scene.ts +214 -2264
  141. package/src/world-gpu-shadow.ts +190 -0
  142. package/src/world-gpu-types.ts +381 -0
  143. package/src/world-gpu-validation.ts +518 -0
  144. package/src/world-heightfield.ts +802 -0
  145. package/src/world-load-limiter.ts +106 -0
  146. package/src/world-noise.ts +241 -0
  147. package/src/world-package.ts +42 -0
  148. package/src/world-region.ts +1 -1
  149. package/src/world-terrain-splat.ts +365 -149
  150. package/src/world-tile-budget.ts +256 -0
  151. package/src/world-tile-geometry.ts +469 -0
  152. package/src/world-tile-lod.ts +408 -0
  153. package/src/world-tile-observation.ts +566 -0
  154. package/src/world-tile-stitch.ts +166 -0
  155. package/src/world-tiles.ts +170 -1745
  156. package/src/world-water-bodies.ts +359 -0
  157. package/src/world.ts +35 -741
@@ -0,0 +1,643 @@
1
+ import { Vector3, Color, Object3D, PointLight, Scene, Camera, Vector2, Vector4 } from 'three';
2
+ import { C as CameraShakeCurve, a as CameraShake } from '../camera-shake-CZKOfGn4.js';
3
+ import { UniformNode, Color as Color$1 } from 'three/webgpu';
4
+
5
+ /**
6
+ * A spell is not an effect: it is a timeline. Charge, release, travel, impact and linger drive
7
+ * several systems in turn, and the sequence is the same every cast, so the engine owns the clock
8
+ * and the spell only answers "what does this phase look like".
9
+ *
10
+ * This is the upstream Ultra Elements `cast.js` phase machine, with the arena removed: a cast
11
+ * never asks where the floor is. It integrates a projectile in a straight line, hands the spell
12
+ * every frame to steer, and retires each record back into a fixed pool. Nothing is allocated per
13
+ * cast, so a game that casts on every frame at 60 Hz allocates nothing at all.
14
+ */
15
+
16
+ /** The beats of a spell, in order. `release` is instantaneous and never observed by a game. */
17
+ type CastPhase = "charge" | "travel" | "impact" | "linger" | "done";
18
+ /**
19
+ * How a spell reaches its target.
20
+ * - `projectile` integrates a velocity through `travel`, and lands on the target or on `groundAt`.
21
+ * - `beam` holds at the target while `held`, then lands.
22
+ * - `strike`, `area` and `self` skip travel and land on `release`.
23
+ */
24
+ type CastShape = "projectile" | "beam" | "strike" | "area" | "self";
25
+ interface ICastTiming {
26
+ /** Seconds of wind-up. Defaults to 0.5. */
27
+ readonly charge?: number;
28
+ /** Longest seconds of travel before the spell lands anyway. Defaults to 4. */
29
+ readonly travel?: number;
30
+ /** Seconds the impact reads on screen. Defaults to 0.2. */
31
+ readonly impact?: number;
32
+ /** Seconds the aftermath stays. Defaults to 2. */
33
+ readonly linger?: number;
34
+ }
35
+ /** One cast's worth of reusable state. The spell owns what goes in `data`. */
36
+ interface ICast {
37
+ /** Pool slot, stable for the pool's lifetime: a spell may key per-slot state by it. */
38
+ readonly index: number;
39
+ spell: ISpell;
40
+ shape: CastShape;
41
+ phase: CastPhase;
42
+ /** Seconds inside the current phase, reset on every `enter`. */
43
+ t: number;
44
+ /** Seconds since the cast started. The pool recycles the largest `age` when it is full. */
45
+ age: number;
46
+ seed: number;
47
+ /** Where the spell was released from. */
48
+ readonly from: Vector3;
49
+ /** The target the game asked for. */
50
+ readonly to: Vector3;
51
+ /** Current world position: `from` while charging, integrated through travel. */
52
+ readonly pos: Vector3;
53
+ readonly vel: Vector3;
54
+ /** Unit vector `from` -> `to`. */
55
+ readonly dir: Vector3;
56
+ /** A held beam stays in `travel` until the game releases it. */
57
+ held: boolean;
58
+ /** Metres travelled. A spell may read it, the pool only accumulates it. */
59
+ travelled: number;
60
+ /** Impact radius in metres, validated once when the cast started. */
61
+ radius: number;
62
+ readonly durations: {
63
+ charge: number;
64
+ impact: number;
65
+ linger: number;
66
+ travel: number;
67
+ };
68
+ /** Spell-owned per-slot scratch, preallocated with the record and reset by the spell at charge. */
69
+ readonly data: Record<string, unknown>;
70
+ }
71
+ /**
72
+ * A spell as the pool sees it. Every factory on `@threenative/core/spells` returns one of these:
73
+ * it is the only shape the pool drives, and the spell reads the world through `SpellWorld`.
74
+ */
75
+ interface ISpell {
76
+ /** The factory name without its `create` prefix, lowercase: `fireball`. */
77
+ readonly name: string;
78
+ /** How the spell reaches its target. Defaults to `projectile`. */
79
+ readonly shape?: CastShape;
80
+ /** Per-spell beat lengths. Missing beats take the pool defaults. */
81
+ readonly timing?: ICastTiming;
82
+ /** Metres per second for a projectile. Defaults to 15. */
83
+ readonly speed?: number;
84
+ /** Metres of collision radius at impact. Defaults to 0.3. */
85
+ readonly radius?: number;
86
+ /** Called on each beat change, including `done`. */
87
+ readonly phase?: (cast: ICast, phase: CastPhase) => void;
88
+ /**
89
+ * Owns the travel step for a spell that steers or arcs. The pool then skips its own straight-line
90
+ * integration and floor test for this cast; return true to land it. A spell with no `travel` hook
91
+ * is integrated by the pool and cannot miss.
92
+ */
93
+ readonly travel?: (cast: ICast, dt: number) => boolean | undefined;
94
+ /** Called once per frame while the cast is alive, in every phase. */
95
+ readonly update?: (cast: ICast, dt: number) => void;
96
+ }
97
+ interface ICastOptions {
98
+ /** World point to travel from. Defaults to the world's `focus`. */
99
+ readonly from?: Vector3;
100
+ /** Hold a beam open past its sustain time. Defaults to false. */
101
+ readonly held?: boolean;
102
+ /** Override the generated seed, so a replay reproduces the same scatter. */
103
+ readonly seed?: number;
104
+ /** Override `spell.shape`, for a spell that carries several forms. */
105
+ readonly shape?: CastShape;
106
+ }
107
+ /** What a pool needs from the world: the floor, and how many records to keep. */
108
+ interface ICastEnvironment {
109
+ /** Floor height under a point, so a projectile lands on a hill and not at y = 0. */
110
+ readonly groundAt?: (x: number, z: number) => number;
111
+ /** Records in the pool. Defaults to 16. */
112
+ readonly castSlots?: number;
113
+ /**
114
+ * Where a cast with no `from` starts: the caster's hand. `SpellWorld` supplies its own `focus`,
115
+ * so a game that moves that point gets it here with no extra wiring.
116
+ */
117
+ readonly focus?: Vector3;
118
+ }
119
+ /**
120
+ * Drive spell timelines from a fixed pool of records.
121
+ *
122
+ * The pool is full at capacity and never grows: a full pool recycles the record that has been alive
123
+ * longest, which is the cast the player has already stopped watching. Every record keeps its
124
+ * identity across casts, so a spell's per-slot state and any pooled mesh it binds stay warm.
125
+ */
126
+ declare class CastPool {
127
+ #private;
128
+ /** Every slot, alive or not. Read `phase !== "done"` for the live ones. */
129
+ readonly casts: readonly ICast[];
130
+ constructor(world?: ICastEnvironment);
131
+ /** The newest live cast. What a HUD reads for the phase strip. */
132
+ get active(): ICast | undefined;
133
+ get count(): number;
134
+ /** Start a spell. Returns the record, which the caller may read but the pool advances. */
135
+ cast(spell: ISpell, to: Vector3, options?: ICastOptions): ICast;
136
+ /** End every held beam. A game calls this when the button comes up. */
137
+ releaseHeld(): void;
138
+ /** Retire every live cast without running linger. */
139
+ clear(): void;
140
+ /**
141
+ * Advance every live cast. A projectile lands on the target, on the world's floor, or when its
142
+ * travel time runs out, whichever comes first.
143
+ */
144
+ update(dt: number): void;
145
+ }
146
+
147
+ /**
148
+ * Where the world keeps what a spell did to it.
149
+ *
150
+ * A fireball that only draws a fireball has not landed anywhere. Upstream keeps this in
151
+ * `GroundField.js`: every spell paints a patch of floor with heat, char, water, frost, a crack or a
152
+ * residual glow, and the floor's own shader reads those channels back. The arena SDF is what makes
153
+ * that file impossible to reuse, so this is the same idea with the arena removed — the game says
154
+ * where the floor is, and the game's material decides what heat looks like.
155
+ *
156
+ * Same contract as `RippleField`: it draws nothing, owns no mesh and no colour. It reports values,
157
+ * the game reads them, and a game that never looks at a channel pays a float array for it and
158
+ * nothing else.
159
+ *
160
+ * The solve is a CPU grid because a game reads it for combos: "cast ice on wet floor" has to be a
161
+ * branch, not a GPU readback that arrives two frames late.
162
+ */
163
+ /** The channels a spell writes. Each is independent and decays on its own clock. */
164
+ declare const REACTION_CHANNELS: readonly ["heat", "char", "wet", "frost", "crack", "glow"];
165
+ type ReactionChannel = (typeof REACTION_CHANNELS)[number];
166
+ /** Where a splat landed and how much of it the spell laid down. Every channel is 0..1. */
167
+ interface IReactionSplat {
168
+ readonly x: number;
169
+ readonly z: number;
170
+ /** Metres. The Gaussian reaches about three of these. */
171
+ readonly radius: number;
172
+ /** `radial` fades from the centre; `ring` leaves a rim; `streak` is stretched along `angle`. */
173
+ readonly pattern?: ReactionPattern;
174
+ /** Radians. Turns the `streak` axis, and is ignored by every other pattern. */
175
+ readonly angle?: number;
176
+ /** Pattern seed, so two impacts of the same spell are not the same mark. */
177
+ readonly seed?: number;
178
+ readonly heat?: number;
179
+ readonly char?: number;
180
+ readonly wet?: number;
181
+ readonly frost?: number;
182
+ readonly crack?: number;
183
+ readonly glow?: number;
184
+ }
185
+ type ReactionPattern = "radial" | "ring" | "streak";
186
+ /** A whole-cell rectangle of changed cells, in grid indices. */
187
+ interface IReactionDirty {
188
+ readonly x: number;
189
+ readonly z: number;
190
+ readonly width: number;
191
+ readonly height: number;
192
+ }
193
+ interface IReactionFieldOptions {
194
+ /** Cells per side. Cost is quadratic in this; 96 over a 120 m patch is ~1.25 m per cell. */
195
+ readonly resolution?: number;
196
+ /** Width of the patch in metres. */
197
+ readonly size?: number;
198
+ /** Per-channel seconds for a full-strength value to halve. `char` is the slow one. */
199
+ readonly halfLife?: Partial<Readonly<Record<ReactionChannel, number>>>;
200
+ }
201
+ /**
202
+ * A patch of world that spells leave marks on.
203
+ *
204
+ * One float array per channel, decayed on `update`, written by `splat`. `consumeDirty` reports the
205
+ * cells that changed since the last call, so a material uploads a strip instead of the whole grid.
206
+ */
207
+ declare class ReactionField {
208
+ #private;
209
+ readonly resolution: number;
210
+ readonly size: number;
211
+ readonly dx: number;
212
+ /** Patch centre in world metres. */
213
+ centerX: number;
214
+ centerZ: number;
215
+ /** Bumped whenever any cell changes, so an upload can skip an unchanged frame. */
216
+ version: number;
217
+ constructor(options?: IReactionFieldOptions);
218
+ /** The live values of one channel, row-major from the patch's -x/-z corner. Read-only to a game. */
219
+ data(channel: ReactionChannel): Float32Array;
220
+ /** True while every cell of every channel is exactly zero. */
221
+ get empty(): boolean;
222
+ /** True while the point is inside the patch, `margin` metres in from its rim. */
223
+ contains(x: number, z: number, margin?: number): boolean;
224
+ /** Nearest-neighbour read at a world point, 0 outside the patch. Cheap enough for a combo check. */
225
+ sample(channel: ReactionChannel, x: number, z: number): number;
226
+ /** Strongest channel at a point, for a game that only asks "is anything happening here". */
227
+ strongest(x: number, z: number): ReactionChannel | undefined;
228
+ /**
229
+ * Lay a mark on the patch. Every channel is additive and saturates at 1, so two fireballs on the
230
+ * same cell burn hotter than one but never past the top of the range. Off-patch splats return
231
+ * false and change nothing.
232
+ */
233
+ splat(splat: IReactionSplat): boolean;
234
+ /** Forget everything now, and report one last full-patch upload. */
235
+ clear(): void;
236
+ /** Move the patch with the action. Newly exposed cells arrive clean. */
237
+ recenter(x: number, z: number): void;
238
+ /** Decay every channel on its own half-life. Time passing on a clean patch changes no cell. */
239
+ update(dt: number): void;
240
+ /**
241
+ * Hand back the cells that changed since the last call, and forget them.
242
+ * `undefined` means nothing changed, so an upload can be skipped whole.
243
+ */
244
+ consumeDirty(): IReactionDirty | undefined;
245
+ }
246
+
247
+ /**
248
+ * The lights a spell throws, without the light count ever moving.
249
+ *
250
+ * A point light added at cast time is a shader recompile and a lighting-state change in the middle
251
+ * of a fight. This pool creates its lights once, parks every one of them at zero intensity, and
252
+ * hands them out for the duration of an impact. A cast therefore changes what the lights do and
253
+ * never what they are. Niagara submits spell-sized lights as plain simple lights for the same
254
+ * reason (UE 5.8.3: Engine/Plugins/FX/Niagara/Source/Niagara/Private/NiagaraRendererLights.cpp:100,
255
+ * :201).
256
+ */
257
+
258
+ interface ISpellLightsOptions {
259
+ /** Where the lights are added. A scene, or any object that outlives the casts. */
260
+ readonly parent: Object3D;
261
+ /** Lights in the pool. Defaults to 4: a charge glow, an impact flash, and two in flight. */
262
+ readonly count?: number;
263
+ /** Lights are cheaper than shadows for a flash; a spell never casts one. */
264
+ readonly shadows?: boolean;
265
+ }
266
+ /** One light, and the game-owned look it was given. */
267
+ interface ISpellLightFlash {
268
+ /** World position of the flash. */
269
+ readonly x: number;
270
+ readonly y: number;
271
+ readonly z: number;
272
+ readonly color: Color;
273
+ /** Peak intensity in candela. */
274
+ readonly intensity: number;
275
+ /** Metres the light reaches. */
276
+ readonly range: number;
277
+ /** Seconds the flash takes to decay to zero. */
278
+ readonly seconds: number;
279
+ }
280
+ /**
281
+ * A fixed pool of spell lights.
282
+ *
283
+ * `flash` returns false when every light is busy: a spell reports that and carries on without
284
+ * one rather than growing the pool. Intensity decays linearly to zero, which reads as a flash
285
+ * rather than a lamp fading, and Update runs on the same fixed delta as the casts.
286
+ */
287
+ declare class SpellLights {
288
+ #private;
289
+ readonly lights: readonly PointLight[];
290
+ constructor(options: ISpellLightsOptions);
291
+ /** True while at least one light is lit, so a game can skip its own light bookkeeping. */
292
+ get active(): boolean;
293
+ /** The light this flash took, or undefined when the pool was full. */
294
+ flash(request: ISpellLightFlash): PointLight | undefined;
295
+ /** Put every light out now, without waiting for its decay. */
296
+ clear(): void;
297
+ update(dt: number): void;
298
+ }
299
+
300
+ /**
301
+ * The world a spell lands in.
302
+ *
303
+ * A spell that reads `scene`, `camera` and a floor function directly has to be rewritten for every
304
+ * game, and the upstream files show what happens when it is: 34 of them read the arena SDF, so the
305
+ * arena is load-bearing and a game cannot replace it. Everything a spell needs therefore arrives
306
+ * through here — the scene to add its pooled objects to, the floor to land on, the light pool that
307
+ * never changes size, the surface field it paints, one shake and one flash limiter.
308
+ *
309
+ * Damage, mana, cooldowns and who the target actually is stay in the game. `SpellWorld` knows
310
+ * nothing about them, and a game that wants a spell to hurt something reads the cast's `to` point
311
+ * from its own update and decides.
312
+ */
313
+
314
+ interface ISpellWorldShakeOptions {
315
+ /** Metres. Defaults to 0.12, which reads as a thump and not as a broken camera. */
316
+ readonly amplitude?: number;
317
+ /** Radians. Defaults to 0.012. */
318
+ readonly rotationAmplitude?: number;
319
+ /** Cycles per second. Defaults to 11. */
320
+ readonly frequency?: number;
321
+ /** Exponential decay per second. Defaults to 5. */
322
+ readonly decay?: number;
323
+ readonly curve?: CameraShakeCurve;
324
+ }
325
+ interface ISpellWorldOptions {
326
+ /** Where every pooled object is added. The game owns it, and it outlives every cast. */
327
+ readonly scene: Scene;
328
+ /** The camera a spell may read for billboarding. Optional: most spells never look at it. */
329
+ readonly camera?: Camera;
330
+ /** Floor height under a point in metres. A spell lands here instead of at y = 0. */
331
+ readonly groundAt?: (x: number, z: number) => number;
332
+ /** Cast records. Defaults to 16. */
333
+ readonly castSlots?: number;
334
+ /** Lights in the pool. Defaults to 4. */
335
+ readonly lightCount?: number;
336
+ /** Surface field. Defaults to 96 cells over 120 m. `false` skips it and saves the float arrays. */
337
+ readonly reaction?: IReactionFieldOptions | false;
338
+ /**
339
+ * Keep every spell to at most three flashes per second (WCAG 2.3.1). Defaults to false, which is
340
+ * the upstream behaviour; a game with an accessibility setting turns it on.
341
+ */
342
+ readonly reducedFlashes?: boolean;
343
+ /** Spells that shake the camera. `false` gives them nothing to shake. */
344
+ readonly shake?: ISpellWorldShakeOptions | false;
345
+ /**
346
+ * Parent an object a spell built. A `GPUParticles3D` also needs a renderer before it can emit, and
347
+ * only the game knows its own context: pass the game context's `add`, which parents *and* attaches.
348
+ * The default parents to `scene`, which is enough for a test and not enough to draw.
349
+ */
350
+ readonly add?: (object: Object3D) => void;
351
+ }
352
+ /**
353
+ * Everything a spell is allowed to touch.
354
+ *
355
+ * One instance per game. `update` advances the light decay, the surface field and the shake; the
356
+ * casts themselves live in a `CastPool` the game steps itself, so a paused game can stop casting
357
+ * without also freezing a scorch that is still fading.
358
+ */
359
+ declare class SpellWorld implements ICastEnvironment {
360
+ #private;
361
+ readonly scene: Scene;
362
+ readonly camera: Camera | undefined;
363
+ readonly groundAt: ((x: number, z: number) => number) | undefined;
364
+ readonly castSlots: number;
365
+ readonly lights: SpellLights;
366
+ readonly reaction: ReactionField | undefined;
367
+ readonly shake: CameraShake | undefined;
368
+ readonly reducedFlashes: boolean;
369
+ /** Where a spell with no `from` starts: the caster's hand, in world metres. */
370
+ readonly focus: Vector3;
371
+ /** Parent a spell's pooled object. See `ISpellWorldOptions.add`. */
372
+ readonly add: (object: Object3D) => void;
373
+ /** Everything a spell has parented through `add`, in creation order. */
374
+ readonly objects: Object3D[];
375
+ /** Seconds since the world was created. */
376
+ time: number;
377
+ /** Flashes the limiter refused, so a game can see its own accessibility setting working. */
378
+ suppressedFlashes: number;
379
+ constructor(options: ISpellWorldOptions);
380
+ /**
381
+ * Ask the limiter whether a flash may be shown.
382
+ *
383
+ * With reduced flashes on, a fourth flash inside one second is refused and the spell draws its
384
+ * impact without one. Returning a boolean rather than quietly dimming keeps the spell honest:
385
+ * the spell still happens, the flash does not.
386
+ */
387
+ flash(): boolean;
388
+ /** Surface height of the floor under a point, or 0 when the game supplied none. */
389
+ floorAt(x: number, z: number): number;
390
+ update(dt: number): void;
391
+ /** Put out every light, clear the floor and stop the shake, keeping every pool warm. */
392
+ clear(): void;
393
+ }
394
+
395
+ /** Anything a game may change about a spell. Merged over the stock recipe. */
396
+ interface IFireSpellOverrides {
397
+ readonly core?: string;
398
+ readonly highlight?: string;
399
+ readonly speed?: number;
400
+ readonly charge?: number;
401
+ readonly impact?: number;
402
+ readonly linger?: number;
403
+ readonly radius?: number;
404
+ readonly burst?: number;
405
+ readonly trail?: number;
406
+ readonly lingerBurst?: number;
407
+ readonly light?: number;
408
+ readonly shake?: number;
409
+ readonly scorch?: number;
410
+ }
411
+ /**
412
+ * A ball of fire that charges in the hand, crosses the room and leaves the floor burning.
413
+ * @situation a fireball spell a player casts at an enemy
414
+ * @situation a burning projectile that explodes and scorches the ground
415
+ * @situation a wizard's fire attack with a wind-up, a flight and an aftermath
416
+ * @constraint every colour, size, count and timing is a named override on the call
417
+ * @constraint the stock look ships as the default, and no override rebuilds a pipeline
418
+ * @override core, highlight, speed, charge, impact, linger, radius, burst, trail, lingerBurst, light, shake, scorch
419
+ * @example const fireball = createFireball(world);
420
+ * casts.cast(fireball, target);
421
+ */
422
+ declare function createFireball(world: SpellWorld, overrides?: IFireSpellOverrides): ISpell;
423
+ /**
424
+ * A bolt out of the sky: it charges, strikes the point instantly and the ground remembers it.
425
+ * @situation a lightning strike spell that hits a point immediately
426
+ * @situation a thunderbolt with a wind-up and a burnt mark where it lands
427
+ * @situation an electrical spell with a column of light from above
428
+ * @override core, highlight, charge, impact, linger, radius, light, shake, scorch
429
+ * @example const bolt = createThunderstrike(world);
430
+ */
431
+ declare function createThunderstrike(world: SpellWorld, overrides?: IFireSpellOverrides): ISpell;
432
+ /**
433
+ * A shard of ice that flies flat and fast, and freezes the ground it breaks on.
434
+ * @situation an ice spike spell that flies at a target and shatters
435
+ * @situation a freezing projectile that leaves frost on the floor
436
+ * @situation a cold spell with a charge, a flight and a lingering chill
437
+ * @override core, highlight, speed, charge, impact, linger, radius, burst, trail, light
438
+ * @example const spike = createGlacialSpike(world);
439
+ */
440
+ declare function createGlacialSpike(world: SpellWorld, overrides?: IFireSpellOverrides): ISpell;
441
+ /**
442
+ * A volley of arcane missiles: fast, precise, and each one pops on arrival.
443
+ * @situation an arcane missile spell that fires several projectiles at a target
444
+ * @situation a magic barrage a mage class spams
445
+ * @situation a pink energy bolt with a short charge
446
+ * @override core, highlight, speed, charge, impact, linger, radius, burst, light
447
+ * @example const barrage = createArcaneBarrage(world);
448
+ */
449
+ declare function createArcaneBarrage(world: SpellWorld, overrides?: IFireSpellOverrides): ISpell;
450
+ /**
451
+ * A ward around the caster: it forms, holds, and breaks outward when it expires.
452
+ * @situation a shield spell a player casts on themselves
453
+ * @situation a magic barrier that forms around the caster
454
+ * @situation a defensive bubble that flashes when it breaks
455
+ * @override core, highlight, charge, impact, linger, radius, light, shake
456
+ * @example const aegis = createAegis(world);
457
+ */
458
+ declare function createAegis(world: SpellWorld, overrides?: IFireSpellOverrides): ISpell;
459
+ /**
460
+ * A pillar of fire that erupts where it lands and keeps burning.
461
+ * @situation a fire area spell that erupts at a point and burns there
462
+ * @situation an inferno column a boss drops on the arena
463
+ * @situation a sustained flame that scorches the ground for seconds
464
+ * @override core, highlight, charge, impact, linger, radius, burst, trail, light, shake, scorch
465
+ * @example const inferno = createInferno(world);
466
+ */
467
+ declare function createInferno(world: SpellWorld, overrides?: IFireSpellOverrides): ISpell;
468
+
469
+ /**
470
+ * Particle behaviour as data, so a spell's look is not a shader.
471
+ *
472
+ * Upstream `Particles.js` keeps one kernel and a table of kinds — flame, ember, spark, smoke,
473
+ * debris — and a spell picks kinds and retunes them. Nothing recompiles when it does, because the
474
+ * numbers a kind owns are uniforms and the kernel reads them. This is that table, driving the
475
+ * engine's own `GPUParticles3D` instead of upstream's WebGL2 renderer.
476
+ *
477
+ * Every value here is behaviour: how long a particle lives, how far and how fast it flies, what
478
+ * gravity and the air do to it, and what colour it runs from and to. The table holds those as
479
+ * uniforms, so a settings screen or a spell override writes them and the pipeline, the material and
480
+ * the kernels all stay exactly as they were.
481
+ *
482
+ * One emitter reads one kind. Two emitters of the same kind and the same code share a pipeline;
483
+ * the engine's node builder hashes the graph, so a second emitter of the same kind costs buffers
484
+ * and a draw, never a program.
485
+ */
486
+
487
+ /** The kinds a spell or an effect selects from. Adding one is a row, not a shader. */
488
+ declare const PARTICLE_KINDS: readonly ["flame", "ember", "spark", "smoke", "ice", "arc", "mote", "debris"];
489
+ type ParticleKindName = (typeof PARTICLE_KINDS)[number];
490
+ /** How a kind's sprite is drawn. Mask and stretch only; colour comes from the table. */
491
+ type ParticleStyle = "glow" | "media" | "spark";
492
+ /** Every value a kind owns. A retune writes these and rebuilds nothing. */
493
+ interface IParticleKindValues {
494
+ /** Seconds a particle lives, shortest and longest. */
495
+ readonly lifetime: readonly [number, number];
496
+ /** Metres across the sprite, at birth and at death. */
497
+ readonly size: readonly [number, number];
498
+ /** Metres per second at spawn, slowest and fastest. */
499
+ readonly speed: readonly [number, number];
500
+ /** Half-angle of the launch cone in radians, around the emitter's direction. */
501
+ readonly cone: number;
502
+ /** Downward acceleration, m/s². 9.8 reads as debris, 0 as magic. */
503
+ readonly gravity: number;
504
+ /** Exponential velocity decay per second. High drag is a licking flame; low is a thrown spark. */
505
+ readonly drag: number;
506
+ /** Upward acceleration, m/s². Fire and smoke rise; sparks do not. */
507
+ readonly buoyancy: number;
508
+ /** Opacity at birth and at death. */
509
+ readonly alpha: readonly [number, number];
510
+ /** Colour at birth, and at death. A spell retunes both. */
511
+ readonly colour: readonly [number, number, number];
512
+ readonly highlight: readonly [number, number, number];
513
+ }
514
+ /** The uniforms one kind's kernel and material read. Held so a retune never touches the graph. */
515
+ interface IParticleKindNodes {
516
+ readonly lifetime: UniformNode<"vec2", Vector2>;
517
+ readonly size: UniformNode<"vec2", Vector2>;
518
+ readonly speed: UniformNode<"vec2", Vector2>;
519
+ readonly alpha: UniformNode<"vec2", Vector2>;
520
+ readonly colour: UniformNode<"vec3", Vector3>;
521
+ readonly highlight: UniformNode<"vec3", Vector3>;
522
+ /** `x` cone, `y` gravity, `z` drag, `w` buoyancy. */
523
+ readonly shape: UniformNode<"vec4", Vector4>;
524
+ }
525
+ /**
526
+ * The tunable kind table.
527
+ *
528
+ * One table per game, or one per spell: it knows only the kinds it was asked for, so a spell that
529
+ * never uses `debris` pays nothing for it. `set` writes uniforms, which is why retuning a spell from
530
+ * a settings screen builds no pipeline.
531
+ */
532
+ declare class ParticleKindTable {
533
+ #private;
534
+ readonly kinds: readonly ParticleKindName[];
535
+ constructor(kinds?: readonly ParticleKindName[]);
536
+ has(kind: ParticleKindName): boolean;
537
+ /** Read one kind's current values. */
538
+ get(kind: ParticleKindName): IParticleKindValues;
539
+ /**
540
+ * Retune a kind. Every field is optional, every value must be finite, and a partial patch leaves
541
+ * the rest alone. No kernel is rebuilt and no material is replaced.
542
+ */
543
+ set(kind: ParticleKindName, patch: Partial<IParticleKindValues>): this;
544
+ /** The TSL nodes one kind's kernel and material read. Stable for the table's lifetime. */
545
+ nodes(kind: ParticleKindName): IParticleKindNodes;
546
+ }
547
+
548
+ /**
549
+ * One recipe, six spells.
550
+ *
551
+ * Every spell in the first wave is the same four beats with different numbers in them: something
552
+ * charges, something crosses the room, something lands, and the room stays changed. So this is one
553
+ * factory that builds a spell out of a recipe, and each `create<Spell>` is a recipe plus a look.
554
+ * That is what keeps the cost honest — a game that imports one spell gets one factory, not a
555
+ * catalog.
556
+ *
557
+ * Drawables (the ball, the shell, the bolt, the shield) and emitters are built once at `create` and
558
+ * only shown, hidden and re-emitted at cast time, so the first cast of a spell costs exactly what
559
+ * its hundredth does. Every drawable is per pool slot: two fireballs in the air at once do not fight
560
+ * over one sprite.
561
+ */
562
+
563
+ /** What a spell is at birth, and what it cools to. */
564
+ interface ISpellTint {
565
+ readonly colour: Color$1;
566
+ readonly highlight: Color$1;
567
+ }
568
+ /** A particle role. `burst` is particles per emission. */
569
+ interface ISpellEmitter {
570
+ readonly kind: ParticleKindName;
571
+ readonly burst: number;
572
+ /** Seconds between repeated emissions. Ignored while travelling, which emits every frame. */
573
+ readonly interval?: number;
574
+ readonly style?: ParticleStyle;
575
+ }
576
+ interface ISpellImpact {
577
+ /**
578
+ * `hold` keeps the shell at full strength for the whole linger instead of expanding once. A ward
579
+ * around the caster holds; an impact wave expands.
580
+ */
581
+ readonly shell?: {
582
+ readonly radius: number;
583
+ readonly seconds: number;
584
+ readonly strength: number;
585
+ readonly hold?: boolean;
586
+ };
587
+ readonly light?: {
588
+ readonly intensity: number;
589
+ readonly range: number;
590
+ readonly seconds: number;
591
+ };
592
+ readonly splat?: {
593
+ readonly radius: number;
594
+ readonly pattern?: ReactionPattern;
595
+ readonly heat?: number;
596
+ readonly char?: number;
597
+ readonly wet?: number;
598
+ readonly frost?: number;
599
+ readonly crack?: number;
600
+ readonly glow?: number;
601
+ };
602
+ /** Camera shake amplitude in metres. */
603
+ readonly shake?: number;
604
+ }
605
+ /** Everything a spell is. A factory is a recipe; the look is the tint. */
606
+ interface ISpellRecipe {
607
+ readonly name: string;
608
+ readonly shape: CastShape;
609
+ readonly speed?: number;
610
+ readonly radius?: number;
611
+ readonly timing: Required<ICastTiming>;
612
+ readonly tint: ISpellTint;
613
+ /** Metres across the ball, and how hard it burns. */
614
+ readonly core?: {
615
+ readonly radius: number;
616
+ readonly intensity: number;
617
+ };
618
+ /** Motes pulled in while the spell winds up. */
619
+ readonly charge?: ISpellEmitter;
620
+ /** What the ball sheds as it flies. */
621
+ readonly trail?: ISpellEmitter;
622
+ /** What the impact throws. */
623
+ readonly burst?: ISpellEmitter;
624
+ /** What keeps burning after the impact. */
625
+ readonly linger?: ISpellEmitter;
626
+ readonly impact: ISpellImpact;
627
+ /** A column from the sky to the point. `height` is how far up it starts. */
628
+ readonly bolt?: {
629
+ readonly width: number;
630
+ readonly height: number;
631
+ readonly seconds: number;
632
+ };
633
+ }
634
+ /**
635
+ * Build a spell from a recipe.
636
+ *
637
+ * The returned object is an `ISpell`: hand it to `CastPool.cast` and the pool drives it. It reads
638
+ * the world only through `SpellWorld`, so a game can swap the scene, the floor or the light pool
639
+ * without touching the spell.
640
+ */
641
+ declare function createSpell(world: SpellWorld, recipe: ISpellRecipe): ISpell;
642
+
643
+ export { type CastPhase, CastPool, type CastShape, type ICast, type ICastEnvironment, type ICastOptions, type ICastTiming, type IFireSpellOverrides, type IParticleKindValues, type IReactionDirty, type IReactionFieldOptions, type IReactionSplat, type ISpell, type ISpellEmitter, type ISpellImpact, type ISpellLightFlash, type ISpellLightsOptions, type ISpellRecipe, type ISpellTint, type ISpellWorldOptions, type ISpellWorldShakeOptions, type ParticleKindName, ParticleKindTable, REACTION_CHANNELS, type ReactionChannel, ReactionField, type ReactionPattern, SpellLights, SpellWorld, createAegis, createArcaneBarrage, createFireball, createGlacialSpike, createInferno, createSpell, createThunderstrike };