@jgengine/shell 0.9.0 → 0.11.0

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;

package/dist/scene/GrassFieldRenderer.js

@@ -0,0 +1,25 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { resolveGrassObject } from "@jgengine/core/world/grassKind";
+import { GrassField } from "../terrain/GrassField.js";
+import { registerSceneKindRenderer } from "./sceneKindRenderers.js";
+function hashSeed(text) {
+    let h = 2166136261 >>> 0;
+    for (let i = 0; i < text.length; i += 1) {
+        h ^= text.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return (h >>> 0) % 100000;
+}
+/** One authored grass volume → an instanced vertex-wind `GrassField` over its footprint. */
+function OneGrass({ object, context }) {
+    const resolved = useMemo(() => resolveGrassObject(object), [object]);
+    if (resolved === null)
+        return null;
+    const { rules, size, center } = resolved;
+    return (_jsx(GrassField, { position: [center[0], center[1], center[2]], area: [size[0], size[1]], density: rules.density, bladeHeight: [rules.bladeHeight * 0.7, rules.bladeHeight], colorBase: rules.colorBase, colorTip: rules.colorTip, colorVariation: rules.colorVariation, roughness: rules.roughness, seed: hashSeed(rules.seed.length > 0 ? rules.seed : object.id), heightAt: (x, z) => context.field.sampleHeight(x, z), wind: { strength: rules.windStrength, speed: rules.windSpeed, gustScale: rules.windGust } }));
+}
+/** Registers the `grass_field` volume renderer. Called by `registerBuiltinSceneKindRenderers`. @internal */
+export function registerGrassFieldRenderer() {
+    registerSceneKindRenderer("grass_field", ({ objects, context }) => (_jsx(_Fragment, { children: objects.map((object) => (_jsx(OneGrass, { object: object, context: context }, object.id))) })));
+}

package/dist/scene/SoilPatchRenderer.d.ts

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

package/dist/scene/SoilPatchRenderer.js

@@ -0,0 +1,21 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useMemo } from "react";
+import { resolveSoilObject } from "@jgengine/core/world/soilKind";
+import { createSoilPatchMaterial } from "../terrain/soilPatchMaterial.js";
+import { registerSceneKindRenderer } from "./sceneKindRenderers.js";
+const SOIL_PATCH_THICKNESS = 0.08;
+/** One authored soil volume → a ground-hugging patch mesh with a crack/moss shader material. */
+function OneSoil({ object, context }) {
+    const resolved = useMemo(() => resolveSoilObject(object), [object]);
+    const material = useMemo(() => (resolved === null ? null : createSoilPatchMaterial(resolved.rules)), [resolved]);
+    useEffect(() => () => material?.dispose(), [material]);
+    if (resolved === null || material === null)
+        return null;
+    const groundY = context.field.sampleHeight(resolved.center[0], resolved.center[2]);
+    const y = groundY + SOIL_PATCH_THICKNESS / 2 + 0.02;
+    return (_jsx("mesh", { position: [resolved.center[0], y, resolved.center[2]], material: material, receiveShadow: true, children: _jsx("boxGeometry", { args: [resolved.size[0], SOIL_PATCH_THICKNESS, resolved.size[1]] }) }));
+}
+/** Registers the `soil` volume runtime renderer. Called by `registerBuiltinSceneKindRenderers`. @internal */
+export function registerSoilPatchRenderer() {
+    registerSceneKindRenderer("soil", ({ objects, context }) => (_jsx(_Fragment, { children: objects.map((object) => (_jsx(OneSoil, { object: object, context: context }, object.id))) })));
+}

package/dist/scene/StudioStage.d.ts

