@rydr/game-sdk 1.12.0 → 1.13.0

package/README.md

@@ -14,11 +14,11 @@ This package is the **public contract** between platform and game:
 
 ## Install
 
-Public git dependency (no registry, no token):
+Public npm package (no token needed — the source repo is private, the package is public):
 
 ```jsonc
 // package.json
-"dependencies": { "@rydr/game-sdk": "github:bdefrenne/rydr-game-sdk#semver:^1.0.0" }
+"dependencies": { "@rydr/game-sdk": "^1.0.0" }
 ```
 
 **Starting a new game?** Don't wire this by hand — scaffold from

package/dist/protocol/version.d.ts

@@ -8,5 +8,5 @@
  */
 export declare const RYDR_PROTOCOL_VERSION: 5;
 /** Semver of this SDK build. Sent in the handshake for telemetry/debugging. */
-export declare const RYDR_SDK_VERSION = "1.12.0";
+export declare const RYDR_SDK_VERSION = "1.13.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/protocol/version.js

@@ -10,5 +10,5 @@
 // shells omit it, the client falls back to its default).
 export const RYDR_PROTOCOL_VERSION = 5;
 /** Semver of this SDK build. Sent in the handshake for telemetry/debugging. */
-export const RYDR_SDK_VERSION = "1.12.0";
+export const RYDR_SDK_VERSION = "1.13.0";
 //# sourceMappingURL=version.js.map

package/dist/three/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `@rydr/game-sdk/three` — optional three.js helpers, kept out of the renderer-agnostic core.
+ *
+ * Importing this entry point requires `three` (declared as a peer dependency). Games that render a
+ * platform world should load it through {@link loadWorldGroup} here instead of hand-rolling a
+ * `GLTFLoader` + DRACO + caching per game.
+ */
+export * from "./world-loader.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/three/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/three/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,mBAAmB,CAAC"}

package/dist/three/index.js

@@ -0,0 +1,9 @@
+/**
+ * `@rydr/game-sdk/three` — optional three.js helpers, kept out of the renderer-agnostic core.
+ *
+ * Importing this entry point requires `three` (declared as a peer dependency). Games that render a
+ * platform world should load it through {@link loadWorldGroup} here instead of hand-rolling a
+ * `GLTFLoader` + DRACO + caching per game.
+ */
+export * from "./world-loader.js";
+//# sourceMappingURL=index.js.map

package/dist/three/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/three/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,mBAAmB,CAAC"}

package/dist/three/world-loader.d.ts

