@rydr/game-sdk 1.16.0 → 1.18.0

package/dist/three/merge.d.ts

@@ -0,0 +1,88 @@
+/**
+ * merge — collapse the per-mesh draw calls of a subtree into one batched mesh
+ * per material.
+ *
+ * three.js submits one draw call per visible mesh, so a scene full of static
+ * decoration (a platform world's ~1800 props) or many articulated units (each
+ * built from dozens of small parts) is dominated by draw-call CPU, not GPU or
+ * sim. The fix is the same primitive in both cases: **merge sibling meshes that
+ * share a material into one batched geometry, baking each mesh's transform into
+ * shared vertex data.** A platform world collapses to ≈one draw per material; a
+ * unit's static parts collapse to a handful.
+ *
+ * This is the single, SDK-owned implementation of that primitive — games never
+ * reimplement bucketing, transform-baking, `mergeGeometries`, material handling
+ * or dispose discipline. They pass only what the SDK can't know: which sub-nodes
+ * are animated ({@link MergeOptions.boundaries}) and which parts to leave alone
+ * ({@link MergeOptions.keepIndividual}). For static worlds even that disappears —
+ * see `loadWorld({ mergeStatics: true })`.
+ *
+ * Baking is destructive to per-mesh transforms: a merged mesh can no longer be
+ * moved, hidden, recoiled or scattered on its own. Opt a subtree OUT with
+ * `userData.__noMerge = true` on its root.
+ */
+import * as THREE from "three";
+/** Count of draw calls before/after, for logging and draw-call audits. */
+export interface MergeResult {
+    /** Mesh draw calls that were merged away. */
+    readonly before: number;
+    /** Batched mesh draw calls created (≈ one per material per island). */
+    readonly after: number;
+}
+export interface MergeOptions {
+    /**
+     * Sub-nodes that must keep their own transform (a rotating turret yaw,
+     * spinning wheels, a rotor hub). Each becomes a merge-island root: descendants
+     * are baked relative to it and the batch is parented under it, so the island
+     * keeps animating after the merge. Meshes never bake across an island
+     * boundary. Default: none — everything bakes relative to `root`.
+     */
+    boundaries?: THREE.Object3D[];
+    /**
+     * How to bucket meshes for merging:
+     * - `'instance'` (default): by `material` identity. Static worlds already
+     *   share one material instance across sibling props; the batch **reuses** that
+     *   instance, so live opacity/color tweaks on the shared material carry through.
+     * - `'source'`: by a caller-provided source-material key. Articulated units
+     *   clone each part's material (so per-part flash doesn't bleed), giving
+     *   "same-palette" parts distinct UUIDs that `'instance'` would never batch.
+     *   The batch gets a fresh clone of the source material, so per-material
+     *   hit-flash still flashes the whole chunk.
+     */
+    groupBy?: "instance" | "source";
+    /**
+     * Where the source material lives when `groupBy: 'source'`. Returning `null`
+     * leaves the mesh individual. Default: `mesh.userData.unit?.srcMat ?? null`.
+     */
+    sourceMaterialAccessor?: (mesh: THREE.Mesh) => THREE.Material | null;
+    /** Predicate for "skip this mesh, keep it an individual draw" (recoiling barrels, etc.). */
+    keepIndividual?: (mesh: THREE.Mesh) => boolean;
+    /** Called once per created batch with the meshes it consumed — so callers can re-sync a parts list. */
+    onBatch?: (batch: THREE.Mesh, consumed: THREE.Mesh[]) => void;
+    /**
+     * Dispose consumed geometries (and their per-mesh materials) after merge.
+     * Default: `false` — safe for shared caches (the world GLB dedup clones shared
+     * geometry, so a source geom may back sibling clones). Owned-unit callers with
+     * private clones may set `true`. Never disposes a reused `'instance'` material
+     * or a `'source'` source material — those outlive the batch.
+     */
+    disposeConsumed?: boolean;
+}
+/**
+ * Merge the mergeable meshes under `root` in place: detach the originals and add
+ * one batched mesh per (island, material, attribute-set, index-ness, renderOrder,
+ * shadow flags) bucket. Idempotent — sets `root.userData.__merged` and returns
+ * `{ before: 0, after: 0 }` on a second call.
+ *
+ * Transforms are baked into each island's LOCAL space, so `root`'s own transform
+ * (and each island's animation) still applies afterward. Buckets with a single
+ * mesh are left individual — same draw-call count, no wasted re-bake. Buckets
+ * `mergeGeometries` rejects (incompatible attributes) are left unmerged + warned.
+ *
+ * Skipped (left as individual draws): `userData.__noMerge` subtrees, hidden
+ * meshes (kept toggleable), skinned / morph-target / multi-material meshes (their
+ * per-mesh state can't be baked), `keepIndividual` matches, and — in `'source'`
+ * mode — meshes whose `sourceMaterialAccessor` returns `null`.
+ */
+export declare function mergeByMaterial(root: THREE.Object3D, opts?: MergeOptions): MergeResult;
+//# sourceMappingURL=merge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../../src/three/merge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,0EAA0E;AAC1E,MAAM,WAAW,WAAW;IAC1B,6CAA6C;IAC7C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,uEAAuE;IACvE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC;IAC9B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,UAAU,GAAG,QAAQ,CAAC;IAChC;;;OAGG;IACH,sBAAsB,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC;IACrE,4FAA4F;IAC5F,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,KAAK,OAAO,CAAC;IAC/C,uGAAuG;IACvG,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,IAAI,CAAC;IAC9D;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAcD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,KAAK,CAAC,QAAQ,EAAE,IAAI,GAAE,YAAiB,GAAG,WAAW,CA+G1F"}

