@jgengine/shell 0.19.0 → 0.22.0

package/dist/render/modelAssets.js

@@ -0,0 +1,43 @@
+import { MATERIAL_TEXTURE_SEMANTICS } from "@jgengine/core/material/materialAsset";
+const legacyMapRoles = ["color", "normal", "roughness", "ao", "metalness", "emissive", "height"];
+const modelMapRoles = [...legacyMapRoles, ...Object.keys(MATERIAL_TEXTURE_SEMANTICS).filter(role => !legacyMapRoles.includes(role))];
+/** Stable loader keys shared by preloading and material application. @internal */
+export function modelMapEntries(maps) {
+    const entries = {};
+    for (const key of modelMapRoles) {
+        if (maps[key] !== undefined)
+            entries[key] = maps[key];
+    }
+    return entries;
+}
+/** Start composed model dependencies together instead of discovering them after each parent commits. @internal */
+export function modelAssetRequests(model) {
+    const models = new Set();
+    const textureGroups = new Map();
+    const visited = new Set();
+    const visit = (next) => {
+        if (visited.has(next))
+            return;
+        visited.add(next);
+        models.add(next.url);
+        if (next.material?.maps !== undefined) {
+            const urls = Object.values(modelMapEntries(next.material.maps));
+            if (urls.length > 0)
+                textureGroups.set(JSON.stringify(urls), urls);
+        }
+        const referencedIds = new Set(next.materialAssignments?.map(assignment => assignment.materialId));
+        for (const asset of next.materialAssets ?? []) {
+            if (!referencedIds.has(asset.id))
+                continue;
+            const urls = Object.values(asset.textures ?? {}).map(metadata => metadata.url);
+            if (urls.length > 0)
+                textureGroups.set(JSON.stringify(urls), urls);
+        }
+        for (const child of [...(next.parts ?? []), ...(next.attachments ?? [])]) {
+            if (typeof child.model !== "string")
+                visit(child.model);
+        }
+    };
+    visit(model);
+    return { models: [...models], textureGroups: [...textureGroups.values()] };
+}

package/dist/render/modelBindPose.d.ts

@@ -0,0 +1,5 @@
+import * as THREE from "three";
+/** Skin-applied vertices captured before animation, shared by a loaded model's clones. @internal */
+export declare function modelBindPosePositions(mesh: THREE.SkinnedMesh): Float32Array;
+/** Retain the imported pose for normalization and colliders without sampling a live animation. @internal */
+export declare function copyModelBindPose(source: THREE.Object3D, clone: THREE.Object3D): void;

package/dist/render/modelBindPose.js

@@ -0,0 +1,35 @@
+import * as THREE from "three";
+const positionsByMesh = new WeakMap();
+const vertex = new THREE.Vector3();
+/** Skin-applied vertices captured before animation, shared by a loaded model's clones. @internal */
+export function modelBindPosePositions(mesh) {
+    let positions = positionsByMesh.get(mesh);
+    if (positions !== undefined)
+        return positions;
+    const attribute = mesh.geometry.getAttribute("position");
+    const skinned = mesh.geometry.getAttribute("skinIndex") !== undefined && mesh.geometry.getAttribute("skinWeight") !== undefined;
+    positions = new Float32Array(attribute.count * 3);
+    for (let index = 0; index < attribute.count; index++) {
+        if (skinned)
+            mesh.getVertexPosition(index, vertex);
+        else
+            vertex.fromBufferAttribute(attribute, index);
+        vertex.toArray(positions, index * 3);
+    }
+    positionsByMesh.set(mesh, positions);
+    return positions;
+}
+/** Retain the imported pose for normalization and colliders without sampling a live animation. @internal */
+export function copyModelBindPose(source, clone) {
+    source.updateMatrixWorld(true);
+    const positions = [];
+    source.traverse((node) => {
+        if (node.isSkinnedMesh === true)
+            positions.push(modelBindPosePositions(node));
+    });
+    let index = 0;
+    clone.traverse((node) => {
+        if (node.isSkinnedMesh === true)
+            positionsByMesh.set(node, positions[index++]);
+    });
+}

package/dist/render/modelLoad.d.ts

@@ -1,5 +1,6 @@
 import * as THREE from "three";
 import { GLTFLoader, type GLTF } from "three/examples/jsm/loaders/GLTFLoader.js";