@@ -0,0 +1,53 @@
+/**
+ * world-loader — opinionated three.js helper for loading a platform {@link CoreWorld} into a scene.
+ *
+ * The SDK core ({@link applyWorld}) is deliberately renderer-agnostic: it walks a `CoreWorld` and calls
+ * back a `loadGlb(url)` you provide, never touching `three`. This module is the **three-aware layer on
+ * top** — it owns a `GLTFLoader` + DRACO decoder and the caching every game was otherwise copy-pasting,
+ * so it lives behind the optional `@rydr/game-sdk/three` entry point (with `three` as a peer
+ * dependency) and never burdens games that don't render 3D.
+ *
+ * Two caches make repeated loads cheap:
+ *  - **Per-URL GLB dedup** ({@link createGlbLoader}): each glb is fetched + DRACO-decoded once per
+ *    assembly; repeated placements of the same prop get a `.clone()` (shared geometry/material). This
+ *    also keeps `applyWorld`'s "add each object to the group" correct — the same Object3D instance
+ *    can't be added to a parent twice.
+ *  - **Per-world assembled-group cache** ({@link loadWorldGroup}, keyed by {@link CoreWorld.id}): a
+ *    platform world is a static environment, so once built it is reused across game/runtime instances
+ *    (replays, level restarts, missions sharing a world) instead of being re-fetched, re-decoded,
+ *    re-uploaded to the GPU and re-shader-compiled every time. Callers detach the group from their
+ *    scene on teardown but must **not** dispose its geometry/materials — the cache owns them. Use
+ *    {@link clearWorldCache} to release them when cycling through many large worlds.
+ */
+import * as THREE from "three";
+import type { CoreWorld } from "../protocol/worlds.js";
+/** DRACO decoder — pinned to the same version the platform world editor uses. */
+export declare const DRACO_DECODER_PATH = "https://www.gstatic.com/draco/versioned/decoders/1.5.6/";
+export interface GlbLoaderOptions {
+    /** Override the DRACO decoder directory (defaults to {@link DRACO_DECODER_PATH}). */
+    dracoDecoderPath?: string;
+}
+/**
+ * A `loadGlb` callback for {@link applyWorld}: fetches a glb by URL and resolves to its root scene.
+ *
+ * The returned closure shares one `GLTFLoader` + DRACO decoder across all URLs and fetches +
+ * DRACO-decodes each URL **once** — repeated URLs resolve to a lightweight `.clone()` (shared
+ * geometry/material) rather than re-downloading and re-decoding. Cloning is also required for
+ * correctness: `applyWorld` adds every returned object to the group, and a single Object3D can't be
+ * parented twice.
+ */
+export declare function createGlbLoader(opts?: GlbLoaderOptions): (url: string) => Promise<THREE.Object3D>;
+/**
+ * Load a platform world's meshes into a group at identity, cached by world id. The caller adds the
+ * returned group to its scene and detaches it on teardown **without disposing it** (the cache owns the
+ * geometry/materials, so the next load reuses them instantly). Throws if any glb fails to load.
+ */
+export declare function loadWorldGroup(coreWorld: CoreWorld, opts?: GlbLoaderOptions): Promise<THREE.Group>;
+/**
+ * Release cached assembled worlds and dispose their geometry + materials (textures are left alone —
+ * they may be shared elsewhere). Pass an `id` to drop a single world, or omit it to clear everything.
+ * Call this when a game cycles through many large worlds and the retain-forever default would grow
+ * memory unbounded. Safe to call while a group is still in a scene, but detach it from the scene first.
+ */
+export declare function clearWorldCache(id?: string): void;
+//# sourceMappingURL=world-loader.d.ts.map

package/dist/three/world-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"world-loader.d.ts","sourceRoot":"","sources":["../../src/three/world-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAEvD,iFAAiF;AACjF,eAAO,MAAM,kBAAkB,4DAA4D,CAAC;AAE5F,MAAM,WAAW,gBAAgB;IAC/B,qFAAqF;IACrF,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,GAAE,gBAAqB,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAcrG;AAKD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,SAAS,EAAE,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAgBtG;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAWjD"}

package/dist/three/world-loader.js

