@jgengine/shell 0.10.0 → 0.12.0

package/dist/render/modelRender.d.ts

@@ -1,23 +1,34 @@
 import * as THREE from "three";
 import type { PaintStroke } from "@jgengine/core/scene/paintLayer";
 export declare const PAINT_TEXTURE_SIZE = 512;
+/** @internal */
 export declare function cloneModelScene(source: THREE.Object3D, options?: {
     cloneMaterials?: boolean;
 }): THREE.Object3D;
+/** @internal */
 export declare function disposeClonedMaterials(root: THREE.Object3D): void;
+/** @internal */
 export declare function standardMaterialsOf(root: THREE.Object3D): THREE.MeshStandardMaterial[];
 export interface MaterialCache {
     materials: THREE.MeshStandardMaterial[];
     seedColor: THREE.Color;
 }
+/** @internal */
 export declare function cacheStandardMaterials(root: THREE.Object3D, into?: MaterialCache | null): MaterialCache;
+/** @internal */
 export declare function applyPaintTextureToMaterials(materials: readonly THREE.MeshStandardMaterial[], paint: PaintCanvas): void;
 export interface PaintCanvas {
     canvas: HTMLCanvasElement;
     context: CanvasRenderingContext2D;
     texture: THREE.CanvasTexture;
 }
+/** @internal */
 export declare function createPaintCanvas(seed: THREE.MeshStandardMaterial, size?: number): PaintCanvas;
+/** @internal */
+export declare function disposePaintCanvas(paint: PaintCanvas): void;
+/** @internal */
 export declare function drawPaintStrokes(paint: PaintCanvas, strokes: readonly PaintStroke[]): void;
+/** @internal */
 export declare function applyPaintTexture(root: THREE.Object3D, paint: PaintCanvas): void;
+/** @internal */
 export declare function syncPaintCanvas(paint: PaintCanvas, seedColor: THREE.Color, strokes: readonly PaintStroke[], drawnCount: number): number;

package/dist/render/modelRender.js

@@ -1,6 +1,7 @@
 import * as THREE from "three";
 import { clone as cloneSkinned } from "three/examples/jsm/utils/SkeletonUtils.js";
 export const PAINT_TEXTURE_SIZE = 512;
+/** @internal */
 export function cloneModelScene(source, options) {
     const clone = cloneSkinned(source);
     if (options?.cloneMaterials === false)
@@ -15,6 +16,7 @@ export function cloneModelScene(source, options) {
     });
     return clone;
 }
