cozyclay 2.1.0 → 3.0.0

package/src/effects/effect-meshes.js

@@ -0,0 +1,232 @@
+/**
+ * GPU side of the effects: one instanced quad mesh for every particle in the
+ * scene and one for every trail-ribbon quad, written from evaluateEffects.
+ *
+ * Quads face whichever camera draws them (the editor, the shot camera, a
+ * contact-sheet view), so the CPU only redoes work when the frame changes.
+ * Blending is premultiplied: a particle writes (rgb x a, a) to blend normally
+ * or (rgb x a, cover x a) to mostly add, so smoke and fire share one draw. Smoke-like
+ * particles are lit by the stage's lights (wrapped, from the camera side);
+ * additive ones are emissive. Both take the stage fog, write no depth and
+ * cast no shadow. Their instance matrices are all zero, so a pass that
+ * swaps in its own material (depth, normal) collapses them to nothing.
+ */
+import * as THREE from "three";
+import { EFFECT_PARTICLE_CAP, EFFECT_SEGMENT_CAP, evaluateEffects } from "./simulate.js";
+
+/** How much of what is behind an emissive (fire, sparks) particle it hides:
+ * 0 would be purely additive, which vanishes over a light stage; at 0.85 a
+ * flame stays orange on the daylight grey and still glows on a night sky. */
+const EMISSIVE_COVER = 0.85;
+const SHADE = /* glsl */ `
+vec3 effectLight(vec3 base, vec3 viewPos) {
+	vec3 n = vec3(0.0, 0.0, 1.0);
+	vec3 irradiance = getAmbientLightIrradiance(ambientLightColor);
+	#if NUM_HEMI_LIGHTS > 0
+	for (int i = 0; i < NUM_HEMI_LIGHTS; i++) irradiance += getHemisphereLightIrradiance(hemisphereLights[i], n);
+	#endif
+	#if NUM_DIR_LIGHTS > 0
+	for (int i = 0; i < NUM_DIR_LIGHTS; i++) irradiance += directionalLights[i].color * (0.55 + 0.45 * dot(n, directionalLights[i].direction));
+	#endif
+	#if NUM_POINT_LIGHTS > 0
+	for (int i = 0; i < NUM_POINT_LIGHTS; i++) {
+		vec3 toLight = pointLights[i].position - viewPos; float d = length(toLight);
+		irradiance += pointLights[i].color * getDistanceAttenuation(d, pointLights[i].distance, pointLights[i].decay) * (0.55 + 0.45 * dot(n, toLight / max(d, 1e-4)));
+	}
+	#endif
+	#if NUM_SPOT_LIGHTS > 0
+	for (int i = 0; i < NUM_SPOT_LIGHTS; i++) {
+		vec3 toLight = spotLights[i].position - viewPos; float d = length(toLight); vec3 l = toLight / max(d, 1e-4);
+		float cone = getSpotAttenuation(spotLights[i].coneCos, spotLights[i].penumbraCos, dot(l, spotLights[i].direction));
+		irradiance += spotLights[i].color * cone * getDistanceAttenuation(d, spotLights[i].distance, spotLights[i].decay) * (0.55 + 0.45 * dot(n, l));
+	}
+	#endif
+	return base * irradiance * RECIPROCAL_PI;
+}
+// Tone map and encode like every stage material, then fog (additive light
+// fades into it instead), then premultiply.
+vec4 effectOut(vec3 color, float alpha, float additive) {
+	gl_FragColor = vec4(color, 1.0);
+	#include <tonemapping_fragment>
+	#include <colorspace_fragment>
+	#ifdef USE_FOG
+	#ifdef FOG_EXP2
+	float fogF = 1.0 - exp(-fogDensity * fogDensity * vFogDepth * vFogDepth);
+	#else
+	float fogF = smoothstep(fogNear, fogFar, vFogDepth);
+	#endif
+	gl_FragColor.rgb = additive > 0.5 ? gl_FragColor.rgb * (1.0 - fogF) : mix(gl_FragColor.rgb, fogColor, fogF);
+	#endif
+	return vec4(gl_FragColor.rgb * alpha, additive > 0.5 ? alpha * ${EMISSIVE_COVER.toFixed(2)} : alpha);
+}
+`;
+const FRAGMENT_HEAD = /* glsl */ `
+#include <common>
+#include <lights_pars_begin>
+#include <fog_pars_fragment>
+uniform float globalOpacity;
+${SHADE}`;
+
+const PARTICLE_VERTEX = /* glsl */ `
+attribute vec3 iPos; attribute vec4 iParams; attribute vec4 iColor; attribute vec4 iStreak;
+varying vec2 vUv; varying vec4 vColor; varying float vLit; varying float vAdd; varying vec3 vViewPos;
+#include <fog_pars_vertex>
+void main() {
+	vec4 center = viewMatrix * vec4(iPos, 1.0);
+	vec3 streak = (viewMatrix * vec4(iStreak.xyz, 0.0)).xyz;
+	float size = iParams.x, len = length(streak.xy);
+	vec2 offset;
+	if (len > size * 0.25) {
+		vec2 along = streak.xy / len;
+		offset = along * position.y * (size + len) + vec2(-along.y, along.x) * position.x * size;
+	} else {
+		float c = cos(iParams.y), s = sin(iParams.y);
+		offset = size * vec2(c * position.x - s * position.y, s * position.x + c * position.y);
+	}
+	vec4 mvPosition = center + vec4(offset, 0.0, 0.0);
+	gl_Position = projectionMatrix * mvPosition;
+	vUv = (uv + vec2(mod(iParams.z, 2.0), floor(iParams.z / 2.0))) * 0.5;
+	vColor = iColor; vLit = iParams.w; vAdd = iStreak.w; vViewPos = mvPosition.xyz;
+	#include <fog_vertex>
+}`;
+const PARTICLE_FRAGMENT = /* glsl */ `
+uniform sampler2D map;
+varying vec2 vUv; varying vec4 vColor; varying float vLit; varying float vAdd; varying vec3 vViewPos;
+${FRAGMENT_HEAD}
+void main() {
+	float alpha = vColor.a * texture2D(map, vUv).r * globalOpacity;
+	if (alpha < 0.002) discard;
+	gl_FragColor = effectOut(vLit > 0.5 ? effectLight(vColor.rgb, vViewPos) : vColor.rgb, alpha, vAdd);
+}`;
+
+const RIBBON_VERTEX = /* glsl */ `
+attribute vec3 rA0; attribute vec3 rB0; attribute vec3 rA1; attribute vec3 rB1; attribute vec2 rAlpha; attribute vec4 rColor;
+varying float vAlpha; varying float vAcross; varying vec3 vColor; varying float vAdd; varying vec3 vViewPos;
+#include <fog_pars_vertex>
+void main() {
+	float along = position.x + 0.5, across = position.y + 0.5;
+	vec3 world = mix(mix(rA0, rB0, across), mix(rA1, rB1, across), along);
+	vec4 mvPosition = viewMatrix * vec4(world, 1.0);
+	gl_Position = projectionMatrix * mvPosition;
+	vAlpha = mix(rAlpha.x, rAlpha.y, along); vAcross = across; vColor = rColor.rgb; vAdd = rColor.a; vViewPos = mvPosition.xyz;
+	#include <fog_vertex>
+}`;
+const RIBBON_FRAGMENT = /* glsl */ `
+varying float vAlpha; varying float vAcross; varying vec3 vColor; varying float vAdd; varying vec3 vViewPos;
+${FRAGMENT_HEAD}
+void main() {
+	float alpha = vAlpha * pow(sin(PI * vAcross), 0.6) * globalOpacity;
+	if (alpha < 0.002) discard;
+	gl_FragColor = effectOut(vAdd > 0.5 ? vColor : effectLight(vColor, vViewPos), alpha, vAdd);
+}`;
+
+/** A 2x2 atlas of soft puffs: cell 0 a clean round falloff, cells 1-3 seeded wisps. */
+function puffAtlas() {
+	const size = 128, cell = 64, data = new Uint8Array(size * size * 4);
+	const hash = (x, y, v) => { const h = Math.sin(x * 127.1 + y * 311.7 + v * 74.7) * 43758.5453; return h - Math.floor(h); };
+	const noise = (x, y, v) => {
+		const ix = Math.floor(x), iy = Math.floor(y), fx = x - ix, fy = y - iy, sx = fx * fx * (3 - 2 * fx), sy = fy * fy * (3 - 2 * fy);
+		const top = hash(ix, iy, v) + (hash(ix + 1, iy, v) - hash(ix, iy, v)) * sx, bottom = hash(ix, iy + 1, v) + (hash(ix + 1, iy + 1, v) - hash(ix, iy + 1, v)) * sx;
+		return top + (bottom - top) * sy;
+	};
+	for (let v = 0; v < 4; v += 1) {
+		for (let y = 0; y < cell; y += 1) {
+			for (let x = 0; x < cell; x += 1) {
+				const nx = (x + 0.5) / cell * 2 - 1, ny = (y + 0.5) / cell * 2 - 1, r = Math.hypot(nx, ny);
+				let a = Math.exp(-r * r * 4.2) * (1 - Math.min(1, Math.max(0, (r - 0.82) / 0.18)));
+				if (v > 0) {
+					const fbm = 0.55 * noise(nx * 3 + 5, ny * 3, v) + 0.3 * noise(nx * 6, ny * 6 + 3, v) + 0.15 * noise(nx * 12 + 1, ny * 12, v);
+					a *= Math.min(1, Math.max(0, 1.6 * fbm - 0.25));
+				}
+				const i = (((v >> 1) * cell + y) * size + (v & 1) * cell + x) * 4;
+				data[i] = data[i + 1] = data[i + 2] = data[i + 3] = Math.round(255 * Math.min(1, a));
+			}
+		}
+	}
+	const texture = new THREE.DataTexture(data, size, size, THREE.RGBAFormat);
+	texture.minFilter = THREE.LinearMipmapLinearFilter;
+	texture.magFilter = THREE.LinearFilter;
+	texture.generateMipmaps = true;
+	texture.needsUpdate = true;
+	return texture;
+}
+
+function effectMaterial(vertexShader, fragmentShader, extra = {}) {
+	return new THREE.ShaderMaterial({
+		uniforms: { ...THREE.UniformsUtils.merge([THREE.UniformsLib.lights, THREE.UniformsLib.fog]), globalOpacity: { value: 1 }, ...extra },
+		vertexShader, fragmentShader, lights: true, fog: true, transparent: true, depthWrite: false, side: THREE.DoubleSide,
+		blending: THREE.CustomBlending, blendEquation: THREE.AddEquation, blendSrc: THREE.OneFactor, blendDst: THREE.OneMinusSrcAlphaFactor,
+		blendSrcAlpha: THREE.OneFactor, blendDstAlpha: THREE.OneMinusSrcAlphaFactor,
+	});
+}
+
+function instancedQuads(material, capacity, layout) {
+	const geometry = new THREE.PlaneGeometry(1, 1);
+	const attributes = {};
+	for (const [name, width] of Object.entries(layout)) {
+		attributes[name] = new THREE.InstancedBufferAttribute(new Float32Array(capacity * width), width).setUsage(THREE.DynamicDrawUsage);
+		geometry.setAttribute(name, attributes[name]);
+	}
+	const mesh = new THREE.InstancedMesh(geometry, material, capacity);
+	mesh.instanceMatrix.array.fill(0);
+	mesh.count = 0;
+	mesh.frustumCulled = false;
+	mesh.renderOrder = 5;
+	mesh.raycast = () => {};
+	// The editor's ink prepass outlines geometry; a puff of smoke is none.
+	mesh.userData.noInk = true;
+	return { mesh, attributes };
+}
+
+const flush = (attributes, count) => {
+	for (const attribute of Object.values(attributes)) {
+		attribute.clearUpdateRanges();
+		attribute.addUpdateRange(0, count * attribute.itemSize);
+		attribute.needsUpdate = true;
+	}
+};
+
+/** The two meshes and `update(scene, frame, opacity)`, which redraws every effect at `frame`. */
+export function createEffectMeshes() {
+	const map = puffAtlas();
+	const particles = instancedQuads(effectMaterial(PARTICLE_VERTEX, PARTICLE_FRAGMENT, { map: { value: map } }), EFFECT_PARTICLE_CAP, { iPos: 3, iParams: 4, iColor: 4, iStreak: 4 });
+	const ribbons = instancedQuads(effectMaterial(RIBBON_VERTEX, RIBBON_FRAGMENT), EFFECT_SEGMENT_CAP, { rA0: 3, rB0: 3, rA1: 3, rB1: 3, rAlpha: 2, rColor: 4 });
+	const p = particles.attributes, r = ribbons.attributes;
+	return {
+		particles: particles.mesh,
+		ribbons: ribbons.mesh,
+		update(scene, frame, opacity = 1) {
+			let n = 0, m = 0;
+			evaluateEffects(scene.records, scene, frame, {
+				particle(q) {
+					if (n >= EFFECT_PARTICLE_CAP) return;
+					p.iPos.array.set([q.x, q.y, q.z], n * 3);
+					p.iParams.array.set([q.size, q.angle, q.variant, q.additive ? 0 : 1], n * 4);
+					p.iColor.array.set([q.r, q.g, q.b, q.alpha], n * 4);
+					p.iStreak.array.set([q.sx, q.sy, q.sz, q.additive ? 1 : 0], n * 4);
+					n += 1;
+				},
+				segment(sg, em) {
+					if (m >= EFFECT_SEGMENT_CAP) return;
+					r.rA0.array.set(sg.a0, m * 3); r.rB0.array.set(sg.b0, m * 3); r.rA1.array.set(sg.a1, m * 3); r.rB1.array.set(sg.b1, m * 3);
+					r.rAlpha.array.set([sg.alpha0, sg.alpha1], m * 2);
+					r.rColor.array.set([...em.rgb, em.effect.additive ? 1 : 0], m * 4);
+					m += 1;
+				},
+			});
+			particles.mesh.count = n;
+			ribbons.mesh.count = m;
+			flush(p, n);
+			flush(r, m);
+			for (const mesh of [particles.mesh, ribbons.mesh]) mesh.material.uniforms.globalOpacity.value = opacity;
+		},
+		dispose() {
+			map.dispose();
+			for (const mesh of [particles.mesh, ribbons.mesh]) {
+				mesh.geometry.dispose();
+				mesh.material.dispose();
+				mesh.dispose?.();
+			}
+		},
+	};
+}