@@ -0,0 +1,110 @@
+/**
+ * world-loader — opinionated three.js helper for loading a platform {@link CoreWorld} into a scene.
+ *
+ * The SDK core ({@link applyWorld}) is deliberately renderer-agnostic: it walks a `CoreWorld` and calls
+ * back a `loadGlb(url)` you provide, never touching `three`. This module is the **three-aware layer on
+ * top** — it owns a `GLTFLoader` + DRACO decoder and the caching every game was otherwise copy-pasting,
+ * so it lives behind the optional `@rydr/game-sdk/three` entry point (with `three` as a peer
+ * dependency) and never burdens games that don't render 3D.
+ *
+ * Two caches make repeated loads cheap:
+ *  - **Per-URL GLB dedup** ({@link createGlbLoader}): each glb is fetched + DRACO-decoded once per
+ *    assembly; repeated placements of the same prop get a `.clone()` (shared geometry/material). This
+ *    also keeps `applyWorld`'s "add each object to the group" correct — the same Object3D instance
+ *    can't be added to a parent twice.
+ *  - **Per-world assembled-group cache** ({@link loadWorldGroup}, keyed by {@link CoreWorld.id}): a
+ *    platform world is a static environment, so once built it is reused across game/runtime instances
+ *    (replays, level restarts, missions sharing a world) instead of being re-fetched, re-decoded,
+ *    re-uploaded to the GPU and re-shader-compiled every time. Callers detach the group from their
+ *    scene on teardown but must **not** dispose its geometry/materials — the cache owns them. Use
+ *    {@link clearWorldCache} to release them when cycling through many large worlds.
+ */
+import * as THREE from "three";
+import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
+import { DRACOLoader } from "three/addons/loaders/DRACOLoader.js";
+import { applyWorld } from "../world-runtime.js";
+/** DRACO decoder — pinned to the same version the platform world editor uses. */
+export const DRACO_DECODER_PATH = "https://www.gstatic.com/draco/versioned/decoders/1.5.6/";
+/**
+ * A `loadGlb` callback for {@link applyWorld}: fetches a glb by URL and resolves to its root scene.
+ *
+ * The returned closure shares one `GLTFLoader` + DRACO decoder across all URLs and fetches +
+ * DRACO-decodes each URL **once** — repeated URLs resolve to a lightweight `.clone()` (shared
+ * geometry/material) rather than re-downloading and re-decoding. Cloning is also required for
+ * correctness: `applyWorld` adds every returned object to the group, and a single Object3D can't be
+ * parented twice.
+ */
+export function createGlbLoader(opts = {}) {
+    const loader = new GLTFLoader();
+    const draco = new DRACOLoader();
+    draco.setDecoderPath(opts.dracoDecoderPath ?? DRACO_DECODER_PATH);
+    loader.setDRACOLoader(draco);
+    const decoded = new Map();
+    return (url) => {
+        let p = decoded.get(url);
+        if (!p) {
+            p = loader.loadAsync(url).then((g) => g.scene);
+            decoded.set(url, p);
+        }
+        return p.then((scene) => scene.clone());
+    };
+}
+/** Assembled worlds, keyed by {@link CoreWorld.id}. See the module doc for the lifecycle contract. */
+const worldGroupCache = new Map();
+/**
+ * Load a platform world's meshes into a group at identity, cached by world id. The caller adds the
+ * returned group to its scene and detaches it on teardown **without disposing it** (the cache owns the
+ * geometry/materials, so the next load reuses them instantly). Throws if any glb fails to load.
+ */
+export function loadWorldGroup(coreWorld, opts = {}) {
+    let p = worldGroupCache.get(coreWorld.id);
+    if (!p) {
+        p = (async () => {
+            const group = new THREE.Group();
+            group.name = "platform-world";
+            await applyWorld(group, coreWorld, { loadGlb: createGlbLoader(opts) });
+            return group;
+        })();
+        // Don't cache a rejected build — let the next attempt retry the fetch.
+        p.catch(() => {
+            if (worldGroupCache.get(coreWorld.id) === p)
+                worldGroupCache.delete(coreWorld.id);
+        });
+        worldGroupCache.set(coreWorld.id, p);
+    }
+    return p;
+}
+/**
+ * Release cached assembled worlds and dispose their geometry + materials (textures are left alone —
+ * they may be shared elsewhere). Pass an `id` to drop a single world, or omit it to clear everything.
+ * Call this when a game cycles through many large worlds and the retain-forever default would grow
+ * memory unbounded. Safe to call while a group is still in a scene, but detach it from the scene first.
+ */
+export function clearWorldCache(id) {
+    const drop = (key, promise) => {
+        worldGroupCache.delete(key);
+        void promise.then(disposeGroup).catch(() => { });
+    };
+    if (id !== undefined) {
+        const p = worldGroupCache.get(id);
+        if (p)
+            drop(id, p);
+        return;
+    }
+    for (const [key, p] of worldGroupCache)
+        drop(key, p);
+}
+/** Dispose a group's geometry + materials (not textures). */
+function disposeGroup(group) {
+    group.parent?.remove(group);
+    group.traverse((o) => {
+        const mesh = o;
+        if (!mesh.isMesh)
+            return;
+        mesh.geometry?.dispose();
+        for (const m of Array.isArray(mesh.material) ? mesh.material : [mesh.material]) {
+            m?.dispose();
+        }
+    });
+}
+//# sourceMappingURL=world-loader.js.map

