@worldmesh/runtime 0.1.0 → 0.2.1

package/README.md

@@ -3,7 +3,7 @@
 The shared [WorldMesh](https://github.com/eliaswillnat/worldmesh) navigation
 runtime: controls, movement, camera, player, abilities and portals.
 
-WorldMesh is a lightweight open network for independently hosted 3D worlds. It
+WorldMesh is an open network for independently hosted 3D worlds, connected across the web. It
 supplies the one thing separately hosted worlds need in common — a navigation
 standard — so that moving through an unfamiliar world feels like moving through
 a familiar one. This package is that standard, as code.
@@ -45,6 +45,24 @@ devices, the shared overlay and portals between worlds.
 Removing the `createWorldMesh` call leaves you with the Three.js project you
 started with.
 
+## Visitors' own avatars (optional)
+
+```js
+createWorldMesh({ scene, camera, renderer, avatar: { source: 'worldmesh' } });
+```
+
+Visitors who picked a character in their WorldMesh Avatar Wallet (VRoid Hub,
+at3d) arrive with a short-lived ticket in the URL fragment. The runtime removes
+it from the address bar, asks the hub for a descriptor, and loads the VRM or
+glTF straight from the platform that hosts it. Portals carry the ticket on.
+Without a ticket, or if anything fails, the player keeps the default body.
+Your world never receives the visitor's account, session or platform tokens.
+
+Already have a model URL? Pass `avatar: { source: 'descriptor', descriptor }`,
+or call `world.loadAvatar(descriptor)` / `world.clearAvatar()` at any time.
+`avatar:load` and `avatar:error` events report the outcome. The VRM and glTF
+loaders (`@pixiv/three-vrm`) are only downloaded when an avatar is shown.
+
 ## What is exported
 
 | | |
@@ -54,8 +72,9 @@ started with.
 | `MovementController`, `CollisionWorld`, `DEFAULT_TUNING` | movement and collision |
 | `CameraRig`, `Player`, `createDefaultAvatar`, `AVATAR_EXPRESSIONS` | camera and figure |
 | `PortalManager`, `buildTravelUrl`, `getReferringWorld` | travel between worlds |
+| `loadAvatarModel`, `resolveWorldMeshAvatar`, `parseAvatarDescriptor`, `AvatarDescriptor` | visitors' own avatars |
 | `Overlay`, `Emitter` | the shared overlay, a tiny typed emitter |
-| `serializePlayerState`, `deserializePlayerState`, `NetworkAdapter` | the multiplayer seam |
+| `Presence`, `DEFAULT_PRESENCE_SERVER`, `NetworkAdapter` | multiplayer (`multiplayer: true`) and the seam for your own |
 | `WORLDMESH_VERSION`, `WORLDMESH_PROTOCOL` | what your world is speaking |
 
 Full option, handle and event reference:

package/dist/avatar/descriptor.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The only thing the runtime knows about external avatars: a normalized
+ * descriptor pointing at a model file the avatar's platform hosts. How it was
+ * found (which platform, which account, which OAuth flow) stays with whoever
+ * produced it — the WorldMesh hub's Avatar Wallet, or the world itself.
+ */
+export type AvatarFormat = 'vrm' | 'glb' | 'gltf';
+export interface AvatarDescriptor {
+    /** Where the avatar lives, e.g. 'vroid' or 'atproto'. Informational. */
+    provider: string;
+    /** The platform's id for the avatar. Informational. */
+    avatarId: string;
+    name: string | null;
+    thumbnail: string | null;
+    format: AvatarFormat;
+    /** The model file, on the platform's own storage. May be short-lived. */
+    modelUrl: string;
+    /** When `modelUrl` stops working (ISO 8601), or null. */
+    expiresAt: string | null;
+    /** The avatar's public page, for credit where its license asks for it. */
+    sourceUrl: string | null;
+}
+/** Model URLs must be https, except on a local development machine. */
+export declare function isLoadableUrl(raw: unknown): raw is string;
+/** Accepts a descriptor from the network only if it has the right shape. */
+export declare function parseAvatarDescriptor(value: unknown): AvatarDescriptor | null;
+//# sourceMappingURL=descriptor.d.ts.map

package/dist/avatar/descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptor.d.ts","sourceRoot":"","sources":["../../src/avatar/descriptor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;AAElD,MAAM,WAAW,gBAAgB;IAC/B,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,YAAY,CAAC;IACrB,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,0EAA0E;IAC1E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAID,uEAAuE;AACvE,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,MAAM,CASzD;AAED,4EAA4E;AAC5E,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,GAAG,IAAI,CAe7E"}

package/dist/avatar/descriptor.js

@@ -0,0 +1,41 @@
+/**
+ * The only thing the runtime knows about external avatars: a normalized
+ * descriptor pointing at a model file the avatar's platform hosts. How it was
+ * found (which platform, which account, which OAuth flow) stays with whoever
+ * produced it — the WorldMesh hub's Avatar Wallet, or the world itself.
+ */
+const FORMATS = ['vrm', 'glb', 'gltf'];
+/** Model URLs must be https, except on a local development machine. */
+export function isLoadableUrl(raw) {
+    if (typeof raw !== 'string')
+        return false;
+    try {
+        const url = new URL(raw);
+        if (url.protocol === 'https:')
+            return true;
+        return url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+    }
+    catch {
+        return false;
+    }
+}
+/** Accepts a descriptor from the network only if it has the right shape. */
+export function parseAvatarDescriptor(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const d = value;
+    if (typeof d.format !== 'string' || !FORMATS.includes(d.format) || !isLoadableUrl(d.modelUrl))
+        return null;
+    const text = (v) => (typeof v === 'string' ? v : null);
+    return {
+        provider: text(d.provider) ?? 'unknown',
+        avatarId: text(d.avatarId) ?? '',
+        name: text(d.name),
+        thumbnail: isLoadableUrl(d.thumbnail) ? d.thumbnail : null,
+        format: d.format,
+        modelUrl: d.modelUrl,
+        expiresAt: text(d.expiresAt),
+        sourceUrl: isLoadableUrl(d.sourceUrl) ? d.sourceUrl : null,
+    };
+}
+//# sourceMappingURL=descriptor.js.map

package/dist/avatar/descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptor.js","sourceRoot":"","sources":["../../src/avatar/descriptor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAoBH,MAAM,OAAO,GAAsB,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;AAE1D,uEAAuE;AACvE,MAAM,UAAU,aAAa,CAAC,GAAY;IACxC,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC1C,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QACzB,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAC3C,OAAO,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAChG,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,qBAAqB,CAAC,KAAc;IAClD,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACrD,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,IAAI,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3G,MAAM,IAAI,GAAG,CAAC,CAAU,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAChE,OAAO;QACL,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,SAAS;QACvC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE;QAChC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;QAClB,SAAS,EAAE,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI;QAC1D,MAAM,EAAE,CAAC,CAAC,MAAsB;QAChC,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;QAC5B,SAAS,EAAE,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI;KAC3D,CAAC;AACJ,CAAC"}

package/dist/avatar/handoff.d.ts

@@ -0,0 +1,29 @@
+import { type AvatarDescriptor } from './descriptor.js';
+/**
+ * Carrying a visitor's chosen avatar between worlds.
+ *
+ * The WorldMesh hub appends an opaque, short-lived ticket to a world's URL as
+ * a fragment (`#wm-avatar=…`): fragments are never sent to servers or in
+ * Referer headers. The runtime takes it out of the address bar (so it is not
+ * bookmarked or shared), keeps it in sessionStorage for this tab, and adds it
+ * again to portal destinations so the avatar follows the visitor.
+ *
+ * A ticket only ever resolves to an avatar descriptor. It carries no session,
+ * no account and no platform credentials.
+ */
+export declare const AVATAR_TICKET_PARAM = "wm-avatar";
+/** sessionStorage key. The hub writes the same key. */
+export declare const AVATAR_TICKET_STORAGE_KEY = "worldmesh.avatarTicket";
+/** Moves a ticket from this page's URL fragment into storage, and returns the current one. */
+export declare function takeAvatarTicket(): string | null;
+export declare function getAvatarTicket(): string | null;
+export declare function setAvatarTicket(ticket: string | null): void;
+/** Adds the current ticket to a destination URL's fragment, unless it already has one. */
+export declare function withAvatarTicket(url: URL): URL;
+/**
+ * Exchanges a ticket at the hub for a descriptor. Sends no cookies and no
+ * credentials. Null when the visitor has not chosen an avatar, the ticket has
+ * expired, or the hub cannot be reached.
+ */
+export declare function resolveWorldMeshAvatar(hubUrl: string, ticket: string, timeoutMs?: number): Promise<AvatarDescriptor | null>;
+//# sourceMappingURL=handoff.d.ts.map

package/dist/avatar/handoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff.d.ts","sourceRoot":"","sources":["../../src/avatar/handoff.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAE/E;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,mBAAmB,cAAc,CAAC;AAC/C,uDAAuD;AACvD,eAAO,MAAM,yBAAyB,2BAA2B,CAAC;AAGlE,8FAA8F;AAC9F,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAahD;AAED,wBAAgB,eAAe,IAAI,MAAM,GAAG,IAAI,CAO/C;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAO3D;AAED,0FAA0F;AAC1F,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,GAAG,GAAG,GAAG,CAM9C;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,SAAS,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAsBjI"}

package/dist/avatar/handoff.js

@@ -0,0 +1,92 @@
+import { parseAvatarDescriptor } from './descriptor.js';
+/**
+ * Carrying a visitor's chosen avatar between worlds.
+ *
+ * The WorldMesh hub appends an opaque, short-lived ticket to a world's URL as
+ * a fragment (`#wm-avatar=…`): fragments are never sent to servers or in
+ * Referer headers. The runtime takes it out of the address bar (so it is not
+ * bookmarked or shared), keeps it in sessionStorage for this tab, and adds it
+ * again to portal destinations so the avatar follows the visitor.
+ *
+ * A ticket only ever resolves to an avatar descriptor. It carries no session,
+ * no account and no platform credentials.
+ */
+export const AVATAR_TICKET_PARAM = 'wm-avatar';
+/** sessionStorage key. The hub writes the same key. */
+export const AVATAR_TICKET_STORAGE_KEY = 'worldmesh.avatarTicket';
+const TICKET_PATTERN = /^[A-Za-z0-9_-]{16,256}\.[A-Za-z0-9_-]{16,512}$/;
+/** Moves a ticket from this page's URL fragment into storage, and returns the current one. */
+export function takeAvatarTicket() {
+    const hash = window.location.hash.slice(1);
+    if (hash) {
+        const params = new URLSearchParams(hash);
+        const ticket = params.get(AVATAR_TICKET_PARAM);
+        if (ticket !== null) {
+            params.delete(AVATAR_TICKET_PARAM);
+            const rest = params.toString();
+            history.replaceState(history.state, '', `${window.location.pathname}${window.location.search}${rest ? `#${rest}` : ''}`);
+            if (TICKET_PATTERN.test(ticket))
+                setAvatarTicket(ticket);
+        }
+    }
+    return getAvatarTicket();
+}
+export function getAvatarTicket() {
+    try {
+        const ticket = sessionStorage.getItem(AVATAR_TICKET_STORAGE_KEY);
+        return ticket && TICKET_PATTERN.test(ticket) ? ticket : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function setAvatarTicket(ticket) {
+    try {
+        if (ticket)
+            sessionStorage.setItem(AVATAR_TICKET_STORAGE_KEY, ticket);
+        else
+            sessionStorage.removeItem(AVATAR_TICKET_STORAGE_KEY);
+    }
+    catch {
+        // Storage blocked: the avatar simply does not follow to the next world.
+    }
+}
+/** Adds the current ticket to a destination URL's fragment, unless it already has one. */
+export function withAvatarTicket(url) {
+    const ticket = getAvatarTicket();
+    if (ticket && !url.hash && /^https?:$/.test(url.protocol)) {
+        url.hash = `${AVATAR_TICKET_PARAM}=${ticket}`;
+    }
+    return url;
+}
+/**
+ * Exchanges a ticket at the hub for a descriptor. Sends no cookies and no
+ * credentials. Null when the visitor has not chosen an avatar, the ticket has
+ * expired, or the hub cannot be reached.
+ */
+export async function resolveWorldMeshAvatar(hubUrl, ticket, timeoutMs = 10_000) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(new URL('/api/account/avatar/resolve', hubUrl), {
+            method: 'POST',
+            mode: 'cors',
+            credentials: 'omit',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ ticket }),
+            signal: controller.signal,
+        });
+        if (response.status === 401) {
+            setAvatarTicket(null);
+            return null;
+        }
+        if (!response.ok)
+            return null;
+        const body = (await response.json());
+        return parseAvatarDescriptor(body.avatar);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=handoff.js.map

package/dist/avatar/handoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff.js","sourceRoot":"","sources":["../../src/avatar/handoff.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAyB,MAAM,iBAAiB,CAAC;AAE/E;;;;;;;;;;;GAWG;AAEH,MAAM,CAAC,MAAM,mBAAmB,GAAG,WAAW,CAAC;AAC/C,uDAAuD;AACvD,MAAM,CAAC,MAAM,yBAAyB,GAAG,wBAAwB,CAAC;AAClE,MAAM,cAAc,GAAG,gDAAgD,CAAC;AAExE,8FAA8F;AAC9F,MAAM,UAAU,gBAAgB;IAC9B,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC3C,IAAI,IAAI,EAAE,CAAC;QACT,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,IAAI,CAAC,CAAC;QACzC,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;QAC/C,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;YACpB,MAAM,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC;YACnC,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;YAC/B,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,EAAE,GAAG,MAAM,CAAC,QAAQ,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACzH,IAAI,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC;gBAAE,eAAe,CAAC,MAAM,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;IACD,OAAO,eAAe,EAAE,CAAC;AAC3B,CAAC;AAED,MAAM,UAAU,eAAe;IAC7B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,cAAc,CAAC,OAAO,CAAC,yBAAyB,CAAC,CAAC;QACjE,OAAO,MAAM,IAAI,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;IAC/D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,MAAqB;IACnD,IAAI,CAAC;QACH,IAAI,MAAM;YAAE,cAAc,CAAC,OAAO,CAAC,yBAAyB,EAAE,MAAM,CAAC,CAAC;;YACjE,cAAc,CAAC,UAAU,CAAC,yBAAyB,CAAC,CAAC;IAC5D,CAAC;IAAC,MAAM,CAAC;QACP,wEAAwE;IAC1E,CAAC;AACH,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,gBAAgB,CAAC,GAAQ;IACvC,MAAM,MAAM,GAAG,eAAe,EAAE,CAAC;IACjC,IAAI,MAAM,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1D,GAAG,CAAC,IAAI,GAAG,GAAG,mBAAmB,IAAI,MAAM,EAAE,CAAC;IAChD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,MAAc,EAAE,MAAc,EAAE,SAAS,GAAG,MAAM;IAC7F,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC;IAC9D,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,IAAI,GAAG,CAAC,6BAA6B,EAAE,MAAM,CAAC,EAAE;YAC3E,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,MAAM;YACZ,WAAW,EAAE,MAAM;YACnB,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;YAChC,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CAAC,CAAC;QACH,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YAC5B,eAAe,CAAC,IAAI,CAAC,CAAC;YACtB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC;QAC9B,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAyB,CAAC;QAC7D,OAAO,qBAAqB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5C,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;AACH,CAAC"}

package/dist/avatar/loader.d.ts

@@ -0,0 +1,26 @@
+import { type Object3D } from 'three';
+import type { AvatarMotion } from '../player/avatar.js';
+import type { AvatarDescriptor } from './descriptor.js';
+/** A loaded external avatar, normalised to the WorldMesh body convention. */
+export interface LoadedAvatar {
+    /** Feet at y = 0, facing -Z, scaled to the player's height. */
+    object: Object3D;
+    /** Call once per frame with how the player moves. */
+    animate(motion: AvatarMotion): void;
+    dispose(): void;
+}
+export interface LoadAvatarOptions {
+    /** Standing height to scale the model to, in metres. */
+    height: number;
+    /** Refuse models larger than this. Defaults to 40 MB. */
+    maxBytes?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Downloads a VRM / glTF model straight from the URL in the descriptor (the
+ * avatar platform's own storage) and turns it into a player body. The loaders
+ * are imported on first use, so worlds that never show an external avatar
+ * never download them.
+ */
+export declare function loadAvatarModel(descriptor: AvatarDescriptor, options: LoadAvatarOptions): Promise<LoadedAvatar>;
+//# sourceMappingURL=loader.d.ts.map

package/dist/avatar/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/avatar/loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+E,KAAK,QAAQ,EAAE,MAAM,OAAO,CAAC;AACnH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,+DAA+D;IAC/D,MAAM,EAAE,QAAQ,CAAC;IACjB,qDAAqD;IACrD,OAAO,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;IACpC,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,UAAU,EAAE,gBAAgB,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,YAAY,CAAC,CAkDrH"}

package/dist/avatar/loader.js

@@ -0,0 +1,177 @@
+import { AnimationMixer, Box3, Group, MathUtils, Mesh, Texture } from 'three';
+/**
+ * Downloads a VRM / glTF model straight from the URL in the descriptor (the
+ * avatar platform's own storage) and turns it into a player body. The loaders
+ * are imported on first use, so worlds that never show an external avatar
+ * never download them.
+ */
+export async function loadAvatarModel(descriptor, options) {
+    const buffer = await download(descriptor.modelUrl, options.maxBytes ?? 40 * 1024 * 1024, options.signal);
+    const [{ GLTFLoader }, vrmModule] = await Promise.all([
+        import('three/examples/jsm/loaders/GLTFLoader.js'),
+        descriptor.format === 'vrm' ? import('@pixiv/three-vrm') : Promise.resolve(null),
+    ]);
+    const loader = new GLTFLoader();
+    if (vrmModule)
+        loader.register((parser) => new vrmModule.VRMLoaderPlugin(parser));
+    const gltf = await loader.parseAsync(buffer, '');
+    const vrm = vrmModule ? gltf.userData.vrm : undefined;
+    if (descriptor.format === 'vrm' && (!vrm || !vrmModule))
+        throw new Error('Not a VRM model');
+    const model = vrm ? vrm.scene : gltf.scene;
+    if (vrm && vrmModule) {
+        vrmModule.VRMUtils.removeUnnecessaryVertices(model);
+        vrmModule.VRMUtils.combineSkeletons(model);
+        // VRM 0.x faces -Z; this makes it face +Z like VRM 1.0 and plain glTF.
+        vrmModule.VRMUtils.rotateVRM0(vrm);
+    }
+    model.traverse((child) => {
+        // Skinned meshes are bounded by their rest pose; animated limbs would pop out of view.
+        child.frustumCulled = false;
+        if (child.isMesh)
+            child.castShadow = true;
+    });
+    // glTF and VRM face +Z; WorldMesh bodies face -Z. Scale to the player and
+    // stand the feet on y = 0.
+    const root = new Group();
+    root.name = 'worldmesh:external-avatar';
+    const turn = new Group();
+    turn.rotation.y = Math.PI;
+    turn.add(model);
+    root.add(turn);
+    root.updateMatrixWorld(true);
+    const box = new Box3().setFromObject(root);
+    const modelHeight = box.max.y - box.min.y;
+    if (!(modelHeight > 0.05 && modelHeight < 100))
+        throw new Error('Model has no usable size');
+    const scale = options.height / modelHeight;
+    turn.scale.setScalar(scale);
+    turn.position.y = -box.min.y * scale;
+    const animate = vrm ? vrmAnimator(vrm) : clipAnimator(model, gltf.animations);
+    return {
+        object: root,
+        animate,
+        dispose() {
+            if (vrm && vrmModule)
+                vrmModule.VRMUtils.deepDispose(model);
+            else
+                disposeTree(model);
+        },
+    };
+}
+async function download(url, maxBytes, signal) {
+    const response = await fetch(url, { mode: 'cors', credentials: 'omit', referrerPolicy: 'no-referrer', signal });
+    if (!response.ok)
+        throw new Error(`Model download failed (${response.status})`);
+    if (Number(response.headers.get('Content-Length') ?? '0') > maxBytes)
+        throw new Error('Model is too large');
+    if (!response.body)
+        return response.arrayBuffer();
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        size += value.byteLength;
+        if (size > maxBytes) {
+            await reader.cancel();
+            throw new Error('Model is too large');
+        }
+        chunks.push(value);
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes.buffer;
+}
+/**
+ * VRMs arrive in a T-pose with no animation. Lower the arms and swing arms
+ * and legs with speed, through the normalised humanoid rig so it works for
+ * any VRM, then let spring bones (hair, clothes) follow.
+ */
+function vrmAnimator(vrm) {
+    const bone = (name) => vrm.humanoid?.getNormalizedBoneNode(name) ?? null;
+    const armL = bone('leftUpperArm');
+    const armR = bone('rightUpperArm');
+    const foreArmL = bone('leftLowerArm');
+    const foreArmR = bone('rightLowerArm');
+    const legL = bone('leftUpperLeg');
+    const legR = bone('rightUpperLeg');
+    const kneeL = bone('leftLowerLeg');
+    const kneeR = bone('rightLowerLeg');
+    // VRM 0.x rigs are mirrored on X and Z relative to VRM 1.0.
+    const mirror = vrm.meta?.metaVersion === '0' ? -1 : 1;
+    let phase = 0;
+    let stride = 0;
+    let air = 0;
+    return (motion) => {
+        if (motion.dt <= 0)
+            return;
+        const blend = 1 - Math.exp(-motion.dt * 10);
+        const walking = motion.grounded ? MathUtils.clamp(motion.speed / 4.5, 0, 1) : 0;
+        stride += (walking - stride) * blend;
+        air += ((motion.grounded ? 0 : 1) - air) * blend;
+        phase += motion.dt * (4 + motion.speed * 1.2) * (stride > 0.01 ? 1 : 0);
+        const swing = Math.sin(phase) * 0.6 * stride;
+        const armDown = 1.2 - air * 0.5;
+        if (armL)
+            armL.rotation.set(mirror * swing * 0.7, 0, mirror * -armDown);
+        if (armR)
+            armR.rotation.set(mirror * -swing * 0.7, 0, mirror * armDown);
+        if (foreArmL)
+            foreArmL.rotation.set(0, 0, mirror * -0.15);
+        if (foreArmR)
+            foreArmR.rotation.set(0, 0, mirror * 0.15);
+        if (legL)
+            legL.rotation.set(mirror * (-swing - air * 0.3), 0, 0);
+        if (legR)
+            legR.rotation.set(mirror * (swing - air * 0.1), 0, 0);
+        if (kneeL)
+            kneeL.rotation.set(mirror * (Math.max(0, swing) * 0.8 + air * 0.4), 0, 0);
+        if (kneeR)
+            kneeR.rotation.set(mirror * (Math.max(0, -swing) * 0.8 + air * 0.2), 0, 0);
+        vrm.update(motion.dt);
+    };
+}
+/** Plain glTF bodies: play an idle clip, and a walk/run clip while moving, if the file has them. */
+function clipAnimator(model, clips) {
+    if (!clips.length)
+        return () => { };
+    const mixer = new AnimationMixer(model);
+    const find = (pattern) => clips.find((clip) => pattern.test(clip.name));
+    const idleClip = find(/idle|stand|breath/i) ?? clips[0];
+    const walkClip = find(/walk|run|jog/i);
+    const idle = mixer.clipAction(idleClip).play();
+    const walk = walkClip && walkClip !== idleClip ? mixer.clipAction(walkClip) : null;
+    let moving = false;
+    return (motion) => {
+        const nowMoving = motion.grounded && motion.speed > 0.5;
+        if (walk && nowMoving !== moving) {
+            moving = nowMoving;
+            const [from, to] = moving ? [idle, walk] : [walk, idle];
+            to.reset().play();
+            from.crossFadeTo(to, 0.2, false);
+        }
+        mixer.update(motion.dt);
+    };
+}
+function disposeTree(root) {
+    root.traverse((child) => {
+        if (!(child instanceof Mesh))
+            return;
+        child.geometry.dispose();
+        for (const material of Array.isArray(child.material) ? child.material : [child.material]) {
+            for (const value of Object.values(material)) {
+                if (value instanceof Texture)
+                    value.dispose();
+            }
+            material.dispose();
+        }
+    });
+}
+//# sourceMappingURL=loader.js.map

package/dist/avatar/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/avatar/loader.ts"],"names":[],"mappings":"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"}

package/dist/controls/input.d.ts

@@ -3,7 +3,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;
 }
 /**
  * Keyboard + pointer-lock mouse input with mobile touch controls support.
@@ -19,6 +26,7 @@ export declare class Input {
     wheelDelta: number;
     locked: boolean;
     private element;
+    private moveBeforeLock;
     private pressed;
     /** Actions that went down this frame and have not been consumed yet. */
     private justPressed;
@@ -26,6 +34,7 @@ export declare class Input {
     private pendingDigit;
     private codeToActions;
     private onPointerLockChange?;
+    private onEscape?;
     private touch?;
     private disposed;
     constructor(options: InputOptions);
@@ -52,11 +61,27 @@ export declare class Input {
     /** Drop stale edge-triggers at the end of a frame. */
     endFrame(): void;
     dispose(): void;
+    /**
+     * 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;
     private handleKeyDown;
     private handleKeyUp;
     /** Losing focus must not leave a key stuck down. */
     private handleBlur;
+    /**
+     * 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;
+    /**
+     * 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;
+    private hoverLook;
     private handleWheel;
     private handlePointerLockChange;
     private handlePointerLockError;

package/dist/controls/input.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"input.d.ts","sourceRoot":"","sources":["../../src/controls/input.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAIvD,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,OAAO,EAAE,WAAW,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACzB,mBAAmB,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;CACjD;AAED;;;;GAIG;AACH,qBAAa,KAAK;IAChB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iEAAiE;IACjE,WAAW,SAAK;IAChB,WAAW,SAAK;IAChB,sDAAsD;IACtD,UAAU,SAAK;IACf,MAAM,UAAS;IAEf,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,OAAO,CAAqB;IACpC,wEAAwE;IACxE,OAAO,CAAC,WAAW,CAA0B;IAC7C,sDAAsD;IACtD,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,aAAa,CAAoC;IACzD,OAAO,CAAC,mBAAmB,CAAC,CAA4B;IACxD,OAAO,CAAC,KAAK,CAAC,CAAgB;IAC9B,OAAO,CAAC,QAAQ,CAAS;gBAEb,OAAO,EAAE,YAAY;IA+BjC,kBAAkB,CAAC,cAAc,UAAQ,GAAG,IAAI;IA4BhD,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;IAYhC,eAAe,IAAI,IAAI;IAOvB,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAIxC,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO;IAMpC,2DAA2D;IAC3D,OAAO,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO;IAOrC,2EAA2E;IAC3E,YAAY,IAAI,MAAM,GAAG,IAAI;IAM7B,iEAAiE;IACjE,WAAW,IAAI;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE;IAgBvC,8EAA8E;IAC9E,QAAQ,IAAI;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE;IAerD,sDAAsD;IACtD,QAAQ,IAAI,IAAI;IAKhB,OAAO,IAAI,IAAI;IAcf,OAAO,CAAC,aAAa,CAcnB;IAEF,OAAO,CAAC,WAAW,CAEjB;IAEF,oDAAoD;IACpD,OAAO,CAAC,UAAU,CAGhB;IAEF,OAAO,CAAC,eAAe,CAIrB;IAEF,OAAO,CAAC,WAAW,CAGjB;IAEF,OAAO,CAAC,uBAAuB,CAQ7B;IAEF,OAAO,CAAC,sBAAsB,CAK5B;CACH"}
+{"version":3,"file":"input.d.ts","sourceRoot":"","sources":["../../src/controls/input.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAIvD,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,OAAO,EAAE,WAAW,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACzB,iEAAiE;IACjE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,mBAAmB,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAChD;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,OAAO,GAAG,IAAI,CAAC;CACjC;AAED;;;;GAIG;AACH,qBAAa,KAAK;IAChB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iEAAiE;IACjE,WAAW,SAAK;IAChB,WAAW,SAAK;IAChB,sDAAsD;IACtD,UAAU,SAAK;IACf,MAAM,UAAS;IAEf,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,cAAc,CAAU;IAChC,OAAO,CAAC,OAAO,CAAqB;IACpC,wEAAwE;IACxE,OAAO,CAAC,WAAW,CAA0B;IAC7C,sDAAsD;IACtD,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,aAAa,CAAoC;IACzD,OAAO,CAAC,mBAAmB,CAAC,CAA4B;IACxD,OAAO,CAAC,QAAQ,CAAC,CAAuB;IACxC,OAAO,CAAC,KAAK,CAAC,CAAgB;IAC9B,OAAO,CAAC,QAAQ,CAAS;gBAEb,OAAO,EAAE,YAAY;IAqCjC,kBAAkB,CAAC,cAAc,UAAQ,GAAG,IAAI;IA4BhD,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;IAYhC,eAAe,IAAI,IAAI;IAevB,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAIxC,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO;IAMpC,2DAA2D;IAC3D,OAAO,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO;IAOrC,2EAA2E;IAC3E,YAAY,IAAI,MAAM,GAAG,IAAI;IAM7B,iEAAiE;IACjE,WAAW,IAAI;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE;IAgBvC,8EAA8E;IAC9E,QAAQ,IAAI;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE;IAerD,sDAAsD;IACtD,QAAQ,IAAI,IAAI;IAKhB,OAAO,IAAI,IAAI;IAgBf;;;;OAIG;IACH,OAAO,CAAC,YAAY,CAKlB;IAEF,OAAO,CAAC,aAAa,CAcnB;IAEF,OAAO,CAAC,WAAW,CAEjB;IAEF,oDAAoD;IACpD,OAAO,CAAC,UAAU,CAGhB;IAEF;;;OAGG;IACH,OAAO,CAAC,iBAAiB,CAMvB;IAEF;;;OAGG;IACH,OAAO,CAAC,eAAe,CAIrB;IAEF,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,WAAW,CAGjB;IAEF,OAAO,CAAC,uBAAuB,CAQ7B;IAEF,OAAO,CAAC,sBAAsB,CAK5B;CACH"}