@jgengine/shell 0.26.0 → 0.28.0

package/dist/settings/settingsController.js

@@ -2,6 +2,7 @@ import { actionLabel, bindingLabel } from "@jgengine/core/input/actionBindings";
 import { BUILT_IN_SETTING_CATEGORIES, busVolumeSettingId, DEFAULT_GRAPHICS_SHADOWS, DEFAULT_MASTER_VOLUME, DEFAULT_UI_SCALE, GRAPHICS_QUALITY_OPTIONS, SETTING_IDS, UI_SCALE_MAX, UI_SCALE_MIN, } from "@jgengine/core/settings/settingsModel";
 import { ANISOTROPY_OPTIONS, applyGraphicsQuality, GRAPHICS_POST_STAGE_LABELS, GRAPHICS_POST_STAGES, graphicsPostStageSettingId, readGraphicsSettings, RENDER_SCALE_MAX, RENDER_SCALE_MIN, RENDER_SCALE_STEP, } from "@jgengine/core/settings/graphicsSettings";
 import { FRAME_RATE_LIMIT_DISPLAY, FRAME_RATE_LIMIT_OPTIONS } from "@jgengine/core/settings/frameRateLimit";
+import { accessibilitySettingRows } from "@jgengine/core/settings/accessibilitySettings";
 import { DEFAULT_TOUCH_JOYSTICK_VARIANT, TOUCH_JOYSTICK_VARIANT_OPTIONS, TOUCH_STYLE_OPTIONS, } from "@jgengine/core/input/touchScheme";
 import { TOUCH_STYLE_AUTO, useSettingsRevision } from "./appliedSettings.js";
 import { useSettingsStore, } from "@jgengine/react/settings";
