@jgengine/shell 0.10.0 → 0.12.0

package/dist/scatter/scatterProxies.js

@@ -0,0 +1,118 @@
+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";
+const PALM_BARK = "#8a7355";
+const PALM_FROND = "#4c8b3d";
+const CYPRESS = "#31502f";
+/** 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 },
+    ]),
+    palm: () => {
+        // Tall bare trunk with a radial crown of drooping fronds — each frond a flattened cone laid
+        // near-horizontal, tips sagging below the crown.
+        const parts = [{ geometry: trunk(2.6, 0.09), color: PALM_BARK }];
+        for (let i = 0; i < 6; i += 1) {
+            const yaw = (i / 6) * Math.PI * 2;
+            const frond = new THREE.ConeGeometry(0.16, 1.35, 4);
+            frond.scale(1, 1, 0.35);
+            frond.rotateX(-Math.PI / 2 - 0.5);
+            frond.rotateY(yaw);
+            frond.translate(Math.sin(yaw) * 0.32, 2.62, Math.cos(yaw) * 0.32);
+            parts.push({ geometry: frond, color: PALM_FROND });
+        }
+        parts.push({ geometry: sphere(0.14, 2.56), color: PALM_BARK });
+        return mergeParts(parts);
+    },
+    cypress: () => mergeParts([
+        { geometry: trunk(0.5, 0.07), color: BARK },
+        { geometry: cone(0.34, 2.5, 0.35, 6), color: CYPRESS },
+        { geometry: cone(0.2, 0.7, 2.75, 5), color: CYPRESS },
+    ]),
+};
+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,84 @@
+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;
+    };
+    /** Terrain surface color sampler forwarded to studio renderers (see `SceneKindRenderContext.groundColorAt`). */
+    groundColorAt?: (x: number, z: number) => string;
+}
+/**
+ * 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, groundColorAt, }: AuthoredSceneProps): import("react").JSX.Element;

package/dist/scene/AuthoredScene.js

@@ -0,0 +1,178 @@
+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, groundColorAt, }) {
+    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 }),
+                    ...(groundColorAt === undefined ? {} : { groundColorAt }),
+                } }), _jsx(AuthoredGenerators, { document: liveDocument, field: field }), shouldPlaceObjects ? (_jsx(AuthoredObjects, { document: liveDocument, field: field, verticalOffset: objectVerticalOffset })) : null] }));
+}

package/dist/scene/CityRenderer.d.ts

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