@umicat/three-sdk 1.38.0 → 1.40.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 +17 -1
- package/dist/vfx/VfxInstance.d.ts +13 -1
- package/dist/vfx/VfxInstance.js +125 -6
- package/dist/vfx/document.d.ts +39 -3
- package/dist/vfx/document.js +85 -5
- package/dist/vfx/index.d.ts +1 -0
- package/dist/vfx/index.js +1 -0
- package/dist/vfx/load.d.ts +4 -1
- package/dist/vfx/load.js +3 -2
- package/dist/vfx/trail.d.ts +68 -0
- package/dist/vfx/trail.js +132 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -110,7 +110,23 @@ velocity with `align: velocity`). Materials gained rim (fresnel),
|
|
|
110
110
|
displacement, a cutout threshold and a band gradient; emitters gained
|
|
111
111
|
per-axis `sizeOverLifeXYZ`. Meshes draw before particles.
|
|
112
112
|
|
|
113
|
-
**
|
|
113
|
+
**Lights and scale (version 5, 1.39.0, ADR-055 step 3).** `lights: [...]`
|
|
114
|
+
(at most 2 point lights: position, colour, candela intensity, range, a
|
|
115
|
+
start/life window, intensity over life, flicker). They are created once and
|
|
116
|
+
dimmed to 0 when off, because adding or removing a three.js light recompiles
|
|
117
|
+
every lit material in the scene; `new VfxInstance(doc, { lights: false })` or
|
|
118
|
+
`effect.spawn({ lights: false })` builds none. An effect placed at a scale
|
|
119
|
+
scales everything: world-space particles take it in speed and size, and a
|
|
120
|
+
light's range follows it.
|
|
121
|
+
|
|
122
|
+
**Trails (version 6, 1.40.0, ADR-055 step 4).** `emitter.trail: { length,
|
|
123
|
+
width, widthOverTrail?, material? }`: each particle keeps up to 16 points of
|
|
124
|
+
where it has been and draws a ribbon turned to the viewer in the vertex
|
|
125
|
+
shader (no camera needed). u runs from the particle (0) to the tail end (1);
|
|
126
|
+
without a material the trail takes the particle's colour and fades out. At
|
|
127
|
+
most 8000 trail points per effect, checked at parse.
|
|
128
|
+
|
|
129
|
+
**Write the lowest version.** `minimumVersion(doc)` is 6 with trails, 5 with lights, 4 with meshes, 3 with a
|
|
114
130
|
material, else 2; the editor and the agent write that, so an effect that needs nothing
|
|
115
131
|
new stays version 2 and keeps playing on 1.36.
|
|
116
132
|
|
|
@@ -6,6 +6,12 @@ import { type VfxDocument, type Vec3 } from './document.js';
|
|
|
6
6
|
export type VfxTextureSource = Map<string, T.Texture> | Record<string, T.Texture> | ((filename: string) => T.Texture | undefined);
|
|
7
7
|
export interface VfxInstanceOptions {
|
|
8
8
|
textures?: VfxTextureSource;
|
|
9
|
+
/**
|
|
10
|
+
* false: build no lights at all (an unlit or mobile-heavy game). Default
|
|
11
|
+
* true. Either way the number of lights never changes after construction,
|
|
12
|
+
* so a scene's lit materials never recompile because an effect played.
|
|
13
|
+
*/
|
|
14
|
+
lights?: boolean;
|
|
9
15
|
}
|
|
10
16
|
/**
|
|
11
17
|
* One playing copy of an effect. Shared by the VFX Editor and games: it owns
|
|
@@ -25,6 +31,7 @@ export declare class VfxInstance {
|
|
|
25
31
|
private byId;
|
|
26
32
|
private flipbookLayers;
|
|
27
33
|
private meshLayers;
|
|
34
|
+
private lightLayers;
|
|
28
35
|
private state;
|
|
29
36
|
/** Particles born so far: hashed into each particle's `seed`. */
|
|
30
37
|
private serial;
|
|
@@ -32,16 +39,19 @@ export declare class VfxInstance {
|
|
|
32
39
|
private live;
|
|
33
40
|
constructor(document: VfxDocument, options?: VfxInstanceOptions);
|
|
34
41
|
private buildParticles;
|
|
42
|
+
private buildTrail;
|
|
35
43
|
/** (Re)creates the per-instance buffers with room for `capacity` particles. */
|
|
36
44
|
private allocate;
|
|
37
45
|
private buildMesh;
|
|
38
|
-
/** A mesh layer's life fraction now, or -1 when it is not showing. */
|
|
46
|
+
/** A mesh layer's or light's life fraction now, or -1 when it is not showing. */
|
|
39
47
|
private meshLife;
|
|
40
48
|
private buildFlipbook;
|
|
41
49
|
private random;
|
|
42
50
|
/** Back to time 0 with the original seed: a replay is identical to the first play. */
|
|
43
51
|
reset(): void;
|
|
44
52
|
get particleCount(): number;
|
|
53
|
+
/** The point lights this instance made (empty with `{ lights: false }`). Never changes after construction. */
|
|
54
|
+
get lights(): readonly T.PointLight[];
|
|
45
55
|
/** True once a NON-looping effect has stopped emitting, every particle has
|
|
46
56
|
* died and every flipbook has played out -- the moment to `dispose()` a
|
|
47
57
|
* one-shot. Always false for a looping effect. */
|
|
@@ -59,6 +69,8 @@ export declare class VfxInstance {
|
|
|
59
69
|
/** A new particle on `layer`, from its own emission shape -- around a parent particle when `at` is given. */
|
|
60
70
|
private spawn;
|
|
61
71
|
private spawnChildren;
|
|
72
|
+
/** Rebuilds an emitter's ribbons: each particle's position, then its history, newest first. */
|
|
73
|
+
private drawTrail;
|
|
62
74
|
/** The frame a flipbook shows now, or -1 for none. A looping flipbook keeps
|
|
63
75
|
* cycling while the effect runs and, once it stops, finishes its current
|
|
64
76
|
* cycle -- the flipbook counterpart of particles draining. */
|
package/dist/vfx/VfxInstance.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
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';
|
|
3
|
+
import { compileMaterial, materialDefaults, maskDefaults } from './material.js';
|
|
4
|
+
import { TrailMesh, trailSampling, trailVertex, newHistory, pushHistory, historyAt } from './trail.js';
|
|
4
5
|
import { meshGeometry, fixRingUv, meshLayerVertex, meshParticleVertex, meshFragment } from './mesh.js';
|
|
5
6
|
/** Closed shapes are drawn front-only, so an additive sphere does not show its back through its front. */
|
|
6
7
|
const closed = (s) => s.type === 'sphere' || s.type === 'box' || s.type === 'torus' || (s.type === 'cylinder' && s.caps);
|
|
@@ -147,6 +148,7 @@ function resolveTexture(source, name) {
|
|
|
147
148
|
const scratchColor = new T.Color();
|
|
148
149
|
const scratchRgba = [0, 0, 0, 0];
|
|
149
150
|
const scratchVec = new T.Vector3();
|
|
151
|
+
const scratchBasis = new T.Matrix3();
|
|
150
152
|
/**
|
|
151
153
|
* One playing copy of an effect. Shared by the VFX Editor and games: it owns
|
|
152
154
|
* no renderer, no DOM and no animation loop -- add `root` to a scene and call
|
|
@@ -165,6 +167,7 @@ export class VfxInstance {
|
|
|
165
167
|
this.byId = new Map();
|
|
166
168
|
this.flipbookLayers = [];
|
|
167
169
|
this.meshLayers = [];
|
|
170
|
+
this.lightLayers = [];
|
|
168
171
|
this.state = 1;
|
|
169
172
|
/** Particles born so far: hashed into each particle's `seed`. */
|
|
170
173
|
this.serial = 0;
|
|
@@ -182,6 +185,16 @@ export class VfxInstance {
|
|
|
182
185
|
for (const config of this.document.flipbooks ?? [])
|
|
183
186
|
this.flipbookLayers.push(this.buildFlipbook(config, resolveTexture(options.textures, config.texture)));
|
|
184
187
|
(this.document.meshes ?? []).forEach((config, i) => this.meshLayers.push(this.buildMesh(config, i, (name) => resolveTexture(options.textures, name))));
|
|
188
|
+
if (options.lights !== false)
|
|
189
|
+
(this.document.lights ?? []).forEach((config, i) => {
|
|
190
|
+
// Created now and dimmed to 0 when off: never added or removed later.
|
|
191
|
+
const light = new T.PointLight(new T.Color(config.color), 0, config.range, 2);
|
|
192
|
+
light.name = config.id;
|
|
193
|
+
light.position.set(...config.position);
|
|
194
|
+
light.castShadow = false;
|
|
195
|
+
this.root.add(light);
|
|
196
|
+
this.lightLayers.push({ config, light, seed: seedOf(this.document.seed, 200000 + i) });
|
|
197
|
+
});
|
|
185
198
|
this.draw();
|
|
186
199
|
}
|
|
187
200
|
buildParticles(config, index, root, textureOf) {
|
|
@@ -227,14 +240,36 @@ export class VfxInstance {
|
|
|
227
240
|
if (config.space === 'world')
|
|
228
241
|
mesh.matrixAutoUpdate = false;
|
|
229
242
|
this.root.add(mesh);
|
|
243
|
+
const trail = config.trail ? this.buildTrail(config, index, textureOf) : undefined;
|
|
230
244
|
const layer = {
|
|
231
245
|
config, index, particles: [], root, fraction: 0, cycle: 0, burstEmitted: config.bursts.map(() => 0),
|
|
232
246
|
orient: emitterQuaternion(config), mesh, geometry, material, capacity: 0, attributes: undefined,
|
|
233
|
-
images, compiled, repeats,
|
|
247
|
+
images, compiled, repeats, trail,
|
|
234
248
|
};
|
|
235
249
|
this.allocate(layer, 64);
|
|
236
250
|
return layer;
|
|
237
251
|
}
|
|
252
|
+
buildTrail(config, index, textureOf) {
|
|
253
|
+
const t = config.trail;
|
|
254
|
+
// Default: the particle's colour, fading from the particle to the tail (u runs head -> tail).
|
|
255
|
+
const compiled = compileMaterial(t.material ?? { ...materialDefaults(), masks: [{ ...maskDefaults({ type: 'gradient', fill: 'linear', center: [.5, .5], width: .25 }), invert: true }], softness: 1, ramp: 'linear' });
|
|
256
|
+
const images = [], repeats = [];
|
|
257
|
+
bindImages(compiled, textureOf, images, repeats);
|
|
258
|
+
const material = new T.ShaderMaterial({
|
|
259
|
+
transparent: true, depthWrite: false, side: T.DoubleSide,
|
|
260
|
+
blending: config.blend === 'additive' ? T.AdditiveBlending : T.NormalBlending,
|
|
261
|
+
uniforms: { ...compiled.uniforms }, vertexShader: trailVertex(compiled), fragmentShader: meshFragment(compiled),
|
|
262
|
+
});
|
|
263
|
+
const { points, interval } = trailSampling(t);
|
|
264
|
+
const mesh = new TrailMesh(material, points);
|
|
265
|
+
// Under its particles, which are the bright heads of the streaks.
|
|
266
|
+
mesh.mesh.name = config.id + ':trail';
|
|
267
|
+
mesh.mesh.renderOrder = index - .5;
|
|
268
|
+
if (config.space === 'world')
|
|
269
|
+
mesh.mesh.matrixAutoUpdate = false;
|
|
270
|
+
this.root.add(mesh.mesh);
|
|
271
|
+
return { mesh, compiled, points, interval, images, repeats };
|
|
272
|
+
}
|
|
238
273
|
/** (Re)creates the per-instance buffers with room for `capacity` particles. */
|
|
239
274
|
allocate(layer, capacity) {
|
|
240
275
|
const make = (size) => new T.InstancedBufferAttribute(new Float32Array(capacity * size), size).setUsage(T.DynamicDrawUsage);
|
|
@@ -276,7 +311,7 @@ export class VfxInstance {
|
|
|
276
311
|
this.root.add(mesh);
|
|
277
312
|
return { config, mesh, geometry, material, compiled, images, repeats, seed: seedOf(this.document.seed, 100000 + index) };
|
|
278
313
|
}
|
|
279
|
-
/** A mesh layer's life fraction now, or -1 when it is not showing. */
|
|
314
|
+
/** A mesh layer's or light's life fraction now, or -1 when it is not showing. */
|
|
280
315
|
meshLife(c) {
|
|
281
316
|
if (!c.enabled)
|
|
282
317
|
return -1;
|
|
@@ -325,13 +360,16 @@ export class VfxInstance {
|
|
|
325
360
|
this.draw();
|
|
326
361
|
}
|
|
327
362
|
get particleCount() { return this.live; }
|
|
363
|
+
/** The point lights this instance made (empty with `{ lights: false }`). Never changes after construction. */
|
|
364
|
+
get lights() { return this.lightLayers.map((l) => l.light); }
|
|
328
365
|
/** True once a NON-looping effect has stopped emitting, every particle has
|
|
329
366
|
* died and every flipbook has played out -- the moment to `dispose()` a
|
|
330
367
|
* one-shot. Always false for a looping effect. */
|
|
331
368
|
get finished() {
|
|
332
369
|
if (this.document.loop || this.time < this.document.duration)
|
|
333
370
|
return false;
|
|
334
|
-
const
|
|
371
|
+
const over = (c) => !c.enabled || this.time >= c.start + (c.life ?? Math.max(.01, this.document.duration - c.start));
|
|
372
|
+
const meshesDone = this.meshLayers.every(({ config }) => over(config)) && this.lightLayers.every(({ config }) => over(config));
|
|
335
373
|
return this.live === 0 && meshesDone && this.flipbookLayers.every((f) => f.done);
|
|
336
374
|
}
|
|
337
375
|
/** Kept for 1.35 callers. Particles are world-sized quads now, so the viewport no longer matters. */
|
|
@@ -374,6 +412,13 @@ export class VfxInstance {
|
|
|
374
412
|
continue;
|
|
375
413
|
}
|
|
376
414
|
this.move(c, p, dt, origin);
|
|
415
|
+
if (p.history && l.trail) {
|
|
416
|
+
p.history.acc += dt;
|
|
417
|
+
while (p.history.acc >= l.trail.interval - 1e-9) {
|
|
418
|
+
p.history.acc -= l.trail.interval;
|
|
419
|
+
pushHistory(p.history, p.x, p.y, p.z, l.trail.points);
|
|
420
|
+
}
|
|
421
|
+
}
|
|
377
422
|
this.spawnChildren(l, p, 'life', dt);
|
|
378
423
|
kept.push(p);
|
|
379
424
|
}
|
|
@@ -521,7 +566,8 @@ export class VfxInstance {
|
|
|
521
566
|
x = p.x;
|
|
522
567
|
y = p.y;
|
|
523
568
|
z = p.z;
|
|
524
|
-
|
|
569
|
+
// The linear part, scale included: an effect placed at 2x throws its particles twice as fast (Godot's emission transform).
|
|
570
|
+
const v = scratchVec.set(vx, vy, vz).applyMatrix3(scratchBasis.setFromMatrix4(m));
|
|
525
571
|
vx = v.x;
|
|
526
572
|
vy = v.y;
|
|
527
573
|
vz = v.z;
|
|
@@ -532,10 +578,15 @@ export class VfxInstance {
|
|
|
532
578
|
angle: pickRange(c.angle, r()) * DEG, spin: pickRange(c.spin, r()) * DEG, size: pickRange(c.size, r()),
|
|
533
579
|
r: scratchRgba[0], g: scratchRgba[1], b: scratchRgba[2], a: scratchRgba[3],
|
|
534
580
|
seed: seedOf(this.document.seed, this.serial++),
|
|
581
|
+
scale: c.space === 'world' ? this.root.matrixWorld.getMaxScaleOnAxis() : 1,
|
|
535
582
|
radialSpeed: pickRange(c.radialSpeed, r()), radialAccel: pickRange(c.radialAccel, r()),
|
|
536
583
|
tangentialAccel: pickRange(c.tangentialAccel, r()), orbit: pickRange(c.orbit, r()), damping: pickRange(c.damping, r()),
|
|
537
584
|
owed: c.children.map(() => 0),
|
|
538
585
|
};
|
|
586
|
+
if (layer.trail) {
|
|
587
|
+
particle.history = newHistory(layer.trail.points);
|
|
588
|
+
pushHistory(particle.history, x, y, z, layer.trail.points);
|
|
589
|
+
}
|
|
539
590
|
layer.particles.push(particle);
|
|
540
591
|
this.live++;
|
|
541
592
|
this.spawnChildren(layer, particle, 'birth', 0);
|
|
@@ -575,6 +626,37 @@ export class VfxInstance {
|
|
|
575
626
|
this.spawn(child, { x, y, z, vx, vy, vz });
|
|
576
627
|
});
|
|
577
628
|
}
|
|
629
|
+
/** Rebuilds an emitter's ribbons: each particle's position, then its history, newest first. */
|
|
630
|
+
drawTrail(l, C) {
|
|
631
|
+
const tr = l.trail, cfg = l.config.trail, n = l.particles.length;
|
|
632
|
+
tr.mesh.grow(n);
|
|
633
|
+
const pts = trailScratch(tr.points), rgba = [0, 0, 0, 0];
|
|
634
|
+
const width = (u) => cfg.width * (cfg.widthOverTrail ? Math.max(0, sampleCurve(cfg.widthOverTrail, u)) : 1 - u);
|
|
635
|
+
for (let i = 0; i < n; i++) {
|
|
636
|
+
const p = l.particles[i], h = p.history;
|
|
637
|
+
pts[0][0] = p.x;
|
|
638
|
+
pts[0][1] = p.y;
|
|
639
|
+
pts[0][2] = p.z;
|
|
640
|
+
// The newest stored point can be the particle's own spot (it was just pushed): skip it then.
|
|
641
|
+
let k = 0, count = 1;
|
|
642
|
+
historyAt(h, 0, tr.points, pts[1]);
|
|
643
|
+
if (h.count && Math.hypot(pts[1][0] - p.x, pts[1][1] - p.y, pts[1][2] - p.z) < 1e-7)
|
|
644
|
+
k = 1;
|
|
645
|
+
for (; k < h.count && count < tr.points; k++, count++)
|
|
646
|
+
historyAt(h, k, tr.points, pts[count]);
|
|
647
|
+
rgba[0] = C[i * 4];
|
|
648
|
+
rgba[1] = C[i * 4 + 1];
|
|
649
|
+
rgba[2] = C[i * 4 + 2];
|
|
650
|
+
rgba[3] = C[i * 4 + 3];
|
|
651
|
+
tr.mesh.write(i, pts, count, rgba, width, p.age / p.life, p.seed);
|
|
652
|
+
}
|
|
653
|
+
tr.mesh.commit(n);
|
|
654
|
+
tr.compiled.uniforms.uTime.value = this.time;
|
|
655
|
+
syncRepeats(tr.repeats);
|
|
656
|
+
if (l.config.space === 'world')
|
|
657
|
+
tr.mesh.mesh.matrix.copy(this.root.matrixWorld).invert();
|
|
658
|
+
tr.mesh.mesh.visible = n > 0 && tr.images.every((x) => !!x?.image?.width);
|
|
659
|
+
}
|
|
578
660
|
/** The frame a flipbook shows now, or -1 for none. A looping flipbook keeps
|
|
579
661
|
* cycling while the effect runs and, once it stops, finishes its current
|
|
580
662
|
* cycle -- the flipbook counterpart of particles draining. */
|
|
@@ -626,7 +708,7 @@ export class VfxInstance {
|
|
|
626
708
|
C[i * 4 + 1] = scratchColor.g * c.intensity;
|
|
627
709
|
C[i * 4 + 2] = scratchColor.b * c.intensity;
|
|
628
710
|
C[i * 4 + 3] = Math.min(1, a);
|
|
629
|
-
M[i * 4] = p.size * (c.sizeOverLife ? Math.max(0, sampleCurve(c.sizeOverLife, t)) : 1);
|
|
711
|
+
M[i * 4] = p.size * p.scale * (c.sizeOverLife ? Math.max(0, sampleCurve(c.sizeOverLife, t)) : 1);
|
|
630
712
|
M[i * 4 + 1] = p.angle;
|
|
631
713
|
L[i * 2] = t;
|
|
632
714
|
L[i * 2 + 1] = p.seed;
|
|
@@ -635,6 +717,8 @@ export class VfxInstance {
|
|
|
635
717
|
A[i * 3 + 2] = xyz?.z ? sampleCurve(xyz.z, t) : 1;
|
|
636
718
|
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;
|
|
637
719
|
}
|
|
720
|
+
if (l.trail)
|
|
721
|
+
this.drawTrail(l, C);
|
|
638
722
|
l.geometry.instanceCount = n;
|
|
639
723
|
for (const attribute of [pos, color, misc, vel, life, axes])
|
|
640
724
|
attribute.needsUpdate = true;
|
|
@@ -646,6 +730,22 @@ export class VfxInstance {
|
|
|
646
730
|
if (c.space === 'world')
|
|
647
731
|
l.mesh.matrix.copy(this.root.matrixWorld).invert();
|
|
648
732
|
}
|
|
733
|
+
if (this.lightLayers.length) {
|
|
734
|
+
this.root.updateWorldMatrix(true, false);
|
|
735
|
+
const k = this.root.matrixWorld.getMaxScaleOnAxis();
|
|
736
|
+
for (const l of this.lightLayers) {
|
|
737
|
+
const c = l.config, t = this.meshLife(c);
|
|
738
|
+
let power = t < 0 ? 0 : c.intensity * (c.intensityOverLife ? Math.max(0, sampleCurve(c.intensityOverLife, t)) : 1);
|
|
739
|
+
if (power > 0 && c.flicker > 0) {
|
|
740
|
+
// Three incommensurate sines: steady-looking randomness, the same on every replay.
|
|
741
|
+
const x = this.time + l.seed * 17, n = Math.sin(x * 23.1) * .5 + Math.sin(x * 37.7) * .3 + Math.sin(x * 61.3) * .2;
|
|
742
|
+
power *= 1 - c.flicker * .5 * (1 + n);
|
|
743
|
+
}
|
|
744
|
+
l.light.intensity = power;
|
|
745
|
+
// A bigger effect lights further.
|
|
746
|
+
l.light.distance = c.range * k;
|
|
747
|
+
}
|
|
748
|
+
}
|
|
649
749
|
for (const m of this.meshLayers) {
|
|
650
750
|
const c = m.config, t = this.meshLife(c);
|
|
651
751
|
const ready = m.images.every((x) => !!x?.image?.width);
|
|
@@ -699,6 +799,13 @@ export class VfxInstance {
|
|
|
699
799
|
l.compiled?.dispose();
|
|
700
800
|
for (const r of l.repeats)
|
|
701
801
|
r.copy.dispose();
|
|
802
|
+
if (l.trail) {
|
|
803
|
+
l.trail.mesh.dispose();
|
|
804
|
+
(l.trail.mesh.material).dispose();
|
|
805
|
+
l.trail.compiled.dispose();
|
|
806
|
+
for (const r of l.trail.repeats)
|
|
807
|
+
r.copy.dispose();
|
|
808
|
+
}
|
|
702
809
|
}
|
|
703
810
|
for (const f of this.flipbookLayers)
|
|
704
811
|
f.material.dispose();
|
|
@@ -709,9 +816,12 @@ export class VfxInstance {
|
|
|
709
816
|
for (const r of m.repeats)
|
|
710
817
|
r.copy.dispose();
|
|
711
818
|
}
|
|
819
|
+
for (const l of this.lightLayers)
|
|
820
|
+
l.light.dispose();
|
|
712
821
|
this.particleLayers = [];
|
|
713
822
|
this.flipbookLayers = [];
|
|
714
823
|
this.meshLayers = [];
|
|
824
|
+
this.lightLayers = [];
|
|
715
825
|
this.byId.clear();
|
|
716
826
|
this.live = 0;
|
|
717
827
|
this.root.removeFromParent();
|
|
@@ -736,6 +846,15 @@ function bindImages(compiled, textureOf, images, repeats) {
|
|
|
736
846
|
compiled.uniforms[`uMask${i}`].value = copy;
|
|
737
847
|
}
|
|
738
848
|
}
|
|
849
|
+
const trailScratches = new Map();
|
|
850
|
+
function trailScratch(points) {
|
|
851
|
+
let s = trailScratches.get(points);
|
|
852
|
+
if (!s) {
|
|
853
|
+
s = Array.from({ length: points }, () => [0, 0, 0]);
|
|
854
|
+
trailScratches.set(points, s);
|
|
855
|
+
}
|
|
856
|
+
return s;
|
|
857
|
+
}
|
|
739
858
|
/** A copy made before its image decoded never uploads on its own: follow the source's version. */
|
|
740
859
|
function syncRepeats(repeats) {
|
|
741
860
|
for (const r of repeats)
|
package/dist/vfx/document.d.ts
CHANGED
|
@@ -15,6 +15,10 @@
|
|
|
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
17
|
*
|
|
18
|
+
* Version 6 (1.40) adds TRAILS (`emitter.trail`, ADR-055 step 4).
|
|
19
|
+
*
|
|
20
|
+
* Version 5 (1.39) adds LIGHTS (`lights`, point lights, ADR-055 step 3).
|
|
21
|
+
*
|
|
18
22
|
* Version 4 (1.38) adds MESHES: mesh layers (`meshes`) and mesh-shaped
|
|
19
23
|
* particles (`emitter.mesh`), ADR-055 step 2. A 1.37 reader ignores unknown
|
|
20
24
|
* top-level fields, so meshes needed their own version to fail loudly there.
|
|
@@ -25,6 +29,7 @@
|
|
|
25
29
|
*/
|
|
26
30
|
import { type Material } from './material.js';
|
|
27
31
|
import { type MeshShape, type MeshLayer } from './mesh.js';
|
|
32
|
+
import { type Trail } from './trail.js';
|
|
28
33
|
/** A number, or `[min, max]`: picked uniformly per particle. */
|
|
29
34
|
export type Range = number | [number, number];
|
|
30
35
|
export type Vec3 = [number, number, number];
|
|
@@ -202,6 +207,8 @@ export interface Emitter {
|
|
|
202
207
|
* `angle` about that line.
|
|
203
208
|
*/
|
|
204
209
|
mesh?: MeshShape;
|
|
210
|
+
/** (version 6) A ribbon through where each particle has been: sparks, shrapnel, comet tails. */
|
|
211
|
+
trail?: Trail;
|
|
205
212
|
}
|
|
206
213
|
export interface Flipbook {
|
|
207
214
|
id: string;
|
|
@@ -229,7 +236,7 @@ export interface Flipbook {
|
|
|
229
236
|
blend: 'normal' | 'additive';
|
|
230
237
|
}
|
|
231
238
|
export interface VfxDocument {
|
|
232
|
-
version: 2 | 3 | 4;
|
|
239
|
+
version: 2 | 3 | 4 | 5 | 6;
|
|
233
240
|
name: string;
|
|
234
241
|
seed: number;
|
|
235
242
|
/** Seconds in one cycle. A looping effect repeats it; a one-shot stops emitting after it. */
|
|
@@ -238,8 +245,31 @@ export interface VfxDocument {
|
|
|
238
245
|
humanCurated: boolean;
|
|
239
246
|
emitters: Emitter[];
|
|
240
247
|
flipbooks?: Flipbook[];
|
|
241
|
-
/** (version
|
|
248
|
+
/** (version 4) Meshes with a material: a shockwave ring, a fireball sphere, a ground disc. */
|
|
242
249
|
meshes?: MeshLayer[];
|
|
250
|
+
/** (version 5) Point lights: the flash of a muzzle, the glow a fire throws on the ground. At most 2. */
|
|
251
|
+
lights?: LightLayer[];
|
|
252
|
+
}
|
|
253
|
+
/**
|
|
254
|
+
* A point light, created once with the effect and dimmed to 0 when it is off
|
|
255
|
+
* -- adding or removing a light in three.js recompiles every lit material in
|
|
256
|
+
* the scene, which would stall a game on every shot. `intensity` is three.js
|
|
257
|
+
* candela with physical (inverse-square) falloff, cut off at `range`.
|
|
258
|
+
*/
|
|
259
|
+
export interface LightLayer {
|
|
260
|
+
id: string;
|
|
261
|
+
enabled: boolean;
|
|
262
|
+
position: Vec3;
|
|
263
|
+
color: string;
|
|
264
|
+
intensity: number;
|
|
265
|
+
range: number;
|
|
266
|
+
/** Seconds into each cycle it comes on, and for how long (null: to the end of the cycle). */
|
|
267
|
+
start: number;
|
|
268
|
+
life: number | null;
|
|
269
|
+
/** Over the light's own life; multiplies `intensity`. */
|
|
270
|
+
intensityOverLife?: Curve;
|
|
271
|
+
/** 0-1: how much it flickers (a fire); 0 = steady. */
|
|
272
|
+
flicker: number;
|
|
243
273
|
}
|
|
244
274
|
/** A version-1 emitter: a disc firing upward with linear colour/size/alpha. Read, never written. */
|
|
245
275
|
export interface EmitterV1 {
|
|
@@ -261,6 +291,7 @@ export declare const LIMITS: {
|
|
|
261
291
|
readonly emitters: 8;
|
|
262
292
|
readonly layers: 8;
|
|
263
293
|
readonly meshes: 8;
|
|
294
|
+
readonly lights: 2;
|
|
264
295
|
readonly particles: 4000;
|
|
265
296
|
readonly cells: 4096;
|
|
266
297
|
readonly bursts: 16;
|
|
@@ -350,9 +381,12 @@ export declare function parseVfx(value: unknown): VfxDocument;
|
|
|
350
381
|
* emitter uses the material look, else 2. The editor and the agent write
|
|
351
382
|
* this, so an effect that needs nothing new still plays on 1.36.
|
|
352
383
|
*/
|
|
353
|
-
export declare function minimumVersion(d: Pick<VfxDocument, 'emitters' | 'meshes'>): 2 | 3 | 4;
|
|
384
|
+
export declare function minimumVersion(d: Pick<VfxDocument, 'emitters' | 'meshes' | 'lights'>): 2 | 3 | 4 | 5 | 6;
|
|
354
385
|
/** A new mesh layer: a soft additive ring on the ground, for the editor's "Add" and the agent. */
|
|
355
386
|
export declare function meshLayerDefaults(): Omit<MeshLayer, 'id'>;
|
|
387
|
+
/** A new light: a warm glow just above the origin, lit for the whole cycle. */
|
|
388
|
+
export declare function lightLayerDefaults(): Omit<LightLayer, 'id'>;
|
|
389
|
+
export declare function lightLayer(id: string, patch?: Partial<LightLayer>): LightLayer;
|
|
356
390
|
export declare function meshLayer(id: string, patch?: Partial<MeshLayer>): MeshLayer;
|
|
357
391
|
/**
|
|
358
392
|
* The most particles an effect can have alive at once, estimated: per enabled
|
|
@@ -360,6 +394,8 @@ export declare function meshLayer(id: string, patch?: Partial<MeshLayer>): MeshL
|
|
|
360
394
|
* parent's count times what each parent particle spawns.
|
|
361
395
|
*/
|
|
362
396
|
export declare function particleBudget(d: VfxDocument): number;
|
|
397
|
+
/** The most particles each emitter can have alive at once (see particleBudget), by id. */
|
|
398
|
+
export declare function particleBudgets(d: VfxDocument): Map<string, number>;
|
|
363
399
|
/** An effect is a project ASSET named `<stem>.vfx.json`; the server keeps the
|
|
364
400
|
* whole compound extension, so this suffix is what marks one. */
|
|
365
401
|
export declare const VFX_SUFFIX = ".vfx.json";
|
package/dist/vfx/document.js
CHANGED
|
@@ -15,6 +15,10 @@
|
|
|
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
17
|
*
|
|
18
|
+
* Version 6 (1.40) adds TRAILS (`emitter.trail`, ADR-055 step 4).
|
|
19
|
+
*
|
|
20
|
+
* Version 5 (1.39) adds LIGHTS (`lights`, point lights, ADR-055 step 3).
|
|
21
|
+
*
|
|
18
22
|
* Version 4 (1.38) adds MESHES: mesh layers (`meshes`) and mesh-shaped
|
|
19
23
|
* particles (`emitter.mesh`), ADR-055 step 2. A 1.37 reader ignores unknown
|
|
20
24
|
* top-level fields, so meshes needed their own version to fail loudly there.
|
|
@@ -25,7 +29,8 @@
|
|
|
25
29
|
*/
|
|
26
30
|
import { parseMaterial, materialTextures, materialDefaults } from './material.js';
|
|
27
31
|
import { parseMeshShape } from './mesh.js';
|
|
28
|
-
|
|
32
|
+
import { trailSampling, TRAIL_POINT_BUDGET } from './trail.js';
|
|
33
|
+
export const LIMITS = { emitters: 8, layers: 8, meshes: 8, lights: 2, particles: 4000, cells: 4096, bursts: 16, children: 4, curvePoints: 8, gradientStops: 16 };
|
|
29
34
|
/** Every emitter field's value when a document leaves it out. */
|
|
30
35
|
export function emitterDefaults() {
|
|
31
36
|
return {
|
|
@@ -103,6 +108,8 @@ export function vfxTextures(document) {
|
|
|
103
108
|
names.push(e.look.texture);
|
|
104
109
|
else if (e.look.type === 'material')
|
|
105
110
|
names.push(...materialTextures(e.look.material));
|
|
111
|
+
if (e.trail?.material)
|
|
112
|
+
names.push(...materialTextures(e.trail.material));
|
|
106
113
|
}
|
|
107
114
|
for (const m of document.meshes ?? [])
|
|
108
115
|
names.push(...materialTextures(m.material));
|
|
@@ -182,8 +189,8 @@ export function parseVfx(value) {
|
|
|
182
189
|
const d = structuredClone(value);
|
|
183
190
|
const number = (v, min, max) => typeof v === 'number' && Number.isFinite(v) && v >= min && v <= max;
|
|
184
191
|
const color = (v) => typeof v === 'string' && /^#[0-9a-f]{6}$/i.test(v);
|
|
185
|
-
if (
|
|
186
|
-
fail(`version must be 2
|
|
192
|
+
if (![2, 3, 4, 5, 6].includes(d.version))
|
|
193
|
+
fail(`version must be 2-6 (or 1, which is upgraded)${typeof d.version === 'number' && d.version > 6 ? ` -- version ${d.version} was written by a newer editor: update @umicat/three-sdk` : ''}`);
|
|
187
194
|
if (typeof d.name !== 'string' || !d.name.trim() || d.name.length > 80)
|
|
188
195
|
fail('name must be 1-80 characters');
|
|
189
196
|
if (!number(d.seed, 1, 2147483646) || !Number.isInteger(d.seed))
|
|
@@ -256,7 +263,7 @@ export function parseVfx(value) {
|
|
|
256
263
|
fail(`${at} is not an object`);
|
|
257
264
|
checkId(input.id, at);
|
|
258
265
|
emitterIds.add(input.id);
|
|
259
|
-
const known = new Set(['id', ...Object.keys(emitterDefaults()), ...CURVE_FIELDS, 'colorOverLife', 'mesh', 'sizeOverLifeXYZ']);
|
|
266
|
+
const known = new Set(['id', ...Object.keys(emitterDefaults()), ...CURVE_FIELDS, 'colorOverLife', 'mesh', 'sizeOverLifeXYZ', 'trail']);
|
|
260
267
|
for (const key of Object.keys(input))
|
|
261
268
|
if (!known.has(key))
|
|
262
269
|
fail(`${at}.${key} is not an emitter field (a version-1 field? set "version": 1, or see emitterDefaults())`);
|
|
@@ -353,6 +360,25 @@ export function parseVfx(value) {
|
|
|
353
360
|
fail(`${lat}.type must be dot, glow, star, texture, sheet or material`);
|
|
354
361
|
if (!['camera', 'velocity', 'ground', 'axis'].includes(e.align))
|
|
355
362
|
fail(`${at}.align must be "camera", "velocity", "ground" or "axis"`);
|
|
363
|
+
if (e.trail !== undefined) {
|
|
364
|
+
if (d.version < 6)
|
|
365
|
+
fail(`${at}.trail is version 6: set "version": 6 (needs @umicat/three-sdk 1.40 or later)`);
|
|
366
|
+
const tr = e.trail, tat = `${at}.trail`;
|
|
367
|
+
if (!tr || typeof tr !== 'object' || Array.isArray(tr))
|
|
368
|
+
fail(`${tat} must be { length, width, widthOverTrail?, material? }`);
|
|
369
|
+
for (const k of Object.keys(tr))
|
|
370
|
+
if (!['length', 'width', 'widthOverTrail', 'material'].includes(k))
|
|
371
|
+
fail(`${tat}.${k} is not a trail field (expected length, width, widthOverTrail, material)`);
|
|
372
|
+
e.trail = { ...{ length: .3, width: .1 }, ...tr };
|
|
373
|
+
if (!number(e.trail.length, .02, 10))
|
|
374
|
+
fail(`${tat}.length must be 0.02-10 seconds`);
|
|
375
|
+
if (!number(e.trail.width, 0, 50))
|
|
376
|
+
fail(`${tat}.width must be 0-50`);
|
|
377
|
+
if (e.trail.widthOverTrail !== undefined)
|
|
378
|
+
checkCurve(e.trail.widthOverTrail, `${tat}.widthOverTrail`);
|
|
379
|
+
if (e.trail.material !== undefined)
|
|
380
|
+
e.trail.material = parseMaterial(e.trail.material, `${tat}.material`, fail, { checkCurve, checkGradient, texturePattern: TEXTURE_PATTERN });
|
|
381
|
+
}
|
|
356
382
|
if (e.sizeOverLifeXYZ !== undefined) {
|
|
357
383
|
if (d.version < 4)
|
|
358
384
|
fail(`${at}.sizeOverLifeXYZ is version 4: set "version": 4 (needs @umicat/three-sdk 1.38 or later)`);
|
|
@@ -407,9 +433,48 @@ export function parseVfx(value) {
|
|
|
407
433
|
};
|
|
408
434
|
for (const id of emitterIds)
|
|
409
435
|
walk(id);
|
|
436
|
+
const budgets = particleBudgets(d);
|
|
437
|
+
const trailPoints = d.emitters.reduce((sum, e) => sum + (e.trail && e.enabled ? (budgets.get(e.id) ?? 0) * trailSampling(e.trail).points : 0), 0);
|
|
438
|
+
if (trailPoints > TRAIL_POINT_BUDGET)
|
|
439
|
+
fail(`too many trail points: up to ${Math.ceil(trailPoints)} (live particles with a trail x points per trail), the limit is ${TRAIL_POINT_BUDGET} -- shorten the trails or emit fewer`);
|
|
410
440
|
const budget = particleBudget(d);
|
|
411
441
|
if (budget > LIMITS.particles)
|
|
412
442
|
fail(`too many live particles: the most this effect can have alive at once is about ${Math.ceil(budget)} (rate x lifetime + bursts, times sub-emitters), the limit is ${LIMITS.particles}`);
|
|
443
|
+
if (d.lights !== undefined) {
|
|
444
|
+
if (!Array.isArray(d.lights) || d.lights.length > LIMITS.lights)
|
|
445
|
+
fail(`lights must be a list of 0-${LIMITS.lights}`);
|
|
446
|
+
if (d.version < 5)
|
|
447
|
+
fail('lights are version 5: set "version": 5 (needs @umicat/three-sdk 1.39 or later)');
|
|
448
|
+
d.lights = d.lights.map((raw, i) => {
|
|
449
|
+
const at = `lights[${i}]`;
|
|
450
|
+
if (!raw || typeof raw !== 'object' || Array.isArray(raw))
|
|
451
|
+
fail(`${at} is not an object`);
|
|
452
|
+
checkId(raw.id, at);
|
|
453
|
+
const base = lightLayerDefaults();
|
|
454
|
+
for (const k of Object.keys(raw))
|
|
455
|
+
if (!(k in base) && k !== 'id' && k !== 'intensityOverLife')
|
|
456
|
+
fail(`${at}.${k} is not a light field (expected id, ${Object.keys(base).join(', ')}, intensityOverLife)`);
|
|
457
|
+
const l = { ...base, ...raw };
|
|
458
|
+
if (typeof l.enabled !== 'boolean')
|
|
459
|
+
fail(`${at}.enabled must be a boolean`);
|
|
460
|
+
checkVec(l.position, `${at}.position`, -100, 100);
|
|
461
|
+
if (!color(l.color))
|
|
462
|
+
fail(`${at}.color must be #rrggbb`);
|
|
463
|
+
if (!number(l.intensity, 0, 1000))
|
|
464
|
+
fail(`${at}.intensity must be 0-1000 (candela)`);
|
|
465
|
+
if (!number(l.range, .1, 100))
|
|
466
|
+
fail(`${at}.range must be 0.1-100`);
|
|
467
|
+
if (!number(l.start, 0, 60))
|
|
468
|
+
fail(`${at}.start must be 0-60`);
|
|
469
|
+
if (l.life !== null && !number(l.life, .01, 60))
|
|
470
|
+
fail(`${at}.life must be null (to the end of the cycle) or 0.01-60`);
|
|
471
|
+
if (l.intensityOverLife !== undefined)
|
|
472
|
+
checkCurve(l.intensityOverLife, `${at}.intensityOverLife`);
|
|
473
|
+
if (!number(l.flicker, 0, 1))
|
|
474
|
+
fail(`${at}.flicker must be 0-1`);
|
|
475
|
+
return l;
|
|
476
|
+
});
|
|
477
|
+
}
|
|
413
478
|
if (d.meshes)
|
|
414
479
|
d.meshes = d.meshes.map((raw, i) => {
|
|
415
480
|
const at = `meshes[${i}]`;
|
|
@@ -483,6 +548,10 @@ export function parseVfx(value) {
|
|
|
483
548
|
* this, so an effect that needs nothing new still plays on 1.36.
|
|
484
549
|
*/
|
|
485
550
|
export function minimumVersion(d) {
|
|
551
|
+
if (d.emitters.some((e) => e.trail !== undefined))
|
|
552
|
+
return 6;
|
|
553
|
+
if (d.lights !== undefined)
|
|
554
|
+
return 5;
|
|
486
555
|
if (d.emitters.some((e) => e.mesh !== undefined || e.sizeOverLifeXYZ !== undefined) || d.meshes !== undefined)
|
|
487
556
|
return 4;
|
|
488
557
|
return d.emitters.some((e) => e.look?.type === 'material') ? 3 : 2;
|
|
@@ -495,6 +564,11 @@ export function meshLayerDefaults() {
|
|
|
495
564
|
material: { ...materialDefaults(), masks: [] },
|
|
496
565
|
};
|
|
497
566
|
}
|
|
567
|
+
/** A new light: a warm glow just above the origin, lit for the whole cycle. */
|
|
568
|
+
export function lightLayerDefaults() {
|
|
569
|
+
return { enabled: true, position: [0, .5, 0], color: '#ffb066', intensity: 8, range: 6, start: 0, life: null, flicker: 0 };
|
|
570
|
+
}
|
|
571
|
+
export function lightLayer(id, patch = {}) { return { id, ...lightLayerDefaults(), ...patch }; }
|
|
498
572
|
export function meshLayer(id, patch = {}) { return { id, ...meshLayerDefaults(), ...patch }; }
|
|
499
573
|
/**
|
|
500
574
|
* The most particles an effect can have alive at once, estimated: per enabled
|
|
@@ -502,6 +576,10 @@ export function meshLayer(id, patch = {}) { return { id, ...meshLayerDefaults(),
|
|
|
502
576
|
* parent's count times what each parent particle spawns.
|
|
503
577
|
*/
|
|
504
578
|
export function particleBudget(d) {
|
|
579
|
+
return [...particleBudgets(d).values()].reduce((s, n) => s + n, 0);
|
|
580
|
+
}
|
|
581
|
+
/** The most particles each emitter can have alive at once (see particleBudget), by id. */
|
|
582
|
+
export function particleBudgets(d) {
|
|
505
583
|
const byId = new Map(d.emitters.map((e) => [e.id, e]));
|
|
506
584
|
const isChild = new Set(d.emitters.flatMap((e) => e.children.map((c) => c.emitter)));
|
|
507
585
|
const live = new Map();
|
|
@@ -522,7 +600,9 @@ export function particleBudget(d) {
|
|
|
522
600
|
live.set(id, n);
|
|
523
601
|
return n;
|
|
524
602
|
};
|
|
525
|
-
|
|
603
|
+
for (const e of d.emitters)
|
|
604
|
+
total(e.id);
|
|
605
|
+
return new Map(d.emitters.map((e) => [e.id, live.get(e.id) ?? 0]));
|
|
526
606
|
}
|
|
527
607
|
function checkV1(d, fail) {
|
|
528
608
|
if (!Array.isArray(d.emitters))
|
package/dist/vfx/index.d.ts
CHANGED
|
@@ -3,6 +3,7 @@ export * from './templates.js';
|
|
|
3
3
|
export { VfxInstance } from './VfxInstance.js';
|
|
4
4
|
export * from './material.js';
|
|
5
5
|
export * from './mesh.js';
|
|
6
|
+
export * from './trail.js';
|
|
6
7
|
export type { VfxInstanceOptions, VfxTextureSource } from './VfxInstance.js';
|
|
7
8
|
export { loadVfx, VfxEffect, siblingUrl, prepareSheetTexture } from './load.js';
|
|
8
9
|
export type { LoadVfxOptions } from './load.js';
|
package/dist/vfx/index.js
CHANGED
package/dist/vfx/load.d.ts
CHANGED
|
@@ -19,7 +19,10 @@ export declare class VfxEffect {
|
|
|
19
19
|
readonly textures: Map<string, T.Texture>;
|
|
20
20
|
private disposed;
|
|
21
21
|
constructor(document: VfxDocument, textures: Map<string, T.Texture>);
|
|
22
|
-
|
|
22
|
+
/** `{ lights: false }`: this copy builds no lights (see VfxInstanceOptions). */
|
|
23
|
+
spawn(options?: {
|
|
24
|
+
lights?: boolean;
|
|
25
|
+
}): VfxInstance;
|
|
23
26
|
/** Frees the shared textures. Dispose the spawned instances first. */
|
|
24
27
|
dispose(): void;
|
|
25
28
|
}
|
package/dist/vfx/load.js
CHANGED
|
@@ -18,10 +18,11 @@ export class VfxEffect {
|
|
|
18
18
|
this.textures = textures;
|
|
19
19
|
this.disposed = false;
|
|
20
20
|
}
|
|
21
|
-
|
|
21
|
+
/** `{ lights: false }`: this copy builds no lights (see VfxInstanceOptions). */
|
|
22
|
+
spawn(options = {}) {
|
|
22
23
|
if (this.disposed)
|
|
23
24
|
throw new Error(`VfxEffect "${this.document.name}" was disposed`);
|
|
24
|
-
return new VfxInstance(this.document, { textures: this.textures });
|
|
25
|
+
return new VfxInstance(this.document, { textures: this.textures, lights: options.lights });
|
|
25
26
|
}
|
|
26
27
|
/** Frees the shared textures. Dispose the spawned instances first. */
|
|
27
28
|
dispose() { this.disposed = true; for (const t of this.textures.values())
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Particle trails (format v6, umicat-design ADR-055 step 4): each particle
|
|
3
|
+
* remembers where it has been for `length` seconds and draws a camera-facing
|
|
4
|
+
* ribbon through those points. A ribbon, not Godot's TubeTrailMesh: from a
|
|
5
|
+
* game camera they read the same, and a ribbon is a quarter of the vertices.
|
|
6
|
+
*
|
|
7
|
+
* The ribbon is turned to the viewer in the VERTEX shader (each vertex knows
|
|
8
|
+
* its centre point, the trail's direction there and which side it is on), so
|
|
9
|
+
* the effect never needs to know where the camera is.
|
|
10
|
+
*/
|
|
11
|
+
import * as T from 'three';
|
|
12
|
+
import type { CompiledMaterial, Material } from './material.js';
|
|
13
|
+
export interface Trail {
|
|
14
|
+
/** Seconds of the particle's past the trail covers. */
|
|
15
|
+
length: number;
|
|
16
|
+
/** World width at the head. */
|
|
17
|
+
width: number;
|
|
18
|
+
/** Width along the trail (t = 0 at the particle, 1 at the tail end). Default: tapers to nothing. */
|
|
19
|
+
widthOverTrail?: {
|
|
20
|
+
points: [number, number][];
|
|
21
|
+
smooth?: boolean;
|
|
22
|
+
};
|
|
23
|
+
/**
|
|
24
|
+
* How the ribbon is drawn; u runs along it (0 at the particle, 1 at the
|
|
25
|
+
* tail), v across. Default: the particle's colour, fading to the tail.
|
|
26
|
+
* Animated numbers follow the PARTICLE's life.
|
|
27
|
+
*/
|
|
28
|
+
material?: Material;
|
|
29
|
+
}
|
|
30
|
+
/** Points per trail, at most: enough for a smooth curve, few enough for 4000 particles. */
|
|
31
|
+
export declare const TRAIL_SEGMENTS_MAX = 16;
|
|
32
|
+
/** Every trail point an effect can have alive at once, at most. */
|
|
33
|
+
export declare const TRAIL_POINT_BUDGET = 8000;
|
|
34
|
+
/** Points kept per trail, and the seconds between them. */
|
|
35
|
+
export declare function trailSampling(t: Trail): {
|
|
36
|
+
points: number;
|
|
37
|
+
interval: number;
|
|
38
|
+
};
|
|
39
|
+
/** Per-particle history: a ring of positions, newest last. */
|
|
40
|
+
export interface TrailHistory {
|
|
41
|
+
xyz: Float32Array;
|
|
42
|
+
count: number;
|
|
43
|
+
head: number;
|
|
44
|
+
acc: number;
|
|
45
|
+
}
|
|
46
|
+
export declare function newHistory(points: number): TrailHistory;
|
|
47
|
+
export declare function pushHistory(h: TrailHistory, x: number, y: number, z: number, points: number): void;
|
|
48
|
+
/** The k-th newest stored point (k = 0 is the newest). */
|
|
49
|
+
export declare function historyAt(h: TrailHistory, k: number, points: number, out: number[]): void;
|
|
50
|
+
export declare const trailVertex: (c: CompiledMaterial) => string;
|
|
51
|
+
/** One emitter's ribbons: a growable buffer rebuilt each frame. */
|
|
52
|
+
export declare class TrailMesh {
|
|
53
|
+
readonly material: T.ShaderMaterial;
|
|
54
|
+
readonly points: number;
|
|
55
|
+
readonly mesh: T.Mesh;
|
|
56
|
+
readonly geometry: T.BufferGeometry<T.NormalBufferAttributes, T.BufferGeometryEventMap>;
|
|
57
|
+
private capacity;
|
|
58
|
+
private attrs;
|
|
59
|
+
private index;
|
|
60
|
+
constructor(material: T.ShaderMaterial, points: number);
|
|
61
|
+
/** Room for `ribbons` trails of `points` points: 2 vertices a point, 2 triangles a segment. */
|
|
62
|
+
grow(ribbons: number): void;
|
|
63
|
+
/** Writes ribbon `r`: `pts` = its centre points head first (count <= points), the rest folded onto the last point. */
|
|
64
|
+
write(r: number, pts: number[][], count: number, rgba: number[], width: (u: number) => number, life: number, seed: number): void;
|
|
65
|
+
/** Draw the first `ribbons` written. */
|
|
66
|
+
commit(ribbons: number): void;
|
|
67
|
+
dispose(): void;
|
|
68
|
+
}
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Particle trails (format v6, umicat-design ADR-055 step 4): each particle
|
|
3
|
+
* remembers where it has been for `length` seconds and draws a camera-facing
|
|
4
|
+
* ribbon through those points. A ribbon, not Godot's TubeTrailMesh: from a
|
|
5
|
+
* game camera they read the same, and a ribbon is a quarter of the vertices.
|
|
6
|
+
*
|
|
7
|
+
* The ribbon is turned to the viewer in the VERTEX shader (each vertex knows
|
|
8
|
+
* its centre point, the trail's direction there and which side it is on), so
|
|
9
|
+
* the effect never needs to know where the camera is.
|
|
10
|
+
*/
|
|
11
|
+
import * as T from 'three';
|
|
12
|
+
/** Points per trail, at most: enough for a smooth curve, few enough for 4000 particles. */
|
|
13
|
+
export const TRAIL_SEGMENTS_MAX = 16;
|
|
14
|
+
/** Every trail point an effect can have alive at once, at most. */
|
|
15
|
+
export const TRAIL_POINT_BUDGET = 8000;
|
|
16
|
+
/** Points kept per trail, and the seconds between them. */
|
|
17
|
+
export function trailSampling(t) {
|
|
18
|
+
const segments = Math.max(2, Math.min(TRAIL_SEGMENTS_MAX, Math.ceil(t.length * 60)));
|
|
19
|
+
return { points: segments + 1, interval: t.length / segments };
|
|
20
|
+
}
|
|
21
|
+
export function newHistory(points) { return { xyz: new Float32Array(points * 3), count: 0, head: 0, acc: 0 }; }
|
|
22
|
+
export function pushHistory(h, x, y, z, points) {
|
|
23
|
+
h.xyz[h.head * 3] = x;
|
|
24
|
+
h.xyz[h.head * 3 + 1] = y;
|
|
25
|
+
h.xyz[h.head * 3 + 2] = z;
|
|
26
|
+
h.head = (h.head + 1) % points;
|
|
27
|
+
h.count = Math.min(points, h.count + 1);
|
|
28
|
+
}
|
|
29
|
+
/** The k-th newest stored point (k = 0 is the newest). */
|
|
30
|
+
export function historyAt(h, k, points, out) {
|
|
31
|
+
const i = ((h.head - 1 - k) % points + points) % points;
|
|
32
|
+
out[0] = h.xyz[i * 3];
|
|
33
|
+
out[1] = h.xyz[i * 3 + 1];
|
|
34
|
+
out[2] = h.xyz[i * 3 + 2];
|
|
35
|
+
}
|
|
36
|
+
export const trailVertex = (c) => `
|
|
37
|
+
attribute vec3 tCenter; attribute vec3 tDir; attribute vec4 tColor; attribute vec4 tMisc; // misc: (side -1/+1, width, u, unused)
|
|
38
|
+
attribute vec2 tLife;
|
|
39
|
+
varying vec2 vUv; varying vec4 vColor; varying vec2 vLife; varying vec3 vN; varying vec3 vV;
|
|
40
|
+
${c.code}
|
|
41
|
+
void main(){
|
|
42
|
+
vec4 cv = modelViewMatrix * vec4(tCenter, 1.0);
|
|
43
|
+
vec3 dv = (modelViewMatrix * vec4(tDir, 0.0)).xyz;
|
|
44
|
+
vec3 side = cross(dv, -cv.xyz);
|
|
45
|
+
float sl = length(side);
|
|
46
|
+
side = sl > 1e-8 ? side / sl : vec3(1.0, 0.0, 0.0);
|
|
47
|
+
float scale = length(modelMatrix[0].xyz);
|
|
48
|
+
cv.xyz += side * tMisc.x * tMisc.y * 0.5 * scale;
|
|
49
|
+
vUv = vec2(tMisc.z, tMisc.x * 0.5 + 0.5); vColor = tColor; vLife = tLife;
|
|
50
|
+
vV = -cv.xyz; vN = normalize(-cv.xyz);
|
|
51
|
+
gl_Position = projectionMatrix * cv;
|
|
52
|
+
}`;
|
|
53
|
+
/** One emitter's ribbons: a growable buffer rebuilt each frame. */
|
|
54
|
+
export class TrailMesh {
|
|
55
|
+
constructor(material, points) {
|
|
56
|
+
this.material = material;
|
|
57
|
+
this.points = points;
|
|
58
|
+
this.geometry = new T.BufferGeometry();
|
|
59
|
+
this.capacity = 0;
|
|
60
|
+
this.mesh = new T.Mesh(this.geometry, material);
|
|
61
|
+
this.mesh.frustumCulled = false;
|
|
62
|
+
this.grow(16);
|
|
63
|
+
}
|
|
64
|
+
/** Room for `ribbons` trails of `points` points: 2 vertices a point, 2 triangles a segment. */
|
|
65
|
+
grow(ribbons) {
|
|
66
|
+
if (ribbons <= this.capacity)
|
|
67
|
+
return;
|
|
68
|
+
const n = Math.max(ribbons, this.capacity * 2), v = n * this.points * 2;
|
|
69
|
+
const make = (size) => new T.BufferAttribute(new Float32Array(v * size), size).setUsage(T.DynamicDrawUsage);
|
|
70
|
+
this.attrs = { center: make(3), dir: make(3), color: make(4), misc: make(4), life: make(2) };
|
|
71
|
+
const g = this.geometry;
|
|
72
|
+
g.setAttribute('position', this.attrs.center); // three needs a `position`; the shader reads tCenter
|
|
73
|
+
g.setAttribute('tCenter', this.attrs.center);
|
|
74
|
+
g.setAttribute('tDir', this.attrs.dir);
|
|
75
|
+
g.setAttribute('tColor', this.attrs.color);
|
|
76
|
+
g.setAttribute('tMisc', this.attrs.misc);
|
|
77
|
+
g.setAttribute('tLife', this.attrs.life);
|
|
78
|
+
const idx = new Uint32Array(n * (this.points - 1) * 6);
|
|
79
|
+
for (let r = 0, w = 0; r < n; r++)
|
|
80
|
+
for (let k = 0; k < this.points - 1; k++) {
|
|
81
|
+
const a = (r * this.points + k) * 2;
|
|
82
|
+
idx[w++] = a;
|
|
83
|
+
idx[w++] = a + 1;
|
|
84
|
+
idx[w++] = a + 2;
|
|
85
|
+
idx[w++] = a + 1;
|
|
86
|
+
idx[w++] = a + 3;
|
|
87
|
+
idx[w++] = a + 2;
|
|
88
|
+
}
|
|
89
|
+
this.index = new T.BufferAttribute(idx, 1);
|
|
90
|
+
g.setIndex(this.index);
|
|
91
|
+
this.capacity = n;
|
|
92
|
+
}
|
|
93
|
+
/** Writes ribbon `r`: `pts` = its centre points head first (count <= points), the rest folded onto the last point. */
|
|
94
|
+
write(r, pts, count, rgba, width, life, seed) {
|
|
95
|
+
const { center, dir, color, misc, life: lf } = this.attrs;
|
|
96
|
+
const C = center.array, D = dir.array, K = color.array, M = misc.array, L = lf.array;
|
|
97
|
+
for (let k = 0; k < this.points; k++) {
|
|
98
|
+
const j = Math.min(k, count - 1), p = pts[j];
|
|
99
|
+
// Direction along the trail: towards the newer neighbour, so the head points where the particle is going.
|
|
100
|
+
const a = pts[Math.max(0, j - 1)], b = pts[Math.min(count - 1, j + 1)];
|
|
101
|
+
const dx = a[0] - b[0], dy = a[1] - b[1], dz = a[2] - b[2];
|
|
102
|
+
const u = count > 1 ? j / (count - 1) : 0, wd = k < count ? width(u) : 0;
|
|
103
|
+
for (let s = 0; s < 2; s++) {
|
|
104
|
+
const v = (r * this.points + k) * 2 + s;
|
|
105
|
+
C[v * 3] = p[0];
|
|
106
|
+
C[v * 3 + 1] = p[1];
|
|
107
|
+
C[v * 3 + 2] = p[2];
|
|
108
|
+
D[v * 3] = dx;
|
|
109
|
+
D[v * 3 + 1] = dy;
|
|
110
|
+
D[v * 3 + 2] = dz;
|
|
111
|
+
K[v * 4] = rgba[0];
|
|
112
|
+
K[v * 4 + 1] = rgba[1];
|
|
113
|
+
K[v * 4 + 2] = rgba[2];
|
|
114
|
+
K[v * 4 + 3] = rgba[3];
|
|
115
|
+
M[v * 4] = s ? 1 : -1;
|
|
116
|
+
M[v * 4 + 1] = wd;
|
|
117
|
+
M[v * 4 + 2] = u;
|
|
118
|
+
M[v * 4 + 3] = 0;
|
|
119
|
+
L[v * 2] = life;
|
|
120
|
+
L[v * 2 + 1] = seed;
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
/** Draw the first `ribbons` written. */
|
|
125
|
+
commit(ribbons) {
|
|
126
|
+
for (const a of Object.values(this.attrs))
|
|
127
|
+
a.needsUpdate = true;
|
|
128
|
+
this.geometry.setDrawRange(0, ribbons * (this.points - 1) * 6);
|
|
129
|
+
this.mesh.visible = ribbons > 0;
|
|
130
|
+
}
|
|
131
|
+
dispose() { this.geometry.dispose(); }
|
|
132
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@umicat/three-sdk",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.40.0",
|
|
4
4
|
"description": "Three.js runtime for Umicat games: the scene3d design format, its loader with physics, a kinematic character controller, and the Umicat platform via @umicat/platform-sdk.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|