@@ -0,0 +1,37 @@
+import { type ReactNode } from "react";
+/** Lighting mood for a {@link StudioStage} — a named 3-point rig + backdrop palette. */
+export type StudioMood = "studio" | "daylight" | "dusk" | "night";
+/** Props for {@link StudioStage}. */
+export interface StudioStageProps {
+    mood?: StudioMood;
+    /** Override the scene background color (hex). Default: the mood's backdrop. */
+    backdrop?: string;
+    /** Turntable spin speed in radians/second (spins the children). 0 disables. Default 0. */
+    turntable?: number;
+    /** Draw the seamless floor + set the scene background. Off for open-world scenes. Default true. */
+    environment?: boolean;
+    /**
+     * Yaw the children every frame so `forward` points at the active camera — frame the declared front
+     * with zero `rotationY` tuning. Overrides `turntable` (the two are mutually exclusive: one spins the
+     * content, the other holds it facing whoever's looking). Default false.
+     */
+    faceCamera?: boolean;
+    /**
+     * The staged content's declared forward axis (`GeneratedAsset.forward`, or a scene kind's own
+     * convention) — the direction `faceCamera` turns to point at the camera. Default `[0, 0, 1]`, the
+     * engine-wide convention (`DEFAULT_FORWARD` in `@jgengine/core/scene/facing`).
+     */
+    forward?: readonly [number, number, number];
+    children: ReactNode;
+}
+/**
+ * A reusable cinematic "product-shot" stage — a 3-point lighting rig (key/fill/rim + ambient), a
+ * seamless backdrop, and an optional turntable — so any parametric studio renders framed and lit like
+ * a hero shot instead of a flat proxy under default light. Pair with `PlayableGame.postProcessing =
+ * STUDIO_STAGE_POST` for the full film grade. Set `environment: false` to keep an open-world sky/ground
+ * and use it purely as a lighting rig. Set `faceCamera` to auto-orient the declared `forward` toward
+ * the camera instead of hand-tuning `rotationY` on the child.
+ *
+ * @capability studio-stage cinematic lighting rig + backdrop + turntable for parametric studios
+ */
+export declare function StudioStage({ mood, backdrop, turntable, environment, faceCamera, forward, children, }: StudioStageProps): import("react").JSX.Element;

package/dist/scene/StudioStage.js