package/dist/three/merge.js

@@ -0,0 +1,148 @@
+/**
+ * merge — collapse the per-mesh draw calls of a subtree into one batched mesh
+ * per material.
+ *
+ * three.js submits one draw call per visible mesh, so a scene full of static
+ * decoration (a platform world's ~1800 props) or many articulated units (each
+ * built from dozens of small parts) is dominated by draw-call CPU, not GPU or
+ * sim. The fix is the same primitive in both cases: **merge sibling meshes that
+ * share a material into one batched geometry, baking each mesh's transform into
+ * shared vertex data.** A platform world collapses to ≈one draw per material; a
+ * unit's static parts collapse to a handful.
+ *
+ * This is the single, SDK-owned implementation of that primitive — games never
+ * reimplement bucketing, transform-baking, `mergeGeometries`, material handling
+ * or dispose discipline. They pass only what the SDK can't know: which sub-nodes
+ * are animated ({@link MergeOptions.boundaries}) and which parts to leave alone
+ * ({@link MergeOptions.keepIndividual}). For static worlds even that disappears —
+ * see `loadWorld({ mergeStatics: true })`.
+ *
+ * Baking is destructive to per-mesh transforms: a merged mesh can no longer be
+ * moved, hidden, recoiled or scattered on its own. Opt a subtree OUT with
+ * `userData.__noMerge = true` on its root.
+ */
+import * as THREE from "three";
+import { mergeGeometries } from "three/addons/utils/BufferGeometryUtils.js";
+const defaultSourceAccessor = (mesh) => mesh.userData.unit?.srcMat ?? null;
+/**
+ * Merge the mergeable meshes under `root` in place: detach the originals and add
+ * one batched mesh per (island, material, attribute-set, index-ness, renderOrder,
+ * shadow flags) bucket. Idempotent — sets `root.userData.__merged` and returns
+ * `{ before: 0, after: 0 }` on a second call.
+ *
+ * Transforms are baked into each island's LOCAL space, so `root`'s own transform
+ * (and each island's animation) still applies afterward. Buckets with a single
+ * mesh are left individual — same draw-call count, no wasted re-bake. Buckets
+ * `mergeGeometries` rejects (incompatible attributes) are left unmerged + warned.
+ *
+ * Skipped (left as individual draws): `userData.__noMerge` subtrees, hidden
+ * meshes (kept toggleable), skinned / morph-target / multi-material meshes (their
+ * per-mesh state can't be baked), `keepIndividual` matches, and — in `'source'`
+ * mode — meshes whose `sourceMaterialAccessor` returns `null`.
+ */
+export function mergeByMaterial(root, opts = {}) {
+    if (root.userData.__merged === true)
+        return { before: 0, after: 0 };
+    const groupBy = opts.groupBy ?? "instance";
+    const sourceAccessor = opts.sourceMaterialAccessor ?? defaultSourceAccessor;
+    const boundarySet = new Set(opts.boundaries ?? []);
+    root.updateMatrixWorld(true);
+    const islandRootFor = (mesh) => {
+        let n = mesh.parent;
+        while (n && n !== root) {
+            if (boundarySet.has(n))
+                return n;
+            n = n.parent;
+        }
+        return root;
+    };
+    // Cache an inverse-world matrix per island so each mesh bakes into island-local space.
+    const islandInverse = new Map();
+    const inverseFor = (island) => {
+        let inv = islandInverse.get(island);
+        if (!inv) {
+            island.updateWorldMatrix(true, false);
+            inv = new THREE.Matrix4().copy(island.matrixWorld).invert();
+            islandInverse.set(island, inv);
+        }
+        return inv;
+    };
+    const buckets = new Map();
+    const local = new THREE.Matrix4();
+    const visit = (obj) => {
+        if (obj.userData.__noMerge === true)
+            return; // skip animated/handle subtrees
+        if (obj.visible === false)
+            return; // keep hidden meshes toggleable
+        const mesh = obj;
+        if (mesh.isMesh && !mesh.isSkinnedMesh && !Array.isArray(mesh.material) && mesh.geometry) {
+            const morphs = mesh.geometry.morphAttributes;
+            const noMorph = !morphs || Object.keys(morphs).length === 0;
+            const keep = opts.keepIndividual?.(mesh) === true;
+            const keyMaterial = groupBy === "source" ? sourceAccessor(mesh) : mesh.material;
+            if (noMorph && !keep && keyMaterial) {
+                const geom = mesh.geometry;
+                const island = islandRootFor(mesh);
+                const attrSig = Object.keys(geom.attributes).sort().join(",");
+                const key = `${island.uuid}|${keyMaterial.uuid}|${attrSig}|${geom.index ? "i" : "n"}|${mesh.renderOrder}|${mesh.castShadow ? 1 : 0}|${mesh.receiveShadow ? 1 : 0}`;
+                mesh.updateWorldMatrix(true, false);
+                local.copy(inverseFor(island)).multiply(mesh.matrixWorld);
+                const baked = geom.clone();
+                baked.applyMatrix4(local);
+                let bucket = buckets.get(key);
+                if (!bucket) {
+                    bucket = { keyMaterial, island, renderOrder: mesh.renderOrder, geometries: [], consumed: [] };
+                    buckets.set(key, bucket);
+                }
+                bucket.geometries.push(baked);
+                bucket.consumed.push(mesh);
+            }
+        }
+        for (const child of obj.children)
+            visit(child);
+    };
+    for (const child of root.children)
+        visit(child);
+    let before = 0;
+    let after = 0;
+    for (const bucket of buckets.values()) {
+        if (bucket.consumed.length < 2) {
+            // Nothing to batch — drop the throwaway bake, leave the original in place.
+            for (const g of bucket.geometries)
+                g.dispose();
+            continue;
+        }
+        const merged = mergeGeometries(bucket.geometries, false);
+        for (const g of bucket.geometries)
+            g.dispose(); // copied into `merged`
+        if (!merged) {
+            console.warn("[merge] skipped an incompatible material bucket");
+            continue;
+        }
+        const reference = bucket.consumed[0];
+        const material = groupBy === "source" ? bucket.keyMaterial.clone() : bucket.keyMaterial;
+        const batch = new THREE.Mesh(merged, material);
+        batch.name = "merged-batch";
+        batch.renderOrder = bucket.renderOrder;
+        batch.castShadow = reference.castShadow;
+        batch.receiveShadow = reference.receiveShadow;
+        bucket.island.add(batch);
+        for (const mesh of bucket.consumed) {
+            mesh.parent?.remove(mesh);
+            before++;
+        }
+        after++;
+        opts.onBatch?.(batch, bucket.consumed);
+        if (opts.disposeConsumed) {
+            for (const mesh of bucket.consumed) {
+                mesh.geometry?.dispose();
+                const m = mesh.material;
+                if (m && m !== bucket.keyMaterial)
+                    m.dispose();
+            }
+        }
+    }
+    root.userData.__merged = true;
+    return { before, after };
+}
+//# sourceMappingURL=merge.js.map

