@sadhaka/loom-engine 0.13.0 → 0.15.0

package/dist/audio/spatial-audio-system.js

@@ -0,0 +1,98 @@
+// SpatialAudioSystem - pushes the local character's transform into
+// the AudioListener resource and the SpatialAudioBus each frame.
+//
+// Phasing rationale (matches PeerRenderSystem / animation-system):
+//   PHASE_RENDER, AFTER any camera/transform sync systems, BEFORE
+//   the renderer submits draw calls. The listener pose for THIS frame
+//   reflects the THIS-FRAME world transform of the player - so a
+//   positional sound triggered by a render-phase system (e.g. cue
+//   reactions to zone events drained earlier in PHASE_LOGIC) hears
+//   the world from the up-to-date listener pose.
+//
+// Per LOOM-AUDIO-SPEC.md §3.3 the work is one-line: read the local
+// character's TransformPool entry by entity id, write its (x, y, z)
+// into the AudioListenerResource.pose, stamp lastUpdateFrame, and
+// hand the pose to SpatialAudioBus.setListener.
+//
+// Identity binding: the engine doesn't know which entity is the local
+// character - that's a consumer concern (TWT wires it after server
+// auth completes). Consumers call setLocalCharacterEntity(entity) on
+// the system. setLocalCharacterEntity(null) puts the system back into
+// no-op mode (e.g. between zones during a teleport).
+//
+// Tolerates:
+//   - missing AudioListenerResource (silent no-op; engine probably
+//     not yet fully wired)
+//   - missing SpatialAudioBus (silent no-op; consumer might have
+//     opted out of spatial audio entirely - the system still keeps
+//     the resource fresh for debug/HUD readers)
+//   - missing TransformPool (silent no-op; engine without ECS
+//     transforms is unusual but valid in headless server tests)
+//   - local character set but transform not attached yet (no-op)
+//
+// What this system does NOT do (deferred to future phases):
+//   - rotate the listener with the player's facing (spec §8.4 fixes
+//     forward = (0, 0, -1))
+//   - apply velocity-based Doppler (PannerNode.setVelocity is
+//     deprecated; v1 ships flat doppler-off audio)
+//   - any per-source position update (handle.setPosition owns that)
+import { entityIndex } from '../entity.js';
+import { POOL_TRANSFORM } from '../world.js';
+import { RESOURCE_TIME, } from '../resources.js';
+import { RESOURCE_AUDIO_LISTENER, } from './audio-listener-resource.js';
+export class SpatialAudioSystem {
+    name = 'spatial-audio';
+    localCharacter = null;
+    spatialBus = null;
+    // Optional spatial bus reference. The system can also work without
+    // a bus (resource-only mode) - useful for tests and for consumers
+    // who do not want positional audio but still want a tracked listener
+    // pose (e.g. for visual SFX triggered relative to the player).
+    constructor(opts = {}) {
+        this.spatialBus = opts.spatialBus ?? null;
+    }
+    // Wire (or rewire) the spatial bus. Useful when the AudioBus is
+    // created lazily after first user gesture - the system can be
+    // registered upfront and the bus attached later.
+    setSpatialBus(bus) {
+        this.spatialBus = bus;
+    }
+    // Bind the local character entity. null means "no local character"
+    // (e.g. mid-teleport, character not yet allocated, headless mode).
+    // The system tolerates an entity that doesn't have a transform yet
+    // by silently skipping the update.
+    setLocalCharacterEntity(entity) {
+        this.localCharacter = entity;
+    }
+    getLocalCharacterEntity() {
+        return this.localCharacter;
+    }
+    update(world, _dt) {
+        if (this.localCharacter === null)
+            return;
+        var listener = world.resources.get(RESOURCE_AUDIO_LISTENER);
+        if (!listener)
+            return;
+        var transforms = world.getPool(POOL_TRANSFORM);
+        if (!transforms)
+            return;
+        var idx = entityIndex(this.localCharacter);
+        // Bounds check against the high-water mark so a fresh entity that
+        // the consumer registered before attaching a transform doesn't
+        // produce undefined reads on the typed arrays.
+        if (idx >= transforms.getHighWaterMark())
+            return;
+        var x = transforms.x[idx] ?? 0;
+        var y = transforms.y[idx] ?? 0;
+        var z = transforms.z[idx] ?? 0;
+        listener.pose.x = x;
+        listener.pose.y = y;
+        listener.pose.z = z;
+        var time = world.resources.get(RESOURCE_TIME);
+        listener.lastUpdateFrame = time ? time.frame : listener.lastUpdateFrame + 1;
+        if (this.spatialBus) {
+            this.spatialBus.setListener(listener.pose);
+        }
+    }
+}
+//# sourceMappingURL=spatial-audio-system.js.map

