@jgengine/shell 0.18.1 → 0.21.0

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
@@ -61,6 +62,35 @@ export declare function modelLoadFallbacks(): readonly {
 }[];
 /** Drops the recorded placeholder list. For tests and between capture runs. @internal */
 export declare function clearModelLoadFallbacks(): void;
+/** Per-model triangle ceiling before the loader warns. A prop is a few thousand triangles; a hero rig tens of thousands. */
+export declare const DEFAULT_MODEL_TRIANGLE_BUDGET = 100000;
+/** Retune the per-model triangle budget (a cinematic game may raise it; a mobile target lowers it). Non-finite or non-positive values restore the default. */
+export declare function setModelTriangleBudget(triangles: number): void;
+/** Triangles a loaded model contributes per draw, summing every mesh (instanced meshes count once per instance). @internal */
+export declare function countSceneTriangles(root: THREE.Object3D): number;
+/** One over-budget model as {@link heavyModels} reports it: the URL the loader fetched, its triangle count, and the budget it exceeded. */
+export interface HeavyModelRecord {
+    url: string;
+    triangles: number;
+    budget: number;
+}
+/**
+ * Record a loaded model's triangle count against the budget: over budget warns once per URL and lands in
+ * {@link heavyModels}; under budget is silent. Split out so the wiring is unit-testable without a GL context.
+ * @internal
+ */
+export declare function recordModelTriangles(url: string, triangles: number, overrides?: {
+    warn?: (record: HeavyModelRecord) => void;
+}): void;
+/**
+ * Every model the shared loader resolved whose triangle count exceeds the budget, in load order. A heavy
+ * prop is invisible in a screenshot and only shows up as a slow frame, so the loader measures each GLB as it
+ * lands and this exposes the verdict for `debug_snapshot` probes and smoke tests to assert against.
+ * @capability heavy-models models over the per-model triangle budget, for perf probes and smoke assertions
+ */
+export declare function heavyModels(): readonly HeavyModelRecord[];
+/** Drops the heavy-model list and the once-per-URL warning memory. For tests and between capture runs. @internal */
+export declare function clearHeavyModels(): void;
 /**
  * A {@link GLTFLoader} whose success path is unchanged but whose failures degrade
  * gracefully: when a load errors, it probes the URL and — for a diagnosed broken
@@ -82,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

@@ -140,6 +140,63 @@ export function modelLoadFallbacks() {
 export function clearModelLoadFallbacks() {
     servedFallbacks.length = 0;
 }
+/** Per-model triangle ceiling before the loader warns. A prop is a few thousand triangles; a hero rig tens of thousands. */
+export const DEFAULT_MODEL_TRIANGLE_BUDGET = 100_000;
+let modelTriangleBudget = DEFAULT_MODEL_TRIANGLE_BUDGET;
+/** Retune the per-model triangle budget (a cinematic game may raise it; a mobile target lowers it). Non-finite or non-positive values restore the default. */
+export function setModelTriangleBudget(triangles) {
+    modelTriangleBudget = Number.isFinite(triangles) && triangles > 0 ? triangles : DEFAULT_MODEL_TRIANGLE_BUDGET;
+}
+/** Triangles a loaded model contributes per draw, summing every mesh (instanced meshes count once per instance). @internal */
+export function countSceneTriangles(root) {
+    let total = 0;
+    root.traverse((node) => {
+        const mesh = node;
+        if (mesh.isMesh !== true || mesh.geometry === undefined)
+            return;
+        const geometry = mesh.geometry;
+        const vertices = geometry.index !== null ? geometry.index.count : geometry.attributes.position?.count ?? 0;
+        const instances = mesh.isInstancedMesh === true && typeof mesh.count === "number" ? mesh.count : 1;
+        total += Math.floor(vertices / 3) * instances;
+    });
+    return total;
+}
+const heavyModelRecords = [];
+const warnedHeavyUrls = new Set();
+function warnHeavyModel(record) {
+    if (typeof console === "undefined")
+        return;
+    console.warn(`[jgengine] model ${record.url} has ${record.triangles.toLocaleString()} triangles (budget ${record.budget.toLocaleString()}). A game prop should be a few thousand — pick a lighter asset or decimate it.`);
+}
+/**
+ * Record a loaded model's triangle count against the budget: over budget warns once per URL and lands in
+ * {@link heavyModels}; under budget is silent. Split out so the wiring is unit-testable without a GL context.
+ * @internal
+ */
+export function recordModelTriangles(url, triangles, overrides = {}) {
+    if (triangles <= modelTriangleBudget)
+        return;
+    const record = { url, triangles, budget: modelTriangleBudget };
+    heavyModelRecords.push(record);
+    if (warnedHeavyUrls.has(url))
+        return;
+    warnedHeavyUrls.add(url);
+    (overrides.warn ?? warnHeavyModel)(record);
+}
+/**
+ * Every model the shared loader resolved whose triangle count exceeds the budget, in load order. A heavy
+ * prop is invisible in a screenshot and only shows up as a slow frame, so the loader measures each GLB as it
+ * lands and this exposes the verdict for `debug_snapshot` probes and smoke tests to assert against.
+ * @capability heavy-models models over the per-model triangle budget, for perf probes and smoke assertions
+ */
+export function heavyModels() {
+    return heavyModelRecords;
+}
+/** Drops the heavy-model list and the once-per-URL warning memory. For tests and between capture runs. @internal */
+export function clearHeavyModels() {
+    heavyModelRecords.length = 0;
+    warnedHeavyUrls.clear();
+}
 /**
  * A {@link GLTFLoader} whose success path is unchanged but whose failures degrade
  * gracefully: when a load errors, it probes the URL and — for a diagnosed broken
@@ -151,7 +208,10 @@ export function clearModelLoadFallbacks() {
  */
 export class DiagnosticGLTFLoader extends GLTFLoader {
     load(url, onLoad, onProgress, onError) {
-        super.load(url, onLoad, onProgress, (event) => {
+        super.load(url, (gltf) => {
+            recordModelTriangles(url, countSceneTriangles(gltf.scene));
+            onLoad(gltf);
+        }, onProgress, (event) => {
             if (onError === undefined)
                 return;
             // Probe the URL the loader actually fetched (base-resolved), not the raw input.
@@ -163,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 = {
@@ -182,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: {