Triggers

@urth/metatell-sdk/triggers lets a plugin list, fire, enable/disable, and observe Spoke triggers in the current scene.

Experimental. This API was added in 0.0.24 and requires the metatell host to install its trigger bridge. Without it, list() returns [] and operations reject with a TriggerOperationError whose code is "host_unavailable".

Only the -2 trigger family is addressable: active-trigger-2, active-trigger-2d-2, passive-trigger-2, and js-event-trigger-2. These expose stable ids. For single-phase triggers the id is the trigger's Spoke responseNodeId. A passive-trigger-2 has its own trigger id plus a separate responseNodeId for each of enter and exit (see below). Legacy triggers are not listed. There is no silent fallback: an unknown id rejects with TriggerNotFoundError.

Listing triggers

import { list } from "@urth/metatell-sdk/triggers";

for (const trigger of list()) {
  console.log(trigger.id, trigger.type, trigger.enabled);
}
Copy

interface TriggerInfo {
  id: string;
  name?: string;
  type: "active-2" | "active-2d-2" | "passive-2" | "js-event-2";
  enabled: boolean;
  responseNodeIds: Partial<Record<"click" | "enter" | "exit" | "event", string>>;
}
Copy

For the single-phase types (active-2, active-2d-2, js-event-2), id is the trigger's only responseNodeId. A passive-2 trigger has separate enter and exit responses. Its id identifies the trigger as a whole, and responseNodeIds carries one entry per phase. Both id and any value in responseNodeIds can be passed to fire() and setEnabled().

Firing a trigger

import { fire } from "@urth/metatell-sdk/triggers";

await fire("response-node-id");

// passive triggers: choose the enter or exit response
await fire("passive-trigger-id", { phase: "enter" });

// js-event triggers: forward a CustomEvent detail
await fire("js-event-trigger-id", { detail: { score: 10 } });
Copy

interface FireOptions {
  phase?: "enter" | "exit"; // required for passive triggers
  detail?: unknown;         // CustomEvent detail for js-event-trigger-2
  timeoutMs?: number;       // default 5000
}
Copy

Enabling and disabling

Only js-event-2 triggers support this. Other types reject with UnsupportedTriggerOperationError.

import { setEnabled } from "@urth/metatell-sdk/triggers";

await setEnabled("js-event-trigger-id", false);
Copy

setEnabled() accepts { timeoutMs?: number } (default 5000) as its third argument.

Observing fired triggers

onFired() returns an Unsubscribe function; call it on teardown.

import { onFired } from "@urth/metatell-sdk/triggers";

const off = onFired((event) => {
  console.log(event.triggerId, event.phase, event.side);
});
Copy

interface TriggerFiredEvent {
  triggerId: string;
  type: "active-2" | "active-2d-2" | "passive-2" | "js-event-2";
  phase: "click" | "enter" | "exit" | "event";
  side: "local" | "sync-remote";
  isSync: boolean;
  isReplay: boolean;
  name?: string;
  detail?: unknown; // CustomEvent detail forwarded from js-event triggers
}
Copy

Errors

Operations reject with error classes exported from @urth/metatell-sdk/triggers:

Error	Meaning
TriggerNotFoundError	No -2 trigger resolves to that id (error.id).
UnsupportedTriggerOperationError	The trigger type does not support the operation.
TriggerPermissionDeniedError	The host denied the operation.
TriggerOperationError	Any other failure. error.code is "host_unavailable" when no host bridge is installed and "unknown" for timeouts and other failures.

import { TriggerNotFoundError, fire } from "@urth/metatell-sdk/triggers";

try {
  await fire("response-node-id");
} catch (e) {
  if (e instanceof TriggerNotFoundError) {
    // the scene no longer contains this trigger
  }
}
Copy

Related

• Room Objects for spawning and moving media and models.
• Events for the underlying trigger:* events.