Avatar

There are two avatar-related APIs:

• user.changeAvatar(avatarId) — change which avatar the current user wears.
• The Avatar class — observe the current user's avatar transform (position, rotation, quaternion) every frame.

Changing the avatar

import { user } from "@urth/metatell-sdk";
// or: import { changeAvatar } from "@urth/metatell-sdk/user";

user.changeAvatar("your-avatar-id");
Copy

avatarId must be a non-empty string; otherwise the call throws an Error. If the host store is not ready the call is a no-op and logs a warning.

Observing the avatar transform

Create an Avatar and assign onUpdateTransform. The handler receives the current transform on each update.

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

const avatar = new Avatar();

avatar.onUpdateTransform = (transform) => {
  console.log("position", transform.position);
  console.log("rotation", transform.rotation);
  console.log("quaternion", transform.quaternion);
};
Copy

The TransformData shape:

interface TransformData {
  position: Vector3Data;             // { x, y, z }
  rotation: EulerData;               // { x, y, z, order? }
  quaternion: QuaternionData;        // { x, y, z, w }
  scale?: Vector3Data;               // when the host provides it
}
Copy

These types are exported from @urth/metatell-sdk/types/property.

This handler fires frequently (per update). Keep it cheap and avoid heavy work inside it.

Related

• Remote Users for other users' transforms via onTransform.
• User Profile reads the current avatarId as part of the profile.