@worldmesh/runtime 0.1.0

package/src/controls/input.ts

@@ -0,0 +1,252 @@
+import type { InputAction, Keymap } from '../types.js';
+import { resolveKeymap } from './keymap.js';
+import { TouchControls, isTouchDevice } from './touch.js';
+
+export interface InputOptions {
+  /** The element that receives pointer lock. */
+  element: HTMLElement;
+  keymap?: Partial<Keymap>;
+  onPointerLockChange?: (locked: boolean) => void;
+}
+
+/**
+ * Keyboard + pointer-lock mouse input with mobile touch controls support.
+ * This is the only place in WorldMesh that reads raw browser events, so the
+ * control convention lives in one file instead of being copy-pasted into every world.
+ */
+export class Input {
+  readonly keymap: Keymap;
+  /** Accumulated mouse movement since the last read, in pixels. */
+  mouseDeltaX = 0;
+  mouseDeltaY = 0;
+  /** Accumulated wheel movement since the last read. */
+  wheelDelta = 0;
+  locked = false;
+
+  private element: HTMLElement;
+  private pressed = new Set<string>();
+  /** Actions that went down this frame and have not been consumed yet. */
+  private justPressed = new Set<InputAction>();
+  /** The last number key pressed this frame, if any. */
+  private pendingDigit: number | null = null;
+  private codeToActions = new Map<string, InputAction[]>();
+  private onPointerLockChange?: (locked: boolean) => void;
+  private touch?: TouchControls;
+  private disposed = false;
+
+  constructor(options: InputOptions) {
+    this.element = options.element;
+    this.keymap = resolveKeymap(options.keymap);
+    this.onPointerLockChange = options.onPointerLockChange;
+
+    for (const action of Object.keys(this.keymap) as InputAction[]) {
+      for (const code of this.keymap[action]) {
+        const list = this.codeToActions.get(code) ?? [];
+        list.push(action);
+        this.codeToActions.set(code, list);
+      }
+    }
+
+    // Touch controls on mobile / touchscreens
+    this.element.style.touchAction = 'none';
+    if (typeof window !== 'undefined') {
+      this.touch = new TouchControls({
+        element: this.element,
+        onExit: () => this.exitPointerLock(),
+      });
+    }
+
+    window.addEventListener('keydown', this.handleKeyDown);
+    window.addEventListener('keyup', this.handleKeyUp);
+    window.addEventListener('blur', this.handleBlur);
+    document.addEventListener('pointerlockchange', this.handlePointerLockChange);
+    document.addEventListener('pointerlockerror', this.handlePointerLockError);
+    this.element.addEventListener('mousemove', this.handleMouseMove);
+    this.element.addEventListener('wheel', this.handleWheel, { passive: true });
+  }
+
+  requestPointerLock(touchTriggered = false): void {
+    if (this.disposed || this.locked) return;
+
+    // Mobile / touch devices do not support pointer lock. Enter directly.
+    if (touchTriggered || isTouchDevice()) {
+      this.setLocked(true);
+      return;
+    }
+
+    if (typeof this.element.requestPointerLock === 'function') {
+      try {
+        const promise = this.element.requestPointerLock();
+        if (promise && typeof (promise as unknown as Promise<void>).then === 'function') {
+          (promise as unknown as Promise<void>).catch(() => {
+            // Pointer lock rejected (e.g. mobile Safari, tablet, iframe restrictions)
+            this.setLocked(true);
+          });
+          return;
+        }
+      } catch {
+        this.setLocked(true);
+        return;
+      }
+    } else {
+      this.setLocked(true);
+    }
+  }
+
+  setLocked(locked: boolean): void {
+    if (this.locked === locked) return;
+    this.locked = locked;
+    if (!locked) {
+      this.pressed.clear();
+      this.justPressed.clear();
+      this.touch?.reset();
+    }
+    this.touch?.setVisible(locked && isTouchDevice());
+    this.onPointerLockChange?.(this.locked);
+  }
+
+  exitPointerLock(): void {
+    if (document.pointerLockElement === this.element) {
+      document.exitPointerLock();
+    }
+    this.setLocked(false);
+  }
+
+  triggerAction(action: InputAction): void {
+    this.justPressed.add(action);
+  }
+
+  isDown(action: InputAction): boolean {
+    if (this.touch?.isDown(action)) return true;
+    for (const code of this.keymap[action]) if (this.pressed.has(code)) return true;
+    return false;
+  }
+
+  /** True once per key press. Reading it clears the flag. */
+  consume(action: InputAction): boolean {
+    if (this.touch?.consume(action)) return true;
+    if (!this.justPressed.has(action)) return false;
+    this.justPressed.delete(action);
+    return true;
+  }
+
+  /** The number key (0–9) pressed this frame, once. Reading it clears it. */
+  consumeDigit(): number | null {
+    const digit = this.pendingDigit;
+    this.pendingDigit = null;
+    return digit;
+  }
+
+  /** Movement intent on the local XZ plane, already normalized. */
+  getMoveAxis(): { x: number; z: number } {
+    let x = (this.isDown('right') ? 1 : 0) - (this.isDown('left') ? 1 : 0);
+    let z = (this.isDown('backward') ? 1 : 0) - (this.isDown('forward') ? 1 : 0);
+
+    if (this.touch) {
+      const touchAxis = this.touch.getMoveAxis();
+      x += touchAxis.x;
+      z += touchAxis.z;
+    }
+
+    const length = Math.hypot(x, z);
+    if (length === 0) return { x: 0, z: 0 };
+    if (length > 1) return { x: x / length, z: z / length };
+    return { x, z };
+  }
+
+  /** Read and reset the mouse/wheel/touch accumulators. Call once per frame. */
+  readLook(): { dx: number; dy: number; wheel: number } {
+    let dx = this.mouseDeltaX;
+    let dy = this.mouseDeltaY;
+    if (this.touch) {
+      const touchLook = this.touch.readLook();
+      dx += touchLook.dx;
+      dy += touchLook.dy;
+    }
+    const look = { dx, dy, wheel: this.wheelDelta };
+    this.mouseDeltaX = 0;
+    this.mouseDeltaY = 0;
+    this.wheelDelta = 0;
+    return look;
+  }
+
+  /** Drop stale edge-triggers at the end of a frame. */
+  endFrame(): void {
+    this.justPressed.clear();
+    this.pendingDigit = null;
+  }
+
+  dispose(): void {
+    this.disposed = true;
+    this.touch?.dispose();
+    window.removeEventListener('keydown', this.handleKeyDown);
+    window.removeEventListener('keyup', this.handleKeyUp);
+    window.removeEventListener('blur', this.handleBlur);
+    document.removeEventListener('pointerlockchange', this.handlePointerLockChange);
+    document.removeEventListener('pointerlockerror', this.handlePointerLockError);
+    this.element.removeEventListener('mousemove', this.handleMouseMove);
+    this.element.removeEventListener('wheel', this.handleWheel);
+    this.pressed.clear();
+    this.justPressed.clear();
+  }
+
+  private handleKeyDown = (event: KeyboardEvent): void => {
+    if (event.repeat) return;
+    if (isTypingTarget(event.target)) return;
+    const actions = this.codeToActions.get(event.code);
+    if (!actions) {
+      // Unbound number keys pick a face for the avatar.
+      const digit = /^(?:Digit|Numpad)(\d)$/.exec(event.code);
+      if (digit) this.pendingDigit = Number(digit[1]);
+      return;
+    }
+    // Space and the arrow keys scroll the page otherwise.
+    if (event.code === 'Space' || event.code.startsWith('Arrow')) event.preventDefault();
+    this.pressed.add(event.code);
+    for (const action of actions) this.justPressed.add(action);
+  };
+
+  private handleKeyUp = (event: KeyboardEvent): void => {
+    this.pressed.delete(event.code);
+  };
+
+  /** Losing focus must not leave a key stuck down. */
+  private handleBlur = (): void => {
+    this.pressed.clear();
+    this.justPressed.clear();
+  };
+
+  private handleMouseMove = (event: MouseEvent): void => {
+    if (!this.locked) return;
+    this.mouseDeltaX += event.movementX;
+    this.mouseDeltaY += event.movementY;
+  };
+
+  private handleWheel = (event: WheelEvent): void => {
+    if (!this.locked) return;
+    this.wheelDelta += event.deltaY;
+  };
+
+  private handlePointerLockChange = (): void => {
+    const isLocked = document.pointerLockElement === this.element;
+    if (isLocked) {
+      this.setLocked(true);
+    } else if (!isTouchDevice()) {
+      // On non-touch desktop, losing pointer lock releases controls
+      this.setLocked(false);
+    }
+  };
+
+  private handlePointerLockError = (): void => {
+    // If pointer lock failed on desktop / iframe, still let the user enter
+    if (!this.locked) {
+      this.setLocked(true);
+    }
+  };
+}
+
+function isTypingTarget(target: EventTarget | null): boolean {
+  if (!(target instanceof HTMLElement)) return false;
+  const tag = target.tagName;
+  return tag === 'INPUT' || tag === 'TEXTAREA' || target.isContentEditable;
+}