package/src/effects/effect-record.js

@@ -0,0 +1,103 @@
+/**
+ * The `object.effect` record: an emitter of smoke, fire, rain or a motion
+ * trail. Pure data and clamps, shared by the object store, the agent schema
+ * and the simulation (src/effects/simulate.js).
+ *
+ * A preset fills every field, and explicit fields override it. The record
+ * stores the MERGED numbers, so a readback shows exactly what is drawn.
+ * Units: metres, seconds, m/s, m/s² (+ gravity falls).
+ */
+import { normalizeObjectColor } from "../object-colors.js";
+
+export const EFFECT_KIND = "effect";
+
+/** Zero size on purpose, like an Empty: an effect is never a blocker, a
+ * support or a collision box; only its particles are seen. */
+export const EFFECT_ENTRY = { kind: EFFECT_KIND, label: "Effect", group: "Effects", footprint: { width: 0, depth: 0 }, height: 0, color: "#7fd4f0" };
+
+const vec = (x, y, z) => ({ x, y, z });
+const ZERO = vec(0, 0, 0);
+
+/**
+ * Each preset at its natural scale. Smoke is a cigarette's: a 12 mm wisp that
+ * rises ~0.45 m over ~2.8 s while it widens 7x. Fire is a small campfire
+ * (~0.4 m of flame); scale size/area/life down for a lighter.
+ */
+export const EFFECT_PRESETS = Object.freeze({
+	smoke: { rate: 60, life: 2.8, size: 0.012, grow: 6, speed: 0.05, spread: 0.1, gravity: -0.3, wind: vec(0.02, 0, 0), color: "#7d8a99", opacity: 0.42, additive: false, area: ZERO, width: 0 },
+	exhale: { rate: 120, life: 2.4, size: 0.035, grow: 8, speed: 0.9, spread: 0.35, gravity: -0.35, wind: vec(0.02, 0, 0), color: "#a3abb4", opacity: 0.3, additive: false, area: vec(0.01, 0, 0.01), width: 0 },
+	steam: { rate: 26, life: 2, size: 0.03, grow: 4, speed: 0.1, spread: 0.2, gravity: -0.45, wind: vec(0.02, 0, 0), color: "#bcc5ce", opacity: 0.2, additive: false, area: vec(0.07, 0, 0.07), width: 0 },
+	fire: { rate: 140, life: 0.75, size: 0.12, grow: 0.3, speed: 0.4, spread: 0.15, gravity: -2.2, wind: ZERO, color: "#ff7a1f", opacity: 1, additive: true, area: vec(0.22, 0, 0.22), width: 0 },
+	sparks: { rate: 40, life: 1, size: 0.012, grow: 0.6, speed: 2.6, spread: 0.55, gravity: 6, wind: ZERO, color: "#ff9d33", opacity: 1, additive: true, area: vec(0.05, 0, 0.05), width: 0 },
+	dust: { rate: 30, life: 7, size: 0.014, grow: 1.2, speed: 0, spread: 1, gravity: 0.01, wind: vec(0.04, 0, 0.01), color: "#a89a82", opacity: 0.55, additive: false, area: vec(3, 2.2, 3), width: 0 },
+	rain: { rate: 1600, life: 1.2, size: 0.01, grow: 1, speed: 0, spread: 0, gravity: 9.8, wind: ZERO, color: "#9aabbd", opacity: 0.4, additive: false, area: vec(8, 5, 8), width: 0 },
+	snow: { rate: 220, life: 8, size: 0.025, grow: 1, speed: 0, spread: 0, gravity: 9.8, wind: vec(0.1, 0, 0), color: "#ffffff", opacity: 0.85, additive: false, area: vec(8, 4, 8), width: 0 },
+	trail: { rate: 0, life: 0.3, size: 0, grow: 1, speed: 0, spread: 0, gravity: 0, wind: ZERO, color: "#a7b8ca", opacity: 0.75, additive: false, area: ZERO, width: 0.5 },
+});
+const EFFECT_PRESET_NAMES = Object.freeze(Object.keys(EFFECT_PRESETS));
+
+const LIMITS = { rate: [0, 2000], life: [0.05, 12], size: [0.001, 5], grow: [0.05, 20], speed: [0, 60], spread: [0, 1], gravity: [-30, 30], opacity: [0, 1], width: [0, 10] };
+const VEC_LIMITS = { wind: [-20, 20], area: [0, 100] };
+const SEED_MAX = 2147483647;
+
+const clampTo = ([min, max], value, fallback) => {
+	const n = Number(value);
+	return Number.isFinite(n) ? Math.min(max, Math.max(min, n)) : fallback;
+};
+
+/** The stored effect: `value`'s preset filled in, its explicit fields clamped over it. */
+export function normalizeEffect(value) {
+	const given = value && typeof value === "object" && !Array.isArray(value) ? value : {};
+	const preset = EFFECT_PRESET_NAMES.includes(given.preset) ? given.preset : "smoke";
+	const base = EFFECT_PRESETS[preset];
+	const out = { preset };
+	for (const [key, range] of Object.entries(LIMITS)) out[key] = clampTo(range, given[key], base[key]);
+	for (const [key, range] of Object.entries(VEC_LIMITS)) {
+		const v = given[key] && typeof given[key] === "object" ? given[key] : {};
+		out[key] = vec(...["x", "y", "z"].map((axis) => clampTo(range, v[axis], base[key][axis])));
+	}
+	out.color = normalizeObjectColor(given.color) ?? base.color;
+	out.additive = typeof given.additive === "boolean" ? given.additive : base.additive;
+	const seed = Number(given.seed);
+	out.seed = Number.isFinite(seed) ? Math.min(SEED_MAX, Math.max(0, Math.round(seed))) : 1;
+	return out;
+}
+
+/** The record fields an effect carries (none for any other renderer): one
+ * spread in normalizeSceneObject and createSceneObject. */
+export function effectFields(record) {
+	return record?.renderer === EFFECT_KIND ? { effect: normalizeEffect(record.effect) } : {};
+}
+
+/**
+ * An `object.set` op with a NEW preset gets that preset's defaults written
+ * out, so the set merges onto the preset rather than onto the old preset's
+ * numbers: { preset: "fire" } on a smoke emitter becomes fire, and
+ * { preset: "fire", rate: 40 } is fire at 40/s. Any other op is returned as is.
+ */
+export function effectPresetSet(op, objects) {
+	const preset = op?.set?.effect?.preset;
+	if (!EFFECT_PRESET_NAMES.includes(preset)) return op;
+	const current = objects?.find?.((object) => object.id === op.id)?.effect;
+	if (current?.preset === preset) return op;
+	const defaults = structuredClone(EFFECT_PRESETS[preset]);
+	return { ...op, set: { ...op.set, effect: { ...defaults, seed: current?.seed ?? 1, ...op.set.effect } } };
+}
+
+const num = (minimum, maximum) => ({ type: "number", minimum, maximum });
+const vecSchema = ([min, max]) => ({ type: "object", properties: { x: num(min, max), y: num(min, max), z: num(min, max) }, required: [], additionalProperties: false });
+
+/** The wire shape of `object.effect` for object.set / patch_elements (every member optional). */
+export const EFFECT_VALUE_SCHEMA = Object.freeze({
+	type: "object",
+	properties: {
+		preset: { type: "string", enum: [...EFFECT_PRESET_NAMES] },
+		...Object.fromEntries(Object.entries(LIMITS).map(([key, [min, max]]) => [key, num(min, max)])),
+		...Object.fromEntries(Object.entries(VEC_LIMITS).map(([key, range]) => [key, vecSchema(range)])),
+		color: { type: "string", minLength: 1, maxLength: 32, pattern: "^#[0-9a-fA-F]{6}$" },
+		additive: { type: "boolean" },
+		seed: { type: "integer", minimum: 0, maximum: SEED_MAX },
+	},
+	required: [],
+	additionalProperties: false,
+});

