@aura3d/engine 4.6.1 → 4.7.0

package/dist/engine/agent-api/vfx/atmosphere-api.js.map

@@ -1 +1 @@
-{"version":3,"file":"atmosphere-api.js","sourceRoot":"","sources":["../../../../../../packages/engine/src/agent-api/vfx/atmosphere-api.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"atmosphere-api.js","sourceRoot":"","sources":["../../../../../../packages/engine/src/agent-api/vfx/atmosphere-api.ts"],"names":[],"mappings":"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"}

package/dist/engine/agent-api/vfx/effects-api.d.ts

@@ -1,10 +1,13 @@
 import type { AuraApp, AuraCreateAppOptions } from "../index.js";
+import type { AuraVfxGenreVariant } from "../../contracts/effects.js";
 import type { QrFlags } from "../../../rendering/contracts/index.js";
 import { ProductionEffectSystem } from "../../production-runtime/effects/ProductionEffectSystem.js";
 export interface AuraEffectsExtensionContext {
     readonly flags: QrFlags;
     readonly options: AuraCreateAppOptions;
 }
+/** GU47 E-F: the genre variant names, in table order. */
+export declare const AURA_VFX_GENRE_VARIANTS: readonly AuraVfxGenreVariant[];
 /** Real `AuraAppEffects` — pooled effect instances over the emitter system. */
 export declare function createAppEffects(app: AuraApp, system: ProductionEffectSystem): import("../../contracts/effects.js").AuraAppEffects;
 interface PendingGameEffects {

package/dist/engine/agent-api/vfx/effects-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"effects-api.d.ts","sourceRoot":"","sources":["../../../../../../packages/engine/src/agent-api/vfx/effects-api.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAuB,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAEnF,OAAO,KAAK,EAAE,OAAO,EAAmB,MAAM,6BAA6B,CAAC;AAE5E,OAAO,EAAE,sBAAsB,EAAgB,MAAM,yDAAyD,CAAC;AAS/G,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;CACxC;AAgDD,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,sBAAsB,GAAG,OAAO,yBAAyB,EAAE,cAAc,CAyO/H;AASD,UAAU,kBAAkB;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;CACvC;AAID,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,kBAAkB,GAAG,IAAI,CAGxE;AAsBD,wBAAgB,kBAAkB,IAAI,MAAM,GAAG,IAAI,CAElD;AAED,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,kBAAkB,GAAG,IAAI,CAE1E;AAED,wEAAwE;AACxE,wBAAgB,qBAAqB,IAAI,IAAI,CAI5C;AAOD;;;;;gCAKgC;AAChC,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,2BAA2B,GAAG,OAAO,yBAAyB,EAAE,cAAc,CAcvI;AAED,6FAA6F;AAC7F,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAEpD;AAKD,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,GAAG,sBAAsB,CAO9G;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,sBAAsB,GAAG,IAAI,CAE1E"}
+{"version":3,"file":"effects-api.d.ts","sourceRoot":"","sources":["../../../../../../packages/engine/src/agent-api/vfx/effects-api.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAuB,oBAAoB,EAAE,MAAM,UAAU,CAAC;AACnF,OAAO,KAAK,EAAiH,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAClL,OAAO,KAAK,EAAE,OAAO,EAAmB,MAAM,6BAA6B,CAAC;AAE5E,OAAO,EAAE,sBAAsB,EAAgB,MAAM,yDAAyD,CAAC;AAU/G,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;CACxC;AA2DD,yDAAyD;AACzD,eAAO,MAAM,uBAAuB,EAAwC,SAAS,mBAAmB,EAAE,CAAC;AA+F3G,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,sBAAsB,GAAG,OAAO,yBAAyB,EAAE,cAAc,CA0Z/H;AASD,UAAU,kBAAkB;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;CACvC;AAID,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,kBAAkB,GAAG,IAAI,CAGxE;AAsBD,wBAAgB,kBAAkB,IAAI,MAAM,GAAG,IAAI,CAElD;AAED,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,kBAAkB,GAAG,IAAI,CAE1E;AAED,wEAAwE;AACxE,wBAAgB,qBAAqB,IAAI,IAAI,CAI5C;AAOD;;;;;gCAKgC;AAChC,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,2BAA2B,GAAG,OAAO,yBAAyB,EAAE,cAAc,CAcvI;AAED,6FAA6F;AAC7F,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAEpD;AAKD,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,GAAG,sBAAsB,CAO9G;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,sBAAsB,GAAG,IAAI,CAE1E"}

package/dist/engine/agent-api/vfx/effects-api.js

@@ -22,6 +22,33 @@ const BURST_PRESETS = {
     "impact-decal": { speed: [0, 0], life: [2, 3], gravity: 0, color: [0.15, 0.12, 0.1], size: [0.2, 0.35], spread: 0.05, additive: false },
     "aura-burst": { speed: [2, 4], life: [0.5, 1.1], gravity: 0, color: [1.5, 2.5, 6], size: [0.08, 0.2], spread: 1, additive: true, light: { intensity: 10, range: 8, duration: 0.6 } }
 };
+/**
+ * GU47 E-F genre-coloured variants of `spark`, `dust` and `pickup`: the base row's motion, life and size with
+ * a genre palette, so two games firing "the same" hit or pickup stop looking identical. Additive rows keep an
+ * HDR colour of the base's energy; dust rows stay LDR.
+ */
+const GENRE_VARIANT_COLORS = {
+    "spark-fire": ["spark", [4.5, 1.4, 0.35]],
+    "spark-electric": ["spark", [1.2, 2.8, 4.6]],
+    "spark-gold": ["spark", [4.2, 3, 0.9]],
+    "spark-magic": ["spark", [3.4, 1, 4.2]],
+    "spark-ice": ["spark", [2.2, 3.4, 4.4]],
+    "dust-sand": ["dust", [0.76, 0.62, 0.42]],
+    "dust-turf": ["dust", [0.36, 0.42, 0.24]],
+    "dust-snow": ["dust", [0.9, 0.93, 0.98]],
+    "dust-ash": ["dust", [0.28, 0.27, 0.27]],
+    "dust-clay": ["dust", [0.66, 0.38, 0.26]],
+    "pickup-gold": ["pickup", [4.4, 3.2, 0.8]],
+    "pickup-gem": ["pickup", [0.9, 2.8, 4.6]],
+    "pickup-power": ["pickup", [3.8, 1, 4]],
+    "pickup-star": ["pickup", [4.4, 4, 2.8]],
+    "pickup-heart": ["pickup", [4.4, 1, 1.6]]
+};
+/** GU47 E-F: the genre variant names, in table order. */
+export const AURA_VFX_GENRE_VARIANTS = Object.keys(GENRE_VARIANT_COLORS);
+for (const [name, [base, color]] of Object.entries(GENRE_VARIANT_COLORS)) {
+    BURST_PRESETS[name] = { ...BURST_PRESETS[base], color };
+}
 /** super-flash C-05 overlay flash: LDR warm white, 0.3 peak, 180 ms decay. */
 const SUPER_FLASH = { color: [1, 0.9, 0.72], peak: 0.3, ms: 180 };
 /** HDR colour → chromaticity (max component 1); LDR colours pass unchanged. */
@@ -29,6 +56,58 @@ function lightChromaticity(c) {
     const m = Math.max(1, c[0] ?? 0, c[1] ?? 0, c[2] ?? 0);
     return [(c[0] ?? 0) / m, (c[1] ?? 0) / m, (c[2] ?? 0) / m];
 }
+function builtinRecipe(kind) {
+    const preset = BURST_PRESETS[kind] ?? BURST_PRESETS.spark;
+    return { speed: preset.speed, life: preset.life, gravity: preset.gravity, color: preset.color, size: preset.size, spread: preset.spread, additive: preset.additive, ...(preset.sprite !== undefined ? { sprite: preset.sprite } : {}) };
+}
+function numberOr(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+function rangeOr(value, fallback) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return [value, value];
+    if (Array.isArray(value) && typeof value[0] === "number")
+        return [value[0], typeof value[1] === "number" ? value[1] : value[0]];
+    return fallback;
+}
+const LAYER_BLENDS = new Set(["alpha", "premultiplied", "additive", "multiply"]);
+/**
+ * GU47 E-F: a registered preset's emitter layer over its base row. The base is the built-in (or genre
+ * variant) named by `layer.preset`, else the built-in of the preset's own name, else `spark`. Recognised layer
+ * fields: count, speed, life | lifetime, gravity (number or vec3: y is used), color (hex or linear rgb),
+ * intensity (multiplies color), size, spread, additive | blend | materialMode, sprite, maxScreen, drag, direction.
+ */
+function recipeFromLayer(kind, layer) {
+    const baseKind = typeof layer.preset === "string" && BURST_PRESETS[layer.preset] ? layer.preset : kind;
+    const base = builtinRecipe(baseKind);
+    const gravity = Array.isArray(layer.gravity) ? numberOr(layer.gravity[1], base.gravity) : numberOr(layer.gravity, base.gravity);
+    const rawColor = typeof layer.color === "string" || Array.isArray(layer.color) ? toVec3(layer.color, base.color) : base.color;
+    const intensity = numberOr(layer.intensity, 1);
+    const blend = typeof layer.blend === "string" && LAYER_BLENDS.has(layer.blend) ? layer.blend : undefined;
+    const additive = typeof layer.additive === "boolean"
+        ? layer.additive
+        : blend !== undefined
+            ? blend === "additive"
+            : typeof layer.materialMode === "string"
+                ? ["additive-glow", "spark", "star"].includes(layer.materialMode)
+                : base.additive;
+    const direction = Array.isArray(layer.direction) && layer.direction.length >= 3 ? [Number(layer.direction[0]), Number(layer.direction[1]), Number(layer.direction[2])] : undefined;
+    return {
+        speed: rangeOr(layer.speed, base.speed),
+        life: rangeOr(layer.life ?? layer.lifetime, base.life),
+        gravity,
+        color: [rawColor[0] * intensity, rawColor[1] * intensity, rawColor[2] * intensity],
+        size: rangeOr(layer.size, base.size),
+        spread: numberOr(layer.spread, base.spread),
+        additive,
+        ...(blend !== undefined ? { blend } : {}),
+        ...(typeof layer.count === "number" && layer.count > 0 ? { count: Math.round(layer.count) } : {}),
+        ...(layer.sprite !== undefined ? { sprite: layer.sprite } : base.sprite !== undefined ? { sprite: base.sprite } : {}),
+        ...(typeof layer.maxScreen === "number" && layer.maxScreen > 0 ? { maxScreen: layer.maxScreen } : {}),
+        ...(typeof layer.drag === "number" ? { drag: layer.drag } : {}),
+        ...(direction ? { direction } : {})
+    };
+}
 let nextInstanceId = 0;
 /** Concurrent transient-instance pool cap (E20's `poolSize ?? 96` default). */
 const EFFECT_INSTANCE_CAP = 96;
@@ -124,25 +203,42 @@ export function createAppEffects(app, system) {
             });
         }
     };
-    const spawnEmitter = (kind, position, options) => {
+    /** GU47 E-F: presets registered by the app; `burst`/`spawn` resolve these before the built-in table. */
+    const registered = new Map();
+    let unsupportedLayerNoted = false;
+    const pendingLayers = [];
+    let layerClock = 0;
+    let offLayerFrame = null;
+    const scheduleLayer = (delay, fire) => {
+        const entry = { due: layerClock + delay, fire, cancelled: false, done: false };
+        pendingLayers.push(entry);
+        if (!offLayerFrame && typeof app.onFrame === "function") {
+            offLayerFrame = app.onFrame((frame) => {
+                layerClock += Math.max(0, frame.dt);
+                for (let i = 0; i < pendingLayers.length;) {
+                    const pending = pendingLayers[i];
+                    if (pending.cancelled || pending.due <= layerClock) {
+                        pendingLayers.splice(i, 1);
+                        pending.done = true;
+                        if (!pending.cancelled)
+                            pending.fire();
+                    }
+                    else
+                        i += 1;
+                }
+            });
+        }
+        return entry;
+    };
+    /** Create one pooled emitter instance; returns its id (also the system emitter id). */
+    const spawnInstance = (recipe, kind, position, options) => {
         const id = `fx-${nextInstanceId++}`;
-        const preset = BURST_PRESETS[kind] ?? BURST_PRESETS.spark;
-        if (options.camera !== false)
-            applyPresetLayers(kind);
-        const color = toVec3(options.color, preset.color);
+        const color = toVec3(options.color, recipe.color);
         const sizeScale = options.scale !== undefined && Number.isFinite(options.scale) && options.scale > 0 ? options.scale : 1;
-        // P2-T7 §6.2.12 light layer — tier-capped transient pool flash.
-        if (preset.light) {
-            system.flashLight({
-                position: [position[0] ?? 0, position[1] ?? 0, position[2] ?? 0],
-                // The particle colour is HDR (up to 9); the light takes chromaticity
-                // only so `intensity` alone sets the flash energy (9 × 20 = 180 blew
-                // every lit surface in range to white).
-                color: lightChromaticity(color),
-                intensity: preset.light.intensity * (options.intensity ?? 1),
-                range: preset.light.range,
-                duration: preset.light.duration
-            });
+        // GU47 E-F: spent one-shots (retired by the system) leave the pool before the cap check.
+        for (const [instanceId, entry] of instances) {
+            if (entry.alive && entry.emitterId && !system.instanceAlive(entry.emitterId))
+                instances.delete(instanceId);
         }
         // Pool cap: recycle the oldest live instance when the pool is full.
         if (instances.size >= EFFECT_INSTANCE_CAP) {
@@ -153,43 +249,205 @@ export function createAppEffects(app, system) {
                 system.removeInstance(entry.emitterId);
             instances.delete(oldest);
         }
+        const count = options.count ?? recipe.count;
+        const sprite = (options.sprite ?? recipe.sprite);
         const emitterId = system.addInstance(id, {
             kind: "effect",
             effect: "particles",
             id,
             position,
-            particleCount: options.continuous ? Math.max(64, options.count ?? 64) : Math.max(1, options.count ?? 24),
-            ...(options.continuous ? {} : { burst: Math.max(1, options.count ?? 24) }),
-            materialMode: preset.additive ? "additive-glow" : "soft-alpha",
-            speed: options.speed ?? preset.speed,
-            gravity: preset.gravity,
+            particleCount: options.continuous ? Math.max(64, count ?? 64) : Math.max(1, count ?? 24),
+            ...(options.continuous ? {} : { burst: Math.max(1, count ?? 24) }),
+            materialMode: recipe.additive ? "additive-glow" : "soft-alpha",
+            ...(recipe.blend !== undefined ? { blend: recipe.blend } : {}),
+            speed: options.speed ?? recipe.speed,
+            gravity: recipe.gravity,
             // The preset's own life, size and spread: without them every kind inherited the
             // emitter defaults (1.2 to 2.4 s lifetime, 5 to 14 cm glow discs) and read as lingering bubbles.
-            lifetime: preset.life,
-            size: [preset.size[0] * sizeScale, preset.size[1] * sizeScale],
-            spread: preset.spread,
+            lifetime: recipe.life,
+            size: [recipe.size[0] * sizeScale, recipe.size[1] * sizeScale],
+            spread: recipe.spread,
             // a preset's soft discs never grow past this share of the screen height: sparks and dust stay specks, not bubbles
-            maxScreen: PRESET_MAX_SCREEN[kind] ?? 0.05,
-            emissionRate: options.continuous ? (options.count ?? 24) * 2 : 0,
+            maxScreen: recipe.maxScreen ?? PRESET_MAX_SCREEN[kind] ?? 0.05,
+            emissionRate: options.continuous ? (count ?? 24) * 2 : 0,
             color,
-            seed: options.seed
+            seed: options.seed,
+            ...(recipe.drag !== undefined ? { drag: recipe.drag } : {}),
+            ...(recipe.direction !== undefined ? { direction: recipe.direction } : {}),
+            // GU47 E-F: atlas sprite (call site, else preset) and node following.
+            ...(sprite !== undefined ? { sprite } : {}),
+            ...(options.attachTo !== undefined ? { attachTo: options.attachTo } : {})
         });
         instances.set(id, { id, emitterId, alive: true });
+        return id;
+    };
+    const stopInstance = (id, immediate) => {
+        const entry = instances.get(id);
+        if (!entry)
+            return;
+        entry.alive = false;
+        if (entry.emitterId)
+            system.removeInstance(entry.emitterId);
+        if (!immediate)
+            instances.delete(id);
+    };
+    /** Built-in preset path (unchanged behaviour): camera layer, light layer, one pooled emitter. */
+    const spawnBuiltin = (kind, position, options) => {
+        const preset = BURST_PRESETS[kind] ?? BURST_PRESETS.spark;
+        if (options.camera !== false)
+            applyPresetLayers(kind);
+        const color = toVec3(options.color, preset.color);
+        // P2-T7 §6.2.12 light layer — tier-capped transient pool flash.
+        if (preset.light) {
+            system.flashLight({
+                position: [position[0] ?? 0, position[1] ?? 0, position[2] ?? 0],
+                // The particle colour is HDR (up to 9); the light takes chromaticity
+                // only so `intensity` alone sets the flash energy (9 × 20 = 180 blew
+                // every lit surface in range to white).
+                color: lightChromaticity(color),
+                intensity: preset.light.intensity * (options.intensity ?? 1),
+                range: preset.light.range,
+                duration: preset.light.duration
+            });
+        }
+        const id = spawnInstance(builtinRecipe(kind), kind, position, options);
         return {
             id,
             get alive() {
-                return instances.get(id)?.alive ?? false;
+                // GU47 E-F: a one-shot is alive until its particles are gone (the system retires spent emitters).
+                return (instances.get(id)?.alive ?? false) && system.instanceAlive(id);
+            },
+            stop: (o) => stopInstance(id, o?.immediate),
+            setPosition: (p) => system.setInstanceOrigin(id, p)
+        };
+    };
+    /**
+     * GU47 E-F registered preset path: every layer of the spec fires at `position` (after `layer.at` seconds):
+     * emitter layers spawn pooled emitters (one-shot bursts for named presets, continuous for authored spec
+     * objects), light layers flash the transient pool, camera layers shake/punch, decal layers place a decal.
+     */
+    const spawnSpec = (spec, position, options) => {
+        const groupId = `fx-${nextInstanceId++}`;
+        const members = [];
+        const timers = [];
+        let stopped = false;
+        let firstColor;
+        const fireLayer = (layer) => {
+            if (stopped)
+                return;
+            switch (layer.type) {
+                case "emitter": {
+                    const recipe = recipeFromLayer(spec.name, layer);
+                    firstColor ??= toVec3(options.color, recipe.color);
+                    members.push(spawnInstance(recipe, spec.name, position, options));
+                    break;
+                }
+                case "light": {
+                    const color = typeof layer.color === "string" || Array.isArray(layer.color) ? toVec3(layer.color, [1, 1, 1]) : firstColor ?? [1, 1, 1];
+                    system.flashLight({
+                        position: [position[0] ?? 0, position[1] ?? 0, position[2] ?? 0],
+                        color: lightChromaticity(color),
+                        intensity: numberOr(layer.intensity, 8) * (options.intensity ?? 1),
+                        range: numberOr(layer.range, 6),
+                        duration: numberOr(layer.duration, 0.25)
+                    });
+                    break;
+                }
+                case "camera": {
+                    if (options.camera === false)
+                        break;
+                    const cam = app.camera;
+                    if (!cam?.shake) {
+                        if (!cameraWarned) {
+                            cameraWarned = true;
+                            system.diagnostics.note("VFX_LAYER_UNAVAILABLE", spec.name, "camera layers skipped — no C-22 camera extension");
+                        }
+                        break;
+                    }
+                    const configure = layer.configure;
+                    if (configure)
+                        cam.shake.configure(configure);
+                    if (typeof layer.shake === "number")
+                        cam.shake.add(layer.shake);
+                    if (layer.punch && typeof layer.punch === "object")
+                        cam.punch?.trigger(layer.punch);
+                    break;
+                }
+                case "decal": {
+                    const handle = spawnDecal({ position, normal: options.normal ?? [0, 1, 0] }, {
+                        ...(typeof layer.size === "number" ? { size: layer.size } : {}),
+                        ...(typeof layer.lifetime === "number" ? { lifetime: layer.lifetime } : {}),
+                        ...(typeof layer.opacity === "number" ? { opacity: layer.opacity } : {}),
+                        ...(layer.color !== undefined ? { color: layer.color } : {})
+                    });
+                    members.push(handle.id);
+                    break;
+                }
+                default:
+                    if (!unsupportedLayerNoted) {
+                        unsupportedLayerNoted = true;
+                        system.diagnostics.note("VFX_PRESET_LAYER_UNSUPPORTED", spec.name, `preset layer type "${layer.type}" is not spawned by burst/spawn (emitter, light, camera and decal are)`);
+                    }
+            }
+        };
+        // A spec without layers is its named built-in (or spark) as one emitter, as before GU47.
+        const layers = spec.layers.length > 0 ? spec.layers : [{ type: "emitter" }];
+        for (const layer of layers) {
+            const delay = typeof layer.at === "number" && layer.at > 0 ? layer.at : 0;
+            if (delay > 0)
+                timers.push(scheduleLayer(delay, () => fireLayer(layer)));
+            else
+                fireLayer(layer);
+        }
+        return {
+            id: groupId,
+            get alive() {
+                return !stopped && (members.some((member) => system.instanceAlive(member) && (instances.get(member)?.alive ?? true)) || timers.some((timer) => !timer.cancelled && !timer.done));
             },
             stop: (o) => {
-                const entry = instances.get(id);
-                if (!entry)
-                    return;
-                entry.alive = false;
-                if (entry.emitterId)
-                    system.removeInstance(entry.emitterId);
-                if (!o?.immediate)
-                    instances.delete(id);
+                stopped = true;
+                for (const timer of timers)
+                    timer.cancelled = true;
+                for (const member of members) {
+                    if (instances.has(member))
+                        stopInstance(member, o?.immediate);
+                    else
+                        system.removeInstance(member);
+                }
             },
+            setPosition: (p) => {
+                for (const member of members)
+                    system.setInstanceOrigin(member, p);
+            }
+        };
+    };
+    const spawnEmitter = (kind, position, options) => {
+        const spec = registered.get(kind);
+        return spec ? spawnSpec(spec, position, options) : spawnBuiltin(kind, position, options);
+    };
+    // P6-T1 — runtime decal routed through the merged DecalBatch (§6.9) under A3D_QR_VFX_DECALS.
+    const spawnDecal = (at, options) => {
+        const id = `fx-${nextInstanceId++}`;
+        const size = Math.max(0.01, options?.size ?? 0.5);
+        system.addInstance(id, {
+            kind: "effect",
+            effect: "decal",
+            id,
+            position: at.position,
+            decal: {
+                size: [size, size],
+                normal: at.normal,
+                baseOpacity: options?.opacity ?? 0.85,
+                ...(options?.color !== undefined ? { color: options.color } : {}),
+                ...(options?.lifetime !== undefined ? { lifetime: options.lifetime } : {})
+            }
+        });
+        return {
+            id,
+            get alive() {
+                return true;
+            },
+            stop: () => system.removeInstance(id),
             setPosition: (p) => system.setInstanceOrigin(id, p)
         };
     };
@@ -204,51 +462,52 @@ export function createAppEffects(app, system) {
             return spawnEmitter(kind, position, options ?? {});
         },
         spawn(effect, at, options) {
-            const kind = typeof effect === "string" ? effect : effect.name;
+            // GU47 E-F: `{ node, socket }` (or the spec's own attachTo) makes the effect follow that node; the old
+            // code spawned it at the world origin.
+            const onNode = !Array.isArray(at) && typeof at.node === "string";
             const position = Array.isArray(at) ? at : [0, 0, 0];
-            // A named preset is a one-shot impact: it bursts and dies with its particles. Only an authored
-            // AuraVfxEffectSpec object is a looping effect that the caller stops.
-            return spawnEmitter(kind, position, { ...(options ?? {}), continuous: typeof effect !== "string" });
-        },
-        trail(_target, options) {
-            void options;
-            system.diagnostics.note("VFX_TRAIL_PENDING", "", "effects.trail lands with P2-T5 ribbons");
-            return {
-                id: `fx-${nextInstanceId++}`,
-                get alive() {
-                    return false;
-                },
-                stop: () => { },
-                setPosition: () => { }
-            };
+            const attachTo = onNode ? at : typeof effect === "string" ? undefined : effect.attachTo;
+            const spawnOptions = { ...(options ?? {}), continuous: typeof effect !== "string", ...(attachTo !== undefined ? { attachTo } : {}) };
+            // A named preset (registered first, then built-in) is a one-shot impact: it bursts and dies with its
+            // particles. Only an authored AuraVfxEffectSpec object is a looping effect that the caller stops.
+            return typeof effect === "string" ? spawnEmitter(effect, position, spawnOptions) : spawnSpec(effect, position, spawnOptions);
         },
-        decal(at, options) {
-            // P6-T1 — runtime decal routed through the merged DecalBatch (§6.9)
-            // under A3D_QR_VFX_DECALS.
+        trail(target, options) {
+            // GU47 E-F: a real ribbon on the RibbonBatch that follows `target` (node id, handle or { node, socket }).
+            // Runtime effects "off" drops trails like every other runtime-spawned effect.
             const id = `fx-${nextInstanceId++}`;
-            const size = Math.max(0.01, options?.size ?? 0.5);
-            system.addInstance(id, {
-                kind: "effect",
-                effect: "decal",
-                id,
-                position: at.position,
-                decal: {
-                    size: [size, size],
-                    normal: at.normal,
-                    baseOpacity: options?.opacity ?? 0.85,
-                    ...(options?.color !== undefined ? { color: options.color } : {}),
-                    ...(options?.lifetime !== undefined ? { lifetime: options.lifetime } : {})
-                }
-            });
+            const live = system.runtimeEffects !== "off";
+            if (live) {
+                system.addTrail(id, target, {
+                    width: options.width,
+                    life: options.life,
+                    color: options.color ?? "#ffffff",
+                    ...(options.widthOverSpeed !== undefined ? { widthOverSpeed: options.widthOverSpeed } : {}),
+                    ...(options.colorTail !== undefined ? { colorTail: options.colorTail } : {})
+                });
+            }
             return {
                 id,
                 get alive() {
-                    return true;
+                    return live && system.trailInfo(id) !== null;
                 },
-                stop: () => system.removeInstance(id),
-                setPosition: (p) => system.setInstanceOrigin(id, p)
+                get length() {
+                    return system.trailInfo(id)?.length ?? 0;
+                },
+                get pointCount() {
+                    return system.trailInfo(id)?.pointCount ?? 0;
+                },
+                stop: (o) => system.stopTrail(id, o?.immediate === true),
+                setPosition: (p) => {
+                    system.trailPush(id, [p[0] ?? 0, p[1] ?? 0, p[2] ?? 0]);
+                },
+                clear: () => system.clearTrail(id),
+                translate: (dx, dy, dz) => system.translateTrail(id, [dx, dy, dz])
             };
         },
+        decal(at, options) {
+            return spawnDecal(at, options);
+        },
         get presets() {
             const out = {};
             for (const [k, v] of presets)
@@ -256,6 +515,8 @@ export function createAppEffects(app, system) {
             return out;
         },
         registerPreset(kind, spec) {
+            // GU47 E-F: registered names (new or overriding a built-in) resolve in burst/spawn before BURST_PRESETS.
+            registered.set(kind, spec);
             presets.set(kind, spec);
         },
         get liveCount() {
@@ -267,6 +528,8 @@ export function createAppEffects(app, system) {
                     system.removeInstance(entry.emitterId);
             }
             instances.clear();
+            // GU47 E-F: runtime trails and any other runtime emitter go too.
+            system.clearRuntimeParticles();
         }
     };
 }
@@ -369,6 +632,6 @@ function toVec3(c, fallback) {
     }
     if (Array.isArray(c) && c.length >= 3)
         return [Number(c[0]), Number(c[1]), Number(c[2])];
-    return fallback;
+    return [fallback[0], fallback[1], fallback[2]];
 }
 //# sourceMappingURL=effects-api.js.map