@worldmesh/runtime 0.1.0

package/src/core/worldmesh.ts

@@ -0,0 +1,313 @@
+import { Vector3 } from 'three';
+import { resolveAbilities } from '../abilities/abilities.js';
+import { CameraRig } from '../camera/cameraRig.js';
+import { Input } from '../controls/input.js';
+import { CollisionWorld } from '../movement/collision.js';
+import { MovementController } from '../movement/controller.js';
+import { expressionForDigit, isAvatarExpression } from '../player/avatar.js';
+import { Player } from '../player/player.js';
+import { PortalManager, buildTravelUrl, type ResolvedPortal } from '../portals/portals.js';
+import type {
+  PlayerState,
+  Vec3Tuple,
+  ViewMode,
+  WorldMeshEvents,
+  WorldMeshHandle,
+  WorldMeshOptions,
+} from '../types.js';
+import { Overlay } from '../ui/overlay.js';
+import { isTouchDevice } from '../controls/touch.js';
+import { Emitter } from './events.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;
+
+/**
+ * Turn an ordinary Three.js scene into a WorldMesh world.
+ *
+ * This is the whole compatibility surface: a world that can produce a scene,
+ * a camera and a renderer gets the shared controls, both camera modes, the
+ * shared overlay and portals from one call.
+ */
+export function createWorldMesh(options: WorldMeshOptions): WorldMeshHandle {
+  const { scene, camera, renderer } = options;
+  const spawn = new Vector3(...(options.spawn ?? [0, 2, 0]));
+  const abilities = resolveAbilities(options.abilities);
+
+  const height = options.player?.height ?? 1.8;
+  const radius = options.player?.radius ?? 0.35;
+
+  const collision = new CollisionWorld(options.colliders ?? [], options.groundLevel ?? 0);
+  const events = new Emitter<WorldMeshEvents>();
+
+  const overlay = new Overlay({
+    ...options.ui,
+    onEnter: (touch) => input.requestPointerLock(touch),
+    onInteract: () => {
+      if (activePortal) {
+        activatePortal(activePortal);
+      } else {
+        input.triggerAction('interact');
+      }
+    },
+  });
+
+  const input = new Input({
+    element: renderer.domElement,
+    keymap: options.keymap,
+    onPointerLockChange: (locked) => {
+      overlay.setLocked(locked);
+      events.emit('pointer:lock', { locked });
+    },
+  });
+
+  const cameraRig = new CameraRig({ ...options.view, camera, collision });
+  const player = new Player({ ...options.player, height, radius });
+  if (player.root) scene.add(player.root);
+
+  const controller = new MovementController({
+    input,
+    collision,
+    abilities,
+    tuning: options.movement,
+    height,
+    radius,
+    spawn,
+  });
+
+  const portals = new PortalManager(scene, options.portals);
+
+  let running = false;
+  let frameHandle = 0;
+  let lastTime = 0;
+  let elapsed = 0;
+  let activePortal: ResolvedPortal | null = null;
+  let disposed = false;
+
+  const handle: WorldMeshHandle = {
+    scene,
+    camera,
+    renderer,
+    abilities,
+    avatar: player.root,
+
+    start,
+    stop,
+    update,
+    dispose,
+
+    getState,
+    setState,
+    teleport,
+    respawn: () => doRespawn('manual'),
+
+    setViewMode,
+    getViewMode: () => cameraRig.mode,
+
+    addPortal: (portal) => {
+      portals.add(portal);
+    },
+    travelTo,
+
+    on: (event, fn) => events.on(event, fn),
+    off: (event, fn) => events.off(event, fn),
+
+    refreshColliders: () => collision.refresh(),
+  };
+
+  applyViewVisibility();
+
+  if (options.autoResize !== false) window.addEventListener('resize', handleResize);
+  handleResize();
+
+  if (options.autoStart !== false) start();
+
+  options.network?.attach(handle);
+
+  return handle;
+
+  function start(): void {
+    if (running || disposed) return;
+    running = true;
+    lastTime = performance.now();
+    frameHandle = requestAnimationFrame(frame);
+  }
+
+  function stop(): void {
+    running = false;
+    if (frameHandle) cancelAnimationFrame(frameHandle);
+    frameHandle = 0;
+  }
+
+  function frame(now: number): void {
+    if (!running) return;
+    frameHandle = requestAnimationFrame(frame);
+    const dt = Math.min((now - lastTime) / 1000, MAX_FRAME);
+    lastTime = now;
+    update(dt);
+    options.onUpdate?.(dt, handle);
+    renderer.render(scene, camera);
+  }
+
+  /** Advance the simulation. Split from rendering so a fixed tick can drive it. */
+  function update(dt: number): void {
+    if (dt <= 0) return;
+    elapsed += dt;
+
+    const look = input.readLook();
+    if (input.locked) {
+      cameraRig.look(look.dx, look.dy);
+      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);
+      if (expression) player.setExpression(expression);
+    }
+
+    // Fixed substeps keep movement stable regardless of frame rate.
+    let remaining = dt;
+    while (remaining > 0) {
+      const step = Math.min(remaining, MAX_STEP);
+      controller.step(step, cameraRig.yaw, input.locked);
+      remaining -= step;
+    }
+
+    if (controller.position.y < controller.tuning.fallLimit) doRespawn('fell');
+
+    cameraRig.update(dt, controller.position, player.eyeHeight * (controller.height / height));
+    player.sync(controller.position, cameraRig.yaw, controller.height, {
+      dt,
+      speed: Math.hypot(controller.velocity.x, controller.velocity.z),
+      grounded: controller.onGround || controller.flying,
+      heading: Math.atan2(-controller.velocity.x, -controller.velocity.z),
+    }, cameraRig.mode === 'third');
+    portals.animate(elapsed);
+
+    updatePortals();
+    input.endFrame();
+
+    events.emit('update', { dt, state: getState() });
+  }
+
+  function updatePortals(): void {
+    const nearest = portals.findActive(controller.position);
+
+    if (nearest !== activePortal) {
+      if (activePortal) events.emit('portal:exit', { portal: activePortal });
+      if (nearest) events.emit('portal:enter', { portal: nearest });
+      activePortal = nearest;
+    }
+
+    if (!nearest) {
+      overlay.setPrompt(null);
+      if (input.locked && input.consume('interact')) {
+        events.emit('interact', { position: controller.position.toArray() as Vec3Tuple });
+      }
+      return;
+    }
+
+    if (nearest.mode === 'auto') {
+      overlay.setPrompt(`Entering ${nearest.label}…`);
+      activatePortal(nearest);
+      return;
+    }
+
+    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);
+  }
+
+  function activatePortal(portal: ResolvedPortal): void {
+    const url = buildTravelUrl(portal.url);
+    let cancelled = false;
+    events.emit('portal:activate', {
+      portal,
+      url,
+      preventDefault: () => {
+        cancelled = true;
+      },
+    });
+    if (cancelled) return;
+    input.exitPointerLock();
+    window.location.href = url;
+  }
+
+  function setViewMode(mode: ViewMode): void {
+    if (cameraRig.mode === mode) return;
+    cameraRig.setMode(mode);
+    applyViewVisibility();
+    events.emit('view:change', { mode });
+  }
+
+  /** In first person the avatar would fill the screen. */
+  function applyViewVisibility(): void {
+    player.setVisible(cameraRig.mode === 'third');
+  }
+
+  function getState(): PlayerState {
+    return {
+      position: controller.position.toArray() as Vec3Tuple,
+      velocity: controller.velocity.toArray() as Vec3Tuple,
+      yaw: cameraRig.yaw,
+      pitch: cameraRig.pitch,
+      facing: player.facing,
+      onGround: controller.onGround,
+      crouching: controller.crouching,
+      flying: controller.flying,
+      expression: player.expression,
+    };
+  }
+
+  function setState(state: Partial<PlayerState>): void {
+    if (state.position) controller.position.set(...state.position);
+    if (state.velocity) controller.velocity.set(...state.velocity);
+    if (typeof state.yaw === 'number') cameraRig.yaw = state.yaw;
+    if (typeof state.facing === 'number') player.facing = state.facing;
+    if (typeof state.pitch === 'number') cameraRig.pitch = state.pitch;
+    if (typeof state.flying === 'boolean') controller.flying = state.flying;
+    if (isAvatarExpression(state.expression)) player.setExpression(state.expression);
+  }
+
+  function teleport(position: Vec3Tuple, yaw?: number): void {
+    controller.reset(new Vector3(...position));
+    if (typeof yaw === 'number') {
+      cameraRig.yaw = yaw;
+      player.facing = yaw;
+    }
+  }
+
+  function doRespawn(reason: 'fell' | 'manual'): void {
+    controller.reset(spawn);
+    events.emit('respawn', { reason });
+  }
+
+  function travelTo(url: string): void {
+    input.exitPointerLock();
+    window.location.href = buildTravelUrl(url);
+  }
+
+  function handleResize(): void {
+    const width = window.innerWidth;
+    const viewHeight = window.innerHeight;
+    // Pixel ratio first: setSize derives the drawing buffer from it, and it
+    // must also update the canvas CSS size or the canvas overflows the window.
+    renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
+    renderer.setSize(width, viewHeight);
+    cameraRig.resize(width, viewHeight);
+  }
+
+  function dispose(): void {
+    if (disposed) return;
+    disposed = true;
+    stop();
+    window.removeEventListener('resize', handleResize);
+    options.network?.detach?.();
+    input.dispose();
+    overlay.dispose();
+    portals.dispose();
+    player.dispose();
+    events.clear();
+  }
+}