package/dist/three/merge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge.js","sourceRoot":"","sources":["../../src/three/merge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,eAAe,EAAE,MAAM,2CAA2C,CAAC;AAkD5E,MAAM,qBAAqB,GAAG,CAAC,IAAgB,EAAyB,EAAE,CACvE,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAqC,IAAI,IAAI,CAAC;AAWrE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,eAAe,CAAC,IAAoB,EAAE,OAAqB,EAAE;IAC3E,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,KAAK,IAAI;QAAE,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IAEpE,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,UAAU,CAAC;IAC3C,MAAM,cAAc,GAAG,IAAI,CAAC,sBAAsB,IAAI,qBAAqB,CAAC;IAC5E,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC;IAEnD,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;IAE7B,MAAM,aAAa,GAAG,CAAC,IAAoB,EAAkB,EAAE;QAC7D,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;QACpB,OAAO,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;YACvB,IAAI,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;gBAAE,OAAO,CAAC,CAAC;YACjC,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC;QACf,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;IAEF,uFAAuF;IACvF,MAAM,aAAa,GAAG,IAAI,GAAG,EAAiC,CAAC;IAC/D,MAAM,UAAU,GAAG,CAAC,MAAsB,EAAiB,EAAE;QAC3D,IAAI,GAAG,GAAG,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACpC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,MAAM,CAAC,iBAAiB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YACtC,GAAG,GAAG,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,MAAM,EAAE,CAAC;YAC5D,aAAa,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QACjC,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC,CAAC;IAEF,MAAM,OAAO,GAAG,IAAI,GAAG,EAAuB,CAAC;IAC/C,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;IAElC,MAAM,KAAK,GAAG,CAAC,GAAmB,EAAQ,EAAE;QAC1C,IAAI,GAAG,CAAC,QAAQ,CAAC,SAAS,KAAK,IAAI;YAAE,OAAO,CAAC,gCAAgC;QAC7E,IAAI,GAAG,CAAC,OAAO,KAAK,KAAK;YAAE,OAAO,CAAC,gCAAgC;QACnE,MAAM,IAAI,GAAG,GAAiE,CAAC;QAC/E,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,aAAa,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACzF,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,eAAe,CAAC;YAC7C,MAAM,OAAO,GAAG,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC;YAC5D,MAAM,IAAI,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC;YAClD,MAAM,WAAW,GACf,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,CAAE,IAAI,CAAC,QAA2B,CAAC;YAClF,IAAI,OAAO,IAAI,CAAC,IAAI,IAAI,WAAW,EAAE,CAAC;gBACpC,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC;gBAC3B,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;gBACnC,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBAC9D,MAAM,GAAG,GAAG,GAAG,MAAM,CAAC,IAAI,IAAI,WAAW,CAAC,IAAI,IAAI,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBAEnK,IAAI,CAAC,iBAAiB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;gBACpC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;gBAC1D,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;gBAC3B,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;gBAE1B,IAAI,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBAC9B,IAAI,CAAC,MAAM,EAAE,CAAC;oBACZ,MAAM,GAAG,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,UAAU,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;oBAC9F,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;gBAC3B,CAAC;gBACD,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;gBAC9B,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC7B,CAAC;QACH,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,QAAQ;YAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IACjD,CAAC,CAAC;IACF,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ;QAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IAEhD,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,MAAM,IAAI,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;QACtC,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC/B,2EAA2E;YAC3E,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,UAAU;gBAAE,CAAC,CAAC,OAAO,EAAE,CAAC;YAC/C,SAAS;QACX,CAAC;QAED,MAAM,MAAM,GAAG,eAAe,CAAC,MAAM,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;QACzD,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,UAAU;YAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,uBAAuB;QACvE,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,CAAC,IAAI,CAAC,iDAAiD,CAAC,CAAC;YAChE,SAAS;QACX,CAAC;QAED,MAAM,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAE,CAAC;QACtC,MAAM,QAAQ,GAAG,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC;QACxF,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QAC/C,KAAK,CAAC,IAAI,GAAG,cAAc,CAAC;QAC5B,KAAK,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC;QACvC,KAAK,CAAC,UAAU,GAAG,SAAS,CAAC,UAAU,CAAC;QACxC,KAAK,CAAC,aAAa,GAAG,SAAS,CAAC,aAAa,CAAC;QAC9C,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAEzB,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YACnC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;YAC1B,MAAM,EAAE,CAAC;QACX,CAAC;QACD,KAAK,EAAE,CAAC;QAER,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;QAEvC,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YACzB,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;gBACnC,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAC;gBACzB,MAAM,CAAC,GAAG,IAAI,CAAC,QAAsC,CAAC;gBACtD,IAAI,CAAC,IAAI,CAAC,KAAK,MAAM,CAAC,WAAW;oBAAE,CAAC,CAAC,OAAO,EAAE,CAAC;YACjD,CAAC;QACH,CAAC;IACH,CAAC;IAED,IAAI,CAAC,QAAQ,CAAC,QAAQ,GAAG,IAAI,CAAC;IAC9B,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AAC3B,CAAC"}

