@worldmesh/runtime 0.1.0 → 0.2.1

package/src/player/player.ts

@@ -1,4 +1,5 @@
 import { Group, Mesh, Object3D, type Vector3 } from 'three';
+import type { LoadedAvatar } from '../avatar/loader.js';
 import type { PlayerOptions } from '../types.js';
 import {
   animateDefaultAvatar,
@@ -30,6 +31,9 @@ export class Player {
   facing = 0;
 
   private isDefaultAvatar: boolean;
+  /** The body the world started with, kept aside while an external avatar is shown. */
+  private baseBody: Object3D | null = null;
+  private external: LoadedAvatar | null = null;
 
   constructor(options: PlayerAvatarOptions) {
     this.height = options.height;
@@ -48,6 +52,38 @@ export class Player {
 
     const body = options.avatar ?? createDefaultAvatar(options.height);
     this.root.add(body as Object3D);
+    this.baseBody = body;
+  }
+
+  /** Whether an external avatar (e.g. from the visitor's Avatar Wallet) is shown. */
+  get hasExternalBody(): boolean {
+    return !!this.external;
+  }
+
+  /**
+   * Show an external avatar instead of the world's body. The original body is
+   * kept, so `clearExternalBody()` brings it back. Ignored when the world
+   * turned the avatar off (`avatar: false`).
+   */
+  setExternalBody(avatar: LoadedAvatar): boolean {
+    if (!this.root || !this.baseBody) {
+      avatar.dispose();
+      return false;
+    }
+    this.clearExternalBody();
+    this.baseBody.visible = false;
+    this.root.scale.y = 1;
+    this.root.add(avatar.object);
+    this.external = avatar;
+    return true;
+  }
+
+  clearExternalBody(): void {
+    if (!this.external) return;
+    this.external.object.removeFromParent();
+    this.external.dispose();
+    this.external = null;
+    if (this.baseBody) this.baseBody.visible = true;
   }
 
   /** Place the avatar at the player's feet, facing `yaw`, and animate it for `motion`. */
@@ -61,16 +97,18 @@ export class Player {
     if (!this.root) return;
     this.root.position.copy(feet);
     this.root.rotation.y = this.facing;
-    if (this.isDefaultAvatar) {
+    if (this.external) {
+      if (motion) this.external.animate(motion);
+    } else if (this.isDefaultAvatar) {
       // Squash the default body while crouching instead of rebuilding it.
       this.root.scale.y = currentHeight / this.height;
-      if (motion) animateDefaultAvatar(this.root.children[0], motion);
+      if (motion && this.baseBody) animateDefaultAvatar(this.baseBody, motion);
     }
   }
 
   setExpression(expression: AvatarExpression): void {
     this.expression = expression;
-    if (this.root && this.isDefaultAvatar) setAvatarExpression(this.root.children[0], expression);
+    if (this.baseBody && this.isDefaultAvatar) setAvatarExpression(this.baseBody, expression);
   }
 
   setVisible(visible: boolean): void {
@@ -78,6 +116,7 @@ export class Player {
   }
 
   dispose(): void {
+    this.clearExternalBody();
     this.root?.traverse((child) => {
       if (child instanceof Mesh) {
         child.geometry.dispose();

package/src/portals/portals.ts

@@ -11,6 +11,7 @@ import {
   TorusGeometry,
   Vector3,
 } from 'three';
+import { withAvatarTicket } from '../avatar/handoff.js';
 import type { PortalMode, PortalOptions } from '../types.js';
 
 export interface ResolvedPortal extends PortalOptions {
@@ -107,14 +108,17 @@ export class PortalManager {
   }
 }
 
-/** Build the destination URL, carrying a back-reference to this world. */
+/**
+ * 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.
+ */
 export function buildTravelUrl(target: string): string {
   try {
     const url = new URL(target, window.location.href);
     if (!url.searchParams.has('from')) {
       url.searchParams.set('from', window.location.origin + window.location.pathname);
     }
-    return url.toString();
+    return withAvatarTicket(url).toString();
   } catch {
     return target;
   }

package/src/types.ts

@@ -1,3 +1,4 @@
+import type { AvatarDescriptor } from './avatar/descriptor.js';
 import type { AvatarExpression } from './player/avatar.js';
 import type { Camera, Object3D, PerspectiveCamera, Scene, WebGLRenderer } from 'three';
 
@@ -78,6 +79,30 @@ export interface PlayerOptions {
   avatar?: Object3D | false;
 }
 
+/**
+ * Let visitors bring their own character. Entirely optional: without it, or
+ * whenever resolving or loading fails, the player keeps the world's body.
+ *
+ * - `worldmesh`: the avatar the visitor picked in their WorldMesh Avatar
+ *   Wallet, handed over through the URL fragment when they arrive from the
+ *   hub or another world. The model loads from the avatar platform itself;
+ *   this world never sees the visitor's account or platform credentials.
+ * - `descriptor`: an avatar the world resolved on its own.
+ */
+export type AvatarOptions =
+  | {
+      source: 'worldmesh';
+      /** The WorldMesh hub that resolves handoff tickets. Defaults to https://worldmesh.net/. */
+      hubUrl?: string;
+      /** Refuse models larger than this many bytes. Defaults to 40 MB. */
+      maxBytes?: number;
+    }
+  | {
+      source: 'descriptor';
+      descriptor: AvatarDescriptor;
+      maxBytes?: number;
+    };
+
 export interface ViewOptions {
   mode?: ViewMode;
   /** Third-person boom length in metres. */
@@ -119,6 +144,17 @@ export interface UiOptions {
   controlsHint?: boolean;
   /** World name shown in the overlay. */
   title?: string;
+  /**
+   * Hide the click-to-enter panel until the visitor has entered once and then
+   * pressed Esc. The first screen stays clear; a click/tap still starts them.
+   */
+  deferLockPanel?: boolean;
+  /**
+   * Walking starts immediately. The keyboard, the on-screen joysticks and
+   * mouse look (with the cursor visible) work before any click, and Esc holds
+   * them until Continue. The first click captures the cursor for unlimited turning.
+   */
+  moveBeforeLock?: boolean;
 }
 
 /** Everything another peer would need to draw this player. Serializable on purpose. */
@@ -149,12 +185,27 @@ export interface WorldMeshEvents {
   /** E pressed with nothing else claiming it. */
   interact: { position: Vec3Tuple };
   respawn: { reason: 'fell' | 'manual' };
+  /** The visitor's own avatar replaced the default body. */
+  'avatar:load': { descriptor: AvatarDescriptor };
+  /** An external avatar could not be shown; the default body stays. */
+  '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 };
+}
+
+/** Someone else's body, an upright cylinder the local player cannot walk through. */
+export interface PeerBody {
+  /** Feet position in world space. */
+  x: number;
+  y: number;
+  z: number;
+  radius: number;
+  height: number;
 }
 
 /**
- * Multiplayer seam. Nothing in the runtime implements this yet — it exists so
- * the local player loop stays shaped like something a network can drive later
- * (peer-to-peer, a world-hosted server, or a WorldMesh signaling service).
+ * Multiplayer seam. `multiplayer` plugs in the built-in relay client; pass
+ * your own adapter here to network the world some other way.
  */
 export interface NetworkAdapter {
   /** Called once with a read-only view of the local world. */
@@ -163,6 +214,8 @@ export interface NetworkAdapter {
   sendLocalState?(state: PlayerState): void;
   /** Called by the adapter when a remote peer's state arrives. */
   onRemoteState?(peerId: string, state: PlayerState): void;
+  /** Where everyone else is standing right now. The local player is kept out of them. */
+  bodies?(): Iterable<PeerBody>;
   detach?(): void;
 }
 
@@ -180,6 +233,8 @@ export interface WorldMeshOptions {
   colliders?: Object3D[] | (() => Object3D[]);
   portals?: PortalOptions[];
   player?: PlayerOptions;
+  /** Show the visitor's own avatar. Off by default. */
+  avatar?: AvatarOptions;
   view?: ViewOptions;
   keymap?: Partial<Keymap>;
   movement?: Partial<MovementTuning>;
@@ -192,10 +247,21 @@ export interface WorldMeshOptions {
   autoResize?: boolean;
   /** Your per-frame world logic. Runs after movement, before rendering. */
   onUpdate?: (dt: number, world: WorldMeshHandle) => void;
-  /** Reserved. Not used by the MVP. */
+  /**
+   * Show everyone else who is in this world. `true` uses the relay WorldMesh
+   * hosts; `{ server }` points at your own copy of workers/presence.
+   * Ignored when `network` is set.
+   */
+  multiplayer?: boolean | MultiplayerOptions;
+  /** A custom network layer. Replaces `multiplayer`. */
   network?: NetworkAdapter;
 }
 
+export interface MultiplayerOptions {
+  /** WebSocket base URL of a presence relay, e.g. `wss://relay.example.com`. */
+  server?: string;
+}
+
 export interface WorldMeshHandle {
   readonly scene: Scene;
   readonly camera: Camera;
@@ -203,6 +269,8 @@ export interface WorldMeshHandle {
   readonly abilities: Readonly<Abilities>;
   /** The avatar root. Move it and you move the player. */
   readonly avatar: Object3D | null;
+  /** The external avatar being shown, or null while the default body is. */
+  readonly avatarDescriptor: AvatarDescriptor | null;
 
   start(): void;
   stop(): void;
@@ -225,6 +293,11 @@ export interface WorldMeshHandle {
   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>;
+  /** Go back to the world's default body. */
+  clearAvatar(): void;
+
   /** Refresh the collider list after the world adds geometry. */
   refreshColliders(): void;
 }

package/src/ui/overlay.ts

@@ -47,6 +47,14 @@ const CSS = `
   -webkit-tap-highlight-color: transparent;
 }
 .wm-overlay[data-locked="true"] .wm-lock { display: none; }
+/* First visit with deferLockPanel: keep the click target, hide the chrome. */
+.wm-overlay[data-defer-lock="true"]:not([data-lock-ready="true"]) .wm-lock {
+  background: transparent;
+  backdrop-filter: none;
+}
+.wm-overlay[data-defer-lock="true"]:not([data-lock-ready="true"]) .wm-lock-content {
+  visibility: hidden;
+}
 .wm-lock-content {
   margin: auto 0;
   width: 100%;
@@ -59,10 +67,14 @@ const CSS = `
   box-sizing: border-box;
 }
 .wm-lock-title {
+  width: 100%;
+  margin: 0;
+  padding: 0;
+  display: block;
+  text-align: center;
   font-size: clamp(22px, 5vw, 34px);
   font-weight: 600;
   letter-spacing: .01em;
-  margin: 0;
 }
 .wm-lock-cta {
   font-size: 13.5px;
@@ -265,7 +277,9 @@ const KEY_LEGEND: [string, string][] = [
 export class Overlay {
   readonly root: HTMLDivElement;
   private prompt: HTMLDivElement;
+  private lock: HTMLDivElement;
   private onEnter: (touch?: boolean) => void;
+  private deferLockPanel: boolean;
 
   constructor(
     options: UiOptions & {
@@ -275,12 +289,15 @@ export class Overlay {
   ) {
     injectStyles();
     this.onEnter = options.onEnter;
+    this.deferLockPanel = options.deferLockPanel === true;
 
     const isTouch = isTouchDevice();
 
     this.root = document.createElement('div');
     this.root.className = 'wm-overlay';
-    this.root.dataset.locked = 'false';
+    // Already walking: no click-to-enter layer. Esc is what brings the pause screen up.
+    this.root.dataset.locked = options.moveBeforeLock ? 'true' : 'false';
+    if (this.deferLockPanel) this.root.dataset.deferLock = 'true';
 
     if (options.crosshair !== false) {
       const crosshair = document.createElement('div');
@@ -290,6 +307,7 @@ export class Overlay {
 
     const lock = document.createElement('div');
     lock.className = 'wm-lock';
+    this.lock = lock;
 
     const content = document.createElement('div');
     content.className = 'wm-lock-content';
@@ -302,11 +320,10 @@ export class Overlay {
     const cta = document.createElement('button');
     cta.type = 'button';
     cta.className = 'wm-lock-cta';
-    cta.textContent = isTouch ? 'Tap to enter' : 'Click to enter';
+    cta.textContent = 'Continue';
     content.appendChild(cta);
 
     const handleEnter = (e: Event) => {
-      e.preventDefault();
       e.stopPropagation();
       const touchInitiated =
         ('pointerType' in e && (e as PointerEvent).pointerType === 'touch') ||
@@ -315,9 +332,18 @@ export class Overlay {
       this.onEnter(touchInitiated);
     };
 
+    // A click or tap on the button resumes. The Enter key does not: that key talks.
+    cta.addEventListener('keydown', (event) => {
+      if (event.key === 'Enter' || event.key === ' ') event.preventDefault();
+    });
     cta.addEventListener('click', handleEnter);
-    cta.addEventListener('pointerup', handleEnter);
-    lock.addEventListener('click', handleEnter);
+    lock.addEventListener('click', (event) => {
+      const target = event.target;
+      if (target instanceof Element && target.closest('button, a, input, textarea, select, label, .walk-pause-actions')) {
+        return;
+      }
+      handleEnter(event);
+    });
 
     if (options.controlsHint !== false) {
       const keys = document.createElement('div');
@@ -341,6 +367,7 @@ export class Overlay {
     }
     lock.appendChild(content);
     this.root.appendChild(lock);
+    if (this.deferLockPanel) this.hideLockChrome();
 
     this.prompt = document.createElement('div');
     this.prompt.className = 'wm-prompt';
@@ -365,14 +392,40 @@ export class Overlay {
 
     const hint = document.createElement('div');
     hint.className = 'wm-hint';
-    hint.textContent = isTouch ? 'Tap ⏸ to pause' : 'ESC to release cursor';
+    hint.textContent = isTouch ? 'Tap ⏸ to open the menu' : 'Esc to open the menu';
     this.root.appendChild(hint);
 
     document.body.appendChild(this.root);
   }
 
+  /** The pause screen, with the control list, is on screen. */
+  isPaused(): boolean {
+    return this.root.dataset.lockReady === 'true' && this.root.dataset.locked !== 'true';
+  }
+
   setLocked(locked: boolean): void {
     this.root.dataset.locked = String(locked);
+    if (!locked && this.deferLockPanel) {
+      this.root.dataset.lockReady = 'true';
+      this.showLockChrome();
+    }
+  }
+
+  /** Keep the full-screen click target; strip the dimmer and copy. */
+  private hideLockChrome(): void {
+    this.lock.style.background = 'transparent';
+    this.lock.style.backdropFilter = 'none';
+    this.lock.style.setProperty('-webkit-backdrop-filter', 'none');
+    const content = this.lock.querySelector('.wm-lock-content');
+    if (content instanceof HTMLElement) content.style.visibility = 'hidden';
+  }
+
+  private showLockChrome(): void {
+    this.lock.style.background = '';
+    this.lock.style.backdropFilter = '';
+    this.lock.style.removeProperty('-webkit-backdrop-filter');
+    const content = this.lock.querySelector('.wm-lock-content');
+    if (content instanceof HTMLElement) content.style.visibility = '';
   }
 
   setPrompt(text: string | null): void {