@jgengine/shell 0.10.0 → 0.11.0

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;

package/dist/scene/AuthoredScene.js

@@ -0,0 +1,173 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment, useEffect, useMemo, useState } from "react";
+import * as THREE from "three";
+import { getDocumentLiveSync, subscribeDocumentLiveSyncInstall, } from "@jgengine/core/editor/index";
+import { placeAuthoredObjects, resolveAuthoredObjects, } from "@jgengine/core/world/authoredObjects";
+import { buildRoadRibbon, roundPathCorners } from "@jgengine/core/world/roads";
+import { isScatterPath, resolveScatter } from "@jgengine/core/world/scatterRegion";
+import { getAssetGenerator } from "@jgengine/core/scene/assetGenerator";
+import { useGameContext } from "@jgengine/react/provider";
+import { createModelMapResolver } from "../render/resolveModel.js";
+import { InstancedScatter } from "../scatter/InstancedScatter.js";
+import { GeneratedAssetInstance } from "./GeneratedAssetRenderer.js";
+import { registerBuiltinSceneKindRenderers } from "./builtinSceneKindRenderers.js";
+import { getSceneKindRenderer } from "./sceneKindRenderers.js";
+/**
+ * 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 function useLiveEditorDocument(document, live = true) {
+    const [resolved, setResolved] = useState(document);
+    useEffect(() => {
+        if (!live) {
+            setResolved(document);
+            return;
+        }
+        let unsubDoc;
+        const attach = () => {
+            unsubDoc?.();
+            unsubDoc = undefined;
+            const sync = getDocumentLiveSync();
+            if (sync === null) {
+                setResolved(document);
+                return;
+            }
+            setResolved(sync.getDocument());
+            unsubDoc = sync.subscribeDocument((event) => setResolved(event.document));
+        };
+        attach();
+        const unsubInstall = subscribeDocumentLiveSyncInstall(attach);
+        return () => {
+            unsubInstall();
+            unsubDoc?.();
+        };
+    }, [document, live]);
+    return live ? resolved : document;
+}
+registerBuiltinSceneKindRenderers();
+function markerToKindObject(marker) {
+    return { id: marker.id, kind: marker.kind, position: marker.position, ...(marker.rotationY === undefined ? {} : { rotationY: marker.rotationY }), ...(marker.meta === undefined ? {} : { meta: marker.meta }) };
+}
+function volumeToKindObject(volume) {
+    return {
+        id: volume.id,
+        kind: volume.kind,
+        center: volume.center,
+        ...(volume.halfExtents === undefined ? {} : { halfExtents: volume.halfExtents }),
+        ...(volume.radius === undefined ? {} : { radius: volume.radius }),
+        ...(volume.meta === undefined ? {} : { meta: volume.meta }),
+    };
+}
+function pathToKindObject(path) {
+    return { id: path.id, kind: path.kind, points: path.points.map((point) => ({ x: point.x, y: point.y, z: point.z })), ...(path.meta === undefined ? {} : { meta: path.meta }) };
+}
+/** Renders every marker placed as a parametric generator asset, re-resolved from its `meta` + seed. */
+function AuthoredGenerators({ document, field }) {
+    const markers = useMemo(() => document.markers.filter((marker) => typeof marker.meta?.["assetId"] === "string" && getAssetGenerator(marker.meta["assetId"]) !== undefined), [document.markers]);
+    return (_jsx(_Fragment, { children: markers.map((marker) => (_jsx(GeneratedAssetInstance, { meta: marker.meta, position: [marker.position.x, field.sampleHeight(marker.position.x, marker.position.z), marker.position.z], rotationY: marker.rotationY ?? 0 }, marker.id))) }));
+}
+/**
+ * Mounts every registered studio renderer for the kinds present in a document — water and any
+ * game/example-registered kind — grouping objects by kind and handing each renderer its slice.
+ * Scatter stays on the batched {@link InstancedScatter} path (its cross-region avoid masks need the
+ * whole document), so it is skipped here.
+ */
+function AuthoredStudios({ document, context }) {
+    const byKind = useMemo(() => {
+        const groups = new Map();
+        const add = (kind, object) => {
+            if (isScatterPath({ kind }) || getSceneKindRenderer(kind) === undefined)
+                return;
+            const bucket = groups.get(kind);
+            if (bucket === undefined)
+                groups.set(kind, [object]);
+            else
+                bucket.push(object);
+        };
+        for (const marker of document.markers)
+            add(marker.kind, markerToKindObject(marker));
+        for (const volume of document.volumes)
+            add(volume.kind, volumeToKindObject(volume));
+        for (const path of document.paths)
+            add(path.kind, pathToKindObject(path));
+        return groups;
+    }, [document]);
+    return (_jsx(_Fragment, { children: [...byKind.entries()].map(([kind, objects]) => {
+            const renderer = getSceneKindRenderer(kind);
+            return renderer === undefined ? null : _jsx(Fragment, { children: renderer({ objects, context }) }, kind);
+        }) }));
+}
+const DEFAULT_PATH_COLOR = "#7a6444";
+/** One editor path drawn as a ground-draped ribbon — subdivided and sampled against the live field. */
+function DrapedPath({ points, width, color, field, }) {
+    const geometry = useMemo(() => {
+        // Fillet sharp turns first so bends read as smooth arcs, not overlapping rectangles.
+        const rounded = roundPathCorners(points, Math.max(1.5, width * 0.9), 6);
+        const ribbon = buildRoadRibbon(rounded, width, (x, z) => field.sampleHeight(x, z), {
+            elevation: 0.18,
+            maxSegmentLength: 1,
+        });
+        const geo = new THREE.BufferGeometry();
+        geo.setAttribute("position", new THREE.BufferAttribute(ribbon.positions, 3));
+        geo.setIndex(new THREE.BufferAttribute(ribbon.indices, 1));
+        geo.computeVertexNormals();
+        return geo;
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [points, width, field]);
+    useEffect(() => () => geometry.dispose(), [geometry]);
+    if (points.length < 2)
+        return null;
+    return (_jsx("mesh", { geometry: geometry, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: color, roughness: 1, metalness: 0, side: THREE.DoubleSide }) }));
+}
+function pathColor(meta, color) {
+    if (typeof meta?.["color"] === "string")
+        return meta["color"];
+    return color ?? DEFAULT_PATH_COLOR;
+}
+/**
+ * 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 function AuthoredPaths({ document, field, kinds }) {
+    const paths = document.paths.filter((path) => !isScatterPath(path) && getSceneKindRenderer(path.kind) === undefined && (kinds === undefined || kinds.includes(path.kind)));
+    return (_jsx(_Fragment, { children: paths.map((path) => (_jsx(DrapedPath, { points: path.points.map((point) => [point.x, point.z]), width: path.width ?? 4, color: pathColor(path.meta, path.color), field: field }, path.id))) }));
+}
+/**
+ * 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 function AuthoredObjects({ document, field, verticalOffset = 0, onExisting = "keep", }) {
+    const ctx = useGameContext();
+    const objects = useMemo(() => resolveAuthoredObjects(document), [document]);
+    useEffect(() => {
+        if (objects.length === 0)
+            return;
+        placeAuthoredObjects(ctx.scene.object, objects, (x, z) => field.sampleHeight(x, z), {
+            verticalOffset,
+            onExisting,
+        });
+    }, [ctx.scene.object, field, objects, onExisting, verticalOffset]);
+    return null;
+}
+/**
+ * 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 function AuthoredScene({ document, field, pathKinds, scatterModels, assets, live = true, placeObjects, }) {
+    const liveDocument = useLiveEditorDocument(document, live);
+    const instances = useMemo(() => resolveScatter(liveDocument, field), [liveDocument, field]);
+    const resolveItem = useMemo(() => createModelMapResolver(scatterModels, assets, "scatterModels"), [scatterModels, assets]);
+    const shouldPlaceObjects = placeObjects === true || (typeof placeObjects === "object" && placeObjects !== null);
+    const objectVerticalOffset = typeof placeObjects === "object" && placeObjects !== null ? (placeObjects.verticalOffset ?? 0) : 0;
+    return (_jsxs(_Fragment, { children: [_jsx(AuthoredPaths, { document: liveDocument, field: field, ...(pathKinds === undefined ? {} : { kinds: pathKinds }) }), _jsx(InstancedScatter, { instances: instances, ...(resolveItem === undefined ? {} : { resolveItem }) }), _jsx(AuthoredStudios, { document: liveDocument, context: { document: liveDocument, field, ...(assets === undefined ? {} : { assets }) } }), _jsx(AuthoredGenerators, { document: liveDocument, field: field }), shouldPlaceObjects ? (_jsx(AuthoredObjects, { document: liveDocument, field: field, verticalOffset: objectVerticalOffset })) : null] }));
+}

package/dist/scene/GeneratedAssetRenderer.d.ts

@@ -0,0 +1,14 @@
+/** Props for {@link GeneratedAsset}: the placed instance's `meta` (assetId + params + seed) and transform. */
+export interface GeneratedAssetProps {
+    /** The placed instance meta — `{ assetId, seed, ...params }`. Re-resolved every render, never baked. */
+    meta: Record<string, unknown> | undefined;
+    position?: readonly [number, number, number];
+    rotationY?: number;
+}
+/**
+ * Renders one placed generator-asset instance by re-resolving its `meta` through the registered
+ * generator and instancing the parts. Returns null when the meta names no generator. The runtime
+ * counterpart to placing a parametric asset — the geometry is data, recomputed from params + seed.
+ * @internal — `AuthoredScene` mounts this for generator markers automatically.
+ */
+export declare function GeneratedAssetInstance({ meta, position, rotationY }: GeneratedAssetProps): import("react").JSX.Element | null;