package/src/effects/emitter.js

@@ -0,0 +1,59 @@
+/**
+ * Where an effect emitter is, whether it is shown and how strongly it emits,
+ * at any frame: the one place the simulation reads the scene from.
+ *
+ * Everything here is a pure function of (records, take, frame), so a frame
+ * evaluates the same whether it is scrubbed to, played into or exported.
+ */
+import { Euler, Matrix4, Quaternion, Vector3 } from "three";
+import { sceneObjectTravelMatrixAt, trackShown } from "../object-travel.js";
+
+const DEG = Math.PI / 180;
+const scratchMatrix = new Matrix4();
+const scratchPos = new Vector3();
+const scratchQuat = new Quaternion();
+const scratchScale = new Vector3();
+const scratchEuler = new Euler();
+
+/** False while the take hides the record or any record it is grouped under
+ * (a smoke emitter on a cigarette still in the pocket), and for a
+ * showOnlyInTake emitter no take drives (a kit's tip smoke in a static scene). */
+export function emitterShown(lookup, record, frame, take) {
+	return trackShown(record.id, frame, take, lookup);
+}
+
+function authoredPose(record) {
+	scratchPos.set(record.x ?? 0, record.y ?? 0, record.z ?? 0);
+	scratchQuat.setFromEuler(scratchEuler.set((record.rotX ?? 0) * DEG, (record.rot ?? 0) * DEG, (record.rotZ ?? 0) * DEG, "XYZ"));
+}
+
+/**
+ * The emitter's world position and orientation at `frame`, scale left out:
+ * effect sizes are metres whatever the record's scale.
+ *
+ * Routed, hinged, take-carried and parented records come from
+ * sceneObjectTravelMatrixAt. A record pinned to a character bone (`attach`)
+ * has no pose at other frames outside the live rig, so `live(id, out)` gives
+ * its current world matrix for every frame (null falls back to the numbers).
+ *
+ * @returns {{ p: number[], q: number[] }}
+ */
+export function emitterPoseAt(lookup, record, frame, take, live = null) {
+	const world = record.attach ? live?.(record.id, scratchMatrix) ?? null : sceneObjectTravelMatrixAt(lookup, record.id, frame, take ?? {}, scratchMatrix);
+	if (world) world.decompose(scratchPos, scratchQuat, scratchScale);
+	else authoredPose(record);
+	return { p: [scratchPos.x, scratchPos.y, scratchPos.z], q: [scratchQuat.x, scratchQuat.y, scratchQuat.z, scratchQuat.w] };
+}
+
+/** `v` (3 numbers) turned by unit quaternion `q`, into `out`. */
+export function rotate(q, x, y, z, out) {
+	const [qx, qy, qz, qw] = q;
+	const ix = qw * x + qy * z - qz * y;
+	const iy = qw * y + qz * x - qx * z;
+	const iz = qw * z + qx * y - qy * x;
+	const iw = -qx * x - qy * y - qz * z;
+	out[0] = ix * qw + iw * -qx + iy * -qz - iz * -qy;
+	out[1] = iy * qw + iw * -qy + iz * -qx - ix * -qz;
+	out[2] = iz * qw + iw * -qz + ix * -qy - iy * -qx;
+	return out;
+}

