@aethervtt/shard-effects 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Dias
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,3 @@
-# Temporary Holding Version
+# @aethervtt/shard-effects
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Part of [Shard](https://github.com/aethervtt/shard), a WebGPU-first 2D/3D game engine in TypeScript. See the repository for documentation.

package/dist/document.d.ts

@@ -0,0 +1,57 @@
+import { type Infer } from '@aethervtt/shard-core';
+export declare function effectError(message: string, path?: string, code?: string): never;
+export declare const EffectTrack: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").InferFields<{
+    id: import("@aethervtt/shard-core").FieldType<string, "object">;
+    kind: import("@aethervtt/shard-core").FieldType<"animation" | "audio" | "marker" | "particles" | "property" | "visual", "u8">;
+    target: import("@aethervtt/shard-core").FieldType<string, "object">;
+    targetPath: import("@aethervtt/shard-core").FieldType<string, "object">;
+    endpoint: import("@aethervtt/shard-core").FieldType<string, "object">;
+    start: import("@aethervtt/shard-core").FieldType<number, "f64">;
+    duration: import("@aethervtt/shard-core").FieldType<number, "f64">;
+    component: import("@aethervtt/shard-core").FieldType<string, "object">;
+    field: import("@aethervtt/shard-core").FieldType<string, "object">;
+    from: import("@aethervtt/shard-core").FieldType<number[], "object">;
+    to: import("@aethervtt/shard-core").FieldType<number[], "object">;
+    easing: import("@aethervtt/shard-core").FieldType<"linear" | "smoothstep", "u8">;
+    parameter: import("@aethervtt/shard-core").FieldType<string, "object">;
+    animation: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"AnimationClip"> | null, "object">;
+    particles: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"ParticleEffect"> | null, "object">;
+    audio: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"audio/AudioEvent"> | null, "object">;
+    marker: import("@aethervtt/shard-core").FieldType<string, "object">;
+}>, "object">;
+export declare const EffectSequence: import("@aethervtt/shard-assets").DataType<{
+    readonly duration: import("@aethervtt/shard-core").FieldType<number, "f64">;
+    readonly parameters: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").InferFields<{
+        id: import("@aethervtt/shard-core").FieldType<string, "object">;
+        value: import("@aethervtt/shard-core").FieldType<number, "f64">;
+        min: import("@aethervtt/shard-core").FieldType<number, "f64">;
+        max: import("@aethervtt/shard-core").FieldType<number, "f64">;
+    }>[], "object">;
+    readonly targets: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").InferFields<{
+        id: import("@aethervtt/shard-core").FieldType<string, "object">;
+        prefab: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"Prefab"> | null, "object">;
+    }>[], "object">;
+    readonly tracks: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").InferFields<{
+        id: import("@aethervtt/shard-core").FieldType<string, "object">;
+        kind: import("@aethervtt/shard-core").FieldType<"animation" | "audio" | "marker" | "particles" | "property" | "visual", "u8">;
+        target: import("@aethervtt/shard-core").FieldType<string, "object">;
+        targetPath: import("@aethervtt/shard-core").FieldType<string, "object">;
+        endpoint: import("@aethervtt/shard-core").FieldType<string, "object">;
+        start: import("@aethervtt/shard-core").FieldType<number, "f64">;
+        duration: import("@aethervtt/shard-core").FieldType<number, "f64">;
+        component: import("@aethervtt/shard-core").FieldType<string, "object">;
+        field: import("@aethervtt/shard-core").FieldType<string, "object">;
+        from: import("@aethervtt/shard-core").FieldType<number[], "object">;
+        to: import("@aethervtt/shard-core").FieldType<number[], "object">;
+        easing: import("@aethervtt/shard-core").FieldType<"linear" | "smoothstep", "u8">;
+        parameter: import("@aethervtt/shard-core").FieldType<string, "object">;
+        animation: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"AnimationClip"> | null, "object">;
+        particles: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"ParticleEffect"> | null, "object">;
+        audio: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"audio/AudioEvent"> | null, "object">;
+        marker: import("@aethervtt/shard-core").FieldType<string, "object">;
+    }>[], "object">;
+}, "effects/EffectSequence">;
+export type EffectDocument = Infer<typeof EffectSequence>;
+export type EffectTrackValue = EffectDocument['tracks'][number];
+export declare function validateEffect(v: EffectDocument): void;
+export declare function parseEffect(value: unknown): EffectDocument;

package/dist/document.js