package/dist/three/perf-marks.d.ts

@@ -0,0 +1,50 @@
+/**
+ * perf-marks — lightweight timing instrumentation, shared so any rydr game's
+ * marks feed the same {@link PerfOverlay} panel.
+ *
+ * Toggle with `window.__PERF__ = true` (or `?perf=1`, handled by the overlay).
+ * When disabled every call is a cheap no-op, so it is safe to sprinkle through
+ * hot-path code.
+ *
+ * Usage:
+ * ```ts
+ *   perfMark('frame.update');    // start a region
+ *   … work …
+ *   perfMeasure('frame.update'); // end the region, record elapsed ms
+ *   window.__perfReport();       // { label: { avg, max, n } }
+ * ```
+ *
+ * Browser-only (uses `performance.now()` + `window`). Part of the optional
+ * `@rydr/game-sdk/three` entry point.
+ */
+/** One label's rolling stats over the last {@link SAMPLES} measures. */
+export interface PerfReportEntry {
+    avg: number;
+    max: number;
+    n: number;
+}
+/** Snapshot of every recorded label. */
+export type PerfReport = Record<string, PerfReportEntry>;
+declare global {
+    interface Window {
+        __PERF__?: boolean;
+        __perfReport?: () => PerfReport | null;
+    }
+}
+/** Start a timing region under `label`. No-op unless `window.__PERF__` is set. */
+export declare function perfMark(label: string): void;
+/**
+ * End the region opened by `perfMark(label)` and push the elapsed ms into a
+ * rolling ring buffer. No-op if no matching mark or perf is disabled.
+ */
+export declare function perfMeasure(label: string): void;
+/** Snapshot every recorded label as `{ avg, max, n }`. null when perf is off. */
+export declare function perfReport(): PerfReport | null;
+/**
+ * Rolling average for a label, WITHOUT the `__PERF__` guard — the overlay reads
+ * these to render its phase breakdown regardless of global logging state.
+ */
+export declare function perfAvg(label: string): number;
+/** Rolling peak for a label. Same no-guard rule as {@link perfAvg}. */
+export declare function perfPeak(label: string): number;
+//# sourceMappingURL=perf-marks.d.ts.map