+/** @internal */
 export function disposeClonedMaterials(root) {
     const seen = new Set();
     root.traverse((node) => {
@@ -33,6 +35,7 @@ export function disposeClonedMaterials(root) {
 function isMeshStandardMaterial(material) {
     return material.isMeshStandardMaterial === true;
 }
+/** @internal */
 export function standardMaterialsOf(root) {
     const materials = [];
     root.traverse((node) => {
@@ -46,6 +49,7 @@ export function standardMaterialsOf(root) {
     });
     return materials;
 }
+/** @internal */
 export function cacheStandardMaterials(root, into) {
     if (into !== null && into !== undefined)
         return into;
@@ -53,12 +57,14 @@ export function cacheStandardMaterials(root, into) {
     const seedColor = materials[0]?.color.clone() ?? new THREE.Color("#ffffff");
     return { materials, seedColor };
 }
+/** @internal */
 export function applyPaintTextureToMaterials(materials, paint) {
     for (const material of materials) {
         material.map = paint.texture;
         material.needsUpdate = true;
     }
 }
+/** @internal */
 export function createPaintCanvas(seed, size = PAINT_TEXTURE_SIZE) {
     const canvas = document.createElement("canvas");
     canvas.width = size;
@@ -76,6 +82,13 @@ export function createPaintCanvas(seed, size = PAINT_TEXTURE_SIZE) {
     texture.colorSpace = seed.map?.colorSpace ?? THREE.SRGBColorSpace;
     return { canvas, context, texture };
 }
+/** @internal */
+export function disposePaintCanvas(paint) {
+    paint.texture.dispose();
+    paint.canvas.width = 0;
+    paint.canvas.height = 0;
+}
+/** @internal */
 export function drawPaintStrokes(paint, strokes) {
     const { canvas, context, texture } = paint;
     for (const stroke of strokes) {
@@ -86,9 +99,11 @@ export function drawPaintStrokes(paint, strokes) {
     }
     texture.needsUpdate = true;
 }
+/** @internal */
 export function applyPaintTexture(root, paint) {
     applyPaintTextureToMaterials(standardMaterialsOf(root), paint);
 }
+/** @internal */
 export function syncPaintCanvas(paint, seedColor, strokes, drawnCount) {
     if (strokes.length < drawnCount) {
         const { canvas, context } = paint;

package/dist/render/resolveModel.d.ts

@@ -1,14 +1,65 @@
 import type { AssetCatalog } from "@jgengine/core/scene/assetCatalog";
 import type { ModelConfig } from "@jgengine/core/game/playableGame";
+import type { GameContextModels } from "@jgengine/core/runtime/gameContext";
 export interface ModelResolveContext {
-    seam: "entityModels" | "objectModels";
+    seam: "entityModels" | "objectModels" | "scatterModels";
     key: string;
 }
 /**
  * Resolve a string asset id or a direct ModelConfig. Missing/misspelled catalog
  * ids throw — silent generic-primitive fallback only happens when the mapping
  * omits the key entirely (or uses tryResolveCatalogModel for optional ids).
- */
+  * @internal
+  */
 export declare function resolveModel(value: string | ModelConfig | undefined, assets: AssetCatalog, context?: ModelResolveContext): ModelConfig | undefined;
-/** Soft lookup used when an object catalog id may double as a model asset id. */
+/** Soft lookup used when an object catalog id may double as a model asset id.
+ * @internal
+ */
 export declare function tryResolveCatalogModel(id: string, assets: AssetCatalog): ModelConfig | undefined;
+/**
+ * Resolve an entity model plus bone-attachment / kit-of-parts models through the catalog
+ * so mounts receive fully-resolved `ModelConfig`s.
+ * @internal
+ */
+export declare function resolveEntityModel(value: string | ModelConfig | undefined, assets: AssetCatalog, key: string): ModelConfig | undefined;
+/**
+ * Preferred + optional fallback catalog ids for a single entity/object slot.
+ * Soft-resolves through the catalog: when neither id is live (pack not pulled/
+ * reindexed yet), the mapping is omitted and the shell keeps its primitive.
+ * Re-home later by fixing ids / pulling packs — no Kenney, no hard throws.
+ */
+export type ModelPick = {
+    model?: string;
+    fallbackModel?: string;
+    style?: Omit<ModelConfig, "url" | "dims">;
+};
+/** Soft-resolve `model`, then `fallbackModel`; merge `style` when either hits.
+ * @internal
+ */
+export declare function pickModel(assets: AssetCatalog, pick: ModelPick): ModelConfig | undefined;
+/** Build an entityModels/objectModels map from a plan; missing catalog ids drop out (primitive).
+ * @internal
+ */
+export declare function resolveModelPlan(assets: AssetCatalog, plan: Record<string, ModelPick>): Record<string, ModelConfig>;
+/**
+ * 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.
+ * @internal
+ */
+export declare function contextModels(playable: {
+    game: {
+        assets: AssetCatalog;
+    };
+    entityModels?: Record<string, string | ModelConfig>;
+    objectModels?: Record<string, string | ModelConfig>;
+}): GameContextModels | undefined;
+/**
+ * Builds a `(key) => ModelConfig | null` override from a `seam`'s id/config map plus its catalog —
+ * `undefined` when either half is missing so the caller can fall back to its own default renderer.
+ * An unmapped key resolves to `null` (deliberate fallback); a mapped key with a missing/misspelled
+ * catalog id throws via {@link resolveModel}, same as the `entityModels`/`objectModels` seams.
+  * @internal
+  */
+export declare function createModelMapResolver(map: Record<string, string | ModelConfig> | undefined, assets: AssetCatalog | undefined, seam: ModelResolveContext["seam"]): ((key: string) => ModelConfig | null) | undefined;

package/dist/render/resolveModel.js

@@ -2,7 +2,8 @@
  * Resolve a string asset id or a direct ModelConfig. Missing/misspelled catalog
  * ids throw — silent generic-primitive fallback only happens when the mapping
  * omits the key entirely (or uses tryResolveCatalogModel for optional ids).
- */
+  * @internal
+  */
 export function resolveModel(value, assets, context) {
     if (value === undefined)
         return undefined;
@@ -13,12 +14,123 @@ export function resolveModel(value, assets, context) {
         const where = context === undefined ? `model asset "${value}"` : `${context.seam}["${context.key}"] → "${value}"`;
         throw new Error(`[jgengine] missing ${where} — not in the asset catalog. Fix the id, register it, or omit the mapping to keep the deliberate primitive/sprite fallback.`);
     }
-    return ref.dims === undefined ? { url: ref.url } : { url: ref.url, dims: ref.dims };
+    return {
+        url: ref.url,
+        ...(ref.dims === undefined ? {} : { dims: ref.dims }),
+        ...(ref.collisionMesh === undefined ? {} : { collisionMesh: ref.collisionMesh }),
+    };
 }
-/** Soft lookup used when an object catalog id may double as a model asset id. */
+/** Soft lookup used when an object catalog id may double as a model asset id.
+ * @internal
+ */
 export function tryResolveCatalogModel(id, assets) {
     const ref = assets.resolve(id);
     if (ref === null)
         return undefined;
-    return ref.dims === undefined ? { url: ref.url } : { url: ref.url, dims: ref.dims };
+    return {
+        url: ref.url,
+        ...(ref.dims === undefined ? {} : { dims: ref.dims }),
+        ...(ref.collisionMesh === undefined ? {} : { collisionMesh: ref.collisionMesh }),
+    };
+}
+/**
+ * Resolve an entity model plus bone-attachment / kit-of-parts models through the catalog
+ * so mounts receive fully-resolved `ModelConfig`s.
+ * @internal
+ */
+export function resolveEntityModel(value, assets, key) {
+    const model = resolveModel(value, assets, { seam: "entityModels", key });
+    if (model === undefined)
+        return model;
+    if (model.attachments === undefined && model.parts === undefined)
+        return model;
+    return {
+        ...model,
+        ...(model.attachments === undefined
+            ? {}
+            : {
+                attachments: model.attachments.map((attachment) => ({
+                    ...attachment,
+                    model: resolveModel(attachment.model, assets) ?? attachment.model,
+                })),
+            }),
+        ...(model.parts === undefined
+            ? {}
+            : {
+                parts: model.parts.map((part) => ({
+                    ...part,
+                    model: resolveModel(part.model, assets) ?? part.model,
+                })),
+            }),
+    };
+}
+/** Soft-resolve `model`, then `fallbackModel`; merge `style` when either hits.
+ * @internal
+ */
+export function pickModel(assets, pick) {
+    for (const id of [pick.model, pick.fallbackModel]) {
+        if (id === undefined)
+            continue;
+        const resolved = tryResolveCatalogModel(id, assets);
+        if (resolved === undefined)
+            continue;
+        return pick.style === undefined ? resolved : { ...resolved, ...pick.style };
+    }
+    return undefined;
+}
+/** Build an entityModels/objectModels map from a plan; missing catalog ids drop out (primitive).
+ * @internal
+ */
+export function resolveModelPlan(assets, plan) {
+    const out = {};
+    for (const [key, pick] of Object.entries(plan)) {
+        const model = pickModel(assets, pick);
+        if (model !== undefined)
+            out[key] = model;
+    }
+    return out;
+}
+function softModelLookup(map, assets) {
+    if (map === undefined)
+        return undefined;
+    return (key) => {
+        const value = map[key];
+        if (value === undefined || typeof value !== "string")
+            return value;
+        return tryResolveCatalogModel(value, 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.
+ * @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)
+        return undefined;
+    return {
+        ...(entity === undefined ? {} : { entity }),
+        ...(object === undefined ? {} : { object }),
+    };
+}
+/**
+ * Builds a `(key) => ModelConfig | null` override from a `seam`'s id/config map plus its catalog —
+ * `undefined` when either half is missing so the caller can fall back to its own default renderer.
+ * An unmapped key resolves to `null` (deliberate fallback); a mapped key with a missing/misspelled
+ * catalog id throws via {@link resolveModel}, same as the `entityModels`/`objectModels` seams.
+  * @internal
+  */
+export function createModelMapResolver(map, assets, seam) {
+    if (map === undefined || assets === undefined)
+        return undefined;
+    return (key) => {
+        const mapped = map[key];
+        if (mapped === undefined)
+            return null;
+        return resolveModel(mapped, assets, { seam, key }) ?? null;
+    };
 }

package/dist/render/useEntityRenderCues.d.ts

@@ -0,0 +1,13 @@
+import { type MutableRefObject } from "react";
+import { type EntityRenderCues, type RenderCueTuning } from "@jgengine/core/combat/renderCues";
+/**
+ * Live motion + animation cues for one entity, read from a mutable ref inside
+ * your own `useFrame` — no re-render per frame, no diffing the parent group's
+ * position, no game-side module map for attack/hit timing. Backs both custom
+ * `renderEntity` rigs and a custom first-person viewmodel (#542): call it with
+ * `entity.id` / the local player's userId and drive bob/recoil/reload poses
+ * from `cuesRef.current` inside the calling component's own `useFrame`.
+ *
+ * @capability entity-render-cues live velocity/bob/fire/reload/hit/death cues for a custom renderEntity or viewmodel component
+ */
+export declare function useEntityRenderCues(instanceId: string | undefined, tuning?: RenderCueTuning): MutableRefObject<EntityRenderCues>;

package/dist/render/useEntityRenderCues.js

@@ -0,0 +1,62 @@
+import { useFrame } from "@react-three/fiber";
+import { useEffect, useRef } from "react";
+import { advanceMotionCues, applyRenderAnimationEvent, applyRenderDeathEvent, applyRenderHitEvent, DEFAULT_FIRE_PULSE_SECONDS, DEFAULT_HIT_PULSE_SECONDS, DEFAULT_RENDER_CUES, } from "@jgengine/core/combat/renderCues";
+import { groundSpeed } from "@jgengine/core/scene/entityStore";
+import { useGameContext } from "@jgengine/react/provider";
+/**
+ * Live motion + animation cues for one entity, read from a mutable ref inside
+ * your own `useFrame` — no re-render per frame, no diffing the parent group's
+ * position, no game-side module map for attack/hit timing. Backs both custom
+ * `renderEntity` rigs and a custom first-person viewmodel (#542): call it with
+ * `entity.id` / the local player's userId and drive bob/recoil/reload poses
+ * from `cuesRef.current` inside the calling component's own `useFrame`.
+ *
+ * @capability entity-render-cues live velocity/bob/fire/reload/hit/death cues for a custom renderEntity or viewmodel component
+ */
+export function useEntityRenderCues(instanceId, tuning) {
+    const ctx = useGameContext();
+    const cuesRef = useRef({ ...DEFAULT_RENDER_CUES });
+    const timersRef = useRef({ fire: 0, hit: 0 });
+    useEffect(() => {
+        cuesRef.current = { ...DEFAULT_RENDER_CUES };
+        timersRef.current = { fire: 0, hit: 0 };
+        if (instanceId === undefined)
+            return;
+        const offAnimation = ctx.game.events.on("entity.animation", (event) => {
+            if (event.instanceId !== instanceId)
+                return;
+            cuesRef.current = applyRenderAnimationEvent(cuesRef.current, event.event);
+            if (event.event === "fire")
+                timersRef.current.fire = tuning?.firePulseSeconds ?? DEFAULT_FIRE_PULSE_SECONDS;
+        });
+        const offHit = ctx.game.events.on("combat.hitReaction", (event) => {
+            if (event.instanceId !== instanceId)
+                return;
+            cuesRef.current = applyRenderHitEvent(cuesRef.current);
+            timersRef.current.hit = tuning?.hitPulseSeconds ?? DEFAULT_HIT_PULSE_SECONDS;
+        });
+        const offDied = ctx.game.events.on("entity.died", (event) => {
+            if (event.instanceId !== instanceId)
+                return;
+            cuesRef.current = applyRenderDeathEvent(cuesRef.current);
+        });
+        return () => {
+            offAnimation();
+            offHit();
+            offDied();
+        };
+    }, [ctx, instanceId, tuning?.firePulseSeconds, tuning?.hitPulseSeconds]);
+    useFrame((_state, delta) => {
+        if (instanceId === undefined || delta <= 0)
+            return;
+        const entity = ctx.scene.entity.get(instanceId);
+        if (entity === null)
+            return;
+        const timers = timersRef.current;
+        timers.fire = Math.max(0, timers.fire - delta);
+        timers.hit = Math.max(0, timers.hit - delta);
+        const advanced = advanceMotionCues(cuesRef.current, groundSpeed(entity), delta, tuning);
+        cuesRef.current = { ...advanced, firing: timers.fire > 0, hit: timers.hit > 0 };
+    });
+    return cuesRef;
+}

package/dist/scatter/InstancedScatter.d.ts

@@ -0,0 +1,24 @@
+import type { ModelConfig } from "@jgengine/core/game/playableGame";
+import { type ScatterInstance } from "@jgengine/core/world/scatterRegion";
+/** Props for {@link InstancedScatter}: the resolved instances plus chunking/instance-cap knobs. */
+export interface InstancedScatterProps {
+    instances: readonly ScatterInstance[];
+    /** Chunk edge in meters; dense fields split into independently frustum-culled buckets. Default 24. */
+    chunkSize?: number;
+    /** Hard cap on rendered instances. Default 20000. */
+    maxInstances?: number;
+    /**
+     * Per-species override: return a real catalog `ModelConfig` for an item to GPU-instance the actual
+     * GLB instead of the stylized proxy; return `null` (or omit the prop) to keep `buildScatterProxy`.
+     */
+    resolveItem?: (item: string) => ModelConfig | null;
+}
+/**
+ * Renders resolved {@link ScatterInstance}s grouped into per-chunk, per-species GPU-instanced draws
+ * that frustum-cull independently. Species with no `resolveItem` mapping (or a `null` result) render
+ * as stylized proxy models (trunked trees, stacked pines, round bushes, faceted rocks, grass tufts);
+ * species `resolveItem` resolves to a `ModelConfig` GPU-instance the real catalog GLB instead. The one
+ * runtime foliage renderer shared by the editor's scatter preview and games that consume
+ * `resolveScatter` — never one node per placement.
+ */
+export declare function InstancedScatter({ instances, chunkSize, maxInstances, resolveItem, }: InstancedScatterProps): import("react").JSX.Element | null;

package/dist/scatter/InstancedScatter.js

@@ -0,0 +1,135 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Suspense, useEffect, useMemo, useRef } from "react";
+import { useLoader } from "@react-three/fiber";
+import * as THREE from "three";
+import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
+import { MeshoptDecoder } from "three/examples/jsm/libs/meshopt_decoder.module.js";
+import { chunkScatterInstances } from "@jgengine/core/world/scatterRegion";
+import { beginFallbackSeam, reportFallbackSeam } from "@jgengine/core/devtools/fallbackSeams";
+import { buildScatterProxy } from "./scatterProxies.js";
+import { buildScatterModelSources, disposeScatterModelSources } from "./scatterModels.js";
+/** Chunk edge (m): dense fields split into this-sized buckets, each frustum-culled independently. */
+const DEFAULT_CHUNK_SIZE = 24;
+const DEFAULT_MAX_INSTANCES = 20000;
+/** Groups resolved instances by spatial chunk then species so each batch is one cullable draw. */
+function batchInstances(instances, chunkSize) {
+    const batches = [];
+    const matrix = new THREE.Matrix4();
+    const position = new THREE.Vector3();
+    const quaternion = new THREE.Quaternion();
+    const euler = new THREE.Euler();
+    const scale = new THREE.Vector3();
+    for (const chunk of chunkScatterInstances(instances, chunkSize)) {
+        const byItem = new Map();
+        for (const instance of chunk.instances) {
+            position.set(instance.x, instance.y, instance.z);
+            euler.set(0, instance.rotationY, 0);
+            quaternion.setFromEuler(euler);
+            scale.set(instance.scale, instance.scale, instance.scale);
+            matrix.compose(position, quaternion, scale);
+            const bucket = byItem.get(instance.item);
+            if (bucket === undefined)
+                byItem.set(instance.item, [matrix.clone()]);
+            else
+                bucket.push(matrix.clone());
+        }
+        for (const [item, matrices] of byItem)
+            batches.push({ key: `${chunk.key}:${item}`, item, matrices });
+    }
+    return batches;
+}
+/** One species-in-a-chunk InstancedMesh; frustum-culled as a unit so offscreen chunks cost nothing. */
+function ScatterBatchMesh({ batch, geometry }) {
+    const meshRef = useRef(null);
+    useEffect(() => {
+        const mesh = meshRef.current;
+        if (mesh === null)
+            return;
+        for (let i = 0; i < batch.matrices.length; i += 1)
+            mesh.setMatrixAt(i, batch.matrices[i]);
+        mesh.count = batch.matrices.length;
+        mesh.instanceMatrix.needsUpdate = true;
+        mesh.computeBoundingSphere();
+    }, [batch]);
+    return (_jsx("instancedMesh", { ref: meshRef, args: [geometry, undefined, batch.matrices.length], castShadow: true, receiveShadow: true, children: _jsx("meshStandardMaterial", { vertexColors: true, roughness: 0.85, metalness: 0 }) }));
+}
+/** One GLB-backed draw source instanced across every chunk of one species. */
+function ScatterModelSourceInstances({ source, matrices }) {
+    const meshRef = useRef(null);
+    useEffect(() => {
+        const mesh = meshRef.current;
+        if (mesh === null)
+            return;
+        const composed = new THREE.Matrix4();
+        for (let i = 0; i < matrices.length; i += 1) {
+            composed.multiplyMatrices(matrices[i], source.localMatrix);
+            mesh.setMatrixAt(i, composed);
+        }
+        mesh.count = matrices.length;
+        mesh.instanceMatrix.needsUpdate = true;
+        mesh.computeBoundingSphere();
+    }, [matrices, source]);
+    return _jsx("instancedMesh", { ref: meshRef, args: [source.geometry, source.material, matrices.length], castShadow: true, receiveShadow: true });
+}
+/** Loads one species' real catalog GLB once, harvests its instanceable draw sources, then GPU-instances them across every chunk that species appears in. */
+function ScatterModelSpecies({ model, batches }) {
+    const gltf = useLoader(GLTFLoader, model.url, (loader) => {
+        loader.setMeshoptDecoder(MeshoptDecoder);
+    });
+    const { sources, root } = useMemo(() => buildScatterModelSources(gltf.scene, model), [gltf, model]);
+    useEffect(() => () => disposeScatterModelSources(root), [root]);
+    return (_jsx(_Fragment, { children: sources.map((source, sourceIndex) => batches.map((batch) => (_jsx(ScatterModelSourceInstances, { source: source, matrices: batch.matrices }, `${batch.key}:${sourceIndex}`)))) }));
+}
+/**
+ * Renders resolved {@link ScatterInstance}s grouped into per-chunk, per-species GPU-instanced draws
+ * that frustum-cull independently. Species with no `resolveItem` mapping (or a `null` result) render
+ * as stylized proxy models (trunked trees, stacked pines, round bushes, faceted rocks, grass tufts);
+ * species `resolveItem` resolves to a `ModelConfig` GPU-instance the real catalog GLB instead. The one
+ * runtime foliage renderer shared by the editor's scatter preview and games that consume
+ * `resolveScatter` — never one node per placement.
+ */
+export function InstancedScatter({ instances, chunkSize = DEFAULT_CHUNK_SIZE, maxInstances = DEFAULT_MAX_INSTANCES, resolveItem, }) {
+    const batches = useMemo(() => batchInstances(instances.length > maxInstances ? instances.slice(0, maxInstances) : instances, chunkSize), [instances, chunkSize, maxInstances]);
+    const { proxyBatches, modelSpecies } = useMemo(() => {
+        // Dev diagnostic (no-op unless armed): re-zero the scatter seam before re-tallying which species
+        // fall to a stylized proxy (no resolveItem mapping / a null result). Reported once per species.
+        beginFallbackSeam("scatter");
+        const proxy = [];
+        const bySpecies = new Map();
+        const knownProxy = new Set();
+        for (const batch of batches) {
+            const species = bySpecies.get(batch.item);
+            if (species !== undefined) {
+                species.batches.push(batch);
+                continue;
+            }
+            if (knownProxy.has(batch.item)) {
+                proxy.push(batch);
+                continue;
+            }
+            const resolved = resolveItem?.(batch.item) ?? null;
+            if (resolved === null) {
+                knownProxy.add(batch.item);
+                reportFallbackSeam("scatter", "omittedMapping");
+                proxy.push(batch);
+                continue;
+            }
+            bySpecies.set(batch.item, { model: resolved, batches: [batch] });
+        }
+        return { proxyBatches: proxy, modelSpecies: [...bySpecies.entries()] };
+    }, [batches, resolveItem]);
+    const geometries = useMemo(() => {
+        const items = new Set(proxyBatches.map((batch) => batch.item));
+        const map = new Map();
+        for (const item of items)
+            map.set(item, buildScatterProxy(item));
+        return map;
+    }, [proxyBatches]);
+    useEffect(() => () => geometries.forEach((geometry) => geometry.dispose()), [geometries]);
+    if (batches.length === 0)
+        return null;
+    return (_jsxs(_Fragment, { children: [proxyBatches.map((batch) => {
+                const geometry = geometries.get(batch.item);
+                return geometry === undefined ? null : _jsx(ScatterBatchMesh, { batch: batch, geometry: geometry }, batch.key);
+            }), modelSpecies.map(([item, species]) => (_jsx(Suspense, { fallback: null, children: _jsx(ScatterModelSpecies, { model: species.model, batches: species.batches }) }, item)))] }));
+}

package/dist/scatter/scatterModels.d.ts

@@ -0,0 +1,25 @@
+import * as THREE from "three";
+import type { ModelConfig } from "@jgengine/core/game/playableGame";
+/** One instanceable draw source harvested from a resolved GLB — geometry stays shared with the loader cache, `localMatrix` bakes the model's own transform (from its scene root) plus scale/anchor normalization. */
+export interface ScatterModelSource {
+    geometry: THREE.BufferGeometry;
+    material: THREE.Material | THREE.Material[];
+    localMatrix: THREE.Matrix4;
+}
+/**
+ * Clones a loaded GLTF scene (so shared cache materials stay untouched), applies the model's material
+ * override, then harvests every mesh as a {@link ScatterModelSource} — one `InstancedMesh` draw per
+ * source, matrices composed per-instance at render time. Geometry is left unowned (still the loader
+ * cache's), only the cloned materials need disposal via {@link disposeScatterModelSources}.
+ * @internal — the GLB-harvesting behind `InstancedScatter`'s `resolveItem` override.
+ */
+export declare function buildScatterModelSources(gltfScene: THREE.Object3D, model: ModelConfig): {
+    sources: ScatterModelSource[];
+    root: THREE.Object3D;
+};
+/**
+ * Disposes the cloned materials harvested by {@link buildScatterModelSources}; never disposes geometry
+ * (still owned by the loader cache).
+ * @internal
+ */
+export declare function disposeScatterModelSources(root: THREE.Object3D): void;

package/dist/scatter/scatterModels.js

@@ -0,0 +1,61 @@
+import * as THREE from "three";
+import { applyMaterialOverride } from "../materialOverride.js";
+import { cloneModelScene, disposeClonedMaterials } from "../render/modelRender.js";
+/** The scale + position offset a `ModelConfig` applies before any per-instance transform — same anchor/targetHeight rules as the single-instance entity renderer. */
+function scatterModelBaseTransform(scene, model) {
+    let scale = model.scale ?? 1;
+    let minY = 0;
+    let centerX = 0;
+    let centerZ = 0;
+    if (model.targetHeight !== undefined) {
+        const box = new THREE.Box3().setFromObject(scene);
+        const height = box.max.y - box.min.y;
+        if (Number.isFinite(height) && height > 0) {
+            scale *= model.targetHeight / height;
+            minY = box.min.y;
+            centerX = (box.min.x + box.max.x) / 2;
+            centerZ = (box.min.z + box.max.z) / 2;
+        }
+    }
+    else if ((model.anchor ?? "center") === "center" && model.dims !== undefined) {
+        minY = model.dims.minY;
+        centerX = model.dims.center.x;
+        centerZ = model.dims.center.z;
+    }
+    const baseY = model.y ?? 0;
+    return new THREE.Matrix4().compose(new THREE.Vector3(-scale * centerX, baseY - scale * minY, -scale * centerZ), new THREE.Quaternion(), new THREE.Vector3(scale, scale, scale));
+}
+/**
+ * Clones a loaded GLTF scene (so shared cache materials stay untouched), applies the model's material
+ * override, then harvests every mesh as a {@link ScatterModelSource} — one `InstancedMesh` draw per
+ * source, matrices composed per-instance at render time. Geometry is left unowned (still the loader
+ * cache's), only the cloned materials need disposal via {@link disposeScatterModelSources}.
+ * @internal — the GLB-harvesting behind `InstancedScatter`'s `resolveItem` override.
+ */
+export function buildScatterModelSources(gltfScene, model) {
+    const root = cloneModelScene(gltfScene);
+    if (model.material !== undefined)
+        applyMaterialOverride(root, model.material, { clone: false });
+    root.updateMatrixWorld(true);
+    const base = scatterModelBaseTransform(root, model);
+    const sources = [];
+    root.traverse((node) => {
+        const mesh = node;
+        if (!mesh.isMesh)
+            return;
+        sources.push({
+            geometry: mesh.geometry,
+            material: mesh.material,
+            localMatrix: base.clone().multiply(mesh.matrixWorld),
+        });
+    });
+    return { sources, root };
+}
+/**
+ * Disposes the cloned materials harvested by {@link buildScatterModelSources}; never disposes geometry
+ * (still owned by the loader cache).
+ * @internal
+ */
+export function disposeScatterModelSources(root) {
+    disposeClonedMaterials(root);
+}

package/dist/scatter/scatterProxies.d.ts

@@ -0,0 +1,6 @@
+import * as THREE from "three";
+/**
+ * Builds the merged proxy geometry for a scatter item id, memoized per builder call by the caller.
+ * @internal — the geometry catalog behind the `InstancedScatter` renderer.
+ */
+export declare function buildScatterProxy(item: string): THREE.BufferGeometry;