@@ -0,0 +1,122 @@
+import { defineDataType } from "@aethervtt/shard-assets";
+import { ShardError, t } from "@aethervtt/shard-core";
+function effectError(message, path = "", code = "invalid-sequence") {
+  throw new ShardError(`effects/${code}`, message, { path });
+}
+const EffectTrack = t.struct({
+  id: t.string({ required: true }),
+  kind: t.enum(["property", "animation", "particles", "audio", "marker", "visual"]),
+  target: t.string(),
+  targetPath: t.string(),
+  endpoint: t.string(),
+  start: t.f64({ min: 0 }),
+  duration: t.f64({ min: 0 }),
+  component: t.string(),
+  field: t.string(),
+  from: t.list(t.f64()),
+  to: t.list(t.f64()),
+  easing: t.enum(["linear", "smoothstep"]),
+  parameter: t.string(),
+  animation: t.handle("AnimationClip"),
+  particles: t.handle("ParticleEffect"),
+  audio: t.handle("audio/AudioEvent"),
+  marker: t.string()
+});
+const EffectSequence = defineDataType(
+  "effects/EffectSequence",
+  {
+    duration: t.f64({ required: true, min: 1e-6, max: 3600 }),
+    parameters: t.list(
+      t.struct({
+        id: t.string({ required: true }),
+        value: t.f64({ default: 1 }),
+        min: t.f64({ default: -1e6 }),
+        max: t.f64({ default: 1e6 })
+      })
+    ),
+    targets: t.list(t.struct({ id: t.string({ required: true }), prefab: t.handle("Prefab") })),
+    tracks: t.list(EffectTrack)
+  },
+  {
+    extension: "effect-sequence",
+    description: "Coordinated presentation with host-bound targets and owned prefab lifetimes.",
+    lazyDependencies: true,
+    validate: (v) => validateEffect(v)
+  }
+);
+function names(items, path, max) {
+  if (items.length > max) effectError(`At most ${max} entries`, path);
+  const ids = /* @__PURE__ */ new Set();
+  items.forEach((item, i) => {
+    if (!/^[A-Za-z][\w-]*$/.test(item.id) || ids.has(item.id))
+      effectError("IDs must be unique identifiers beginning with a letter", `${path}/${i}/id`);
+    ids.add(item.id);
+  });
+  return ids;
+}
+function validateEffect(v) {
+  const targets = names(v.targets, "/targets", 128);
+  const parameters = names(v.parameters, "/parameters", 64);
+  names(v.tracks, "/tracks", 512);
+  for (let i = 0; i < v.parameters.length; i++) {
+    const p = v.parameters[i];
+    if (p.min > p.max || p.value < p.min || p.value > p.max)
+      effectError("Parameter default must be within min/max", `/parameters/${i}`);
+  }
+  for (let i = 0; i < v.tracks.length; i++) {
+    const a = v.tracks[i], path = `/tracks/${i}`;
+    if (a.start + a.duration > v.duration + 1e-9 || (a.kind === "marker" ? a.duration !== 0 : a.duration <= 0))
+      effectError("Track must fit inside the sequence; only markers have zero duration", path);
+    if (a.kind === "marker") {
+      if (!a.marker) effectError("Marker needs a name", `${path}/marker`);
+      continue;
+    }
+    if (!targets.has(a.target)) effectError("Unknown target", `${path}/target`);
+    if (a.targetPath.split("/").some((p) => p === ".." || p === "."))
+      effectError("Use a relative child path", `${path}/targetPath`);
+    if (a.kind === "property") {
+      if (!a.component || !a.field || !a.from.length || a.from.length > 4 || a.from.length !== a.to.length)
+        effectError(
+          "Property needs component/field and matching numeric endpoints (1\u20134 values)",
+          path
+        );
+      if (a.parameter && !parameters.has(a.parameter))
+        effectError("Unknown parameter", `${path}/parameter`);
+    } else if (a.kind === "visual") {
+      if (!["render/Trail", "render/Beam", "render/Decal"].includes(a.component))
+        effectError("Visual track needs a supported presentation component", `${path}/component`);
+      if (a.endpoint && (a.component !== "render/Beam" || !targets.has(a.endpoint)))
+        effectError("Only beams bind a named endpoint target", `${path}/endpoint`);
+    } else if (!a[a.kind]) effectError(`Missing ${a.kind} asset`, `${path}/${a.kind}`);
+    if ((a.kind === "animation" || a.kind === "particles" || a.kind === "visual") && !v.targets.find((t2) => t2.id === a.target).prefab)
+      effectError(
+        "Animation, particles and visuals require an owned prefab target",
+        `${path}/target`
+      );
+    for (let j = 0; j < i; j++) {
+      const b = v.tracks[j];
+      if (a.target !== b.target || a.targetPath !== b.targetPath || a.start >= b.start + b.duration - 1e-9 || b.start >= a.start + a.duration - 1e-9)
+        continue;
+      if (a.kind === b.kind && (a.kind === "animation" || a.kind === "particles" || a.kind === "visual" && a.component === b.component) || a.kind === "property" && b.kind === "property" && a.component === b.component && a.field === b.field)
+        effectError(`Overlaps track ${b.id}`, path);
+    }
+  }
+}
+function parseEffect(value) {
+  const errors = EffectSequence.validate(value);
+  if (errors.length)
+    throw new ShardError("effects/invalid-sequence", errors[0].message, {
+      path: errors[0].path,
+      details: errors
+    });
+  const document = EffectSequence.deserialize(value);
+  validateEffect(document);
+  return document;
+}
+export {
+  EffectSequence,
+  EffectTrack,
+  effectError,
+  parseEffect,
+  validateEffect
+};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { type EffectDocument, EffectSequence, EffectTrack, type EffectTrackValue, parseEffect, validateEffect, } from './document.js';
+export { effectMethods } from './methods.js';
+export { effectsPlugin } from './plugin.js';
+export { cancelEffect, describeEffects, type EffectInstance, type PlayEffectOptions, type PreparedEffect, pauseEffect, playEffect, prepareEffect, updateEffects, } from './runtime.js';

package/dist/index.js

@@ -0,0 +1,30 @@
+import {
+  EffectSequence,
+  EffectTrack,
+  parseEffect,
+  validateEffect
+} from "./document.js";
+import { effectMethods } from "./methods.js";
+import { effectsPlugin } from "./plugin.js";
+import {
+  cancelEffect,
+  describeEffects,
+  pauseEffect,
+  playEffect,
+  prepareEffect,
+  updateEffects
+} from "./runtime.js";
+export {
+  EffectSequence,
+  EffectTrack,
+  cancelEffect,
+  describeEffects,
+  effectMethods,
+  effectsPlugin,
+  parseEffect,
+  pauseEffect,
+  playEffect,
+  prepareEffect,
+  updateEffects,
+  validateEffect
+};

package/dist/methods.d.ts

