@jgengine/shell 0.9.0 → 0.11.0

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;

package/dist/scatter/InstancedScatter.js

@@ -0,0 +1,130 @@
+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 { 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(() => {
+        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);
+                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;

package/dist/scatter/scatterProxies.js

@@ -0,0 +1,94 @@
+import * as THREE from "three";
+const BARK = "#5b4127";
+const LEAF = "#3f6b30";
+const PINE = "#2f5330";
+const OAK = "#4a7a37";
+const BUSH = "#4d7d3a";
+const ROCK = "#82858c";
+const GRASS = "#5f9a3c";
+/** Concatenates part geometries into one vertex-colored buffer (position + normal + color). */
+function mergeParts(parts) {
+    const geos = parts.map((part) => (part.geometry.index === null ? part.geometry : part.geometry.toNonIndexed()));
+    let total = 0;
+    for (const geo of geos)
+        total += geo.attributes.position.count;
+    const position = new Float32Array(total * 3);
+    const normal = new Float32Array(total * 3);
+    const color = new Float32Array(total * 3);
+    const tint = new THREE.Color();
+    let offset = 0;
+    for (let i = 0; i < geos.length; i += 1) {
+        const geo = geos[i];
+        const pos = geo.attributes.position;
+        const nor = geo.attributes.normal;
+        position.set(pos.array, offset * 3);
+        normal.set(nor.array, offset * 3);
+        tint.set(parts[i].color);
+        for (let v = 0; v < pos.count; v += 1) {
+            color[(offset + v) * 3] = tint.r;
+            color[(offset + v) * 3 + 1] = tint.g;
+            color[(offset + v) * 3 + 2] = tint.b;
+        }
+        offset += pos.count;
+    }
+    for (const geo of geos)
+        geo.dispose();
+    const merged = new THREE.BufferGeometry();
+    merged.setAttribute("position", new THREE.BufferAttribute(position, 3));
+    merged.setAttribute("normal", new THREE.BufferAttribute(normal, 3));
+    merged.setAttribute("color", new THREE.BufferAttribute(color, 3));
+    merged.computeBoundingSphere();
+    return merged;
+}
+function trunk(height, radius) {
+    const geo = new THREE.CylinderGeometry(radius * 0.8, radius, height, 5);
+    geo.translate(0, height / 2, 0);
+    return geo;
+}
+function cone(radius, height, y, segments = 7) {
+    const geo = new THREE.ConeGeometry(radius, height, segments);
+    geo.translate(0, y + height / 2, 0);
+    return geo;
+}
+function sphere(radius, y, squash = 1) {
+    const geo = new THREE.IcosahedronGeometry(radius, 1);
+    geo.scale(1, squash, 1);
+    geo.translate(0, y, 0);
+    return geo;
+}
+const BUILDERS = {
+    tree: () => mergeParts([
+        { geometry: trunk(1.1, 0.12), color: BARK },
+        { geometry: cone(0.8, 1.7, 0.9), color: LEAF },
+    ]),
+    pine: () => mergeParts([
+        { geometry: trunk(0.9, 0.1), color: BARK },
+        { geometry: cone(0.7, 1.0, 0.7), color: PINE },
+        { geometry: cone(0.55, 0.9, 1.35), color: PINE },
+        { geometry: cone(0.38, 0.8, 1.95), color: PINE },
+    ]),
+    oak: () => mergeParts([
+        { geometry: trunk(1.0, 0.14), color: BARK },
+        { geometry: sphere(0.85, 1.55, 0.85), color: OAK },
+    ]),
+    bush: () => mergeParts([{ geometry: sphere(0.55, 0.45, 0.8), color: BUSH }]),
+    shrub: () => mergeParts([{ geometry: sphere(0.5, 0.4, 0.75), color: BUSH }]),
+    rock: () => mergeParts([{ geometry: sphere(0.5, 0.28, 0.7), color: ROCK }]),
+    stone: () => mergeParts([{ geometry: sphere(0.4, 0.22, 0.65), color: ROCK }]),
+    grass: () => mergeParts([
+        { geometry: cone(0.09, 0.7, 0), color: GRASS },
+        { geometry: cone(0.08, 0.55, 0).translate(0.12, 0, 0.05), color: GRASS },
+        { geometry: cone(0.08, 0.6, 0).translate(-0.1, 0, -0.06), color: GRASS },
+    ]),
+};
+function defaultProxy() {
+    return mergeParts([{ geometry: cone(0.35, 1.2, 0), color: GRASS }]);
+}
+/**
+ * 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 function buildScatterProxy(item) {
+    const builder = BUILDERS[item];
+    return builder === undefined ? defaultProxy() : builder();
+}

package/dist/scatter.d.ts

@@ -0,0 +1 @@
+export * from "./scatter/InstancedScatter.js";

package/dist/scatter.js

@@ -0,0 +1 @@
+export * from "./scatter/InstancedScatter.js";

package/dist/scene/AuthoredScene.d.ts

@@ -0,0 +1,82 @@
+import type { EditorDocument } from "@jgengine/core/editor/index";
+import type { ModelConfig } from "@jgengine/core/game/playableGame";
+import type { AssetCatalog } from "@jgengine/core/scene/assetCatalog";
+import type { TerrainField } from "@jgengine/core/world/terrain";
+/**
+ * Resolves the document AuthoredScene renders: when a {@link getDocumentLiveSync} bus is
+ * installed (editor host live), subscribe to document patches; otherwise use the prop.
+ * Document is authoritative — runtime overrides never land here unless written back.
+ * @internal
+ */
+export declare function useLiveEditorDocument(document: EditorDocument, live?: boolean): EditorDocument;
+/** Props for {@link AuthoredPaths}: the document, the ground field to drape over, and a kind filter. */
+export interface AuthoredPathsProps {
+    document: EditorDocument;
+    field: TerrainField;
+    /** Only render these path kinds; default renders every non-scatter path. */
+    kinds?: readonly string[];
+}
+/**
+ * Renders a document's non-scatter paths (roads, routes, corridors) as ground-draped ribbons — the
+ * editor authors the polyline, the engine drapes it over the live terrain at runtime. Width comes
+ * from `path.width`, color from `path.meta.color`/`path.color`. A game never hand-rolls path meshes.
+ */
+export declare function AuthoredPaths({ document, field, kinds }: AuthoredPathsProps): import("react").JSX.Element;
+/** Props for {@link AuthoredObjects}: document, ground field, and optional lift / onExisting. */
+export interface AuthoredObjectsProps {
+    document: EditorDocument;
+    field: TerrainField;
+    /** Extra lift in meters on top of each marker's own verticalOffset (default 0). */
+    verticalOffset?: number;
+    /**
+     * How to treat instance ids already in the object store. Default `"keep"` so an onInit
+     * `placeAuthoredObjects` call wins and remounts stay remount-safe.
+     */
+    onExisting?: "throw" | "replace" | "keep";
+}
+/**
+ * Places every editor marker with a catalog id into `ctx.scene.object`, grounded on `field`.
+ * WorldScene renders them through the game's `objectModels` seam — no bespoke place loop. Pure
+ * headless twin: `resolveAuthoredObjects` / `placeAuthoredObjects`.
+ */
+export declare function AuthoredObjects({ document, field, verticalOffset, onExisting, }: AuthoredObjectsProps): null;
+/** Props for {@link AuthoredScene}: the document to render and the ground field to drape/ground on. */
+export interface AuthoredSceneProps {
+    document: EditorDocument;
+    field: TerrainField;
+    /** Restrict rendered path kinds; default renders every non-scatter path. */
+    pathKinds?: readonly string[];
+    /**
+     * Scatter palette item id → model asset id or `ModelConfig`; a mapped item GPU-instances the real
+     * catalog GLB instead of the stylized proxy. Keyed by scatter `item` (not entity name — pass a
+     * dedicated map even if it shares entries with `entityModels`). Requires `assets`.
+     */
+    scatterModels?: Record<string, string | ModelConfig>;
+    /** Catalog `scatterModels` string ids resolve through; required together with `scatterModels`. */
+    assets?: AssetCatalog;
+    /**
+     * When true (default), subscribe to the global document live-sync bus if the editor host is
+     * mounted so headless/RPC document patches hot-apply without a full reload. Pass false to pin
+     * the `document` prop (tests, one-shot previews).
+     */
+    live?: boolean;
+    /**
+     * Place the document's catalog-id markers into the object
+     * store — WorldScene renders them via the game's `objectModels` seam. Omit when the game places
+     * props itself in onInit with `placeAuthoredObjects`.
+     */
+    placeObjects?: boolean | {
+        verticalOffset?: number;
+    };
+}
+/**
+ * Renders an editor document's scene content — draped paths plus GPU-instanced foliage — from one
+ * mount, grounded on the live `field`. The runtime counterpart to authoring a scene in the editor:
+ * drag paths and foliage regions, save `editor.scene.json`, and the game plays them with no bespoke
+ * render code. When a live-sync bus is installed (editor host), document patches stream in and
+ * re-render automatically — document is authoritative; runtime overrides stay ephemeral unless
+ * written back. Terrain/collision come from the world's ground field (`environment({ sculpt })`);
+ * place markers with your own entity spawns. Pass `scatterModels`+`assets` to resolve palette items to
+ * real catalog GLBs; unmapped items keep the stylized proxy.
+ */
+export declare function AuthoredScene({ document, field, pathKinds, scatterModels, assets, live, placeObjects, }: AuthoredSceneProps): import("react").JSX.Element;