@worldmesh/runtime 0.1.0 → 0.2.1

package/src/controls/input.ts

@@ -6,7 +6,14 @@ export interface InputOptions {
   /** The element that receives pointer lock. */
   element: HTMLElement;
   keymap?: Partial<Keymap>;
+  /** Keyboard and joysticks work before the cursor is captured. */
+  moveBeforeLock?: boolean;
   onPointerLockChange?: (locked: boolean) => void;
+  /**
+   * Escape toggles the pause screen. Return true when this press captures
+   * the mouse again, so the key's usual "show the cursor" action can be cancelled.
+   */
+  onEscape?: () => boolean | void;
 }
 
 /**
@@ -24,6 +31,7 @@ export class Input {
   locked = false;
 
   private element: HTMLElement;
+  private moveBeforeLock: boolean;
   private pressed = new Set<string>();
   /** Actions that went down this frame and have not been consumed yet. */
   private justPressed = new Set<InputAction>();
@@ -31,13 +39,16 @@ export class Input {
   private pendingDigit: number | null = null;
   private codeToActions = new Map<string, InputAction[]>();
   private onPointerLockChange?: (locked: boolean) => void;
+  private onEscape?: () => boolean | void;
   private touch?: TouchControls;
   private disposed = false;
 
   constructor(options: InputOptions) {
     this.element = options.element;
+    this.moveBeforeLock = options.moveBeforeLock === true;
     this.keymap = resolveKeymap(options.keymap);
     this.onPointerLockChange = options.onPointerLockChange;
+    this.onEscape = options.onEscape;
 
     for (const action of Object.keys(this.keymap) as InputAction[]) {
       for (const code of this.keymap[action]) {
@@ -56,6 +67,7 @@ export class Input {
       });
     }
 
+    window.addEventListener('keydown', this.handleEscape, true);
     window.addEventListener('keydown', this.handleKeyDown);
     window.addEventListener('keyup', this.handleKeyUp);
     window.addEventListener('blur', this.handleBlur);
@@ -63,6 +75,9 @@ export class Input {
     document.addEventListener('pointerlockerror', this.handlePointerLockError);
     this.element.addEventListener('mousemove', this.handleMouseMove);
     this.element.addEventListener('wheel', this.handleWheel, { passive: true });
+    this.element.addEventListener('pointerdown', this.handlePointerDown);
+    // The sticks are on screen from the start, so the first touch moves instead of "entering".
+    if (this.moveBeforeLock && isTouchDevice()) this.touch?.setVisible(true);
   }
 
   requestPointerLock(touchTriggered = false): void {
@@ -109,7 +124,15 @@ export class Input {
     if (document.pointerLockElement === this.element) {
       document.exitPointerLock();
     }
-    this.setLocked(false);
+    if (this.locked) this.setLocked(false);
+    else {
+      // Never captured, but the pause screen is coming up: drop the sticks and any held keys.
+      this.pressed.clear();
+      this.justPressed.clear();
+      this.touch?.reset();
+      this.touch?.setVisible(false);
+      this.onPointerLockChange?.(false);
+    }
   }
 
   triggerAction(action: InputAction): void {
@@ -179,6 +202,7 @@ export class Input {
   dispose(): void {
     this.disposed = true;
     this.touch?.dispose();
+    window.removeEventListener('keydown', this.handleEscape, true);
     window.removeEventListener('keydown', this.handleKeyDown);
     window.removeEventListener('keyup', this.handleKeyUp);
     window.removeEventListener('blur', this.handleBlur);
@@ -186,10 +210,23 @@ export class Input {
     document.removeEventListener('pointerlockerror', this.handlePointerLockError);
     this.element.removeEventListener('mousemove', this.handleMouseMove);
     this.element.removeEventListener('wheel', this.handleWheel);
+    this.element.removeEventListener('pointerdown', this.handlePointerDown);
     this.pressed.clear();
     this.justPressed.clear();
   }
 
+  /**
+   * Escape toggles the pause screen. The browser's own Esc action is what
+   * puts the cursor back, so that is left alone. It is cancelled only when
+   * this press captures the mouse again, or the cursor would vanish immediately.
+   */
+  private handleEscape = (event: KeyboardEvent): void => {
+    if (event.key !== 'Escape' || event.repeat || this.disposed || !this.onEscape) return;
+    if (document.querySelector('dialog[open]')) return;
+    const relock = this.onEscape() === true;
+    if (relock) event.preventDefault();
+  };
+
   private handleKeyDown = (event: KeyboardEvent): void => {
     if (event.repeat) return;
     if (isTypingTarget(event.target)) return;
@@ -216,12 +253,34 @@ export class Input {
     this.justPressed.clear();
   };
 
+  /**
+   * A click captures the cursor for looking. Touch is left alone: the joysticks
+   * already have the finger, and they do not need a tap before they work.
+   */
+  private handlePointerDown = (event: PointerEvent): void => {
+    if (!this.moveBeforeLock || this.locked || this.disposed || event.button !== 0) return;
+    if (event.pointerType === 'touch' || event.pointerType === 'pen') return;
+    const target = event.target instanceof Element ? event.target : null;
+    if (target?.closest('button, a, input, textarea, select, label, dialog, .wm-lock, .walk-pause-actions')) return;
+    this.requestPointerLock();
+  };
+
+  /**
+   * Captured: every movement turns the camera. Before the first click, with
+   * moveBeforeLock, the visible cursor turns it too, so looking works from the start.
+   */
   private handleMouseMove = (event: MouseEvent): void => {
-    if (!this.locked) return;
+    if (!this.locked && !this.hoverLook(event)) return;
     this.mouseDeltaX += event.movementX;
     this.mouseDeltaY += event.movementY;
   };
 
+  private hoverLook(event: MouseEvent): boolean {
+    if (!this.moveBeforeLock || this.disposed || isTouchDevice()) return false;
+    // A held button is a drag on something else, not a look.
+    return event.buttons === 0;
+  }
+
   private handleWheel = (event: WheelEvent): void => {
     if (!this.locked) return;
     this.wheelDelta += event.deltaY;

package/src/controls/touch.ts

@@ -198,6 +198,11 @@ export class TouchControls {
     menuBtn.addEventListener('pointerdown', (e) => {
       e.stopPropagation();
       e.preventDefault();
+    });
+    // Open on click, not pointerdown: opening hides this button, and the tap's
+    // click would then land on the pause screen and resume straight away.
+    menuBtn.addEventListener('click', (e) => {
+      e.stopPropagation();
       this.onExit?.();
     });
     this.root.appendChild(menuBtn);

package/src/core/worldmesh.ts

@@ -1,5 +1,8 @@
 import { Vector3 } from 'three';
 import { resolveAbilities } from '../abilities/abilities.js';
+import { parseAvatarDescriptor, type AvatarDescriptor } from '../avatar/descriptor.js';
+import { resolveWorldMeshAvatar, takeAvatarTicket } from '../avatar/handoff.js';
+import { loadAvatarModel } from '../avatar/loader.js';
 import { CameraRig } from '../camera/cameraRig.js';
 import { Input } from '../controls/input.js';
 import { CollisionWorld } from '../movement/collision.js';
@@ -18,11 +21,13 @@ import type {
 import { Overlay } from '../ui/overlay.js';
 import { isTouchDevice } from '../controls/touch.js';
 import { Emitter } from './events.js';
+import { DEFAULT_PRESENCE_SERVER, Presence } from '../net/presence.js';
 
 /** Never simulate more than this per substep, so a stall cannot tunnel the player. */
 const MAX_STEP = 1 / 60;
 /** Never simulate more than this per frame, so a backgrounded tab does not catch up violently. */
 const MAX_FRAME = 0.1;
+const DEFAULT_HUB = 'https://worldmesh.net/';
 
 /**
  * Turn an ordinary Three.js scene into a WorldMesh world.
@@ -33,6 +38,9 @@ const MAX_FRAME = 0.1;
  */
 export function createWorldMesh(options: WorldMeshOptions): WorldMeshHandle {
   const { scene, camera, renderer } = options;
+  // Always take an avatar handoff ticket out of the address bar, even if this
+  // world shows no avatars: portals still carry it on to the next world.
+  const avatarTicket = takeAvatarTicket();
   const spawn = new Vector3(...(options.spawn ?? [0, 2, 0]));
   const abilities = resolveAbilities(options.abilities);
 
@@ -57,10 +65,19 @@ export function createWorldMesh(options: WorldMeshOptions): WorldMeshHandle {
   const input = new Input({
     element: renderer.domElement,
     keymap: options.keymap,
+    moveBeforeLock: options.ui?.moveBeforeLock === true,
     onPointerLockChange: (locked) => {
       overlay.setLocked(locked);
       events.emit('pointer:lock', { locked });
     },
+    onEscape: () => {
+      if (overlay.isPaused()) {
+        input.requestPointerLock();
+        return true;
+      }
+      input.exitPointerLock();
+      return false;
+    },
   });
 
   const cameraRig = new CameraRig({ ...options.view, camera, collision });
@@ -85,6 +102,8 @@ export function createWorldMesh(options: WorldMeshOptions): WorldMeshHandle {
   let elapsed = 0;
   let activePortal: ResolvedPortal | null = null;
   let disposed = false;
+  let avatarDescriptor: AvatarDescriptor | null = null;
+  let avatarLoad: AbortController | null = null;
 
   const handle: WorldMeshHandle = {
     scene,
@@ -92,6 +111,9 @@ export function createWorldMesh(options: WorldMeshOptions): WorldMeshHandle {
     renderer,
     abilities,
     avatar: player.root,
+    get avatarDescriptor() {
+      return avatarDescriptor;
+    },
 
     start,
     stop,
@@ -111,6 +133,9 @@ export function createWorldMesh(options: WorldMeshOptions): WorldMeshHandle {
     },
     travelTo,
 
+    loadAvatar,
+    clearAvatar,
+
     on: (event, fn) => events.on(event, fn),
     off: (event, fn) => events.off(event, fn),
 
@@ -124,10 +149,68 @@ export function createWorldMesh(options: WorldMeshOptions): WorldMeshHandle {
 
   if (options.autoStart !== false) start();
 
-  options.network?.attach(handle);
+  const network = options.network ?? createMultiplayer();
+  network?.attach(handle);
+  if (network?.bodies) controller.bodies = () => network.bodies!();
+
+  startAvatar();
 
   return handle;
 
+  /** Brings in the visitor's own avatar, if the world asked for one. The default body stays until it is ready. */
+  function startAvatar(): void {
+    const config = options.avatar;
+    if (!config || !player.root) return;
+    if (config.source === 'descriptor') {
+      const descriptor = parseAvatarDescriptor(config.descriptor);
+      if (descriptor) void loadAvatar(descriptor);
+      else events.emit('avatar:error', { descriptor: null, error: new Error('Invalid avatar descriptor') });
+      return;
+    }
+    if (config.source !== 'worldmesh' || !avatarTicket) return;
+    resolveWorldMeshAvatar(config.hubUrl ?? DEFAULT_HUB, avatarTicket).then(
+      (descriptor) => {
+        if (descriptor && !disposed) void loadAvatar(descriptor);
+      },
+      (error) => events.emit('avatar:error', { descriptor: null, error }),
+    );
+  }
+
+  async function loadAvatar(descriptor: AvatarDescriptor): Promise<boolean> {
+    if (disposed || !player.root) return false;
+    avatarLoad?.abort();
+    const load = (avatarLoad = new AbortController());
+    try {
+      const loaded = await loadAvatarModel(descriptor, {
+        height,
+        maxBytes: options.avatar?.maxBytes,
+        signal: load.signal,
+      });
+      if (disposed || load.signal.aborted) {
+        loaded.dispose();
+        return false;
+      }
+      if (!player.setExternalBody(loaded)) return false;
+      avatarDescriptor = descriptor;
+      applyViewVisibility();
+      events.emit('avatar:load', { descriptor });
+      return true;
+    } catch (error) {
+      if (load.signal.aborted) return false;
+      console.warn('[worldmesh] Could not load the avatar; keeping the default body.', error);
+      events.emit('avatar:error', { descriptor, error });
+      return false;
+    } finally {
+      if (avatarLoad === load) avatarLoad = null;
+    }
+  }
+
+  function clearAvatar(): void {
+    avatarLoad?.abort();
+    player.clearExternalBody();
+    avatarDescriptor = null;
+  }
+
   function start(): void {
     if (running || disposed) return;
     running = true;
@@ -157,9 +240,12 @@ export function createWorldMesh(options: WorldMeshOptions): WorldMeshHandle {
     elapsed += dt;
 
     const look = input.readLook();
-    if (input.locked) {
-      cameraRig.look(look.dx, look.dy);
-      cameraRig.zoom(look.wheel);
+    const playing = isPlaying();
+    if (playing) {
+      if (input.locked || isTouchDevice() || options.ui?.moveBeforeLock === true) {
+        cameraRig.look(look.dx, look.dy);
+        if (input.locked) cameraRig.zoom(look.wheel);
+      }
       if (input.consume('toggleView')) setViewMode(cameraRig.mode === 'first' ? 'third' : 'first');
       const digit = input.consumeDigit();
       const expression = digit === null ? null : expressionForDigit(digit);
@@ -170,7 +256,7 @@ export function createWorldMesh(options: WorldMeshOptions): WorldMeshHandle {
     let remaining = dt;
     while (remaining > 0) {
       const step = Math.min(remaining, MAX_STEP);
-      controller.step(step, cameraRig.yaw, input.locked);
+      controller.step(step, cameraRig.yaw, playing);
       remaining -= step;
     }
 
@@ -191,6 +277,11 @@ export function createWorldMesh(options: WorldMeshOptions): WorldMeshHandle {
     events.emit('update', { dt, state: getState() });
   }
 
+  /** Walking, until Esc opens the pause screen. */
+  function isPlaying(): boolean {
+    return !overlay.isPaused() && (input.locked || options.ui?.moveBeforeLock === true);
+  }
+
   function updatePortals(): void {
     const nearest = portals.findActive(controller.position);
 
@@ -202,7 +293,7 @@ export function createWorldMesh(options: WorldMeshOptions): WorldMeshHandle {
 
     if (!nearest) {
       overlay.setPrompt(null);
-      if (input.locked && input.consume('interact')) {
+      if (isPlaying() && input.consume('interact')) {
         events.emit('interact', { position: controller.position.toArray() as Vec3Tuple });
       }
       return;
@@ -216,7 +307,7 @@ export function createWorldMesh(options: WorldMeshOptions): WorldMeshHandle {
 
     const isTouch = isTouchDevice();
     overlay.setPrompt(isTouch ? `Tap to enter ${nearest.label}` : `Press E to enter ${nearest.label}`);
-    if (input.locked && input.consume('interact')) activatePortal(nearest);
+    if (isPlaying() && input.consume('interact')) activatePortal(nearest);
   }
 
   function activatePortal(portal: ResolvedPortal): void {
@@ -298,12 +389,23 @@ export function createWorldMesh(options: WorldMeshOptions): WorldMeshHandle {
     cameraRig.resize(width, viewHeight);
   }
 
+  function createMultiplayer(): Presence | undefined {
+    if (!options.multiplayer) return undefined;
+    const server = (options.multiplayer === true ? undefined : options.multiplayer.server) ?? DEFAULT_PRESENCE_SERVER;
+    return new Presence({
+      url: `${server.replace(/\/$/, '')}/world`,
+      scene,
+      onCount: (count) => events.emit('players', { count }),
+    });
+  }
+
   function dispose(): void {
     if (disposed) return;
     disposed = true;
     stop();
+    avatarLoad?.abort();
     window.removeEventListener('resize', handleResize);
-    options.network?.detach?.();
+    network?.detach?.();
     input.dispose();
     overlay.dispose();
     portals.dispose();

package/src/index.ts

@@ -16,22 +16,42 @@ export {
   getAvatarExpression,
   isAvatarExpression,
   setAvatarExpression,
+  setAvatarAppear,
+  setAvatarColor,
 } from './player/avatar.js';
 export type { AvatarExpression, AvatarMotion } from './player/avatar.js';
 export { PortalManager, buildTravelUrl, getReferringWorld } from './portals/portals.js';
+export { isLoadableUrl, parseAvatarDescriptor } from './avatar/descriptor.js';
+export type { AvatarDescriptor, AvatarFormat } from './avatar/descriptor.js';
+export {
+  AVATAR_TICKET_PARAM,
+  AVATAR_TICKET_STORAGE_KEY,
+  getAvatarTicket,
+  resolveWorldMeshAvatar,
+  setAvatarTicket,
+  takeAvatarTicket,
+  withAvatarTicket,
+} from './avatar/handoff.js';
+export { loadAvatarModel } from './avatar/loader.js';
+export type { LoadAvatarOptions, LoadedAvatar } from './avatar/loader.js';
 export { Overlay } from './ui/overlay.js';
 export { deserializePlayerState, serializePlayerState } from './net/adapter.js';
+export { DEFAULT_PRESENCE_SERVER, Presence } from './net/presence.js';
+export type { PresenceOptions } from './net/presence.js';
 
-export const WORLDMESH_VERSION = '0.1.0';
+export const WORLDMESH_VERSION = '0.2.1';
 /** Bumped when the world-facing contract changes in an incompatible way. */
 export const WORLDMESH_PROTOCOL = 1;
 
 export type {
   Abilities,
+  AvatarOptions,
   InputAction,
   Keymap,
   MovementTuning,
+  MultiplayerOptions,
   NetworkAdapter,
+  PeerBody,
   PlayerOptions,
   PlayerState,
   PortalMode,

package/src/movement/controller.ts

@@ -1,6 +1,6 @@
 import { Vector3 } from 'three';
 import type { Input } from '../controls/input.js';
-import type { Abilities, MovementTuning } from '../types.js';
+import type { Abilities, MovementTuning, PeerBody } from '../types.js';
 import type { CollisionWorld } from './collision.js';
 
 export const DEFAULT_TUNING: MovementTuning = {
@@ -18,6 +18,13 @@ export const DEFAULT_TUNING: MovementTuning = {
   fallLimit: -60,
 };
 
+/**
+ * How fast two people who start out inside each other (both arriving at the
+ * spawn point, say) drift apart, in m/s. Slow, so it reads as making room
+ * rather than a shove.
+ */
+const SEPARATE_SPEED = 1.5;
+
 export interface ControllerOptions {
   input: Input;
   collision: CollisionWorld;
@@ -42,6 +49,8 @@ export class MovementController {
   flying = false;
   /** Current standing height, shrinks while crouching. */
   currentHeight: number;
+  /** Other people's bodies, which this player walks into rather than through. */
+  bodies: (() => Iterable<PeerBody>) | null = null;
 
   readonly tuning: MovementTuning;
 
@@ -197,18 +206,26 @@ export class MovementController {
 
   private applyMotion(dt: number): void {
     const horizontal = this.scratch.set(this.velocity.x * dt, 0, this.velocity.z * dt);
-    const resolved = this.collision.resolveHorizontal(
+    let resolved = this.collision.resolveHorizontal(
       this.position,
       horizontal,
       this.radius,
       this.currentHeight,
     );
+    const walked = resolved.clone();
+    const apart = this.keepApart(resolved, dt);
+    // Stepping round someone can lead into a wall, so check the walls again.
+    if (apart !== 'clear') {
+      resolved = this.collision.resolveHorizontal(this.position, resolved, this.radius, this.currentHeight);
+    }
 
     // Feed the resolved slide back into velocity so we do not keep pushing
-    // into a wall and accelerating along it.
+    // into a wall and accelerating along it. Drifting out of someone is not
+    // walking, so it does not carry on once clear of them.
     if (dt > 0) {
-      this.velocity.x = resolved.x / dt;
-      this.velocity.z = resolved.z / dt;
+      const moved = apart === 'separating' ? walked : resolved;
+      this.velocity.x = moved.x / dt;
+      this.velocity.z = moved.z / dt;
     }
     this.position.x += resolved.x;
     this.position.z += resolved.z;
@@ -245,4 +262,41 @@ export class MovementController {
       this.onGround = false;
     }
   }
+
+  /**
+   * Bend this step's horizontal `move` so the player does not end up inside
+   * anyone else. Walking into someone stops at their edge and slides round
+   * them; already overlapping, the gap may only grow. Says whether `move`
+   * changed, and whether that includes drifting out of someone.
+   */
+  private keepApart(move: Vector3, dt: number): 'clear' | 'blocked' | 'separating' {
+    if (!this.bodies) return 'clear';
+    const { x, y, z } = this.position;
+    let result: 'clear' | 'blocked' | 'separating' = 'clear';
+    for (const body of this.bodies()) {
+      // Only bodies at the same height block: jumping over someone is fine.
+      if (body.y >= y + this.currentHeight || y >= body.y + body.height) continue;
+      const reach = this.radius + body.radius;
+      const nowX = x - body.x;
+      const nowZ = z - body.z;
+      const now = Math.hypot(nowX, nowZ);
+      if (now >= reach + Math.hypot(move.x, move.z)) continue;
+      let awayX = nowX + move.x;
+      let awayZ = nowZ + move.z;
+      const next = Math.hypot(awayX, awayZ);
+      const floor = Math.min(reach, now + SEPARATE_SPEED * dt);
+      if (next >= floor) continue;
+      if (next < 1e-4) {
+        // Heading straight through their middle: step back the way we came, or any way at all.
+        awayX = now > 1e-4 ? nowX : 1;
+        awayZ = now > 1e-4 ? nowZ : 0;
+      }
+      // End the step `floor` away from them, in the direction we were headed.
+      const away = Math.hypot(awayX, awayZ);
+      move.x = (awayX / away) * floor - nowX;
+      move.z = (awayZ / away) * floor - nowZ;
+      if (result !== 'separating') result = now < reach ? 'separating' : 'blocked';
+    }
+    return result;
+  }
 }

package/src/net/adapter.ts

@@ -1,20 +1,9 @@
 import type { NetworkAdapter, PlayerState } from '../types.js';
 
 /**
- * Multiplayer is intentionally NOT implemented. This file exists to pin down
- * the seam so the runtime stays easy to network later:
- *
- *  - the local player is simulated from serializable `PlayerState`, so a peer's
- *    state can drive an identical avatar with no movement-code changes;
- *  - the runtime exposes `update(dt)` separately from rendering, so a fixed
- *    network tick can drive it;
- *  - nothing in movement/camera/portals reaches for a global connection.
- *
- * Expected eventual topologies, in order of how much WorldMesh has to host:
- *  1. peer-to-peer WebRTC, worlds exchange state directly;
- *  2. a multiplayer server run by the world's own creator;
- *  3. optional WorldMesh signaling/discovery only (no game traffic);
- *  4. an optional hosted fallback, last resort.
+ * The built-in implementation is `Presence` (presence.ts), enabled with the
+ * `multiplayer` option. Anything else that implements `NetworkAdapter` can be
+ * passed as `network` instead.
  */
 export type { NetworkAdapter, PlayerState };