Remote Users

@urth/metatell-sdk/users exposes the other users present in the room (presence). Use it to render nameplates, track who joins and leaves, or react to who is speaking.

For the current user (self), use @urth/metatell-sdk/user instead; see User Profile.

Reading the current roster

import { list, get } from "@urth/metatell-sdk/users";

const everyone = list();              // RemoteUser[]
const someone = get("session-id");    // RemoteUser | undefined
Copy

A RemoteUser has the following shape:

interface RemoteUser {
  sessionId: string;
  userId?: string;
  profile: UserProfile;        // { displayName, avatarId?, roles? }
  speaking: boolean;
  transform?: TransformData;   // position / rotation / quaternion
}
Copy

Users are keyed by sessionId, which is stable for the duration of a session.

Subscribing to presence events

Every subscription returns an Unsubscribe function; call it on teardown.

import {
  onJoin,
  onLeave,
  onUpdate,
  onSpeaking,
  onTransform,
} from "@urth/metatell-sdk/users";

const offs = [
  onJoin((u) => console.log("joined", u.profile.displayName)),
  onLeave(({ sessionId }) => console.log("left", sessionId)),
  onUpdate((u) => console.log("profile changed", u.profile.displayName)),
  onSpeaking((e) => console.log(e.sessionId, e.speaking, e.level)),
  onTransform((e) => moveNameplate(e.sessionId, e.transform)),
];

function teardown() {
  for (const off of offs) off();
}
Copy

• onJoin / onLeave — a user enters or leaves the room.
• onUpdate — a user's profile (display name, avatar) changes.
• onSpeaking — a user starts or stops speaking, with a level.
• onTransform — a user's position/rotation updates. This can fire frequently; keep the handler cheap.

Related

• Voice for the current user's own speaking level.
• Events for the underlying typed event bus.