package/src/index.ts

@@ -0,0 +1,46 @@
+export { createWorldMesh } from './core/worldmesh.js';
+export { Emitter } from './core/events.js';
+export { Input } from './controls/input.js';
+export { TouchControls, isTouchDevice } from './controls/touch.js';
+export { DEFAULT_KEYMAP, resolveKeymap } from './controls/keymap.js';
+export { DEFAULT_ABILITIES, resolveAbilities } from './abilities/abilities.js';
+export { CollisionWorld } from './movement/collision.js';
+export { DEFAULT_TUNING, MovementController } from './movement/controller.js';
+export { CameraRig } from './camera/cameraRig.js';
+export { Player } from './player/player.js';
+export {
+  AVATAR_EXPRESSIONS,
+  animateDefaultAvatar,
+  createDefaultAvatar,
+  expressionForDigit,
+  getAvatarExpression,
+  isAvatarExpression,
+  setAvatarExpression,
+} from './player/avatar.js';
+export type { AvatarExpression, AvatarMotion } from './player/avatar.js';
+export { PortalManager, buildTravelUrl, getReferringWorld } from './portals/portals.js';
+export { Overlay } from './ui/overlay.js';
+export { deserializePlayerState, serializePlayerState } from './net/adapter.js';
+
+export const WORLDMESH_VERSION = '0.1.0';
+/** Bumped when the world-facing contract changes in an incompatible way. */
+export const WORLDMESH_PROTOCOL = 1;
+
+export type {
+  Abilities,
+  InputAction,
+  Keymap,
+  MovementTuning,
+  NetworkAdapter,
+  PlayerOptions,
+  PlayerState,
+  PortalMode,
+  PortalOptions,
+  UiOptions,
+  Vec3Tuple,
+  ViewMode,
+  ViewOptions,
+  WorldMeshEvents,
+  WorldMeshHandle,
+  WorldMeshOptions,
+} from './types.js';

