@jgengine/shell 0.26.0 → 0.27.0

package/dist/scene/DecalRenderer.js

@@ -0,0 +1,74 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from "react";
+import * as THREE from "three";
+import { resolveDecalObject } from "@jgengine/core/world/decalKind";
+import { createDecalDrapeGeometry } from "../render/decalGeometry.js";
+import { createDecalTexture } from "../render/decalTexture.js";
+import { useDisposable } from "../render/useDisposable.js";
+import { registerSceneKindRenderer } from "./sceneKindRenderers.js";
+/** Tilts at or above this stand the decal up on a wall instead of draping it on the ground. */
+const WALL_TILT = 45;
+function dataTexture(style, seed) {
+    const baked = createDecalTexture(style, seed);
+    const texture = new THREE.DataTexture(baked.data, baked.size, baked.size, THREE.RGBAFormat, THREE.UnsignedByteType);
+    texture.colorSpace = THREE.SRGBColorSpace;
+    texture.magFilter = THREE.LinearFilter;
+    texture.minFilter = THREE.LinearMipmapLinearFilter;
+    texture.generateMipmaps = true;
+    texture.wrapS = THREE.ClampToEdgeWrapping;
+    texture.wrapT = THREE.ClampToEdgeWrapping;
+    texture.needsUpdate = true;
+    return texture;
+}
+function OneDecal({ object, context }) {
+    const resolved = useMemo(() => resolveDecalObject(object), [object]);
+    const rules = resolved?.rules;
+    const style = rules?.style ?? "dirt";
+    const seed = rules?.seed ?? "";
+    const texture = useDisposable(() => dataTexture(style, seed), [style, seed]);
+    const wall = (rules?.tilt ?? 0) >= WALL_TILT;
+    const geometry = useDisposable(() => {
+        if (resolved === null || rules === undefined)
+            return new THREE.BufferGeometry();
+        if (wall)
+            return new THREE.PlaneGeometry(rules.size, rules.size);
+        const draped = createDecalDrapeGeometry({
+            size: rules.size,
+            rotationY: resolved.rotationY,
+            heightAt: context.field.sampleHeight,
+            lift: rules.lift,
+        });
+        const next = new THREE.BufferGeometry();
+        next.setAttribute("position", new THREE.BufferAttribute(draped.positions, 3));
+        next.setAttribute("normal", new THREE.BufferAttribute(draped.normals, 3));
+        next.setAttribute("uv", new THREE.BufferAttribute(draped.uvs, 2));
+        next.setIndex(new THREE.BufferAttribute(draped.indices, 1));
+        next.computeBoundingSphere();
+        return next;
+    }, [resolved, rules, wall, context.field]);
+    const material = useDisposable(() => new THREE.MeshStandardMaterial({
+        map: texture,
+        transparent: true,
+        depthWrite: false,
+        opacity: rules?.opacity ?? 1,
+        roughness: 0.92,
+        metalness: 0,
+        polygonOffset: true,
+        polygonOffsetFactor: -4,
+        polygonOffsetUnits: -4,
+    }), [texture, rules?.opacity]);
+    if (resolved === null || rules === undefined)
+        return null;
+    const [px, py, pz] = resolved.position;
+    if (!wall) {
+        return _jsx("mesh", { geometry: geometry, material: material, position: [px, py, pz], receiveShadow: true, frustumCulled: true });
+    }
+    // A standing decal is pushed out along its own normal so it clears the wall it describes.
+    const normalX = Math.sin(resolved.rotationY);
+    const normalZ = Math.cos(resolved.rotationY);
+    return (_jsx("mesh", { geometry: geometry, material: material, position: [px + normalX * rules.offset, py + rules.lift, pz + normalZ * rules.offset], rotation: [THREE.MathUtils.degToRad(rules.tilt - 90), resolved.rotationY, 0], receiveShadow: true, frustumCulled: true }));
+}
+/** Registers the `decal` marker renderer. Called by `registerBuiltinSceneKindRenderers`. @internal */
+export function registerDecalRenderer() {
+    registerSceneKindRenderer("decal", ({ objects, context }) => (_jsx(_Fragment, { children: objects.map((object) => (_jsx(OneDecal, { object: object, context: context }, object.id))) })));
+}

package/dist/scene/GrassFieldRenderer.js

@@ -1,9 +1,10 @@
-import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useMemo } from "react";
 import { resolveGrassObject } from "@jgengine/core/world/grassKind";
 import { clearanceMasksFrom, DEFAULT_CLEARANCE_KINDS } from "@jgengine/core/world/scatterRegion";
 import { masksInfluence } from "@jgengine/core/world/geometry";
 import { GrassField } from "../terrain/GrassField.js";
