Events

@urth/metatell-sdk/events is the low-level typed event bus that the higher level modules (user, users, chat, input, voice, emote, objects, triggers, runtime, environment) are built on. Most plugins should prefer those modules; reach for events when you need an event that has no dedicated wrapper, or want to work with the bus directly.

Subscribing

import { on, once, off } from "@urth/metatell-sdk/events";

const unsubscribe = on("chat:message", (message) => {
  console.log(message.text);
});

once("users:join", (user) => {
  console.log("first join", user.profile.displayName);
});

// either call the returned function, or off() with the same handler
unsubscribe();
Copy

• on(event, handler) — subscribe; returns an Unsubscribe.
• once(event, handler) — subscribe for a single delivery.
• off(event, handler) — remove a previously registered handler.

Event map

Events are fully typed: the payload type is inferred from the event name. The EventMap includes (among others):

The onAdded(), onUpdated(), and onMoved() wrappers in Room Objects deliver copies of their payloads. onRemoved() and onFired() in Triggers pass the bus payload through unchanged, so treat it as read-only. Prefer onCapabilitiesChanged() from /runtime and onChanged() from /environment over the raw runtime:changed and environment:changed events: the wrappers validate, order, and fetch full state.

The EventMap also contains internal request/response events that back the wrapper APIs and are not meant to be used directly: chat:send-request / chat:send-result and input:raycast-request / input:raycast-result (behind the promise-based chat and input APIs), emote:trigger-request (behind emote.trigger()), objects:op-request / objects:op-result, trigger:op-request / trigger:op-result, runtime:request / runtime:result, and environment:request / environment:result / environment:release. Prefer the wrapper functions over emitting these yourself. All payload types are exported from @urth/metatell-sdk/events.

Accessing the bus

import { getBus } from "@urth/metatell-sdk/events";

const bus = getBus();
bus.on("emote", (e) => console.log(e.name));
Copy

createBus() is also exported for advanced cases (e.g. tests) that need an isolated bus instance.