package/dist/three/world-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"world-loader.js","sourceRoot":"","sources":["../../src/three/world-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAGjD,iFAAiF;AACjF,MAAM,CAAC,MAAM,kBAAkB,GAAG,yDAAyD,CAAC;AAO5F;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,OAAyB,EAAE;IACzD,MAAM,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;IAChC,MAAM,KAAK,GAAG,IAAI,WAAW,EAAE,CAAC;IAChC,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,gBAAgB,IAAI,kBAAkB,CAAC,CAAC;IAClE,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IAC7B,MAAM,OAAO,GAAG,IAAI,GAAG,EAAmC,CAAC;IAC3D,OAAO,CAAC,GAAW,EAAE,EAAE;QACrB,IAAI,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACzB,IAAI,CAAC,CAAC,EAAE,CAAC;YACP,CAAC,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;YAC/C,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACtB,CAAC;QACD,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;IAC1C,CAAC,CAAC;AACJ,CAAC;AAED,sGAAsG;AACtG,MAAM,eAAe,GAAG,IAAI,GAAG,EAAgC,CAAC;AAEhE;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,SAAoB,EAAE,OAAyB,EAAE;IAC9E,IAAI,CAAC,GAAG,eAAe,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IAC1C,IAAI,CAAC,CAAC,EAAE,CAAC;QACP,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE;YACd,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;YAChC,KAAK,CAAC,IAAI,GAAG,gBAAgB,CAAC;YAC9B,MAAM,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,OAAO,EAAE,eAAe,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACvE,OAAO,KAAK,CAAC;QACf,CAAC,CAAC,EAAE,CAAC;QACL,uEAAuE;QACvE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;YACX,IAAI,eAAe,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,CAAC;gBAAE,eAAe,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QACpF,CAAC,CAAC,CAAC;QACH,eAAe,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,EAAW;IACzC,MAAM,IAAI,GAAG,CAAC,GAAW,EAAE,OAA6B,EAAQ,EAAE;QAChE,eAAe,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC5B,KAAK,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAClD,CAAC,CAAC;IACF,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;QACrB,MAAM,CAAC,GAAG,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAClC,IAAI,CAAC;YAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;QACnB,OAAO;IACT,CAAC;IACD,KAAK,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,eAAe;QAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;AACvD,CAAC;AAED,6DAA6D;AAC7D,SAAS,YAAY,CAAC,KAAkB;IACtC,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5B,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,EAAE;QACnB,MAAM,IAAI,GAAG,CAAe,CAAC;QAC7B,IAAI,CAAC,IAAI,CAAC,MAAM;YAAE,OAAO;QACzB,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAC;QACzB,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC9E,CAAgC,EAAE,OAAO,EAAE,CAAC;QAC/C,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rydr/game-sdk",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/bdefrenne/rydr-game-sdk.git"
@@ -15,6 +15,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./three": {
+      "types": "./dist/three/index.d.ts",
+      "import": "./dist/three/index.js"
     }
   },
   "main": "./dist/index.js",
@@ -32,7 +36,17 @@
     "version": "node scripts/sync-version.mjs && node scripts/release-changelog.mjs && git add src/protocol/version.ts CHANGELOG.md",
     "postversion": "git push --follow-tags"
   },
+  "peerDependencies": {
+    "three": ">=0.160.0"
+  },
+  "peerDependenciesMeta": {
+    "three": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@types/three": "^0.184.0",
+    "three": "^0.184.0",
     "typescript": "^5.5.0"
   }
 }