@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,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
+ }
@@ -0,0 +1,184 @@
1
+ // Ported from Ultra Elements src/engine/camera.js @698b720 (MIT, Copyright (c) 2026 Humpalumps). JavaScript copied verbatim; GLSL transliterated to TSL.
2
+ import { type Camera, Euler, type PerspectiveCamera, Quaternion, Vector3 } from "three";
3
+
4
+ // Camera game feel, all of it on the camera rather than in post:
5
+ // - trauma shake (Eiserloh, "Juicing Your Cameras With Math", GDC 2016): offsets = trauma^2 x Perlin
6
+ // noise, so small hits barely move it and big ones slam. Each source keeps its own frequency
7
+ // (earth rumbles at ~8 Hz, lightning cracks at ~30 Hz) and they mix weighted by trauma.
8
+ // - FOV punch and hitstop (Nijman, "The Art of Screenshake", 2013).
9
+ // apply() goes right after OrbitControls.update() and restore() right before the next one, so the
10
+ // controls never see the offsets and can't accumulate them. No allocations per frame.
11
+
12
+ const DEG = Math.PI / 180;
13
+ const YAW = 2 * DEG;
14
+ const PITCH = 2 * DEG;
15
+ const ROLL = 3 * DEG;
16
+ const MOVE = 0.06; // at trauma 1
17
+ const SOURCES = 4;
18
+ const QUEUE = 8;
19
+
20
+ // 1D gradient noise in [-1, 1] (hashed gradients on the integer lattice, quintic fade)
21
+ function grad(i0: number): number {
22
+ let i = i0;
23
+ i = Math.imul(i ^ (i >>> 16), 0x45d9f3b);
24
+ i = Math.imul(i ^ (i >>> 16), 0x45d9f3b);
25
+ return ((i ^ (i >>> 16)) >>> 0) / 2147483648 - 1;
26
+ }
27
+ function perlin(x: number, seed: number): number {
28
+ const i = Math.floor(x);
29
+ const f = x - i;
30
+ const s = seed * 1013;
31
+ const a = grad(i + s) * f;
32
+ const b = grad(i + 1 + s) * (f - 1);
33
+ return 2 * (a + (b - a) * f * f * f * (f * (f * 6 - 15) + 10));
34
+ }
35
+
36
+ const _q = new Quaternion();
37
+ const _e = new Euler();
38
+
39
+ type RigCamera = Camera & Partial<Pick<PerspectiveCamera, "fov" | "updateProjectionMatrix">>;
40
+
41
+ export class CameraRig {
42
+ reduced = false; // "Reduce flashes & shake": shake x0.25, no hitstop, no punch
43
+ amount = 1; // shake multiplier (GUI)
44
+ decay = 1.5; // trauma lost per second
45
+
46
+ private _src = Array.from({ length: SOURCES }, (_, i) => ({
47
+ trauma: 0,
48
+ freq: 15,
49
+ phase: 0,
50
+ seed: i * 6 + 1,
51
+ }));
52
+ private _queue = Array.from({ length: QUEUE }, () => ({ t: 0, trauma: 0, freq: 15 }));
53
+ private _stop = 0; // hitstop seconds left
54
+ private _punch = { deg: 0, t: 1, dur: 1 };
55
+ private _off = new Vector3(); // what apply() added, for restore()
56
+ private _rot = new Quaternion();
57
+ private _fov = 0;
58
+ private _applied = false;
59
+
60
+ // trauma 0..1 (it adds up and clamps); delay in seconds (thunder: distance / 343)
61
+ // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: upstream Ultra Elements code, copied verbatim
62
+ shake(trauma: number, freqHz = 15, delay = 0): void {
63
+ if (!(trauma > 0)) return;
64
+ if (delay > 0) {
65
+ let slot = this._queue[0] as (typeof this._queue)[number];
66
+ for (const q of this._queue)
67
+ if (q.t <= 0) {
68
+ slot = q;
69
+ break;
70
+ // biome-ignore lint/style/noUselessElse: upstream Ultra Elements code, copied verbatim
71
+ } else if (q.t > slot.t) slot = q; // full: drop the latest
72
+ slot.t = delay;
73
+ slot.trauma = trauma;
74
+ slot.freq = freqHz;
75
+ return;
76
+ }
77
+ // same-ish frequency: same source, trauma adds; else a free slot, else the weakest one
78
+ let slot: (typeof this._src)[number] | null = null;
79
+ let weakest = this._src[0] as (typeof this._src)[number];
80
+ for (const s of this._src) {
81
+ if (s.trauma > 0 && Math.abs(s.freq - freqHz) < 0.2 * freqHz) {
82
+ slot = s;
83
+ break;
84
+ }
85
+ if (s.trauma < weakest.trauma) weakest = s;
86
+ }
87
+ if (!slot) {
88
+ slot = weakest;
89
+ slot.trauma = 0;
90
+ slot.freq = freqHz;
91
+ }
92
+ slot.trauma = Math.min(1, slot.trauma + trauma);
93
+ }
94
+
95
+ // FOV kick: +deg over a frame, then eases back over the rest of `duration`
96
+ punch(deg = 3, duration = 0.08): void {
97
+ if (this.reduced) return;
98
+ const p = this._punch;
99
+ if (p.t < p.dur && Math.abs(p.deg) * (1 - p.t / p.dur) > Math.abs(deg)) return; // a bigger one is still running
100
+ p.deg = deg;
101
+ p.t = 0;
102
+ p.dur = Math.max(duration, 1e-3);
103
+ }
104
+
105
+ hitstop(seconds: number): void {
106
+ if (!this.reduced) this._stop = Math.max(this._stop, seconds);
107
+ }
108
+
109
+ // main multiplies the simulation dt by this
110
+ get timeScale(): number {
111
+ return this._stop > 0 && !this.reduced ? 0.05 : 1;
112
+ }
113
+
114
+ // dt: real (unscaled) seconds; the shake keeps going through hitstop
115
+ // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: upstream Ultra Elements code, copied verbatim
116
+ apply(camera: RigCamera, dt0: number): void {
117
+ this.restore(camera); // in case restore() was skipped
118
+ const dt = dt0 > 0 ? Math.min(dt0, 0.1) : 0;
119
+ // biome-ignore lint/suspicious/noAssignInExpressions: upstream Ultra Elements code, copied verbatim
120
+ for (const q of this._queue) if (q.t > 0 && (q.t -= dt) <= 0) this.shake(q.trauma, q.freq);
121
+ this._stop = Math.max(0, this._stop - dt);
122
+
123
+ let total = 0;
124
+ let yaw = 0;
125
+ let pitch = 0;
126
+ let roll = 0;
127
+ let x = 0;
128
+ let y = 0;
129
+ let z = 0;
130
+ for (const s of this._src) {
131
+ if (s.trauma <= 0) continue;
132
+ s.phase = (s.phase + s.freq * dt) % 65536;
133
+ const w = s.trauma;
134
+ const t = s.phase;
135
+ total += w;
136
+ yaw += w * perlin(t, s.seed);
137
+ pitch += w * perlin(t, s.seed + 1);
138
+ roll += w * perlin(t, s.seed + 2);
139
+ x += w * perlin(t, s.seed + 3);
140
+ y += w * perlin(t, s.seed + 4);
141
+ z += w * perlin(t, s.seed + 5);
142
+ s.trauma = Math.max(0, s.trauma - this.decay * dt);
143
+ }
144
+
145
+ this._off.set(0, 0, 0);
146
+ this._rot.identity();
147
+ if (total > 0) {
148
+ const tr = Math.min(total, 1);
149
+ const k = (tr * tr * this.amount * (this.reduced ? 0.25 : 1)) / total;
150
+ this._rot.setFromEuler(_e.set(pitch * k * PITCH, yaw * k * YAW, roll * k * ROLL, "YXZ"));
151
+ camera.quaternion.multiply(this._rot);
152
+ this._off
153
+ .set(x, y, z)
154
+ .multiplyScalar(k * MOVE)
155
+ .applyQuaternion(camera.quaternion);
156
+ camera.position.add(this._off);
157
+ }
158
+
159
+ const p = this._punch;
160
+ this._fov = 0;
161
+ if (p.t < p.dur && !this.reduced) {
162
+ const u = p.t / p.dur;
163
+ this._fov = p.deg * (u < 0.2 ? u / 0.2 : ((1 - u) / 0.8) ** 2);
164
+ p.t += dt;
165
+ }
166
+ if (this._fov !== 0 && camera.fov !== undefined) {
167
+ camera.fov += this._fov;
168
+ camera.updateProjectionMatrix?.();
169
+ }
170
+ this._applied = true;
171
+ }
172
+
173
+ // takes back exactly what apply() added (subtracting, so camera jumps made in between survive)
174
+ restore(camera: RigCamera): void {
175
+ if (!this._applied) return;
176
+ this._applied = false;
177
+ camera.position.sub(this._off);
178
+ camera.quaternion.multiply(_q.copy(this._rot).invert());
179
+ if (this._fov !== 0 && camera.fov !== undefined) {
180
+ camera.fov -= this._fov;
181
+ camera.updateProjectionMatrix?.();
182
+ }
183
+ }
184
+ }
@@ -0,0 +1,96 @@
1
+ // Ported from Ultra Elements src/engine/quality.js @698b720 (MIT, Copyright (c) 2026 Humpalumps). JavaScript copied verbatim; GLSL transliterated to TSL.
2
+ // Engine: the tier comes from `?q=` when there is a location; there is no `matchMedia` probe on the
3
+ // native host, so `mobile` is `?mobile` only.
4
+
5
+ // Quality tiers. Spells author counts at High; emission is multiplied by Q.emission (tier x auto).
6
+ // Anything here that changes a shader define or a target size only changes on an explicit tier
7
+ // switch (main.js shows "Recompiling…"); the auto ladder only touches uniforms and sizes.
8
+ export const TIERS = {
9
+ low: {
10
+ resolution: 0.6,
11
+ msaa: 2,
12
+ fxScale: 0.5,
13
+ particles: [256, 128],
14
+ debris: 512,
15
+ volumeSteps: 12,
16
+ noiseSize: 64,
17
+ groundSize: 512,
18
+ reflections: false,
19
+ reflectionScale: 0.35,
20
+ reflectFx: false,
21
+ maxLights: 8,
22
+ shadowLights: 0,
23
+ bloomLevels: 3,
24
+ emission: 0.35,
25
+ fluidIterations: 6,
26
+ },
27
+ medium: {
28
+ resolution: 0.85,
29
+ msaa: 4,
30
+ fxScale: 0.5,
31
+ particles: [512, 256],
32
+ debris: 2048,
33
+ volumeSteps: 16,
34
+ noiseSize: 128,
35
+ groundSize: 1024,
36
+ reflections: false,
37
+ reflectionScale: 0.35,
38
+ reflectFx: false,
39
+ maxLights: 16,
40
+ shadowLights: 1,
41
+ bloomLevels: 6,
42
+ emission: 0.7,
43
+ },
44
+ high: {
45
+ resolution: 1,
46
+ msaa: 4,
47
+ fxScale: 0.5,
48
+ particles: [512, 512],
49
+ debris: 4096,
50
+ volumeSteps: 24,
51
+ noiseSize: 128,
52
+ groundSize: 1024,
53
+ reflections: false,
54
+ reflectionScale: 0.35,
55
+ reflectFx: true,
56
+ maxLights: 16,
57
+ shadowLights: 4,
58
+ bloomLevels: 6,
59
+ emission: 1,
60
+ },
61
+ ultra: {
62
+ resolution: 1,
63
+ msaa: 4,
64
+ fxScale: 1,
65
+ particles: [1024, 1024],
66
+ debris: 8192,
67
+ volumeSteps: 32,
68
+ noiseSize: 128,
69
+ groundSize: 2048,
70
+ reflections: false,
71
+ reflectionScale: 0.5,
72
+ reflectFx: true,
73
+ maxLights: 16,
74
+ shadowLights: 4,
75
+ bloomLevels: 6,
76
+ emission: 1.6,
77
+ fluid: true,
78
+ anamorphic: true,
79
+ },
80
+ };
81
+ export type TierName = keyof typeof TIERS;
82
+
83
+ const args = new URLSearchParams(globalThis.location?.search ?? "");
84
+ export const mobile = args.has("mobile");
85
+ const asked = args.get("q");
86
+ export const tierName: TierName =
87
+ asked !== null && asked in TIERS ? (asked as TierName) : mobile ? "low" : "high";
88
+
89
+ // live values; auto scales multiply on top (auto.emission, auto.steps)
90
+ export const Q = {
91
+ tier: tierName,
92
+ mobile,
93
+ ...TIERS[tierName],
94
+ autoResolution: mobile,
95
+ auto: { emission: 1, steps: 1 },
96
+ };
@@ -0,0 +1,52 @@
1
+ // Ultra Elements (MIT, Copyright (c) 2026 Humpalumps), ported @698b720: the shared foundation every
2
+ // ported spell module builds on, and the spells ported so far. Only what a game calls is public;
3
+ // ported spell modules import the TSL chunks, Volumes and FxTarget by relative path.
4
+ export { Q, TIERS } from "./engine/quality.js";
5
+ /**
6
+ * The shared Ultra Elements spell world: casts, volumes, spell lights and the per-frame CPU tick.
7
+ * Add `fx.scenes.fx` to the scene, `addSpell` each ported spell, call `renderFrame(dt)` each frame.
8
+ * @situation an Ultra Elements spell such as the raymarched teardrop Fireball cast at a target
9
+ * @situation a volumetric fire spell drawn through the Three.js TSL node API on WebGPU
10
+ * @constraint call bakeNoise first: the volume shaders sample its noise, curl and blackbody textures
11
+ * @example const ultra = createFx({ camera, size: () => ({ width: innerWidth, height: innerHeight }), seed: 777 }); const fireball = ultra.addSpell(fire); scene.add(ultra.fx.scenes.fx);
12
+ */
13
+ export {
14
+ createFx,
15
+ type Fx,
16
+ type IFxOptions,
17
+ type ITrail,
18
+ type ITrails,
19
+ type IShocks,
20
+ type IGround,
21
+ type IFluid,
22
+ type IFluidDomain,
23
+ type IRig,
24
+ type IArena,
25
+ type IDummy,
26
+ } from "./main.js";
27
+ export type { ICast, ISpell, ISpellInstance, Phase } from "./spells/cast.js";
28
+ export { default as fire } from "./spells/fire.js";
29
+ /** The fixed arena layout the spells and the ground field read (floor, pool, dummies, caster focus). */
30
+ export { ARENA, U } from "./vfx/common.js";
31
+ /**
32
+ * The Ultra Elements arena floor's response to the ground field and spell impacts (scorch, char, wet,
33
+ * glowing hot ground) as nodes for a game's own floor material: `color`, `roughness`, `metalness`,
34
+ * `emissive` from the floor's own surface at a world position.
35
+ * @situation a floor that shows the Fireball's scorch and hot ground cooling over seconds
36
+ * @example const shade = groundShade(positionWorld, { albedo, rough: float(0.85), metal: float(0) }); floor.colorNode = vec4(shade.color, 1);
37
+ */
38
+ export { groundShade, type IGroundSurface } from "./scene/arenaMaterial.js";
39
+ /**
40
+ * The Ultra Elements GPU particle system behind `fx.particles`: a spell's kinds, emitters and field emitters.
41
+ * @situation the flames, embers, sparks, smoke and debris an Ultra Elements spell emits as it charges, flies and hits
42
+ * @example const flames = ultra.fx.particles.emitter("fire.flame"); // ultra from createFx
43
+ */
44
+ export { Particles } from "./vfx/Particles.js";
45
+ export type { IEmitter, KindDef } from "./vfx/Particles.js";
46
+ /**
47
+ * CPU bake of the Ultra Elements 3D noise, curl and blackbody textures that every spell volume samples.
48
+ * @situation the noise and blackbody textures an Ultra Elements spell needs before it first draws
49
+ * @constraint costs about 0.6 s at 64^3 and about 5 s at 128^3 on the main thread; bake once at load
50
+ * @example bakeNoise({ noiseSize: 64 }); // once at load, before createFx draws
51
+ */
52
+ export { bakeNoise, type IBakedNoise } from "./vfx/noise.js";