@@ -11,6 +12,7 @@ const DEFAULT_CATEGORY_LABELS = {
     graphics: "Graphics",
     gameplay: "Gameplay",
     controls: "Controls",
+    accessibility: "Accessibility",
 };
 const percent = (value) => `${Math.round(value * 100)}%`;
 const TOUCH_STYLE_SELECT_OPTIONS = [
@@ -195,6 +197,7 @@ export function useSettingsCategories(config) {
         graphics: graphicsRows,
         gameplay: gameplayRows,
         controls: controlsRows,
+        accessibility: accessibilitySettingRows(store),
     };
     const builtInKeybinds = { controls: keybinds };
     const declaredLabels = new Map(config.categories.map((c) => [c.id, c.label]));

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/StaticObjectModels.d.ts

@@ -1,6 +1,19 @@
 import { type ReactNode } from "react";
+import * as THREE from "three";
 import type { SceneObject } from "@jgengine/core/scene/objectStore";
 import { type StaticObjectBatch } from "./staticObjectBatches.js";
+/**
+ * Report what static object batching is doing to `debug_snapshot().systems`: the grouped batches, the
+ * total instances behind them, and how many instances survived per-instance culling this frame. A
+ * batch whose instances are all outside the view contributes a draw of zero, so `drawn` is the culling
+ * evidence, not a claim.
+ * @internal
+ */
+export declare function useStaticObjectBatchProbe(scene: THREE.Object3D, stats: {
+    batches: number;
+    instances: number;
+    singles: number;
+}): void;
 /** Render compatible authored or `scenery` props as shared model draws, preserving unsupported models. @internal */
 export declare function StaticObjectModels({ batch, single }: {
     batch: StaticObjectBatch;

package/dist/world/StaticObjectModels.js

@@ -1,21 +1,46 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useFrame, useLoader } from "@react-three/fiber";
-import { useEffect, useMemo, useRef, useState } from "react";
+import { useEffect, useMemo, useRef, useState, useCallback } from "react";
 import * as THREE from "three";
+import { devtools } from "@jgengine/core/devtools/devtools";
 import { useGameContext } from "@jgengine/react/provider";
 import { sharedGltfLoader } from "../render/modelLoad.js";
 import { IsolatedModelPart } from "../render/SceneModels.js";
+import { freezeStaticTransforms } from "../render/staticTransforms.js";
 import { measureLocalBounds, reportMeasuredBounds } from "../render/measureBounds.js";
 import { measureLocalCollisionTriangles, reportMeasuredCollisionMesh } from "../render/measureCollisionMesh.js";
 import { buildScatterModelSources, disposeScatterModelSources } from "../scatter/scatterModels.js";
 import { useRenderVisibility } from "../visibility/CullingProvider.js";
 import { CAMERA_POST_FRAME_PRIORITY } from "../camera/cameraRigs.js";
-import { canInstanceStaticScene, incompatibleStaticObjectIds, isCompatibleStaticObject, syncStaticObjectSource } from "./staticObjectBatches.js";
+import { canInstanceStaticScene, countStaticBatchDraws, incompatibleStaticObjectIds, isCompatibleStaticObject, STATIC_BATCH_MESH_KEY, syncStaticObjectSource } from "./staticObjectBatches.js";
+/**
+ * Report what static object batching is doing to `debug_snapshot().systems`: the grouped batches, the
+ * total instances behind them, and how many instances survived per-instance culling this frame. A
+ * batch whose instances are all outside the view contributes a draw of zero, so `drawn` is the culling
+ * evidence, not a claim.
+ * @internal
+ */
+export function useStaticObjectBatchProbe(scene, stats) {
+    const ref = useRef(stats);
+    ref.current = stats;
+    useEffect(() => devtools.probes.registerSystem("render/staticBatches", {
+        counters: () => ({ ...ref.current, ...countStaticBatchDraws(scene) }),
+        state: () => {
+            const { draws, drawn } = countStaticBatchDraws(scene);
+            return `${ref.current.batches} batches · ${draws} draws · ${drawn}/${ref.current.instances} instances drawn`;
+        },
+    }), [scene]);
+}
 function ObjectSource({ source, objects, batch }) {
     const ctx = useGameContext();
     const visibility = useRenderVisibility();
     const ref = useRef(null);
     const scratch = useMemo(() => new THREE.Object3D(), []);
+    const attach = useCallback((mesh) => {
+        ref.current = mesh;
+        if (mesh !== null)
+            freezeStaticTransforms(mesh);
+    }, []);
     useEffect(() => {
         const mesh = ref.current;
         return () => { mesh?.dispose(); };
@@ -28,7 +53,7 @@ function ObjectSource({ source, objects, batch }) {
                     isCompatibleStaticObject(object, batch.model, ctx.scene.object.catalog(id)) ? object : null;
             }, visibility.current, scratch);
     }, CAMERA_POST_FRAME_PRIORITY + 0.1);
-    return _jsx("instancedMesh", { ref: ref, args: [source.geometry, source.material, objects.length], castShadow: source.castShadow, receiveShadow: source.receiveShadow, dispose: null });
+    return _jsx("instancedMesh", { ref: attach, args: [source.geometry, source.material, objects.length], userData: { [STATIC_BATCH_MESH_KEY]: true }, castShadow: source.castShadow, receiveShadow: source.receiveShadow, dispose: null });
 }
 function LoadedStaticObjects({ batch, single }) {
     const ctx = useGameContext();

package/dist/world/WorldParticles.d.ts

@@ -11,8 +11,9 @@ export declare function transformParticleVector(point: Vec3, origin: Vec3, yaw:
 /** @internal Cosmetic catch-up follows game time, with bounded work after suspension. */
 export declare function resolveParticleDelta(previousTime: number, gameTime: number): number;
 /** Renders the existing director and pooled simulator; named bursts reuse the standing pool. @internal */
-export declare function WorldParticles({ quality, particleCap, diagnostics }: {
+export declare function WorldParticles({ quality, particleCap, particleBudget, diagnostics }: {
     quality: GraphicsQuality;
     particleCap?: number;
+    particleBudget?: number;
     diagnostics?: boolean;
 }): ReactElement;