@@ -0,0 +1,42 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useRef } from "react";
+import { useFrame, useThree } from "@react-three/fiber";
+import * as THREE from "three";
+import { DEFAULT_FORWARD, yawToFace } from "@jgengine/core/scene/facing";
+const MOODS = {
+    studio: { key: 3.1, keyColor: "#fff4e6", fill: 0.9, fillColor: "#cdd8ff", rim: 2.6, rimColor: "#ffe9c7", ambient: 0.35, ambientColor: "#5b6472", backdrop: "#14161c", floor: "#1b1e26" },
+    daylight: { key: 3.4, keyColor: "#fff6ea", fill: 1.2, fillColor: "#d6e6ff", rim: 1.6, rimColor: "#ffffff", ambient: 0.6, ambientColor: "#8fa2bf", backdrop: "#cdd7e4", floor: "#aeb7c4" },
+    dusk: { key: 2.6, keyColor: "#ffcf9e", fill: 0.7, fillColor: "#7c8fd8", rim: 3.0, rimColor: "#ff9d6b", ambient: 0.4, ambientColor: "#4a4668", backdrop: "#221a26", floor: "#241d2a" },
+    night: { key: 1.6, keyColor: "#bcd0ff", fill: 0.4, fillColor: "#38507e", rim: 2.4, rimColor: "#9fd0ff", ambient: 0.22, ambientColor: "#1e2740", backdrop: "#0a0c12", floor: "#0e1119" },
+};
+/**
+ * A reusable cinematic "product-shot" stage — a 3-point lighting rig (key/fill/rim + ambient), a
+ * seamless backdrop, and an optional turntable — so any parametric studio renders framed and lit like
+ * a hero shot instead of a flat proxy under default light. Pair with `PlayableGame.postProcessing =
+ * STUDIO_STAGE_POST` for the full film grade. Set `environment: false` to keep an open-world sky/ground
+ * and use it purely as a lighting rig. Set `faceCamera` to auto-orient the declared `forward` toward
+ * the camera instead of hand-tuning `rotationY` on the child.
+ *
+ * @capability studio-stage cinematic lighting rig + backdrop + turntable for parametric studios
+ */
+export function StudioStage({ mood = "studio", backdrop, turntable = 0, environment = true, faceCamera = false, forward = DEFAULT_FORWARD, children, }) {
+    const spin = useRef(null);
+    const camera = useThree((state) => state.camera);
+    const groupWorld = useRef(new THREE.Vector3()).current;
+    const cameraWorld = useRef(new THREE.Vector3()).current;
+    useFrame((_, delta) => {
+        const group = spin.current;
+        if (group === null)
+            return;
+        if (faceCamera) {
+            group.getWorldPosition(groupWorld);
+            camera.getWorldPosition(cameraWorld);
+            group.rotation.y = yawToFace(forward, [groupWorld.x, groupWorld.z], [cameraWorld.x, cameraWorld.z]);
+            return;
+        }
+        if (turntable !== 0)
+            group.rotation.y += turntable * delta;
+    });
+    const rig = MOODS[mood];
+    return (_jsxs(_Fragment, { children: [environment ? _jsx("color", { attach: "background", args: [backdrop ?? rig.backdrop] }) : null, _jsx("ambientLight", { intensity: rig.ambient, color: rig.ambientColor }), _jsx("directionalLight", { position: [7, 9, 5], intensity: rig.key, color: rig.keyColor, castShadow: true, "shadow-mapSize": [2048, 2048], "shadow-bias": -0.0004, children: _jsx("orthographicCamera", { attach: "shadow-camera", args: [-24, 24, 24, -24, 0.5, 80] }) }), _jsx("directionalLight", { position: [-8, 5, 3], intensity: rig.fill, color: rig.fillColor }), _jsx("directionalLight", { position: [0, 6, -10], intensity: rig.rim, color: rig.rimColor }), environment ? (_jsxs("mesh", { "rotation-x": -Math.PI / 2, "position-y": -0.01, receiveShadow: true, children: [_jsx("planeGeometry", { args: [400, 400] }), _jsx("meshStandardMaterial", { color: rig.floor, roughness: 0.95, metalness: 0 })] })) : null, _jsx("group", { ref: spin, children: children })] }));
+}

package/dist/scene/WaterRenderer.d.ts

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

package/dist/scene/WaterRenderer.js

@@ -0,0 +1,37 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { resolveWaterObject } from "@jgengine/core/world/waterKind";
+import { Ocean } from "../water/Ocean.js";
+import { registerSceneKindRenderer } from "./sceneKindRenderers.js";
+/** Map the editor-authored water params onto the shell Ocean shader config. */
+function toOceanConfig(rules, size) {
+    const maxSpan = Math.max(size[0], size[1]);
+    return {
+        size: size[0],
+        depth: size[1],
+        resolution: Math.min(160, Math.max(16, Math.round(maxSpan / 2))),
+        amplitude: rules.waveHeight,
+        speed: rules.waveSpeed,
+        timeScale: rules.waveSpeed,
+        waveScale: Math.min(300, Math.max(2, 6 / rules.waveScale)),
+        color: {
+            deep: rules.color,
+            shallow: rules.shallowColor,
+            opacity: rules.opacity,
+            fresnelStrength: rules.reflectivity,
+        },
+        foam: { coverage: Math.min(1, rules.foam / 4), intensity: Math.min(1.5, rules.foam / 3) },
+    };
+}
+/** One authored water volume → a bounded, animated Ocean plane at the box top. */
+function OneWater({ object }) {
+    const resolved = useMemo(() => resolveWaterObject(object), [object]);
+    const config = useMemo(() => (resolved === null ? null : toOceanConfig(resolved.rules, resolved.size)), [resolved]);
+    if (resolved === null || config === null)
+        return null;
+    return _jsx(Ocean, { config: config, position: [resolved.center[0], resolved.center[1], resolved.center[2]] });
+}
+/** Registers the `water` volume runtime renderer. Called by `registerBuiltinSceneKindRenderers`. @internal */
+export function registerWaterRenderer() {
+    registerSceneKindRenderer("water", ({ objects }) => (_jsx(_Fragment, { children: objects.map((object) => (_jsx(OneWater, { object: object }, object.id))) })));
+}

