@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 +24 -2
- package/dist/vfx/VfxInstance.d.ts +6 -0
- package/dist/vfx/VfxInstance.js +188 -24
- package/dist/vfx/document.d.ts +45 -1
- package/dist/vfx/document.js +109 -7
- package/dist/vfx/index.d.ts +2 -0
- package/dist/vfx/index.js +2 -0
- package/dist/vfx/material.d.ts +215 -0
- package/dist/vfx/material.js +532 -0
- package/dist/vfx/mesh.d.ts +96 -0
- package/dist/vfx/mesh.js +161 -0
- package/package.json +1 -1
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()`.
|
|
93
|
-
|
|
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. */
|
package/dist/vfx/VfxInstance.js
CHANGED
|
@@ -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 =
|
|
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 =
|
|
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
|
-
|
|
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
|
|
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,
|
|
187
|
+
buildParticles(config, index, root, textureOf) {
|
|
166
188
|
const geometry = new T.InstancedBufferGeometry();
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
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:
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
551
|
-
|
|
552
|
-
|
|
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'));
|
package/dist/vfx/document.d.ts
CHANGED
|
@@ -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
|