@jgengine/shell 0.21.0 → 0.23.0

package/dist/terrain/terrainSurfaceShader.js

@@ -0,0 +1,266 @@
+/** Integer-hash value noise (`jgHashUint`, `jgVNoise`, `jgFbm`) every surface chunk builds on. */
+export const NOISE_GLSL = /* glsl */ `
+uint jgHashUint(uvec2 v){
+  uint x = v.x * 1664525u + v.y * 1013904223u;
+  x = (x ^ (x >> 16u)) * 2246822519u;
+  x = (x ^ (x >> 13u)) * 3266489917u;
+  x = x ^ (x >> 16u);
+  return x;
+}
+float jgHash(vec2 p){
+  ivec2 i = ivec2(floor(p));
+  return float(jgHashUint(uvec2(i))) * (1.0 / 4294967296.0);
+}
+float jgVNoise(vec2 p){
+  vec2 i = floor(p); vec2 f = fract(p);
+  vec2 u = f * f * (3.0 - 2.0 * f);
+  float a = jgHash(i);
+  float b = jgHash(i + vec2(1.0, 0.0));
+  float c = jgHash(i + vec2(0.0, 1.0));
+  float d = jgHash(i + vec2(1.0, 1.0));
+  return mix(mix(a, b, u.x), mix(c, d, u.x), u.y);
+}
+float jgFbm(vec2 p){
+  float v = 0.0; float amp = 0.5;
+  for (int i = 0; i < 4; i++){ v += amp * jgVNoise(p); p *= 2.0; amp *= 0.5; }
+  return v;
+}
+`;
+/**
+ * GLSL for the terrain surface pass: per-surface procedural ground (grass, dirt, gravel, rock, sand,
+ * mud, snow, road) and the height-aware blend between painted layers. Needs `NOISE_GLSL` first.
+ * Every octave is gated by `jgBand(frequency)` so detail finer than a pixel fades to its mean
+ * instead of shimmering at distance.
+ */
+export const SURFACE_FUNCTIONS_GLSL = /* glsl */ `
+float jgFootprint;
+float jgFbm2(vec2 p){ return jgVNoise(p) * 0.62 + jgVNoise(p * 2.03 + 17.3) * 0.38; }
+float jgFbm3o(vec2 p){ return (jgVNoise(p) * 0.5 + jgVNoise(p * 2.03 + 17.3) * 0.3 + jgVNoise(p * 4.1 + 5.9) * 0.2); }
+float jgBand(float freq){ return 1.0 - smoothstep(0.16, 0.42, freq * jgFootprint); }
+vec2 jgHash22(vec2 cell){
+  uint h = jgHashUint(uvec2(ivec2(floor(cell + 0.5))));
+  uint h2 = h * 747796405u + 2891336453u;
+  h2 = (h2 ^ (h2 >> 15u)) * 2246822519u;
+  return vec2(float(h), float(h2 ^ (h2 >> 13u))) * (1.0 / 4294967296.0);
+}
+float jgHash3(vec3 i){
+  ivec3 c = ivec3(i);
+  return float(jgHashUint(uvec2(uint(c.x) ^ (uint(c.z) * 2654435761u), uint(c.y) + uint(c.z) * 1013904223u))) * (1.0 / 4294967296.0);
+}
+float jgVNoise3(vec3 p){
+  vec3 i = floor(p); vec3 f = fract(p);
+  vec3 u = f * f * (3.0 - 2.0 * f);
+  float a = jgHash3(i), b = jgHash3(i + vec3(1.0, 0.0, 0.0));
+  float c = jgHash3(i + vec3(0.0, 1.0, 0.0)), d = jgHash3(i + vec3(1.0, 1.0, 0.0));
+  float e = jgHash3(i + vec3(0.0, 0.0, 1.0)), g = jgHash3(i + vec3(1.0, 0.0, 1.0));
+  float h = jgHash3(i + vec3(0.0, 1.0, 1.0)), k = jgHash3(i + vec3(1.0, 1.0, 1.0));
+  return mix(mix(mix(a, b, u.x), mix(c, d, u.x), u.y), mix(mix(e, g, u.x), mix(h, k, u.x), u.y), u.z);
+}
+float jgFbm3(vec3 p){
+  float v = 0.0; float amp = 0.5;
+  for (int i = 0; i < 3; i++){ v += amp * jgVNoise3(p); p = p * 2.03 + vec3(1.7, 9.2, 4.1); amp *= 0.5; }
+  return v / 0.875;
+}
+// x: distance to the nearest feature point, y: F2 - F1 (0 on a cell border), z: that cell's random id.
+vec3 jgVoronoi(vec2 p){
+  vec2 n = floor(p); vec2 f = fract(p);
+  float d1 = 8.0; float d2 = 8.0; float id = 0.0;
+  for (int j = -1; j <= 1; j++){
+    for (int i = -1; i <= 1; i++){
+      vec2 g = vec2(float(i), float(j));
+      vec2 o = jgHash22(n + g);
+      vec2 r = g + 0.15 + o * 0.7 - f;
+      float d = dot(r, r);
+      if (d < d1){ d2 = d1; d1 = d; id = o.x; } else if (d < d2){ d2 = d; }
+    }
+  }
+  d1 = sqrt(d1);
+  return vec3(d1, sqrt(d2) - d1, id);
+}
+
+struct JgSurf { vec3 albedo; float height; float rough; float bump; };
+
+// height: 0..1 relief used to decide which layer wins along a blend edge; bump: displacement in metres.
+JgSurf jgSurface(int cls, vec3 color, float rough, float scale, vec3 wp){
+  vec2 p = wp.xz * scale;
+  JgSurf s;
+  s.albedo = color; s.rough = rough; s.height = 0.4; s.bump = 0.0;
+  float m = jgFbm3o(p / 1.6 + float(cls) * 13.7);
+#ifdef JG_SURFACE_LOW
+  s.albedo = color * (0.84 + 0.34 * m);
+  s.height = m;
+  return s;
+#else
+  bool shaded = false;
+#if (JG_SURFACE_CLASSES & 2) != 0
+  if (cls == 1) {
+    float clump = jgFbm3o(p / 0.9 + 5.3);
+    float dry = smoothstep(0.5, 0.75, jgFbm2(p / 7.0 + 17.0));
+    float blade = jgVNoise(p * 11.0 + clump * 3.0);
+    float fine = jgVNoise(p * 27.0 + 91.0);
+    float bBlade = jgBand(11.0);
+    s.albedo = mix(color, color * vec3(1.24, 1.12, 0.7), dry * 0.55);
+    s.albedo *= 0.74 + 0.48 * clump;
+    s.albedo = mix(s.albedo, color * vec3(0.78, 0.64, 0.46), smoothstep(0.42, 0.24, clump) * 0.25);
+    s.albedo *= 1.0 + (blade - 0.5) * 0.5 * bBlade + (fine - 0.5) * 0.32 * jgBand(27.0);
+    s.height = 0.2 + clump * 0.55 + blade * 0.25 * bBlade;
+    s.bump = clump * 0.014 + blade * 0.008 * bBlade;
+    shaded = true;
+  }
+#endif
+#if (JG_SURFACE_CLASSES & 4) != 0
+  if (cls == 2) {
+    float clod = jgVNoise(p * 3.0 + m * 2.0);
+    float crumb = jgVNoise(p * 14.0 + 7.0);
+    vec3 v = jgVoronoi(p * 2.2 + 7.7);
+    float peb = (1.0 - smoothstep(0.1, 0.2, v.x)) * step(0.7, v.z) * jgBand(7.0);
+    s.albedo = color * (0.78 + 0.44 * m);
+    s.albedo *= 1.0 + (clod - 0.5) * 0.32 * jgBand(3.0) + (crumb - 0.5) * 0.24 * jgBand(14.0);
+    s.albedo = mix(s.albedo, color * vec3(1.34, 1.3, 1.24) + 0.02, peb * 0.75);
+    s.height = 0.05 + m * 0.4 + clod * 0.2 + peb * 0.5;
+    s.bump = clod * 0.012 * jgBand(3.0) + crumb * 0.003 * jgBand(14.0) + peb * 0.012;
+    shaded = true;
+  }
+#endif
+#if (JG_SURFACE_CLASSES & 8) != 0
+  if (cls == 3) {
+    // Round pebbles from F1 distance (not Voronoi cells, which read as flagstone paving), two sizes,
+    // packed over darker grit.
+    vec3 va = jgVoronoi(p * 5.5);
+    float ra = 0.28 + 0.18 * fract(va.z * 13.1);
+    float sa = 1.0 - smoothstep(ra * 0.72, ra, va.x);
+    float da = sqrt(max(0.0, 1.0 - (va.x / ra) * (va.x / ra))) * sa;
+    vec3 vb = jgVoronoi(p * 11.0 + 3.1);
+    float rb = 0.32 + 0.14 * fract(vb.z * 7.7);
+    float sb = (1.0 - smoothstep(rb * 0.66, rb, vb.x)) * (1.0 - sa);
+    float db = sqrt(max(0.0, 1.0 - (vb.x / rb) * (vb.x / rb))) * sb;
+    float grit = jgVNoise(p * 24.0);
+    float bA = jgBand(5.5);
+    float bB = jgBand(11.0);
+    vec3 hueA = mix(vec3(1.08, 1.0, 0.9), vec3(0.92, 0.97, 1.08), fract(va.z * 7.13));
+    vec3 hueB = mix(vec3(1.05, 1.0, 0.93), vec3(0.95, 0.98, 1.05), fract(vb.z * 5.71));
+    vec3 near = color * (0.58 + 0.2 * grit);
+    near = mix(near, color * hueB * (0.66 + 0.5 * vb.z) * (0.72 + 0.28 * db), sb * bB);
+    near = mix(near, color * hueA * (0.64 + 0.62 * va.z) * (0.7 + 0.3 * da), sa);
+    s.albedo = mix(color * (0.8 + 0.26 * m), near, bA);
+    s.height = 0.3 + max(da, db * 0.6 * bB) * 0.6 * bA;
+    s.bump = (da * 0.03 + db * 0.012 * bB) * bA;
+    s.rough = rough - 0.08 * sa * bA;
+    shaded = true;
+  }
+#endif
+#if (JG_SURFACE_CLASSES & 16) != 0
+  if (cls == 4) {
+    vec3 q = wp * scale;
+    float n = jgFbm3(q / 1.8);
+    float n2 = jgFbm3(q * 1.7 + 5.0);
+    float grain = jgVNoise3(q * 9.0);
+    float strata = sin(q.y * 2.6 + n * 5.0) * 0.5 + 0.5;
+    float pits = smoothstep(0.72, 0.9, jgVNoise3(q * 4.3 + 11.0)) * jgBand(4.3);
+    float lichen = smoothstep(0.6, 0.78, jgFbm2(p / 3.0 + 41.0));
+    s.albedo = color * (0.4 + 1.25 * n) * (0.8 + 0.4 * n2 * jgBand(3.4)) * (1.0 - pits * 0.35) * (0.94 + strata * 0.12);
+    s.albedo *= 1.0 + (grain - 0.5) * 0.3 * jgBand(9.0);
+    s.albedo = mix(s.albedo, s.albedo * vec3(0.92, 1.06, 0.82), lichen * 0.45);
+    s.height = 0.35 + n * 0.65;
+    s.bump = n * 0.1 + n2 * 0.02 * jgBand(3.4) - pits * 0.006 + grain * 0.004 * jgBand(9.0);
+    s.rough = rough - 0.1 * n;
+    shaded = true;
+  }
+#endif
+#if (JG_SURFACE_CLASSES & 32) != 0
+  if (cls == 5) {
+    float warp = jgFbm2(p / 3.0 + 3.3);
+    float ripple = sin((p.x * 0.83 + p.y * 0.56) * 6.0 + warp * 7.0) * 0.5 + 0.5;
+    float grain = jgVNoise(p * 40.0);
+    float bRipple = jgBand(1.0);
+    s.albedo = color * (0.92 + 0.16 * m) * (1.0 + (ripple - 0.5) * 0.1 * bRipple);
+    float speck = jgVNoise(p * 9.0 + 2.7);
+    s.albedo *= 1.0 + (grain - 0.5) * 0.14 * jgBand(40.0) + (speck - 0.5) * 0.12 * jgBand(9.0);
+    s.height = 0.05 + ripple * 0.25 + m * 0.2;
+    s.bump = ripple * 0.012 * bRipple;
+    shaded = true;
+  }
+#endif
+#if (JG_SURFACE_CLASSES & 64) != 0
+  if (cls == 6) {
+    float puddle = smoothstep(0.56, 0.66, jgFbm3o(p / 3.2 + 31.0));
+    float lumps = jgVNoise(p * 4.0 + m);
+    s.albedo = color * (0.8 + 0.38 * m) * (1.0 + (lumps - 0.5) * 0.26 * jgBand(4.0));
+    s.albedo = mix(s.albedo, s.albedo * 0.58, puddle);
+    s.rough = mix(rough, 0.22, puddle);
+    s.height = (0.1 + m * 0.4 + lumps * 0.2) * (1.0 - puddle * 0.8);
+    s.bump = lumps * 0.012 * jgBand(4.0) * (1.0 - puddle);
+    shaded = true;
+  }
+#endif
+#if (JG_SURFACE_CLASSES & 128) != 0
+  if (cls == 7) {
+    float drift = jgFbm2(p / 4.0 + 9.0);
+    s.albedo = color * (0.93 + 0.1 * m + 0.04 * drift);
+    s.height = 0.3 + drift * 0.5;
+    s.bump = drift * 0.03 + m * 0.01;
+    shaded = true;
+  }
+#endif
+#if (JG_SURFACE_CLASSES & 256) != 0
+  if (cls == 8) {
+    float grain = jgVNoise(p * 30.0);
+    float stain = jgFbm2(p / 5.0 + 2.0);
+    s.albedo = color * (0.88 + 0.22 * stain) * (1.0 + (grain - 0.5) * 0.2 * jgBand(30.0));
+    s.height = 0.2 + stain * 0.2;
+    s.bump = grain * 0.0015 * jgBand(30.0);
+    shaded = true;
+  }
+#endif
+  if (!shaded) {
+    float fine = jgVNoise(p * 6.0 + 3.0);
+    s.albedo = color * (1.0 + (fine - 0.5) * 0.18 * jgBand(6.0));
+    s.height = 0.25 + m * 0.4;
+    s.bump = m * 0.02 + fine * 0.004 * jgBand(6.0);
+  }
+  return s;
+#endif
+}
+`;
+/** Paint-coverage uniforms and the warped, smoothed cell lookup. */
+export const PAINT_PARS_GLSL = /* glsl */ `
+uniform sampler2D uPaintA;
+uniform sampler2D uPaintB;
+uniform vec2 uPaintMin;
+uniform vec2 uPaintCell;
+uniform vec2 uPaintGrid;
+uniform float uPaintWarp;
+uniform vec3 uLayerColor[8];
+uniform float uLayerClass[8];
+uniform float uLayerRough[8];
+uniform float uLayerScale[8];
+float jgWarpNoise(vec2 p){ return (jgVNoise(p) * 0.65 + jgVNoise(p * 2.7 + 13.1) * 0.35) - 0.5; }
+vec2 jgPaintUv(vec2 wp){
+  vec2 cell = (wp - uPaintMin) / uPaintCell;
+  cell += vec2(jgWarpNoise(wp / 2.3 + 4.1), jgWarpNoise(wp / 2.3 + vec2(19.7, 3.3))) * uPaintWarp;
+  vec2 c = cell - 0.5;
+  vec2 i = floor(c); vec2 f = fract(c);
+  f = f * f * (3.0 - 2.0 * f);
+  return (i + f + 0.5) / uPaintGrid;
+}
+`;
+/**
+ * Micro-normal from a surface height `jgBumpH` (metres) via screen-space derivatives; goes after
+ * `normal_fragment_maps`. Skipped on the low tier.
+ */
+export const SURFACE_BUMP_NORMAL_GLSL = /* glsl */ `
+#ifndef JG_SURFACE_LOW
+{
+  // Bump from the blended surface height (metres) via screen-space derivatives, unnormalised so the
+  // tilt is the true world slope of that height field at any distance.
+  vec3 jgSigX = dFdx(-vViewPosition);
+  vec3 jgSigY = dFdy(-vViewPosition);
+  vec2 jgDh = vec2(dFdx(jgBumpH), dFdy(jgBumpH));
+  vec3 jgR1 = cross(jgSigY, normal);
+  vec3 jgR2 = cross(normal, jgSigX);
+  float jgDet = dot(jgSigX, jgR1) * faceDirection;
+  vec3 jgGrad = sign(jgDet) * (jgDh.x * jgR1 + jgDh.y * jgR2);
+  normal = normalize(abs(jgDet) * normal - jgGrad);
+}
+#endif
+`;