@@ -0,0 +1,2 @@
+import type { AppMethod } from '@aethervtt/shard-runtime';
+export declare const effectMethods: AppMethod[];

package/dist/methods.js

@@ -0,0 +1,85 @@
+import { defineSchema, isPlainObject, t } from "@aethervtt/shard-core";
+import { effectError } from "./document.js";
+import {
+  cancelEffect,
+  describeEffects,
+  Effects,
+  pauseEffect,
+  playEffect,
+  prepareEffect
+} from "./runtime.js";
+const effectMethods = [
+  {
+    name: "effects.prepare",
+    description: "Prepare a catalog asset or host-supplied sequence document. Returns a releasable preparation ID.",
+    params: defineSchema("effects/PrepareParams", { source: t.json({ required: true }) }),
+    handler: async ({ world }, p) => ({ preparation: (await prepareEffect(world, p.source)).id })
+  },
+  {
+    name: "effects.release",
+    description: "Release a preparation; active instances retain their assets.",
+    params: defineSchema("effects/ReleaseParams", { preparation: t.u32({ required: true }) }),
+    handler: ({ world }, p) => {
+      const plan = world.resource(Effects).plans.get(p.preparation);
+      const released = !!plan && !plan.released;
+      plan?.release();
+      return { released };
+    }
+  },
+  {
+    name: "effects.play",
+    description: "Play a prepared sequence, binding borrowed targets to live entity IDs.",
+    params: defineSchema("effects/PlayParams", {
+      preparation: t.u32({ required: true }),
+      bindings: t.json({ default: {} }),
+      parameters: t.json({ default: {} }),
+      seed: t.u32(),
+      ownerEntity: t.entity(),
+      parent: t.entity()
+    }),
+    handler: ({ world }, p) => {
+      const plan = world.resource(Effects).plans.get(p.preparation);
+      if (!plan) effectError("Unknown preparation", "/preparation", "invalid-preparation");
+      if (!isPlainObject(p.bindings) || !isPlainObject(p.parameters))
+        effectError("Bindings and parameters must be objects");
+      for (const value of Object.values(p.bindings))
+        if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
+          effectError("Binding must be an entity ID", "/bindings");
+      return {
+        instance: playEffect(world, plan, {
+          bindings: p.bindings,
+          parameters: p.parameters,
+          seed: p.seed,
+          parent: typeof p.parent === "number" && p.parent >= 0 ? p.parent : void 0,
+          ownerEntity: typeof p.ownerEntity === "number" && p.ownerEntity >= 0 ? p.ownerEntity : void 0
+        }).id
+      };
+    }
+  },
+  {
+    name: "effects.cancel",
+    description: "Cancel an active sequence and restore/release its presentation state.",
+    params: defineSchema("effects/CancelParams", { instance: t.u32({ required: true }) }),
+    handler: ({ world }, p) => ({ cancelled: cancelEffect(world, p.instance) })
+  },
+  {
+    name: "effects.pause",
+    description: "Pause/resume this sequence, including its particles and authored audio.",
+    params: defineSchema("effects/PauseParams", {
+      instance: t.u32({ required: true }),
+      paused: t.bool({ default: true })
+    }),
+    handler: ({ world }, p) => ({
+      updated: pauseEffect(world, p.instance, p.paused)
+    })
+  },
+  {
+    name: "effects.inspect",
+    description: "Active sequences, prepared leases, target bindings and bounded cursor-based execution trace.",
+    params: defineSchema("effects/InspectParams", { cursor: t.u32() }),
+    handler: ({ world }, p) => describeEffects(world, p.cursor)
+  }
+];
+export {
+  effectMethods
+};

package/dist/plugin.d.ts

@@ -0,0 +1 @@
+export declare const effectsPlugin: import("@aethervtt/shard-runtime").Plugin;

package/dist/plugin.js

@@ -0,0 +1,21 @@
+import { Update } from "@aethervtt/shard-core";
+import { definePlugin } from "@aethervtt/shard-runtime";
+import * as document from "./document.js";
+import * as methods from "./methods.js";
+import * as runtime from "./runtime.js";
+const effectsPlugin = definePlugin({
+  name: "effects",
+  provides: [document, methods, runtime],
+  build(app) {
+    const state = app.world.initResource(runtime.Effects);
+    for (const plugin of app.describe().plugins) state.plugins.add(plugin.name);
+    app.addSystems(Update, runtime.updateEffects);
+    app.addMethod(...methods.effectMethods);
+  },
+  dispose(app) {
+    runtime.disposeEffects(app.world);
+  }
+});
+export {
+  effectsPlugin
+};

package/dist/runtime.d.ts