package/dist/three/perf-marks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"perf-marks.d.ts","sourceRoot":"","sources":["../../src/three/perf-marks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,CAAC,EAAE,MAAM,CAAC;CACX;AACD,wCAAwC;AACxC,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;AAEzD,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,YAAY,CAAC,EAAE,MAAM,UAAU,GAAG,IAAI,CAAC;KACxC;CACF;AAMD,kFAAkF;AAClF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAG5C;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAY/C;AAED,iFAAiF;AACjF,wBAAgB,UAAU,IAAI,UAAU,GAAG,IAAI,CAU9C;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAI7C;AAED,uEAAuE;AACvE,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAI9C"}

package/dist/three/perf-marks.js

@@ -0,0 +1,86 @@
+/**
+ * perf-marks — lightweight timing instrumentation, shared so any rydr game's
+ * marks feed the same {@link PerfOverlay} panel.
+ *
+ * Toggle with `window.__PERF__ = true` (or `?perf=1`, handled by the overlay).
+ * When disabled every call is a cheap no-op, so it is safe to sprinkle through
+ * hot-path code.
+ *
+ * Usage:
+ * ```ts
+ *   perfMark('frame.update');    // start a region
+ *   … work …
+ *   perfMeasure('frame.update'); // end the region, record elapsed ms
+ *   window.__perfReport();       // { label: { avg, max, n } }
+ * ```
+ *
+ * Browser-only (uses `performance.now()` + `window`). Part of the optional
+ * `@rydr/game-sdk/three` entry point.
+ */
+const SAMPLES = 60;
+const marks = new Map();
+const histories = new Map();
+function enabled() {
+    return typeof window !== "undefined" && window.__PERF__ === true;
+}
+/** Start a timing region under `label`. No-op unless `window.__PERF__` is set. */
+export function perfMark(label) {
+    if (!enabled())
+        return;
+    marks.set(label, performance.now());
+}
+/**
+ * End the region opened by `perfMark(label)` and push the elapsed ms into a
+ * rolling ring buffer. No-op if no matching mark or perf is disabled.
+ */
+export function perfMeasure(label) {
+    if (!enabled())
+        return;
+    const start = marks.get(label);
+    if (start == null)
+        return;
+    const ms = performance.now() - start;
+    let hist = histories.get(label);
+    if (!hist) {
+        hist = [];
+        histories.set(label, hist);
+    }
+    hist.push(ms);
+    if (hist.length > SAMPLES)
+        hist.shift();
+}
+/** Snapshot every recorded label as `{ avg, max, n }`. null when perf is off. */
+export function perfReport() {
+    if (!enabled())
+        return null;
+    const out = {};
+    for (const [label, hist] of histories) {
+        if (!hist.length)
+            continue;
+        const avg = hist.reduce((a, b) => a + b, 0) / hist.length;
+        const max = Math.max(...hist);
+        out[label] = { avg: +avg.toFixed(2), max: +max.toFixed(2), n: hist.length };
+    }
+    return out;
+}
+/**
+ * Rolling average for a label, WITHOUT the `__PERF__` guard — the overlay reads
+ * these to render its phase breakdown regardless of global logging state.
+ */
+export function perfAvg(label) {
+    const hist = histories.get(label);
+    if (!hist || !hist.length)
+        return 0;
+    return hist.reduce((a, b) => a + b, 0) / hist.length;
+}
+/** Rolling peak for a label. Same no-guard rule as {@link perfAvg}. */
+export function perfPeak(label) {
+    const hist = histories.get(label);
+    if (!hist || !hist.length)
+        return 0;
+    return Math.max(...hist);
+}
+if (typeof window !== "undefined") {
+    window.__perfReport = perfReport;
+}
+//# sourceMappingURL=perf-marks.js.map

