@jgengine/shell 0.10.0 → 0.11.0

package/dist/render/defaultSurface.js

@@ -0,0 +1,101 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import {} from "@react-three/fiber";
+import { useMemo } from "react";
+import * as THREE from "three";
+const DETAIL_SIZE = 64;
+const DETAIL_REPEAT = 3;
+const NORMAL_STRENGTH = 2.2;
+const ROUGHNESS_SPREAD = 0.14;
+function periodicValueNoise(size, cells, seed) {
+    const lattice = new Float32Array(cells * cells);
+    for (let index = 0; index < lattice.length; index += 1) {
+        const h = Math.sin((index + 1) * 12.9898 + seed * 78.233) * 43758.5453;
+        lattice[index] = h - Math.floor(h);
+    }
+    const at = (cx, cy) => lattice[((cy % cells) + cells) % cells * cells + (((cx % cells) + cells) % cells)];
+    const field = new Float32Array(size * size);
+    const step = cells / size;
+    for (let y = 0; y < size; y += 1) {
+        for (let x = 0; x < size; x += 1) {
+            const fx = x * step;
+            const fy = y * step;
+            const x0 = Math.floor(fx);
+            const y0 = Math.floor(fy);
+            const tx = fx - x0;
+            const ty = fy - y0;
+            const sx = tx * tx * (3 - 2 * tx);
+            const sy = ty * ty * (3 - 2 * ty);
+            const top = at(x0, y0) * (1 - sx) + at(x0 + 1, y0) * sx;
+            const bottom = at(x0, y0 + 1) * (1 - sx) + at(x0 + 1, y0 + 1) * sx;
+            field[y * size + x] = top * (1 - sy) + bottom * sy;
+        }
+    }
+    return field;
+}
+function heightField(size) {
+    const coarse = periodicValueNoise(size, 4, 1);
+    const medium = periodicValueNoise(size, 8, 7);
+    const fine = periodicValueNoise(size, 16, 13);
+    const field = new Float32Array(size * size);
+    for (let index = 0; index < field.length; index += 1) {
+        field[index] = coarse[index] * 0.55 + medium[index] * 0.3 + fine[index] * 0.15;
+    }
+    return field;
+}
+let cached = null;
+/**
+ * Shared, lazily-built procedural detail maps (a subtle tangent-space normal map plus a
+ * roughness-variation map) used by every un-modeled primitive so a flat colored box reads as a
+ * surface, not plastic. Pure JS `DataTexture` — no canvas/DOM, so it imports safely under `bun test`.
+ * @internal shell-internal default render surface; games never import it.
+ */
+export function detailMaps() {
+    if (cached !== null)
+        return cached;
+    const size = DETAIL_SIZE;
+    const height = heightField(size);
+    const sample = (x, y) => height[(((y % size) + size) % size) * size + (((x % size) + size) % size)];
+    const normalData = new Uint8Array(size * size * 4);
+    const roughnessData = new Uint8Array(size * size * 4);
+    for (let y = 0; y < size; y += 1) {
+        for (let x = 0; x < size; x += 1) {
+            const dx = (sample(x - 1, y) - sample(x + 1, y)) * NORMAL_STRENGTH;
+            const dy = (sample(x, y - 1) - sample(x, y + 1)) * NORMAL_STRENGTH;
+            const length = Math.hypot(dx, dy, 1);
+            const offset = (y * size + x) * 4;
+            normalData[offset] = Math.round((dx / length * 0.5 + 0.5) * 255);
+            normalData[offset + 1] = Math.round((dy / length * 0.5 + 0.5) * 255);
+            normalData[offset + 2] = Math.round((1 / length * 0.5 + 0.5) * 255);
+            normalData[offset + 3] = 255;
+            const rough = Math.round((0.5 + (sample(x, y) - 0.5) * 2 * ROUGHNESS_SPREAD * 0.5) * 255);
+            roughnessData[offset] = rough;
+            roughnessData[offset + 1] = rough;
+            roughnessData[offset + 2] = rough;
+            roughnessData[offset + 3] = 255;
+        }
+    }
+    const build = (data) => {
+        const texture = new THREE.DataTexture(data, size, size, THREE.RGBAFormat);
+        texture.wrapS = THREE.RepeatWrapping;
+        texture.wrapT = THREE.RepeatWrapping;
+        texture.repeat.set(DETAIL_REPEAT, DETAIL_REPEAT);
+        texture.minFilter = THREE.LinearMipmapLinearFilter;
+        texture.magFilter = THREE.LinearFilter;
+        texture.generateMipmaps = true;
+        texture.anisotropy = 4;
+        texture.needsUpdate = true;
+        return texture;
+    };
+    cached = { normal: build(normalData), roughness: build(roughnessData) };
+    return cached;
+}
+/**
+ * The upgraded default material for un-modeled entities/objects: tuned PBR roughness/metalness plus
+ * the shared procedural detail maps, so primitive fallbacks catch light and image-based reflections
+ * instead of reading as flat plastic. Drop-in replacement for a bare `<meshStandardMaterial color>`.
+ * @internal shell-internal default render surface; games never import it.
+ */
+export function DefaultSurface({ color, roughness = 0.72, metalness = 0.04, detail = true, ...rest }) {
+    const maps = useMemo(() => (detail ? detailMaps() : null), [detail]);
+    return (_jsx("meshStandardMaterial", { color: color, roughness: roughness, metalness: metalness, envMapIntensity: 0.6, normalMap: maps?.normal ?? null, normalScale: maps === null ? undefined : new THREE.Vector2(0.6, 0.6), roughnessMap: maps?.roughness ?? null, ...rest }));
+}