package/src/controls/keymap.ts

@@ -0,0 +1,23 @@
+import type { Keymap } from '../types.js';
+
+/**
+ * The WorldMesh control convention. Every world ships these bindings so that
+ * moving through an unfamiliar world feels like moving through a familiar one.
+ */
+export const DEFAULT_KEYMAP: Keymap = {
+  forward: ['KeyW', 'ArrowUp'],
+  backward: ['KeyS', 'ArrowDown'],
+  left: ['KeyA', 'ArrowLeft'],
+  right: ['KeyD', 'ArrowRight'],
+  jump: ['Space'],
+  sprint: ['ShiftLeft', 'ShiftRight'],
+  interact: ['KeyE'],
+  toggleView: ['KeyV'],
+  crouch: ['KeyC'],
+  fly: ['KeyF'],
+  dash: ['KeyQ'],
+};
+
+export function resolveKeymap(overrides: Partial<Keymap> = {}): Keymap {
+  return { ...DEFAULT_KEYMAP, ...overrides };
+}

package/src/controls/touch.ts

@@ -0,0 +1,378 @@
+import type { InputAction } from '../types.js';
+
+export function isTouchDevice(): boolean {
+  if (typeof window === 'undefined') return false;
+  return (
+    'ontouchstart' in window ||
+    navigator.maxTouchPoints > 0 ||
+    (typeof window.matchMedia === 'function' && window.matchMedia('(pointer: coarse)').matches)
+  );
+}
+
+const TOUCH_STYLE_ID = 'worldmesh-touch-style';
+
+const TOUCH_CSS = `
+.wm-touch-root {
+  position: fixed;
+  inset: 0;
+  pointer-events: none;
+  z-index: 2147482990;
+  user-select: none;
+  -webkit-user-select: none;
+  font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+}
+.wm-touch-joystick-base {
+  position: absolute;
+  width: 112px;
+  height: 112px;
+  margin: -56px 0 0 -56px;
+  border-radius: 50%;
+  border: 2px solid rgba(255, 255, 255, 0.28);
+  background: rgba(8, 11, 16, 0.4);
+  backdrop-filter: blur(4px);
+  pointer-events: none;
+  will-change: transform;
+  transition: opacity .15s ease;
+}
+/* Resting in the bottom-left corner so players can see where to put a thumb. */
+.wm-touch-joystick-base.wm-idle {
+  left: calc(env(safe-area-inset-left, 0px) + 84px);
+  top: calc(100% - env(safe-area-inset-bottom, 0px) - 104px);
+  opacity: 0.6;
+}
+.wm-touch-joystick-knob {
+  position: absolute;
+  left: 50%;
+  top: 50%;
+  width: 44px;
+  height: 44px;
+  margin: -22px 0 0 -22px;
+  border-radius: 50%;
+  background: rgba(255, 255, 255, 0.65);
+  box-shadow: 0 0 12px rgba(255, 255, 255, 0.35);
+  pointer-events: none;
+  will-change: transform;
+}
+.wm-touch-buttons {
+  position: absolute;
+  right: calc(env(safe-area-inset-right, 0px) + 20px);
+  bottom: calc(env(safe-area-inset-bottom, 0px) + 24px);
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 12px;
+  pointer-events: none;
+}
+.wm-touch-btn {
+  pointer-events: auto;
+  border-radius: 50%;
+  border: 1.5px solid rgba(255, 255, 255, 0.32);
+  background: rgba(8, 11, 16, 0.65);
+  backdrop-filter: blur(4px);
+  color: #fff;
+  font-family: inherit;
+  font-weight: 600;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+  -webkit-tap-highlight-color: transparent;
+  touch-action: none;
+  transition: transform .08s ease, background .08s ease;
+  padding: 0;
+}
+.wm-touch-btn:active {
+  background: rgba(255, 255, 255, 0.25);
+  transform: scale(0.92);
+}
+.wm-btn-jump {
+  width: 58px;
+  height: 58px;
+  font-size: 18px;
+}
+.wm-btn-interact {
+  width: 48px;
+  height: 48px;
+  font-size: 14px;
+  letter-spacing: .05em;
+}
+.wm-btn-view {
+  width: 40px;
+  height: 40px;
+  font-size: 14px;
+  opacity: 0.85;
+}
+.wm-touch-menu-btn {
+  position: absolute;
+  top: 14px;
+  right: 14px;
+  width: 40px;
+  height: 40px;
+  border-radius: 10px;
+  border: 1px solid rgba(255, 255, 255, 0.22);
+  background: rgba(8, 11, 16, 0.6);
+  backdrop-filter: blur(4px);
+  color: #fff;
+  font-size: 15px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+  pointer-events: auto;
+  touch-action: manipulation;
+  -webkit-tap-highlight-color: transparent;
+  padding: 0;
+}
+.wm-touch-menu-btn:active {
+  background: rgba(255, 255, 255, 0.22);
+}
+`;
+
+function injectTouchStyles(): void {
+  if (typeof document === 'undefined' || document.getElementById(TOUCH_STYLE_ID)) return;
+  const style = document.createElement('style');
+  style.id = TOUCH_STYLE_ID;
+  style.textContent = TOUCH_CSS;
+  document.head.appendChild(style);
+}
+
+export interface TouchControlsOptions {
+  element?: HTMLElement;
+  onExit?: () => void;
+}
+
+export class TouchControls {
+  private root: HTMLDivElement;
+  private joystickBase: HTMLDivElement;
+  private joystickKnob: HTMLDivElement;
+  private onExit?: () => void;
+
+  private movePointerId: number | null = null;
+  private moveStart = { x: 0, y: 0 };
+  private moveAxis = { x: 0, z: 0 };
+
+  private lookPointerId: number | null = null;
+  private lookPrev = { x: 0, y: 0 };
+  private lookDelta = { dx: 0, dy: 0 };
+
+  private actionsDown = new Set<InputAction>();
+  private justPressed = new Set<InputAction>();
+
+  private disposed = false;
+  private visible = false;
+
+  constructor(options: TouchControlsOptions) {
+    this.onExit = options.onExit;
+
+    injectTouchStyles();
+
+    this.root = document.createElement('div');
+    this.root.className = 'wm-touch-root';
+    this.root.style.display = 'none';
+
+    // Joystick UI
+    this.joystickBase = document.createElement('div');
+    this.joystickBase.className = 'wm-touch-joystick-base wm-idle';
+    this.joystickKnob = document.createElement('div');
+    this.joystickKnob.className = 'wm-touch-joystick-knob';
+    this.joystickBase.appendChild(this.joystickKnob);
+    this.root.appendChild(this.joystickBase);
+
+    // Action buttons (bottom right)
+    const buttons = document.createElement('div');
+    buttons.className = 'wm-touch-buttons';
+
+    const viewBtn = this.createActionButton('V', 'toggleView', 'wm-btn-view', 'Camera mode');
+    const interactBtn = this.createActionButton('E', 'interact', 'wm-btn-interact', 'Interact');
+    const jumpBtn = this.createActionButton('▲', 'jump', 'wm-btn-jump', 'Jump');
+
+    buttons.append(viewBtn, interactBtn, jumpBtn);
+    this.root.appendChild(buttons);
+
+    // Menu / Pause button (top right)
+    const menuBtn = document.createElement('button');
+    menuBtn.type = 'button';
+    menuBtn.className = 'wm-touch-menu-btn';
+    menuBtn.textContent = '⏸';
+    menuBtn.title = 'Menu / Pause';
+    menuBtn.addEventListener('pointerdown', (e) => {
+      e.stopPropagation();
+      e.preventDefault();
+      this.onExit?.();
+    });
+    this.root.appendChild(menuBtn);
+
+    document.body.appendChild(this.root);
+
+    window.addEventListener('pointerdown', this.handlePointerDown);
+    window.addEventListener('pointermove', this.handlePointerMove);
+    window.addEventListener('pointerup', this.handlePointerUp);
+    window.addEventListener('pointercancel', this.handlePointerUp);
+  }
+
+  private createActionButton(
+    label: string,
+    action: InputAction,
+    className: string,
+    title: string,
+  ): HTMLButtonElement {
+    const btn = document.createElement('button');
+    btn.type = 'button';
+    btn.className = `wm-touch-btn ${className}`;
+    btn.textContent = label;
+    btn.title = title;
+
+    const onDown = (e: PointerEvent) => {
+      e.stopPropagation();
+      e.preventDefault();
+      this.actionsDown.add(action);
+      this.justPressed.add(action);
+    };
+
+    const onUp = (e: PointerEvent) => {
+      e.stopPropagation();
+      e.preventDefault();
+      this.actionsDown.delete(action);
+    };
+
+    btn.addEventListener('pointerdown', onDown);
+    btn.addEventListener('pointerup', onUp);
+    btn.addEventListener('pointercancel', onUp);
+
+    return btn;
+  }
+
+  private handlePointerDown = (e: PointerEvent): void => {
+    if (!this.visible || this.disposed) return;
+    if (e.pointerType !== 'touch' && e.pointerType !== 'pen') return;
+
+    const target = e.target as HTMLElement | null;
+    if (target?.closest('.wm-touch-btn, .wm-touch-menu-btn, .wm-prompt, .wm-badge, .wm-lock')) {
+      return;
+    }
+
+    const halfWidth = window.innerWidth * 0.5;
+
+    // Left half: movement joystick
+    if (this.movePointerId === null && e.clientX < halfWidth) {
+      this.movePointerId = e.pointerId;
+      this.moveAxis = { x: 0, z: 0 };
+      // Grab the resting stick where it is; anywhere else, the stick comes to the thumb.
+      const rest = this.joystickBase.getBoundingClientRect();
+      const restX = rest.left + rest.width / 2;
+      const restY = rest.top + rest.height / 2;
+      const onStick = Math.hypot(e.clientX - restX, e.clientY - restY) < rest.width * 0.75;
+      this.moveStart = onStick ? { x: restX, y: restY } : { x: e.clientX, y: e.clientY };
+      this.joystickBase.classList.remove('wm-idle');
+      this.joystickBase.style.left = `${this.moveStart.x}px`;
+      this.joystickBase.style.top = `${this.moveStart.y}px`;
+      this.joystickKnob.style.transform = '';
+      if (onStick) this.handlePointerMove(e);
+      return;
+    }
+
+    // Right half (or secondary touch): camera look
+    if (this.lookPointerId === null && e.clientX >= halfWidth * 0.8) {
+      this.lookPointerId = e.pointerId;
+      this.lookPrev = { x: e.clientX, y: e.clientY };
+    }
+  };
+
+  private handlePointerMove = (e: PointerEvent): void => {
+    if (!this.visible || this.disposed) return;
+
+    if (e.pointerId === this.movePointerId) {
+      const dx = e.clientX - this.moveStart.x;
+      const dy = e.clientY - this.moveStart.y;
+      const dist = Math.hypot(dx, dy);
+      const maxRadius = 50;
+      const clampedDist = Math.min(dist, maxRadius);
+      const angle = Math.atan2(dy, dx);
+
+      const knobX = Math.cos(angle) * clampedDist;
+      const knobY = Math.sin(angle) * clampedDist;
+      this.joystickKnob.style.transform = `translate(${knobX}px, ${knobY}px)`;
+
+      this.moveAxis.x = clampedDist > 0 ? knobX / maxRadius : 0;
+      this.moveAxis.z = clampedDist > 0 ? knobY / maxRadius : 0;
+      return;
+    }
+
+    if (e.pointerId === this.lookPointerId) {
+      const dx = e.clientX - this.lookPrev.x;
+      const dy = e.clientY - this.lookPrev.y;
+      this.lookPrev = { x: e.clientX, y: e.clientY };
+      this.lookDelta.dx += dx * 1.4;
+      this.lookDelta.dy += dy * 1.4;
+    }
+  };
+
+  private handlePointerUp = (e: PointerEvent): void => {
+    if (e.pointerId === this.movePointerId) {
+      this.movePointerId = null;
+      this.moveAxis = { x: 0, z: 0 };
+      this.restJoystick();
+    }
+    if (e.pointerId === this.lookPointerId) {
+      this.lookPointerId = null;
+    }
+  };
+
+  getMoveAxis(): { x: number; z: number } {
+    return this.moveAxis;
+  }
+
+  readLook(): { dx: number; dy: number } {
+    const res = { dx: this.lookDelta.dx, dy: this.lookDelta.dy };
+    this.lookDelta = { dx: 0, dy: 0 };
+    return res;
+  }
+
+  isDown(action: InputAction): boolean {
+    return this.actionsDown.has(action);
+  }
+
+  consume(action: InputAction): boolean {
+    if (!this.justPressed.has(action)) return false;
+    this.justPressed.delete(action);
+    return true;
+  }
+
+  triggerAction(action: InputAction): void {
+    this.justPressed.add(action);
+  }
+
+  setVisible(visible: boolean): void {
+    this.visible = visible;
+    this.root.style.display = visible ? 'block' : 'none';
+    if (!visible) {
+      this.reset();
+    }
+  }
+
+  reset(): void {
+    this.movePointerId = null;
+    this.lookPointerId = null;
+    this.moveAxis = { x: 0, z: 0 };
+    this.lookDelta = { dx: 0, dy: 0 };
+    this.actionsDown.clear();
+    this.justPressed.clear();
+    this.restJoystick();
+  }
+
+  private restJoystick(): void {
+    this.joystickBase.classList.add('wm-idle');
+    this.joystickBase.style.left = '';
+    this.joystickBase.style.top = '';
+    this.joystickKnob.style.transform = '';
+  }
+
+  dispose(): void {
+    this.disposed = true;
+    window.removeEventListener('pointerdown', this.handlePointerDown);
+    window.removeEventListener('pointermove', this.handlePointerMove);
+    window.removeEventListener('pointerup', this.handlePointerUp);
+    window.removeEventListener('pointercancel', this.handlePointerUp);
+    this.root.remove();
+  }
+}

package/src/core/events.ts

@@ -0,0 +1,31 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+type AnyListener = (payload: any) => void;
+
+/** Tiny typed event bus. Deliberately no dependencies. */
+export class Emitter<Events extends object> {
+  private listeners = new Map<keyof Events, Set<AnyListener>>();
+
+  on<K extends keyof Events>(event: K, fn: (payload: Events[K]) => void): () => void {
+    let set = this.listeners.get(event);
+    if (!set) {
+      set = new Set();
+      this.listeners.set(event, set);
+    }
+    set.add(fn);
+    return () => this.off(event, fn);
+  }
+
+  off<K extends keyof Events>(event: K, fn: (payload: Events[K]) => void): void {
+    this.listeners.get(event)?.delete(fn);
+  }
+
+  emit<K extends keyof Events>(event: K, payload: Events[K]): void {
+    const set = this.listeners.get(event);
+    if (!set) return;
+    for (const fn of [...set]) fn(payload);
+  }
+
+  clear(): void {
+    this.listeners.clear();
+  }
+}