package/dist/scene/builtinSceneKindRenderers.d.ts

@@ -0,0 +1,2 @@
+/** Registers the engine's built-in environment scene-kind renderers. Called by `AuthoredScene`. @internal */
+export declare function registerBuiltinSceneKindRenderers(): void;

package/dist/scene/builtinSceneKindRenderers.js

@@ -0,0 +1,22 @@
+/**
+ * Registers the engine's built-in *environment* scene-kind renderers (the shell half of #809) and
+ * ensures the matching core kinds are registered too. Idempotent; `AuthoredScene` calls it at module
+ * load so a document with a `water`/`grass_field`/`soil` volume renders without the game wiring
+ * anything up. Domain studios (poles, …) register their own renderer via the public
+ * `registerSceneKindRenderer` — no edit here.
+ */
+import { registerBuiltinSceneKinds } from "@jgengine/core/scene/builtinSceneKinds";
+import { registerGrassFieldRenderer } from "./GrassFieldRenderer.js";
+import { registerWaterRenderer } from "./WaterRenderer.js";
+import { registerSoilPatchRenderer } from "./SoilPatchRenderer.js";
+let registered = false;
+/** Registers the engine's built-in environment scene-kind renderers. Called by `AuthoredScene`. @internal */
+export function registerBuiltinSceneKindRenderers() {
+    if (registered)
+        return;
+    registered = true;
+    registerBuiltinSceneKinds();
+    registerWaterRenderer();
+    registerGrassFieldRenderer();
+    registerSoilPatchRenderer();
+}

package/dist/scene/sceneKindRenderers.d.ts

@@ -0,0 +1,28 @@
+import type { ReactElement } from "react";
+import type { EditorDocument } from "@jgengine/core/editor/index";
+import type { AssetCatalog } from "@jgengine/core/scene/assetCatalog";
+import type { SceneKindObject } from "@jgengine/core/scene/sceneKinds";
+import type { TerrainField } from "@jgengine/core/world/terrain";
+/** Context a scene-kind renderer receives alongside the matching document objects. */
+export interface SceneKindRenderContext {
+    document: EditorDocument;
+    /** Ground field to drape/ground kind geometry on. */
+    field: TerrainField;
+    /** Catalog for kinds that instance real GLBs (pole assets, etc.). */
+    assets?: AssetCatalog;
+}
+/** A registered renderer: given every document object of its kind, returns the render tree for them. */
+export type SceneKindRenderer = (props: {
+    objects: readonly SceneKindObject[];
+    context: SceneKindRenderContext;
+}) => ReactElement | null;
+/**
+ * Register the runtime renderer for a scene kind — the shell half of the #809 seam. `AuthoredScene`
+ * groups a document's objects by kind and mounts the registered renderer for each, so a new studio
+ * renders from the document with no fork of `AuthoredScene`. Idempotent per kind (last wins).
+ */
+export declare function registerSceneKindRenderer(kind: string, renderer: SceneKindRenderer): void;
+/** The renderer registered for a kind, or undefined. @internal — `AuthoredScene` uses it internally. */
+export declare function getSceneKindRenderer(kind: string): SceneKindRenderer | undefined;
+/** Every kind that has a registered renderer. @internal */
+export declare function renderedSceneKinds(): string[];

package/dist/scene/sceneKindRenderers.js

