@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,397 @@
1
+ /**
2
+ * One recipe, six spells.
3
+ *
4
+ * Every spell in the first wave is the same four beats with different numbers in them: something
5
+ * charges, something crosses the room, something lands, and the room stays changed. So this is one
6
+ * factory that builds a spell out of a recipe, and each `create<Spell>` is a recipe plus a look.
7
+ * That is what keeps the cost honest — a game that imports one spell gets one factory, not a
8
+ * catalog.
9
+ *
10
+ * Drawables (the ball, the shell, the bolt, the shield) and emitters are built once at `create` and
11
+ * only shown, hidden and re-emitted at cast time, so the first cast of a spell costs exactly what
12
+ * its hundredth does. Every drawable is per pool slot: two fireballs in the air at once do not fight
13
+ * over one sprite.
14
+ */
15
+
16
+ import { Color, Vector3 } from "three/webgpu";
17
+ import {
18
+ type ParticleKindName,
19
+ ParticleKindTable,
20
+ type ParticleStyle,
21
+ createParticleKindEmitter,
22
+ } from "../particle-kinds.js";
23
+ import { GPUParticles3D } from "../particles.js";
24
+ import type { CastShape, ICast, ICastTiming, ISpell } from "./cast-pool.js";
25
+ import { type ISpellDrawables, createDrawables } from "./mechanisms.js";
26
+ import type { ReactionPattern } from "./reaction-field.js";
27
+ import type { SpellWorld } from "./spell-world.js";
28
+
29
+ /** What a spell is at birth, and what it cools to. */
30
+ export interface ISpellTint {
31
+ readonly colour: Color;
32
+ readonly highlight: Color;
33
+ }
34
+
35
+ /** A particle role. `burst` is particles per emission. */
36
+ export interface ISpellEmitter {
37
+ readonly kind: ParticleKindName;
38
+ readonly burst: number;
39
+ /** Seconds between repeated emissions. Ignored while travelling, which emits every frame. */
40
+ readonly interval?: number;
41
+ readonly style?: ParticleStyle;
42
+ }
43
+
44
+ export interface ISpellImpact {
45
+ /**
46
+ * `hold` keeps the shell at full strength for the whole linger instead of expanding once. A ward
47
+ * around the caster holds; an impact wave expands.
48
+ */
49
+ readonly shell?: {
50
+ readonly radius: number;
51
+ readonly seconds: number;
52
+ readonly strength: number;
53
+ readonly hold?: boolean;
54
+ };
55
+ readonly light?: { readonly intensity: number; readonly range: number; readonly seconds: number };
56
+ readonly splat?: {
57
+ readonly radius: number;
58
+ readonly pattern?: ReactionPattern;
59
+ readonly heat?: number;
60
+ readonly char?: number;
61
+ readonly wet?: number;
62
+ readonly frost?: number;
63
+ readonly crack?: number;
64
+ readonly glow?: number;
65
+ };
66
+ /** Camera shake amplitude in metres. */
67
+ readonly shake?: number;
68
+ }
69
+
70
+ /** Everything a spell is. A factory is a recipe; the look is the tint. */
71
+ export interface ISpellRecipe {
72
+ readonly name: string;
73
+ readonly shape: CastShape;
74
+ readonly speed?: number;
75
+ readonly radius?: number;
76
+ readonly timing: Required<ICastTiming>;
77
+ readonly tint: ISpellTint;
78
+ /** Metres across the ball, and how hard it burns. */
79
+ readonly core?: { readonly radius: number; readonly intensity: number };
80
+ /** Motes pulled in while the spell winds up. */
81
+ readonly charge?: ISpellEmitter;
82
+ /** What the ball sheds as it flies. */
83
+ readonly trail?: ISpellEmitter;
84
+ /** What the impact throws. */
85
+ readonly burst?: ISpellEmitter;
86
+ /** What keeps burning after the impact. */
87
+ readonly linger?: ISpellEmitter;
88
+ readonly impact: ISpellImpact;
89
+ /** A column from the sky to the point. `height` is how far up it starts. */
90
+ readonly bolt?: { readonly width: number; readonly height: number; readonly seconds: number };
91
+ }
92
+
93
+ /** Per-cast scratch, one object per pool slot, so a cast allocates nothing. */
94
+ interface ICastScratch {
95
+ sinceImpact: number;
96
+ emitTimer: number;
97
+ }
98
+
99
+ interface IBuilt {
100
+ readonly drawables: ISpellDrawables[];
101
+ readonly scratch: ICastScratch[];
102
+ readonly charge: GPUParticles3D | undefined;
103
+ readonly trail: GPUParticles3D | undefined;
104
+ readonly burst: GPUParticles3D | undefined;
105
+ readonly linger: GPUParticles3D | undefined;
106
+ }
107
+
108
+ /**
109
+ * Build a spell from a recipe.
110
+ *
111
+ * The returned object is an `ISpell`: hand it to `CastPool.cast` and the pool drives it. It reads
112
+ * the world only through `SpellWorld`, so a game can swap the scene, the floor or the light pool
113
+ * without touching the spell.
114
+ */
115
+ export function createSpell(world: SpellWorld, recipe: ISpellRecipe): ISpell {
116
+ const built = build(world, recipe);
117
+ const position = new Vector3();
118
+ const sky = new Vector3();
119
+ const lightColour = new Color();
120
+ const shellColour = new Color();
121
+
122
+ return {
123
+ name: recipe.name,
124
+ radius: recipe.radius,
125
+ shape: recipe.shape,
126
+ speed: recipe.speed,
127
+ timing: recipe.timing,
128
+
129
+ phase(cast, phase) {
130
+ const scratch = at(built.scratch, cast);
131
+ const drawables = at(built.drawables, cast);
132
+ if (phase === "charge") {
133
+ scratch.sinceImpact = 0;
134
+ scratch.emitTimer = 0;
135
+ return;
136
+ }
137
+ if (phase === "impact") {
138
+ scratch.sinceImpact = 0;
139
+ scratch.emitTimer = 0;
140
+ land(world, drawables, recipe, cast, sky, lightColour, shellColour);
141
+ emit(built.burst, recipe.burst, cast.pos, recipe.burst?.burst ?? 0);
142
+ return;
143
+ }
144
+ if (phase === "linger") {
145
+ emit(built.linger, recipe.linger, cast.pos, recipe.linger?.burst ?? 0);
146
+ return;
147
+ }
148
+ // Retired: put every drawable this cast owns away. The floor mark belongs to the world.
149
+ drawables.core.hide();
150
+ drawables.shell.hide();
151
+ drawables.bolt.hide();
152
+ },
153
+
154
+ update(cast, dt) {
155
+ const scratch = at(built.scratch, cast);
156
+ const drawables = at(built.drawables, cast);
157
+ if (cast.phase === "charge") {
158
+ position.copy(cast.from);
159
+ chargeUp(drawables, recipe, position, cast.t / Math.max(1e-4, cast.durations.charge));
160
+ emit(built.charge, recipe.charge, position, (recipe.charge?.burst ?? 0) * dt * 60);
161
+ return;
162
+ }
163
+ if (cast.phase === "travel") {
164
+ position.copy(cast.pos);
165
+ drawBall(drawables, recipe, position);
166
+ emit(built.trail, recipe.trail, position, (recipe.trail?.burst ?? 0) * dt * 60);
167
+ if (recipe.bolt !== undefined) {
168
+ sky.copy(cast.pos).setY(cast.pos.y + recipe.bolt.height);
169
+ drawBolt(drawables, recipe, sky, cast.pos, 1, world.camera);
170
+ }
171
+ return;
172
+ }
173
+ scratch.sinceImpact += dt;
174
+ stepImpact(drawables, recipe, cast, scratch.sinceImpact, world.camera);
175
+ if (cast.phase === "linger") {
176
+ scratch.emitTimer += dt;
177
+ const interval = Math.max(0.02, recipe.linger?.interval ?? 0.12);
178
+ if (scratch.emitTimer >= interval) {
179
+ // One emission per interval, never a backlog: a long frame must not spend the burst twice.
180
+ scratch.emitTimer = 0;
181
+ emit(built.linger, recipe.linger, cast.pos, recipe.linger?.burst ?? 0);
182
+ }
183
+ }
184
+ },
185
+ };
186
+ }
187
+
188
+ /** Build every pool slot's drawables and the four emitters. Called once, at `create`. */
189
+ function build(world: SpellWorld, recipe: ISpellRecipe): IBuilt {
190
+ const table = new ParticleKindTable(
191
+ uniqueKinds([recipe.charge, recipe.trail, recipe.burst, recipe.linger]),
192
+ );
193
+ for (const kind of table.kinds) {
194
+ table.set(kind, {
195
+ colour: [recipe.tint.colour.r, recipe.tint.colour.g, recipe.tint.colour.b],
196
+ highlight: [recipe.tint.highlight.r, recipe.tint.highlight.g, recipe.tint.highlight.b],
197
+ });
198
+ }
199
+ return {
200
+ burst: buildEmitter(world, table, recipe.burst, recipe.name, 1, recipe.tint),
201
+ charge: buildEmitter(world, table, recipe.charge, recipe.name, 2, recipe.tint),
202
+ drawables: Array.from({ length: world.castSlots }, () => createDrawables(world.scene)),
203
+ linger: buildEmitter(world, table, recipe.linger, recipe.name, 3, recipe.tint),
204
+ scratch: Array.from({ length: world.castSlots }, () => ({ emitTimer: 0, sinceImpact: 0 })),
205
+ trail: buildEmitter(world, table, recipe.trail, recipe.name, 4, recipe.tint),
206
+ };
207
+ }
208
+
209
+ /** Land the impact: the flash, the shell, the mark and the shake. */
210
+ function land(
211
+ world: SpellWorld,
212
+ drawables: ISpellDrawables,
213
+ recipe: ISpellRecipe,
214
+ cast: ICast,
215
+ sky: Vector3,
216
+ lightColour: Color,
217
+ shellColour: Color,
218
+ ): void {
219
+ const impact = recipe.impact;
220
+ if (impact.light !== undefined) {
221
+ const light = impact.light;
222
+ // The limiter can refuse a flash. The spell still lands; only the flash does not happen.
223
+ if (world.flash()) {
224
+ lightColour.copy(recipe.tint.colour).lerp(recipe.tint.highlight, 0.4);
225
+ world.lights.flash({
226
+ color: lightColour,
227
+ intensity: light.intensity,
228
+ range: light.range,
229
+ seconds: light.seconds,
230
+ x: cast.pos.x,
231
+ y: cast.pos.y,
232
+ z: cast.pos.z,
233
+ });
234
+ }
235
+ }
236
+ if (impact.splat !== undefined) {
237
+ const splat = impact.splat;
238
+ world.reaction?.splat({
239
+ char: splat.char,
240
+ crack: splat.crack,
241
+ frost: splat.frost,
242
+ glow: splat.glow,
243
+ heat: splat.heat,
244
+ pattern: splat.pattern ?? "radial",
245
+ radius: splat.radius,
246
+ seed: cast.seed,
247
+ wet: splat.wet,
248
+ x: cast.pos.x,
249
+ z: cast.pos.z,
250
+ });
251
+ }
252
+ if (impact.shake !== undefined && impact.shake > 0) world.shake?.trigger();
253
+ if (recipe.bolt !== undefined) {
254
+ sky.copy(cast.pos).setY(cast.pos.y + recipe.bolt.height);
255
+ drawBolt(drawables, recipe, sky, cast.pos, 1, world.camera);
256
+ }
257
+ if (impact.shell !== undefined) {
258
+ shellColour.copy(recipe.tint.colour).lerp(recipe.tint.highlight, 0.5);
259
+ drawables.shell.show(cast.pos, 0.02, impact.shell.radius, shellColour, impact.shell.strength);
260
+ }
261
+ drawables.core.hide();
262
+ }
263
+
264
+ /** Advance the shell and the bolt through the impact and the linger. */
265
+ function stepImpact(
266
+ drawables: ISpellDrawables,
267
+ recipe: ISpellRecipe,
268
+ cast: ICast,
269
+ sinceImpact: number,
270
+ camera: { readonly position: Vector3 } | undefined,
271
+ ): void {
272
+ const shell = recipe.impact.shell;
273
+ if (shell !== undefined) {
274
+ const colour = recipe.tint.colour.clone().lerp(recipe.tint.highlight, 0.5);
275
+ if (shell.hold === true) {
276
+ // A held shell does not expand: it sits at its radius and pulses until the cast retires.
277
+ const pulse = 0.9 + 0.1 * Math.sin(sinceImpact * 9);
278
+ drawables.shell.show(cast.pos, 0.999, shell.radius, colour, shell.strength * pulse, 1);
279
+ } else {
280
+ const progress = Math.min(1, sinceImpact / Math.max(0.05, shell.seconds));
281
+ drawables.shell.show(cast.pos, progress, shell.radius, colour, shell.strength);
282
+ }
283
+ }
284
+ const bolt = recipe.bolt;
285
+ if (bolt !== undefined) {
286
+ const life = Math.min(1, sinceImpact / Math.max(0.05, bolt.seconds));
287
+ const sky = new Vector3(cast.pos.x, cast.pos.y + bolt.height, cast.pos.z);
288
+ drawBolt(drawables, recipe, sky, cast.pos, 1 - life, camera);
289
+ }
290
+ }
291
+
292
+ function drawBall(drawables: ISpellDrawables, recipe: ISpellRecipe, at: Vector3): void {
293
+ const core = recipe.core;
294
+ if (core === undefined) return;
295
+ drawables.core.show(at, core.radius, recipe.tint.colour, recipe.tint.highlight, core.intensity);
296
+ }
297
+
298
+ function chargeUp(
299
+ drawables: ISpellDrawables,
300
+ recipe: ISpellRecipe,
301
+ at: Vector3,
302
+ progress: number,
303
+ ): void {
304
+ const core = recipe.core;
305
+ if (core === undefined) return;
306
+ const eased = Math.min(1, Math.max(0, progress));
307
+ drawables.core.show(
308
+ at,
309
+ core.radius * (0.25 + 0.75 * eased),
310
+ recipe.tint.colour,
311
+ recipe.tint.highlight,
312
+ core.intensity * eased,
313
+ );
314
+ }
315
+
316
+ function drawBolt(
317
+ drawables: ISpellDrawables,
318
+ recipe: ISpellRecipe,
319
+ from: Vector3,
320
+ to: Vector3,
321
+ strength: number,
322
+ camera: { readonly position: Vector3 } | undefined,
323
+ ): void {
324
+ const bolt = recipe.bolt;
325
+ if (bolt === undefined || strength <= 0.001) {
326
+ drawables.bolt.hide();
327
+ return;
328
+ }
329
+ drawables.bolt.show(
330
+ from,
331
+ to,
332
+ bolt.width,
333
+ recipe.tint.highlight,
334
+ recipe.tint.colour,
335
+ strength,
336
+ 0.37,
337
+ camera,
338
+ );
339
+ }
340
+
341
+ function buildEmitter(
342
+ world: SpellWorld,
343
+ table: ParticleKindTable,
344
+ role: ISpellEmitter | undefined,
345
+ name: string,
346
+ seedOffset: number,
347
+ tint: ISpellTint,
348
+ ): GPUParticles3D | undefined {
349
+ if (role === undefined) return undefined;
350
+ const options = createParticleKindEmitter({
351
+ // burst is particles per emission and may be fractional (a trail emits 2.4 per frame), but a
352
+ // ring capacity is a whole number of slots.
353
+ amount: Math.max(64, Math.ceil(role.burst * 64)),
354
+ kind: role.kind,
355
+ seed: seedOffset * 1013 + hashName(name),
356
+ style: role.style,
357
+ table,
358
+ });
359
+ const particles = new GPUParticles3D(options);
360
+ particles.name = `${name}-${role.kind}-${seedOffset}`;
361
+ world.add(particles);
362
+ return particles;
363
+ }
364
+
365
+ function emit(
366
+ emitter: GPUParticles3D | undefined,
367
+ role: ISpellEmitter | undefined,
368
+ at: Vector3,
369
+ count: number,
370
+ ): void {
371
+ if (emitter === undefined || role === undefined) return;
372
+ emitter.emitParticle({ count: Math.max(1, Math.round(count)), origin: at });
373
+ }
374
+
375
+ function uniqueKinds(roles: readonly (ISpellEmitter | undefined)[]): ParticleKindName[] {
376
+ const kinds: ParticleKindName[] = [];
377
+ for (const role of roles) {
378
+ if (role !== undefined && !kinds.includes(role.kind)) kinds.push(role.kind);
379
+ }
380
+ return kinds.length > 0 ? kinds : ["spark"];
381
+ }
382
+
383
+ function at<T>(list: readonly T[], cast: ICast): T {
384
+ const value = list[cast.index];
385
+ if (value === undefined) throw new RangeError(`cast slot ${cast.index} is outside the pool`);
386
+ return value;
387
+ }
388
+
389
+ /** A small stable hash of a name, so two spells' emitters do not share a random stream. */
390
+ function hashName(name: string): number {
391
+ let hash = 2166136261;
392
+ for (let index = 0; index < name.length; index++) {
393
+ hash ^= name.charCodeAt(index);
394
+ hash = Math.imul(hash, 16777619);
395
+ }
396
+ return hash >>> 8;
397
+ }
@@ -0,0 +1,283 @@
1
+ /**
2
+ * The first six spells: Fireball, Thunderstrike, Glacial Spike, Arcane Barrage, Aegis and Inferno.
3
+ *
4
+ * Each is a recipe over `createSpell` — the four beats with different numbers in them — plus the
5
+ * stock look the owner asked to absorb. Every colour, size, count and timing below is a named
6
+ * override on the factory call, so a game changes a spell completely without editing this file.
7
+ *
8
+ * Timings, silhouettes and stock looks are ported behaviour-only from Ultra Elements
9
+ * (`src/spells/fire.js`, `lightning.js`, `ice.js`, `arcane.js`, MIT, pinned `698b720`). The GLSL is
10
+ * not: every line on screen is TSL for the owned renderer and the native host.
11
+ */
12
+
13
+ import { Color } from "three/webgpu";
14
+ import type { SpellWorld } from "./spell-world.js";
15
+ import { type ISpellEmitter, type ISpellRecipe, createSpell } from "./spell.js";
16
+
17
+ /** Anything a game may change about a spell. Merged over the stock recipe. */
18
+ export interface IFireSpellOverrides {
19
+ readonly core?: string;
20
+ readonly highlight?: string;
21
+ readonly speed?: number;
22
+ readonly charge?: number;
23
+ readonly impact?: number;
24
+ readonly linger?: number;
25
+ readonly radius?: number;
26
+ readonly burst?: number;
27
+ readonly trail?: number;
28
+ readonly lingerBurst?: number;
29
+ readonly light?: number;
30
+ readonly shake?: number;
31
+ readonly scorch?: number;
32
+ }
33
+
34
+ const colour = (value: string): Color => new Color(value);
35
+
36
+ function recipe(base: ISpellRecipe, overrides: IFireSpellOverrides): ISpellRecipe {
37
+ const tint = {
38
+ colour: colour(overrides.core ?? `#${base.tint.colour.getHexString()}`),
39
+ highlight: colour(overrides.highlight ?? `#${base.tint.highlight.getHexString()}`),
40
+ };
41
+ const withBurst = (
42
+ role: ISpellEmitter | undefined,
43
+ burst: number | undefined,
44
+ ): ISpellEmitter | undefined =>
45
+ role === undefined || burst === undefined ? role : { ...role, burst };
46
+ return {
47
+ ...base,
48
+ burst: withBurst(base.burst, overrides.burst),
49
+ core:
50
+ base.core === undefined
51
+ ? undefined
52
+ : { ...base.core, intensity: overrides.light ?? base.core.intensity },
53
+ impact: {
54
+ ...base.impact,
55
+ shake: overrides.shake ?? base.impact.shake,
56
+ splat:
57
+ base.impact.splat === undefined
58
+ ? undefined
59
+ : { ...base.impact.splat, char: overrides.scorch ?? base.impact.splat.char },
60
+ },
61
+ linger: withBurst(base.linger, overrides.lingerBurst),
62
+ radius: overrides.radius ?? base.radius,
63
+ speed: overrides.speed ?? base.speed,
64
+ timing: {
65
+ charge: overrides.charge ?? base.timing.charge,
66
+ impact: overrides.impact ?? base.timing.impact,
67
+ linger: overrides.linger ?? base.timing.linger,
68
+ travel: base.timing.travel,
69
+ },
70
+ tint,
71
+ trail: withBurst(base.trail, overrides.trail),
72
+ };
73
+ }
74
+
75
+ /**
76
+ * A ball of fire that charges in the hand, crosses the room and leaves the floor burning.
77
+ * @situation a fireball spell a player casts at an enemy
78
+ * @situation a burning projectile that explodes and scorches the ground
79
+ * @situation a wizard's fire attack with a wind-up, a flight and an aftermath
80
+ * @constraint every colour, size, count and timing is a named override on the call
81
+ * @constraint the stock look ships as the default, and no override rebuilds a pipeline
82
+ * @override core, highlight, speed, charge, impact, linger, radius, burst, trail, lingerBurst, light, shake, scorch
83
+ * @example const fireball = createFireball(world);
84
+ * casts.cast(fireball, target);
85
+ */
86
+ export function createFireball(world: SpellWorld, overrides: IFireSpellOverrides = {}) {
87
+ return createSpell(
88
+ world,
89
+ recipe(
90
+ {
91
+ burst: { burst: 26, kind: "spark", style: "spark" },
92
+ core: { intensity: 1.3, radius: 0.34 },
93
+ impact: {
94
+ light: { intensity: 60, range: 14, seconds: 0.45 },
95
+ shake: 0.11,
96
+ shell: { radius: 2.6, seconds: 0.42, strength: 0.85 },
97
+ splat: { char: 0.75, heat: 1, radius: 2.6 },
98
+ },
99
+ linger: { burst: 3, interval: 0.1, kind: "flame", style: "media" },
100
+ name: "fireball",
101
+ radius: 0.35,
102
+ shape: "projectile",
103
+ speed: 18,
104
+ timing: { charge: 0.7, impact: 0.25, linger: 2.6, travel: 2.6 },
105
+ tint: { colour: colour("#ff8a2a"), highlight: colour("#fff2dc") },
106
+ trail: { burst: 2.4, kind: "flame", style: "media" },
107
+ },
108
+ overrides,
109
+ ),
110
+ );
111
+ }
112
+
113
+ /**
114
+ * A bolt out of the sky: it charges, strikes the point instantly and the ground remembers it.
115
+ * @situation a lightning strike spell that hits a point immediately
116
+ * @situation a thunderbolt with a wind-up and a burnt mark where it lands
117
+ * @situation an electrical spell with a column of light from above
118
+ * @override core, highlight, charge, impact, linger, radius, light, shake, scorch
119
+ * @example const bolt = createThunderstrike(world);
120
+ */
121
+ export function createThunderstrike(world: SpellWorld, overrides: IFireSpellOverrides = {}) {
122
+ return createSpell(
123
+ world,
124
+ recipe(
125
+ {
126
+ bolt: { height: 22, seconds: 0.8, width: 0.55 },
127
+ burst: { burst: 30, kind: "spark", style: "spark" },
128
+ charge: { burst: 2, kind: "mote" },
129
+ impact: {
130
+ light: { intensity: 120, range: 20, seconds: 0.5 },
131
+ shake: 0.16,
132
+ shell: { radius: 3.4, seconds: 0.36, strength: 1 },
133
+ splat: { char: 0.9, glow: 0.8, heat: 0.7, pattern: "ring", radius: 3.2 },
134
+ },
135
+ linger: { burst: 1.6, interval: 0.16, kind: "arc", style: "glow" },
136
+ name: "thunderstrike",
137
+ radius: 0.2,
138
+ shape: "strike",
139
+ timing: { charge: 0.6, impact: 0.8, linger: 1.6, travel: 1.8 },
140
+ tint: { colour: colour("#5b78ff"), highlight: colour("#d6e6ff") },
141
+ },
142
+ overrides,
143
+ ),
144
+ );
145
+ }
146
+
147
+ /**
148
+ * A shard of ice that flies flat and fast, and freezes the ground it breaks on.
149
+ * @situation an ice spike spell that flies at a target and shatters
150
+ * @situation a freezing projectile that leaves frost on the floor
151
+ * @situation a cold spell with a charge, a flight and a lingering chill
152
+ * @override core, highlight, speed, charge, impact, linger, radius, burst, trail, light
153
+ * @example const spike = createGlacialSpike(world);
154
+ */
155
+ export function createGlacialSpike(world: SpellWorld, overrides: IFireSpellOverrides = {}) {
156
+ return createSpell(
157
+ world,
158
+ recipe(
159
+ {
160
+ burst: { burst: 28, kind: "ice", style: "glow" },
161
+ charge: { burst: 2, kind: "mote" },
162
+ core: { intensity: 1.1, radius: 0.22 },
163
+ impact: {
164
+ light: { intensity: 40, range: 11, seconds: 0.35 },
165
+ shake: 0.07,
166
+ shell: { radius: 2.2, seconds: 0.38, strength: 0.7 },
167
+ splat: { crack: 0.4, frost: 1, radius: 2.8 },
168
+ },
169
+ linger: { burst: 2, interval: 0.14, kind: "ice", style: "glow" },
170
+ name: "glacial-spike",
171
+ radius: 0.12,
172
+ shape: "projectile",
173
+ speed: 26,
174
+ timing: { charge: 0.8, impact: 0.3, linger: 2.4, travel: 1.4 },
175
+ tint: { colour: colour("#4f9bff"), highlight: colour("#c9f4ff") },
176
+ trail: { burst: 1.8, kind: "ice", style: "glow" },
177
+ },
178
+ overrides,
179
+ ),
180
+ );
181
+ }
182
+
183
+ /**
184
+ * A volley of arcane missiles: fast, precise, and each one pops on arrival.
185
+ * @situation an arcane missile spell that fires several projectiles at a target
186
+ * @situation a magic barrage a mage class spams
187
+ * @situation a pink energy bolt with a short charge
188
+ * @override core, highlight, speed, charge, impact, linger, radius, burst, light
189
+ * @example const barrage = createArcaneBarrage(world);
190
+ */
191
+ export function createArcaneBarrage(world: SpellWorld, overrides: IFireSpellOverrides = {}) {
192
+ return createSpell(
193
+ world,
194
+ recipe(
195
+ {
196
+ burst: { burst: 18, kind: "spark", style: "glow" },
197
+ charge: { burst: 3, kind: "mote" },
198
+ core: { intensity: 1.4, radius: 0.19 },
199
+ impact: {
200
+ light: { intensity: 34, range: 9, seconds: 0.28 },
201
+ shake: 0.05,
202
+ shell: { radius: 1.6, seconds: 0.28, strength: 0.6 },
203
+ splat: { glow: 0.7, heat: 0.2, radius: 1.8 },
204
+ },
205
+ linger: { burst: 1.4, interval: 0.12, kind: "spark", style: "glow" },
206
+ name: "arcane-barrage",
207
+ radius: 0.2,
208
+ shape: "projectile",
209
+ speed: 24,
210
+ timing: { charge: 0.55, impact: 0.12, linger: 1.1, travel: 1.6 },
211
+ tint: { colour: colour("#ff4fd8"), highlight: colour("#ffd8f6") },
212
+ trail: { burst: 2, kind: "spark", style: "glow" },
213
+ },
214
+ overrides,
215
+ ),
216
+ );
217
+ }
218
+
219
+ /**
220
+ * A ward around the caster: it forms, holds, and breaks outward when it expires.
221
+ * @situation a shield spell a player casts on themselves
222
+ * @situation a magic barrier that forms around the caster
223
+ * @situation a defensive bubble that flashes when it breaks
224
+ * @override core, highlight, charge, impact, linger, radius, light, shake
225
+ * @example const aegis = createAegis(world);
226
+ */
227
+ export function createAegis(world: SpellWorld, overrides: IFireSpellOverrides = {}) {
228
+ return createSpell(
229
+ world,
230
+ recipe(
231
+ {
232
+ burst: { burst: 22, kind: "mote", style: "glow" },
233
+ charge: { burst: 3, kind: "mote" },
234
+ impact: {
235
+ light: { intensity: 26, range: 8, seconds: 0.3 },
236
+ shell: { hold: true, radius: 1.9, seconds: 0.6, strength: 1 },
237
+ splat: { glow: 0.4, radius: 1.6 },
238
+ },
239
+ linger: { burst: 1.2, interval: 0.2, kind: "mote", style: "glow" },
240
+ name: "aegis",
241
+ radius: 0.3,
242
+ shape: "self",
243
+ timing: { charge: 0.45, impact: 0.15, linger: 3.4, travel: 0 },
244
+ tint: { colour: colour("#ff4fd8"), highlight: colour("#c9a8ff") },
245
+ },
246
+ overrides,
247
+ ),
248
+ );
249
+ }
250
+
251
+ /**
252
+ * A pillar of fire that erupts where it lands and keeps burning.
253
+ * @situation a fire area spell that erupts at a point and burns there
254
+ * @situation an inferno column a boss drops on the arena
255
+ * @situation a sustained flame that scorches the ground for seconds
256
+ * @override core, highlight, charge, impact, linger, radius, burst, trail, light, shake, scorch
257
+ * @example const inferno = createInferno(world);
258
+ */
259
+ export function createInferno(world: SpellWorld, overrides: IFireSpellOverrides = {}) {
260
+ return createSpell(
261
+ world,
262
+ recipe(
263
+ {
264
+ burst: { burst: 40, kind: "flame", style: "media" },
265
+ charge: { burst: 4, kind: "ember" },
266
+ impact: {
267
+ light: { intensity: 90, range: 18, seconds: 0.9 },
268
+ shake: 0.14,
269
+ shell: { radius: 4.2, seconds: 0.6, strength: 0.9 },
270
+ splat: { char: 1, heat: 1, radius: 4.4 },
271
+ },
272
+ linger: { burst: 5, interval: 0.08, kind: "flame", style: "media" },
273
+ name: "inferno",
274
+ radius: 0.4,
275
+ shape: "area",
276
+ timing: { charge: 0.9, impact: 0.3, linger: 5, travel: 0 },
277
+ tint: { colour: colour("#ff5a12"), highlight: colour("#ffd9a0") },
278
+ trail: { burst: 3, kind: "smoke", style: "media" },
279
+ },
280
+ overrides,
281
+ ),
282
+ );
283
+ }