package/dist/audio/spatial-audio-system.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spatial-audio-system.js","sourceRoot":"","sources":["../../src/audio/spatial-audio-system.ts"],"names":[],"mappings":"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"}

package/dist/audio/zone-audio-system.d.ts

@@ -0,0 +1,78 @@
+import type { System } from '../system.js';
+import type { World } from '../world.js';
+import type { ZoneEvent, ZoneEventType } from '../director/zone/zone-event-envelope.js';
+export interface PositionalPlayOptionsStub {
+    x?: number;
+    y?: number;
+    z?: number;
+    gain?: number;
+    rate?: number;
+    loop?: boolean;
+    refDistance?: number;
+    maxDistance?: number;
+    rolloffFactor?: number;
+    distanceModel?: 'linear' | 'inverse' | 'exponential';
+}
+export interface AudioListenerPoseStub {
+    x: number;
+    y: number;
+    z?: number;
+    forward?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    up?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+export interface AudioListenerResourceStub {
+    pose: AudioListenerPoseStub;
+    lastUpdateFrame: number;
+}
+export interface CueCatalogStub {
+    play(name: string, options?: PositionalPlayOptionsStub): unknown;
+}
+export interface MusicDirectorStub {
+    playMusic(name: string, fadeInMs?: number): void;
+    stopMusic(fadeOutMs?: number): Promise<void> | void;
+    crossfadeMusic(name: string, fadeMs?: number): void;
+    currentMusic(): string | null;
+}
+export declare const RESOURCE_AUDIO_LISTENER_STUB = "audio_listener";
+export declare const RESOURCE_CUE_CATALOG_STUB = "cue_catalog";
+export declare const RESOURCE_MUSIC_DIRECTOR_STUB = "music_director";
+export interface ZoneCuePlay {
+    cue: string;
+    options?: PositionalPlayOptionsStub;
+}
+export interface ZoneAudioContext {
+    cues: CueCatalogStub | null;
+    music: MusicDirectorStub | null;
+    localZone: string | null;
+    listener: AudioListenerPoseStub;
+}
+export interface ZoneAudioMapping {
+    eventType: ZoneEventType;
+    handle(event: ZoneEvent, ctx: ZoneAudioContext): ZoneCuePlay | null;
+}
+export interface ZoneAudioSystemOptions {
+    currentZone?: () => string | null;
+    verbose?: boolean;
+}
+export declare class ZoneAudioSystem implements System {
+    readonly name: string;
+    private readonly mappings;
+    private readonly currentZone;
+    private readonly verbose;
+    private readonly lastProcessedIdByZone;
+    constructor(opts?: ZoneAudioSystemOptions);
+    registerMapping(mapping: ZoneAudioMapping): void;
+    unregisterMapping(eventType: ZoneEventType): void;
+    hasMapping(eventType: ZoneEventType): boolean;
+    mappingCount(): number;
+    update(world: World, _dt: number): void;
+}
+//# sourceMappingURL=zone-audio-system.d.ts.map

package/dist/audio/zone-audio-system.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zone-audio-system.d.ts","sourceRoot":"","sources":["../../src/audio/zone-audio-system.ts"],"names":[],"mappings":"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"}

package/dist/audio/zone-audio-system.js

@@ -0,0 +1,206 @@
+// ZoneAudioSystem - zone-event audio integration shell (Phase 17, Track C).
+//
+// Runs PHASE_RENDER, AFTER ZoneEventSystem (which appends every
+// observed zone event to the per-zone ring buffer in
+// ZoneEventLog.byZone[<zone>].recent). Each tick the audio system
+// drains the local zone's ring buffer for events that landed THIS
+// frame (i.e. events with id strictly greater than the last id we
+// processed for that zone), looks up the consumer-registered mapping
+// for each event type, and dispatches the resulting cue play through
+// the registered CueCatalog / MusicDirector resources.
+//
+// This file ships ZERO mappings. Engine consumers (TheWorldTable.ai,
+// etc.) register their own mappings for the cues they want to fire on
+// each zone event type.
+//
+// Tolerances:
+//   - Missing mapping for an event type: log + skip silently. Most
+//     consumers will register only a subset of the seven zone event
+//     types.
+//   - Missing CueCatalog / MusicDirector resources: no-op gracefully.
+//     The system keeps draining events but cue plays evaporate. This
+//     lets a consumer wire ZoneAudioSystem before the catalog is built
+//     (e.g. while audio assets are still loading) without crashing.
+//   - Missing ZoneEventLog: no-op (nothing to drain).
+//   - Missing AudioListener resource: cue plays still dispatch but
+//     `listener` in the handler context falls back to a zero pose.
+//   - Multiple mappings for the SAME event type: registerMapping
+//     overwrites. unregisterMapping by eventType.
+//
+// Dispatch ORDER: registerMapping registration order is irrelevant
+// since each event type has at most ONE handler. The order in which
+// events are processed within a tick is the order they appear in
+// ZoneEventLog.byZone[<zone>].recent (newest first, per Phase 16
+// log semantics). Per spec we replay newest-first so a consumer that
+// registers a music crossfade reacts to the latest knot pulse before
+// older ones; the zone-events log is a deduped ring, so duplicates
+// are not a concern.
+import { RESOURCE_ZONE_EVENT_LOG, } from '../director/zone/zone-event-log.js';
+// Resource keys (defined here as duplicate string constants to keep
+// the system standalone). The values MATCH the ones declared in the
+// Track A / Track B files; coordination merge will swap to a single
+// import after 0.15.0 assembles.
+// TODO[phase-17-merge]: replace these constants with re-imports from
+// audio-listener-resource.ts / cue-catalog.ts / music-director.ts.
+export const RESOURCE_AUDIO_LISTENER_STUB = 'audio_listener';
+export const RESOURCE_CUE_CATALOG_STUB = 'cue_catalog';
+export const RESOURCE_MUSIC_DIRECTOR_STUB = 'music_director';
+// ---- The system ----
+export class ZoneAudioSystem {
+    name = 'zone-audio';
+    mappings;
+    currentZone;
+    verbose;
+    // Per-zone last processed event id. Drives the "events landed this
+    // frame" filter so the system reads the per-zone ring buffer once
+    // per tick and fires only fresh events.
+    lastProcessedIdByZone;
+    constructor(opts = {}) {
+        this.mappings = new Map();
+        this.currentZone = opts.currentZone ?? null;
+        this.verbose = opts.verbose ?? false;
+        this.lastProcessedIdByZone = new Map();
+    }
+    registerMapping(mapping) {
+        if (!mapping || typeof mapping.eventType !== 'string'
+            || typeof mapping.handle !== 'function') {
+            return;
+        }
+        this.mappings.set(mapping.eventType, mapping);
+    }
+    unregisterMapping(eventType) {
+        this.mappings.delete(eventType);
+    }
+    // For tests + introspection.
+    hasMapping(eventType) {
+        return this.mappings.has(eventType);
+    }
+    mappingCount() {
+        return this.mappings.size;
+    }
+    update(world, _dt) {
+        const log = world.resources.get(RESOURCE_ZONE_EVENT_LOG);
+        if (!log)
+            return;
+        const cues = world.resources.get(RESOURCE_CUE_CATALOG_STUB) ?? null;
+        const music = world.resources.get(RESOURCE_MUSIC_DIRECTOR_STUB) ?? null;
+        const listenerRes = world.resources.get(RESOURCE_AUDIO_LISTENER_STUB);
+        const listener = listenerRes
+            ? listenerRes.pose
+            : { x: 0, y: 0, z: 0 };
+        const localZone = safeCurrentZone(this.currentZone);
+        // Decide which zones to drain. With a local-zone filter set, we
+        // drain ONLY that zone; without it, we drain every zone present
+        // in the log (single-zone consumers + tests).
+        const zonesToDrain = [];
+        if (localZone !== null) {
+            if (log.byZone.has(localZone))
+                zonesToDrain.push(localZone);
+        }
+        else {
+            for (const z of log.byZone.keys())
+                zonesToDrain.push(z);
+        }
+        for (let zi = 0; zi < zonesToDrain.length; zi++) {
+            const zone = zonesToDrain[zi];
+            const entry = log.byZone.get(zone);
+            if (!entry)
+                continue;
+            // recent[] is newest-first per Phase 16 ZoneEventLog convention.
+            // We walk from oldest -> newest among UNSEEN events so handlers
+            // see events in chronological order (e.g. boss.spawn before
+            // boss.tick). Determine the cutoff by lastProcessedId for this
+            // zone.
+            const lastId = this.lastProcessedIdByZone.get(zone) ?? 0;
+            let maxIdSeen = lastId;
+            // Walk newest->oldest, collect unseen, then reverse so dispatch
+            // is oldest->newest.
+            const fresh = [];
+            for (let i = 0; i < entry.recent.length; i++) {
+                const ev = entry.recent[i];
+                if (!ev)
+                    continue;
+                if (ev.id > lastId) {
+                    fresh.push(ev);
+                    if (ev.id > maxIdSeen)
+                        maxIdSeen = ev.id;
+                }
+                else {
+                    // Past the boundary; older events have already been
+                    // processed.
+                    break;
+                }
+            }
+            if (fresh.length === 0)
+                continue;
+            // Reverse to oldest-first.
+            for (let i = fresh.length - 1; i >= 0; i--) {
+                const ev = fresh[i];
+                const mapping = this.mappings.get(ev.type);
+                if (!mapping) {
+                    if (this.verbose) {
+                        try {
+                            console.log('[zone-audio] no mapping for ' + ev.type + ' (zone='
+                                + ev.zone_id + ', id=' + ev.id + ')');
+                        }
+                        catch { /* ignore */ }
+                    }
+                    continue;
+                }
+                const ctx = {
+                    cues,
+                    music,
+                    localZone,
+                    listener,
+                };
+                let result = null;
+                try {
+                    result = mapping.handle(ev, ctx);
+                }
+                catch (err) {
+                    if (this.verbose) {
+                        try {
+                            console.warn('[zone-audio] mapping handle threw', err);
+                        }
+                        catch { /* ignore */ }
+                    }
+                    result = null;
+                }
+                if (!result)
+                    continue;
+                if (typeof result.cue !== 'string' || result.cue.length === 0)
+                    continue;
+                if (!cues) {
+                    // Catalog absent: silently drop the cue. The handler
+                    // already ran (e.g. it called ctx.music.crossfadeMusic) so
+                    // music side-effects still happen.
+                    continue;
+                }
+                try {
+                    cues.play(result.cue, result.options);
+                }
+                catch (err) {
+                    if (this.verbose) {
+                        try {
+                            console.warn('[zone-audio] cues.play threw', err);
+                        }
+                        catch { /* ignore */ }
+                    }
+                }
+            }
+            this.lastProcessedIdByZone.set(zone, maxIdSeen);
+        }
+    }
+}
+function safeCurrentZone(fn) {
+    if (!fn)
+        return null;
+    try {
+        const z = fn();
+        return typeof z === 'string' && z.length > 0 ? z : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=zone-audio-system.js.map

package/dist/audio/zone-audio-system.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zone-audio-system.js","sourceRoot":"","sources":["../../src/audio/zone-audio-system.ts"],"names":[],"mappings":"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"}

package/dist/director/ai/ai-plugin-registry.d.ts

@@ -0,0 +1,20 @@
+import type { IAIPlugin, EmittedEvents, PluginContext, PeerInfo, PlayerAction } from './plugin.js';
+export declare class AIPluginDuplicateError extends Error {
+    readonly pluginName: string;
+    constructor(pluginName: string);
+}
+export declare class AIPluginRegistry {
+    private plugins;
+    register(plugin: IAIPlugin): void;
+    unregister(name: string): Promise<boolean>;
+    list(): ReadonlyArray<IAIPlugin>;
+    get(name: string): IAIPlugin | undefined;
+    dispatchTick(ctx: PluginContext): Promise<EmittedEvents>;
+    dispatchPeerJoin(ctx: PluginContext, peer: PeerInfo): Promise<EmittedEvents>;
+    dispatchPeerLeave(ctx: PluginContext, peer: PeerInfo): Promise<EmittedEvents>;
+    dispatchZoneEnter(ctx: PluginContext, peer: PeerInfo, fromZone: string | null): Promise<EmittedEvents>;
+    dispatchPlayerAction(ctx: PluginContext, peer: PeerInfo, action: PlayerAction): Promise<EmittedEvents>;
+    private dispatch;
+    private errorMeta;
+}
+//# sourceMappingURL=ai-plugin-registry.d.ts.map

package/dist/director/ai/ai-plugin-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-plugin-registry.d.ts","sourceRoot":"","sources":["../../../src/director/ai/ai-plugin-registry.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EACV,SAAS,EACT,aAAa,EACb,aAAa,EACb,QAAQ,EACR,YAAY,EACb,MAAM,aAAa,CAAC;AAErB,qBAAa,sBAAuB,SAAQ,KAAK;aACnB,UAAU,EAAE,MAAM;gBAAlB,UAAU,EAAE,MAAM;CAI/C;AAED,qBAAa,gBAAgB;IAK3B,OAAO,CAAC,OAAO,CAAmB;IAOlC,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI;IA0B3B,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA8BhD,IAAI,IAAI,aAAa,CAAC,SAAS,CAAC;IAMhC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAgBlC,YAAY,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;IAMxD,gBAAgB,CAAC,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,aAAa,CAAC;IAM5E,iBAAiB,CAAC,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,aAAa,CAAC;IAM7E,iBAAiB,CACrB,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE,QAAQ,EACd,QAAQ,EAAE,MAAM,GAAG,IAAI,GACtB,OAAO,CAAC,aAAa,CAAC;IAMnB,oBAAoB,CACxB,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE,QAAQ,EACd,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,aAAa,CAAC;YAYX,QAAQ;IAiEtB,OAAO,CAAC,SAAS;CAgBlB"}

package/dist/director/ai/ai-plugin-registry.js

@@ -0,0 +1,232 @@
+// AIPluginRegistry - dispatches lifecycle hooks across registered plugins.
+//
+// Per LOOM-DIRECTOR-PROTOCOL-V2 Section 5.3: the registry holds N
+// plugins, dispatches each hook in priority order (lower runs first),
+// and concatenates the EmittedEvents from every plugin into a single
+// merged result. The caller (the engine's emit path / TWT's loom_director
+// orchestrator) takes the merged events and routes them - character
+// events to the v1 stream, zone events to the v2 zone log + presence
+// fanout.
+//
+// Error isolation guarantee (open question 8.3): if a plugin's hook
+// throws synchronously OR the returned Promise rejects, the registry
+// logs the failure via that plugin's logger, drops that plugin's
+// contribution for THIS dispatch only, and continues with the next
+// plugin. The dispatch never throws to the caller. Plugin authors
+// remain responsible for their own internal try/catch; the registry
+// is the safety net of last resort.
+//
+// Implementation notes:
+//   - Plugins are kept in a sorted array; register/unregister keep
+//     it sorted so the dispatch hot path is a simple iteration.
+//   - The registry never instantiates a PluginContext; the caller
+//     supplies one per dispatch (or reuses one and refreshes views).
+//     This keeps the registry decoupled from world-state plumbing.
+//   - dispose() is awaited inside unregister() so plugins can flush
+//     pending work; if dispose throws we log and continue (drop
+//     guarantee extends to dispose so the caller never sees plugin
+//     errors leak).
+export class AIPluginDuplicateError extends Error {
+    pluginName;
+    constructor(pluginName) {
+        super('AIPluginDuplicateError: plugin already registered: ' + pluginName);
+        this.pluginName = pluginName;
+        this.name = 'AIPluginDuplicateError';
+    }
+}
+export class AIPluginRegistry {
+    // Sorted by priority ascending, then by registration order. The
+    // registration index is encoded by inserting at the right position
+    // on register() rather than re-sorting, which preserves stable
+    // ordering for equal priorities.
+    plugins = [];
+    // ----- Lifecycle -----
+    // Register a plugin. Throws AIPluginDuplicateError if a plugin with
+    // the same name is already registered (names are the registry key).
+    // Insertion is O(n) but n is small (typically 1-10 plugins).
+    register(plugin) {
+        for (var i = 0; i < this.plugins.length; i++) {
+            var existing = this.plugins[i];
+            if (existing && existing.name === plugin.name) {
+                throw new AIPluginDuplicateError(plugin.name);
+            }
+        }
+        // Find the first plugin with strictly higher priority and insert
+        // before it. This preserves stable ordering for equal priorities
+        // (a later-registered plugin runs after an earlier one with the
+        // same priority).
+        var insertAt = this.plugins.length;
+        for (var j = 0; j < this.plugins.length; j++) {
+            var p = this.plugins[j];
+            if (p && p.priority > plugin.priority) {
+                insertAt = j;
+                break;
+            }
+        }
+        this.plugins.splice(insertAt, 0, plugin);
+    }
+    // Unregister a plugin by name. Awaits the plugin's dispose() if
+    // present; logs and drops if dispose throws. Returns true if a
+    // plugin was removed, false if no plugin with that name was
+    // registered.
+    async unregister(name) {
+        var idx = -1;
+        for (var i = 0; i < this.plugins.length; i++) {
+            var p = this.plugins[i];
+            if (p && p.name === name) {
+                idx = i;
+                break;
+            }
+        }
+        if (idx === -1)
+            return false;
+        var plugin = this.plugins[idx];
+        this.plugins.splice(idx, 1);
+        if (plugin && typeof plugin.dispose === 'function') {
+            try {
+                await plugin.dispose();
+            }
+            catch (err) {
+                // Drop guarantee extends to dispose. We can't log via the
+                // plugin's logger because we have no PluginContext here;
+                // fall back to console with the plugin name tag.
+                console.error('[plugin: ' + plugin.name + '] dispose() threw', this.errorMeta(err));
+            }
+        }
+        return true;
+    }
+    // Read-only snapshot of the plugin list, in dispatch order. Returns
+    // a fresh array; mutating it does not affect the registry.
+    list() {
+        return this.plugins.slice();
+    }
+    // Look up a plugin by name. Returns undefined if no plugin with
+    // that name is registered.
+    get(name) {
+        for (var i = 0; i < this.plugins.length; i++) {
+            var p = this.plugins[i];
+            if (p && p.name === name)
+                return p;
+        }
+        return undefined;
+    }
+    // ----- Dispatchers -----
+    // All five dispatchers share the same shape: iterate plugins in
+    // priority order, call the hook if defined, await the result, merge
+    // into the running EmittedEvents. Errors are caught per-plugin and
+    // logged via the plugin's logger if reachable through ctx; never
+    // thrown to the caller.
+    async dispatchTick(ctx) {
+        return this.dispatch(ctx, 'onTick', function (plugin, ctx) {
+            return plugin.onTick(ctx);
+        });
+    }
+    async dispatchPeerJoin(ctx, peer) {
+        return this.dispatch(ctx, 'onPeerJoin', function (plugin, ctx) {
+            return plugin.onPeerJoin(ctx, peer);
+        });
+    }
+    async dispatchPeerLeave(ctx, peer) {
+        return this.dispatch(ctx, 'onPeerLeave', function (plugin, ctx) {
+            return plugin.onPeerLeave(ctx, peer);
+        });
+    }
+    async dispatchZoneEnter(ctx, peer, fromZone) {
+        return this.dispatch(ctx, 'onZoneEnter', function (plugin, ctx) {
+            return plugin.onZoneEnter(ctx, peer, fromZone);
+        });
+    }
+    async dispatchPlayerAction(ctx, peer, action) {
+        return this.dispatch(ctx, 'onPlayerAction', function (plugin, ctx) {
+            return plugin.onPlayerAction(ctx, peer, action);
+        });
+    }
+    // ----- Internals -----
+    // Generic dispatch helper. `hookName` is the property name we check
+    // for definition on each plugin; `invoke` calls the actual hook
+    // (the spread of args differs per dispatcher). Per-plugin try/catch
+    // around the await isolates failures.
+    async dispatch(ctx, hookName, invoke) {
+        var merged = {};
+        var characterEvents = undefined;
+        var zoneEvents = undefined;
+        // Snapshot the plugin list at dispatch start so a mutation during
+        // the dispatch (a hook calls registry.register/unregister) cannot
+        // change which plugins run for THIS dispatch. Spec doesn't forbid
+        // mutation but the predictable behavior is "this dispatch sees
+        // the registry as it was at start".
+        var snapshot = this.plugins.slice();
+        for (var i = 0; i < snapshot.length; i++) {
+            var plugin = snapshot[i];
+            if (!plugin)
+                continue;
+            // Hook not implemented by this plugin? Skip without allocating
+            // anything. Use bracket access so the keyof typing carries through.
+            var hook = plugin[hookName];
+            if (typeof hook !== 'function')
+                continue;
+            var emitted;
+            try {
+                emitted = await invoke(plugin, ctx);
+            }
+            catch (err) {
+                // Log via the plugin's logger so the failure is tagged with
+                // the plugin name. ctx.logger may itself throw; if so, fall
+                // back to console (cannot let logger errors break dispatch).
+                try {
+                    ctx.logger.error('plugin hook ' + String(hookName) + ' threw', this.errorMeta(err));
+                }
+                catch {
+                    console.error('[plugin: ' + plugin.name + '] hook ' + String(hookName) + ' threw', this.errorMeta(err));
+                }
+                // Drop this plugin's contribution for this dispatch.
+                continue;
+            }
+            if (!emitted)
+                continue;
+            if (emitted.characterEvents && emitted.characterEvents.length > 0) {
+                if (!characterEvents)
+                    characterEvents = [];
+                for (var ci = 0; ci < emitted.characterEvents.length; ci++) {
+                    var ce = emitted.characterEvents[ci];
+                    if (ce)
+                        characterEvents.push(ce);
+                }
+            }
+            if (emitted.zoneEvents && emitted.zoneEvents.length > 0) {
+                if (!zoneEvents)
+                    zoneEvents = [];
+                for (var zi = 0; zi < emitted.zoneEvents.length; zi++) {
+                    var ze = emitted.zoneEvents[zi];
+                    if (ze)
+                        zoneEvents.push(ze);
+                }
+            }
+        }
+        if (characterEvents)
+            merged.characterEvents = characterEvents;
+        if (zoneEvents)
+            merged.zoneEvents = zoneEvents;
+        return merged;
+    }
+    // Pull useful fields out of an unknown error for log meta. Avoids
+    // throwing on non-Error throws (strings, objects, undefined).
+    errorMeta(err) {
+        if (err instanceof Error) {
+            return {
+                error_name: err.name,
+                error_message: err.message,
+                error_stack: err.stack ?? null,
+            };
+        }
+        var safe;
+        try {
+            safe = JSON.stringify(err);
+        }
+        catch {
+            safe = String(err);
+        }
+        return { error: safe };
+    }
+}
+//# sourceMappingURL=ai-plugin-registry.js.map