package/dist/scene/GeneratedAssetRenderer.js

@@ -0,0 +1,59 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef } from "react";
+import * as THREE from "three";
+import { resolveGeneratorAsset } from "@jgengine/core/scene/assetGenerator";
+const UNIT_BOX = new THREE.BoxGeometry(1, 1, 1);
+const NEUTRAL = "#b8b0a4";
+/** All parts of one generated asset, batched into one instanced box draw per color. */
+function GeneratedParts({ asset }) {
+    const byColor = useMemo(() => {
+        const groups = new Map();
+        for (const part of asset.parts) {
+            const color = part.color ?? NEUTRAL;
+            const bucket = groups.get(color);
+            if (bucket === undefined)
+                groups.set(color, [part]);
+            else
+                bucket.push(part);
+        }
+        return [...groups.entries()];
+    }, [asset]);
+    return (_jsx(_Fragment, { children: byColor.map(([color, parts]) => (_jsx(ColorBatch, { color: color, parts: parts }, color))) }));
+}
+function ColorBatch({ color, parts }) {
+    const meshRef = useRef(null);
+    useEffect(() => {
+        const mesh = meshRef.current;
+        if (mesh === null)
+            return;
+        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();
+        parts.forEach((part, index) => {
+            position.set(part.position[0], part.position[1], part.position[2]);
+            euler.set(0, part.rotationY ?? 0, 0);
+            quaternion.setFromEuler(euler);
+            scale.set(Math.max(1e-3, part.size[0]), Math.max(1e-3, part.size[1]), Math.max(1e-3, part.size[2]));
+            matrix.compose(position, quaternion, scale);
+            mesh.setMatrixAt(index, matrix);
+        });
+        mesh.count = parts.length;
+        mesh.instanceMatrix.needsUpdate = true;
+        mesh.computeBoundingSphere();
+    }, [parts]);
+    return (_jsx("instancedMesh", { ref: meshRef, args: [UNIT_BOX, undefined, Math.max(1, parts.length)], castShadow: true, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: color, roughness: 0.62, metalness: 0.04 }) }));
+}
+/**
+ * Renders one placed generator-asset instance by re-resolving its `meta` through the registered
+ * generator and instancing the parts. Returns null when the meta names no generator. The runtime
+ * counterpart to placing a parametric asset — the geometry is data, recomputed from params + seed.
+ * @internal — `AuthoredScene` mounts this for generator markers automatically.
+ */
+export function GeneratedAssetInstance({ meta, position = [0, 0, 0], rotationY = 0 }) {
+    const asset = useMemo(() => resolveGeneratorAsset(meta), [meta]);
+    if (asset === null)
+        return null;
+    return (_jsx("group", { position: [position[0], position[1], position[2]], rotation: [0, rotationY, 0], children: _jsx(GeneratedParts, { asset: asset }) }));
+}

package/dist/scene/GrassFieldRenderer.d.ts

@@ -0,0 +1,2 @@
+/** Registers the `grass_field` volume renderer. Called by `registerBuiltinSceneKindRenderers`. @internal */
+export declare function registerGrassFieldRenderer(): void;