@worldmesh/runtime 0.2.1 → 0.2.2

package/src/net/presence.ts

@@ -1,6 +1,12 @@
 import { CanvasTexture, Group, Mesh, MeshBasicMaterial, Sprite, SpriteMaterial, Vector3, type Object3D, type Scene } from 'three';
-import { animateDefaultAvatar, createDefaultAvatar, setAvatarExpression } from '../player/avatar.js';
+import { Footsteps } from '../audio/footsteps.js';
+import { parseAvatarShare, type SignedAvatarShare } from '../avatar/descriptor.js';
+import { loadAvatarModel, type LoadedAvatar } from '../avatar/loader.js';
+import { animateDefaultAvatar, createDefaultAvatar, setAvatarColor, setAvatarExpression } from '../player/avatar.js';
+import { setFigureStroke } from '../player/stroke.js';
 import type { NetworkAdapter, PeerBody, PlayerState, WorldMeshHandle } from '../types.js';
+import { easeYaw } from './follow.js';
+import { isRoomFullSignal, probeRoom } from './roomFull.js';
 
 /** The relay WorldMesh hosts (workers/presence). Worlds can point at their own. */
 export const DEFAULT_PRESENCE_SERVER = 'wss://relay.worldmesh.net';
@@ -14,30 +20,109 @@ export interface PresenceOptions {
   getName?: () => string | null;
   /** Made-up name shown instead of the username in private mode. */
   getAlias?: () => string | null;
+  /** Body colour ('#rrggbb') everyone else draws this visitor in, or null for the default. */
+  getColor?: () => string | null;
+  /**
+   * The avatar everyone else should see this visitor wearing: the link the hub
+   * signed for it (`descriptor.share`), or null for the default body.
+   */
+  getAvatar?: () => SharedAvatar | null;
+  /**
+   * Whether a link someone else sent was signed by the hub (createShareVerifier).
+   * Models are downloaded only when it says yes; without it, everyone else is
+   * drawn in the default body. Throwing means it cannot tell right now (the
+   * hub's key did not load): the link is checked again a minute later.
+   */
+  verifyAvatar?: (share: SharedAvatar) => Promise<boolean>;
+  /** Draw other people in the avatars they wear. Defaults to true. */
+  showAvatars?: boolean;
+  /** Largest avatar model downloaded for someone else. Defaults to 40 MB. */
+  maxAvatarBytes?: number;
   /**
    * Someone new just started walking here, first seen at (x, z). Not called
    * for the people already in the room when this visitor joins.
    */
   onArrive?: (x: number, z: number) => void;
-  /** Called with each remote figure as it is made, e.g. to add an outline. */
+  /** Called with each remote figure as it is made, already outlined. */
   onFigure?: (root: Object3D) => void;
+  /**
+   * Someone in the room left, last seen at (x, z). Return true to keep their
+   * figure in the scene a little longer (to finish an exit effect); hand it
+   * back with `dropFigure` when done. Otherwise it is removed straight away.
+   */
+  onDepart?: (x: number, z: number, root: Object3D) => boolean | void;
+  /**
+   * Where this visitor is listening from. When set, everyone else's footsteps,
+   * jumps and landings are heard, fading with distance and silent far off.
+   */
+  listener?: () => Vector3 | null;
+  /**
+   * The relay refused this join because the room is full. Not used for
+   * ordinary disconnects — those still reconnect in the background.
+   */
+  onFull?: (full: boolean) => void;
+  /**
+   * Shared state of something in the room changed: a lift, a door. Called
+   * for every write in the order the relay took them, this visitor's own
+   * included (`self`), and for the room's remembered state on joining, with
+   * how old it is in seconds (`age`, 0 for live writes).
+   */
+  onShared?: (key: string, value: Record<string, number>, info: { self: boolean; age: number }) => void;
+  /**
+   * Adjust where a remote figure is drawn this frame, after it eased toward
+   * its last reported spot. Lets a world keep someone standing on a moving
+   * platform, which they reported a moment ago from a little lower down.
+   */
+  place?: (position: Vector3, grounded: boolean) => void;
 }
 
+/** An avatar as it goes to everyone else in the room: a link the hub signed. */
+export type SharedAvatar = SignedAvatarShare;
+
 /** How often the local position goes out, per second. */
 const SEND_RATE = 10;