@@ -0,0 +1,150 @@
+import { type AnimationLayerValue } from '@aethervtt/shard-animation';
+import { type AudioLease } from '@aethervtt/shard-audio';
+import { type ComponentDef, type ComponentStorage, type Entity, type Owner, type Table, type TypedArray, type World } from '@aethervtt/shard-core';
+import { type EffectDocument, type EffectTrackValue } from './document.js';
+export interface PreparedEffect {
+    readonly id: number;
+    readonly document: EffectDocument;
+    readonly released: boolean;
+    release(): void;
+}
+interface Plan extends PreparedEffect {
+    world: World;
+    refs: number;
+    owner: Owner;
+    audio: AudioLease[];
+}
+interface FieldSlot {
+    entity: Entity;
+    def: ComponentDef;
+    field: string;
+    width: number;
+    saved: Float64Array;
+    table: Table | null;
+    capacity: number;
+    row: number;
+    storage: ComponentStorage | null;
+    column: TypedArray | null;
+    key: string;
+}
+interface Track {
+    definition: EffectTrackValue;
+    entity: Entity | null;
+    slot: FieldSlot | null;
+    from: Float64Array;
+    to: Float64Array;
+    state: number;
+    audio: number;
+    visual: ComponentDef | null;
+    layer: AnimationLayerValue | null;
+    seed: number;
+}
+interface Boundary {
+    time: number;
+    index: number;
+    end: boolean;
+}
+export interface EffectInstance {
+    readonly id: number;
+    readonly seed: number;
+    readonly targets: ReadonlyMap<string, Entity>;
+    readonly time: number;
+    readonly state: 'playing' | 'paused' | 'completed' | 'cancelled' | 'failed';
+    readonly error: string | null;
+}
+interface Instance extends EffectInstance {
+    time: number;
+    state: EffectInstance['state'];
+    error: string | null;
+    plan: Plan;
+    owner: Owner;
+    ownerEntity: Entity | undefined;
+    tracks: Track[];
+    slots: FieldSlot[];
+    boundaries: Boundary[];
+    claims: string[];
+    cursor: number;
+}
+/** Ring storage: recording a boundary does not allocate. Reading diagnostics does. */
+declare class Trace {
+    next: number;
+    times: Float64Array<ArrayBuffer>;
+    ids: Float64Array<ArrayBuffer>;
+    kinds: string[];
+    tracks: string[];
+    reasons: string[];
+    write(id: number, time: number, kind: string, track?: string, reason?: string): void;
+    read(cursor: number): {
+        entries: {
+            cursor: number;
+            instance: number | undefined;
+            time: number | undefined;
+            kind: string | undefined;
+            track: string | undefined;
+            reason: string | undefined;
+        }[];
+        oldestCursor: number;
+        nextCursor: number;
+        truncated: boolean;
+    };
+}
+export declare const Effects: import("@aethervtt/shard-core").ResourceDef<{
+    plans: Map<number, Plan>;
+    active: Instance[];
+    claims: Map<string, number>;
+    plugins: Set<string>;
+    nextId: number;
+    nextPlan: number;
+    pending: number;
+    disposed: boolean;
+    trace: Trace;
+}>;
+/** All references go through the host's catalog. Never interprets a GUID as a URL/path. */
+export declare function prepareEffect(world: World, source: unknown): Promise<PreparedEffect>;
+export interface PlayEffectOptions {
+    bindings?: Readonly<Record<string, Entity>>;
+    parameters?: Readonly<Record<string, number>>;
+    seed?: number;
+    ownerEntity?: Entity;
+    /** Parent frame for owned targets; their authored transforms stay local. */
+    parent?: Entity;
+}
+/** Synchronous after preparation: validation and binding finish before any track starts. */
+export declare function playEffect(world: World, prepared: PreparedEffect, options?: PlayEffectOptions): EffectInstance;
+export declare function cancelEffect(world: World, id: number): boolean;
+export declare function pauseEffect(world: World, id: number, paused?: boolean): boolean;
+/** Exported for isolated performance measurement; App users install effectsPlugin. */
+export declare const updateEffects: import("@aethervtt/shard-core").SystemDef<undefined>;
+export declare function describeEffects(world: World, cursor?: number): {
+    pending: number;
+    preparations: {
+        id: number;
+        released: boolean;
+        references: number;
+        duration: number;
+    }[];
+    instances: {
+        id: number;
+        state: "cancelled" | "completed" | "failed" | "paused" | "playing";
+        time: number;
+        seed: number;
+        targets: {
+            [k: string]: number;
+        };
+    }[];
+    trace: {
+        entries: {
+            cursor: number;
+            instance: number | undefined;
+            time: number | undefined;
+            kind: string | undefined;
+            track: string | undefined;
+            reason: string | undefined;
+        }[];
+        oldestCursor: number;
+        nextCursor: number;
+        truncated: boolean;
+    };
+};
+export declare function disposeEffects(world: World): void;
+export {};

package/dist/runtime.js

