@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,489 @@
1
+ import {
2
+ Break,
3
+ Fn,
4
+ If,
5
+ Loop,
6
+ cameraPosition,
7
+ clamp,
8
+ dot,
9
+ exp,
10
+ float,
11
+ int,
12
+ length,
13
+ max,
14
+ min,
15
+ mix,
16
+ normalize,
17
+ positionWorld,
18
+ select,
19
+ sqrt,
20
+ uniform,
21
+ vec2,
22
+ vec3,
23
+ vec4,
24
+ } from "three/tsl";
25
+ // Ported from Ultra Elements src/vfx/Volumes.js @698b720 (MIT, Copyright (c) 2026 Humpalumps). JavaScript copied verbatim; GLSL transliterated to TSL.
26
+ import {
27
+ BackSide,
28
+ BoxGeometry,
29
+ type BufferGeometry,
30
+ type Camera,
31
+ Group,
32
+ IcosahedronGeometry,
33
+ Matrix3,
34
+ Matrix4,
35
+ Mesh,
36
+ MeshBasicNodeMaterial,
37
+ type PerspectiveCamera,
38
+ Quaternion,
39
+ Vector3,
40
+ Vector4,
41
+ } from "three/webgpu";
42
+ import type { Node } from "three/webgpu";
43
+ import { Q } from "../engine/quality.js";
44
+ import {
45
+ FX_BLENDING,
46
+ type IMat3Rows,
47
+ U,
48
+ closestOnSegment,
49
+ fxOut,
50
+ hgPhase,
51
+ mat3Rows,
52
+ mulMat3Rows,
53
+ sceneViewZ,
54
+ setMat3Rows,
55
+ spellLight,
56
+ spellLightScatter,
57
+ } from "./common.js";
58
+
59
+ type F = Node<"float">;
60
+ type V3 = Node<"vec3">;
61
+
62
+ // Raymarched hero volumes (PLAN 2.5 "Volumes"). Each volume is a proxy mesh in the fx scene whose
63
+ // BACK faces are drawn (so the camera can be inside) with the depth test off (a back face behind the
64
+ // floor must not hide the part of the volume in front of it); the shader intersects the true shape
65
+ // analytically and marches from entry to min(exit, scene depth).
66
+ //
67
+ // Spells supply the medium:
68
+ // void volumeSample(vec3 pw, vec3 pl, out float sigma, out vec3 albedo, out vec3 emission)
69
+ // pw world position, pl local position (-1..1 over the shape's half extents)
70
+ // sigma extinction (1/m)
71
+ // albedo single-scattering albedo
72
+ // emission emitted radiance per metre (HDR); integrated as T * E * (1 - exp(-sigma dt)) / sigma
73
+ // with COMMON, NOISE (noise3/fbm3/blackbody), ARENA and LIGHTS GLSL available, plus the uniforms
74
+ // below (uVolScale etc.).
75
+ // TSL: volumeSample(pw, pl, sigma, albedo, emission, V) with sigma/albedo/emission var nodes to assign
76
+ // and V the scope GLSL had: this volume's uniforms (V.uVolRot as rows: mulMat3Rows(V.uVolRot, v)), the
77
+ // spell's own uniforms, and V.gVolDt.
78
+ //
79
+ // Integration is per-slab energy conserving (Hillaire 2015). Lighting per occupied sample:
80
+ // sun HG phase (g), shadowed by ONE extra density tap towards the sun (optical depth =
81
+ // trapezoid over the tap), plus a 0.25-strength wide lobe standing in for multiple
82
+ // scattering (after Wrenninge's octaves)
83
+ // ambient uAmbient, dimmed by the sun tap's optical depth
84
+ // spells spellLightScatter (no capsule shadows: gLightNoShadow), all attenuated by one tap
85
+ // towards the brightest spell light (light 0; packWorld sorts brightest first), so smoke
86
+ // over a fireball is lit from below and dark on top
87
+ // Lighting is evaluated on every 2nd occupied sample and held in between (it varies much more
88
+ // slowly than density); the two shadow taps alternate, so each refreshes every 4th sample. That
89
+ // keeps the march at ~1.5 density evaluations per step. Samples with zero albedo (pure fire, soot)
90
+ // skip lighting entirely.
91
+ // Step count = clamp(radiusPx / 5, 8, min(maxSteps, Q.volumeSteps * Q.auto.steps)), radiusPx in
92
+ // FX-target pixels, set per frame by update(). Samples are combined as trapezoid slabs (sigma,
93
+ // albedo and emission averaged over each slab's two ends), which removes the step banding; there is
94
+ // NO per-pixel jitter: at half res without TAA any jitter turns into a fixed dither pattern ("grid of
95
+ // dots") on high-frequency media. gVolDt (this ray's step) lets volumeSample fade noise octaves the
96
+ // march can't resolve.
97
+
98
+ // Every lookup in a march is LOD 0 (the noise, curl and blackbody textures have no mips anyway):
99
+ // common.ts samples them with level 0 throughout (upstream's NO_GRADIENTS define).
100
+
101
+ const ownUniforms = () => ({
102
+ uVolCenter: uniform(new Vector3()),
103
+ uVolRot: mat3Rows(), // world -> shape axes
104
+ uVolScale: uniform(new Vector3(1, 1, 1)), // half extents (m)
105
+ uVolSteps: uniform(8),
106
+ uVolLight: uniform(new Vector4(0.3, 0.3, 1, 1)), // HG g, sun tap distance (m), ambient gain, sun gain
107
+ });
108
+ type IOwnUniforms = ReturnType<typeof ownUniforms>;
109
+ export interface IVolumeScope extends IOwnUniforms {
110
+ // this ray's step length (m), readable from volumeSample: fade noise octaves finer than ~2 steps
111
+ // (they can't be resolved and only turn into per-pixel grain)
112
+ readonly gVolDt: F;
113
+ // the spell's own uniforms (Volumes.add({ uniforms }))
114
+ readonly [uniform: string]: unknown;
115
+ }
116
+ export type VolumeSample = (
117
+ pw: V3,
118
+ pl: V3,
119
+ sigma: F,
120
+ albedo: V3,
121
+ emission: V3,
122
+ V: IVolumeScope,
123
+ ) => void;
124
+
125
+ // entry/exit distances along a unit ray in shape space (rotated, unscaled, so t is metres)
126
+ function volumeHitFor(shape: number, uVolScale: V3) {
127
+ if (shape === 0) {
128
+ return Fn(([o, d]: [V3, V3]) => {
129
+ // ellipsoid
130
+ const out = vec2(1.0, -1.0).toVar();
131
+ const oc = o.div(uVolScale);
132
+ const rd = d.div(uVolScale);
133
+ const a = dot(rd, rd);
134
+ const b = dot(oc, rd);
135
+ const c = dot(oc, oc).sub(1.0);
136
+ const h = b.mul(b).sub(a.mul(c));
137
+ If(h.greaterThanEqual(0.0), () => {
138
+ const hs = sqrt(h);
139
+ out.assign(vec2(b.negate().sub(hs), b.negate().add(hs)).div(a));
140
+ });
141
+ return out;
142
+ });
143
+ }
144
+ if (shape === 1) {
145
+ return Fn(([o, d]: [V3, V3]) => {
146
+ // box
147
+ const dd = vec3(
148
+ select(d.x.abs().lessThan(1e-6), float(1e-6), d.x),
149
+ select(d.y.abs().lessThan(1e-6), float(1e-6), d.y),
150
+ select(d.z.abs().lessThan(1e-6), float(1e-6), d.z),
151
+ );
152
+ const m = vec3(1.0).div(dd);
153
+ const n = m.mul(o);
154
+ const k = m.abs().mul(uVolScale);
155
+ const t1 = n.negate().sub(k);
156
+ const t2 = n.negate().add(k);
157
+ return vec2(max(max(t1.x, t1.y), t1.z), min(min(t2.x, t2.y), t2.z));
158
+ });
159
+ }
160
+ // capsule along y: radius uVolScale.x, half length uVolScale.y including the caps.
161
+ // Near hit after Inigo Quilez (MIT); the far hit is the near hit of the reversed ray.
162
+ const capsuleNear = Fn(([ro, rd, hy, ra]: [V3, V3, F, F]) => {
163
+ const res = float(-1.0).toVar();
164
+ const ba = vec3(0.0, hy.mul(2.0), 0.0);
165
+ const oa = ro.sub(vec3(0.0, hy.negate(), 0.0));
166
+ const baba = dot(ba, ba);
167
+ const bard = dot(ba, rd);
168
+ const baoa = dot(ba, oa);
169
+ const rdoa = dot(rd, oa);
170
+ const oaoa = dot(oa, oa);
171
+ const a = baba.sub(bard.mul(bard));
172
+ const b = baba.mul(rdoa).sub(baoa.mul(bard));
173
+ const c = baba.mul(oaoa).sub(baoa.mul(baoa)).sub(ra.mul(ra).mul(baba));
174
+ const h = b.mul(b).sub(a.mul(c));
175
+ If(h.greaterThanEqual(0.0), () => {
176
+ const t = b.negate().sub(sqrt(h)).div(a);
177
+ const y = baoa.add(t.mul(bard));
178
+ If(y.greaterThan(0.0).and(y.lessThan(baba)), () => {
179
+ res.assign(t);
180
+ }).Else(() => {
181
+ const oc = select(y.lessThanEqual(0.0), oa, ro.sub(vec3(0.0, hy, 0.0)));
182
+ const b2 = dot(rd, oc);
183
+ const c2 = dot(oc, oc).sub(ra.mul(ra));
184
+ const h2 = b2.mul(b2).sub(c2);
185
+ If(h2.greaterThan(0.0), () => {
186
+ res.assign(b2.negate().sub(sqrt(h2)));
187
+ });
188
+ });
189
+ });
190
+ return res;
191
+ });
192
+ return Fn(([o, d]: [V3, V3]) => {
193
+ const out = vec2(1.0, -1.0).toVar();
194
+ const ra = uVolScale.x;
195
+ const hy = max(uVolScale.y.sub(ra), 1e-4);
196
+ const far = length(o).add(uVolScale.y.add(ra).mul(2.0));
197
+ const tb = capsuleNear(o.add(d.mul(far)), d.negate(), hy, ra);
198
+ If(tb.greaterThanEqual(0.0), () => {
199
+ const qy = o.y.sub(clamp(o.y, hy.negate(), hy));
200
+ const q = vec3(o.x, qy, o.z);
201
+ out.assign(
202
+ vec2(
203
+ select(dot(q, q).lessThan(ra.mul(ra)), float(0.0), capsuleNear(o, d, hy, ra)),
204
+ far.sub(tb),
205
+ ),
206
+ );
207
+ });
208
+ return out;
209
+ });
210
+ }
211
+
212
+ // engine: GLSL read the camera's forward axis from viewMatrix; set once per frame by update()
213
+ const uCamForward = uniform(new Vector3(0, 0, -1));
214
+
215
+ function volumeMain(
216
+ shape: number,
217
+ own: IOwnUniforms,
218
+ extra: Record<string, unknown>,
219
+ volumeSample: VolumeSample,
220
+ ) {
221
+ const { uVolCenter, uVolRot, uVolScale, uVolSteps, uVolLight } = own;
222
+ const volumeHit = volumeHitFor(shape, uVolScale);
223
+ return Fn(() => {
224
+ // gLightNoShadow = true: spellLightScatter(..., noShadow) below
225
+ const out = vec4(0.0).toVar();
226
+ const rd = normalize(positionWorld.sub(cameraPosition)).toVar();
227
+ const o = mulMat3Rows(uVolRot, cameraPosition.sub(uVolCenter)).toVar();
228
+ const d = mulMat3Rows(uVolRot, rd).toVar();
229
+ const hit = volumeHit(o, d).toVar();
230
+ const cosV = dot(rd, uCamForward).toVar();
231
+ const t0 = max(hit.x, 0.0).toVar();
232
+ const t1 = min(hit.y, sceneViewZ().div(cosV)).toVar();
233
+ If(t1.greaterThan(t0), () => {
234
+ // else discard
235
+ const steps = int(uVolSteps).toVar();
236
+ const dt = t1.sub(t0).div(float(steps)).toVar();
237
+ const gVolDt = dt.toVar();
238
+ const V: IVolumeScope = { ...extra, ...own, gVolDt };
239
+ // samples sit at t0 + (i + j) dt; slabs run between them (trapezoid), plus a j dt slab in
240
+ // front of the first sample and a (1 - j) dt one behind the last, so [t0, t1] is covered exactly
241
+ const j = 0.5;
242
+ const t = t0.add(dt.mul(j)).toVar();
243
+ const len = dt.mul(j).toVar();
244
+ const tap = uVolLight.y;
245
+ const tapS = mulMat3Rows(uVolRot, U.uSunDir).mul(tap);
246
+ const sunPhase = hgPhase(dot(U.uSunDir, rd), uVolLight.x).mul(4.0 * Math.PI);
247
+ const sun = U.uSunColor.mul(uVolLight.w).mul(sunPhase);
248
+ const amb = U.uAmbient.mul(uVolLight.z);
249
+ const scat = vec3(0.0).toVar();
250
+ const emit = vec3(0.0).toVar();
251
+ const Lin = vec3(0.0).toVar();
252
+ const T = float(1.0).toVar();
253
+ const zSum = float(0.0).toVar();
254
+ const wSum = float(0.0).toVar();
255
+ const odSun = float(0.0).toVar();
256
+ const odL = float(0.0).toVar();
257
+ const s2 = float(0.0).toVar();
258
+ const a2 = vec3(0.0).toVar();
259
+ const e2 = vec3(0.0).toVar();
260
+ const sP = float(0.0).toVar();
261
+ const aP = vec3(0.0).toVar();
262
+ const eP = vec3(0.0).toVar(); // previous sample
263
+ const hasLight = U.uWorldCounts.x.greaterThan(0.5);
264
+ const lit = int(0).toVar();
265
+ const sigma = float(0.0).toVar();
266
+ const albedo = vec3(0.0).toVar();
267
+ const e = vec3(0.0).toVar();
268
+ Loop({ start: 0, end: 64, type: "int", condition: "<=" }, ({ i }: { i: Node<"int"> }) => {
269
+ If(i.greaterThan(steps).or(T.lessThan(0.01)), () => {
270
+ Break();
271
+ });
272
+ sigma.assign(sP);
273
+ albedo.assign(aP);
274
+ e.assign(eP);
275
+ If(i.lessThan(steps), () => {
276
+ const ps = o.add(d.mul(t));
277
+ const pw = cameraPosition.add(rd.mul(t));
278
+ volumeSample(pw, ps.div(uVolScale), sigma, albedo, e, V);
279
+ If(sigma.greaterThan(1e-4), () => {
280
+ // lighting on every 2nd occupied sample, held in between; the shadow taps alternate between
281
+ // the sun and the brightest spell light (packWorld sorts it first), both on the first sample
282
+ const k = lit.bitAnd(3);
283
+ If(
284
+ k
285
+ .bitAnd(1)
286
+ .equal(0)
287
+ .and(max(albedo.r, max(albedo.g, albedo.b)).greaterThan(1e-3)),
288
+ () => {
289
+ If(k.equal(0), () => {
290
+ volumeSample(
291
+ pw.add(U.uSunDir.mul(tap)),
292
+ ps.add(tapS).div(uVolScale),
293
+ s2,
294
+ a2,
295
+ e2,
296
+ V,
297
+ );
298
+ odSun.assign(sigma.add(s2).mul(tap));
299
+ });
300
+ If(hasLight.and(k.equal(2).or(lit.equal(0))), () => {
301
+ const L0 = spellLight(int(0));
302
+ const lp = select(L0.type.equal(1), closestOnSegment(L0.pos, L0.end, pw), L0.pos);
303
+ const ld0 = lp.sub(pw);
304
+ const ll = length(ld0);
305
+ const dl = min(tap, ll.mul(0.5)); // never tap past the light itself
306
+ const ld = ld0.mul(dl.div(max(ll, 1e-4)));
307
+ volumeSample(
308
+ pw.add(ld),
309
+ ps.add(mulMat3Rows(uVolRot, ld)).div(uVolScale),
310
+ s2,
311
+ a2,
312
+ e2,
313
+ V,
314
+ );
315
+ odL.assign(sigma.add(s2).mul(dl));
316
+ });
317
+ Lin.assign(
318
+ sun
319
+ .mul(exp(odSun.negate()).add(exp(odSun.mul(-0.25)).mul(0.25)))
320
+ .add(amb.mul(mix(0.35, 1.0, exp(odSun.mul(-0.5)))))
321
+ .add(
322
+ spellLightScatter(pw, rd.negate(), uVolLight.x, true).mul(
323
+ exp(odL.negate()).add(exp(odL.mul(-0.25)).mul(0.25)),
324
+ ),
325
+ ),
326
+ );
327
+ },
328
+ );
329
+ lit.addAssign(1);
330
+ });
331
+ }).Else(() => {
332
+ len.assign(dt.mul(1.0 - j));
333
+ });
334
+ // trapezoid slab: the mean of its two end samples, so a density edge between two samples
335
+ // contributes in proportion to where it falls (rectangle slabs turn it into contour bands)
336
+ const first = i.equal(0);
337
+ const sg = select(first, sigma, sigma.add(sP).mul(0.5)).toVar();
338
+ const eg = select(first, e, e.add(eP).mul(0.5)).toVar();
339
+ const ag = select(first, albedo, albedo.add(aP).mul(0.5)).toVar();
340
+ sP.assign(sigma);
341
+ aP.assign(albedo);
342
+ eP.assign(e);
343
+ If(sg.greaterThan(1e-4), () => {
344
+ const Tr = exp(sg.negate().mul(len));
345
+ const a = T.mul(float(1.0).sub(Tr));
346
+ scat.addAssign(ag.mul(Lin).mul(a));
347
+ emit.addAssign(eg.div(sg).mul(a));
348
+ zSum.addAssign(t.sub(len.mul(0.5)).mul(a));
349
+ wSum.addAssign(a);
350
+ T.mulAssign(Tr);
351
+ }).Else(() => {
352
+ emit.addAssign(eg.mul(T).mul(len));
353
+ });
354
+ t.addAssign(dt);
355
+ len.assign(dt);
356
+ });
357
+ const alpha = float(1.0).sub(T);
358
+ If(alpha.greaterThanEqual(0.002).or(dot(emit, emit).greaterThanEqual(1e-6)), () => {
359
+ // else discard
360
+ const z = select(wSum.greaterThan(0.0), zSum.div(wSum), t0).mul(cosV);
361
+ out.assign(fxOut(scat.div(max(alpha, 1e-4)), alpha, emit, vec2(0.0), z));
362
+ });
363
+ });
364
+ return out;
365
+ })();
366
+ }
367
+
368
+ const SHAPES = { sphere: 0, box: 1, capsule: 2 };
369
+
370
+ // icosphere scaled so its faces (not just its vertices) enclose the unit sphere
371
+ function sphereProxy(): BufferGeometry {
372
+ const g = new IcosahedronGeometry(1, 2);
373
+ const p = g.attributes.position as unknown as {
374
+ count: number;
375
+ getX(i: number): number;
376
+ getY(i: number): number;
377
+ getZ(i: number): number;
378
+ };
379
+ const a = new Vector3();
380
+ const b = new Vector3();
381
+ const c = new Vector3();
382
+ const n = new Vector3();
383
+ let inner = 1;
384
+ for (let i = 0; i < p.count; i += 3) {
385
+ a.set(p.getX(i), p.getY(i), p.getZ(i));
386
+ b.set(p.getX(i + 1), p.getY(i + 1), p.getZ(i + 1));
387
+ c.set(p.getX(i + 2), p.getY(i + 2), p.getZ(i + 2));
388
+ n.subVectors(c, b).cross(a.clone().sub(b)).normalize();
389
+ inner = Math.min(inner, Math.abs(n.dot(a)));
390
+ }
391
+ return g.scale(1.01 / inner, 1.01 / inner, 1.01 / inner);
392
+ }
393
+
394
+ const _p = new Vector3();
395
+ const _q = new Quaternion();
396
+ const _s = new Vector3();
397
+ const _m = new Matrix4();
398
+ const _r = new Matrix3();
399
+
400
+ export interface IVolumeHandle {
401
+ mesh: Mesh;
402
+ position: Vector3;
403
+ scale: Vector3;
404
+ quaternion: Quaternion;
405
+ uniforms: Record<string, unknown> & IOwnUniforms;
406
+ visible: boolean;
407
+ maxSteps: number;
408
+ g: number; // HG asymmetry (sun and spell lights)
409
+ shadowTap: number; // sun-shadow tap distance, fraction of the smallest half extent
410
+ ambient: number;
411
+ sun: number;
412
+ }
413
+
414
+ export class Volumes {
415
+ readonly group = new Group(); // add once to the fx scene
416
+ readonly list: IVolumeHandle[] = [];
417
+ readonly proxies: Record<keyof typeof SHAPES, BufferGeometry>;
418
+
419
+ constructor() {
420
+ const box = new BoxGeometry(2, 2, 2);
421
+ this.proxies = { sphere: sphereProxy(), box, capsule: box };
422
+ }
423
+
424
+ // At load only (one program per call). Returns a plain handle; set its fields each frame.
425
+ add({
426
+ shape = "sphere",
427
+ tsl,
428
+ uniforms = {},
429
+ maxSteps = 32,
430
+ }: {
431
+ shape?: keyof typeof SHAPES;
432
+ tsl: VolumeSample;
433
+ uniforms?: Record<string, unknown>;
434
+ maxSteps?: number;
435
+ }): IVolumeHandle {
436
+ const own = ownUniforms();
437
+ const material = new MeshBasicNodeMaterial({
438
+ ...FX_BLENDING,
439
+ depthTest: false,
440
+ side: BackSide,
441
+ });
442
+ material.fog = false;
443
+ material.fragmentNode = volumeMain(SHAPES[shape], own, uniforms, tsl);
444
+ const mesh = new Mesh(this.proxies[shape], material);
445
+ mesh.visible = false;
446
+ mesh.frustumCulled = false;
447
+ mesh.renderOrder = 10;
448
+ this.group.add(mesh);
449
+ const h: IVolumeHandle = {
450
+ mesh,
451
+ position: mesh.position,
452
+ scale: mesh.scale,
453
+ quaternion: mesh.quaternion,
454
+ uniforms: { ...U, ...own, ...uniforms },
455
+ visible: false,
456
+ maxSteps,
457
+ g: 0.3, // HG asymmetry (sun and spell lights)
458
+ shadowTap: 0.3, // sun-shadow tap distance, fraction of the smallest half extent
459
+ ambient: 1,
460
+ sun: 1,
461
+ };
462
+ this.list.push(h);
463
+ return h;
464
+ }
465
+
466
+ update(camera: Camera): void {
467
+ camera.getWorldDirection(uCamForward.value);
468
+ const cap = Math.max(4, Math.floor(Math.min(Q.volumeSteps * Q.auto.steps, 64)));
469
+ const pxPerM =
470
+ // biome-ignore lint/style/noNonNullAssertion: upstream Ultra Elements code, copied verbatim
471
+ 0.5 * U.uFxResolution.value.y * (camera as PerspectiveCamera).projectionMatrix.elements[5]!;
472
+ for (const h of this.list) {
473
+ const m = h.mesh;
474
+ const u = h.uniforms;
475
+ m.visible = h.visible;
476
+ if (!h.visible) continue;
477
+ m.updateMatrixWorld();
478
+ m.matrixWorld.decompose(_p, _q, _s);
479
+ u.uVolCenter.value.copy(_p);
480
+ u.uVolScale.value.copy(_s);
481
+ setMat3Rows(u.uVolRot, _r.setFromMatrix4(_m.makeRotationFromQuaternion(_q.invert())));
482
+ u.uVolLight.value.set(h.g, h.shadowTap * Math.min(_s.x, _s.y, _s.z), h.ambient, h.sun);
483
+ const r = Math.max(_s.x, _s.y, _s.z);
484
+ const dist = _p.distanceTo(camera.position);
485
+ const px = dist > r ? (r * pxPerM) / dist : Number.POSITIVE_INFINITY;
486
+ u.uVolSteps.value = Math.min(h.maxSteps, cap, Math.max(8, Math.ceil(px / 5)));
487
+ }
488
+ }
489
+ }