@worldmesh/runtime 0.2.1 → 0.2.3

package/src/net/roomFull.ts

@@ -0,0 +1,160 @@
+/**
+ * The relay refuses a full room with HTTP 503 and the body "Room is full"
+ * before the WebSocket upgrade. Browsers do not expose that status on a failed
+ * handshake (close is usually 1006 with an empty reason). Node's `ws` package
+ * can surface it via `unexpected-response`. These helpers classify both.
+ */
+
+/** Close / HTTP / error shapes that mean the relay refused a full room. */
+export function isRoomFullSignal(signal: {
+  status?: number;
+  code?: number;
+  reason?: string;
+  message?: string;
+  body?: string;
+} | null | undefined): boolean {
+  if (!signal) return false;
+  if (signal.status === 503) return true;
+  const text = [signal.reason, signal.message, signal.body].filter((part) => typeof part === 'string').join(' ');
+  return /room is full/i.test(text);
+}
+
+/** Copy on the full-screen overlay. Named rooms (the hub lobby) vs world rooms. */
+export function roomFullLabel(wsUrl: string): string {
+  try {
+    if (/^\/room\//i.test(new URL(wsUrl).pathname)) return 'Lobby is full';
+  } catch {
+    // Fall through to the world wording.
+  }
+  return 'World is full';
+}
+
+export function presenceHttpUrl(wsUrl: string): string {
+  return wsUrl.replace(/^ws/i, 'http');
+}
+
+/** GET /occupancy query for this Presence URL (named room or this page's world). */
+export function occupancyProbeUrl(wsUrl: string, pageOrigin?: string): string | null {
+  try {
+    const url = new URL(presenceHttpUrl(wsUrl));
+    const room = url.pathname.match(/^\/room\/([a-z0-9-]{1,64})$/i);
+    if (room) {
+      url.pathname = '/occupancy';
+      url.search = `rooms=${encodeURIComponent(room[1].toLowerCase())}`;
+      return url.toString();
+    }
+    if (/\/world\/?$/i.test(url.pathname)) {
+      const origin = pageOrigin || (typeof location !== 'undefined' ? location.origin : '');
+      if (!origin) return null;
+      url.pathname = '/occupancy';
+      url.search = `origins=${encodeURIComponent(origin)}`;
+      return url.toString();
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+export function occupancyIsFull(payload: unknown, wsUrl: string, pageOrigin?: string): boolean {
+  if (!payload || typeof payload !== 'object') return false;
+  const data = payload as Record<string, unknown>;
+  let key: string | null = null;
+  try {
+    const path = new URL(wsUrl).pathname;
+    const room = path.match(/^\/room\/([a-z0-9-]{1,64})$/i);
+    if (room) key = `room:${room[1].toLowerCase()}`;
+    else {
+      const origin = (pageOrigin || (typeof location !== 'undefined' ? location.origin : '')).toLowerCase();
+      key = origin || null;
+    }
+  } catch {
+    return false;
+  }
+  if (!key) return false;
+  const entry = data[key];
+  if (!entry || typeof entry !== 'object') return false;
+  const { count, cap } = entry as { count?: unknown; cap?: unknown };
+  return atCapacity(count, cap);
+}
+
+function atCapacity(count: unknown, cap: unknown): boolean {
+  return (
+    typeof count === 'number' &&
+    typeof cap === 'number' &&
+    Number.isFinite(count) &&
+    Number.isFinite(cap) &&
+    cap > 0 &&
+    count >= cap
+  );
+}
+
+export type ProbeFetch = (
+  input: string,
+  init?: { method?: string; headers?: Record<string, string> },
+) => Promise<Response>;
+
+/**
+ * The shared relay turns a world away for the rest of the UTC day once its
+ * room has used the free daily allowance: HTTP 429 with "allowance" in the
+ * body. A plain 429 ("Too many requests") is only a short rate limit.
+ */
+export function isOverAllowanceSignal(signal: { status?: number; body?: string } | null | undefined): boolean {
+  return signal?.status === 429 && /allowance/i.test(signal.body ?? '');
+}
+
+/** Why a join was refused: the room is full, the world is past today's allowance, or neither (a network blip). */
+export type RoomProbe = 'full' | 'allowance' | 'open';
+
+/**
+ * After a handshake that never welcomed us, ask the relay why. Same-path GET
+ * (no Upgrade) is the browser stand-in for the refused upgrade; GET
+ * /occupancy covers older relays and Node callers that omit Origin.
+ */
+export async function probeRoom(
+  wsUrl: string,
+  pageOrigin?: string,
+  fetchFn: ProbeFetch = fetch as ProbeFetch,
+): Promise<RoomProbe> {
+  const origin = pageOrigin || (typeof location !== 'undefined' ? location.origin : undefined);
+  const headers: Record<string, string> = { Accept: 'text/plain, application/json' };
+  if (origin) headers.Origin = origin;
+
+  try {
+    const direct = await fetchFn(presenceHttpUrl(wsUrl), { method: 'GET', headers });
+    const text = await direct.text();
+    if (isRoomFullSignal({ status: direct.status, body: text })) return 'full';
+    if (isOverAllowanceSignal({ status: direct.status, body: text })) return 'allowance';
+    if (direct.ok) {
+      try {
+        const json = JSON.parse(text) as { count?: unknown; cap?: unknown };
+        if (atCapacity(json.count, json.cap)) return 'full';
+      } catch {
+        // Not occupancy JSON (e.g. the old 426 body).
+      }
+    }
+  } catch {
+    // Fall through to /occupancy.
+  }
+
+  const occupancyUrl = occupancyProbeUrl(wsUrl, origin);
+  if (!occupancyUrl) return 'open';
+  try {
+    const res = await fetchFn(occupancyUrl, { method: 'GET', headers: { Accept: 'application/json' } });
+    const text = await res.text();
+    if (isRoomFullSignal({ status: res.status, body: text })) return 'full';
+    if (!res.ok) return 'open';
+    return occupancyIsFull(JSON.parse(text), wsUrl, origin) ? 'full' : 'open';
+  } catch {
+    return 'open';
+  }
+}
+
+/** probeRoom, answering only whether the room is full. */
+export async function probeRoomFull(
+  wsUrl: string,
+  pageOrigin?: string,
+  fetchFn: ProbeFetch = fetch as ProbeFetch,
+): Promise<boolean> {
+  return (await probeRoom(wsUrl, pageOrigin, fetchFn)) === 'full';
+}

package/src/player/avatar.ts

@@ -14,6 +14,7 @@ import {
   SplineCurve,
   SRGBColorSpace,
   Vector2,
+  Vector3,
   type BufferGeometry,
   type Object3D,
 } from 'three';
@@ -100,20 +101,38 @@ function toonSteps(shadow: string, light: string): CanvasTexture {
 }
 
 const APPEAR_KEY = 'worldmeshAppear';
+const APPEAR_AXIS_KEY = 'worldmeshAppearAxis';
+const UP = new Vector3(0, 1, 0);
 
 /**
- * Scatter the surface into points that fill in as `uFill` goes from 0 to 1.
- * Materials on one figure share a uniform so the body and face appear together.
+ * Warp the surface along an axis (up and down unless told otherwise) and fade
+ * it in as `uFill` goes from 0 to 1. Materials on one figure share uniforms so
+ * the body and face appear together. Runs after any shader changes the
+ * material already makes (a VRM's MToon has its own).
  */
-function attachAppear(material: Material, shared?: { value: number }): { value: number } {
-  const fill = shared ?? { value: 1 };
+function attachAppear(
+  material: Material,
+  shared?: { fill: { value: number }; axis: { value: Vector3 } },
+): { fill: { value: number }; axis: { value: Vector3 } } {
+  const fill = shared?.fill ?? { value: 1 };
+  const axis = shared?.axis ?? { value: UP.clone() };
   material.userData[APPEAR_KEY] = fill;
-  material.customProgramCacheKey = () => 'worldmesh-appear';
-  material.onBeforeCompile = (shader) => {
+  material.userData[APPEAR_AXIS_KEY] = axis;
+  const ownKey = material.customProgramCacheKey;
+  const ownCompile = material.onBeforeCompile;
+  material.customProgramCacheKey = () => `${ownKey.call(material)}|worldmesh-appear`;
+  material.onBeforeCompile = (shader, renderer) => {
+    ownCompile.call(material, shader, renderer);
+    // A shader without these hooks is left as it is: it just appears without the warp.
+    const hooks = ['#include <common>', '#include <begin_vertex>'].every((hook) => shader.vertexShader.includes(hook)) &&
+      ['#include <common>', '#include <dithering_fragment>'].every((hook) => shader.fragmentShader.includes(hook));
+    if (!hooks) return;
     shader.uniforms.uFill = fill;
+    shader.uniforms.uAppearAxis = axis;
     const appearFns = `
 varying vec3 vAppearPos;
 uniform float uFill;
+uniform vec3 uAppearAxis;
 float appearHash(vec3 p) {
   p = fract(p * vec3(443.897, 441.423, 437.195));
   p += dot(p, p.yzx + 19.19);
@@ -122,17 +141,26 @@ float appearHash(vec3 p) {
 float appearNoise(vec3 p) {
   return appearHash(p) * 0.65 + appearHash(p * 2.7 + 4.2) * 0.35;
 }`;
+    // The shift is picked from the rest pose but added after skinning: added
+    // before, every bone would turn it with its own rotation (a T-posed arm
+    // hanging down throws it sideways) instead of it running along the axis.
+    const shift = 'transformed += (inverse(modelMatrix) * vec4(uAppearAxis * appearShift, 0.0)).xyz;';
+    const skinned = shader.vertexShader.includes('#include <skinning_vertex>');
     shader.vertexShader = shader.vertexShader
       .replace('#include <common>', `#include <common>\n${appearFns}`)
       .replace(
         '#include <begin_vertex>',
         `#include <begin_vertex>
-float appearWarp = 1.0 - uFill;
+// Eased so the warp stays strong for longer before it settles.
+float appearWarp = pow(1.0 - uFill, 0.6);
 vec3 appearWorld = (modelMatrix * vec4(position, 1.0)).xyz;
-float appearShift = (appearNoise(appearWorld * 5.5) * 2.0 - 1.0) * 0.38 * appearWarp;
-transformed += (inverse(modelMatrix) * vec4(0.0, appearShift, 0.0, 0.0)).xyz;
-vAppearPos = appearWorld;`,
+float appearShift = (appearNoise(appearWorld * 5.5) * 2.0 - 1.0) * 1.1 * appearWarp;
+vAppearPos = appearWorld;
+${skinned ? '' : shift}`,
       );
+    if (skinned) {
+      shader.vertexShader = shader.vertexShader.replace('#include <skinning_vertex>', `#include <skinning_vertex>\n${shift}`);
+    }
     shader.fragmentShader = shader.fragmentShader
       .replace(
         '#include <common>',
@@ -141,11 +169,29 @@ ${appearFns}`,
       )
       .replace(
         '#include <dithering_fragment>',
-        `if (uFill < 0.999 && appearHash(floor(vAppearPos * 70.0)) > uFill) discard;
-#include <dithering_fragment>`,
+        `#include <dithering_fragment>
+// Fades from invisible to solid over the whole warp.
+gl_FragColor.a *= uFill * uFill * (3.0 - 2.0 * uFill);`,
       );
   };
-  return fill;
+  return { fill, axis };
+}
+
+/**
+ * Give a loaded avatar (VRM or glTF) the same appear warp as the default body,
+ * so setAvatarAppear can bring it in. Settled (solid) to begin with.
+ */
+export function attachAvatarAppear(root: Object3D): void {
+  let shared: { fill: { value: number }; axis: { value: Vector3 } } | undefined;
+  root.traverse((child) => {
+    const mesh = child as Mesh;
+    if (!mesh.isMesh) return;
+    for (const material of Array.isArray(mesh.material) ? mesh.material : [mesh.material]) {
+      // Meshes can share a material: warp it once.
+      if (material.userData[APPEAR_KEY]) continue;
+      shared = attachAppear(material, shared);
+    }
+  });
 }
 
 /** Tint a default avatar. Custom bodies are left alone. */
@@ -164,8 +210,11 @@ export function setAvatarColor(root: Object3D, color: string): boolean {
   return found;
 }
 
-/** Drive the point-fill on a default avatar. Returns false for anything else. */
-export function setAvatarAppear(root: Object3D, amount: number): boolean {
+/**
+ * Drive the point-fill on a default avatar or a loaded one. The surface warps
+ * along `axis` (a world direction; up by default). Returns false for anything else.
+ */
+export function setAvatarAppear(root: Object3D, amount: number, axis: { x: number; y: number; z: number } = UP): boolean {
   let found = false;
   root.traverse((child) => {
     const mesh = child as Mesh;
@@ -175,6 +224,15 @@ export function setAvatarAppear(root: Object3D, amount: number): boolean {
       const fill = material.userData[APPEAR_KEY] as { value: number } | undefined;
       if (!fill) continue;
       fill.value = amount;
+      (material.userData[APPEAR_AXIS_KEY] as { value: Vector3 } | undefined)?.value.set(axis.x, axis.y, axis.z);
+      // Blend only while fading in, so a settled figure draws as before.
+      // The face decal is always see-through; keep that.
+      material.userData.appearTransparent ??= material.transparent;
+      const blend = amount < 0.999 || material.userData.appearTransparent === true;
+      if (material.transparent !== blend) {
+        material.transparent = blend;
+        material.needsUpdate = true;
+      }
       found = true;
     }
   });
@@ -300,11 +358,13 @@ export function getAvatarExpression(avatar: Object3D): AvatarExpression | null {
 /**
  * Swing the limbs of an avatar made by `createDefaultAvatar`. Call once per
  * frame with how fast it is moving; anything else is ignored, so it is safe
- * to call on custom avatars too.
+ * to call on custom avatars too. Returns true on the frame a foot lands,
+ * false otherwise, and null when `avatar` is not a default avatar.
  */
-export function animateDefaultAvatar(avatar: Object3D, motion: AvatarMotion): void {
+export function animateDefaultAvatar(avatar: Object3D, motion: AvatarMotion): boolean | null {
   const rig = avatar.userData[RIG_KEY] as AvatarRig | undefined;
-  if (!rig || motion.dt <= 0) return;
+  if (!rig) return null;
+  if (motion.dt <= 0) return false;
 
   const blend = 1 - Math.exp(-motion.dt * 10);
   const walking = motion.grounded ? MathUtils.clamp(motion.speed / 4.5, 0, 1) : 0;
@@ -312,6 +372,7 @@ export function animateDefaultAvatar(avatar: Object3D, motion: AvatarMotion): vo
   rig.air += ((motion.grounded ? 0 : 1) - rig.air) * blend;
 
   // Steps get longer, not just faster, as speed rises.
+  const before = footfalls(rig.phase);
   rig.phase += motion.dt * (4 + motion.speed * 1.2) * (rig.stride > 0.01 ? 1 : 0);
   const swing = Math.sin(rig.phase) * 0.75 * rig.stride;
 
@@ -324,6 +385,8 @@ export function animateDefaultAvatar(avatar: Object3D, motion: AvatarMotion): vo
 
   rig.torso.position.y = Math.abs(Math.cos(rig.phase)) * 0.045 * rig.stride;
   rig.head.rotation.z = Math.sin(rig.phase) * 0.04 * rig.stride;
+  // A foot lands where the legs are furthest apart and the body is lowest.
+  const landed = motion.grounded && rig.stride > 0.15 && footfalls(rig.phase) !== before;
 
   rig.blinkTimer -= motion.dt;
   if (rig.blinkTimer <= 0) {
@@ -331,6 +394,12 @@ export function animateDefaultAvatar(avatar: Object3D, motion: AvatarMotion): vo
     rig.blinkTimer = rig.blinking ? 0.12 : nextBlink();
     rig.face.map = faceTexture(rig.expression, rig.blinking);
   }
+  return landed;
+}
+
+/** How many footfalls a walk cycle at `phase` has passed: one per half turn, offset to the widest stance. */
+function footfalls(phase: number): number {
+  return Math.floor((phase - Math.PI / 2) / Math.PI);
 }
 
 function nextBlink(): number {

package/src/player/player.ts

@@ -1,6 +1,7 @@
 import { Group, Mesh, Object3D, type Vector3 } from 'three';
 import type { LoadedAvatar } from '../avatar/loader.js';
 import type { PlayerOptions } from '../types.js';
+import { setFigureStroke } from './stroke.js';
 import {
   animateDefaultAvatar,
   createDefaultAvatar,
@@ -51,6 +52,8 @@ export class Player {
     this.isDefaultAvatar = !options.avatar;
 
     const body = options.avatar ?? createDefaultAvatar(options.height);
+    // The default figure always wears its ink outline, in the hub and every world alike.
+    if (this.isDefaultAvatar) setFigureStroke(body, true);
     this.root.add(body as Object3D);
     this.baseBody = body;
   }
@@ -86,24 +89,30 @@ export class Player {
     if (this.baseBody) this.baseBody.visible = true;
   }
 
-  /** Place the avatar at the player's feet, facing `yaw`, and animate it for `motion`. */
-  sync(feet: Vector3, yaw: number, currentHeight: number, motion?: AvatarMotion, freeLook = false): void {
+  /**
+   * Place the avatar at the player's feet, facing `yaw`, and animate it for `motion`.
+   * Says whether a foot landed this frame, or null when the avatar's walk is
+   * not one the runtime animates and so cannot tell.
+   */
+  sync(feet: Vector3, yaw: number, currentHeight: number, motion?: AvatarMotion, freeLook = false): boolean | null {
     if (!freeLook) this.facing = yaw;
     else if (motion && motion.speed > 0.3 && motion.heading !== undefined) {
       let delta = motion.heading - this.facing;
       delta = Math.atan2(Math.sin(delta), Math.cos(delta));
       this.facing += delta * (1 - Math.exp(-12 * motion.dt));
     }
-    if (!this.root) return;
+    if (!this.root) return null;
     this.root.position.copy(feet);
     this.root.rotation.y = this.facing;
     if (this.external) {
       if (motion) this.external.animate(motion);
+      return null;
     } else if (this.isDefaultAvatar) {
       // Squash the default body while crouching instead of rebuilding it.
       this.root.scale.y = currentHeight / this.height;
-      if (motion && this.baseBody) animateDefaultAvatar(this.baseBody, motion);
+      if (motion && this.baseBody) return animateDefaultAvatar(this.baseBody, motion);
     }
+    return null;
   }
 
   setExpression(expression: AvatarExpression): void {

package/src/player/stroke.ts

@@ -0,0 +1,93 @@
+import { BackSide, Mesh, MeshBasicMaterial, MeshToonMaterial, type Material, type Object3D } from 'three';
+
+/** How far the shell sits outside the body, in metres. Thick enough to read as ink. */
+const STROKE_WIDTH = 0.05;
+/** Same ink as the door frames. Shown in both themes. */
+const STROKE_COLOR = 0x1c1c1c;
+
+/**
+ * A cartoon outline around the default white figure. Each body part gets a
+ * slightly larger shell of its back faces, so the ink shows only at the
+ * silhouette. The drawn-on face is left alone.
+ */
+export function setFigureStroke(root: Object3D | null, enabled: boolean): void {
+  if (!root) return;
+  const strokes: Mesh[] = [];
+  root.traverse((child) => {
+    if (child instanceof Mesh && child.userData.stroke === true) strokes.push(child);
+  });
+  if (!enabled) {
+    const materials = new Set<Material>();
+    for (const mesh of strokes) {
+      if (!Array.isArray(mesh.material)) materials.add(mesh.material);
+      mesh.removeFromParent();
+    }
+    for (const material of materials) material.dispose();
+    return;
+  }
+  if (strokes.length > 0) return;
+
+  const sources: Mesh[] = [];
+  root.traverse((child) => {
+    if (!(child instanceof Mesh) || child.userData.stroke === true) return;
+    if (!(child.material instanceof MeshToonMaterial)) return;
+    sources.push(child);
+  });
+  if (sources.length === 0) return;
+
+  const sample = sources[0].material as MeshToonMaterial;
+  const fading = sample.transparent;
+  const material = new MeshBasicMaterial({
+    color: STROKE_COLOR,
+    side: BackSide,
+    toneMapped: false,
+    transparent: fading,
+    opacity: fading ? sample.opacity : 1,
+    depthWrite: sample.depthWrite,
+  });
+  material.userData.stroke = true;
+  material.polygonOffset = true;
+  material.polygonOffsetFactor = 1;
+  material.polygonOffsetUnits = 1;
+  material.customProgramCacheKey = () => 'worldmesh-stroke';
+  material.onBeforeCompile = (shader) => {
+    shader.vertexShader = shader.vertexShader.replace(
+      '#include <begin_vertex>',
+      `#include <begin_vertex>\ntransformed += normalize(normal) * ${STROKE_WIDTH.toFixed(3)};`,
+    );
+  };
+
+  for (const source of sources) {
+    const stroke = new Mesh(source.geometry, material);
+    stroke.name = 'worldmesh:stroke';
+    stroke.userData.stroke = true;
+    stroke.position.copy(source.position);
+    stroke.quaternion.copy(source.quaternion);
+    stroke.scale.copy(source.scale);
+    stroke.castShadow = false;
+    stroke.receiveShadow = false;
+    stroke.raycast = () => {};
+    source.parent?.add(stroke);
+  }
+}
+
+/** Fade the outline with the figure. Shared across every part, so one write is enough. */
+export function setStrokeOpacity(root: Object3D | null, amount: number): void {
+  if (!root) return;
+  const solid = amount >= 0.999;
+  let material: MeshBasicMaterial | null = null;
+  root.traverse((child) => {
+    if (material || !(child instanceof Mesh) || child.userData.stroke !== true) return;
+    if (child.material instanceof MeshBasicMaterial) material = child.material;
+  });
+  const stroke = material as MeshBasicMaterial | null;
+  if (!stroke) return;
+  stroke.transparent = !solid;
+  stroke.opacity = amount;
+  stroke.depthWrite = solid;
+  stroke.needsUpdate = true;
+}
+
+export function isStrokeMaterial(material: Material): boolean {
+  return material.userData.stroke === true;
+}

package/src/portals/portals.ts

@@ -12,6 +12,7 @@ import {
   Vector3,
 } from 'three';
 import { withAvatarTicket } from '../avatar/handoff.js';
+import { withView } from '../camera/viewHandoff.js';
 import type { PortalMode, PortalOptions } from '../types.js';
 
 export interface ResolvedPortal extends PortalOptions {
@@ -110,7 +111,7 @@ export class PortalManager {
 
 /**
  * Build the destination URL, carrying a back-reference to this world, and the
- * visitor's avatar handoff ticket (in the fragment) if they arrived with one.
+ * visitor's avatar handoff ticket and camera view (in the fragment) if any.
  */
 export function buildTravelUrl(target: string): string {
   try {
@@ -118,7 +119,9 @@ export function buildTravelUrl(target: string): string {
     if (!url.searchParams.has('from')) {
       url.searchParams.set('from', window.location.origin + window.location.pathname);
     }
-    return withAvatarTicket(url).toString();
+    // A world's own fragment (e.g. a hash route) is left alone.
+    if (url.hash) return url.toString();
+    return withView(withAvatarTicket(url)).toString();
   } catch {
     return target;
   }

package/src/types.ts

@@ -1,4 +1,4 @@
-import type { AvatarDescriptor } from './avatar/descriptor.js';
+import type { AvatarDescriptor, SignedAvatarShare } from './avatar/descriptor.js';
 import type { AvatarExpression } from './player/avatar.js';
 import type { Camera, Object3D, PerspectiveCamera, Scene, WebGLRenderer } from 'three';
 
@@ -134,7 +134,7 @@ export interface PortalOptions {
 }
 
 export interface UiOptions {
-  /** Crosshair dot in first person. */
+  /** Crosshair dot in the middle of the screen. Off unless set to true. */
   crosshair?: boolean;
   /** Bottom-left WorldMesh badge linking back to the hub. */
   badge?: boolean;
@@ -191,6 +191,12 @@ export interface WorldMeshEvents {
   'avatar:error': { descriptor: AvatarDescriptor | null; error: unknown };
   /** People in this world including the visitor, or null while not connected. Only with `multiplayer`. */
   players: { count: number | null };
+  /** The presence relay refused the join because the room is at capacity. */
+  'room:full': { full: boolean };
+  /** An immersive-vr session started. */
+  'vr:enter': Record<string, never>;
+  /** The immersive-vr session ended. */
+  'vr:exit': Record<string, never>;
 }
 
 /** Someone else's body, an upright cylinder the local player cannot walk through. */
@@ -205,17 +211,24 @@ export interface PeerBody {
 
 /**
  * Multiplayer seam. `multiplayer` plugs in the built-in relay client; pass
- * your own adapter here to network the world some other way.
+ * your own adapter as `network` to network the world some other way
+ * (docs/compatibility.md, "Your own network layer"). The runtime calls only
+ * `attach`, `bodies` and `detach`; the adapter does everything else itself.
  */
 export interface NetworkAdapter {
-  /** Called once with a read-only view of the local world. */
+  /**
+   * Called once when the world goes online, with the world's handle. Listen
+   * to its `update` event for the local player's state every frame. In a
+   * hub's live doorway the world stays offline until the visitor walks in.
+   */
   attach(world: WorldMeshHandle): void;
-  /** Called with the local player's state at the network tick rate. */
+  /** Never called by the runtime: a conventional name for the adapter's own send, called from `update`. */
   sendLocalState?(state: PlayerState): void;
-  /** Called by the adapter when a remote peer's state arrives. */
+  /** Never called by the runtime: a conventional name for the adapter's own receive. */
   onRemoteState?(peerId: string, state: PlayerState): void;
-  /** Where everyone else is standing right now. The local player is kept out of them. */
+  /** Where everyone else is standing right now, asked every step. The local player is kept out of them. */
   bodies?(): Iterable<PeerBody>;
+  /** Called from `world.dispose()`. Disconnect and remove what the adapter added to the scene. */
   detach?(): void;
 }
 
@@ -253,8 +266,15 @@ export interface WorldMeshOptions {
    * Ignored when `network` is set.
    */
   multiplayer?: boolean | MultiplayerOptions;
+  /** Play footstep sounds as the player walks. Off by default. */
+  footsteps?: boolean;
   /** A custom network layer. Replaces `multiplayer`. */
   network?: NetworkAdapter;
+  /**
+   * Offer immersive VR through the shared Enter VR control. Defaults to true.
+   * The button only appears when the browser can start an `immersive-vr` session.
+   */
+  vr?: boolean;
 }
 
 export interface MultiplayerOptions {
@@ -285,19 +305,42 @@ export interface WorldMeshHandle {
 
   setViewMode(mode: ViewMode): void;
   getViewMode(): ViewMode;
+  /** How far back the third-person camera sits, in metres. */
+  getCameraDistance(): number;
+  /** Move the third-person camera in or out (0.4 m at the closest); it follows at once when closer. */
+  setCameraDistance(distance: number): void;
 
   addPortal(portal: PortalOptions): void;
   /** Navigate to another WorldMesh world, carrying a `from` back-reference. */
   travelTo(url: string): void;
+  /** Free the cursor for leaving the page, without bringing up the pause screen. */
+  releasePointer(): void;
 
   on<K extends keyof WorldMeshEvents>(event: K, fn: (payload: WorldMeshEvents[K]) => void): () => void;
   off<K extends keyof WorldMeshEvents>(event: K, fn: (payload: WorldMeshEvents[K]) => void): void;
 
-  /** Show an external avatar. Resolves to false (default body kept) if it cannot be loaded. */
-  loadAvatar(descriptor: AvatarDescriptor): Promise<boolean>;
+  /**
+   * Show an external avatar. Resolves to false (default body kept) if it
+   * cannot be loaded. Pass `data` (downloadAvatarModel) if the model file is
+   * already downloaded, and it is not fetched again.
+   */
+  loadAvatar(descriptor: AvatarDescriptor, data?: ArrayBuffer): Promise<boolean>;
   /** Go back to the world's default body. */
   clearAvatar(): void;
+  /**
+   * The link other players may download this visitor's avatar from, signed by
+   * the hub and renewed before it expires; null for the default body or an
+   * avatar that may not be shown to others. For a custom `network` to send.
+   */
+  getSharedAvatar(): SignedAvatarShare | null;
 
   /** Refresh the collider list after the world adds geometry. */
   refreshColliders(): void;
+
+  /** Start an immersive-vr session. Resolves false if the browser refuses. */
+  enterVR(): Promise<boolean>;
+  /** End the immersive-vr session, if one is running. */
+  exitVR(): Promise<void>;
+  /** True while a WebXR immersive-vr session is presenting. */
+  isVR(): boolean;
 }