package/dist/terrain/terrainSurfaces.d.ts

@@ -0,0 +1,59 @@
+import * as THREE from "three";
+import type { TerrainPaintSource } from "./terrainPaintColor.js";
+/** Procedural ground response the terrain shader renders for a painted surface id. */
+export type TerrainSurfaceClass = "ground" | "grass" | "dirt" | "gravel" | "rock" | "sand" | "mud" | "snow" | "road";
+/**
+ * Classifies a painted surface id (e.g. `"grass"`, `"dry-grass"`, `"cobble-stone"`) into the procedural
+ * ground response the terrain shader draws for it; unknown ids get the generic `"ground"` response.
+ */
+export declare function terrainSurfaceClass(surface: string): TerrainSurfaceClass;
+/** Shader index of a surface class (`jgSurface`'s `cls`); bit `1 << index` in a class mask. */
+export declare function terrainSurfaceClassIndex(cls: TerrainSurfaceClass): number;
+/** Default roughness the terrain shades a surface class with. */
+export declare function terrainSurfaceRoughness(cls: TerrainSurfaceClass): number;
+/** At most this many distinct paint layers reach the GPU; extra layers fold into the last slot. */
+export declare const MAX_TERRAIN_PAINT_LAYERS = 8;
+/** One GPU paint slot: authored hue plus the procedural response it renders with. */
+export interface TerrainPaintSlot {
+    color: THREE.Color;
+    surfaceClass: TerrainSurfaceClass;
+    classIndex: number;
+    roughness: number;
+    /** Pattern frequency multiplier from the layer's authored `tiling`. */
+    scale: number;
+}
+/** Per-cell paint coverage packed for the shader: two RGBA8 planes holding up to eight layer weights. */
+export interface TerrainPaintWeights {
+    cols: number;
+    rows: number;
+    bounds: {
+        minX: number;
+        minZ: number;
+        maxX: number;
+        maxZ: number;
+    };
+    slots: TerrainPaintSlot[];
+    /** `cols*rows*4` bytes each: slots 0–3 and 4–7, 0..255 coverage scaled by layer opacity. */
+    planes: [Uint8Array, Uint8Array];
+}
+/**
+ * Packs a terrain's authored paint (layer stack, blend weights or hard surface ids) into per-cell
+ * coverage planes for the terrain surface shader. Returns `undefined` when the source exposes no
+ * cell grid. Pass `into` to rewrite an existing buffer in place after a paint stroke.
+ */
+export declare function packTerrainPaintWeights(source: TerrainPaintSource, into?: TerrainPaintWeights): TerrainPaintWeights | undefined;
+/** GPU-side paint coverage shared by the terrain surface material; `update` after each paint stroke. */
+export interface TerrainPaintTextures {
+    /** Shader uniforms (`uPaintA`, `uLayerColor`, …) to merge into the surface material. */
+    readonly uniforms: Record<string, THREE.IUniform>;
+    /** Bit `1 << classIndex` per surface class the current slots use; shaders compile only these responses. */
+    readonly classMask: number;
+    /** Re-upload coverage and layer slots; reallocates only when the cell grid size changes. */
+    update(weights: TerrainPaintWeights): void;
+    dispose(): void;
+}
+/**
+ * Uploads packed paint coverage ({@link packTerrainPaintWeights}) as two linear-filtered RGBA
+ * textures plus per-slot hue, surface class, roughness and pattern scale for the terrain surface material.
+ */
+export declare function createTerrainPaintTextures(weights: TerrainPaintWeights): TerrainPaintTextures;