package/dist/three/perf-marks.js.map

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

package/dist/three/perf-overlay.d.ts

@@ -0,0 +1,104 @@
+/**
+ * perf-overlay — a shared, collapsible Three.js performance HUD for every rydr
+ * game. Shows FPS / CPU / GPU (via WebGL2 timer queries) / `renderer.info`, a
+ * `perfMark` phase breakdown, live entity counters, a copy-report button, and a
+ * generic draw-call audit. Default-off; zero cost when disabled.
+ *
+ * This is the SDK's first browser-UI module (the core protocol/client stay
+ * isomorphic). It is intentionally **self-contained**: it injects nothing
+ * global, depends on no CSS variables, and builds its own top-right overlay
+ * stack — so any Three.js game gets the panel by constructing it.
+ *
+ * Core is generic; each game extends it through a plain options object
+ * ({@link PerfOverlayOptions}) — `counters`, `phases`, `buttons`, `scene` — no
+ * formal capability interface (the surface is too small to warrant one).
+ *
+ * Enable: `?perf=1` on the page (or parent frame, for iframed games) or
+ * `window.__PERF__ = true`. Toggle the panel with the backtick key.
+ *
+ * Per-frame call order (mirrors a typical render loop):
+ * ```ts
+ *   perf.frameStart();
+ *   update();
+ *   perf.gpuBegin();  render();  perf.gpuEnd();
+ *   perf.frameEnd(dtSeconds);
+ * ```
+ */
+import type * as THREE from "three";
+/** Per-game extension surface — all optional. */
+export interface PerfOverlayOptions {
+    /** Scene to drive the generic "Audit draw calls" button. Omit to hide it. */
+    scene?: THREE.Object3D;
+    /** Live entity counts → rendered as panel rows (e.g. `{ enemies, projectiles }`). */
+    counters?: () => Record<string, number>;
+    /** `perfMark` labels to surface as an avg/max breakdown (e.g. `['update','render']`). */
+    phases?: string[];
+    /** Extra action buttons (e.g. a renderer-specific "Toggle bloom"). */
+    buttons?: PerfButtonSpec[];
+    /** Pixel offset of the overlay stack from the top-right corner. Default
+     *  `{ top: 8, right: 8 }`. Raise `right` to clear other top-right chrome
+     *  (e.g. a host hamburger menu). */
+    offset?: {
+        top?: number;
+        right?: number;
+    };
+}
+/** A custom panel button. */
+export interface PerfButtonSpec {
+    label: string;
+    /** CSS background tint; defaults to the neutral blue. */
+    color?: string;
+    onClick: () => void;
+}
+/**
+ * Bucket a scene's renderable objects (≈ draw calls) by top-level child, plus a
+ * material/geometry composition of the biggest bucket. Renderer-agnostic — the
+ * same audit the tower-defense game used, generalized over any `scene`.
+ */
+export declare function auditScene(scene: THREE.Object3D): string;
+/**
+ * The performance overlay. Construct once with the canvas host + renderer, drive
+ * it from the render loop, and pass game specifics via {@link PerfOverlayOptions}.
+ */
+export declare class PerfOverlay {
+    private readonly renderer;
+    private readonly opts;
+    private readonly gl;
+    private readonly ext;
+    private readonly fps;
+    private readonly frameMs;
+    private readonly cpuMs;
+    private readonly gpuMs;
+    private prevFrameTime;
+    private cpuStart;
+    private readonly gpuPool;
+    private readonly gpuPending;
+    private gpuCurrent;
+    private lastInfo;
+    private domTick;
+    private readonly DOM_INTERVAL;
+    private visible;
+    private readonly stack;
+    private readonly pill;
+    private readonly panel;
+    private readonly pre;
+    private readonly reportOut;
+    private readonly onKey;
+    constructor(host: HTMLElement, renderer: THREE.WebGLRenderer, opts?: PerfOverlayOptions);
+    frameStart(): void;
+    gpuBegin(): void;
+    gpuEnd(): void;
+    /** End of frame. `dt` is seconds since last frame (drives the DOM throttle). */
+    frameEnd(dt: number): void;
+    toggle(): void;
+    destroy(): void;
+    private applyVisibility;
+    private makeButton;
+    private buildButtons;
+    private dumpReport;
+    private initGpuExt;
+    private pollGpu;
+    private updatePill;
+    private updateDom;
+}
+//# sourceMappingURL=perf-overlay.d.ts.map

