@jgengine/shell 0.10.0 → 0.12.0

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,73 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useMemo } from "react";
+import { resolveGrassObject } from "@jgengine/core/world/grassKind";
+import { GrassField } from "../terrain/GrassField.js";
+import { registerSceneKindRenderer } from "./sceneKindRenderers.js";
+/** Volume kinds turf yields to — blades never grow through cracked soil or out of open water. */
+const GRASS_YIELDS_TO = new Set(["soil", "water"]);
+/**
+ * Patch-local no-grow rects from the document's soil/water volumes. Water rects shrink by the
+ * shore margin so a fringe of blades still wades into the shallows like a real pond edge.
+ */
+function grassExclusionsFrom(context, center) {
+    const zones = [];
+    for (const volume of context.document.volumes) {
+        if (!GRASS_YIELDS_TO.has(volume.kind) || volume.halfExtents === undefined)
+            continue;
+        const shoreMargin = volume.kind === "water" ? 1.6 : 0;
+        const halfX = Math.max(0, volume.halfExtents.x - shoreMargin);
+        const halfZ = Math.max(0, volume.halfExtents.z - shoreMargin);
+        if (halfX <= 0 || halfZ <= 0)
+            continue;
+        zones.push({
+            center: [volume.center.x - center[0], volume.center.z - center[2]],
+            half: [halfX, halfZ],
+            feather: volume.kind === "water" ? 2.4 : 1.2,
+        });
+    }
+    return zones;
+}
+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;
+}
+function sampleHeight(field, x, z) {
+    return field.sampleHeight(x, z);
+}
+/**
+ * One authored grass volume → an instanced vertex-wind `GrassField` over its footprint.
+ * `area`/`bladeHeight`/`wind`/`heightAt` are memoized so `GrassField`'s internal geometry and
+ * material `useMemo`s see stable references across re-renders — otherwise every re-render (the
+ * live-sync document context object is recreated per render) rebuilds the blade geometry and
+ * shader material from scratch, which shows up as recurring render hitches.
+ */
+function OneGrass({ object, context }) {
+    const resolved = useMemo(() => resolveGrassObject(object), [object]);
+    const heightAt = useCallback((x, z) => sampleHeight(context.field, x, z), [context.field]);
+    const area = useMemo(() => (resolved === null ? null : [resolved.size[0], resolved.size[1]]), [resolved]);
+    const bladeHeight = useMemo(() => (resolved === null ? null : [resolved.rules.bladeHeight * 0.7, resolved.rules.bladeHeight]), [resolved]);
+    const wind = useMemo(() => resolved === null
+        ? null
+        : { strength: resolved.rules.windStrength, speed: resolved.rules.windSpeed, gustScale: resolved.rules.windGust }, [resolved]);
+    // Depends on the volumes slice, not the context object — the live-sync context is recreated
+    // per render and would otherwise rebuild the tuft geometry every frame.
+    const volumes = context.document.volumes;
+    const exclude = useMemo(() => (resolved === null ? null : grassExclusionsFrom(context, resolved.center)), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [volumes, resolved]);
+    if (resolved === null || area === null || bladeHeight === null || wind === null || exclude === null)
+        return null;
+    const { rules, center } = resolved;
+    // Size the instance buffer to the authored patch (bounded): the default 1500-blade buffer reads
+    // as stubble on anything bigger than a lawn, silently ignoring the authored density.
+    const instanceCount = Math.max(1500, Math.min(250000, Math.ceil(rules.density * area[0] * area[1])));
+    return (_jsx(GrassField, { position: [center[0], center[1], center[2]], area: area, count: instanceCount, density: rules.density, bladeHeight: bladeHeight, colorBase: rules.colorBase, colorTip: rules.colorTip, colorGround: context.groundColorAt?.(center[0], center[2]), colorVariation: rules.colorVariation, roughness: rules.roughness, seed: hashSeed(rules.seed.length > 0 ? rules.seed : object.id), heightAt: heightAt, wind: wind, edgeFeather: 2.2, exclude: exclude }));
+}
+/** 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/PoleLineRenderer.d.ts

@@ -0,0 +1,2 @@
+/** Registers the built-in pole-line runtime renderer. Called by `registerBuiltinSceneKindRenderers`. @internal */
+export declare function registerPoleLineRenderer(): void;