+import { KTX2Loader } from "three/examples/jsm/loaders/KTX2Loader.js";
 import { type AssetLoadDiagnosis } from "@jgengine/core/scene/assetDiagnostics";
 /**
  * The shared GLB {@link THREE.LoadingManager}'s `onError` sink. It fires for EVERY item the manager
@@ -111,6 +112,8 @@ export interface ModelLoaderConfig {
 export declare function configureModelLoaders(options?: ModelLoaderConfig): Readonly<Required<ModelLoaderConfig>>;
 /** Detects GPU support for the configured KTX2 transcoder after a renderer exists. */
 export declare function detectKtx2Support(renderer: THREE.WebGLRenderer): void;
+/** Shared transcoder for authored material maps; GPU support is detected by the canvas. @internal */
+export declare function materialKtx2Loader(): KTX2Loader;
 /**
  * How long the shared GLB loader has been idle, in ms — `0` while any model is still
  * in flight. A capture host reads this to wait for streaming to finish instead of

package/dist/render/modelLoad.js

@@ -223,6 +223,7 @@ const DEFAULT_DRACO_DECODER_PATH = "https://cdn.jsdelivr.net/npm/three@0.182.0/e
 const DEFAULT_KTX2_TRANSCODER_PATH = "https://cdn.jsdelivr.net/npm/three@0.182.0/examples/jsm/libs/basis/";
 let configuredModelLoaders;
 let ktx2Loader;
+const ktx2DetectedRenderers = new WeakMap();
 /** Configures shared Draco and KTX2 loaders. Repeated calls with the same paths are no-ops. */
 export function configureModelLoaders(options = {}) {
     const next = {
@@ -242,7 +243,15 @@ export function configureModelLoaders(options = {}) {
 /** Detects GPU support for the configured KTX2 transcoder after a renderer exists. */
 export function detectKtx2Support(renderer) {
     configureModelLoaders();
+    if (ktx2DetectedRenderers.get(renderer) === ktx2Loader)
+        return;
     ktx2Loader?.detectSupport(renderer);
+    ktx2DetectedRenderers.set(renderer, ktx2Loader);
+}
+/** Shared transcoder for authored material maps; GPU support is detected by the canvas. @internal */
+export function materialKtx2Loader() {
+    configureModelLoaders();
+    return ktx2Loader;
 }
 // LoadingManager reports queue transitions, not per-item events: `onStart` fires when the
 // queue goes busy and `onLoad` when it drains (errors included, via itemEnd), so a flag plus

package/dist/render/modelNodeVisibility.d.ts

@@ -0,0 +1,6 @@
+import type { Object3D } from "three";
+import { type RigNodeDiagnostic } from "./rigNode.js";
+/** Order and duplicate references do not change a model instance's visibility selection. @internal */
+export declare function modelHiddenNodesKey(names?: readonly string[]): string;
+/** Apply visibility only to uniquely resolved nodes on an owned clone, retaining imported hidden state and rig hierarchy. @internal */
+export declare function applyModelNodeVisibility(root: Object3D, names?: readonly string[]): RigNodeDiagnostic[];

package/dist/render/modelNodeVisibility.js

@@ -0,0 +1,18 @@
+import { parseModelHiddenNodes } from "@jgengine/core/editor/modelNodeVisibility";
+import { resolveRigNode } from "./rigNode.js";
+/** Order and duplicate references do not change a model instance's visibility selection. @internal */
+export function modelHiddenNodesKey(names = []) {
+    return JSON.stringify([...new Set(names)].sort());
+}
+/** Apply visibility only to uniquely resolved nodes on an owned clone, retaining imported hidden state and rig hierarchy. @internal */
+export function applyModelNodeVisibility(root, names = []) {
+    const diagnostics = [];
+    for (const name of new Set(parseModelHiddenNodes(names))) {
+        const resolved = resolveRigNode(root, name);
+        if (resolved.node === undefined)
+            diagnostics.push(resolved.diagnostic);
+        else
+            resolved.node.visible = false;
+    }
+    return diagnostics;
+}

package/dist/render/modelRender.d.ts

@@ -1,13 +1,30 @@
 import * as THREE from "three";
 import type { PaintStroke } from "@jgengine/core/scene/paintLayer";
+import type { ModelConfig } from "@jgengine/core/game/playableGame";
+import { type MeasuredLocalBounds } from "./measureBounds.js";
 export declare const PAINT_TEXTURE_SIZE = 512;
 /** Shadow participation applied to every mesh of a cloned model; mirrors `ModelConfig.shadows`. */
 export type ModelShadowMode = "cast" | "receive" | "both" | "none";
-/** @internal */
+/** Register an instance replacement without transferring borrowed geometry or textures. @internal */
+export declare function ownModelMaterial(root: THREE.Object3D, material: THREE.Material): boolean;
+/** Resolve placement from bind bounds in the frame containing the imported root, shared by rendering and collider measurement. @internal */
+export declare function modelPlacementTransform(root: THREE.Object3D, model: ModelConfig, bindBounds?: MeasuredLocalBounds | null): {
+    scale: number;
+    position: [number, number, number];
+};
+/**
+ * Clone a model with independent pose and materials, retaining shared geometry and textures.
+ * @capability model-instance clone a loaded model for independent styling and animation
+ */
 export declare function cloneModelScene(source: THREE.Object3D, options?: {
     cloneMaterials?: boolean;
     shadows?: ModelShadowMode;
 }): THREE.Object3D;
+/**
+ * Release materials and bone textures owned by `cloneModelScene`; shared assets and attached models remain owned by their callers.
+ * @capability model-instance release a cloned model without disposing cached geometry or textures
+ */
+export declare function disposeModelScene(root: THREE.Object3D): void;
 /** @internal */
 export declare function disposeClonedMaterials(root: THREE.Object3D): void;
 /** @internal */

package/dist/render/modelRender.js

@@ -1,25 +1,103 @@
 import * as THREE from "three";
 import { clone as cloneSkinned } from "three/examples/jsm/utils/SkeletonUtils.js";
+import { measureLocalBounds } from "./measureBounds.js";
+import { copyModelBindPose } from "./modelBindPose.js";
 export const PAINT_TEXTURE_SIZE = 512;
-/** @internal */
+const modelResources = new WeakMap();
+/** Register an instance replacement without transferring borrowed geometry or textures. @internal */
+export function ownModelMaterial(root, material) {
+    const resources = modelResources.get(root);
+    if (resources === undefined)
+        return false;
+    resources.materials.add(material);
+    return true;
+}
+/** Resolve placement from bind bounds in the frame containing the imported root, shared by rendering and collider measurement. @internal */
+export function modelPlacementTransform(root, model, bindBounds) {
+    let scale = model.scale ?? 1;
+    let minY = 0;
+    let centerX = 0;
+    let centerZ = 0;
+    const bounds = model.targetHeight === undefined ? null : bindBounds === undefined ? measureLocalBounds(root) : bindBounds;
+    const height = bounds === null ? 0 : bounds.max[1] - bounds.min[1];
+    if (bounds !== null && Number.isFinite(height) && height > 0) {
+        scale *= model.targetHeight / height;
+        minY = bounds.min[1];
+        centerX = (bounds.min[0] + bounds.max[0]) / 2;
+        centerZ = (bounds.min[2] + bounds.max[2]) / 2;
+    }
+    else if ((model.anchor ?? "center") === "center" && model.dims !== undefined) {
+        minY = model.dims.minY;
+        centerX = model.dims.center.x;
+        centerZ = model.dims.center.z;
+    }
+    return { scale, position: [-scale * centerX, (model.y ?? 0) - scale * minY, -scale * centerZ] };
+}
+/**
+ * Clone a model with independent pose and materials, retaining shared geometry and textures.
+ * @capability model-instance clone a loaded model for independent styling and animation
+ */
 export function cloneModelScene(source, options) {
     const clone = cloneSkinned(source);
+    copyModelBindPose(source, clone);
     const shadows = options?.shadows ?? "both";
     const cloneMaterials = options?.cloneMaterials !== false;
+    const materials = new Map();
+    const sourceSkeletons = [];
+    source.traverse((node) => {
+        if (node.isSkinnedMesh === true)
+            sourceSkeletons.push(node.skeleton);
+    });
+    const skeletons = new Map();
+    let skinnedIndex = 0;
+    const cloneMaterial = (source) => {
+        let material = materials.get(source);
+        if (material === undefined) {
+            material = source.clone();
+            material.onBeforeCompile = source.onBeforeCompile;
+            material.customProgramCacheKey = source.customProgramCacheKey;
+            materials.set(source, material);
+        }
+        return material;
+    };
     clone.traverse((node) => {
         const mesh = node;
         if (!mesh.isMesh)
             return;
+        if (mesh.isSkinnedMesh === true) {
+            const skinned = mesh;
+            const sourceSkeleton = sourceSkeletons[skinnedIndex++];
+            const shared = skeletons.get(sourceSkeleton);
+            if (shared === undefined)
+                skeletons.set(sourceSkeleton, skinned.skeleton);
+            else
+                skinned.skeleton = shared;
+        }
         mesh.castShadow = shadows === "cast" || shadows === "both";
         mesh.receiveShadow = shadows === "receive" || shadows === "both";
         if (!cloneMaterials)
             return;
         mesh.material = Array.isArray(mesh.material)
-            ? mesh.material.map((material) => material.clone())
-            : mesh.material.clone();
+            ? mesh.material.map(cloneMaterial)
+            : cloneMaterial(mesh.material);
     });
+    modelResources.set(clone, { materials: new Set(materials.values()), skeletons: new Set(skeletons.values()) });
     return clone;
 }
+/**
+ * Release materials and bone textures owned by `cloneModelScene`; shared assets and attached models remain owned by their callers.
+ * @capability model-instance release a cloned model without disposing cached geometry or textures
+ */
+export function disposeModelScene(root) {
+    const resources = modelResources.get(root);
+    if (resources === undefined)
+        return;
+    for (const material of resources.materials)
+        material.dispose();
+    // Effect replay can recreate a bone texture on this same scene, so retain its ownership record.
+    for (const skeleton of resources.skeletons)
+        skeleton.dispose();
+}
 /** @internal */
 export function disposeClonedMaterials(root) {
     const seen = new Set();

package/dist/render/projectedOverdraw.d.ts

@@ -0,0 +1,35 @@
+import * as THREE from "three";
+/** Sampling resolution; lower resolutions change thin geometry and alpha-mask raster coverage. */
+export interface ProjectedOverdrawOptions {
+    width?: number;
+    height?: number;
+}
+/** Projected mesh-fragment overlap, with depth rejection disabled; this is not production early-Z overdraw or GPU timing. */
+export interface ProjectedOverdrawReport {
+    width: number;
+    height: number;
+    sampledPixels: number;
+    coveredPixels: number;
+    fragmentSamples: number;
+    mean: number;
+    meanCovered: number;
+    max: number;
+    meshes: number;
+    materialSlots: number;
+    /** Native opaque render-queue slots, including masked slots. */
+    opaqueSlots: number;
+    /** Slots with alphaTest/alphaHash; this can overlap queue counts. */
+    maskedSlots: number;
+    blendedSlots: number;
+    transmissionSlots: number;
+    caveats: readonly string[];
+}
+/** Convert finite nonnegative RGBA32F sample counts to overlap statistics. @internal */
+export declare function summarizeProjectedOverdraw(pixels: Float32Array, width: number, height: number): Pick<ProjectedOverdrawReport, "sampledPixels" | "coveredPixels" | "fragmentSamples" | "mean" | "meanCovered" | "max">;
+/**
+ * Opt in to a synchronous offscreen count of projected mesh fragments. Native PBR/unlit vertex transforms and alpha discard remain; depth rejection, shadow/refraction passes and postprocessing do not participate.
+ * Blended texels count equally, including zero opacity when native alphaTest/alphaHash does not discard them. Pure shader-modifying onBeforeCompile callbacks are retained; render callbacks, custom shader materials, stencil and alpha-to-coverage are rejected.
+ * The float readback stalls the GPU. Temporary materials/target are disposed and renderer draw counters/state restored; borrowed assets may become resident while measured.
+ * @capability projected-overdraw sample actual mesh/camera fragment overlap with native coverage and explicit depth/blending/transmission limits
+ */
+export declare function measureProjectedOverdraw(renderer: THREE.WebGLRenderer, scene: THREE.Scene, camera: THREE.Camera, options?: ProjectedOverdrawOptions): ProjectedOverdrawReport;

package/dist/render/projectedOverdraw.js

@@ -0,0 +1,204 @@
+import * as THREE from "three";
+function supported(material) {
+    const flags = material;
+    return flags.isMeshStandardMaterial === true || flags.isMeshBasicMaterial === true;
+}
+/** Convert finite nonnegative RGBA32F sample counts to overlap statistics. @internal */
+export function summarizeProjectedOverdraw(pixels, width, height) {
+    if (pixels.length !== width * height * 4)
+        throw new Error("Projected-overdraw readback dimensions do not match the RGBA buffer");
+    let coveredPixels = 0, fragmentSamples = 0, max = 0;
+    for (let index = 0; index < pixels.length; index += 4) {
+        const count = pixels[index];
+        if (!Number.isFinite(count) || count < 0)
+            throw new Error("Projected-overdraw float readback returned invalid samples");
+        if (count > 0)
+            coveredPixels++;
+        fragmentSamples += count;
+        max = Math.max(max, count);
+    }
+    const sampledPixels = width * height;
+    return { sampledPixels, coveredPixels, fragmentSamples, mean: fragmentSamples / sampledPixels, meanCovered: coveredPixels === 0 ? 0 : fragmentSamples / coveredPixels, max };
+}
+function countMaterial(source) {
+    const material = source.clone();
+    const compile = source.onBeforeCompile;
+    const key = source.customProgramCacheKey();
+    material.onBeforeCompile = (shader, renderer) => {
+        compile.call(material, shader, renderer);
+        const tail = /#include <dithering_fragment>(\s*})\s*$/;
+        if (!tail.test(shader.fragmentShader))
+            throw new Error("Projected overdraw requires the native final fragment chunk; this shader callback changes the fragment main tail");
+        shader.fragmentShader = shader.fragmentShader.replace(tail, "#include <dithering_fragment>\ngl_FragColor = vec4(1.0);$1");
+    };
+    material.customProgramCacheKey = () => `${key}|jg-projected-overdraw:v1`;
+    material.transparent = true;
+    material.blending = THREE.CustomBlending;
+    material.blendEquation = THREE.AddEquation;
+    material.blendSrc = THREE.OneFactor;
+    material.blendDst = THREE.OneFactor;
+    material.blendEquationAlpha = THREE.AddEquation;
+    material.blendSrcAlpha = THREE.OneFactor;
+    material.blendDstAlpha = THREE.OneFactor;
+    material.depthTest = false;
+    material.depthWrite = false;
+    material.colorWrite = true;
+    material.forceSinglePass = true;
+    material.toneMapped = false;
+    material.premultipliedAlpha = false;
+    material.alphaToCoverage = false;
+    if (material.isMeshPhysicalMaterial)
+        material.transmission = 0;
+    return material;
+}
+/**
+ * Opt in to a synchronous offscreen count of projected mesh fragments. Native PBR/unlit vertex transforms and alpha discard remain; depth rejection, shadow/refraction passes and postprocessing do not participate.
+ * Blended texels count equally, including zero opacity when native alphaTest/alphaHash does not discard them. Pure shader-modifying onBeforeCompile callbacks are retained; render callbacks, custom shader materials, stencil and alpha-to-coverage are rejected.
+ * The float readback stalls the GPU. Temporary materials/target are disposed and renderer draw counters/state restored; borrowed assets may become resident while measured.
+ * @capability projected-overdraw sample actual mesh/camera fragment overlap with native coverage and explicit depth/blending/transmission limits
+ */
+export function measureProjectedOverdraw(renderer, scene, camera, options = {}) {
+    const width = options.width ?? 128;
+    const height = options.height ?? 128;
+    if (!Number.isInteger(width) || !Number.isInteger(height) || width < 1 || height < 1 || width > 2048 || height > 2048)
+        throw new Error("Projected-overdraw resolution must contain integer dimensions from 1 to 2048");
+    if (!renderer.extensions.has("EXT_color_buffer_float") || !renderer.extensions.has("EXT_float_blend"))
+        throw new Error("Projected overdraw requires RGBA32F rendering/readback and EXT_float_blend; this renderer cannot provide a fragment count");
+    if (camera.isArrayCamera)
+        throw new Error("Projected overdraw requires one camera projection; measure array-camera views separately");
+    if (scene.overrideMaterial !== null)
+        throw new Error("Projected overdraw does not support an active scene overrideMaterial");
+    const meshes = [];
+    const originals = new Map();
+    const materials = new Set();
+    let materialSlots = 0, opaqueSlots = 0, maskedSlots = 0, blendedSlots = 0, transmissionSlots = 0;
+    if (scene.onBeforeRender !== THREE.Object3D.prototype.onBeforeRender || scene.onAfterRender !== THREE.Object3D.prototype.onAfterRender)
+        throw new Error("Projected overdraw rejects scene render callbacks");
+    scene.traverseVisible(node => {
+        if (!node.layers.test(camera.layers))
+            return;
+        const flags = node;
+        if (flags.geometry?.drawRange.count === 0 || (flags.isInstancedMesh && flags.count === 0))
+            return;
+        if (flags.material !== undefined && (Array.isArray(flags.material) ? flags.material : [flags.material]).every(material => !material.visible))
+            return;
+        if (flags.isPoints || flags.isLine || flags.isSprite || flags.isBatchedMesh)
+            throw new Error(`Projected overdraw does not support ${node.type}`);
+        if (!flags.isMesh)
+            return;
+        if (node.onBeforeRender !== THREE.Object3D.prototype.onBeforeRender || node.onAfterRender !== THREE.Object3D.prototype.onAfterRender)
+            throw new Error(`Projected overdraw rejects render callbacks on ${node.name || node.type}`);
+        meshes.push(flags);
+        originals.set(flags, flags.material);
+        for (const material of Array.isArray(flags.material) ? flags.material : [flags.material]) {
+            if (!material.visible)
+                continue;
+            if (!supported(material))
+                throw new Error(`Projected overdraw requires native PBR or unlit material; ${material.name || material.type} is unsupported`);
+            if (material.onBeforeRender !== THREE.Material.prototype.onBeforeRender)
+                throw new Error(`Projected overdraw rejects material render callbacks on ${material.name || material.type}`);
+            if (material.stencilWrite || material.alphaToCoverage)
+                throw new Error(`Projected overdraw cannot reproduce stencil or multisample alpha coverage on ${material.name || material.type}`);
+            materials.add(material);
+            materialSlots++;
+            if (material.alphaTest > 0 || material.alphaHash)
+                maskedSlots++;
+            if (material.transparent)
+                blendedSlots++;
+            else
+                opaqueSlots++;
+            if (material.transmission > 0)
+                transmissionSlots++;
+        }
+    });
+    const target = new THREE.WebGLRenderTarget(width, height, { type: THREE.FloatType, format: THREE.RGBAFormat, minFilter: THREE.NearestFilter, magFilter: THREE.NearestFilter, depthBuffer: false, stencilBuffer: false, generateMipmaps: false });
+    target.texture.colorSpace = THREE.NoColorSpace;
+    const replacements = new Map();
+    const userData = new Map([...materials].map(material => [material, { object: material.userData, entries: { ...material.userData } }]));
+    const context = renderer.getContext();
+    const state = {
+        target: renderer.getRenderTarget(), face: renderer.getActiveCubeFace(), mip: renderer.getActiveMipmapLevel(),
+        viewport: renderer.getCurrentViewport(new THREE.Vector4()),
+        scissor: new THREE.Vector4().fromArray(context.getParameter(context.SCISSOR_BOX)), scissorTest: context.getParameter(context.SCISSOR_TEST),
+        clearColor: renderer.getClearColor(new THREE.Color()), clearAlpha: renderer.getClearAlpha(), autoClear: renderer.autoClear,
+        autoClearColor: renderer.autoClearColor, autoClearDepth: renderer.autoClearDepth, autoClearStencil: renderer.autoClearStencil,
+        xr: renderer.xr.enabled, shadows: renderer.shadowMap.enabled, infoAutoReset: renderer.info.autoReset, render: { ...renderer.info.render },
+        background: scene.background, fog: scene.fog, shaderCheck: renderer.debug.checkShaderErrors, shaderError: renderer.debug.onShaderError,
+    };
+    try {
+        const shaderErrors = [];
+        renderer.debug.checkShaderErrors = true;
+        renderer.debug.onShaderError = (gl, program, vertex, fragment) => { shaderErrors.push([gl.getProgramInfoLog(program), gl.getShaderInfoLog(vertex), gl.getShaderInfoLog(fragment)].filter(Boolean).join("\n")); };
+        renderer.xr.enabled = false;
+        renderer.shadowMap.enabled = false;
+        renderer.info.autoReset = false;
+        renderer.autoClear = false;
+        renderer.setRenderTarget(target);
+        renderer.setClearColor(0x000000, 0.25);
+        renderer.clear(true, false, false);
+        const probe = new Float32Array(4).fill(NaN);
+        renderer.readRenderTargetPixels(target, 0, 0, 1, 1, probe);
+        if (!Number.isFinite(probe[3]) || Math.abs(probe[3] - 0.25) > 0.001)
+            throw new Error("Projected overdraw RGBA32F readback is unsupported or incomplete");
+        renderer.setClearColor(0x000000, 0);
+        renderer.clear(true, false, false);
+        for (const source of materials)
+            replacements.set(source, countMaterial(source));
+        for (const mesh of meshes) {
+            const source = originals.get(mesh);
+            mesh.material = Array.isArray(source) ? source.map(material => replacements.get(material) ?? material) : replacements.get(source) ?? source;
+        }
+        scene.background = null;
+        scene.fog = null;
+        renderer.render(scene, camera);
+        if (shaderErrors.length > 0)
+            throw new Error(`Projected-overdraw shader compilation failed: ${shaderErrors.join("\n")}`);
+        const pixels = new Float32Array(width * height * 4).fill(NaN);
+        renderer.readRenderTargetPixels(target, 0, 0, width, height, pixels);
+        return { width, height, ...summarizeProjectedOverdraw(pixels, width, height), meshes: meshes.length, materialSlots, opaqueSlots, maskedSlots, blendedSlots, transmissionSlots,
+            caveats: ["Depth rejection is disabled: projected overlap is an upper bound on production opaque shading, not early-Z overdraw.", "Native alphaTest/alphaHash discard is retained at this sampled resolution; blended texels count equally, including zero opacity.", "Transmission refraction/background, shadow, postprocessing, sky and MSAA passes are excluded. No GPU timing is measured.", "Native vertex transforms and pure shader-modifying material callbacks remain; borrowed assets may be uploaded during this diagnostic."] };
+    }
+    finally {
+        for (const [mesh, material] of originals)
+            mesh.material = material;
+        for (const [material, saved] of userData) {
+            material.userData = saved.object;
+            for (const key of Object.keys(saved.object))
+                if (!(key in saved.entries))
+                    delete saved.object[key];
+            Object.assign(saved.object, saved.entries);
+        }
+        scene.background = state.background;
+        scene.fog = state.fog;
+        renderer.xr.enabled = state.xr;
+        renderer.shadowMap.enabled = state.shadows;
+        renderer.autoClear = state.autoClear;
+        renderer.autoClearColor = state.autoClearColor;
+        renderer.autoClearDepth = state.autoClearDepth;
+        renderer.autoClearStencil = state.autoClearStencil;
+        renderer.info.autoReset = state.infoAutoReset;
+        renderer.debug.checkShaderErrors = state.shaderCheck;
+        renderer.debug.onShaderError = state.shaderError;
+        for (const material of replacements.values())
+            material.dispose();
+        target.dispose();
+        if (state.target === null)
+            renderer.setRenderTarget(null, state.face, state.mip);
+        else {
+            const viewport = state.target.viewport.clone(), scissor = state.target.scissor.clone(), scissorTest = state.target.scissorTest;
+            state.target.viewport.copy(state.viewport);
+            state.target.scissor.copy(state.scissor);
+            state.target.scissorTest = state.scissorTest;
+            try {
+                renderer.setRenderTarget(state.target, state.face, state.mip);
+            }
+            finally {
+                state.target.viewport.copy(viewport);
+                state.target.scissor.copy(scissor);
+                state.target.scissorTest = scissorTest;
+            }
+        }
+        renderer.setClearColor(state.clearColor, state.clearAlpha);
+        Object.assign(renderer.info.render, state.render);
+    }
+}

package/dist/render/resolveModel.d.ts

@@ -1,5 +1,6 @@
-import type { AssetCatalog } from "@jgengine/core/scene/assetCatalog";
+import type { AssetCatalog, ModelAssetRef } from "@jgengine/core/scene/assetCatalog";
 import type { ModelConfig } from "@jgengine/core/game/playableGame";
+import type { SceneObject } from "@jgengine/core/scene/objectStore";
 import type { GameContextModels } from "@jgengine/core/runtime/gameContext";
 export interface ModelResolveContext {
     seam: "entityModels" | "objectModels" | "scatterModels";
@@ -16,6 +17,14 @@ export declare function resolveModel(value: string | ModelConfig | undefined, as
  * @internal
  */
 export declare function tryResolveCatalogModel(id: string, assets: AssetCatalog): ModelConfig | undefined;
+/** @internal */
+export interface ObjectModelCacheEntry {
+    input: string | ModelConfig | undefined;
+    ref: ModelAssetRef | null;
+    model: ModelConfig | undefined;
+}
+/** Resolve a live object's catalog and animation, retaining unchanged base model identities. @internal */
+export declare function resolveObjectModel(object: SceneObject, models: Record<string, string | ModelConfig> | undefined, assets: AssetCatalog, cache: Map<string, ObjectModelCacheEntry>): ModelConfig | undefined;
 /**
  * Resolve an entity model plus bone-attachment / kit-of-parts models through the catalog
  * so mounts receive fully-resolved `ModelConfig`s.
@@ -45,7 +54,8 @@ export declare function resolveModelPlan(assets: AssetCatalog, plan: Record<stri
  * The `createGameContext` `models` lookup derived from a playable's render maps: what each entity kind /
  * object catalog id actually renders as, so colliders auto-fit the rendered mesh. Soft-resolves string
  * ids (a missing catalog id keeps the default collider instead of throwing — the render path already
- * reports it), passes inline configs through. `undefined` when the playable maps no models at all.
+ * reports it), passes inline configs through. Unmapped objects resolve their own catalog id,
+ * matching WorldScene; `undefined` when both the catalog and model maps are empty.
  * @internal
  */
 export declare function contextModels(playable: {

package/dist/render/resolveModel.js

@@ -8,6 +8,7 @@ import { warnOnce } from "@jgengine/core/devtools/warnOnce";
 function catalogModelConfig(ref) {
     return {
         url: ref.url,
+        ...(ref.anchor === undefined ? {} : { anchor: ref.anchor }),
         ...(ref.dims === undefined ? {} : { dims: ref.dims }),
         ...(ref.collisionMesh === undefined ? {} : { collisionMesh: ref.collisionMesh }),
         animation: "auto",
@@ -40,6 +41,18 @@ export function tryResolveCatalogModel(id, assets) {
         return undefined;
     return catalogModelConfig(ref);
 }
+/** Resolve a live object's catalog and animation, retaining unchanged base model identities. @internal */
+export function resolveObjectModel(object, models, assets, cache) {
+    const input = models?.[object.catalogId];
+    const ref = assets.resolve(typeof input === "string" ? input : object.catalogId);
+    const cached = cache.get(object.catalogId);
+    const resolved = cached !== undefined && cached.input === input && cached.ref === ref ? cached.model :
+        resolveModel(input, assets, { seam: "objectModels", key: object.catalogId }) ?? tryResolveCatalogModel(object.catalogId, assets);
+    if (cached === undefined || cached.model !== resolved || cached.input !== input || cached.ref !== ref) {
+        cache.set(object.catalogId, { input, ref, model: resolved });
+    }
+    return resolved !== undefined && object.animation !== undefined ? { ...resolved, animation: object.animation } : resolved;
+}
 /**
  * Resolve an entity model plus bone-attachment / kit-of-parts models through the catalog
  * so mounts receive fully-resolved `ModelConfig`s.
@@ -114,17 +127,21 @@ function softModelLookup(map, assets) {
  * The `createGameContext` `models` lookup derived from a playable's render maps: what each entity kind /
  * object catalog id actually renders as, so colliders auto-fit the rendered mesh. Soft-resolves string
  * ids (a missing catalog id keeps the default collider instead of throwing — the render path already
- * reports it), passes inline configs through. `undefined` when the playable maps no models at all.
+ * reports it), passes inline configs through. Unmapped objects resolve their own catalog id,
+ * matching WorldScene; `undefined` when both the catalog and model maps are empty.
  * @internal
  */
 export function contextModels(playable) {
     const entity = softModelLookup(playable.entityModels, playable.game.assets);
-    const object = softModelLookup(playable.objectModels, playable.game.assets);
-    if (entity === undefined && object === undefined)
+    const explicitObject = softModelLookup(playable.objectModels, playable.game.assets);
+    if (entity === undefined && explicitObject === undefined && playable.game.assets.ids().length === 0)
         return undefined;
+    const object = (key) => playable.objectModels?.[key] === undefined
+        ? tryResolveCatalogModel(key, playable.game.assets)
+        : explicitObject?.(key);
     return {
         ...(entity === undefined ? {} : { entity }),
-        ...(object === undefined ? {} : { object }),
+        object,
     };
 }
 /**

package/dist/render/rigNode.d.ts

@@ -0,0 +1,26 @@
+import type { Object3D } from "three";
+/** A missing or nonunique node reference that a rig author can repair. */
+export interface RigNodeDiagnostic {
+    code: "missing-node" | "ambiguous-node";
+    message: string;
+}
+/** A node on this model instance, or a diagnostic instead of an arbitrary attachment target. */
+export type RigNodeResolution = {
+    node: Object3D;
+    matchedBy: "runtime" | "authored";
+    diagnostic?: undefined;
+} | {
+    node: undefined;
+    matchedBy?: undefined;
+    diagnostic: RigNodeDiagnostic;
+};
+/**
+ * Resolves a bone or attachment slot by its exact runtime name first, then by the original
+ * imported name preserved as `userData.name`. GLTFLoader sanitizes names such as `handslot.r`
+ * to `handslotr`; authored references remain usable without renaming the animated hierarchy.
+ * Both lookups require a unique target. Call on model load or slot changes, not each frame,
+ * and keep the result with that model instance rather than reusing a cached asset's node.
+ *
+ * @capability imported-rig-node resolve original imported bone and slot names with ambiguity diagnostics
+ */
+export declare function resolveRigNode(rig: Object3D, name: string): RigNodeResolution;