@umicat/three-sdk 1.36.0 → 1.38.0

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.
package/README.md CHANGED
@@ -89,8 +89,30 @@ cannot load.
89
89
 
90
90
  `parseVfx` accepts version-1 documents (1.35's upward-firing disc) and
91
91
  upgrades them to the v2 emitter that plays the same, and fills every emitter
92
- field a document leaves out from `emitterDefaults()`. The editor and the agent
93
- always write version 2, which **needs 1.36.0 to play**.
92
+ field a document leaves out from `emitterDefaults()`.
93
+
94
+ **The effect material (version 3, 1.37.0, ADR-055).** `look: { type:
95
+ 'material', material }` draws a particle with up to three masks — procedural
96
+ noise (perlin / value / cellular / cell edges, fbm / ridged / ping-pong,
97
+ domain warp; generated in the browser and tileable), a gradient, a shape or an
98
+ image — each scaled, scrolled, spun, optionally polar, reshaped (`levels`) and
99
+ offset, combined with Binbun's twelve blend modes; then dissolve, an alpha
100
+ ramp, a gradient map for colour, an optional glowing edge, and HDR emission.
101
+ `dissolve`, `threshold`, `opacity`, `emission` and each mask's `strength` /
102
+ `offset` are a number or `{ overLife: Curve }`. See `src/vfx/material.ts`.
103
+
104
+ **Meshes (version 4, 1.38.0, ADR-055 step 2).** `meshes: [...]` places Godot's
105
+ primitive meshes (quad, plane, sphere, cylinder/cone, torus, box, flat ring)
106
+ in the effect, each shown for a `start`/`life` window of the cycle with scale,
107
+ colour and alpha over that life and drawn with a material; `emitter.mesh`
108
+ draws every particle as such a mesh (`size` scales it; it stands on its
109
+ velocity with `align: velocity`). Materials gained rim (fresnel),
110
+ displacement, a cutout threshold and a band gradient; emitters gained
111
+ per-axis `sizeOverLifeXYZ`. Meshes draw before particles.
112
+
113
+ **Write the lowest version.** `minimumVersion(doc)` is 4 with meshes, 3 with a
114
+ material, else 2; the editor and the agent write that, so an effect that needs nothing
115
+ new stays version 2 and keeps playing on 1.36.
94
116
 
95
117
  ## What is proven, and by what
96
118
 
@@ -24,13 +24,19 @@ export declare class VfxInstance {
24
24
  private particleLayers;
25
25
  private byId;
26
26
  private flipbookLayers;
27
+ private meshLayers;
27
28
  private state;
29
+ /** Particles born so far: hashed into each particle's `seed`. */
30
+ private serial;
28
31
  private accumulator;
29
32
  private live;
30
33
  constructor(document: VfxDocument, options?: VfxInstanceOptions);
31
34
  private buildParticles;
32
35
  /** (Re)creates the per-instance buffers with room for `capacity` particles. */
33
36
  private allocate;
37
+ private buildMesh;
38
+ /** A mesh layer's life fraction now, or -1 when it is not showing. */
39
+ private meshLife;
34
40
  private buildFlipbook;
35
41
  private random;
36
42
  /** Back to time 0 with the original seed: a replay is identical to the first play. */
@@ -1,5 +1,10 @@
1
1
  import * as T from 'three';
2
2
  import { parseVfx, pickRange, sampleCurve, sampleGradient, LIMITS, } from './document.js';
3
+ import { compileMaterial, materialDefaults } from './material.js';
4
+ import { meshGeometry, fixRingUv, meshLayerVertex, meshParticleVertex, meshFragment } from './mesh.js';
5
+ /** Closed shapes are drawn front-only, so an additive sphere does not show its back through its front. */
6
+ const closed = (s) => s.type === 'sphere' || s.type === 'box' || s.type === 'torus' || (s.type === 'cylinder' && s.caps);
7
+ const SIDE = { front: T.FrontSide, back: T.BackSide, both: T.DoubleSide };
3
8
  const SHARED_QUAD = (() => {
4
9
  // Corners in [0,1]^2 with y UP; the shader turns them into a cell-sized quad.
5
10
  const g = new T.BufferGeometry();
@@ -44,15 +49,16 @@ const PARTICLE_QUAD = (() => {
44
49
  })();
45
50
  // iMisc = (size, angle radians, frame, unused)
46
51
  const PARTICLE_VERTEX = `
47
- attribute vec3 iPos; attribute vec4 iColor; attribute vec4 iMisc; attribute vec3 iVel;
52
+ attribute vec3 iPos; attribute vec4 iColor; attribute vec4 iMisc; attribute vec3 iVel; attribute vec2 iLife; attribute vec3 iAxes;
48
53
  uniform float uAlign; uniform float uStretch; uniform vec2 uCell; uniform mat3 uOrient; uniform vec3 uAxis;
49
- varying vec2 vUv; varying vec2 vQuad; varying vec4 vColor;
54
+ varying vec2 vUv; varying vec2 vQuad; varying vec4 vColor; varying vec2 vLife;
50
55
  void main(){
51
- vec2 c = position.xy;
52
- vQuad = c * 2.0;
56
+ vec2 c = position.xy * iAxes.xy; // per-axis scale over life; the UVs below stay on the unscaled corner
57
+ vQuad = position.xy * 2.0;
53
58
  vColor = iColor;
59
+ vLife = iLife;
54
60
  float size = iMisc.x, angle = iMisc.y, frame = iMisc.z;
55
- vec2 uv = c + 0.5;
61
+ vec2 uv = position.xy + 0.5;
56
62
  vUv = vec2((mod(frame, uCell.x) + uv.x) / uCell.x, 1.0 - (floor(frame / uCell.x) + 1.0 - uv.y) / uCell.y);
57
63
  float s = sin(angle), co = cos(angle);
58
64
  vec2 turned = vec2(c.x * co - c.y * s, c.x * s + c.y * co) * size;
@@ -112,7 +118,21 @@ void main(){
112
118
  #include <tonemapping_fragment>
113
119
  #include <colorspace_fragment>
114
120
  }`;
115
- const LOOK_CODE = { dot: 0, glow: 1, star: 2, texture: 3, sheet: 3 };
121
+ /** The material look: the material's colour and alpha times the particle's. */
122
+ const materialFragment = (c) => `
123
+ varying vec2 vQuad; varying vec4 vColor; varying vec2 vLife;
124
+ ${c.code}
125
+ float vfxBayer(vec2 p){ ivec2 q = ivec2(mod(p, 4.0)); int i = q.x + q.y * 4;
126
+ float m[16] = float[16](0.,8.,2.,10.,12.,4.,14.,6.,3.,11.,1.,9.,15.,7.,13.,5.); return (m[i] + 0.5) / 16.0; }
127
+ void main(){
128
+ vec4 m = vfxMaterial(vQuad * 0.5 + 0.5, vLife, 1.0);
129
+ float a = m.a * vColor.a;
130
+ ${c.alphaMode === 'cutout' ? 'if (a < uCutoff) discard; a = 1.0;' : c.alphaMode === 'dither' ? 'if (a < vfxBayer(gl_FragCoord.xy)) discard; a = 1.0;' : 'if (a <= 0.002) discard;'}
131
+ gl_FragColor = vec4(m.rgb * vColor.rgb, a);
132
+ #include <tonemapping_fragment>
133
+ #include <colorspace_fragment>
134
+ }`;
135
+ const LOOK_CODE = { dot: 0, glow: 1, star: 2, texture: 3, sheet: 3, material: 0 };
116
136
  const ALIGN_CODE = { camera: 0, velocity: 1, ground: 2, axis: 3 };
117
137
  const TAU = Math.PI * 2, DEG = Math.PI / 180;
118
138
  function resolveTexture(source, name) {
@@ -144,7 +164,10 @@ export class VfxInstance {
144
164
  this.particleLayers = [];
145
165
  this.byId = new Map();
146
166
  this.flipbookLayers = [];
167
+ this.meshLayers = [];
147
168
  this.state = 1;
169
+ /** Particles born so far: hashed into each particle's `seed`. */
170
+ this.serial = 0;
148
171
  this.accumulator = 0;
149
172
  this.live = 0;
150
173
  this.document = parseVfx(document);
@@ -152,23 +175,38 @@ export class VfxInstance {
152
175
  this.root.name = this.document.name;
153
176
  const children = new Set(this.document.emitters.flatMap((e) => e.children.map((c) => c.emitter)));
154
177
  this.document.emitters.forEach((config, index) => {
155
- const look = config.look;
156
- const texture = look.type === 'texture' || look.type === 'sheet' ? resolveTexture(options.textures, look.texture) : undefined;
157
- const layer = this.buildParticles(config, index, !children.has(config.id), texture);
178
+ const layer = this.buildParticles(config, index, !children.has(config.id), (name) => resolveTexture(options.textures, name));
158
179
  this.particleLayers.push(layer);
159
180
  this.byId.set(config.id, layer);
160
181
  });
161
182
  for (const config of this.document.flipbooks ?? [])
162
183
  this.flipbookLayers.push(this.buildFlipbook(config, resolveTexture(options.textures, config.texture)));
184
+ (this.document.meshes ?? []).forEach((config, i) => this.meshLayers.push(this.buildMesh(config, i, (name) => resolveTexture(options.textures, name))));
163
185
  this.draw();
164
186
  }
165
- buildParticles(config, index, root, texture) {
187
+ buildParticles(config, index, root, textureOf) {
166
188
  const geometry = new T.InstancedBufferGeometry();
167
- geometry.index = PARTICLE_QUAD.index;
168
- geometry.setAttribute('position', PARTICLE_QUAD.getAttribute('position'));
169
- const look = config.look;
189
+ const look = config.look, solid = config.mesh;
190
+ if (solid) {
191
+ // A mesh particle: the shape's own buffers, instanced.
192
+ const g = fixRingUv(meshGeometry(solid), solid);
193
+ geometry.index = g.index;
194
+ for (const k of ['position', 'normal', 'uv'])
195
+ geometry.setAttribute(k, g.getAttribute(k));
196
+ }
197
+ else {
198
+ geometry.index = PARTICLE_QUAD.index;
199
+ geometry.setAttribute('position', PARTICLE_QUAD.getAttribute('position'));
200
+ }
201
+ const texture = !solid && (look.type === 'texture' || look.type === 'sheet') ? textureOf(look.texture) : undefined;
202
+ const images = texture || (!solid && (look.type === 'texture' || look.type === 'sheet')) ? [texture] : [];
203
+ // A mesh particle always draws through a material: its look's, or a solid one.
204
+ const compiled = look.type === 'material' ? compileMaterial(look.material) : solid ? compileMaterial({ ...materialDefaults(), masks: [] }) : undefined;
205
+ const repeats = [];
206
+ if (compiled)
207
+ bindImages(compiled, textureOf, images, repeats);
170
208
  const material = new T.ShaderMaterial({
171
- transparent: true, depthWrite: false, side: T.DoubleSide,
209
+ transparent: true, depthWrite: false, side: solid && closed(solid) ? T.FrontSide : T.DoubleSide,
172
210
  blending: config.blend === 'additive' ? T.AdditiveBlending : T.NormalBlending,
173
211
  uniforms: {
174
212
  uLook: { value: LOOK_CODE[look.type] }, uSoft: { value: look.type === 'dot' ? look.softness : 0 },
@@ -177,8 +215,10 @@ export class VfxInstance {
177
215
  uAlign: { value: ALIGN_CODE[config.align] }, uStretch: { value: config.stretch },
178
216
  uAxis: { value: new T.Vector3(...config.direction).applyQuaternion(emitterQuaternion(config)).normalize() },
179
217
  uOrient: { value: new T.Matrix3().setFromMatrix4(new T.Matrix4().makeRotationFromQuaternion(emitterQuaternion(config))) },
218
+ ...compiled?.uniforms,
180
219
  },
181
- vertexShader: PARTICLE_VERTEX, fragmentShader: PARTICLE_FRAGMENT,
220
+ vertexShader: solid ? meshParticleVertex(compiled) : PARTICLE_VERTEX,
221
+ fragmentShader: solid ? meshFragment(compiled) : compiled ? materialFragment(compiled) : PARTICLE_FRAGMENT,
182
222
  });
183
223
  const mesh = new T.Mesh(geometry, material);
184
224
  mesh.frustumCulled = false;
@@ -190,7 +230,7 @@ export class VfxInstance {
190
230
  const layer = {
191
231
  config, index, particles: [], root, fraction: 0, cycle: 0, burstEmitted: config.bursts.map(() => 0),
192
232
  orient: emitterQuaternion(config), mesh, geometry, material, capacity: 0, attributes: undefined,
193
- texture, needsTexture: look.type === 'texture' || look.type === 'sheet',
233
+ images, compiled, repeats,
194
234
  };
195
235
  this.allocate(layer, 64);
196
236
  return layer;
@@ -198,14 +238,56 @@ export class VfxInstance {
198
238
  /** (Re)creates the per-instance buffers with room for `capacity` particles. */
199
239
  allocate(layer, capacity) {
200
240
  const make = (size) => new T.InstancedBufferAttribute(new Float32Array(capacity * size), size).setUsage(T.DynamicDrawUsage);
201
- layer.attributes = { pos: make(3), color: make(4), misc: make(4), vel: make(3) };
241
+ layer.attributes = { pos: make(3), color: make(4), misc: make(4), vel: make(3), life: make(2), axes: make(3) };
202
242
  const g = layer.geometry;
203
243
  g.setAttribute('iPos', layer.attributes.pos);
204
244
  g.setAttribute('iColor', layer.attributes.color);
205
245
  g.setAttribute('iMisc', layer.attributes.misc);
206
246
  g.setAttribute('iVel', layer.attributes.vel);
247
+ g.setAttribute('iLife', layer.attributes.life);
248
+ g.setAttribute('iAxes', layer.attributes.axes);
207
249
  layer.capacity = capacity;
208
250
  }
251
+ buildMesh(config, index, textureOf) {
252
+ const geometry = fixRingUv(meshGeometry(config.shape), config.shape);
253
+ const compiled = compileMaterial(config.material);
254
+ const images = [], repeats = [];
255
+ bindImages(compiled, textureOf, images, repeats);
256
+ const s = config.shape;
257
+ const material = new T.ShaderMaterial({
258
+ transparent: true, depthWrite: false,
259
+ side: config.side === 'both' && closed(s) ? T.FrontSide : SIDE[config.side],
260
+ blending: config.blend === 'additive' ? T.AdditiveBlending : T.NormalBlending,
261
+ uniforms: {
262
+ uLayerColor: { value: new T.Vector4(1, 1, 1, 1) }, uLayerLife: { value: new T.Vector2(0, 0) },
263
+ uFacing: { value: config.facing === 'camera' ? (s.type === 'quad' ? 1 : s.type === 'plane' ? 2 : 0) : 0 },
264
+ ...compiled.uniforms,
265
+ },
266
+ vertexShader: meshLayerVertex(compiled), fragmentShader: meshFragment(compiled),
267
+ });
268
+ const mesh = new T.Mesh(geometry, material);
269
+ // Meshes draw BEFORE particles: an effect's meshes are its core, its ground rings and discs, which particles fly in front of.
270
+ mesh.name = config.id;
271
+ mesh.frustumCulled = false;
272
+ mesh.renderOrder = -100 + index;
273
+ mesh.visible = false;
274
+ mesh.position.set(...config.position);
275
+ mesh.rotation.set(config.rotation[0] * DEG, config.rotation[1] * DEG, config.rotation[2] * DEG, 'XYZ');
276
+ this.root.add(mesh);
277
+ return { config, mesh, geometry, material, compiled, images, repeats, seed: seedOf(this.document.seed, 100000 + index) };
278
+ }
279
+ /** A mesh layer's life fraction now, or -1 when it is not showing. */
280
+ meshLife(c) {
281
+ if (!c.enabled)
282
+ return -1;
283
+ const d = this.document.duration, life = c.life ?? Math.max(.01, d - c.start);
284
+ const cycleTime = this.document.loop ? this.time % d : this.time;
285
+ let t = (cycleTime - c.start) / life;
286
+ // A looping layer that outlives its cycle carries over into the next one.
287
+ if (this.document.loop && t < 0 && this.time >= d)
288
+ t = (cycleTime + d - c.start) / life;
289
+ return t >= 0 && t < 1 ? t : -1;
290
+ }
209
291
  buildFlipbook(config, texture) {
210
292
  const material = new T.ShaderMaterial({
211
293
  transparent: true, depthWrite: false, side: T.DoubleSide,
@@ -231,6 +313,7 @@ export class VfxInstance {
231
313
  this.accumulator = 0;
232
314
  this.state = this.document.seed;
233
315
  this.live = 0;
316
+ this.serial = 0;
234
317
  for (const l of this.particleLayers) {
235
318
  l.particles = [];
236
319
  l.fraction = 0;
@@ -248,7 +331,8 @@ export class VfxInstance {
248
331
  get finished() {
249
332
  if (this.document.loop || this.time < this.document.duration)
250
333
  return false;
251
- return this.live === 0 && this.flipbookLayers.every((f) => f.done);
334
+ const meshesDone = this.meshLayers.every(({ config: c }) => !c.enabled || this.time >= c.start + (c.life ?? Math.max(.01, this.document.duration - c.start)));
335
+ return this.live === 0 && meshesDone && this.flipbookLayers.every((f) => f.done);
252
336
  }
253
337
  /** Kept for 1.35 callers. Particles are world-sized quads now, so the viewport no longer matters. */
254
338
  setViewportHeight(_height) { }
@@ -447,6 +531,7 @@ export class VfxInstance {
447
531
  age: 0, life: pickRange(c.lifetime, r()), x, y, z, vx, vy, vz,
448
532
  angle: pickRange(c.angle, r()) * DEG, spin: pickRange(c.spin, r()) * DEG, size: pickRange(c.size, r()),
449
533
  r: scratchRgba[0], g: scratchRgba[1], b: scratchRgba[2], a: scratchRgba[3],
534
+ seed: seedOf(this.document.seed, this.serial++),
450
535
  radialSpeed: pickRange(c.radialSpeed, r()), radialAccel: pickRange(c.radialAccel, r()),
451
536
  tangentialAccel: pickRange(c.tangentialAccel, r()), orbit: pickRange(c.orbit, r()), damping: pickRange(c.damping, r()),
452
537
  owed: c.children.map(() => 0),
@@ -514,8 +599,9 @@ export class VfxInstance {
514
599
  const c = l.config, n = l.particles.length;
515
600
  if (n > l.capacity)
516
601
  this.allocate(l, Math.min(LIMITS.particles, Math.max(n, l.capacity * 2)));
517
- const { pos, color, misc, vel } = l.attributes;
518
- const P = pos.array, C = color.array, M = misc.array, V = vel.array;
602
+ const { pos, color, misc, vel, life, axes } = l.attributes;
603
+ const P = pos.array, C = color.array, M = misc.array, V = vel.array, L = life.array, A = axes.array;
604
+ const xyz = c.sizeOverLifeXYZ;
519
605
  const look = c.look;
520
606
  for (let i = 0; i < n; i++) {
521
607
  const p = l.particles[i], t = p.age / p.life;
@@ -542,17 +628,49 @@ export class VfxInstance {
542
628
  C[i * 4 + 3] = Math.min(1, a);
543
629
  M[i * 4] = p.size * (c.sizeOverLife ? Math.max(0, sampleCurve(c.sizeOverLife, t)) : 1);
544
630
  M[i * 4 + 1] = p.angle;
631
+ L[i * 2] = t;
632
+ L[i * 2 + 1] = p.seed;
633
+ A[i * 3] = xyz?.x ? sampleCurve(xyz.x, t) : 1;
634
+ A[i * 3 + 1] = xyz?.y ? sampleCurve(xyz.y, t) : 1;
635
+ A[i * 3 + 2] = xyz?.z ? sampleCurve(xyz.z, t) : 1;
545
636
  M[i * 4 + 2] = look.type !== 'sheet' ? 0 : look.fps === 'life' ? Math.min(look.frames - 1, Math.floor(t * look.frames)) : Math.floor(p.age * look.fps) % look.frames;
546
637
  }
547
638
  l.geometry.instanceCount = n;
548
- for (const attribute of [pos, color, misc, vel])
639
+ for (const attribute of [pos, color, misc, vel, life, axes])
549
640
  attribute.needsUpdate = true;
550
- // A textured look waits for its image; a missing one draws nothing.
551
- const image = l.texture?.image;
552
- l.mesh.visible = n > 0 && (!l.needsTexture || !!image?.width);
641
+ if (l.compiled)
642
+ l.compiled.uniforms.uTime.value = this.time;
643
+ syncRepeats(l.repeats);
644
+ // A textured look waits for its images; a missing one draws nothing.
645
+ l.mesh.visible = n > 0 && l.images.every((t) => !!t?.image?.width);
553
646
  if (c.space === 'world')
554
647
  l.mesh.matrix.copy(this.root.matrixWorld).invert();
555
648
  }
649
+ for (const m of this.meshLayers) {
650
+ const c = m.config, t = this.meshLife(c);
651
+ const ready = m.images.every((x) => !!x?.image?.width);
652
+ m.mesh.visible = t >= 0 && ready;
653
+ if (!m.mesh.visible)
654
+ continue;
655
+ const k = c.scaleOverLife ? sampleCurve(c.scaleOverLife, t) : 1;
656
+ m.mesh.scale.set(c.scale[0] * k, c.scale[1] * k, c.scale[2] * k);
657
+ sampleGradient({ stops: [[0, c.color, 1]] }, 0, scratchRgba);
658
+ let [r, g, b] = scratchRgba, a = 1;
659
+ if (c.colorOverLife) {
660
+ sampleGradient(c.colorOverLife, t, scratchRgba);
661
+ r *= scratchRgba[0];
662
+ g *= scratchRgba[1];
663
+ b *= scratchRgba[2];
664
+ a *= scratchRgba[3];
665
+ }
666
+ if (c.alphaOverLife)
667
+ a *= Math.max(0, sampleCurve(c.alphaOverLife, t));
668
+ scratchColor.setRGB(r, g, b, T.SRGBColorSpace);
669
+ m.material.uniforms.uLayerColor.value.set(scratchColor.r * c.intensity, scratchColor.g * c.intensity, scratchColor.b * c.intensity, Math.min(1, a));
670
+ m.material.uniforms.uLayerLife.value.set(t, m.seed);
671
+ m.compiled.uniforms.uTime.value = this.time;
672
+ syncRepeats(m.repeats);
673
+ }
556
674
  for (const f of this.flipbookLayers) {
557
675
  const frame = this.frameOf(f.config);
558
676
  if (frame < 0 && this.time >= f.config.delay)
@@ -578,17 +696,63 @@ export class VfxInstance {
578
696
  for (const l of this.particleLayers) {
579
697
  l.geometry.dispose();
580
698
  l.material.dispose();
699
+ l.compiled?.dispose();
700
+ for (const r of l.repeats)
701
+ r.copy.dispose();
581
702
  }
582
703
  for (const f of this.flipbookLayers)
583
704
  f.material.dispose();
705
+ for (const m of this.meshLayers) {
706
+ m.geometry.dispose();
707
+ m.material.dispose();
708
+ m.compiled.dispose();
709
+ for (const r of m.repeats)
710
+ r.copy.dispose();
711
+ }
584
712
  this.particleLayers = [];
585
713
  this.flipbookLayers = [];
714
+ this.meshLayers = [];
586
715
  this.byId.clear();
587
716
  this.live = 0;
588
717
  this.root.removeFromParent();
589
718
  this.root.clear();
590
719
  }
591
720
  }
721
+ /**
722
+ * Bind a material's image masks. The shared texture is clamped for sprite
723
+ * sheets, so a mask gets a repeat-wrapped copy of it (same decoded image).
724
+ */
725
+ function bindImages(compiled, textureOf, images, repeats) {
726
+ for (const [i, name] of compiled.images) {
727
+ const t = textureOf(name);
728
+ images.push(t);
729
+ if (!t) {
730
+ compiled.uniforms[`uMask${i}`].value = null;
731
+ continue;
732
+ }
733
+ const copy = t.clone();
734
+ copy.wrapS = copy.wrapT = T.RepeatWrapping;
735
+ repeats.push({ source: t, copy, version: -1 });
736
+ compiled.uniforms[`uMask${i}`].value = copy;
737
+ }
738
+ }
739
+ /** A copy made before its image decoded never uploads on its own: follow the source's version. */
740
+ function syncRepeats(repeats) {
741
+ for (const r of repeats)
742
+ if (r.version !== r.source.version && r.source.image?.width) {
743
+ r.copy.image = r.source.image;
744
+ r.copy.needsUpdate = true;
745
+ r.version = r.source.version;
746
+ }
747
+ }
748
+ /** A particle's material seed, 0..1, from the effect seed and its birth order. */
749
+ function seedOf(seed, serial) {
750
+ let h = Math.imul(serial + 1, 0x9e3779b1) ^ Math.imul(seed, 0x85ebca6b);
751
+ h = Math.imul(h ^ (h >>> 16), 0x7feb352d);
752
+ h = Math.imul(h ^ (h >>> 15), 0x846ca68b);
753
+ h ^= h >>> 16;
754
+ return (h >>> 0) / 4294967296;
755
+ }
592
756
  /** An emitter's `rotation` (XYZ Euler degrees) as a quaternion. */
593
757
  function emitterQuaternion(e) {
594
758
  return new T.Quaternion().setFromEuler(new T.Euler(e.rotation[0] * DEG, e.rotation[1] * DEG, e.rotation[2] * DEG, 'XYZ'));
@@ -14,7 +14,17 @@
14
14
  *
15
15
  * Version 2. A version-1 document (the upward-firing disc emitter of 1.35) is
16
16
  * still accepted: `parseVfx` upgrades it to the v2 emitter that plays the same.
17
+ *
18
+ * Version 4 (1.38) adds MESHES: mesh layers (`meshes`) and mesh-shaped
19
+ * particles (`emitter.mesh`), ADR-055 step 2. A 1.37 reader ignores unknown
20
+ * top-level fields, so meshes needed their own version to fail loudly there.
21
+ *
22
+ * Version 3 (1.37) adds the effect MATERIAL (`look: { type: 'material' }`,
23
+ * ADR-055). A document that uses none of it is still written as version 2 --
24
+ * `minimumVersion()` -- so games whose lockfile holds 1.36 keep playing it.
17
25
  */
26
+ import { type Material } from './material.js';
27
+ import { type MeshShape, type MeshLayer } from './mesh.js';
18
28
  /** A number, or `[min, max]`: picked uniformly per particle. */
19
29
  export type Range = number | [number, number];
20
30
  export type Vec3 = [number, number, number];
@@ -83,6 +93,11 @@ export type ParticleLook =
83
93
  rows: number;
84
94
  frames: number;
85
95
  fps: number | 'life';
96
+ }
97
+ /** (version 3) The general effect material: masks, dissolve, a gradient map, emission. See material.ts. */
98
+ | {
99
+ type: 'material';
100
+ material: Material;
86
101
  };
87
102
  export interface Burst {
88
103
  time: number;
@@ -150,6 +165,16 @@ export interface Emitter {
150
165
  /** World width of one particle. */
151
166
  size: Range;
152
167
  sizeOverLife?: Curve;
168
+ /**
169
+ * (version 4) Per-axis scale over life on top of `size` (Godot's
170
+ * CurveXYZTexture scale curve): a shock ring that widens without getting
171
+ * taller. A quad uses x (width) and y (height). A missing axis stays 1.
172
+ */
173
+ sizeOverLifeXYZ?: {
174
+ x?: Curve;
175
+ y?: Curve;
176
+ z?: Curve;
177
+ };
153
178
  /** One stop: that colour. More: each particle picks a point on it at random. */
154
179
  color: Gradient;
155
180
  /** Multiplies `color` over life. */
@@ -170,6 +195,13 @@ export interface Emitter {
170
195
  stretch: number;
171
196
  blend: 'normal' | 'additive';
172
197
  children: SubEmitter[];
198
+ /**
199
+ * (version 3) Draw each particle as this mesh instead of a camera-facing
200
+ * quad: `size` then SCALES the mesh. It stands on the emitter's up, or on
201
+ * its velocity / the emitter axis with align velocity / axis, turned by
202
+ * `angle` about that line.
203
+ */
204
+ mesh?: MeshShape;
173
205
  }
174
206
  export interface Flipbook {
175
207
  id: string;
@@ -197,7 +229,7 @@ export interface Flipbook {
197
229
  blend: 'normal' | 'additive';
198
230
  }
199
231
  export interface VfxDocument {
200
- version: 2;
232
+ version: 2 | 3 | 4;
201
233
  name: string;
202
234
  seed: number;
203
235
  /** Seconds in one cycle. A looping effect repeats it; a one-shot stops emitting after it. */
@@ -206,6 +238,8 @@ export interface VfxDocument {
206
238
  humanCurated: boolean;
207
239
  emitters: Emitter[];
208
240
  flipbooks?: Flipbook[];
241
+ /** (version 3) Meshes with a material: a shockwave ring, a fireball sphere, a ground disc. */
242
+ meshes?: MeshLayer[];
209
243
  }
210
244
  /** A version-1 emitter: a disc firing upward with linear colour/size/alpha. Read, never written. */
211
245
  export interface EmitterV1 {
@@ -226,6 +260,7 @@ export interface EmitterV1 {
226
260
  export declare const LIMITS: {
227
261
  readonly emitters: 8;
228
262
  readonly layers: 8;
263
+ readonly meshes: 8;
229
264
  readonly particles: 4000;
230
265
  readonly cells: 4096;
231
266
  readonly bursts: 16;
@@ -310,6 +345,15 @@ export declare function sampleGradient(g: Gradient, t: number, out?: number[]):
310
345
  * fields left out take `emitterDefaults()`.
311
346
  */
312
347
  export declare function parseVfx(value: unknown): VfxDocument;
348
+ /**
349
+ * The lowest format version that can express this document: 3 when any
350
+ * emitter uses the material look, else 2. The editor and the agent write
351
+ * this, so an effect that needs nothing new still plays on 1.36.
352
+ */
353
+ export declare function minimumVersion(d: Pick<VfxDocument, 'emitters' | 'meshes'>): 2 | 3 | 4;
354
+ /** A new mesh layer: a soft additive ring on the ground, for the editor's "Add" and the agent. */
355
+ export declare function meshLayerDefaults(): Omit<MeshLayer, 'id'>;
356
+ export declare function meshLayer(id: string, patch?: Partial<MeshLayer>): MeshLayer;
313
357
  /**
314
358
  * The most particles an effect can have alive at once, estimated: per enabled
315
359
  * emitter, rate x longest life plus every burst, and for sub-emitters, the