@jgengine/shell 0.11.0 → 0.12.0

package/dist/scene/GrassFieldRenderer.js

@@ -1,8 +1,32 @@
 import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
-import { useMemo } from "react";
+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) {
@@ -11,13 +35,37 @@ function hashSeed(text) {
     }
     return (h >>> 0) % 100000;
 }
-/** One authored grass volume → an instanced vertex-wind `GrassField` over its footprint. */
+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]);
-    if (resolved === null)
+    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, 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 } }));
+    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() {

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.js

@@ -1,19 +1,82 @@
 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";
-const SOIL_PATCH_THICKNESS = 0.08;
-/** One authored soil volume → a ground-hugging patch mesh with a crack/moss shader material. */
+/** 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 material = useMemo(() => (resolved === null ? null : createSoilPatchMaterial(resolved.rules)), [resolved]);
+    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]);
-    if (resolved === null || material === null)
+    useEffect(() => () => geometry?.dispose(), [geometry]);
+    if (resolved === null || material === null || geometry === 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]] }) }));
+    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() {

package/dist/scene/WaterRenderer.js

@@ -1,15 +1,17 @@
 import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
-import { useMemo } from "react";
+import { useCallback, 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) {
+function toOceanConfig(rules, size, depthRange) {
     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))),
+        // ~2 vertices per meter (bounded): the old span/2 gave a 30 m lake a 15×15 grid, which waved
+        // like a blanket instead of water.
+        resolution: Math.min(220, Math.max(48, Math.round(maxSpan * 2))),
         amplitude: rules.waveHeight,
         speed: rules.waveSpeed,
         timeScale: rules.waveSpeed,
@@ -18,20 +20,42 @@ function toOceanConfig(rules, size) {
             deep: rules.color,
             shallow: rules.shallowColor,
             opacity: rules.opacity,
-            fresnelStrength: rules.reflectivity,
+            // The editor's reflectivity slider stays restrained: full slider ≈ a soft sky sheen at
+            // grazing angles, never the white-out the old fresnel washed the whole sheet with.
+            fresnelStrength: rules.reflectivity * 0.9,
+            depthRange,
+            sparkle: 0.25 + rules.reflectivity * 0.3,
+        },
+        foam: {
+            coverage: Math.min(1, rules.foam / 4),
+            intensity: Math.min(1.2, rules.foam / 3),
+            shoreWidth: Math.min(1.5, rules.foam * 0.35),
         },
-        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 }) {
+/**
+ * One authored water volume → a bounded, animated Ocean sheet at the box top, draped over the live
+ * terrain's depth: the carved lake bed (see `lakebedFromWaterVolumes`) gives every vertex a real
+ * water-column depth, which drives shallow→deep color, shore transparency/foam, and wave damping.
+ */
+function OneWater({ object, context }) {
     const resolved = useMemo(() => resolveWaterObject(object), [object]);
-    const config = useMemo(() => (resolved === null ? null : toOceanConfig(resolved.rules, resolved.size)), [resolved]);
+    const surfaceY = resolved === null ? 0 : resolved.center[1];
+    const centerX = resolved === null ? 0 : resolved.center[0];
+    const centerZ = resolved === null ? 0 : resolved.center[2];
+    const depthAt = useCallback((x, z) => surfaceY - context.field.sampleHeight(centerX + x, centerZ + z), [context.field, surfaceY, centerX, centerZ]);
+    const config = useMemo(() => {
+        if (resolved === null)
+            return null;
+        // Full deep color roughly where the carved bed bottoms out (box depth + undercut headroom).
+        const boxDepth = Math.max(0.4, resolved.center[1] - (object.center?.y ?? resolved.center[1]) + 0.001) * 2;
+        return toOceanConfig(resolved.rules, resolved.size, Math.max(0.8, boxDepth * 0.9));
+    }, [resolved, object]);
     if (resolved === null || config === null)
         return null;
-    return _jsx(Ocean, { config: config, position: [resolved.center[0], resolved.center[1], resolved.center[2]] });
+    return _jsx(Ocean, { config: config, position: [centerX, surfaceY, centerZ], depthAt: depthAt });
 }
 /** 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))) })));
+    registerSceneKindRenderer("water", ({ objects, context }) => (_jsx(_Fragment, { children: objects.map((object) => (_jsx(OneWater, { object: object, context: context }, object.id))) })));
 }

package/dist/scene/builtinSceneKindRenderers.js

@@ -9,6 +9,8 @@ import { registerBuiltinSceneKinds } from "@jgengine/core/scene/builtinSceneKind
 import { registerGrassFieldRenderer } from "./GrassFieldRenderer.js";
 import { registerWaterRenderer } from "./WaterRenderer.js";
 import { registerSoilPatchRenderer } from "./SoilPatchRenderer.js";
+import { registerCityRenderer } from "./CityRenderer.js";
+import { registerPoleLineRenderer } from "./PoleLineRenderer.js";
 let registered = false;
 /** Registers the engine's built-in environment scene-kind renderers. Called by `AuthoredScene`. @internal */
 export function registerBuiltinSceneKindRenderers() {
@@ -19,4 +21,6 @@ export function registerBuiltinSceneKindRenderers() {
     registerWaterRenderer();
     registerGrassFieldRenderer();
     registerSoilPatchRenderer();
+    registerCityRenderer();
+    registerPoleLineRenderer();
 }

package/dist/scene/cityWindowMaterial.d.ts

@@ -0,0 +1,16 @@
+import * as THREE from "three";
+/**
+ * Instanced facade material for city massing walls: a `MeshStandardMaterial` whose fragment stage
+ * paints procedural window strips on the side faces of every instanced unit box — floor bands from
+ * the district's real `floorHeight`, window columns on a fixed pitch, and a per-cell hash that
+ * dims/lights individual windows so no two facades read identical. Ground floors (plus any buried
+ * foundation, via the `instanceGroundOffset` attribute) stay solid wall so street level reads as
+ * storefront/lobby rather than floating glass. Same `onBeforeCompile` idiom as the grass/terrain
+ * materials; instance colors keep tinting the wall exactly like the plain massing material.
+ * @internal — created by `CityRenderer` for the banded-piece InstancedMesh.
+ */
+export declare function createCityWindowMaterial(options: {
+    floorHeight: number;
+    windowColor: string;
+    roughness?: number;
+}): THREE.MeshStandardMaterial;

package/dist/scene/cityWindowMaterial.js

@@ -0,0 +1,81 @@
+import * as THREE from "three";
+/**
+ * Instanced facade material for city massing walls: a `MeshStandardMaterial` whose fragment stage
+ * paints procedural window strips on the side faces of every instanced unit box — floor bands from
+ * the district's real `floorHeight`, window columns on a fixed pitch, and a per-cell hash that
+ * dims/lights individual windows so no two facades read identical. Ground floors (plus any buried
+ * foundation, via the `instanceGroundOffset` attribute) stay solid wall so street level reads as
+ * storefront/lobby rather than floating glass. Same `onBeforeCompile` idiom as the grass/terrain
+ * materials; instance colors keep tinting the wall exactly like the plain massing material.
+ * @internal — created by `CityRenderer` for the banded-piece InstancedMesh.
+ */
+export function createCityWindowMaterial(options) {
+    const material = new THREE.MeshStandardMaterial({
+        color: "#ffffff",
+        roughness: options.roughness ?? 0.82,
+        metalness: 0.04,
+    });
+    const uniforms = {
+        uFloorHeight: { value: Math.max(2, options.floorHeight) },
+        uWindowColor: { value: new THREE.Color(options.windowColor) },
+    };
+    material.onBeforeCompile = (shader) => {
+        Object.assign(shader.uniforms, uniforms);
+        shader.vertexShader = shader.vertexShader
+            .replace("#include <common>", `
+#include <common>
+attribute float instanceGroundOffset;
+varying vec3 vCityLocal;
+varying vec3 vCityScale;
+varying vec3 vCityNormal;
+varying float vCityGround;
+`)
+            .replace("#include <begin_vertex>", `
+#include <begin_vertex>
+vCityLocal = position;
+vCityScale = vec3(length(instanceMatrix[0].xyz), length(instanceMatrix[1].xyz), length(instanceMatrix[2].xyz));
+vCityNormal = normal;
+vCityGround = instanceGroundOffset;
+`);
+        shader.fragmentShader = shader.fragmentShader
+            .replace("#include <common>", `
+#include <common>
+uniform float uFloorHeight;
+uniform vec3 uWindowColor;
+varying vec3 vCityLocal;
+varying vec3 vCityScale;
+varying vec3 vCityNormal;
+varying float vCityGround;
+float cityHash(vec2 cell) {
+  return fract(sin(dot(cell, vec2(127.1, 311.7))) * 43758.5453);
+}
+`)
+            .replace("#include <color_fragment>", `
+#include <color_fragment>
+{
+  // Side faces only — roofs and undersides stay plain wall.
+  if (abs(vCityNormal.y) < 0.5) {
+    float along = abs(vCityNormal.x) > 0.5 ? (vCityLocal.z + 0.5) * vCityScale.z : (vCityLocal.x + 0.5) * vCityScale.x;
+    float faceWidth = abs(vCityNormal.x) > 0.5 ? vCityScale.z : vCityScale.x;
+    float up = (vCityLocal.y + 0.5) * vCityScale.y - vCityGround;
+    float pitch = 2.4;
+    float floorT = fract(up / uFloorHeight);
+    float colT = fract(along / pitch);
+    float floorIndex = floor(up / uFloorHeight);
+    float colIndex = floor(along / pitch);
+    bool window = up > uFloorHeight * 1.05 && floorT > 0.32 && floorT < 0.78 && colT > 0.2 && colT < 0.8
+      && along > 0.7 && along < faceWidth - 0.7;
+    if (window) {
+      float cell = cityHash(vec2(floorIndex, colIndex) + vec2(vCityScale.x, vCityScale.z));
+      vec3 pane = uWindowColor * mix(0.55, 1.25, cell);
+      diffuseColor.rgb = mix(diffuseColor.rgb, pane, 0.88);
+    }
+    // A thin darker plinth line right above grade grounds the facade.
+    if (up > 0.0 && up < 0.35) diffuseColor.rgb *= 0.8;
+  }
+}
+`);
+    };
+    material.customProgramCacheKey = () => `jgengine-city-windows`;
+    return material;
+}

package/dist/scene/sceneKindRenderers.d.ts

@@ -10,6 +10,8 @@ export interface SceneKindRenderContext {
     field: TerrainField;
     /** Catalog for kinds that instance real GLBs (pole assets, etc.). */
     assets?: AssetCatalog;
+    /** Terrain surface color at a world XZ — lets kind geometry (grass roots, soil borders) blend into the ground it sits on. */
+    groundColorAt?: (x: number, z: number) => string;
 }
 /** A registered renderer: given every document object of its kind, returns the render tree for them. */
 export type SceneKindRenderer = (props: {