package/dist/three/perf-overlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"perf-overlay.d.ts","sourceRoot":"","sources":["../../src/three/perf-overlay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAIpC,iDAAiD;AACjD,MAAM,WAAW,kBAAkB;IACjC,6EAA6E;IAC7E,KAAK,CAAC,EAAE,KAAK,CAAC,QAAQ,CAAC;IACvB,qFAAqF;IACrF,QAAQ,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,yFAAyF;IACzF,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,sEAAsE;IACtE,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;IAC3B;;wCAEoC;IACpC,MAAM,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3C;AAED,6BAA6B;AAC7B,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AA6DD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,GAAG,MAAM,CA6FxD;AAED;;;GAGG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsB;IAC/C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqB;IAC1C,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAiD;IACpE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA+B;IAEnD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAgB;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IACtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IAEtC,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,QAAQ,CAAK;IAErB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;IAC/C,OAAO,CAAC,UAAU,CAA2B;IAE7C,OAAO,CAAC,QAAQ,CAAkF;IAElG,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IAEtC,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;IACvC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAoB;IACzC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;IACvC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAiB;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiB;IAC3C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6B;gBAEvC,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,KAAK,CAAC,aAAa,EAAE,IAAI,GAAE,kBAAuB;IA2E3F,UAAU,IAAI,IAAI;IAWlB,QAAQ,IAAI,IAAI;IAShB,MAAM,IAAI,IAAI;IAQd,gFAAgF;IAChF,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAsB1B,MAAM,IAAI,IAAI;IAMd,OAAO,IAAI,IAAI;IAgBf,OAAO,CAAC,eAAe;IAKvB,OAAO,CAAC,UAAU;IAYlB,OAAO,CAAC,YAAY;IAuBpB,OAAO,CAAC,UAAU;IA0BlB,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,OAAO;IAkBf,OAAO,CAAC,UAAU;IAKlB,OAAO,CAAC,SAAS;CA6BlB"}