@@ -0,0 +1,17 @@
+const renderers = new Map();
+/**
+ * Register the runtime renderer for a scene kind — the shell half of the #809 seam. `AuthoredScene`
+ * groups a document's objects by kind and mounts the registered renderer for each, so a new studio
+ * renders from the document with no fork of `AuthoredScene`. Idempotent per kind (last wins).
+ */
+export function registerSceneKindRenderer(kind, renderer) {
+    renderers.set(kind, renderer);
+}
+/** The renderer registered for a kind, or undefined. @internal — `AuthoredScene` uses it internally. */
+export function getSceneKindRenderer(kind) {
+    return renderers.get(kind);
+}
+/** Every kind that has a registered renderer. @internal */
+export function renderedSceneKinds() {
+    return [...renderers.keys()];
+}

package/dist/scene.d.ts

@@ -0,0 +1 @@
+export * from "./scene/AuthoredScene.js";

package/dist/scene.js

@@ -0,0 +1 @@
+export * from "./scene/AuthoredScene.js";

package/dist/settings/appliedSettings.d.ts

@@ -1,6 +1,11 @@
 import type { AudioBusDef } from "@jgengine/core/audio/audioFalloff";
 import { type SettingsStore } from "@jgengine/core/settings/settingsModel";
+import { type TouchStyle } from "@jgengine/core/input/touchScheme";
 import type { AudioEngine } from "../audio/audioEngine.js";