-/** Resend at least this often while standing still, so late joiners see us. */
-const HEARTBEAT_MS = 3000;
+/** The relay takes one avatar change a second per peer; stay under it. */
+const AVATAR_SEND_MS = 1200;
+/** Leeway for clocks that are a little off when checking a link's expiry. */
+const CLOCK_SKEW_MS = 5 * 60_000;
+/**
+ * While standing still, send only a keep-alive this often. The relay answers
+ * it without waking the room, so a room where nobody moves can sleep; late
+ * joiners still see us, as the relay remembers our last position.
+ */
+const KEEPALIVE_MS = 30_000;
+/** After the relay says this world used today's free allowance, try again this much later. */
+const ALLOWANCE_RETRY_MS = 30 * 60_000;
 const MAX_BACKOFF_MS = 30_000;
 
 interface Remote {
+  /** Holds the body, name tag and bubble; moved and turned as one. */
   root: Object3D;
+  /** The default figure, hidden while an avatar of theirs is shown. */
+  body: Object3D;
+  /** The avatar they wear, once downloaded. */
+  external: LoadedAvatar | null;
+  /** Id of the avatar they say they wear, '' for the default body. */
+  avatarId: string;
+  /** Their latest signed link to it. */
+  avatarShare: SharedAvatar | null;
+  /** Download in progress. */
+  avatarLoad: AbortController | null;
+  /** `id url` of the last download that failed, so it is not tried again. */
+  avatarFailed: string;
   target: Vector3;
   targetYaw: number;
   yaw: number;
   /** Smoothed horizontal speed, estimated from how far the avatar moves. */
   speed: number;
+  /** Their footsteps, jumps and landings, when this room hears them. */
+  steps: Footsteps | null;
+  /** Smoothed vertical speed, from how far the avatar rises or falls. */
+  vertical: number;
   /** Standing on something (floor, platform, step) rather than in the air. */
   grounded: boolean;
+  /** Body colour currently applied, '' for the default. */
+  color: string;
   /** Text currently drawn on the tag. */
   label: string;
   tag: Sprite;
@@ -69,10 +154,25 @@ interface PeerState {
   n?: string;
   a?: string;
   g?: number;
+  /** Body colour, '#rrggbb'; '' or absent for the default. */
+  k?: string;
+  /** The avatar they wear (welcome only). */
+  v?: WireAvatar;
+}
+
+/** An avatar on the wire: a signed link (SignedAvatarShare). No `u` means the default body. */
+interface WireAvatar {
+  u?: unknown;
+  f?: unknown;
+  i?: unknown;
+  x?: unknown;
+  s?: unknown;
 }
 
 type ServerMessage =
-  | { t: 'welcome'; id: string; peers: (PeerState & { id: string })[] }
+  | { t: 'welcome'; id: string; peers: (PeerState & { id: string })[]; objects?: { k: string; v: unknown; ms: number }[] }
+  | ({ t: 'v'; id: string } & WireAvatar)
+  | { t: 'o'; id: string; k: string; v: unknown }
   | ({ t: 's'; id: string } & PeerState)
   | { t: 'c'; id: string; m: string }
   | { t: 'leave'; id: string };
@@ -93,28 +193,71 @@ export class Presence implements NetworkAdapter {
   private closed = false;
   private lastSent = 0;
   private lastPayload = '';
-
-  private url: string;
+  private welcomed = false;
+  private full = false;
+  private probeId = 0;
+  /** The over-allowance notice was logged once already. */
+  private allowanceLogged = false;
+  /** This connection has sent a position, so the relay will take an avatar. */
+  private stateSent = false;
+  /** `id url` of the avatar the relay last heard from us; null before anything was sent. */
+  private avatarSent: string | null = null;
+  private avatarSentAt = 0;
+  /** Avatars heard for someone not drawn yet. */
+  private pendingAvatars = new Map<string, WireAvatar>();
+  /** One avatar download at a time, so a busy room does not stall the page. */
+  private avatarQueue: Promise<void> = Promise.resolve();
+  /** Tidies up an avatar left on a figure that is kept after its owner left. */
+  private keptAvatars = new WeakMap<Object3D, LoadedAvatar>();
+
+  readonly url: string;
   private onCount: (count: number | null) => void;
+  private onFull: (full: boolean) => void;
   private getName: () => string | null;
   private getAlias: () => string | null;
+  private getColor: () => string | null;
+  private getAvatar: () => SharedAvatar | null;
+  private showAvatars: boolean;
+  private verifyAvatar: ((share: SharedAvatar) => Promise<boolean>) | null;
+  private maxAvatarBytes: number | undefined;
   private onArrive: (x: number, z: number) => void;
   private onFigure: (root: Object3D) => void;
+  private onDepart: NonNullable<PresenceOptions['onDepart']>;
+  private listener: (() => Vector3 | null) | null;
+  private onShared: NonNullable<PresenceOptions['onShared']>;
+  private place: PresenceOptions['place'];
 
   constructor(options: PresenceOptions) {
     this.url = options.url;
     this.onCount = options.onCount ?? (() => {});
+    this.onFull = options.onFull ?? (() => {});
     this.getName = options.getName ?? (() => null);
     this.getAlias = options.getAlias ?? (() => null);
+    this.getColor = options.getColor ?? (() => null);
+    this.getAvatar = options.getAvatar ?? (() => null);
+    this.showAvatars = options.showAvatars !== false;
+    this.verifyAvatar = options.verifyAvatar ?? null;
+    this.maxAvatarBytes = options.maxAvatarBytes;
     this.onArrive = options.onArrive ?? (() => {});
     this.onFigure = options.onFigure ?? (() => {});
+    this.onDepart = options.onDepart ?? (() => {});
+    this.listener = options.listener ?? null;
+    this.onShared = options.onShared ?? (() => {});
+    this.place = options.place;
     this.group.name = 'worldmesh:remote-players';
     options.scene.add(this.group);
   }
 
+  /** Late-bind the full-room overlay (createWorldMesh wires this after constructing Presence). */
+  setOnFull(handler: (full: boolean) => void): void {
+    this.onFull = handler;
+    if (this.full) handler(true);
+  }
+
   attach(world: WorldMeshHandle): void {
     this.unsubscribe = world.on('update', ({ dt, state }) => {
       this.sendLocalState(state);
+      this.sendAvatar();
       this.update(dt);
     });
     window.addEventListener('pagehide', this.handlePageHide);
@@ -130,12 +273,36 @@ export class Presence implements NetworkAdapter {
     if (now - this.lastSent < 1000 / SEND_RATE) return;
 
     const [x, y, z] = state.position;
-    const payload = JSON.stringify({ t: 's', p: [round(x), round(y), round(z)], r: round(state.facing), e: state.expression, n: this.getName() ?? '', a: this.getAlias() ?? '', g: state.onGround || state.flying ? 1 : 0 });
-    if (payload === this.lastPayload && now - this.lastSent < HEARTBEAT_MS) return;
+    const payload = JSON.stringify({ t: 's', p: [round(x), round(y), round(z)], r: round(state.facing), e: state.expression, n: this.getName() ?? '', a: this.getAlias() ?? '', k: this.getColor() ?? '', g: state.onGround || state.flying ? 1 : 0 });
+    if (payload === this.lastPayload) {
+      if (now - this.lastSent < KEEPALIVE_MS) return;
+      socket.send('ping');
+      this.lastSent = now;
+      return;
+    }
 
     socket.send(payload);
     this.lastPayload = payload;
     this.lastSent = now;
+    this.stateSent = true;
+  }
+
+  /**
+   * Tell the room which avatar this visitor wears, whenever that (or its link)
+   * changes. The relay keeps it for whoever joins later.
+   */
+  private sendAvatar(): void {
+    const socket = this.socket;
+    if (!socket || socket.readyState !== WebSocket.OPEN || !this.selfId || !this.stateSent) return;
+    const avatar = parseAvatarShare(this.getAvatar());
+    const key = avatar ? `${avatar.i} ${avatar.u} ${avatar.x}` : '';
+    // Nothing to say on a fresh connection when there is no avatar.
+    if (key === (this.avatarSent ?? '')) return;
+    const now = performance.now();
+    if (now - this.avatarSentAt < AVATAR_SEND_MS) return;
+    socket.send(JSON.stringify(avatar ? { t: 'v', u: avatar.u, f: avatar.f, i: avatar.i, x: avatar.x, s: avatar.s } : { t: 'v' }));
+    this.avatarSent = key;
+    this.avatarSentAt = now;
   }
 
   /** Say something. Everyone else gets a bubble; this client draws its own. */
@@ -146,6 +313,29 @@ export class Presence implements NetworkAdapter {
     socket.send(JSON.stringify({ t: 'c', m: line }));
   }
 
+  /**
+   * Set shared state everyone in the room sees, e.g. where a lift is going.
+   * Values are flat objects of numbers. The write comes back through
+   * `onShared` like everyone else's. False when not connected.
+   */
+  share(key: string, value: Record<string, number>): boolean {
+    const socket = this.socket;
+    if (!socket || socket.readyState !== WebSocket.OPEN || !this.selfId) return false;
+    socket.send(JSON.stringify({ t: 'o', k: key, v: value }));
+    return true;
+  }
+
+  /** Remove a figure kept by `onDepart` once its exit is over. */
+  dropFigure(root: Object3D): void {
+    const external = this.keptAvatars.get(root);
+    this.keptAvatars.delete(root);
+    if (external) {
+      external.object.removeFromParent();
+      external.dispose();
+    }
+    disposeObject(root);
+  }
+
   /** Everyone else's body where it is drawn, so walking into them stops where they appear to be. */
   bodies(): PeerBody[] {
     const bodies: PeerBody[] = [];
@@ -162,15 +352,22 @@ export class Presence implements NetworkAdapter {
     for (const remote of this.remotes.values()) {
       const before = remote.root.position.clone();
       remote.root.position.lerp(remote.target, blend);
+      this.place?.(remote.root.position, remote.grounded);
 
-      let delta = remote.targetYaw - remote.yaw;
-      delta = Math.atan2(Math.sin(delta), Math.cos(delta));
-      remote.yaw += delta * blend;
+      remote.yaw = easeYaw(remote.yaw, remote.targetYaw, blend);
       remote.root.rotation.y = remote.yaw;
 
       const moved = Math.hypot(remote.root.position.x - before.x, remote.root.position.z - before.z);
       remote.speed += (moved / Math.max(dt, 1e-4) - remote.speed) * blend;
-      animateDefaultAvatar(remote.root, { dt, speed: remote.speed, grounded: remote.grounded });
+      const motion = { dt, speed: remote.speed, grounded: remote.grounded };
+      let footfall: boolean | null = null;
+      if (remote.external) remote.external.animate(motion);
+      else footfall = animateDefaultAvatar(remote.body, motion);
+      if (remote.steps) {
+        remote.vertical = (remote.root.position.y - before.y) / Math.max(dt, 1e-4);
+        remote.steps.loudness = earshot(this.listener?.() ?? null, remote.root.position);
+        remote.steps.update(dt, remote.speed, remote.grounded, footfall, remote.vertical);
+      }
 
       if (remote.bubble) {
         remote.bubbleLeft -= dt;
@@ -195,6 +392,8 @@ export class Presence implements NetworkAdapter {
   rejoin(): void {
     if (this.closed) return;
     window.clearTimeout(this.reconnectTimer);
+    this.probeId += 1;
+    this.leaveFull();
     this.disconnect();
     this.backoff = 1000;
     this.connect();
@@ -221,6 +420,12 @@ export class Presence implements NetworkAdapter {
       return;
     }
     this.socket = socket;
+    this.welcomed = false;
+
+    listenForHandshakeRefuse(socket, (signal) => {
+      if (this.socket !== socket || this.welcomed) return;
+      if (isRoomFullSignal(signal)) this.enterFull();
+    });
 
     socket.addEventListener('message', (event) => {
       if (typeof event.data !== 'string') return;
@@ -233,17 +438,29 @@ export class Presence implements NetworkAdapter {
       this.handleMessage(message);
     });
 
-    socket.addEventListener('close', () => {
+    socket.addEventListener('close', (event) => {
       if (this.socket !== socket) return;
+      const welcomed = this.welcomed;
       this.socket = null;
       this.selfId = null;
+      this.welcomed = false;
       this.clearRemotes();
       this.onCount(null);
-      this.scheduleReconnect();
+      if (this.full) return;
+      if (welcomed) {
+        this.scheduleReconnect();
+        return;
+      }
+      if (isRoomFullSignal({ code: event.code, reason: event.reason })) {
+        this.enterFull();
+        return;
+      }
+      void this.classifyFailedJoin();
     });
   }
 
   private disconnect(): void {
+    this.probeId += 1;
     const socket = this.socket;
     this.socket = null;
     this.selfId = null;
@@ -253,24 +470,89 @@ export class Presence implements NetworkAdapter {
   }
 
   private scheduleReconnect(): void {
-    if (this.closed) return;
+    if (this.closed || this.full) return;
     window.clearTimeout(this.reconnectTimer);
     this.reconnectTimer = window.setTimeout(() => this.connect(), this.backoff);
     this.backoff = Math.min(this.backoff * 2, MAX_BACKOFF_MS);
   }
 
+  private enterFull(): void {
+    if (this.full) return;
+    this.full = true;
+    window.clearTimeout(this.reconnectTimer);
+    this.probeId += 1;
+    const socket = this.socket;
+    this.socket = null;
+    this.selfId = null;
+    this.welcomed = false;
+    socket?.close(1000, 'full');
+    this.clearRemotes();
+    this.onCount(null);
+    this.onFull(true);
+  }
+
+  private leaveFull(): void {
+    if (!this.full) return;
+    this.full = false;
+    this.onFull(false);
+  }
+
+  /** Browser handshakes hide 503; confirm via HTTP before treating this as a network blip. */
+  private async classifyFailedJoin(): Promise<void> {
+    const id = ++this.probeId;
+    const state = await probeRoom(this.url);
+    if (id !== this.probeId || this.closed || this.socket || this.full) return;
+    if (state === 'full') this.enterFull();
+    else if (state === 'allowance') this.waitForAllowance();
+    else this.scheduleReconnect();
+  }
+
+  /**
+   * The shared relay turned this world away for today: stay single-player,
+   * tell the creator once in the console, and look again much later.
+   */
+  private waitForAllowance(): void {
+    if (!this.allowanceLogged) {
+      this.allowanceLogged = true;
+      console.info(
+        "[WorldMesh] This world has used today's free multiplayer allowance on the shared relay, so visitors are single-player until 00:00 UTC. Run your own relay to lift the limit: https://worldmesh.net/connect.md",
+      );
+    }
+    window.clearTimeout(this.reconnectTimer);
+    this.reconnectTimer = window.setTimeout(() => this.connect(), ALLOWANCE_RETRY_MS);
+  }
+
   private handleMessage(message: ServerMessage): void {
     switch (message.t) {
       case 'welcome':
         this.selfId = message.id;
+        this.welcomed = true;
         this.backoff = 1000;
         this.lastPayload = '';
         this.lastSent = 0;
-        for (const peer of message.peers) this.upsert(peer.id, peer, true);
+        this.stateSent = false;
+        this.avatarSent = null;
+        this.avatarSentAt = 0;
+        this.leaveFull();
+        for (const peer of message.peers) {
+          if (peer.v) this.pendingAvatars.set(peer.id, peer.v);
+          this.upsert(peer.id, peer, true);
+        }
+        for (const object of message.objects ?? []) this.shared(object.k, object.v, false, object.ms / 1000);
+        break;
+      case 'o':
+        this.shared(message.k, message.v, message.id === this.selfId, 0);
         break;
       case 's':
         if (message.id !== this.selfId) this.upsert(message.id, message, false);
         break;
+      case 'v': {
+        if (message.id === this.selfId || typeof message.id !== 'string') break;
+        const remote = this.remotes.get(message.id);
+        if (remote) this.wear(remote, message);
+        else this.pendingAvatars.set(message.id, message);
+        break;
+      }
       case 'c': {
         const remote = message.id === this.selfId ? undefined : this.remotes.get(message.id);
         if (remote && typeof message.m === 'string') showBubble(remote, message.m);
@@ -278,14 +560,30 @@ export class Presence implements NetworkAdapter {
       }
       case 'leave': {
         const remote = this.remotes.get(message.id);
-        if (remote) disposeObject(remote.root);
+        if (remote) {
+          const kept = this.onDepart(remote.root.position.x, remote.root.position.z, remote.root) === true;
+          remote.avatarLoad?.abort();
+          remote.avatarLoad = null;
+          if (kept) {
+            dropBubble(remote);
+            if (remote.external) this.keptAvatars.set(remote.root, remote.external);
+          } else disposeRemote(remote);
+        }
         this.remotes.delete(message.id);
+        this.pendingAvatars.delete(message.id);
         break;
       }
     }
     this.onCount(this.remotes.size + 1);
   }
 
+  private shared(key: unknown, value: unknown, self: boolean, age: number): void {
+    if (typeof key !== 'string' || !value || typeof value !== 'object' || Array.isArray(value)) return;
+    const numbers: Record<string, number> = {};
+    for (const [name, v] of Object.entries(value)) if (typeof v === 'number' && Number.isFinite(v)) numbers[name] = v;
+    this.onShared(key, numbers, { self, age: Number.isFinite(age) ? Math.max(0, age) : 0 });
+  }
+
   private upsert(id: string, state: PeerState, snap: boolean): void {
     const { p, r: yaw, e: expression, g } = state;
     if (!Array.isArray(p) || p.length !== 3 || !p.every(Number.isFinite) || !Number.isFinite(yaw)) return;
@@ -293,15 +591,43 @@ export class Presence implements NetworkAdapter {
 
     let remote = this.remotes.get(id);
     if (!remote) {
-      const root = createDefaultAvatar();
+      const root = new Group();
+      root.name = 'worldmesh:remote-player';
+      const body = createDefaultAvatar();
+      root.add(body);
       const tag = createNameTag(GUEST);
       tag.position.y = TAG_HEIGHT;
       root.add(tag);
+      setFigureStroke(root, true);
       this.onFigure(root);
       this.group.add(root);
-      remote = { root, target: new Vector3(p[0], p[1], p[2]), targetYaw: yaw, yaw, speed: 0, grounded: true, label: GUEST, tag, appear: 0, bubble: null, bubbleLeft: 0 };
+      remote = {
+        root,
+        body,
+        external: null,
+        avatarId: '',
+        avatarShare: null,
+        avatarLoad: null,
+        avatarFailed: '',
+        target: new Vector3(p[0], p[1], p[2]),
+        targetYaw: yaw,
+        yaw,
+        speed: 0,
+        steps: this.listener ? new Footsteps() : null,
+        vertical: 0,
+        grounded: true,
+        color: '',
+        label: GUEST,
+        tag,
+        appear: 0,
+        bubble: null,
+        bubbleLeft: 0,
+      };
       this.remotes.set(id, remote);
       setFigureOpacity(root, 0);
+      const pending = this.pendingAvatars.get(id);
+      this.pendingAvatars.delete(id);
+      if (pending) this.wear(remote, pending);
       if (!snap) this.onArrive(p[0], p[2]);
       snap = true;
     }
@@ -311,7 +637,12 @@ export class Presence implements NetworkAdapter {
     remote.grounded = g === 0 || g === 1 ? g === 1 : p[1] < 0.05 || Math.abs(p[1] - remote.target.y) < GROUND_HOLD;
     remote.target.set(p[0], p[1], p[2]);
     remote.targetYaw = yaw;
-    if (typeof expression === 'string') setAvatarExpression(remote.root, expression);
+    if (typeof expression === 'string') setAvatarExpression(remote.body, expression);
+    const color = typeof state.k === 'string' && COLOR.test(state.k) ? state.k.toLowerCase() : '';
+    if (color !== remote.color) {
+      remote.color = color;
+      setAvatarColor(remote.body, color || DEFAULT_COLOR);
+    }
     if (label !== remote.label) {
       remote.label = label;
       disposeObject(remote.tag);
@@ -332,8 +663,96 @@ export class Presence implements NetworkAdapter {
   }
 
   private clearRemotes(): void {
-    for (const remote of this.remotes.values()) disposeObject(remote.root);
+    for (const remote of this.remotes.values()) disposeRemote(remote);
     this.remotes.clear();
+    this.pendingAvatars.clear();
+  }
+
+  /**
+   * Show the avatar someone says they wear, or their default body again.
+   * A new link to the same avatar only replaces the link; it is not reloaded.
+   */
+  private wear(remote: Remote, avatar: WireAvatar): void {
+    const wanted = this.showAvatars && this.verifyAvatar ? parseAvatarShare(avatar) : null;
+    if (!wanted) {
+      if (!remote.avatarId) return;
+      remote.avatarId = '';
+      remote.avatarShare = null;
+      remote.avatarLoad?.abort();
+      remote.avatarLoad = null;
+      takeOffAvatar(remote);
+      return;
+    }
+    const sameAvatar = wanted.i === remote.avatarId;
+    remote.avatarShare = wanted;
+    if (sameAvatar && (remote.external || remote.avatarLoad)) return;
+    if (remote.avatarFailed === `${wanted.i} ${wanted.u} ${wanted.x}`) return;
+    remote.avatarId = wanted.i;
+    remote.avatarLoad?.abort();
+    const load = (remote.avatarLoad = new AbortController());
+    this.avatarQueue = this.avatarQueue.then(() => this.download(remote, load));
+  }
+
+  private async download(remote: Remote, load: AbortController): Promise<void> {
+    const share = remote.avatarShare;
+    if (load.signal.aborted || !share) return;
+    const id = share.i;
+    const failed = (reason: unknown) => {
+      remote.avatarFailed = `${share.i} ${share.u} ${share.x}`;
+      console.warn('[worldmesh] Not showing another player’s avatar; showing the default body.', reason);
+      if (remote.avatarLoad === load) remote.avatarLoad = null;
+    };
+    // Only links the hub signed, and not ones that ran out long ago.
+    if (share.x * 1000 < Date.now() - CLOCK_SKEW_MS) return failed('its link has expired');
+    let vouched = false;
+    try {
+      vouched = !!this.verifyAvatar && (await this.verifyAvatar(share));
+    } catch {
+      // Could not tell just now (the hub's key did not load): not a bad link, so check again later.
+      if (!load.signal.aborted) this.retryLater(remote, load);
+      return;
+    }
+    if (load.signal.aborted) return;
+    if (!vouched) return failed('its link is not signed by the hub');
+    let timedOut = false;
+    const timer = window.setTimeout(() => {
+      timedOut = true;
+      load.abort();
+    }, AVATAR_TIMEOUT_MS);
+    try {
+      const loaded = await loadAvatarModel(
+        { provider: 'peer', avatarId: id, name: null, thumbnail: null, format: share.f, modelUrl: share.u, expiresAt: null, sourceUrl: null },
+        { height: BODY_HEIGHT, maxBytes: this.maxAvatarBytes, signal: load.signal },
+      );
+      if (load.signal.aborted || remote.avatarId !== id) {
+        loaded.dispose();
+        return;
+      }
+      takeOffAvatar(remote);
+      loaded.object.userData[EXTERNAL_KEY] = true;
+      remote.root.add(loaded.object);
+      remote.body.visible = false;
+      remote.external = loaded;
+    } catch (error) {
+      if (load.signal.aborted && !timedOut) return;
+      remote.avatarFailed = `${share.i} ${share.u} ${share.x}`;
+      console.warn('[worldmesh] Could not load another player’s avatar; showing the default body.', error);
+    } finally {
+      window.clearTimeout(timer);
+      if (remote.avatarLoad === load) remote.avatarLoad = null;
+    }
+  }
+
+  /**
+   * Download their avatar again in a while, with whatever link they sent by
+   * then. Called off when the download is (they left or changed avatar).
+   */
+  private retryLater(remote: Remote, load: AbortController): void {
+    const timer = window.setTimeout(() => {
+      if (load.signal.aborted || remote.avatarLoad !== load) return;
+      this.avatarQueue = this.avatarQueue.then(() => this.download(remote, load));
+    }, AVATAR_RETRY_MS);
+    load.signal.addEventListener('abort', () => window.clearTimeout(timer), { once: true });
   }
 
   // Leave the room promptly when the tab navigates away (e.g. through a door),
@@ -355,19 +774,103 @@ function round(value: number): number {
   return Math.round(value * 100) / 100;
 }
 
+/** Give up on someone else's avatar download after this long. */
+const AVATAR_TIMEOUT_MS = 60_000;
+/** Check someone's link again after this long when the hub's key could not be had. */
+const AVATAR_RETRY_MS = 60_000;
+/** Marks the root of a downloaded avatar on a remote figure. */
+const EXTERNAL_KEY = 'worldmeshExternal';
+
+/** Back to the default body. */
+function takeOffAvatar(remote: Remote): void {
+  const external = remote.external;
+  if (!external) return;
+  external.object.removeFromParent();
+  external.dispose();
+  remote.external = null;
+  remote.body.visible = true;
+}
+
+function disposeRemote(remote: Remote): void {
+  remote.avatarLoad?.abort();
+  remote.avatarLoad = null;
+  takeOffAvatar(remote);
+  disposeObject(remote.root);
+}
+
+/** Every object under `root`, except inside downloaded avatars, whose own materials are left as they are. */
+function eachOwnPart(root: Object3D, visit: (child: Object3D) => void): void {
+  visit(root);
+  for (const child of root.children) {
+    if (child.userData[EXTERNAL_KEY] === true) continue;
+    eachOwnPart(child, visit);
+  }
+}
+
+/**
+ * Node's `ws` package emits `unexpected-response` with the HTTP status when
+ * the upgrade is refused. Browsers only get a generic `error` / close 1006.
+ */
+function listenForHandshakeRefuse(
+  socket: WebSocket,
+  onRefuse: (signal: { status?: number; message?: string; body?: string }) => void,
+): void {
+  socket.addEventListener('error', (event) => {
+    const err = event as ErrorEvent & { error?: { message?: string } };
+    const message = err.message || err.error?.message;
+    if (isRoomFullSignal({ message })) onRefuse({ message });
+  });
+  const nodeSocket = socket as WebSocket & {
+    on?(event: string, listener: (...args: unknown[]) => void): void;
+  };
+  nodeSocket.on?.('unexpected-response', (...args: unknown[]) => {
+    const res = args[1] as NodeHandshakeResponse | undefined;
+    if (!res) return;
+    const chunks: Uint8Array[] = [];
+    res.on?.('data', (chunk) => {
+      chunks.push(typeof chunk === 'string' ? new TextEncoder().encode(chunk) : chunk);
+    });
+    res.on?.('end', () => {
+      onRefuse({ status: res.statusCode, body: new TextDecoder().decode(concatBytes(chunks)) });
+    });
+    if (!res.on) onRefuse({ status: res.statusCode });
+  });
+}
+
+interface NodeHandshakeResponse {
+  statusCode?: number;
+  on?(event: string, listener: (chunk: string | Uint8Array) => void): void;
+}
+
+function concatBytes(chunks: Uint8Array[]): Uint8Array {
+  const size = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0);
+  const out = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return out;
+}
+
 /** How long a newly appeared figure takes to go from transparent to opaque. */
 const APPEAR_FADE = 0.55;
 
 const GUEST = 'Guest';
 
+/** What a body colour must look like on the wire. */
+const COLOR = /^#[0-9a-f]{6}$/i;
+/** The default avatar's own colour, for a peer that goes back to it. */
+const DEFAULT_COLOR = '#ffffff';
+
 /** Ease every mesh on an avatar toward a shared opacity. */
 function setFigureOpacity(root: Object3D, amount: number): void {
   const solid = amount >= 0.999;
   let outlined = false;
-  root.traverse((child) => {
+  eachOwnPart(root, (child) => {
     if (child instanceof Mesh && child.userData.stroke === true) outlined = true;
   });
-  root.traverse((child) => {
+  eachOwnPart(root, (child) => {
     if (!(child instanceof Mesh)) return;
     for (const material of Array.isArray(child.material) ? child.material : [child.material]) {
       const stroke = material.userData.stroke === true;
@@ -419,8 +922,8 @@ function dropBubble(remote: Remote): void {
   remote.bubble = null;
 }
 
-/** A white speech bubble. One line, cut off if they wrote a novel. */
-function createSpeechBubble(text: string): Sprite {
+/** A white speech bubble. One line, cut off if they wrote a novel. Its bottom edge sits at the sprite's position. */
+export function createSpeechBubble(text: string): Sprite {
   const scale = 2;
   const font = `600 ${20 * scale}px system-ui, -apple-system, sans-serif`;
   const canvas = document.createElement('canvas');
@@ -452,7 +955,11 @@ function createSpeechBubble(text: string): Sprite {
   return sprite;
 }
 
-function createNameTag(text: string): Sprite {
+/**
+ * The tag drawn over another player's head, as on the relay. 'Guest' is drawn
+ * dimmer. Centred on its position; the relay puts it 2.15 m above the feet.
+ */
+export function createNameTag(text: string): Sprite {
   const scale = 2; // Canvas pixels per CSS pixel, for crisp text.
   const font = `600 ${22 * scale}px system-ui, -apple-system, sans-serif`;
   const canvas = document.createElement('canvas');
@@ -482,6 +989,19 @@ function createNameTag(text: string): Sprite {
   return sprite;
 }
 
+/** Footsteps are heard this far away at most, in metres. */
+const EARSHOT = 30;
+
+/** How loud someone at `source` is to a listener: full beside them, half at 8 m, nothing past earshot. */
+function earshot(listener: Vector3 | null, source: Vector3): number {
+  if (!listener) return 0;
+  const distance = listener.distanceTo(source);
+  if (distance >= EARSHOT) return 0;
+  // Eased to zero at the edge so walking out of earshot does not cut a step off.
+  const edge = 1 - distance / EARSHOT;
+  return (1 / (1 + distance / 8)) * Math.min(1, edge * 4);
+}
+
 function disposeObject(root: Object3D): void {
   root.traverse((child) => {
     if (child instanceof Sprite) {