@worldmesh/runtime 0.2.1 → 0.2.3

package/src/hosted.ts

@@ -0,0 +1,4 @@
+// The entry of the runtime worldmesh.net serves for loadWorldMesh
+// (src/load.ts, scripts/build-hosted.mjs). Not part of the npm entry.
+export { createWorldMesh } from './core/worldmesh.js';
+export { WORLDMESH_PROTOCOL, WORLDMESH_VERSION } from './version.js';

package/src/index.ts

@@ -1,4 +1,4 @@
-export { createWorldMesh } from './core/worldmesh.js';
+export { DOORWAY_VIEW_PARAM, createWorldMesh } from './core/worldmesh.js';
 export { Emitter } from './core/events.js';
 export { Input } from './controls/input.js';
 export { TouchControls, isTouchDevice } from './controls/touch.js';
@@ -7,6 +7,7 @@ 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 { VIEW_PARAM, VIEW_STORAGE_KEY, getRememberedView, rememberView, takeViewHandoff, withView } from './camera/viewHandoff.js';
 export { Player } from './player/player.js';
 export {
   AVATAR_EXPRESSIONS,
@@ -20,9 +21,10 @@ export {
   setAvatarColor,
 } from './player/avatar.js';
 export type { AvatarExpression, AvatarMotion } from './player/avatar.js';
+export { isStrokeMaterial, setFigureStroke, setStrokeOpacity } from './player/stroke.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 { isLoadableUrl, parseAvatarDescriptor, parseAvatarShare } from './avatar/descriptor.js';
+export type { AvatarDescriptor, AvatarFormat, SignedAvatarShare } from './avatar/descriptor.js';
 export {
   AVATAR_TICKET_PARAM,
   AVATAR_TICKET_STORAGE_KEY,
@@ -32,16 +34,21 @@ export {
   takeAvatarTicket,
   withAvatarTicket,
 } from './avatar/handoff.js';
-export { loadAvatarModel } from './avatar/loader.js';
+export { downloadAvatarModel, loadAvatarModel } from './avatar/loader.js';
 export type { LoadAvatarOptions, LoadedAvatar } from './avatar/loader.js';
 export { Overlay } from './ui/overlay.js';
+export { immersiveVrSupported, requestImmersiveVr, IMMERSIVE_VR } from './xr/session.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 { DEFAULT_PRESENCE_SERVER, Presence, createNameTag, createSpeechBubble } from './net/presence.js';
+export { easeYaw } from './net/follow.js';
+export type { PresenceOptions, SharedAvatar } from './net/presence.js';
+export { SharedAvatarLink, createShareVerifier, shareableAvatar } from './avatar/share.js';
+export { isOverAllowanceSignal, isRoomFullSignal, occupancyIsFull, occupancyProbeUrl, probeRoom, probeRoomFull, roomFullLabel } from './net/roomFull.js';
+export type { RoomProbe } from './net/roomFull.js';
 
-export const WORLDMESH_VERSION = '0.2.1';
-/** Bumped when the world-facing contract changes in an incompatible way. */
-export const WORLDMESH_PROTOCOL = 1;
+export { WORLDMESH_PROTOCOL, WORLDMESH_VERSION } from './version.js';
+export { HOSTED_RUNTIME_URL, loadWorldMesh } from './load.js';
+export type { LoadWorldMeshOptions } from './load.js';
 
 export type {
   Abilities,

package/src/load.ts

@@ -0,0 +1,103 @@
+import * as THREE from 'three';
+import type { WorldMeshHandle, WorldMeshOptions } from './types.js';
+import { WORLDMESH_PROTOCOL, WORLDMESH_VERSION } from './version.js';
+
+/**
+ * The current runtime for this protocol, served by WorldMesh
+ * (scripts/build-hosted.mjs). `loadWorldMesh` runs it, so a fix reaches a
+ * world the next time it is opened, without the world rebuilding.
+ */
+export const HOSTED_RUNTIME_URL = `https://worldmesh.net/runtime/${WORLDMESH_PROTOCOL}/index.js`;
+
+/** Where the hosted runtime picks up the world's own Three.js (scripts/build-hosted.mjs). */
+const THREE_KEY = Symbol.for('worldmesh.three');
+const DEFAULT_TIMEOUT_MS = 8000;
+/**
+ * The runtime is asked for at a new URL this often, which bounds how long a
+ * browser keeps an old one. Cache headers can't: worldmesh.net's Browser
+ * Cache TTL stretches any shorter max-age on a .js file to 4 hours.
+ */
+const REFRESH_MS = 5 * 60_000;
+
+export interface LoadWorldMeshOptions {
+  /** Run the runtime from here instead: a preview or a self-hosted copy. */
+  url?: string;
+  /** Give up on it after this many milliseconds and use the bundled copy. Default 8000. */
+  timeoutMs?: number;
+  /** false: always use the copy bundled with the world, as `createWorldMesh` does. */
+  hosted?: boolean;
+}
+
+/** What the hosted runtime exports (src/hosted.ts). */
+interface HostedRuntime {
+  createWorldMesh(options: WorldMeshOptions): WorldMeshHandle;
+  WORLDMESH_PROTOCOL: number;
+  WORLDMESH_VERSION: string;
+}
+
+const loading = new Map<string, Promise<HostedRuntime | null>>();
+
+/**
+ * `createWorldMesh`, kept current: runs the latest runtime WorldMesh serves for
+ * this protocol, with the world's own Three.js. If that cannot be loaded in
+ * time, or does not start, the copy bundled with the world runs instead, so
+ * the world works as it did when it was built.
+ */
+export async function loadWorldMesh(options: WorldMeshOptions, load: LoadWorldMeshOptions = {}): Promise<WorldMeshHandle> {
+  const useHosted = load.hosted !== false && typeof window !== 'undefined';
+  const hosted = useHosted ? await hostedRuntime(load.url ?? HOSTED_RUNTIME_URL, load.timeoutMs ?? DEFAULT_TIMEOUT_MS) : null;
+  if (hosted) {
+    try {
+      return hosted.createWorldMesh(options);
+    } catch (error) {
+      console.warn(`[WorldMesh] Runtime ${hosted.WORLDMESH_VERSION} did not start; using the copy bundled with this world (${WORLDMESH_VERSION}).`, error);
+    }
+  }
+  const { createWorldMesh } = await import('./core/worldmesh.js');
+  return createWorldMesh(options);
+}
+
+function hostedRuntime(url: string, timeoutMs: number): Promise<HostedRuntime | null> {
+  let pending = loading.get(url);
+  if (!pending) {
+    pending = importHosted(url, timeoutMs);
+    loading.set(url, pending);
+  }
+  return pending;
+}
+
+async function importHosted(url: string, timeoutMs: number): Promise<HostedRuntime | null> {
+  const shared = globalThis as unknown as Record<symbol, unknown>;
+  shared[THREE_KEY] ??= THREE;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<null>((resolve) => {
+    timer = setTimeout(() => resolve(null), timeoutMs);
+  });
+  const fallback = `using the copy bundled with this world (${WORLDMESH_VERSION})`;
+  try {
+    // Left to the browser: bundlers must not try to resolve or inline it.
+    const imported = import(/* webpackIgnore: true */ /* @vite-ignore */ refreshed(url)) as Promise<HostedRuntime>;
+    const runtime = await Promise.race([imported, timeout]);
+    if (!runtime) {
+      console.info(`[WorldMesh] ${url} took longer than ${timeoutMs} ms; ${fallback}.`);
+      return null;
+    }
+    if (runtime.WORLDMESH_PROTOCOL !== WORLDMESH_PROTOCOL || typeof runtime.createWorldMesh !== 'function') {
+      console.warn(`[WorldMesh] ${url} is not a protocol ${WORLDMESH_PROTOCOL} runtime; ${fallback}.`);
+      return null;
+    }
+    return runtime;
+  } catch (error) {
+    console.info(`[WorldMesh] Could not load ${url}; ${fallback}.`, error);
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** `url` with `v` set to the current REFRESH_MS slot, e.g. `…/index.js?v=5867331`. */
+function refreshed(url: string): string {
+  const fresh = new URL(url, globalThis.location?.href);
+  fresh.searchParams.set('v', String(Math.floor(Date.now() / REFRESH_MS)));
+  return fresh.href;
+}

package/src/net/follow.ts

@@ -0,0 +1,9 @@
+/**
+ * Turn `yaw` toward `target` by `blend` (0 to 1) of the way, the short way
+ * round. Radians; the result is not wrapped. Remote figures ease toward the
+ * facing their owner last reported with this.
+ */
+export function easeYaw(yaw: number, target: number, blend: number): number {
+  const delta = Math.atan2(Math.sin(target - yaw), Math.cos(target - yaw));
+  return yaw + delta * blend;
+}