package/dist/terrain/terrainSurfaces.js

@@ -0,0 +1,199 @@
+import * as THREE from "three";
+import { TERRAIN_MATERIAL_COLORS } from "@jgengine/core/editor/terrainMaterials";
+const CLASS_INDEX = {
+    ground: 0, grass: 1, dirt: 2, gravel: 3, rock: 4, sand: 5, mud: 6, snow: 7, road: 8,
+};
+/** Authored-tiling neutral point per class: a layer's `tiling` divided by this scales the pattern. */
+const CLASS_TILING = {
+    ground: 3, grass: 3, dirt: 2, gravel: 2, rock: 4, sand: 3, mud: 2, snow: 3, road: 2,
+};
+const CLASS_ROUGHNESS = {
+    ground: 0.92, grass: 0.95, dirt: 0.93, gravel: 0.88, rock: 0.82, sand: 0.96, mud: 0.8, snow: 0.78, road: 0.86,
+};
+const ALIASES = [
+    ["gravel", "gravel"], ["pebble", "gravel"], ["shingle", "gravel"], ["scree", "gravel"],
+    ["grass", "grass"], ["moss", "grass"], ["meadow", "grass"], ["lawn", "grass"], ["turf", "grass"], ["leaf", "grass"],
+    ["mud", "mud"], ["clay", "mud"], ["swamp", "mud"], ["bog", "mud"],
+    ["sand", "sand"], ["beach", "sand"], ["dune", "sand"],
+    ["snow", "snow"], ["ice", "snow"], ["frost", "snow"],
+    ["road", "road"], ["asphalt", "road"], ["tarmac", "road"], ["concrete", "road"], ["pavement", "road"],
+    ["rock", "rock"], ["stone", "rock"], ["cliff", "rock"], ["slate", "rock"], ["basalt", "rock"],
+    ["dirt", "dirt"], ["soil", "dirt"], ["earth", "dirt"], ["path", "dirt"], ["trail", "dirt"], ["ash", "dirt"],
+];
+/**
+ * Classifies a painted surface id (e.g. `"grass"`, `"dry-grass"`, `"cobble-stone"`) into the procedural
+ * ground response the terrain shader draws for it; unknown ids get the generic `"ground"` response.
+ */
+export function terrainSurfaceClass(surface) {
+    const id = surface.toLowerCase();
+    for (const [key, cls] of ALIASES)
+        if (id === key)
+            return cls;
+    for (const [key, cls] of ALIASES)
+        if (id.includes(key))
+            return cls;
+    return "ground";
+}
+/** Shader index of a surface class (`jgSurface`'s `cls`); bit `1 << index` in a class mask. */
+export function terrainSurfaceClassIndex(cls) {
+    return CLASS_INDEX[cls];
+}
+/** Default roughness the terrain shades a surface class with. */
+export function terrainSurfaceRoughness(cls) {
+    return CLASS_ROUGHNESS[cls];
+}
+/** At most this many distinct paint layers reach the GPU; extra layers fold into the last slot. */
+export const MAX_TERRAIN_PAINT_LAYERS = 8;
+function slotFor(surface, layer) {
+    const surfaceClass = terrainSurfaceClass(surface);
+    const tiling = layer?.tiling;
+    return {
+        color: new THREE.Color(layer?.tint ?? TERRAIN_MATERIAL_COLORS[surface] ?? "#7c7f86"),
+        surfaceClass,
+        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)),
+    };
+}
+/**
+ * Packs a terrain's authored paint (layer stack, blend weights or hard surface ids) into per-cell
+ * coverage planes for the terrain surface shader. Returns `undefined` when the source exposes no
+ * cell grid. Pass `into` to rewrite an existing buffer in place after a paint stroke.
+ */
+export function packTerrainPaintWeights(source, into) {
+    const { gridBounds, cols, rows } = source;
+    if (gridBounds === undefined || cols === undefined || rows === undefined || cols < 1 || rows < 1)
+        return undefined;
+    const layers = source.layers;
+    const slotIndex = new Map();
+    const slots = [];
+    const addSlot = (key, surface, layer) => {
+        const known = slotIndex.get(key);
+        if (known !== undefined)
+            return known;
+        const index = Math.min(slots.length, MAX_TERRAIN_PAINT_LAYERS - 1);
+        if (slots.length < MAX_TERRAIN_PAINT_LAYERS)
+            slots.push(slotFor(surface, layer));
+        slotIndex.set(key, index);
+        return index;
+    };
+    const layerSlots = layers.map(layer => addSlot(`layer:${layer.id}`, layer.surface, layer));
+    const surfaceSlot = (surface) => {
+        const index = layers.findIndex(layer => layer.surface === surface);
+        return index >= 0 ? layerSlots[index] : addSlot(`surface:${surface}`, surface, undefined);
+    };
+    const size = cols * rows * 4;
+    const planes = into !== undefined && into.cols === cols && into.rows === rows ? into.planes : [new Uint8Array(size), new Uint8Array(size)];
+    planes[0].fill(0);
+    planes[1].fill(0);
+    const cellW = (gridBounds.maxX - gridBounds.minX) / cols;
+    const cellD = (gridBounds.maxZ - gridBounds.minZ) / rows;
+    const accum = new Float32Array(MAX_TERRAIN_PAINT_LAYERS);
+    for (let gz = 0; gz < rows; gz++) {
+        const z = gridBounds.minZ + (gz + 0.5) * cellD;
+        for (let gx = 0; gx < cols; gx++) {
+            const x = gridBounds.minX + (gx + 0.5) * cellW;
+            accum.fill(0);
+            const weights = source.weightsAt(x, z);
+            if (layers.length > 0 && weights.length === layers.length) {
+                for (let i = 0; i < layers.length; i++)
+                    accum[layerSlots[i]] += weights[i] * (layers[i].opacity ?? 1);
+            }
+            else {
+                const surface = source.surfaceAt(x, z);
+                if (surface === null)
+                    continue;
+                const slot = surfaceSlot(surface);
+                const layer = layers.find(candidate => candidate.surface === surface);
+                accum[slot] = layer?.opacity ?? 1;
+            }
+            const cell = (gz * cols + gx) * 4;
+            for (let i = 0; i < MAX_TERRAIN_PAINT_LAYERS; i++) {
+                const value = Math.round(Math.min(1, Math.max(0, accum[i])) * 255);
+                if (value === 0)
+                    continue;
+                planes[i < 4 ? 0 : 1][cell + (i & 3)] = value;
+            }
+        }
+    }
+    return {
+        cols,
+        rows,
+        bounds: { minX: gridBounds.minX, minZ: gridBounds.minZ, maxX: gridBounds.maxX, maxZ: gridBounds.maxZ },
+        slots,
+        planes,
+    };
+}
+/** Edge warp, in cells: how far noise pushes a painted boundary off the cell grid. */
+const PAINT_EDGE_WARP = 1.5;
+function coverageTexture(data, cols, rows) {
+    const texture = new THREE.DataTexture(data, cols, rows, THREE.RGBAFormat, THREE.UnsignedByteType);
+    texture.magFilter = THREE.LinearFilter;
+    texture.minFilter = THREE.LinearFilter;
+    texture.wrapS = THREE.ClampToEdgeWrapping;
+    texture.wrapT = THREE.ClampToEdgeWrapping;
+    texture.generateMipmaps = false;
+    texture.needsUpdate = true;
+    return texture;
+}
+/**
+ * Uploads packed paint coverage ({@link packTerrainPaintWeights}) as two linear-filtered RGBA
+ * textures plus per-slot hue, surface class, roughness and pattern scale for the terrain surface material.
+ */
+export function createTerrainPaintTextures(weights) {
+    const colors = Array.from({ length: MAX_TERRAIN_PAINT_LAYERS }, () => new THREE.Color());
+    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 uniforms = {
+        uPaintA: { value: coverageTexture(weights.planes[0], weights.cols, weights.rows) },
+        uPaintB: { value: coverageTexture(weights.planes[1], weights.cols, weights.rows) },
+        uPaintMin: { value: new THREE.Vector2() },
+        uPaintCell: { value: new THREE.Vector2() },
+        uPaintGrid: { value: new THREE.Vector2() },
+        uPaintWarp: { value: PAINT_EDGE_WARP },
+        uLayerColor: { value: colors },
+        uLayerClass: { value: classes },
+        uLayerRough: { value: roughness },
+        uLayerScale: { value: scales },
+    };
+    let classMask = 0;
+    const update = (next) => {
+        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;
+            if (current.image.width === next.cols && current.image.height === next.rows) {
+                if (current.image.data !== plane)
+                    current.image.data.set(plane);
+                current.needsUpdate = true;
+            }
+            else {
+                current.dispose();
+                uniforms[key].value = coverageTexture(plane, next.cols, next.rows);
+            }
+        }
+        const { bounds, cols, rows } = next;
+        uniforms.uPaintMin.value.set(bounds.minX, bounds.minZ);
+        uniforms.uPaintCell.value.set((bounds.maxX - bounds.minX) / cols, (bounds.maxZ - bounds.minZ) / rows);
+        uniforms.uPaintGrid.value.set(cols, rows);
+        for (let i = 0; i < MAX_TERRAIN_PAINT_LAYERS; i++) {
+            const slot = next.slots[i];
+            colors[i].copy(slot?.color ?? colors[i]);
+            classes[i] = slot?.classIndex ?? 0;
+            roughness[i] = slot?.roughness ?? 0.9;
+            scales[i] = slot?.scale ?? 1;
+        }
+    };
+    update(weights);
+    return {
+        uniforms,
+        get classMask() {
+            return classMask;
+        },
+        update,
+        dispose: () => {
+            uniforms.uPaintA.value.dispose();
+            uniforms.uPaintB.value.dispose();
+        },
+    };
+}