package/src/effects/simulate.js

@@ -0,0 +1,261 @@
+/**
+ * Effect particles at a frame, computed from nothing but the frame.
+ *
+ * Particle k of an emitter belongs to integer frame s when the seeded count
+ * for s (rate x take level / fps, stochastically rounded) exceeds k, and only
+ * while the emitter is shown at s. It is born a seeded u in [0, 1) frames
+ * before s, where the emitter was then: its pose at s, moved back along the
+ * step from s - 1 by u (exactly the pose at s for u = 0). Its state at frame
+ * f is analytic in its age (f - s + u) / fps: drag toward wind plus
+ * gravity, a seeded sway/curl drift, size growth and an opacity fade. No
+ * state is carried between frames, so scrubbing, playback, capture and
+ * export all draw the same particles. A trail is a ribbon through the
+ * emitter's own pose over the last `life` seconds instead.
+ */
+import { emitterPoseAt, emitterShown, rotate } from "./emitter.js";
+import { trackLevel } from "../object-travel.js";
+import { EFFECT_KIND, normalizeEffect } from "./effect-record.js";
+
+/** Live particles drawn per scene; beyond it every emitter is thinned evenly. */
+export const EFFECT_PARTICLE_CAP = 2000;
+/** Trail ribbon quads per scene, shared evenly by the trail emitters. */
+export const EFFECT_SEGMENT_CAP = 512;
+const TRAIL_SUBSTEPS = 4;
+/** Edge travel per frame (m) under which a trail stretch counts as still. */
+const TRAIL_STILL_M = 0.002;
+/** Edge speed (m/s) at which a swoosh is fully opaque; slower motion fades it. */
+const TRAIL_FULL_SPEED = 2;
+
+// The shape of each preset that is not authored: drag (1/s), sway/curl/jitter
+// drift (m), fades, spread of life/size, spin (rad/s), streak (s of velocity),
+// flicker, a lift of the birth point (x start size, so a flame on the deck
+// starts above it), a droop of the throw (a share of the speed turned down),
+// and whether births fill a volume (rain/snow/dust).
+const LOOK = { drag: 1.5, sway: 0, curl: 0, curlRate: 2, jitter: 0, fadeIn: 0.05, fadeOut: 1, lifeVar: 0.2, sizeVar: 0.3, growPow: 1, spin: 0, streak: 0, flicker: 0, twinkle: 0, lift: 0, droop: 0, tint: null, clean: false, volume: false, top: false };
+const LOOKS = {
+	smoke: { ...LOOK, drag: 1.7, sway: 0.012, curl: 0.01, curlRate: 2.2, jitter: 0.005, fadeIn: 0.04, fadeOut: 1, lifeVar: 0.25, sizeVar: 0.25, growPow: 0.8, spin: 0.6 },
+	// a breath leaves the lips forward and a little down (droop: a downward share of the speed), then rises and spreads
+	exhale: { ...LOOK, drag: 3.2, sway: 0.02, curl: 0.03, curlRate: 1.6, jitter: 0.03, fadeIn: 0.03, fadeOut: 1.5, lifeVar: 0.3, sizeVar: 0.35, growPow: 0.6, spin: 0.8, droop: 0.25 },
+	steam: { ...LOOK, drag: 1.8, sway: 0.03, curl: 0.025, curlRate: 2.5, jitter: 0.015, fadeIn: 0.12, fadeOut: 1.8, lifeVar: 0.3, sizeVar: 0.35, growPow: 0.8, spin: 0.5 },
+	fire: { ...LOOK, drag: 3, sway: 0.01, curl: 0.03, curlRate: 5, jitter: 0.03, fadeIn: 0.06, fadeOut: 2.2, lifeVar: 0.35, spin: 1.5, streak: 0.15, flicker: 0.35, lift: 0.5, tint: "fire", clean: true },
+	sparks: { ...LOOK, drag: 0.8, jitter: 0.05, fadeIn: 0, fadeOut: 0.7, lifeVar: 0.5, sizeVar: 0.4, streak: 0.035, flicker: 0.5, tint: "spark", clean: true },
+	dust: { ...LOOK, drag: 0.8, curl: 0.04, curlRate: 0.7, jitter: 0.04, fadeIn: 0.2, fadeOut: 0.25, lifeVar: 0.3, sizeVar: 0.4, twinkle: 0.4, clean: true, volume: true },
+	rain: { ...LOOK, drag: 1.4, fadeIn: 0.04, fadeOut: 0, lifeVar: 0, sizeVar: 0.2, streak: 0.035, clean: true, volume: true, top: true },
+	snow: { ...LOOK, drag: 12, curl: 0.08, curlRate: 1.3, jitter: 0.05, fadeIn: 0.04, fadeOut: 0.1, lifeVar: 0, sizeVar: 0.35, spin: 1, clean: true, volume: true, top: true },
+	trail: LOOK,
+};
+
+const mix32 = (h) => {
+	h = Math.imul(h ^ (h >>> 16), 0x7feb352d);
+	h = Math.imul(h ^ (h >>> 15), 0x846ca68b);
+	return (h ^ (h >>> 16)) >>> 0;
+};
+/** Uniform [0, 1) for (seed, birth frame, particle, channel); pure. */
+const rnd = (seed, s, k, c) => mix32(mix32(mix32(seed + Math.imul(s, 0x27d4eb2f)) ^ Math.imul(k + 7, 0x165667b1)) + c) / 4294967296;
+const hashText = (text) => {
+	let h = 0x811c9dc5;
+	for (let i = 0; i < text.length; i += 1) h = Math.imul(h ^ text.charCodeAt(i), 0x01000193);
+	return h >>> 0;
+};
+const toLinear = (c) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+const linearRgb = (hex) => [1, 3, 5].map((i) => toLinear(parseInt(hex.slice(i, i + 2), 16) / 255));
+const smooth = (x) => (x >= 1 ? 1 : x <= 0 ? 0 : x * x * (3 - 2 * x));
+
+function emitterOf(record, scene) {
+	const effect = record.effect?.preset ? record.effect : normalizeEffect(record.effect);
+	const seed = mix32(effect.seed ^ hashText(record.id));
+	const poses = new Map();
+	const hidden = scene.hidden?.has?.(record.id) === true;
+	const at = (s) => Math.max(0, s);
+	const look = LOOKS[effect.preset] ?? LOOK, fall = effect.gravity / look.drag - effect.wind.y;
+	return {
+		id: record.id, effect, seed, look, trail: effect.preset === "trail", rgb: linearRgb(effect.color),
+		// Rain and snow fall from the box's top at terminal speed: they are gone once they reach its floor.
+		fallLife: look.top && fall > 0 ? effect.area.y / fall : Infinity,
+		phase: [0, 1, 2, 3].map((c) => 2 * Math.PI * rnd(seed, 0, -1, 90 + c)),
+		pose(s) {
+			let pose = poses.get(at(s));
+			if (!pose) poses.set(at(s), (pose = emitterPoseAt(scene.lookup, record, at(s), scene.take, scene.live)));
+			return pose;
+		},
+		/** Emission strength at frame s: 0 hidden, else the take level (1 without a track). */
+		level: (s) => (hidden || !emitterShown(scene.lookup, record, at(s), scene.take) ? 0 : trackLevel(record.id, at(s), scene.take)),
+	};
+}
+
+/** How many times the births at s are split so a fast emitter still lays a
+ * continuous stream (one particle per half a start size of travel, at most 8);
+ * the smoke emitted is the same, each part carries a share of the opacity. */
+function splitAt(em, s, perFrame) {
+	if (em.look.volume || !(em.effect.size > 0)) return 1;
+	const [a, b] = [em.pose(s).p, em.pose(s - 1).p];
+	const need = Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]) / (0.5 * em.effect.size);
+	return Math.min(8, Math.max(1, need / perFrame));
+}
+
+/** Every particle alive at `frame`, oldest birth first: visit(s, k, u, age, life, split). */
+function forEachLive(em, frame, fps, visit) {
+	const { effect, look, seed } = em;
+	const last = Math.floor(frame);
+	for (let s = Math.floor(frame - effect.life * (1 + look.lifeVar) * fps) - 1; s <= last; s += 1) {
+		const perFrame = (effect.rate * em.level(s)) / fps;
+		if (!(perFrame > 0)) continue;
+		const split = splitAt(em, s, perFrame);
+		const count = Math.floor(perFrame * split + rnd(seed, s, -1, 0));
+		for (let k = 0; k < count; k += 1) {
+			const life = Math.min(em.fallLife, effect.life * (1 + look.lifeVar * (2 * rnd(seed, s, k, 1) - 1)));
+			const u = rnd(seed, s, k, 2);
+			const age = (frame - s + u) / fps;
+			if (age >= 0 && age <= life) visit(s, k, u, age, life, split);
+		}
+	}
+}
+
+const turn = [0, 0, 0];
+
+/** Particle (s, k) at `frame` into `out`; false when it is gone (under a volume's floor). */
+function particleAt(em, s, k, u, age, life, split, frame, fps, out) {
+	const { effect, look, seed } = em;
+	const r = (c) => rnd(seed, s, k, c);
+	const pose = em.pose(s);
+	const a = age / life;
+	let ox = (r(3) - 0.5) * effect.area.x, oy = (look.top ? effect.area.y : r(4) * effect.area.y) + look.lift * effect.size, oz = (r(5) - 0.5) * effect.area.z;
+	if (!look.volume) [ox, oy, oz] = rotate(pose.q, ox, oy, oz, turn);
+	// Born u frames before frame s (age counts from there), so on the line the
+	// emitter swept from s - 1 to s: a fast hand leaves a stream, not beads.
+	const before = em.pose(s - 1).p;
+	out.s = s; out.k = k; out.u = u;
+	out.bx = pose.p[0] + (before[0] - pose.p[0]) * u + ox; out.by = pose.p[1] + (before[1] - pose.p[1]) * u + oy; out.bz = pose.p[2] + (before[2] - pose.p[2]) * u + oz;
+	// A cone of half-angle spread x 90 deg about the emitter's local +Y.
+	const cosT = 1 - r(6) * (1 - Math.cos((effect.spread * Math.PI) / 2)), sinT = Math.sqrt(Math.max(0, 1 - cosT * cosT)), phi = 2 * Math.PI * r(7);
+	let [dx, dy, dz] = [sinT * Math.cos(phi), cosT, sinT * Math.sin(phi)];
+	if (!look.volume) [dx, dy, dz] = rotate(pose.q, dx, dy, dz, turn);
+	const speed = effect.speed * (0.75 + 0.5 * r(8)), drag = look.drag;
+	// Velocity relaxes to the terminal one: the wind plus gravity / drag.
+	const tx = effect.wind.x, ty = effect.wind.y - effect.gravity / drag, tz = effect.wind.z;
+	const v0x = dx * speed + (look.volume ? tx : 0), v0y = (dy - look.droop) * speed + (look.volume ? ty : 0), v0z = dz * speed + (look.volume ? tz : 0);
+	const e = Math.exp(-drag * age), f1 = (1 - e) / drag;
+	let x = out.bx + tx * age + (v0x - tx) * f1, y = out.by + ty * age + (v0y - ty) * f1, z = out.bz + tz * age + (v0z - tz) * f1;
+	// Drift: a sway frozen at birth (so the column snakes as it rises), a slow
+	// lean of the whole plume, a per-particle curl and a little jitter.
+	const tau = (s + u) / fps, time = frame / fps, rise = age * Math.sqrt(age);
+	x += look.sway * (rise * Math.sin(1.7 * tau + em.phase[0]) + 0.6 * age * Math.sin(0.45 * time + em.phase[2]));
+	z += look.sway * (rise * Math.sin(1.3 * tau + em.phase[1]) + 0.6 * age * Math.cos(0.37 * time + em.phase[3]));
+	const curl = look.curlRate * age + 2 * Math.PI * r(9);
+	x += look.curl * age * Math.cos(curl) + look.jitter * age * (2 * r(10) - 1);
+	y += look.jitter * 0.5 * age * (2 * r(11) - 1);
+	z += look.curl * age * Math.sin(curl) + look.jitter * age * (2 * r(12) - 1);
+	// Nothing falls through the deck, and a volume's drops end at its floor.
+	if (y < 0 || (look.volume && y < pose.p[1])) return false;
+	let size = effect.size * (1 + look.sizeVar * (2 * r(13) - 1)) * (1 + (effect.grow - 1) * a ** look.growPow);
+	let alpha = (effect.opacity / split) * (look.fadeIn > 0 ? smooth(a / look.fadeIn) : 1) * Math.max(0, 1 - a) ** look.fadeOut;
+	if (look.twinkle) alpha *= 1 - look.twinkle * (0.5 + 0.5 * Math.sin(3 * age + 2 * Math.PI * r(17)));
+	// Fire: a yellow core that reddens and dims as it rises; sparks cool too.
+	let bright = 1, g = 1, b = 1, hot = 0;
+	if (look.tint === "fire") [bright, g, b, hot] = [1.2 * (1 - 0.35 * a), 1 - 0.3 * a, 1 - 0.85 * a, (1 - a) ** 3];
+	if (look.tint === "spark") [bright, g, b, hot] = [1.6 * (1 - 0.4 * a), 1 - 0.3 * a, 1 - 0.6 * a, 0.5 * (1 - a) ** 2];
+	if (look.flicker) {
+		const flick = rnd(seed, s, k, 1000 + Math.floor(frame));
+		bright *= 1 + look.flicker * (2 * flick - 1);
+		size *= 1 + 0.3 * look.flicker * (flick - 0.5);
+	}
+	const vx = tx + (v0x - tx) * e, vy = ty + (v0y - ty) * e, vz = tz + (v0z - tz) * e;
+	Object.assign(out, { x, y, z, size, alpha, angle: 2 * Math.PI * r(14) + look.spin * (2 * r(15) - 1) * age, variant: look.clean ? 0 : 1 + Math.floor(r(16) * 3),
+		r: em.rgb[0] * bright, g: (em.rgb[1] * g + 0.45 * hot) * bright, b: (em.rgb[2] * b + 0.12 * hot) * bright, additive: effect.additive, sx: vx * look.streak, sy: vy * look.streak, sz: vz * look.streak });
+	return true;
+}
+
+const catmull = (p0, p1, p2, p3, t, out) => {
+	for (let i = 0; i < 3; i += 1) out[i] = 0.5 * (2 * p1[i] + (p2[i] - p0[i]) * t + (2 * p0[i] - 5 * p1[i] + 4 * p2[i] - p3[i]) * t * t + (3 * p1[i] - p0[i] - 3 * p2[i] + p3[i]) * t * t * t);
+	return out;
+};
+const dist = (a, b) => Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
+
+/** The trail ribbon at `frame` as quads: visit({ a0, b0, a1, b1, alpha0, alpha1 }) older end first. */
+function forEachSegment(em, frame, fps, cap, visit) {
+	const { effect } = em;
+	const half = effect.width / 2, span = effect.life * fps, last = Math.floor(frame), first = Math.floor(frame - span);
+	const edges = new Map();
+	const edge = (s) => {
+		const at = Math.min(last, s);
+		if (!edges.has(at)) {
+			const { p, q } = em.pose(at), off = rotate(q, 0, half, 0, [0, 0, 0]);
+			edges.set(at, { a: [p[0] - off[0], p[1] - off[1], p[2] - off[2]], b: [p[0] + off[0], p[1] + off[1], p[2] + off[2]] });
+		}
+		return edges.get(at);
+	};
+	const alphaAt = (s, t, level) => effect.opacity * level * Math.max(0, 1 - (frame - s - t) / span) ** 1.5;
+	let drawn = 0, clamped = 0;
+	for (let s = first; s < last; s += 1) {
+		const level = Math.min(em.level(s), em.level(s + 1));
+		const e0 = edge(s), e1 = edge(s + 1);
+		const move = Math.max(dist(e0.a, e1.a), dist(e0.b, e1.b));
+		if (!(level > 0) || move < TRAIL_STILL_M) continue;
+		const fast = Math.min(1, (move * fps) / TRAIL_FULL_SPEED), before = edge(s - 1), after = edge(s + 2);
+		for (let j = 0; j < TRAIL_SUBSTEPS; j += 1) {
+			const t0 = j / TRAIL_SUBSTEPS, t1 = (j + 1) / TRAIL_SUBSTEPS;
+			const alpha0 = alphaAt(s, t0, level) * fast, alpha1 = alphaAt(s, t1, level) * fast;
+			if (alpha0 <= 0 && alpha1 <= 0) continue;
+			if (drawn >= cap) { clamped += 1; continue; }
+			drawn += 1;
+			visit({ a0: catmull(before.a, e0.a, e1.a, after.a, t0, [0, 0, 0]), b0: catmull(before.b, e0.b, e1.b, after.b, t0, [0, 0, 0]),
+				a1: catmull(before.a, e0.a, e1.a, after.a, t1, [0, 0, 0]), b1: catmull(before.b, e0.b, e1.b, after.b, t1, [0, 0, 0]), alpha0, alpha1 });
+		}
+	}
+	return clamped;
+}
+
+/**
+ * Every effect record's particles and ribbons at `frame`.
+ *
+ * `scene`: { lookup: Map of AUTHORED records by id, take: { fps, objectTracks },
+ * live?: (id, out) => world matrix of an attached record, hidden?: Set of ids
+ * that emit nothing }. `particle(p, em)` / `segment(sg, em)` receive what is
+ * drawn (p is reused between calls); `only` limits the work to one emitter
+ * while keeping the scene-wide cap the renderer applies.
+ *
+ * @returns {Map<string, { alive: number, clamped: number, emitter: number[], min: number[], max: number[] }>}
+ */
+export function evaluateEffects(records, scene, frame, { only = null, particle = null, segment = null } = {}) {
+	const fps = scene.take?.fps > 0 ? scene.take.fps : 24;
+	const emitters = records.filter((record) => record?.renderer === EFFECT_KIND).map((record) => emitterOf(record, scene));
+	const counts = emitters.map((em) => {
+		let count = 0;
+		if (!em.trail) forEachLive(em, frame, fps, () => { count += 1; });
+		return count;
+	});
+	const total = counts.reduce((sum, count) => sum + count, 0);
+	const trailCap = Math.floor(EFFECT_SEGMENT_CAP / Math.max(1, emitters.filter((em) => em.trail).length));
+	const stats = new Map();
+	const scratch = {};
+	emitters.forEach((em, index) => {
+		const st = { alive: 0, clamped: 0, emitter: em.pose(Math.floor(frame)).p, min: [Infinity, Infinity, Infinity], max: [-Infinity, -Infinity, -Infinity] };
+		stats.set(em.id, st);
+		if (only && em.id !== only) return;
+		const grow = (x, y, z, pad) => {
+			const { min, max } = st;
+			min[0] = Math.min(min[0], x - pad); min[1] = Math.min(min[1], y - pad); min[2] = Math.min(min[2], z - pad);
+			max[0] = Math.max(max[0], x + pad); max[1] = Math.max(max[1], y + pad); max[2] = Math.max(max[2], z + pad);
+		};
+		if (em.trail) {
+			st.clamped = forEachSegment(em, frame, fps, trailCap, (sg) => {
+				st.alive += 1;
+				for (const point of [sg.a0, sg.b0, sg.a1, sg.b1]) grow(point[0], point[1], point[2], 0);
+				segment?.(sg, em);
+			});
+			return;
+		}
+		const n = counts[index], keep = total > EFFECT_PARTICLE_CAP ? Math.floor((n * EFFECT_PARTICLE_CAP) / total) : n;
+		st.clamped = n - keep;
+		let order = 0;
+		forEachLive(em, frame, fps, (s, k, u, age, life, split) => {
+			const i = order++;
+			if (keep < n && Math.floor(((i + 1) * keep) / n) === Math.floor((i * keep) / n)) return;
+			if (!particleAt(em, s, k, u, age, life, split, frame, fps, scratch) || scratch.alpha < 5e-4) return;
+			st.alive += 1;
+			grow(scratch.x, scratch.y, scratch.z, scratch.size / 2);
+			particle?.(scratch, em);
+		});
+	});
+	return stats;
+}