+/** Sentinel Controls value meaning "defer to the game's suggested touch skin". */
+export declare const TOUCH_STYLE_AUTO = "auto";
+/** Shell-internal: binds the SettingsStore touch-style choice to the touch renderer. @internal */
+export declare function useTouchStyle(store: SettingsStore, fallback: TouchStyle): TouchStyle;
 export declare function useSettingsRevision(store: SettingsStore): number;
 export declare function useGraphicsSettings(store: SettingsStore, shadowsDefault: boolean): {
     shadows: boolean;

package/dist/settings/appliedSettings.js

@@ -1,5 +1,14 @@
 import { useEffect, useReducer } from "react";
 import { busVolumeSettingId, DEFAULT_GRAPHICS_QUALITY, DEFAULT_MASTER_VOLUME, DEFAULT_UI_SCALE, GRAPHICS_QUALITY_DPR, SETTING_IDS, UI_SCALE_MAX, UI_SCALE_MIN, } from "@jgengine/core/settings/settingsModel";
+import { TOUCH_STYLES } from "@jgengine/core/input/touchScheme";
+/** Sentinel Controls value meaning "defer to the game's suggested touch skin". */
+export const TOUCH_STYLE_AUTO = "auto";
+/** Shell-internal: binds the SettingsStore touch-style choice to the touch renderer. @internal */
+export function useTouchStyle(store, fallback) {
+    useSettingsRevision(store);
+    const raw = store.get(SETTING_IDS.touchStyle, TOUCH_STYLE_AUTO);
+    return TOUCH_STYLES.includes(raw) ? raw : fallback;
+}
 export function useSettingsRevision(store) {
     const [rev, bump] = useReducer((n) => n + 1, 0);
     useEffect(() => store.subscribe(() => bump()), [store]);

package/dist/settings/settingsController.d.ts

@@ -12,6 +12,8 @@ export interface SettingsControllerInput {
     hide: readonly SettingCategory[];
     fovEnabled: boolean;
     hideBindings: readonly string[];
+    /** Show the touch-controls skin selector in Controls (touch device with a dock). */
+    touchStyle: boolean;
     overrides: BindingOverrides;
     rebind: (action: string, code: string) => void;
     resetBinding: (action: string) => void;

package/dist/settings/settingsController.js

@@ -1,6 +1,8 @@
 import { useEffect, useReducer } from "react";
 import { actionLabel, bindingLabel } from "@jgengine/core/input/actionBindings";
 import { BUILT_IN_SETTING_CATEGORIES, busVolumeSettingId, DEFAULT_GRAPHICS_QUALITY, DEFAULT_GRAPHICS_SHADOWS, DEFAULT_MASTER_VOLUME, DEFAULT_UI_SCALE, GRAPHICS_QUALITY_OPTIONS, SETTING_IDS, UI_SCALE_MAX, UI_SCALE_MIN, } from "@jgengine/core/settings/settingsModel";
+import { TOUCH_STYLE_OPTIONS } from "@jgengine/core/input/touchScheme";
+import { TOUCH_STYLE_AUTO } from "./appliedSettings.js";
 import { useSettingsStore, } from "@jgengine/react/settings";
 import { usePlayerFov } from "../camera/PlayerFov.js";
 const DEFAULT_CATEGORY_LABELS = {
@@ -10,6 +12,10 @@ const DEFAULT_CATEGORY_LABELS = {
     controls: "Controls",
 };
 const percent = (value) => `${Math.round(value * 100)}%`;
+const TOUCH_STYLE_SELECT_OPTIONS = [
+    { value: TOUCH_STYLE_AUTO, label: "Auto (game default)" },
+    ...TOUCH_STYLE_OPTIONS.map((option) => ({ value: option.value, label: option.label })),
+];
 export function useSettingsCategories(config) {
     const store = useSettingsStore();
     const fov = usePlayerFov();
@@ -119,11 +125,26 @@ export function useSettingsCategories(config) {
             reset: () => config.resetBinding(action),
         };
     });
+    const controlsRows = [
+        ...(config.touchStyle
+            ? [
+                {
+                    id: SETTING_IDS.touchStyle,
+                    label: "Touch controls",
+                    kind: "select",
+                    value: store.get(SETTING_IDS.touchStyle, TOUCH_STYLE_AUTO),
+                    options: TOUCH_STYLE_SELECT_OPTIONS,
+                    set: (value) => store.set(SETTING_IDS.touchStyle, value),
+                },
+            ]
+            : []),
+        ...extrasFor("controls"),
+    ];
     const builtInRows = {
         sound: soundRows,
         graphics: graphicsRows,
         gameplay: gameplayRows,
-        controls: extrasFor("controls"),
+        controls: controlsRows,
     };
     const builtInKeybinds = { controls: keybinds };
     const declaredLabels = new Map(config.categories.map((c) => [c.id, c.label]));

package/dist/shellConstants.d.ts

@@ -0,0 +1,4 @@
+/** No action names are reserved when no camera rig is active (hud/none presentation): games may bind `turnLeft`/`interact`/etc. as their own. */
+export declare const EMPTY_RESERVED: ReadonlySet<string>;
+/** Empty action list — published while the orientation gate is up to suppress all held input without touching the tracker. */
+export declare const NO_ACTIONS: string[];

package/dist/shellConstants.js

@@ -0,0 +1,4 @@
+/** No action names are reserved when no camera rig is active (hud/none presentation): games may bind `turnLeft`/`interact`/etc. as their own. */
+export const EMPTY_RESERVED = new Set();
+/** Empty action list — published while the orientation gate is up to suppress all held input without touching the tracker. */
+export const NO_ACTIONS = [];

package/dist/shellMovement.d.ts

@@ -0,0 +1,8 @@
+/** Movement action names the shell drives via the walk controller. @internal */
+export declare const SHELL_MOVEMENT_ACTIONS: readonly ["moveForward", "moveBack", "moveLeft", "moveRight", "jump"];
+/**
+ * True when the game's input map binds any walk-controller action — the shell owns pose
+ * for those games. Games that omit all five drive pose themselves.
+ * @internal
+ */
+export declare function shellDrivesPlayerPose(input: Record<string, unknown> | undefined): boolean;

package/dist/shellMovement.js

@@ -0,0 +1,11 @@
+/** Movement action names the shell drives via the walk controller. @internal */
+export const SHELL_MOVEMENT_ACTIONS = ["moveForward", "moveBack", "moveLeft", "moveRight", "jump"];
+/**
+ * True when the game's input map binds any walk-controller action — the shell owns pose
+ * for those games. Games that omit all five drive pose themselves.
+ * @internal
+ */
+export function shellDrivesPlayerPose(input) {
+    const bound = input ?? {};
+    return SHELL_MOVEMENT_ACTIONS.some((action) => action in bound);
+}