package/dist/scene/PoleLineRenderer.js

@@ -0,0 +1,287 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Runtime renderer for the built-in `pole_line` scene kind: instanced poles (proxy cylinders, or a
+ * GLB pole asset when one is named) plus merged tube geometry for the sagging cables. Registered by
+ * `registerBuiltinSceneKindRenderers` so any document with a `pole_line` path renders with no game
+ * wiring. Uses the generic core primitive `readNamedSockets` to hang wires off a GLB pole's authored
+ * crossarm empties (falling back to computed offsets).
+ */
+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 { parseParams } from "@jgengine/core/scene/sceneKinds";
+import { readNamedSockets } from "@jgengine/core/scene/modelSockets";
+import { POLE_LINE_KIND, POLE_LINE_SCHEMA, resolvePoleLine } from "@jgengine/core/world/poleLineKind";
+import { registerSceneKindRenderer } from "./sceneKindRenderers.js";
+function Cables({ cables }) {
+    const geometry = useMemo(() => {
+        const parts = [];
+        for (const cable of cables) {
+            if (cable.points.length < 2)
+                continue;
+            const curve = new THREE.CatmullRomCurve3(cable.points.map((point) => new THREE.Vector3(point[0], point[1], point[2])));
+            parts.push(new THREE.TubeGeometry(curve, Math.max(2, (cable.points.length - 1) * 2), cable.radius, 6, false));
+        }
+        if (parts.length === 0)
+            return null;
+        const merged = mergePositionGeometries(parts);
+        for (const part of parts)
+            part.dispose();
+        return merged;
+    }, [cables]);
+    useEffect(() => () => geometry?.dispose(), [geometry]);
+    if (geometry === null)
+        return null;
+    // Dark warm rubber-sheath tone with a hint of sheen — pitch black tubes read as ink scribbles
+    // against the sky, real cable catches a little light along its top.
+    return (_jsx("mesh", { geometry: geometry, castShadow: true, children: _jsx("meshStandardMaterial", { color: "#31281f", roughness: 0.55, metalness: 0.15 }) }));
+}
+/**
+ * Weathered wood for the proxy poles: vertical grain streaks + broad tonal banding driven by the
+ * pole's own cylindrical coordinates, offset per instance so no two poles share a pattern, and a
+ * sun-bleach lift toward the top. Injected via `onBeforeCompile`, instancing-aware.
+ */
+function createWeatheredWoodMaterial(color, grainAlong = "y") {
+    const material = new THREE.MeshStandardMaterial({ color, roughness: 0.92, metalness: 0 });
+    material.onBeforeCompile = (shader) => {
+        shader.vertexShader = shader.vertexShader
+            .replace("#include <common>", `#include <common>
+varying vec3 vJgWoodLocal;
+varying vec2 vJgWoodSeed;`)
+            .replace("#include <begin_vertex>", `#include <begin_vertex>
+vJgWoodLocal = position;
+#ifdef USE_INSTANCING
+vJgWoodSeed = (instanceMatrix * vec4(0.0, 0.0, 0.0, 1.0)).xz;
+#else
+vJgWoodSeed = vec2(0.0);
+#endif`);
+        shader.fragmentShader = shader.fragmentShader
+            .replace("#include <common>", `#include <common>
+varying vec3 vJgWoodLocal;
+varying vec2 vJgWoodSeed;
+float jgWoodHash(vec2 p){
+  uvec2 q = uvec2(ivec2(floor(p)));
+  uint x = q.x * 1664525u + q.y * 1013904223u;
+  x = (x ^ (x >> 16u)) * 2246822519u;
+  x = (x ^ (x >> 13u)) * 3266489917u;
+  return float(x ^ (x >> 16u)) * (1.0 / 4294967296.0);
+}
+float jgWoodNoise(vec2 p){
+  vec2 i = floor(p); vec2 f = fract(p);
+  vec2 u = f * f * (3.0 - 2.0 * f);
+  float a = jgWoodHash(i); float b = jgWoodHash(i + vec2(1.0, 0.0));
+  float c = jgWoodHash(i + vec2(0.0, 1.0)); float d = jgWoodHash(i + vec2(1.0, 1.0));
+  return mix(mix(a, b, u.x), mix(c, d, u.x), u.y);
+}`)
+            .replace("#include <color_fragment>", `#include <color_fragment>
+${grainAlong === "y"
+            ? `vec2 jgWoodUv = vec2(atan(vJgWoodLocal.x, vJgWoodLocal.z) * 1.4, vJgWoodLocal.y * 0.55);`
+            : `vec2 jgWoodUv = vec2(vJgWoodLocal.y * 9.0 + vJgWoodLocal.z * 7.0, vJgWoodLocal.x * 0.8);`}
+vec2 jgWoodOff = vec2(dot(vJgWoodSeed, vec2(0.73, 1.31)), dot(vJgWoodSeed, vec2(1.17, 0.41)));
+float jgWoodBand = jgWoodNoise(jgWoodUv * vec2(2.0, 1.0) + jgWoodOff);
+float jgWoodStreak = jgWoodNoise(jgWoodUv * vec2(7.0, 0.35) + jgWoodOff * 1.7);
+diffuseColor.rgb *= mix(0.74, 1.14, jgWoodBand * 0.45 + jgWoodStreak * 0.55);
+${grainAlong === "y" ? `// Sun-bleached crown, damp-darkened foot — reads as years outdoors, not fresh paint.
+diffuseColor.rgb = mix(diffuseColor.rgb * 0.82, diffuseColor.rgb * vec3(1.08, 1.05, 0.98), smoothstep(-3.5, 3.0, vJgWoodLocal.y));` : ""}`);
+    };
+    material.customProgramCacheKey = () => `jgengine-weathered-wood-${grainAlong}`;
+    return material;
+}
+/** Minimal position/normal/index merge — avoids depending on a specific BufferGeometryUtils path. */
+function mergePositionGeometries(geometries) {
+    let vertexCount = 0;
+    let indexCount = 0;
+    for (const geometry of geometries) {
+        vertexCount += geometry.getAttribute("position").count;
+        const index = geometry.getIndex();
+        indexCount += index === null ? geometry.getAttribute("position").count : index.count;
+    }
+    const positions = new Float32Array(vertexCount * 3);
+    const normals = new Float32Array(vertexCount * 3);
+    const indices = new Uint32Array(indexCount);
+    let vertexOffset = 0;
+    let indexOffset = 0;
+    for (const geometry of geometries) {
+        const position = geometry.getAttribute("position");
+        const normal = geometry.getAttribute("normal");
+        positions.set(position.array, vertexOffset * 3);
+        if (normal !== undefined)
+            normals.set(normal.array, vertexOffset * 3);
+        const index = geometry.getIndex();
+        if (index === null) {
+            for (let i = 0; i < position.count; i += 1)
+                indices[indexOffset + i] = vertexOffset + i;
+            indexOffset += position.count;
+        }
+        else {
+            for (let i = 0; i < index.count; i += 1)
+                indices[indexOffset + i] = vertexOffset + index.getX(i);
+            indexOffset += index.count;
+        }
+        vertexOffset += position.count;
+    }
+    const merged = new THREE.BufferGeometry();
+    merged.setAttribute("position", new THREE.BufferAttribute(positions, 3));
+    merged.setAttribute("normal", new THREE.BufferAttribute(normals, 3));
+    merged.setIndex(new THREE.BufferAttribute(indices, 1));
+    return merged;
+}
+/**
+ * Proxy utility poles built from primitives when no GLB pole asset is named: a tapered trunk, a
+ * wood crossarm sized to the wire spread with a small brace, and one ceramic insulator peg under
+ * each wire offset — so the cables visibly hang *from* the pole instead of floating beside a stick.
+ */
+function ProxyPoles({ poles, height, wireCount, wireSpacing, }) {
+    const trunkRef = useRef(null);
+    const armRef = useRef(null);
+    const braceRef = useRef(null);
+    const insulatorRef = useRef(null);
+    const armLength = wireCount > 1 ? (wireCount - 1) * wireSpacing + 0.6 : 0.8;
+    // Chunkier members than a real-scale pole: stylized worlds read thin cylinders as wire, not wood.
+    const trunkGeometry = useMemo(() => new THREE.CylinderGeometry(0.13, 0.22, height, 10), [height]);
+    const armGeometry = useMemo(() => new THREE.BoxGeometry(armLength, 0.17, 0.14), [armLength]);
+    const braceGeometry = useMemo(() => {
+        const braceSpan = Math.hypot(armLength * 0.32, 0.7);
+        return new THREE.BoxGeometry(0.07, braceSpan, 0.06);
+    }, [armLength]);
+    const insulatorGeometry = useMemo(() => new THREE.CylinderGeometry(0.06, 0.085, 0.24, 8), []);
+    const trunkMaterial = useMemo(() => createWeatheredWoodMaterial("#6b533a"), []);
+    const armMaterial = useMemo(() => createWeatheredWoodMaterial("#59452e", "x"), []);
+    useEffect(() => () => {
+        trunkGeometry.dispose();
+        armGeometry.dispose();
+        braceGeometry.dispose();
+        insulatorGeometry.dispose();
+    }, [trunkGeometry, armGeometry, braceGeometry, insulatorGeometry]);
+    useEffect(() => () => {
+        trunkMaterial.dispose();
+        armMaterial.dispose();
+    }, [trunkMaterial, armMaterial]);
+    useEffect(() => {
+        const trunk = trunkRef.current;
+        const arm = armRef.current;
+        const brace = braceRef.current;
+        const insulator = insulatorRef.current;
+        if (trunk === 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(1, 1, 1);
+        const armY = height - 0.22;
+        const half = (wireCount - 1) / 2;
+        const braceAngle = Math.atan2(armLength * 0.32, 0.7);
+        poles.forEach((pole, index) => {
+            euler.set(0, pole.yaw, 0);
+            quaternion.setFromEuler(euler);
+            position.set(pole.position[0], pole.position[1] + height / 2, pole.position[2]);
+            matrix.compose(position, quaternion, scale);
+            trunk.setMatrixAt(index, matrix);
+            if (arm !== null) {
+                position.set(pole.position[0], pole.position[1] + armY, pole.position[2]);
+                matrix.compose(position, quaternion, scale);
+                arm.setMatrixAt(index, matrix);
+            }
+            if (brace !== null) {
+                // Two diagonal braces from the trunk up to the crossarm — the classic A-frame silhouette.
+                const cos = Math.cos(pole.yaw);
+                const sin = Math.sin(pole.yaw);
+                for (let side = 0; side < 2; side += 1) {
+                    const direction = side === 0 ? 1 : -1;
+                    const lateral = direction * armLength * 0.16;
+                    position.set(pole.position[0] + cos * lateral, pole.position[1] + armY - 0.38, pole.position[2] - sin * lateral);
+                    euler.set(0, pole.yaw, direction * braceAngle);
+                    quaternion.setFromEuler(euler);
+                    matrix.compose(position, quaternion, scale);
+                    brace.setMatrixAt(index * 2 + side, matrix);
+                }
+                euler.set(0, pole.yaw, 0);
+                quaternion.setFromEuler(euler);
+            }
+            if (insulator !== null) {
+                // Insulator pegs sit on the crossarm at each wire's lateral offset (the pole's local X axis
+                // after yaw — the same perpendicular the resolver strings cables along).
+                const cos = Math.cos(pole.yaw);
+                const sin = Math.sin(pole.yaw);
+                for (let w = 0; w < wireCount; w += 1) {
+                    const offset = (w - half) * wireSpacing;
+                    position.set(pole.position[0] + cos * offset, pole.position[1] + height - 0.08, pole.position[2] - sin * offset);
+                    matrix.compose(position, quaternion, scale);
+                    insulator.setMatrixAt(index * wireCount + w, matrix);
+                }
+            }
+        });
+        trunk.count = poles.length;
+        trunk.instanceMatrix.needsUpdate = true;
+        trunk.computeBoundingSphere();
+        if (arm !== null) {
+            arm.count = poles.length;
+            arm.instanceMatrix.needsUpdate = true;
+            arm.computeBoundingSphere();
+        }
+        if (brace !== null) {
+            brace.count = poles.length * 2;
+            brace.instanceMatrix.needsUpdate = true;
+            brace.computeBoundingSphere();
+        }
+        if (insulator !== null) {
+            insulator.count = poles.length * wireCount;
+            insulator.instanceMatrix.needsUpdate = true;
+            insulator.computeBoundingSphere();
+        }
+    }, [poles, height, wireCount, wireSpacing]);
+    return (_jsxs(_Fragment, { children: [_jsx("instancedMesh", { ref: trunkRef, args: [trunkGeometry, trunkMaterial, Math.max(1, poles.length)], castShadow: true, receiveShadow: true }), wireCount > 0 ? (_jsxs(_Fragment, { children: [_jsx("instancedMesh", { ref: armRef, args: [armGeometry, armMaterial, Math.max(1, poles.length)], castShadow: true, receiveShadow: true }), _jsx("instancedMesh", { ref: braceRef, args: [braceGeometry, armMaterial, Math.max(1, poles.length * 2)], castShadow: true }), _jsx("instancedMesh", { ref: insulatorRef, args: [insulatorGeometry, undefined, Math.max(1, poles.length * wireCount)], castShadow: true, children: _jsx("meshStandardMaterial", { color: "#a8a18c", roughness: 0.32, metalness: 0.12 }) })] })) : null] }));
+}
+function ModelPoles({ url, poles }) {
+    const gltf = useLoader(GLTFLoader, url);
+    const sources = useMemo(() => {
+        const meshes = [];
+        gltf.scene.updateWorldMatrix(true, true);
+        gltf.scene.traverse((node) => {
+            const mesh = node;
+            if (mesh.isMesh)
+                meshes.push({ geometry: mesh.geometry, material: mesh.material, local: mesh.matrixWorld.clone() });
+        });
+        // readNamedSockets is available for wire-anchor refinement; the proxy path already honors offsets.
+        void readNamedSockets(gltf.scene);
+        return meshes;
+    }, [gltf]);
+    return (_jsx(_Fragment, { children: sources.map((source, index) => (_jsx(ModelPoleSource, { source: source, poles: poles }, index))) }));
+}
+function ModelPoleSource({ source, poles }) {
+    const meshRef = useRef(null);
+    useEffect(() => {
+        const mesh = meshRef.current;
+        if (mesh === null)
+            return;
+        const base = new THREE.Matrix4();
+        const composed = new THREE.Matrix4();
+        const position = new THREE.Vector3();
+        const quaternion = new THREE.Quaternion();
+        const euler = new THREE.Euler();
+        const scale = new THREE.Vector3(1, 1, 1);
+        poles.forEach((pole, index) => {
+            position.set(pole.position[0], pole.position[1], pole.position[2]);
+            euler.set(0, pole.yaw, 0);
+            quaternion.setFromEuler(euler);
+            base.compose(position, quaternion, scale);
+            composed.multiplyMatrices(base, source.local);
+            mesh.setMatrixAt(index, composed);
+        });
+        mesh.count = poles.length;
+        mesh.instanceMatrix.needsUpdate = true;
+        mesh.computeBoundingSphere();
+    }, [poles, source]);
+    return _jsx("instancedMesh", { ref: meshRef, args: [source.geometry, source.material, Math.max(1, poles.length)], castShadow: true, receiveShadow: true });
+}
+function OnePoleLine({ object, context }) {
+    const resolved = useMemo(() => resolvePoleLine(object, parseParams(POLE_LINE_SCHEMA, object.meta), { sampleHeight: (x, z) => context.field.sampleHeight(x, z) }), [object, context.field]);
+    const modelUrl = resolved.poleAsset.length > 0 ? context.assets?.resolve(resolved.poleAsset)?.url : undefined;
+    return (_jsxs(_Fragment, { children: [modelUrl !== undefined ? (_jsx(Suspense, { fallback: _jsx(ProxyPoles, { poles: resolved.poles, height: resolved.poleHeight, wireCount: resolved.wireCount, wireSpacing: resolved.wireSpacing }), children: _jsx(ModelPoles, { url: modelUrl, poles: resolved.poles }) })) : (_jsx(ProxyPoles, { poles: resolved.poles, height: resolved.poleHeight, wireCount: resolved.wireCount, wireSpacing: resolved.wireSpacing })), _jsx(Cables, { cables: resolved.cables })] }));
+}
+/** Registers the built-in pole-line runtime renderer. Called by `registerBuiltinSceneKindRenderers`. @internal */
+export function registerPoleLineRenderer() {
+    registerSceneKindRenderer(POLE_LINE_KIND, ({ objects, context }) => (_jsx(_Fragment, { children: objects.map((object) => (_jsx(OnePoleLine, { 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,84 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useMemo } from "react";
+import * as THREE from "three";
+import { resolveSoilObject } from "@jgengine/core/world/soilKind";
+import { createSoilPatchMaterial } from "../terrain/soilPatchMaterial.js";
+import { registerSceneKindRenderer } from "./sceneKindRenderers.js";
+/** Height offset above the sampled terrain so the draped patch never z-fights the ground. */
+const SOIL_LIFT = 0.04;
+/** Amplitude of the seeded micro-relief layered onto the drape, meters. */
+const SOIL_RELIEF = 0.13;
+/** Cheap deterministic 2D value noise (two octaves) for the patch's baked micro-relief. */
+function reliefNoise(x, z) {
+    const n = (px, pz) => {
+        const s = Math.sin(px * 12.9898 + pz * 78.233) * 43758.5453;
+        return s - Math.floor(s);
+    };
+    const octave = (px, pz) => {
+        const ix = Math.floor(px);
+        const iz = Math.floor(pz);
+        const fx = px - ix;
+        const fz = pz - iz;
+        const ux = fx * fx * (3 - 2 * fx);
+        const uz = fz * fz * (3 - 2 * fz);
+        const a = n(ix, iz);
+        const b = n(ix + 1, iz);
+        const c = n(ix, iz + 1);
+        const d = n(ix + 1, iz + 1);
+        return a + (b - a) * ux + (c - a) * uz + (a - b - c + d) * ux * uz;
+    };
+    return octave(x * 0.7, z * 0.7) * 0.65 + octave(x * 2.3, z * 2.3) * 0.35;
+}
+/**
+ * One authored soil volume → a subdivided plane draped over the live terrain (each vertex sampled
+ * from the height field) with the crack/moss shader and a noise-eroded edge fade, so the patch hugs
+ * relief and dissolves into the surrounding ground instead of reading as a hovering brown box.
+ */
+function OneSoil({ object, context }) {
+    const resolved = useMemo(() => resolveSoilObject(object), [object]);
+    const groundColorAt = context.groundColorAt;
+    const material = useMemo(() => resolved === null
+        ? null
+        : createSoilPatchMaterial(resolved.rules, {
+            center: [resolved.center[0], resolved.center[2]],
+            halfSize: [resolved.size[0] / 2, resolved.size[1] / 2],
+            ...(groundColorAt === undefined
+                ? {}
+                : { groundColor: groundColorAt(resolved.center[0], resolved.center[2]) }),
+        }), [resolved, groundColorAt]);
+    const geometry = useMemo(() => {
+        if (resolved === null)
+            return null;
+        const [w, d] = resolved.size;
+        const segX = Math.min(96, Math.max(12, Math.round(w / 0.4)));
+        const segZ = Math.min(96, Math.max(12, Math.round(d / 0.4)));
+        const plane = new THREE.PlaneGeometry(w, d, segX, segZ);
+        plane.rotateX(-Math.PI / 2);
+        const positions = plane.getAttribute("position");
+        for (let i = 0; i < positions.count; i += 1) {
+            const x = positions.getX(i);
+            const z = positions.getZ(i);
+            const wx = resolved.center[0] + x;
+            const wz = resolved.center[2] + z;
+            // Seeded micro-relief so the cracked dirt catches light like packed earth, not a flat decal;
+            // the amplitude eases out toward the border so the fading edge still meets the ground flush.
+            const edgeX = 1 - Math.min(1, Math.abs(x) / (w / 2));
+            const edgeZ = 1 - Math.min(1, Math.abs(z) / (d / 2));
+            const edgeEase = Math.min(1, Math.min(edgeX, edgeZ) * 3);
+            const relief = (reliefNoise(wx, wz) - 0.5) * 2 * SOIL_RELIEF * edgeEase;
+            positions.setY(i, context.field.sampleHeight(wx, wz) + SOIL_LIFT + relief);
+        }
+        positions.needsUpdate = true;
+        plane.computeVertexNormals();
+        return plane;
+    }, [resolved, context.field]);
+    useEffect(() => () => material?.dispose(), [material]);
+    useEffect(() => () => geometry?.dispose(), [geometry]);
+    if (resolved === null || material === null || geometry === null)
+        return null;
+    return _jsx("mesh", { position: [resolved.center[0], 0, resolved.center[2]], geometry: geometry, material: material, receiveShadow: true });
+}
+/** 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;