@@ -0,0 +1,576 @@
+import {
+  AnimationClips,
+  AnimationPlayer,
+  animationLayer
+} from "@aethervtt/shard-animation";
+import { assetServer } from "@aethervtt/shard-assets";
+import {
+  pauseAudioEvent,
+  playAudioEvent,
+  prepareAudio,
+  stopAudioEvent
+} from "@aethervtt/shard-audio";
+import {
+  defineResource,
+  defineSystem,
+  findComponent,
+  ShardError
+} from "@aethervtt/shard-core";
+import { ParticleSystem } from "@aethervtt/shard-particles";
+import { descendantPaths } from "@aethervtt/shard-render";
+import { FrameDemand, Time } from "@aethervtt/shard-runtime";
+import { loadPrefab, spawnPrefab } from "@aethervtt/shard-scene";
+import {
+  EffectSequence,
+  effectError,
+  parseEffect
+} from "./document.js";
+class Trace {
+  next = 0;
+  times = new Float64Array(2048);
+  ids = new Float64Array(2048);
+  kinds = new Array(2048).fill("");
+  tracks = new Array(2048).fill("");
+  reasons = new Array(2048).fill("");
+  write(id, time, kind, track = "", reason = "") {
+    const s = this.next++ % 2048;
+    this.times[s] = time;
+    this.ids[s] = id;
+    this.kinds[s] = kind;
+    this.tracks[s] = track;
+    this.reasons[s] = reason;
+  }
+  read(cursor) {
+    const oldestCursor = Math.max(0, this.next - 2048);
+    const entries = [];
+    for (let i = Math.max(oldestCursor, cursor); i < this.next; i++) {
+      const s = i % 2048;
+      entries.push({
+        cursor: i,
+        instance: this.ids[s],
+        time: this.times[s],
+        kind: this.kinds[s],
+        track: this.tracks[s],
+        reason: this.reasons[s]
+      });
+    }
+    return { entries, oldestCursor, nextCursor: this.next, truncated: cursor < oldestCursor };
+  }
+}
+const Effects = defineResource("effects/State", {
+  init: () => ({
+    plans: /* @__PURE__ */ new Map(),
+    active: [],
+    claims: /* @__PURE__ */ new Map(),
+    plugins: /* @__PURE__ */ new Set(),
+    nextId: 1,
+    nextPlan: 1,
+    pending: 0,
+    disposed: false,
+    trace: new Trace()
+  })
+});
+function stateOf(world) {
+  const state = world.tryResource(Effects);
+  if (!state || state.disposed)
+    effectError("Install the effects plugin in a live app", "", "no-plugin");
+  return state;
+}
+function dropPlan(plan) {
+  if (--plan.refs !== 0) return;
+  for (const lease of plan.audio) lease.release();
+  plan.world.owners.release(plan.owner);
+  plan.world.resource(Effects).plans.delete(plan.id);
+}
+async function prepareEffect(world, source) {
+  const state = stateOf(world);
+  if (state.plans.size + state.pending >= 128)
+    effectError("Preparation capacity (128) reached", "", "capacity");
+  state.pending++;
+  const id = state.nextPlan++;
+  const owner = world.owners.create(`effect-preparation-${id}`);
+  const audio = [];
+  const server = assetServer(world);
+  const load = async (ref, type) => {
+    if (state.disposed) effectError("App disposed during preparation", "", "disposed");
+    const entry = server.entry(ref);
+    if (!entry || entry.type !== type)
+      effectError(`Expected catalog asset ${type}`, "", "asset-missing");
+    server.lease(entry.guid, owner);
+    await server.load(entry.guid);
+    if (entry.error || entry.state !== "loaded")
+      effectError(`Could not load ${entry.path}`, "", "asset-failed");
+    return { type, guid: entry.guid, path: entry.path };
+  };
+  try {
+    let document;
+    if (typeof source === "string" || source && typeof source === "object" && !("tracks" in source) && ("guid" in source || "path" in source)) {
+      const ref = await load(source, EffectSequence.name);
+      document = parseEffect(
+        EffectSequence.serialize(world.initResource(EffectSequence.store).require(ref))
+      );
+    } else document = parseEffect(source);
+    for (const target of document.targets)
+      if (target.prefab) {
+        if (!state.plugins.has("scene"))
+          effectError("Prefab targets require the scene plugin", "/targets", "missing-plugin");
+        target.prefab = await load(target.prefab, "Prefab");
+        await loadPrefab(world, target.prefab);
+      }
+    for (const track of document.tracks) {
+      const kind = track.kind;
+      if (kind === "property" || kind === "marker") continue;
+      const plugin = kind === "audio" ? "audio/events" : kind === "visual" ? track.component === "render/Decal" ? "render/decals" : "render/ribbons" : kind;
+      if (!state.plugins.has(plugin))
+        effectError(`Track ${track.id} requires ${plugin}`, "/tracks", "missing-plugin");
+      if (kind === "visual") continue;
+      if (kind === "audio") {
+        track.audio = await load(track.audio, "audio/AudioEvent");
+        audio.push(await prepareAudio(world, track.audio));
+      } else if (kind === "animation")
+        track.animation = await load(
+          track.animation,
+          "AnimationClip"
+        );
+      else
+        track.particles = await load(
+          track.particles,
+          "ParticleEffect"
+        );
+    }
+    if (state.disposed) effectError("App disposed during preparation", "", "disposed");
+    const freeze = (value) => {
+      if (value && typeof value === "object") {
+        for (const child of Object.values(value)) freeze(child);
+        Object.freeze(value);
+      }
+    };
+    freeze(document);
+    let released = false;
+    const plan = {
+      id,
+      document,
+      world,
+      owner,
+      audio,
+      refs: 1,
+      get released() {
+        return released;
+      },
+      release() {
+        if (!released) {
+          released = true;
+          dropPlan(plan);
+        }
+      }
+    };
+    state.plans.set(id, plan);
+    return plan;
+  } catch (error) {
+    for (const lease of audio) lease.release();
+    world.owners.release(owner);
+    throw error;
+  } finally {
+    state.pending--;
+  }
+}
+function refresh(world, slot) {
+  if (!world.isAlive(slot.entity)) return false;
+  const table = world.entityTableUnchecked(slot.entity);
+  if (slot.table !== table || slot.capacity !== table.capacity) {
+    const storage = table.storage(slot.def);
+    if (!storage) return false;
+    slot.table = table;
+    slot.capacity = table.capacity;
+    slot.storage = storage;
+    slot.column = storage.byName[slot.field];
+  }
+  slot.row = world.entityRowUnchecked(slot.entity);
+  return true;
+}
+function property(world, entity, d, factor) {
+  const def = findComponent(d.component), field = def?.fields[d.field];
+  if (!def || !field || def.hostOnly || field.options.readonly || !["f32", "f64", "vec2", "vec3", "vec4", "color"].includes(field.kind) || field.stride !== d.from.length || !world.has(entity, def))
+    effectError(`Cannot animate ${d.component}.${d.field} on ${entity}`, "", "invalid-field");
+  for (const values of [d.from, d.to])
+    for (const value of values) {
+      const scaled = value * factor;
+      if (!Number.isFinite(scaled) || field.storage === "f32" && !Number.isFinite(Math.fround(scaled)) || scaled < (field.options.min ?? -Infinity) || scaled > (field.options.max ?? Infinity))
+        effectError("Scaled property endpoint exceeds schema bounds", "", "invalid-field");
+    }
+  const slot = {
+    entity,
+    def,
+    field: d.field,
+    width: field.stride,
+    saved: new Float64Array(field.stride),
+    table: null,
+    capacity: 0,
+    row: 0,
+    storage: null,
+    column: null,
+    key: `${entity}:${def.id}:${d.field}`
+  };
+  refresh(world, slot);
+  for (let i = 0; i < slot.width; i++) slot.saved[i] = slot.column[slot.row * slot.width + i];
+  return slot;
+}
+function playEffect(world, prepared, options = {}) {
+  const state = stateOf(world), plan = state.plans.get(prepared.id);
+  if (plan !== prepared || plan.released)
+    effectError("Preparation is released or belongs to another app", "", "invalid-preparation");
+  if (state.active.length >= 256)
+    effectError("Active instance capacity (256) reached", "", "capacity");
+  const seed = options.seed ?? 0;
+  if (!Number.isInteger(seed) || seed < 0 || seed > 4294967295)
+    effectError("Seed must be a u32", "/seed");
+  if (options.ownerEntity !== void 0 && !world.isAlive(options.ownerEntity))
+    effectError("Owner entity is dead", "", "dead-target");
+  if (options.parent !== void 0 && !world.isAlive(options.parent))
+    effectError("Parent entity is dead", "/parent", "dead-target");
+  const parameters = new Map(plan.document.parameters.map((p) => [p.id, p.value]));
+  for (const [key, value] of Object.entries(options.parameters ?? {})) {
+    const p = plan.document.parameters.find((p2) => p2.id === key);
+    if (!p || !Number.isFinite(value) || value < p.min || value > p.max)
+      effectError(`Invalid parameter ${key}`, "/parameters");
+    parameters.set(key, value);
+  }
+  for (const key of Object.keys(options.bindings ?? {})) {
+    const target = plan.document.targets.find((t) => t.id === key);
+    if (!target || target.prefab) effectError(`Unexpected borrowed binding ${key}`, "/bindings");
+  }
+  const id = state.nextId++;
+  const owner = world.owners.create(`effect-instance-${id}`);
+  const instance = {
+    id,
+    seed,
+    plan,
+    owner,
+    ownerEntity: options.ownerEntity ?? options.parent,
+    targets: /* @__PURE__ */ new Map(),
+    time: 0,
+    state: "playing",
+    error: null,
+    tracks: [],
+    slots: [],
+    boundaries: [],
+    claims: [],
+    cursor: 0
+  };
+  plan.refs++;
+  try {
+    for (const target of plan.document.targets) {
+      let entity;
+      if (target.prefab) {
+        entity = spawnPrefab(world, target.prefab, { parent: options.parent });
+        world.owners.adopt(owner, entity);
+      } else entity = options.bindings?.[target.id];
+      if (entity === void 0 || !world.isAlive(entity))
+        effectError(`Missing live binding ${target.id}`, "/bindings", "dead-target");
+      instance.targets.set(target.id, entity);
+    }
+    const slots = /* @__PURE__ */ new Map();
+    for (let i = 0; i < plan.document.tracks.length; i++) {
+      const d = plan.document.tracks[i];
+      let entity = d.kind === "marker" ? null : instance.targets.get(d.target);
+      if (entity !== null && d.targetPath)
+        entity = descendantPaths(world, entity).get(d.targetPath) ?? null;
+      if (d.kind !== "marker" && entity === null)
+        effectError(`Missing target path for ${d.id}`, `/tracks/${i}/targetPath`, "dead-target");
+      const factor = d.parameter ? parameters.get(d.parameter) : 1;
+      let slot = null;
+      if (d.kind === "property") {
+        slot = property(world, entity, d, factor);
+        const existing = slots.get(slot.key);
+        if (existing) slot = existing;
+        else {
+          if (state.claims.has(slot.key))
+            effectError(
+              `Field claimed by instance ${state.claims.get(slot.key)}`,
+              `/tracks/${i}`,
+              "conflict"
+            );
+          state.claims.set(slot.key, id);
+          instance.claims.push(slot.key);
+          slots.set(slot.key, slot);
+          instance.slots.push(slot);
+        }
+      }
+      const visual = d.kind === "visual" ? findComponent(d.component) : null;
+      if (d.kind === "visual" && (!visual || !world.has(entity, visual)))
+        effectError("Visual target lacks its component", `/tracks/${i}`, "invalid-field");
+      instance.tracks.push({
+        definition: d,
+        entity,
+        slot,
+        from: Float64Array.from(d.from, (v) => v * factor),
+        to: Float64Array.from(d.to, (v) => v * factor),
+        state: 0,
+        audio: 0,
+        layer: null,
+        visual: visual ?? null,
+        seed: (seed ^ Math.imul(i + 1, 2654435769)) >>> 0
+      });
+      instance.boundaries.push({ time: d.start, index: i, end: false });
+      if (d.kind !== "marker")
+        instance.boundaries.push({ time: d.start + d.duration, index: i, end: true });
+    }
+    const channels = instance.tracks.map((track) => {
+      if (track.slot) return [track.slot.key];
+      if (track.visual) return [`${track.entity}:${track.visual.id}:playing`];
+      if (track.definition.kind !== "animation") return [];
+      const paths = descendantPaths(world, track.entity);
+      return world.resource(AnimationClips).require(track.definition.animation).channels.map((channel) => {
+        const entity = paths.get(channel.target);
+        const def = findComponent(channel.component);
+        if (entity === void 0 || !def || !world.has(entity, def))
+          effectError("Animation channel has no live target/component", "", "dead-target");
+        const key = `${entity}:${def.id}:${channel.field}`;
+        const claimed = state.claims.get(key);
+        if (claimed !== void 0 && claimed !== id)
+          effectError("Animation field already claimed", "", "conflict");
+        if (claimed === void 0) {
+          state.claims.set(key, id);
+          instance.claims.push(key);
+        }
+        return key;
+      });
+    });
+    for (let i = 0; i < instance.tracks.length; i++)
+      for (let j = 0; j < i; j++) {
+        const a = instance.tracks[i].definition, b = instance.tracks[j].definition;
+        if (a.start < b.start + b.duration - 1e-9 && b.start < a.start + a.duration - 1e-9 && channels[i].some((key) => channels[j].includes(key)))
+          effectError(
+            "Resolved tracks write the same field concurrently",
+            `/tracks/${i}`,
+            "conflict"
+          );
+      }
+    for (const track of instance.tracks)
+      if (track.visual) {
+        world.set(track.entity, track.visual, { playing: false, paused: false });
+        if (track.definition.endpoint)
+          world.set(track.entity, track.visual, {
+            target: instance.targets.get(track.definition.endpoint)
+          });
+      }
+    instance.boundaries.sort(
+      (a, b) => Math.abs(a.time - b.time) > 1e-9 ? a.time - b.time : Number(b.end) - Number(a.end) || a.index - b.index
+    );
+    state.active.push(instance);
+    state.trace.write(id, 0, "play");
+    advance(world, instance, 0);
+    world.tryResource(FrameDemand)?.hold("effects");
+    return instance;
+  } catch (error) {
+    finish(
+      world,
+      instance,
+      "failed",
+      error instanceof ShardError ? error.code : "effects/activation-failed"
+    );
+    throw error;
+  }
+}
+function sample(world, track, time) {
+  const d = track.definition;
+  if (track.entity !== null && !world.isAlive(track.entity)) return false;
+  if (track.slot) {
+    const slot = track.slot;
+    if (!refresh(world, slot)) return false;
+    let f = Math.min(1, Math.max(0, (time - d.start) / d.duration));
+    if (d.easing === "smoothstep") f = f * f * (3 - 2 * f);
+    const offset = slot.row * slot.width;
+    for (let k = 0; k < slot.width; k++)
+      slot.column[offset + k] = track.from[k] + (track.to[k] - track.from[k]) * f;
+    slot.storage.changed[slot.row] = world.tick;
+    slot.storage.lastChanged = world.tick;
+  } else if (track.layer) track.layer.time = Math.max(0, Math.min(d.duration, time - d.start));
+  return true;
+}
+function startTrack(world, instance, track) {
+  const d = track.definition, entity = track.entity;
+  track.state = 1;
+  if (track.visual) world.set(entity, track.visual, { playing: true, paused: false });
+  else if (d.kind === "animation") {
+    const clip = world.resource(AnimationClips).require(d.animation);
+    track.layer = animationLayer(d.animation, { playing: false, loop: "once" });
+    if (!Number.isFinite(clip.duration)) effectError("Invalid animation clip", "", "asset-failed");
+    if (!world.has(entity, AnimationPlayer)) world.add(entity, AnimationPlayer);
+    world.set(entity, AnimationPlayer, { layers: [track.layer] });
+    track.layer = world.entityTable(entity).column(AnimationPlayer, "layers")[world.entityRow(entity)][0];
+  } else if (d.kind === "particles") {
+    if (!world.has(entity, ParticleSystem)) world.add(entity, ParticleSystem);
+    world.set(entity, ParticleSystem, { effect: d.particles, seed: track.seed, playing: true });
+  } else if (d.kind === "audio")
+    track.audio = playAudioEvent(world, d.audio, { entity, seed: track.seed });
+  world.resource(Effects).trace.write(instance.id, d.start, d.kind === "marker" ? "marker" : "start", d.id, d.marker);
+  if (d.kind === "marker") track.state = 2;
+}
+function endTrack(world, track, teardown = false) {
+  if (track.audio) {
+    stopAudioEvent(world, track.audio, { release: 0 });
+    track.audio = 0;
+  }
+  if (track.entity !== null && world.isAlive(track.entity)) {
+    if (track.visual && world.has(track.entity, track.visual))
+      world.set(track.entity, track.visual, { playing: false, paused: false });
+    if (track.definition.kind === "particles" && world.has(track.entity, ParticleSystem))
+      world.remove(track.entity, ParticleSystem);
+    if (teardown && track.layer && world.has(track.entity, AnimationPlayer))
+      world.remove(track.entity, AnimationPlayer);
+  }
+  if (teardown) track.layer = null;
+  track.state = 2;
+}
+function finish(world, instance, status, reason = "") {
+  if (instance.state === "completed" || instance.state === "cancelled" || instance.state === "failed")
+    return;
+  const state = world.resource(Effects);
+  instance.state = status;
+  instance.error = reason || null;
+  for (let i = 0; i < instance.tracks.length; i++) endTrack(world, instance.tracks[i], true);
+  for (let i = 0; i < instance.slots.length; i++) {
+    const slot = instance.slots[i];
+    if (refresh(world, slot)) {
+      for (let k = 0; k < slot.width; k++) slot.column[slot.row * slot.width + k] = slot.saved[k];
+      slot.storage.changed[slot.row] = world.tick;
+      slot.storage.lastChanged = world.tick;
+    }
+  }
+  for (let i = 0; i < instance.claims.length; i++) state.claims.delete(instance.claims[i]);
+  world.owners.release(instance.owner);
+  dropPlan(instance.plan);
+  const at = state.active.indexOf(instance);
+  if (at !== -1) state.active.splice(at, 1);
+  state.trace.write(instance.id, instance.time, status, "", reason);
+  refreshDemand(world);
+}
+function advance(world, instance, time) {
+  const trace = world.resource(Effects).trace;
+  instance.time = Math.min(time, instance.plan.document.duration);
+  while (instance.cursor < instance.boundaries.length && instance.boundaries[instance.cursor].time <= instance.time + 1e-9) {
+    const b = instance.boundaries[instance.cursor++], track = instance.tracks[b.index], d = track.definition;
+    if (b.end) {
+      if (track.state === 1) {
+        if (!sample(world, track, b.time)) effectError("Target disappeared", "", "dead-target");
+        endTrack(world, track);
+        trace.write(instance.id, b.time, "end", d.id);
+      }
+    } else if ((d.kind === "audio" || d.kind === "particles" || d.kind === "visual") && d.start + d.duration <= instance.time) {
+      track.state = 2;
+      trace.write(instance.id, b.time, "skip", d.id, "missed-window");
+    } else startTrack(world, instance, track);
+  }
+  for (let i = 0; i < instance.tracks.length; i++) {
+    const track = instance.tracks[i];
+    if (track.state === 1 && !sample(world, track, instance.time))
+      effectError("Target disappeared", "", "dead-target");
+  }
+  if (instance.time >= instance.plan.document.duration - 1e-9) finish(world, instance, "completed");
+}
+function cancelEffect(world, id) {
+  const state = stateOf(world), instance = state.active.find((i) => i.id === id);
+  if (!instance) return false;
+  finish(world, instance, "cancelled");
+  return true;
+}
+function refreshDemand(world) {
+  const active = world.resource(Effects).active;
+  let playing = false;
+  for (let i = 0; i < active.length; i++)
+    if (active[i].state === "playing") {
+      playing = true;
+      break;
+    }
+  world.tryResource(FrameDemand)?.set("effects", playing);
+}
+function pauseEffect(world, id, paused = true) {
+  const instance = stateOf(world).active.find((i) => i.id === id);
+  if (!instance) return false;
+  instance.state = paused ? "paused" : "playing";
+  for (const track of instance.tracks) {
+    if (track.audio) pauseAudioEvent(world, track.audio, paused);
+    if (track.visual && track.state !== 0 && world.isAlive(track.entity))
+      world.set(track.entity, track.visual, { paused });
+    if (track.state === 1 && track.definition.kind === "particles" && world.isAlive(track.entity))
+      world.set(track.entity, ParticleSystem, { playing: !paused });
+  }
+  refreshDemand(world);
+  world.resource(Effects).trace.write(id, instance.time, paused ? "pause" : "resume");
+  return true;
+}
+const updateEffects = defineSystem({
+  name: "effects/update",
+  run(_, world) {
+    const state = world.resource(Effects), delta = world.resource(Time).delta;
+    if (state.disposed) return;
+    for (let i = state.active.length - 1; i >= 0; i--) {
+      const instance = state.active[i];
+      if (instance.ownerEntity !== void 0 && !world.isAlive(instance.ownerEntity)) {
+        finish(world, instance, "cancelled", "owner-removed");
+        continue;
+      }
+      let dead = false;
+      for (let j = 0; j < instance.tracks.length; j++) {
+        const track = instance.tracks[j], entity = track.entity, endpoint = track.definition.endpoint ? instance.targets.get(track.definition.endpoint) : void 0;
+        if (entity !== null && !world.isAlive(entity) || endpoint !== void 0 && !world.isAlive(endpoint)) {
+          dead = true;
+          break;
+        }
+      }
+      if (dead) {
+        finish(world, instance, "failed", "effects/dead-target");
+        continue;
+      }
+      if (instance.state === "paused") continue;
+      try {
+        advance(world, instance, instance.time + delta);
+      } catch (error) {
+        finish(
+          world,
+          instance,
+          "failed",
+          error instanceof ShardError ? error.code : "effects/update-failed"
+        );
+      }
+    }
+  }
+});
+function describeEffects(world, cursor = 0) {
+  const state = stateOf(world);
+  return {
+    pending: state.pending,
+    preparations: [...state.plans.values()].map((p) => ({
+      id: p.id,
+      released: p.released,
+      references: p.refs,
+      duration: p.document.duration
+    })),
+    instances: state.active.map((i) => ({
+      id: i.id,
+      state: i.state,
+      time: i.time,
+      seed: i.seed,
+      targets: Object.fromEntries(i.targets)
+    })),
+    trace: state.trace.read(cursor)
+  };
+}
+function disposeEffects(world) {
+  const state = world.resource(Effects);
+  while (state.active.length)
+    finish(world, state.active[state.active.length - 1], "cancelled", "disposed");
+  for (const plan of state.plans.values()) plan.release();
+  state.disposed = true;
+}
+export {
+  Effects,
+  cancelEffect,
+  describeEffects,
+  disposeEffects,
+  pauseEffect,
+  playEffect,
+  prepareEffect,
+  updateEffects
+};

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@aethervtt/shard-effects",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "@aethervtt/shard-core": "0.2.1",
+    "@aethervtt/shard-runtime": "0.2.1",
+    "@aethervtt/shard-assets": "0.2.1",
+    "@aethervtt/shard-scene": "0.2.1",
+    "@aethervtt/shard-animation": "0.2.1",
+    "@aethervtt/shard-audio": "0.2.1",
+    "@aethervtt/shard-particles": "0.2.1",
+    "@aethervtt/shard-transform": "0.2.1",
+    "@aethervtt/shard-render": "0.2.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aethervtt/shard.git",
+    "directory": "packages/effects"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "shard": {
+    "buildSha": "772eb0d2b8a5fc499105708f4ae92c58788cc9ea"
+  }
+}