package/src/movement/collision.ts

@@ -0,0 +1,109 @@
+import { Object3D, Raycaster, Vector3 } from 'three';
+
+const DOWN = new Vector3(0, -1, 0);
+
+export interface GroundSample {
+  /**
+   * Surface height under the player. `-Infinity` when the world has colliders
+   * but none of them are below the player — that is a hole, and the player
+   * should keep falling rather than snap to an imaginary floor.
+   */
+  y: number;
+  hit: boolean;
+}
+
+/**
+ * Deliberately minimal collision: raycasts against a world-supplied list of
+ * meshes. No physics engine, no broadphase. It is enough to stand on things
+ * and to stop walking through walls, which is all the MVP needs to prove that
+ * one controller works across five very different worlds.
+ */
+export class CollisionWorld {
+  private raycaster = new Raycaster();
+  private colliders: Object3D[] = [];
+  private source: Object3D[] | (() => Object3D[]);
+  /** Y used when a world supplies no colliders at all. */
+  groundLevel: number;
+
+  constructor(source: Object3D[] | (() => Object3D[]) = [], groundLevel = 0) {
+    this.source = source;
+    this.groundLevel = groundLevel;
+    this.refresh();
+  }
+
+  refresh(): void {
+    this.colliders = typeof this.source === 'function' ? this.source() : this.source;
+  }
+
+  get isEmpty(): boolean {
+    return this.colliders.length === 0;
+  }
+
+  /**
+   * Find the ground under `position`. `stepHeight` lets the player walk up
+   * small ledges without jumping; `maxDrop` limits how far down we look.
+   */
+  sampleGround(position: Vector3, stepHeight = 0.6, maxDrop = 4): GroundSample {
+    if (this.isEmpty) return { y: this.groundLevel, hit: false };
+
+    this.raycaster.set(new Vector3(position.x, position.y + stepHeight, position.z), DOWN);
+    this.raycaster.far = stepHeight + maxDrop;
+    const hits = this.raycaster.intersectObjects(this.colliders, true);
+    const hit = hits.find((candidate) => candidate.face !== null) ?? hits[0];
+    if (!hit) return { y: -Infinity, hit: false };
+    return { y: hit.point.y, hit: true };
+  }
+
+  /**
+   * Slide a horizontal movement `delta` along whatever it runs into.
+   * Two passes so that sliding into a corner does not tunnel through it.
+   */
+  resolveHorizontal(feet: Vector3, delta: Vector3, radius: number, height: number): Vector3 {
+    const result = delta.clone();
+    if (this.isEmpty || (result.x === 0 && result.z === 0)) return result;
+
+    // Probe up the body: a knee-only ray walks through railings, a chest-only
+    // ray walks through crates, and two rays miss anything between them.
+    const heights = [height * 0.15, height * 0.4, height * 0.65, height * 0.9];
+    const probe = new Vector3();
+    const direction = new Vector3();
+
+    for (let pass = 0; pass < 2; pass++) {
+      const distance = Math.hypot(result.x, result.z);
+      if (distance < 1e-5) break;
+      direction.set(result.x, 0, result.z).divideScalar(distance);
+
+      let blocked = false;
+      for (const offset of heights) {
+        probe.set(feet.x, feet.y + offset, feet.z);
+        this.raycaster.set(probe, direction);
+        this.raycaster.far = distance + radius;
+        const hit = this.raycaster.intersectObjects(this.colliders, true)[0];
+        if (!hit || !hit.face) continue;
+
+        const normal = hit.face.normal.clone().transformDirection(hit.object.matrixWorld);
+        normal.y = 0;
+        if (normal.lengthSq() < 1e-6) continue;
+        normal.normalize();
+
+        const into = result.dot(normal);
+        if (into < 0) {
+          result.addScaledVector(normal, -into);
+          blocked = true;
+        }
+      }
+      if (!blocked) break;
+    }
+
+    return result;
+  }
+
+  /** Distance from `origin` along `direction` before hitting something. */
+  castDistance(origin: Vector3, direction: Vector3, far: number): number {
+    if (this.isEmpty) return far;
+    this.raycaster.set(origin, direction);
+    this.raycaster.far = far;
+    const hit = this.raycaster.intersectObjects(this.colliders, true)[0];
+    return hit ? hit.distance : far;
+  }
+}