+import { GrassCover } from "../terrain/GrassCover.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"]);
@@ -86,7 +87,7 @@ function OneGrass({ object, context }) {
     // footprint, and the fade only thins how many *draw* at range in the vertex shader — so a deeper
     // meadow reads expansive without raising the instance ceiling.
     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, bladeWidth: bladeWidth, bladeBend: bladeBend, tuftRadius: rules.tuftRadius, normalLift: rules.normalLift, 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, coverageAt: coverageAt, wind: wind, edgeFeather: 2.2, exclude: exclude }));
+    return (_jsxs(_Fragment, { children: [_jsx(GrassCover, { position: [center[0], center[1], center[2]], area: area, seed: hashSeed(rules.seed.length > 0 ? rules.seed : object.id), colorBase: rules.colorBase, colorTip: rules.colorTip, strength: rules.groundCover, edgeFeather: 2.2, heightAt: heightAt, coverageAt: coverageAt }), _jsx(GrassField, { position: [center[0], center[1], center[2]], area: area, count: instanceCount, density: rules.density, bladeHeight: bladeHeight, bladeWidth: bladeWidth, bladeBend: bladeBend, tuftRadius: rules.tuftRadius, normalLift: rules.normalLift, 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, coverageAt: coverageAt, wind: wind, edgeFeather: 2.2, exclude: exclude })] }));
 }
 /** Registers the `grass_field` volume renderer. Called by `registerBuiltinSceneKindRenderers`. @internal */
 export function registerGrassFieldRenderer() {

package/dist/scene/builtinSceneKindRenderers.js

@@ -11,6 +11,7 @@ import { registerWaterRenderer } from "./WaterRenderer.js";
 import { registerSoilPatchRenderer } from "./SoilPatchRenderer.js";
 import { registerCityRenderer } from "./CityRenderer.js";
 import { registerPoleLineRenderer } from "./PoleLineRenderer.js";
+import { registerDecalRenderer } from "./DecalRenderer.js";
 let registered = false;
 /** Registers the engine's built-in environment scene-kind renderers. Called by `AuthoredScene`. @internal */
 export function registerBuiltinSceneKindRenderers() {
@@ -23,4 +24,5 @@ export function registerBuiltinSceneKindRenderers() {
     registerSoilPatchRenderer();
     registerCityRenderer();
     registerPoleLineRenderer();
+    registerDecalRenderer();
 }

package/dist/terrain/GrassCover.d.ts

@@ -0,0 +1,21 @@
+import * as THREE from "three";
+import type { TerrainHeightSampler } from "./terrainMath.js";
+/** Props for {@link GrassCover}: one authored patch's footprint, colours and drape samplers. */
+export interface GrassCoverProps {
+    area: readonly [number, number];
+    seed: number;
+    colorBase: THREE.ColorRepresentation;
+    colorTip: THREE.ColorRepresentation;
+    strength: number;
+    edgeFeather: number;
+    heightAt: TerrainHeightSampler;
+    coverageAt: TerrainHeightSampler;
+    segments?: number;
+    position?: readonly [number, number, number];
+}
+/**
+ * The turf surface under one authored `grass_field` patch: a ground-draped, edge-feathered mat that
+ * turns a bare pavement footprint into grass the blade field stands in. Bounded to one draw and a
+ * {@link GRASS_COVER_MAX_SEGMENTS}² grid, so a large park still costs a single mesh.
+ */
+export declare function GrassCover({ area, seed, colorBase, colorTip, strength, edgeFeather, heightAt, coverageAt, segments, position, }: GrassCoverProps): import("react").JSX.Element | null;

package/dist/terrain/GrassCover.js

@@ -0,0 +1,84 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as THREE from "three";
+import { useDisposable } from "../render/useDisposable.js";
+import { createGrassCoverGeometry, GRASS_COVER_MAX_SEGMENTS } from "./grassCoverGeometry.js";
+let grainTexture = null;
+/**
+ * Tileable thatch grain for the cover mat (luminance around 0.9), generated once from a hash — no
+ * asset pull, deterministic, and cheap enough that a 96² mat still reads as grass up close.
+ */
+function coverGrain() {
+    if (grainTexture !== null)
+        return grainTexture;
+    const size = 64;
+    const data = new Uint8Array(size * size * 4);
+    const hash = (x, y) => {
+        let h = Math.imul(x + 1, 374761393) ^ Math.imul(y + 1, 668265263) ^ 0x9e3779b9;
+        h = Math.imul(h ^ (h >>> 13), 1274126177);
+        return ((h ^ (h >>> 16)) >>> 0) / 4294967296;
+    };
+    for (let y = 0; y < size; y += 1) {
+        for (let x = 0; x < size; x += 1) {
+            const fine = (hash(x, y) + hash((x + 32) % size, (y + 17) % size)) * 0.5;
+            const clump = (hash((x >> 2) * 3, (y >> 2) * 5) + hash(((x >> 2) + 7) % 16, ((y >> 2) + 3) % 16)) * 0.5;
+            const value = Math.max(180, Math.min(255, Math.round(232 + (fine - 0.5) * 46 + (clump - 0.5) * 30)));
+            const i = (y * size + x) * 4;
+            data[i] = value;
+            data[i + 1] = value;
+            data[i + 2] = value;
+            data[i + 3] = 255;
+        }
+    }
+    grainTexture = new THREE.DataTexture(data, size, size, THREE.RGBAFormat, THREE.UnsignedByteType);
+    grainTexture.wrapS = THREE.RepeatWrapping;
+    grainTexture.wrapT = THREE.RepeatWrapping;
+    grainTexture.magFilter = THREE.LinearFilter;
+    grainTexture.minFilter = THREE.LinearMipmapLinearFilter;
+    grainTexture.generateMipmaps = true;
+    grainTexture.needsUpdate = true;
+    return grainTexture;
+}
+/**
+ * The turf surface under one authored `grass_field` patch: a ground-draped, edge-feathered mat that
+ * turns a bare pavement footprint into grass the blade field stands in. Bounded to one draw and a
+ * {@link GRASS_COVER_MAX_SEGMENTS}² grid, so a large park still costs a single mesh.
+ */
+export function GrassCover({ area, seed, colorBase, colorTip, strength, edgeFeather, heightAt, coverageAt, segments, position, }) {
+    const geometry = useDisposable(() => {
+        const baked = createGrassCoverGeometry({
+            area,
+            seed,
+            colorBase,
+            colorTip,
+            strength,
+            edgeFeather,
+            heightAt,
+            coverageAt,
+            ...(segments === undefined ? {} : { segments }),
+        });
+        const next = new THREE.BufferGeometry();
+        if (baked.positions.length === 0)
+            return next;
+        next.setAttribute("position", new THREE.BufferAttribute(baked.positions, 3));
+        next.setAttribute("normal", new THREE.BufferAttribute(baked.normals, 3));
+        next.setAttribute("color", new THREE.BufferAttribute(baked.colors, 4));
+        next.setAttribute("uv", new THREE.BufferAttribute(baked.uvs, 2));
+        next.setIndex(new THREE.BufferAttribute(baked.indices, 1));
+        next.computeBoundingSphere();
+        return next;
+    }, [area, seed, colorBase, colorTip, strength, edgeFeather, heightAt, coverageAt, segments]);
+    const material = useDisposable(() => new THREE.MeshStandardMaterial({
+        map: coverGrain(),
+        vertexColors: true,
+        transparent: true,
+        depthWrite: false,
+        roughness: 0.96,
+        metalness: 0,
+        polygonOffset: true,
+        polygonOffsetFactor: -1,
+        polygonOffsetUnits: -1,
+    }), []);
+    if (strength <= 0)
+        return null;
+    return (_jsx("mesh", { geometry: geometry, material: material, receiveShadow: true, frustumCulled: true, ...(position === undefined ? {} : { position: [position[0], position[1], position[2]] }) }));
+}

package/dist/terrain/grassCoverGeometry.d.ts

@@ -0,0 +1,40 @@
+import * as THREE from "three";
+import { type TerrainArea, type TerrainHeightSampler } from "./terrainMath.js";
+/** World metres one cover-texture tile spans; the mat's own grain is sampled in world space. */
+export declare const GRASS_COVER_TILE_METRES = 3;
+/** Largest grid a cover mat bakes to, per axis — a 66 m park stays one draw at ~1 m cells. */
+export declare const GRASS_COVER_MAX_SEGMENTS = 96;
+/** Inputs for {@link createGrassCoverGeometry}. */
+export interface GrassCoverGeometryOptions {
+    area: TerrainArea;
+    seed: number;
+    colorBase: THREE.ColorRepresentation;
+    colorTip: THREE.ColorRepresentation;
+    /** Ground-cover mat strength 0..1 (the authored `groundCover`); 0 produces no geometry. */
+    strength: number;
+    /** Meters of soft fringe at the patch border, matching the blade field's own feather. */
+    edgeFeather: number;
+    heightAt: TerrainHeightSampler;
+    coverageAt: TerrainHeightSampler;
+    /** Lift above the ground in meters so the mat never z-fights the terrain. Default 0.035. */
+    lift?: number;
+    /** Grid segments per axis; defaults to one per 2 m, clamped to {@link GRASS_COVER_MAX_SEGMENTS}. */
+    segments?: number;
+}
+/** Bake result for {@link createGrassCoverGeometry}; empty arrays when the mat is switched off. */
+export interface GrassCoverGeometry {
+    positions: Float32Array;
+    normals: Float32Array;
+    colors: Float32Array;
+    uvs: Float32Array;
+    indices: Uint32Array;
+    size: readonly [number, number];
+}
+/**
+ * Drapes an authored `grass_field` volume's footprint with a feathered turf mat: vertices follow the
+ * runtime ground, the patch edge fades out over `edgeFeather`, and authored clearance masks punch
+ * the cover back out where a path or footing crosses it. This is the surface under the blades, so a
+ * park reads as grass instead of bare pavement with stubble on it.
+ * @internal
+ */
+export declare function createGrassCoverGeometry(options: GrassCoverGeometryOptions): GrassCoverGeometry;

package/dist/terrain/grassCoverGeometry.js

@@ -0,0 +1,112 @@
+import * as THREE from "three";
+import { resolveTerrainSize } from "./terrainMath.js";
+/** World metres one cover-texture tile spans; the mat's own grain is sampled in world space. */
+export const GRASS_COVER_TILE_METRES = 3;
+/** Largest grid a cover mat bakes to, per axis — a 66 m park stays one draw at ~1 m cells. */
+export const GRASS_COVER_MAX_SEGMENTS = 96;
+function hash2(x, z, seed) {
+    let h = Math.imul(x | 0, 374761393) ^ Math.imul(z | 0, 668265263) ^ Math.imul(seed | 0, 2246822519);
+    h = Math.imul(h ^ (h >>> 13), 1274126177);
+    return ((h ^ (h >>> 16)) >>> 0) / 4294967296;
+}
+function smooth(t) {
+    return t * t * (3 - 2 * t);
+}
+/** Bilinear value noise in world space; deterministic per seed, no allocation on the hot path. */
+function valueNoise(x, z, seed) {
+    const xi = Math.floor(x);
+    const zi = Math.floor(z);
+    const tx = smooth(x - xi);
+    const tz = smooth(z - zi);
+    const a = hash2(xi, zi, seed);
+    const b = hash2(xi + 1, zi, seed);
+    const c = hash2(xi, zi + 1, seed);
+    const d = hash2(xi + 1, zi + 1, seed);
+    return (a + (b - a) * tx) * (1 - tz) + (c + (d - c) * tx) * tz;
+}
+/**
+ * Drapes an authored `grass_field` volume's footprint with a feathered turf mat: vertices follow the
+ * runtime ground, the patch edge fades out over `edgeFeather`, and authored clearance masks punch
+ * the cover back out where a path or footing crosses it. This is the surface under the blades, so a
+ * park reads as grass instead of bare pavement with stubble on it.
+ * @internal
+ */
+export function createGrassCoverGeometry(options) {
+    const size = resolveTerrainSize(options.area);
+    const segments = Math.max(1, Math.min(GRASS_COVER_MAX_SEGMENTS, Math.floor(options.segments ?? Math.min(GRASS_COVER_MAX_SEGMENTS, Math.max(2, Math.round(Math.max(size.width, size.depth) / 2))))));
+    if (options.strength <= 0 || size.width <= 0 || size.depth <= 0) {
+        return { positions: new Float32Array(), normals: new Float32Array(), colors: new Float32Array(), uvs: new Float32Array(), indices: new Uint32Array(), size: [size.width, size.depth] };
+    }
+    const lift = options.lift ?? 0.035;
+    const halfW = size.width / 2;
+    const halfD = size.depth / 2;
+    const base = new THREE.Color(options.colorBase);
+    const tip = new THREE.Color(options.colorTip);
+    const root = base.clone().multiplyScalar(0.55);
+    const sheen = base.clone().multiplyScalar(0.98);
+    const cols = segments + 1;
+    const count = cols * cols;
+    const positions = new Float32Array(count * 3);
+    const normals = new Float32Array(count * 3);
+    const colors = new Float32Array(count * 4);
+    const uvs = new Float32Array(count * 2);
+    const eps = Math.max(0.25, Math.min(size.width, size.depth) / segments / 2);
+    for (let iz = 0; iz < cols; iz += 1) {
+        const z = -halfD + (iz / segments) * size.depth;
+        for (let ix = 0; ix < cols; ix += 1) {
+            const x = -halfW + (ix / segments) * size.width;
+            const index = iz * cols + ix;
+            positions[index * 3] = x;
+            positions[index * 3 + 1] = options.heightAt(x, z) + lift;
+            positions[index * 3 + 2] = z;
+            const hL = options.heightAt(x - eps, z);
+            const hR = options.heightAt(x + eps, z);
+            const hD = options.heightAt(x, z - eps);
+            const hU = options.heightAt(x, z + eps);
+            const nx = hL - hR;
+            const nz = hD - hU;
+            const ny = 2 * eps;
+            const length = Math.hypot(nx, ny, nz) || 1;
+            normals[index * 3] = nx / length;
+            normals[index * 3 + 1] = ny / length;
+            normals[index * 3 + 2] = nz / length;
+            const edge = Math.min(halfW - Math.abs(x), halfD - Math.abs(z));
+            const feather = Math.max(0.001, options.edgeFeather);
+            const edgeFade = smooth(Math.min(1, Math.max(0, edge / feather)));
+            const coverage = Math.max(0, Math.min(1, options.coverageAt(x, z)));
+            const grain = valueNoise(x / 1.7, z / 1.7, options.seed);
+            const patch = valueNoise(x / 11 + 31.7, z / 11 - 9.2, options.seed + 17);
+            const alpha = options.strength * edgeFade * coverage * (0.82 + 0.18 * grain);
+            // Macro patches lift the mat toward the blade tip hue and back to a rooted shade, so a park
+            // reads as turf with light and dry pockets instead of one flat green sheet.
+            const light = smooth(Math.min(1, Math.max(0, (patch - 0.25) / 0.6)));
+            const r = root.r + (sheen.r - root.r) * light;
+            const g = root.g + (sheen.g - root.g) * light;
+            const b = root.b + (sheen.b - root.b) * light;
+            const tipMix = grain * 0.3;
+            colors[index * 4] = r + (tip.r - r) * tipMix;
+            colors[index * 4 + 1] = g + (tip.g - g) * tipMix;
+            colors[index * 4 + 2] = b + (tip.b - b) * tipMix;
+            colors[index * 4 + 3] = alpha;
+            uvs[index * 2] = x / GRASS_COVER_TILE_METRES;
+            uvs[index * 2 + 1] = z / GRASS_COVER_TILE_METRES;
+        }
+    }
+    const indices = new Uint32Array(segments * segments * 6);
+    let cursor = 0;
+    for (let iz = 0; iz < segments; iz += 1) {
+        for (let ix = 0; ix < segments; ix += 1) {
+            const a = iz * cols + ix;
+            const b = a + 1;
+            const c = a + cols;
+            const d = c + 1;
+            indices[cursor++] = a;
+            indices[cursor++] = c;
+            indices[cursor++] = b;
+            indices[cursor++] = b;
+            indices[cursor++] = c;
+            indices[cursor++] = d;
+        }
+    }
+    return { positions, normals, colors, uvs, indices, size: [size.width, size.depth] };
+}

package/dist/terrain/terrainDetailMaterial.d.ts

@@ -34,9 +34,21 @@ export interface TerrainDetailMaterialOptions {
     classMask?: number;
     /** Initial editor relief-contour strength. Default 0. */
     contour?: number;
+    /**
+     * Per-painted-slot scanned color maps (slot 1 first), each with its own world tile metres. Layers
+     * without a map (or beyond {@link MAX_TERRAIN_LAYER_MAPS}) keep the procedural surface response.
+     */
+    layerMaps?: readonly (TerrainLayerMap | undefined)[];
 }
 /** Compile every surface response, for an editor viewport whose paint can change to any surface. */
 export declare const ALL_TERRAIN_SURFACE_CLASSES = 511;
+/** One painted layer's scanned color map plus the world metres one tile covers. */
+export interface TerrainLayerMap {
+    color: THREE.Texture;
+    tileMetres: number;
+}
+/** At most this many painted layers sample their own scanned map; extra layers keep procedural shading. */
+export declare const MAX_TERRAIN_LAYER_MAPS = 4;
 /**
  * A `MeshStandardMaterial` that renders terrain as ground rather than flat colour. Each painted
  * layer draws its surface type's procedural response (grass clumps and blades, dirt clods and

package/dist/terrain/terrainDetailMaterial.js

@@ -1,10 +1,38 @@
 import * as THREE from "three";
 import { NOISE_GLSL, PAINT_PARS_GLSL, SURFACE_BUMP_NORMAL_GLSL, SURFACE_FUNCTIONS_GLSL } from "./terrainSurfaceShader.js";
+let placeholder;
+function placeholderTexture() {
+    if (placeholder !== undefined)
+        return placeholder;
+    placeholder = new THREE.DataTexture(new Uint8Array([255, 255, 255, 255]), 1, 1, THREE.RGBAFormat);
+    placeholder.needsUpdate = true;
+    return placeholder;
+}
 const ROCK_CLASS_BIT = 1 << 4;
 /** Compile every surface response, for an editor viewport whose paint can change to any surface. */
 export const ALL_TERRAIN_SURFACE_CLASSES = 0x1ff;
+/** At most this many painted layers sample their own scanned map; extra layers keep procedural shading. */
+export const MAX_TERRAIN_LAYER_MAPS = 4;
 // Slot 0 is the unpainted base, 1–8 the paint layers, 9 slope rock.
 const SLOT_GLSL = /* glsl */ `
+#ifdef JG_TERRAIN_LAYER_MAPS
+uniform sampler2D uLayerMap1;
+uniform sampler2D uLayerMap2;
+uniform sampler2D uLayerMap3;
+uniform sampler2D uLayerMap4;
+uniform float uLayerTile1;
+uniform float uLayerTile2;
+uniform float uLayerTile3;
+uniform float uLayerTile4;
+vec3 jgLayerMap(int slot, vec3 wp, out bool has) {
+  has = false;
+  if (slot == 1) { if (uLayerTile1 > 0.0) { has = true; return texture2D(uLayerMap1, wp.xz / uLayerTile1).rgb; } }
+  else if (slot == 2) { if (uLayerTile2 > 0.0) { has = true; return texture2D(uLayerMap2, wp.xz / uLayerTile2).rgb; } }
+  else if (slot == 3) { if (uLayerTile3 > 0.0) { has = true; return texture2D(uLayerMap3, wp.xz / uLayerTile3).rgb; } }
+  else if (slot == 4) { if (uLayerTile4 > 0.0) { has = true; return texture2D(uLayerMap4, wp.xz / uLayerTile4).rgb; } }
+  return vec3(0.0);
+}
+#endif
 JgSurf jgSlot(int slot, vec3 baseTone, vec3 wp){
   vec3 jgFlatC = baseTone;
   JgSurf s;
@@ -22,6 +50,15 @@ JgSurf jgSlot(int slot, vec3 baseTone, vec3 wp){
   else {
     s = jgSurface(0, baseTone, roughness, 1.0, wp);
   }
+#ifdef JG_TERRAIN_LAYER_MAPS
+  if (slot > 0 && slot <= 4) {
+    bool jgHasMap;
+    vec3 jgMapped = jgLayerMap(slot, wp, jgHasMap);
+    // The layer owns its own scan: grain, colour and all, tiled at its authored metres, and the
+    // mask weights decide how much of it shows against the neighbour layer.
+    if (jgHasMap) s.albedo = mix(s.albedo, jgMapped, 0.92);
+  }
+#endif
   s.albedo = mix(jgFlatC, s.albedo, uSurface);
   s.height *= uSurface;
   s.bump *= uSurface;
@@ -48,6 +85,20 @@ export function createTerrainDetailMaterial(detail, textures, options = {}) {
     const strength = detail.material?.strength ?? 1;
     const tint = detail.material?.tint ?? 1;
     const paint = options.paint;
+    const layerMaps = (options.layerMaps ?? []).slice(0, MAX_TERRAIN_LAYER_MAPS);
+    const hasLayerMaps = layerMaps.some((entry) => entry !== undefined);
+    const layerMapUniforms = hasLayerMaps
+        ? {
+            uLayerMap1: { value: layerMaps[0]?.color ?? placeholderTexture() },
+            uLayerMap2: { value: layerMaps[1]?.color ?? placeholderTexture() },
+            uLayerMap3: { value: layerMaps[2]?.color ?? placeholderTexture() },
+            uLayerMap4: { value: layerMaps[3]?.color ?? placeholderTexture() },
+            uLayerTile1: { value: layerMaps[0]?.tileMetres ?? 0 },
+            uLayerTile2: { value: layerMaps[1]?.tileMetres ?? 0 },
+            uLayerTile3: { value: layerMaps[2]?.tileMetres ?? 0 },
+            uLayerTile4: { value: layerMaps[3]?.tileMetres ?? 0 },
+        }
+        : {};
     const low = options.quality === "low";
     const contour = { value: options.contour ?? 0 };
     // Rock is always compiled for slope rock; each extra class costs shader time even where unused on
@@ -68,6 +119,7 @@ export function createTerrainDetailMaterial(detail, textures, options = {}) {
         uSurface: { value: detail.surfaceStrength },
         uContour: contour,
         ...(paint === undefined ? {} : paint.uniforms),
+        ...layerMapUniforms,
         ...(hasTexture
             ? {
                 uMatColor: { value: textures.color },
@@ -88,6 +140,7 @@ export function createTerrainDetailMaterial(detail, textures, options = {}) {
     });
     material.defines = {
         ...(paint === undefined ? {} : { JG_TERRAIN_PAINT: "" }),
+        ...(hasLayerMaps ? { JG_TERRAIN_LAYER_MAPS: "" } : {}),
         ...(low ? { JG_SURFACE_LOW: "" } : {}),
         JG_SURFACE_CLASSES: String(classMask),
     };
@@ -264,6 +317,6 @@ ${materialNormalGlsl}`)
             .replace("#include <aomap_fragment>", `#include <aomap_fragment>
 ${materialAoGlsl}`);
     };