package/dist/render/modelLoad.d.ts

@@ -0,0 +1,24 @@
+import { GLTFLoader, type GLTF } from "three/examples/jsm/loaders/GLTFLoader.js";
+import { type AssetLoadDiagnosis } from "@jgengine/core/scene/assetDiagnostics";
+/**
+ * Re-fetch a model URL that just failed to load and classify what actually came
+ * back — a 404, a dev-server HTML fallback, a corrupt or non-model body — so the
+ * runtime can replace an opaque GLTF parse error with a diagnosis naming the
+ * broken asset contract. Runs only on the error path (loads rarely fail), and
+ * never throws: a failed probe returns a `missing` diagnosis instead.
+ * @internal
+ */
+export declare function probeModelUrl(url: string, logicalId?: string, fetchImpl?: typeof fetch): Promise<AssetLoadDiagnosis>;
+/**
+ * A {@link GLTFLoader} whose success path is unchanged but whose failures are
+ * enriched: when a load errors, it probes the URL and rejects with an
+ * {@link AssetLoadDiagnosis}-derived message (missing / HTML fallback / corrupt /
+ * unsupported) instead of the raw parse error. Drop-in for the shared loader, so
+ * `useLoader(sharedGltfLoader, url)` benefits with no call-site change.
+ * @internal
+ */
+export declare class DiagnosticGLTFLoader extends GLTFLoader {
+    load(url: string, onLoad: (gltf: GLTF) => void, onProgress?: (event: ProgressEvent) => void, onError?: (event: unknown) => void): void;
+}
+/** Shared GLTF loader used by shell entity/object model mounts. @internal */
+export declare const sharedGltfLoader: DiagnosticGLTFLoader;

package/dist/render/modelLoad.js

@@ -0,0 +1,73 @@
+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 { classifyAssetResponse, } from "@jgengine/core/scene/assetDiagnostics";
+/**
+ * Dedicated LoadingManager for every GLB load instead of THREE.DefaultLoadingManager.
+ * The shared default manager is process-wide; under repeated dev-server navigations its
+ * AbortController can already be aborted, which silently stalls GLTFLoader.fetch forever
+ * with no thrown error. A private manager sidesteps that (ported from the duet-keys ship).
+ * @internal
+ */
+const modelLoadingManager = new THREE.LoadingManager();
+/** How many leading bytes to read when probing a failed model URL for its signature. @internal */
+const PROBE_BYTE_LIMIT = 64;
+/**
+ * Re-fetch a model URL that just failed to load and classify what actually came
+ * back — a 404, a dev-server HTML fallback, a corrupt or non-model body — so the
+ * runtime can replace an opaque GLTF parse error with a diagnosis naming the
+ * broken asset contract. Runs only on the error path (loads rarely fail), and
+ * never throws: a failed probe returns a `missing` diagnosis instead.
+ * @internal
+ */
+export async function probeModelUrl(url, logicalId, fetchImpl = fetch) {
+    const base = logicalId === undefined ? { url } : { url, logicalId };
+    try {
+        const response = await fetchImpl(url);
+        const buffer = await response.arrayBuffer();
+        const bytes = new Uint8Array(buffer.slice(0, PROBE_BYTE_LIMIT));
+        return classifyAssetResponse({
+            ...base,
+            status: response.status,
+            statusText: response.statusText,
+            contentType: response.headers.get("content-type") ?? undefined,
+            bytes,
+        });
+    }
+    catch {
+        // The probe fetch itself failed (network/CORS) — the file is effectively unreachable.
+        return classifyAssetResponse({ ...base, status: 0 });
+    }
+}
+/**
+ * A {@link GLTFLoader} whose success path is unchanged but whose failures are
+ * enriched: when a load errors, it probes the URL and rejects with an
+ * {@link AssetLoadDiagnosis}-derived message (missing / HTML fallback / corrupt /
+ * unsupported) instead of the raw parse error. Drop-in for the shared loader, so
+ * `useLoader(sharedGltfLoader, url)` benefits with no call-site change.
+ * @internal
+ */
+export class DiagnosticGLTFLoader extends GLTFLoader {
+    load(url, onLoad, onProgress, onError) {
+        super.load(url, onLoad, onProgress, (event) => {
+            if (onError === undefined)
+                return;
+            void probeModelUrl(url)
+                .then((diagnosis) => {
+                if (diagnosis.ok) {
+                    // The bytes look fine on re-fetch — surface the original parse error unchanged.
+                    onError(event);
+                    return;
+                }
+                const enriched = new Error(`[jgengine] ${diagnosis.message}`);
+                enriched.diagnosis = diagnosis;
+                enriched.cause = event;
+                onError(enriched);
+            })
+                .catch(() => onError(event));
+        });
+    }
+}
+/** Shared GLTF loader used by shell entity/object model mounts. @internal */
+export const sharedGltfLoader = new DiagnosticGLTFLoader(modelLoadingManager);
+sharedGltfLoader.setMeshoptDecoder(MeshoptDecoder);

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,50 @@
 import type { AssetCatalog } from "@jgengine/core/scene/assetCatalog";
 import type { ModelConfig } from "@jgengine/core/game/playableGame";
 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>;
+/**
+ * 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;
@@ -15,10 +16,86 @@ export function resolveModel(value, assets, context) {
     }
     return ref.dims === undefined ? { url: ref.url } : { url: ref.url, dims: ref.dims };
 }
-/** 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 };
 }
+/**
+ * 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;
+}
+/**
+ * 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;