package/dist/world/StaticObjectModels.d.ts

@@ -1,7 +1,7 @@
 import { type ReactNode } from "react";
 import type { SceneObject } from "@jgengine/core/scene/objectStore";
 import { type StaticObjectBatch } from "./staticObjectBatches.js";
-/** Render compatible authored props as shared model draws, preserving unsupported models. @internal */
+/** Render compatible authored or `scenery` props as shared model draws, preserving unsupported models. @internal */
 export declare function StaticObjectModels({ batch, single }: {
     batch: StaticObjectBatch;
     single: (object: SceneObject) => ReactNode;

package/dist/world/StaticObjectModels.js

@@ -69,7 +69,7 @@ function LoadedStaticObjects({ batch, single }) {
         return _jsx(_Fragment, { children: batch.objects.map(single) });
     return _jsxs(_Fragment, { children: [harvested.sources.map((source, index) => objects.length === 0 ? null : _jsx(ObjectSource, { source: source, objects: objects, batch: batch }, index)), excluded.map((id) => { const live = ctx.scene.object.get(id); return live === null ? null : single(live); })] });
 }
-/** Render compatible authored props as shared model draws, preserving unsupported models. @internal */
+/** Render compatible authored or `scenery` props as shared model draws, preserving unsupported models. @internal */
 export function StaticObjectModels({ batch, single }) {
     return _jsx(IsolatedModelPart, { model: batch.model, seam: "object", children: _jsx(LoadedStaticObjects, { batch: batch, single: single }) });
 }

package/dist/world/WorldScene.js

@@ -175,7 +175,7 @@ function WorldActors({ entitySprites, entityModels, objectModels, objectStyles,
         }
         return [{ object, model, custom, style, authored: authoredIds.has(instanceId), catalog: ctx.scene.object.catalog(instanceId) }];
     });
-    const grouped = groupStaticObjects(candidates.map((candidate) => ({ ...candidate, custom: candidate.custom !== undefined && candidate.custom !== null })), 24, batchCache.current);
+    const grouped = groupStaticObjects(candidates.map((candidate) => ({ ...candidate, custom: candidate.custom !== undefined && candidate.custom !== null })), undefined, batchCache.current);
     batchCache.current = new Map(grouped.batches.map((batch) => [batch.key, batch]));
     const candidatesById = new Map(candidates.map((candidate) => [candidate.object.instanceId, candidate]));
     const renderSingle = (object) => {

package/dist/world/staticObjectBatches.d.ts

@@ -24,7 +24,11 @@ export declare function canBatchStaticObject(candidate: StaticObjectCandidate):
 export declare function isCompatibleStaticObject(object: SceneObject, model: ModelConfig | undefined, catalog: GameContextObjectEntry | null): boolean;
 /** Stable exclusion snapshot; only compatibility transitions allocate. @internal */
 export declare function incompatibleStaticObjectIds(batch: StaticObjectBatch, get: (id: string) => SceneObject | null, catalog: (id: string) => GameContextObjectEntry | null, previous: readonly string[], fallbackObjects?: Map<string, SceneObject>): readonly string[];
-/** Groups compatible authored props above eight placements per spatial cell. @internal */
+/** Batch cell edge in metres: one instanced draw per model per cell, culled as a unit. @internal */
+export declare const STATIC_BATCH_CHUNK = 64;
+/** Smallest same-model group worth an instanced draw; below this each prop draws on its own. @internal */
+export declare const STATIC_BATCH_MIN = 3;
+/** Groups compatible authored or `scenery` props, at least {@link STATIC_BATCH_MIN} per spatial cell. @internal */
 export declare function groupStaticObjects(candidates: readonly StaticObjectCandidate[], chunkSize?: number, previous?: ReadonlyMap<string, StaticObjectBatch>): {
     batches: StaticObjectBatch[];
     singles: StaticObjectCandidate[];

package/dist/world/staticObjectBatches.js

@@ -3,7 +3,7 @@ import { POINTER_OBJECT_INSTANCES_KEY } from "../pointer/pointerService.js";
 /** The same compatibility gate is used when live placements change after grouping. @internal */
 export function canBatchStaticObject(candidate) {
     const { object, model, catalog } = candidate;
-    return candidate.authored && !candidate.custom && candidate.style === undefined &&
+    return (candidate.authored || catalog?.scenery === true) && !candidate.custom && candidate.style === undefined &&
         isCompatibleStaticObject(object, model, catalog);
 }
 /** Checks a live placement without constructing a grouping candidate. @internal */
@@ -15,7 +15,7 @@ export function isCompatibleStaticObject(object, model, catalog) {
         (catalog?.breakable === undefined || catalog.breakable === false) && catalog?.slotInventory === undefined &&
         (animation === undefined || animation === "auto" || animation === "none") && model.ik === undefined &&
         (model.scale ?? 1) >= 0 && (model.parts?.length ?? 0) === 0 && (model.attachments?.length ?? 0) === 0 &&
-        model.partMotion === undefined && model.material?.maps === undefined && (model.materialAssignments?.length ?? 0) === 0 &&
+        model.partMotion === undefined && model.surfaceDetail !== false && model.material?.maps === undefined && (model.materialAssignments?.length ?? 0) === 0 &&
         (model.hiddenNodes === undefined || (Array.isArray(model.hiddenNodes) && model.hiddenNodes.length === 0));
 }
 /** Stable exclusion snapshot; only compatibility transitions allocate. @internal */
@@ -49,8 +49,12 @@ export function incompatibleStaticObjectIds(batch, get, catalog, previous, fallb
         return live !== null && !compatible(live) ? [live.instanceId] : [];
     });
 }
-/** Groups compatible authored props above eight placements per spatial cell. @internal */
-export function groupStaticObjects(candidates, chunkSize = 24, previous) {
+/** Batch cell edge in metres: one instanced draw per model per cell, culled as a unit. @internal */
+export const STATIC_BATCH_CHUNK = 64;
+/** Smallest same-model group worth an instanced draw; below this each prop draws on its own. @internal */
+export const STATIC_BATCH_MIN = 3;
+/** Groups compatible authored or `scenery` props, at least {@link STATIC_BATCH_MIN} per spatial cell. @internal */
+export function groupStaticObjects(candidates, chunkSize = STATIC_BATCH_CHUNK, previous) {
     const groups = new Map();
     const singles = [];
     for (const candidate of candidates) {
@@ -70,7 +74,7 @@ export function groupStaticObjects(candidates, chunkSize = 24, previous) {
     }
     const batches = [];
     for (const { batch, candidates: members } of groups.values()) {
-        if (batch.objects.length > 8) {
+        if (batch.objects.length >= STATIC_BATCH_MIN) {
             const cached = previous?.get(batch.key);
             batches.push(cached !== undefined && cached.objects.length === batch.objects.length &&
                 cached.objects.every((object, index) => object.instanceId === batch.objects[index].instanceId) ? cached : batch);

package/dist/world/worldBarSamples.d.ts

@@ -6,6 +6,8 @@ export interface WorldBarSample {
     x: number;
     y: number;
     percent: number;
+    /** Screen pixels per world metre at the anchor, so painted bars shrink with distance and zoom. */
+    pxPerMeter?: number;
 }
 export interface Projectable {
     set(x: number, y: number, z: number): this;
@@ -63,9 +65,19 @@ export declare function collectNameplateSamples(ctx: GameContext, statId: string
     width: number;
     height: number;
 }, into: NameplateSample[], project: Projectable, maxDistance?: number, occlude?: boolean, options?: WorldOverlaySampleOptions): number;
+/**
+ * Painted bar size for a sample: about {@link WORLD_BAR_METERS} wide at the anchor's on-screen
+ * scale, clamped between a still-readable minimum and the configured maximum, with height in
+ * proportion. Samples without a scale (caller-painted screen samples) keep the maximum.
+ * @internal
+ */
+export declare function worldBarSize(pxPerMeter: number | undefined, maxWidthPx?: number, maxHeightPx?: number): {
+    width: number;
+    height: number;
+};
 /** @internal */
 export declare function paintWorldBarSamples(canvas: {
     width: number;
     height: number;
     getContext(kind: "2d"): CanvasRenderingContext2D | null;
-}, samples: readonly WorldBarSample[], dpr: number, barWidthPx?: number, barHeightPx?: number): void;
+}, samples: readonly WorldBarSample[], dpr: number, maxBarWidthPx?: number, maxBarHeightPx?: number): void;