@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.
Files changed (236) hide show
  1. package/README.md +1 -1
  2. package/capabilities.json +1988 -204
  3. package/dist/{assets-YUbXa3-Y.d.ts → assets-CfMKnOsK.d.ts} +78 -1
  4. package/dist/camera-shake-CZKOfGn4.d.ts +46 -0
  5. package/dist/{canvas-layer-vCtanIeB.d.ts → canvas-layer-G7ttVy7y.d.ts} +1 -1
  6. package/dist/chunk-4SRAQFTU.js +133 -0
  7. package/dist/chunk-CFGTPFUH.js +231 -0
  8. package/dist/chunk-DIPIJICH.js +8916 -0
  9. package/dist/chunk-EEABDLUC.js +2237 -0
  10. package/dist/chunk-EFWZWLPY.js +1895 -0
  11. package/dist/chunk-GXY7B3JG.js +46 -0
  12. package/dist/chunk-GYUZJQ7U.js +280 -0
  13. package/dist/chunk-H4J6IAJE.js +504 -0
  14. package/dist/chunk-KIRUKTBQ.js +187 -0
  15. package/dist/chunk-QWJEMUUT.js +94 -0
  16. package/dist/chunk-SV4QVUTQ.js +31 -0
  17. package/dist/chunk-U4YHUKKL.js +615 -0
  18. package/dist/chunk-VP43GIWW.js +18 -0
  19. package/dist/chunk-XDTZ4QMO.js +160 -0
  20. package/dist/default-tone-mapping-GgKPTiBP.d.ts +4 -0
  21. package/dist/{game-DzMcitDO.d.ts → game-k8K3hZai.d.ts} +85 -9
  22. package/dist/hot.d.ts +5 -4
  23. package/dist/hot.js +5 -52
  24. package/dist/index.d.ts +633 -1351
  25. package/dist/index.js +12873 -23068
  26. package/dist/{model-lod-CTpZ6imz.d.ts → model-lod-DPTzeCcD.d.ts} +35 -3
  27. package/dist/playtest.d.ts +5 -4
  28. package/dist/playtest.js +25 -75
  29. package/dist/quality-BYqKGAwo.d.ts +868 -0
  30. package/dist/react-css.js +1 -215
  31. package/dist/react.d.ts +3 -2
  32. package/dist/render-environment.d.ts +170 -0
  33. package/dist/render-environment.js +352 -0
  34. package/dist/{renderer-rZm0hVqq.d.ts → renderer-BtOSseYf.d.ts} +42 -35
  35. package/dist/spells/index.d.ts +643 -0
  36. package/dist/spells/index.js +1558 -0
  37. package/dist/spells/ultra/index.d.ts +1600 -0
  38. package/dist/spells/ultra/index.js +6804 -0
  39. package/dist/terrain-jobs-worker.js +1 -123
  40. package/dist/two-sided-foliage-W523J3UM.js +1 -0
  41. package/dist/ui-layer.js +6 -384
  42. package/dist/worker.js +13 -43
  43. package/dist/world.d.ts +988 -268
  44. package/dist/world.js +17464 -18290
  45. package/mcp/animation-server.mjs +1 -1
  46. package/mcp/animation.mjs +2 -3
  47. package/mcp/engine-server.mjs +245 -52
  48. package/mcp/servers.mjs +10 -3
  49. package/mcp/terrain.mjs +8 -0
  50. package/package.json +19 -7
  51. package/patches/three@0.187.0-prd269-upgrade.patch +2102 -0
  52. package/patches/three@0.187.0.patch +2004 -407
  53. package/src/animation-batch.ts +193 -0
  54. package/src/animation-layers.ts +7 -3
  55. package/src/animation.ts +209 -29
  56. package/src/asset-cache.ts +3 -3
  57. package/src/asset-memo.ts +202 -0
  58. package/src/assets.ts +437 -125
  59. package/src/auto-batch.ts +190 -44
  60. package/src/card-lod.ts +152 -0
  61. package/src/compressed-texture-preparation.ts +1008 -0
  62. package/src/compute-driven.ts +1 -1
  63. package/src/config.ts +8 -0
  64. package/src/debug.ts +103 -22
  65. package/src/dev-global.ts +54 -0
  66. package/src/engine-hooks.ts +37 -0
  67. package/src/frame-budget.ts +50 -23
  68. package/src/game-boot-phase.ts +269 -0
  69. package/src/game-dev-tools.ts +86 -0
  70. package/src/game-frame-loop.ts +958 -0
  71. package/src/game-renderer-metrics.ts +77 -0
  72. package/src/game-startup.ts +1076 -0
  73. package/src/game-ui.ts +84 -0
  74. package/src/game-validate.ts +70 -0
  75. package/src/game.ts +198 -2264
  76. package/src/gamepad-mappings.ts +269 -0
  77. package/src/generated/console-markers.ts +13 -0
  78. package/src/geometry-capture.ts +28 -4
  79. package/src/gpu-readings.ts +98 -0
  80. package/src/gpu-scene-bvh.ts +149 -36
  81. package/src/hot.ts +4 -7
  82. package/src/index.ts +141 -9
  83. package/src/input.ts +237 -25
  84. package/src/instanced-batch-lod.ts +3 -8
  85. package/src/interpolation.ts +171 -40
  86. package/src/launch-diagnostics.ts +22 -12
  87. package/src/look/ao-admission.ts +25 -0
  88. package/src/look/auto-exposure.ts +5 -16
  89. package/src/look/default-tone-mapping.ts +41 -5
  90. package/src/look/filmic-tone-mapping.ts +15 -13
  91. package/src/look/local-exposure.ts +2 -7
  92. package/src/look/look-diagnostics.ts +3 -3
  93. package/src/look/quad-pass.ts +21 -0
  94. package/src/look/quality.ts +14 -5
  95. package/src/look/unreal-bloom.ts +4 -13
  96. package/src/look/world-environment.ts +113 -103
  97. package/src/loop.ts +29 -0
  98. package/src/merge-parts.ts +20 -24
  99. package/src/model-lod.ts +139 -17
  100. package/src/particle-kinds.ts +515 -0
  101. package/src/particle-significance.ts +12 -0
  102. package/src/particles.ts +19 -10
  103. package/src/picking.ts +17 -3
  104. package/src/platform.ts +23 -4
  105. package/src/playtest.ts +27 -1
  106. package/src/profiling/FrameStages.ts +5 -6
  107. package/src/profiling/Spans.ts +3 -17
  108. package/src/profiling/debug-telemetry.ts +2 -6
  109. package/src/profiling/render-list-validate.ts +6 -15
  110. package/src/projection-apply.ts +4 -1
  111. package/src/projection-marker.ts +2 -1
  112. package/src/projection-plan.ts +9 -6
  113. package/src/quiet-markers.ts +3 -10
  114. package/src/render/cpu-bvh.ts +100 -0
  115. package/src/render/depth-pyramid.ts +6 -14
  116. package/src/render/environment/environmentContribution.ts +202 -0
  117. package/src/render/environment/environmentRadiance.ts +44 -0
  118. package/src/render/environment/environmentSampleCache.ts +56 -0
  119. package/src/render/environment/environmentSampling.ts +201 -0
  120. package/src/render/environment/environmentSnapshot.ts +71 -0
  121. package/src/render/environment/gate.ts +57 -0
  122. package/src/render/mesh-pool.ts +4 -20
  123. package/src/render/probe-trace.ts +872 -0
  124. package/src/render/probe-volume.ts +780 -34
  125. package/src/render/radiance-cache.ts +17 -0
  126. package/src/render/resolution-subrect.ts +2 -0
  127. package/src/render/rough-diffuse.ts +46 -12
  128. package/src/render/soft-shadow.ts +27 -12
  129. package/src/render/virtual-shadow-adaptive.ts +55 -0
  130. package/src/render/virtual-shadow-casters.ts +175 -0
  131. package/src/render/virtual-shadow-layers.ts +76 -0
  132. package/src/render/virtual-shadow-level.ts +224 -0
  133. package/src/render/virtual-shadow-markers.ts +193 -0
  134. package/src/render/virtual-shadow-options.ts +370 -0
  135. package/src/render/virtual-shadow-pages.ts +5 -0
  136. package/src/render/virtual-shadow-partial.ts +13 -0
  137. package/src/render/virtual-shadow.ts +231 -1008
  138. package/src/render/world-impostor-surface.ts +402 -40
  139. package/src/render/world-impostor.ts +5 -2
  140. package/src/render-camera-cull.ts +98 -3
  141. package/src/render-environment.ts +41 -0
  142. package/src/render-pass-budget.ts +34 -7
  143. package/src/renderProjection.ts +22 -0
  144. package/src/renderer-config.ts +36 -0
  145. package/src/renderer-facts.ts +37 -0
  146. package/src/renderer.ts +144 -65
  147. package/src/resolution-scaler.ts +3 -2
  148. package/src/scene-entry-inspectors.ts +61 -0
  149. package/src/snow-field.ts +2 -1
  150. package/src/spells/cast-pool.ts +361 -0
  151. package/src/spells/index.ts +177 -0
  152. package/src/spells/mechanisms.ts +295 -0
  153. package/src/spells/reaction-field.ts +415 -0
  154. package/src/spells/spell-lights.ts +139 -0
  155. package/src/spells/spell-world.ts +187 -0
  156. package/src/spells/spell.ts +397 -0
  157. package/src/spells/spells.ts +283 -0
  158. package/src/spells/ultra/engine/camera.ts +184 -0
  159. package/src/spells/ultra/engine/quality.ts +96 -0
  160. package/src/spells/ultra/index.ts +52 -0
  161. package/src/spells/ultra/main.ts +305 -0
  162. package/src/spells/ultra/scene/arenaMaterial.ts +325 -0
  163. package/src/spells/ultra/spells/cast.ts +233 -0
  164. package/src/spells/ultra/spells/fire.ts +1267 -0
  165. package/src/spells/ultra/vfx/FluidVolume.ts +816 -0
  166. package/src/spells/ultra/vfx/FluidVolume.tsl.ts +855 -0
  167. package/src/spells/ultra/vfx/FxTarget.ts +61 -0
  168. package/src/spells/ultra/vfx/GroundField.ts +1399 -0
  169. package/src/spells/ultra/vfx/Particles.ts +1475 -0
  170. package/src/spells/ultra/vfx/Ribbons.ts +645 -0
  171. package/src/spells/ultra/vfx/Shockwaves.ts +286 -0
  172. package/src/spells/ultra/vfx/Volumes.ts +489 -0
  173. package/src/spells/ultra/vfx/common.ts +1195 -0
  174. package/src/spells/ultra/vfx/noise.ts +441 -0
  175. package/src/startup-offscreen-bytes.ts +78 -0
  176. package/src/startup-readiness.ts +128 -34
  177. package/src/static-transform.ts +25 -19
  178. package/src/streamed-textures.ts +112 -0
  179. package/src/streaming.ts +68 -4
  180. package/src/texture-streaming.ts +331 -0
  181. package/src/version.ts +1 -1
  182. package/src/warmup.ts +56 -8
  183. package/src/water-surface.ts +9 -3
  184. package/src/worker.ts +12 -2
  185. package/src/world-bundle-safety.ts +446 -0
  186. package/src/world-cell-batches.ts +1178 -0
  187. package/src/world-cell-chunks.ts +1128 -0
  188. package/src/world-cell-data.ts +995 -0
  189. package/src/world-cell-impostors.ts +1461 -0
  190. package/src/world-cell-lod-bias.ts +151 -0
  191. package/src/world-cell-models.ts +1074 -0
  192. package/src/world-cell-options.ts +177 -0
  193. package/src/world-cell-placements.ts +798 -0
  194. package/src/world-cell-prewarm.ts +592 -0
  195. package/src/world-cell-readiness.ts +357 -0
  196. package/src/world-cell-records.ts +401 -0
  197. package/src/world-cell-render-bundles.ts +459 -0
  198. package/src/world-cell-render-gpu-dress.ts +710 -0
  199. package/src/world-cell-render-main-cull.ts +540 -0
  200. package/src/world-cell-render-shadow-claims.ts +198 -0
  201. package/src/world-cell-render-util.ts +259 -0
  202. package/src/world-cell-render.ts +1501 -0
  203. package/src/world-cell-residency.ts +754 -0
  204. package/src/world-cell-stale.ts +238 -0
  205. package/src/world-cells.ts +1335 -10418
  206. package/src/world-chunk-shadow.ts +308 -0
  207. package/src/world-collar.ts +315 -0
  208. package/src/world-gpu-flags.ts +131 -0
  209. package/src/world-gpu-readback.ts +881 -0
  210. package/src/world-gpu-reference.ts +524 -0
  211. package/src/world-gpu-scene.ts +256 -2286
  212. package/src/world-gpu-shadow.ts +203 -0
  213. package/src/world-gpu-types.ts +409 -0
  214. package/src/world-gpu-validation.ts +518 -0
  215. package/src/world-heightfield.ts +802 -0
  216. package/src/world-load-limiter.ts +111 -0
  217. package/src/world-model-sections.ts +80 -0
  218. package/src/world-noise.ts +241 -0
  219. package/src/world-package.ts +42 -0
  220. package/src/world-region.ts +1 -1
  221. package/src/world-river-ribbon.ts +282 -0
  222. package/src/world-root-frame.ts +39 -0
  223. package/src/world-shore-field.ts +91 -0
  224. package/src/world-static-pose.ts +163 -0
  225. package/src/world-surface-sampler.ts +48 -0
  226. package/src/world-terrain-splat.ts +361 -153
  227. package/src/world-tile-budget.ts +249 -0
  228. package/src/world-tile-geometry.ts +469 -0
  229. package/src/world-tile-lod.ts +408 -0
  230. package/src/world-tile-observation.ts +566 -0
  231. package/src/world-tile-stitch.ts +166 -0
  232. package/src/world-tiles.ts +247 -1755
  233. package/src/world-validate.ts +6 -14
  234. package/src/world-warm.ts +51 -0
  235. package/src/world-water-bodies.ts +359 -0
  236. 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";