-    material.customProgramCacheKey = () => `jgengine-terrain-detail-${hasTexture ? "tex" : "flat"}-${hasTexture && textures.roughness !== undefined ? "rough" : "scalar"}-${hasTexture && textures.ao !== undefined ? "ao" : "unoccluded"}-${paint === undefined ? "bare" : "paint"}-${low ? "low" : "full"}-${classMask}`;
+    material.customProgramCacheKey = () => `jgengine-terrain-detail-${hasTexture ? "tex" : "flat"}-${hasTexture && textures.roughness !== undefined ? "rough" : "scalar"}-${hasTexture && textures.ao !== undefined ? "ao" : "unoccluded"}-${paint === undefined ? "bare" : "paint"}-${hasLayerMaps ? "layers" : "procedural"}-${low ? "low" : "full"}-${classMask}`;
     return { material, contour };
 }

package/dist/terrain/terrainSurfaces.d.ts

@@ -21,6 +21,10 @@ export interface TerrainPaintSlot {
     roughness: number;
     /** Pattern frequency multiplier from the layer's authored `tiling`. */
     scale: number;
+    /** World metres per texture repeat for this layer's scanned color map; 0 when the layer has no map. */
+    tileMetres: number;
+    /** Resolved color-map URL the slot's scanned texture comes from, if any. */
+    materialUrl?: string;
 }
 /** Per-cell paint coverage packed for the shader: two RGBA8 planes holding up to eight layer weights. */
 export interface TerrainPaintWeights {
@@ -50,6 +54,8 @@ export interface TerrainPaintTextures {
     readonly classMask: number;
     /** Re-upload coverage and layer slots; reallocates only when the cell grid size changes. */
     update(weights: TerrainPaintWeights): void;
+    /** The slot table the current coverage was packed from (layer materials, tile metres, classes). */
+    readonly slots: readonly TerrainPaintSlot[];
     dispose(): void;
 }
 /**

package/dist/terrain/terrainSurfaces.js

@@ -53,6 +53,8 @@ function slotFor(surface, layer) {
         classIndex: CLASS_INDEX[surfaceClass],
         roughness: layer?.roughness ?? CLASS_ROUGHNESS[surfaceClass],
         scale: tiling === undefined || tiling <= 0 ? 1 : Math.min(2, Math.max(0.5, CLASS_TILING[surfaceClass] / tiling)),
+        tileMetres: layer?.materialUrl === undefined ? 0 : tiling !== undefined && tiling > 0 ? tiling : 6,
+        ...(layer?.materialUrl === undefined ? {} : { materialUrl: layer.materialUrl }),
     };
 }
 /**
@@ -145,6 +147,7 @@ export function createTerrainPaintTextures(weights) {
     const classes = new Float32Array(MAX_TERRAIN_PAINT_LAYERS);
     const roughness = new Float32Array(MAX_TERRAIN_PAINT_LAYERS);
     const scales = new Float32Array(MAX_TERRAIN_PAINT_LAYERS);
+    const tiles = new Float32Array(MAX_TERRAIN_PAINT_LAYERS);
     const uniforms = {
         uPaintA: { value: coverageTexture(weights.planes[0], weights.cols, weights.rows) },
         uPaintB: { value: coverageTexture(weights.planes[1], weights.cols, weights.rows) },
@@ -156,9 +159,12 @@ export function createTerrainPaintTextures(weights) {
         uLayerClass: { value: classes },
         uLayerRough: { value: roughness },
         uLayerScale: { value: scales },
+        uLayerTile: { value: tiles },
     };
     let classMask = 0;
+    let slots = weights.slots;
     const update = (next) => {
+        slots = next.slots;
         classMask = next.slots.reduce((mask, slot) => mask | (1 << slot.classIndex), 0);
         for (const [key, plane] of [["uPaintA", next.planes[0]], ["uPaintB", next.planes[1]]]) {
             const current = uniforms[key].value;
@@ -182,6 +188,7 @@ export function createTerrainPaintTextures(weights) {
             classes[i] = slot?.classIndex ?? 0;
             roughness[i] = slot?.roughness ?? 0.9;
             scales[i] = slot?.scale ?? 1;
+            tiles[i] = slot?.tileMetres ?? 0;
         }
     };
     update(weights);
@@ -190,6 +197,9 @@ export function createTerrainPaintTextures(weights) {
         get classMask() {
             return classMask;
         },
+        get slots() {
+            return slots;
+        },
         update,
         dispose: () => {
             uniforms.uPaintA.value.dispose();

package/dist/world/WorldScene.js

@@ -17,6 +17,7 @@ import { useSceneEntityIds, useSceneObjectIds, useGameStore, usePlayer, useTarge
 import { colorFromId } from "../worldSky.js";
 import { DefaultSurface, detailMaps } from "../render/defaultSurface.js";
 import { useDisposable } from "../render/useDisposable.js";
+import { WindClock } from "../render/modelWind.js";
 import { MeasuredBoundsGroup } from "../render/measureBounds.js";
 import { EntitySprite, IsolatedEntityModel } from "../render/SceneModels.js";
 import { resolveEntityModel, resolveObjectModel } from "../render/resolveModel.js";
@@ -202,7 +203,7 @@ function WorldActors({ entitySprites, entityModels, objectModels, objectStyles,
             }), grouped.singles.map((candidate) => renderSingle(candidate.object)), grouped.batches.map((batch) => _jsx(StaticObjectModels, { batch: batch, single: renderSingle }, batch.key))] }));
 }
 export function WorldView({ entitySprites, entityModels, objectModels, objectStyles, environment, assets, renderEntity, renderObject, selectedIds, hideLocalActor, editorLayers, }) {
-    return (_jsxs(_Fragment, { children: [_jsx(WorldEnvironment, { environment: environment }), _jsx(WorldActors, { entitySprites: entitySprites, entityModels: entityModels, objectModels: objectModels, objectStyles: objectStyles, assets: assets, renderEntity: renderEntity, renderObject: renderObject, selectedIds: selectedIds, hideLocalActor: hideLocalActor, editorLayers: editorLayers })] }));
+    return (_jsxs(_Fragment, { children: [_jsx(WindClock, {}), _jsx(WorldEnvironment, { environment: environment }), _jsx(WorldActors, { entitySprites: entitySprites, entityModels: entityModels, objectModels: objectModels, objectStyles: objectStyles, assets: assets, renderEntity: renderEntity, renderObject: renderObject, selectedIds: selectedIds, hideLocalActor: hideLocalActor, editorLayers: editorLayers })] }));
 }
 export function RemotePlayers({ rows, presenceInterpolationMs = 100 }) {
     const groups = useRef(new Map());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/shell",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Game player shell for JGengine: React Three Fiber canvas, orbit camera, input tracking, HUD mounting, GameUiPreview, and a demo game. Consumers supply a GameRegistry.",
   "license": "Apache-2.0",
   "type": "module",
@@ -35,9 +35,9 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.26.0",
-    "@jgengine/react": "^0.26.0",
-    "@jgengine/ws": "^0.26.0"
+    "@jgengine/core": "^0.27.0",
+    "@jgengine/react": "^0.27.0",
+    "@jgengine/ws": "^0.27.0"
   },
   "peerDependencies": {
     "@react-three/drei": "^10.0.0",

package/skills/jgengine/api.md

@@ -6,7 +6,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.26.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.27.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -285,7 +285,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.26.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.27.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter