@worldmesh/runtime 0.2.0 → 0.2.2

package/dist/net/presence.js

@@ -1,11 +1,27 @@
 import { CanvasTexture, Group, Mesh, MeshBasicMaterial, Sprite, SpriteMaterial, Vector3 } from 'three';
-import { animateDefaultAvatar, createDefaultAvatar, setAvatarExpression } from '../player/avatar.js';
+import { Footsteps } from '../audio/footsteps.js';
+import { parseAvatarShare } from '../avatar/descriptor.js';
+import { loadAvatarModel } from '../avatar/loader.js';
+import { animateDefaultAvatar, createDefaultAvatar, setAvatarColor, setAvatarExpression } from '../player/avatar.js';
+import { setFigureStroke } from '../player/stroke.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://worldmesh-presence.elias-willnat.workers.dev';
+export const DEFAULT_PRESENCE_SERVER = 'wss://relay.worldmesh.net';
 /** 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;
 /**
  * For peers that do not send `g`: a height change smaller than this between
@@ -33,25 +49,68 @@ export class Presence {
     closed = false;
     lastSent = 0;
     lastPayload = '';
+    welcomed = false;
+    full = false;
+    probeId = 0;
+    /** The over-allowance notice was logged once already. */
+    allowanceLogged = false;
+    /** This connection has sent a position, so the relay will take an avatar. */
+    stateSent = false;
+    /** `id url` of the avatar the relay last heard from us; null before anything was sent. */
+    avatarSent = null;
+    avatarSentAt = 0;
+    /** Avatars heard for someone not drawn yet. */
+    pendingAvatars = new Map();
+    /** One avatar download at a time, so a busy room does not stall the page. */
+    avatarQueue = Promise.resolve();
+    /** Tidies up an avatar left on a figure that is kept after its owner left. */
+    keptAvatars = new WeakMap();
     url;
     onCount;
+    onFull;
     getName;
     getAlias;
+    getColor;
+    getAvatar;
+    showAvatars;
+    verifyAvatar;
+    maxAvatarBytes;
     onArrive;
     onFigure;
+    onDepart;
+    listener;
+    onShared;
+    place;
     constructor(options) {
         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) {
+        this.onFull = handler;
+        if (this.full)
+            handler(true);
+    }
     attach(world) {
         this.unsubscribe = world.on('update', ({ dt, state }) => {
             this.sendLocalState(state);
+            this.sendAvatar();
             this.update(dt);
         });
         window.addEventListener('pagehide', this.handlePageHide);
@@ -66,12 +125,38 @@ export class Presence {
         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)
+        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.
+     */
+    sendAvatar() {
+        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. */
     say(text) {
@@ -81,6 +166,28 @@ export class Presence {
             return;
         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, value) {
+        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) {
+        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() {
         const bodies = [];
@@ -96,13 +203,22 @@ export class Presence {
         for (const remote of this.remotes.values()) {
             const before = remote.root.position.clone();
             remote.root.position.lerp(remote.target, blend);
-            let delta = remote.targetYaw - remote.yaw;
-            delta = Math.atan2(Math.sin(delta), Math.cos(delta));
-            remote.yaw += delta * blend;
+            this.place?.(remote.root.position, remote.grounded);
+            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 = 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;
                 remote.bubble.material.opacity = remote.bubbleLeft < 1 ? Math.max(0, remote.bubbleLeft) : 1;
@@ -126,6 +242,8 @@ export class Presence {
         if (this.closed)
             return;
         window.clearTimeout(this.reconnectTimer);
+        this.probeId += 1;
+        this.leaveFull();
         this.disconnect();
         this.backoff = 1000;
         this.connect();
@@ -151,6 +269,13 @@ export class Presence {
             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;
@@ -163,17 +288,30 @@ export class Presence {
             }
             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();
         });
     }
     disconnect() {
+        this.probeId += 1;
         const socket = this.socket;
         this.socket = null;
         this.selfId = null;
@@ -182,26 +320,95 @@ export class Presence {
         this.onCount(null);
     }
     scheduleReconnect() {
-        if (this.closed)
+        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);
     }
+    enterFull() {
+        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);
+    }
+    leaveFull() {
+        if (!this.full)
+            return;
+        this.full = false;
+        this.onFull(false);
+    }
+    /** Browser handshakes hide 503; confirm via HTTP before treating this as a network blip. */
+    async classifyFailedJoin() {
+        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.
+     */
+    waitForAllowance() {
+        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);
+    }
     handleMessage(message) {
         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.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')
@@ -210,14 +417,34 @@ export class Presence {
             }
             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);
     }
+    shared(key, value, self, age) {
+        if (typeof key !== 'string' || !value || typeof value !== 'object' || Array.isArray(value))
+            return;
+        const numbers = {};
+        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 });
+    }
     upsert(id, state, snap) {
         const { p, r: yaw, e: expression, g } = state;
         if (!Array.isArray(p) || p.length !== 3 || !p.every(Number.isFinite) || !Number.isFinite(yaw))
@@ -225,15 +452,44 @@ export class Presence {
         const label = nameLabel(state.n, state.a);
         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;
@@ -245,7 +501,12 @@ export class Presence {
         remote.target.set(p[0], p[1], p[2]);
         remote.targetYaw = yaw;
         if (typeof expression === 'string')
-            setAvatarExpression(remote.root, expression);
+            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);
@@ -266,8 +527,105 @@ export class Presence {
     }
     clearRemotes() {
         for (const remote of this.remotes.values())
-            disposeObject(remote.root);
+            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.
+     */
+    wear(remote, avatar) {
+        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));
+    }
+    async download(remote, load) {
+        const share = remote.avatarShare;
+        if (load.signal.aborted || !share)
+            return;
+        const id = share.i;
+        const failed = (reason) => {
+            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).
+     */
+    retryLater(remote, load) {
+        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),
     // and rejoin if the browser restores the page from its back/forward cache.
@@ -285,18 +643,90 @@ export class Presence {
 function round(value) {
     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) {
+    const external = remote.external;
+    if (!external)
+        return;
+    external.object.removeFromParent();
+    external.dispose();
+    remote.external = null;
+    remote.body.visible = true;
+}
+function disposeRemote(remote) {
+    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, visit) {
+    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, onRefuse) {
+    socket.addEventListener('error', (event) => {
+        const err = event;
+        const message = err.message || err.error?.message;
+        if (isRoomFullSignal({ message }))
+            onRefuse({ message });
+    });
+    const nodeSocket = socket;
+    nodeSocket.on?.('unexpected-response', (...args) => {
+        const res = args[1];
+        if (!res)
+            return;
+        const chunks = [];
+        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 });
+    });
+}
+function concatBytes(chunks) {
+    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, amount) {
     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]) {
@@ -348,8 +778,8 @@ function dropBubble(remote) {
     bubble.removeFromParent();
     remote.bubble = null;
 }
-/** A white speech bubble. One line, cut off if they wrote a novel. */
-function createSpeechBubble(text) {
+/** 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) {
     const scale = 2;
     const font = `600 ${20 * scale}px system-ui, -apple-system, sans-serif`;
     const canvas = document.createElement('canvas');
@@ -378,7 +808,11 @@ function createSpeechBubble(text) {
     sprite.center.set(0.5, 0);
     return sprite;
 }
-function createNameTag(text) {
+/**
+ * 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) {
     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');
@@ -405,6 +839,19 @@ function createNameTag(text) {
     sprite.name = 'worldmesh:name-tag';
     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, source) {
+    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) {
     root.traverse((child) => {
         if (child instanceof Sprite) {