@jgengine/shell 0.18.1 → 0.21.0

package/dist/structures/buildingSpatialBatch.js

@@ -0,0 +1,45 @@
+import * as THREE from "three";
+/** Partition final geometry bounds without changing instance transforms or material groups. @internal */
+export function partitionBuildingMatrices(geometry, matrices, sourceMatrix, cellSize = 64) {
+    if (!Number.isFinite(cellSize) || cellSize <= 0)
+        throw new RangeError("Building cell size must be positive and finite");
+    if (geometry.boundingBox === null)
+        geometry.computeBoundingBox();
+    const geometryBounds = geometry.boundingBox;
+    if (geometryBounds === null || geometryBounds.isEmpty())
+        return [];
+    const chunks = new Map();
+    const aggregateBounds = new THREE.Box3();
+    const finalMatrices = [];
+    const bounds = new THREE.Box3();
+    const center = new THREE.Vector3();
+    for (const matrix of matrices) {
+        const finalMatrix = sourceMatrix === undefined ? matrix : new THREE.Matrix4().multiplyMatrices(matrix, sourceMatrix);
+        bounds.copy(geometryBounds).applyMatrix4(finalMatrix);
+        aggregateBounds.union(bounds);
+        finalMatrices.push(finalMatrix);
+        bounds.getCenter(center);
+        const key = `${Math.floor(center.x / cellSize)}:${Math.floor(center.z / cellSize)}`;
+        let chunk = chunks.get(key);
+        if (chunk === undefined) {
+            chunk = { key, matrices: [], bounds: new THREE.Box3() };
+            chunks.set(key, chunk);
+        }
+        chunk.matrices.push(finalMatrix);
+        chunk.bounds.union(bounds);
+    }
+    if (finalMatrices.length > 0 && aggregateBounds.max.x - aggregateBounds.min.x <= cellSize
+        && aggregateBounds.max.z - aggregateBounds.min.z <= cellSize) {
+        return [{ key: "compact", matrices: finalMatrices, bounds: aggregateBounds }];
+    }
+    return [...chunks.values()];
+}
+/** Install matrices and bounds; cleanup releases only the mesh's instance buffers, retaining shared assets. @internal */
+export function applyBuildingChunk(mesh, chunk) {
+    chunk.matrices.forEach((matrix, index) => mesh.setMatrixAt(index, matrix));
+    mesh.count = chunk.matrices.length;
+    mesh.instanceMatrix.needsUpdate = true;
+    mesh.boundingBox = chunk.bounds.clone();
+    mesh.boundingSphere = chunk.bounds.getBoundingSphere(new THREE.Sphere());
+    return () => mesh.dispose();
+}

package/dist/structures/buildingSurface.d.ts

@@ -0,0 +1,21 @@
+import * as THREE from "three";
+import type { BuildingSurfaceMaps, BuildingSurfaceMaterial } from "@jgengine/core/world/buildings";
+import type { MaterialOverrideTextures } from "../materialOverride.js";
+/** A surface that names at least one map URL. */
+export type TexturedBuildingSurface = BuildingSurfaceMaterial & {
+    maps: BuildingSurfaceMaps;
+};
+/** True when the surface names at least one map URL, so the batch needs the textured path. */
+export declare function surfaceHasMaps(surface: BuildingSurfaceMaterial | undefined): surface is TexturedBuildingSurface;
+/** A stable key for bucketing instances that share one surface (same colour, maps, tiling, and response). */
+export declare function surfaceKey(surface: BuildingSurfaceMaterial | undefined): string;
+/**
+ * Loads a surface's PBR maps and returns per-caller clones configured to tile `repeat` times per
+ * slot, or `undefined` until the first map arrives so the batch draws its flat colour meanwhile.
+ * Clones share the decoded image, so two kinds using one map at different repeats cost one
+ * download. Maps whose file is missing are skipped rather than failing the whole surface.
+ * @internal
+ */
+export declare function useBuildingSurfaceTextures(surface: BuildingSurfaceMaterial | undefined): MaterialOverrideTextures | undefined;
+/** Applies a surface's colour, response, and loaded maps onto a standard or physical material in place. @internal */
+export declare function applyBuildingSurface(material: THREE.MeshStandardMaterial, surface: BuildingSurfaceMaterial, textures: MaterialOverrideTextures | undefined): THREE.MeshStandardMaterial;

package/dist/structures/buildingSurface.js

@@ -0,0 +1,134 @@
+import { useEffect, useMemo, useState } from "react";
+import * as THREE from "three";
+const SURFACE_ROLES = ["color", "normal", "roughness", "ao", "metalness"];
+/** True when the surface names at least one map URL, so the batch needs the textured path. */
+export function surfaceHasMaps(surface) {
+    if (surface?.maps === undefined)
+        return false;
+    return SURFACE_ROLES.some((role) => surface.maps?.[role] !== undefined);
+}
+/** A stable key for bucketing instances that share one surface (same colour, maps, tiling, and response). */
+export function surfaceKey(surface) {
+    if (surface === undefined)
+        return "";
+    const repeat = surface.repeat === undefined ? 1 : surface.repeat;
+    const maps = surface.maps === undefined ? "" : SURFACE_ROLES.map((role) => surface.maps?.[role] ?? "").join(",");
+    const tiling = typeof repeat === "number" ? String(repeat) : repeat.join("x");
+    return `${surface.color ?? ""}|${maps}|${tiling}|${surface.roughness ?? ""}|${surface.metalness ?? ""}`;
+}
+function repeatOf(surface) {
+    const repeat = surface.repeat ?? 1;
+    return typeof repeat === "number" ? [repeat, repeat] : [repeat[0], repeat[1]];
+}
+const textureLoader = new THREE.TextureLoader();
+const loads = new Map();
+/** One shared decode per URL; a missing file (a pack without `ao.jpg`) resolves to null instead of failing the batch. */
+function loadSurfaceTexture(url) {
+    let pending = loads.get(url);
+    if (pending === undefined) {
+        pending = new Promise((resolve) => {
+            textureLoader.load(url, (texture) => resolve(texture), undefined, () => resolve(null));
+        });
+        loads.set(url, pending);
+    }
+    return pending;
+}
+/**
+ * Loads a surface's PBR maps and returns per-caller clones configured to tile `repeat` times per
+ * slot, or `undefined` until the first map arrives so the batch draws its flat colour meanwhile.
+ * Clones share the decoded image, so two kinds using one map at different repeats cost one
+ * download. Maps whose file is missing are skipped rather than failing the whole surface.
+ * @internal
+ */
+export function useBuildingSurfaceTextures(surface) {
+    const maps = surface?.maps;
+    const color = maps?.color;
+    const normal = maps?.normal;
+    const roughness = maps?.roughness;
+    const ao = maps?.ao;
+    const metalness = maps?.metalness;
+    const urls = useMemo(() => {
+        const record = {};
+        if (color !== undefined)
+            record.color = color;
+        if (normal !== undefined)
+            record.normal = normal;
+        if (roughness !== undefined)
+            record.roughness = roughness;
+        if (ao !== undefined)
+            record.ao = ao;
+        if (metalness !== undefined)
+            record.metalness = metalness;
+        return record;
+    }, [color, normal, roughness, ao, metalness]);
+    const [loaded, setLoaded] = useState(undefined);
+    useEffect(() => {
+        const entries = Object.entries(urls);
+        if (entries.length === 0) {
+            setLoaded(undefined);
+            return;
+        }
+        let cancelled = false;
+        Promise.all(entries.map(([role, url]) => loadSurfaceTexture(url).then((texture) => [role, texture]))).then((results) => {
+            if (cancelled)
+                return;
+            const record = {};
+            for (const [role, texture] of results)
+                if (texture !== null)
+                    record[role] = texture;
+            setLoaded(Object.keys(record).length === 0 ? undefined : record);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [urls]);
+    const [repeatX, repeatY] = surface === undefined ? [1, 1] : repeatOf(surface);
+    const textures = useMemo(() => {
+        if (loaded === undefined)
+            return undefined;
+        const out = {};
+        for (const role of SURFACE_ROLES) {
+            const source = loaded[role];
+            if (source === undefined)
+                continue;
+            const texture = source.clone();
+            texture.wrapS = THREE.RepeatWrapping;
+            texture.wrapT = THREE.RepeatWrapping;
+            texture.repeat.set(repeatX, repeatY);
+            texture.colorSpace = role === "color" ? THREE.SRGBColorSpace : THREE.NoColorSpace;
+            texture.needsUpdate = true;
+            out[role] = texture;
+        }
+        return out;
+    }, [loaded, repeatX, repeatY]);
+    useEffect(() => () => {
+        if (textures === undefined)
+            return;
+        for (const role of SURFACE_ROLES)
+            textures[role]?.dispose();
+    }, [textures]);
+    return textures;
+}
+/** Applies a surface's colour, response, and loaded maps onto a standard or physical material in place. @internal */
+export function applyBuildingSurface(material, surface, textures) {
+    if (surface.color !== undefined)
+        material.color.set(surface.color);
+    if (surface.roughness !== undefined)
+        material.roughness = surface.roughness;
+    if (surface.metalness !== undefined)
+        material.metalness = surface.metalness;
+    if (textures !== undefined) {
+        if (textures.color !== undefined)
+            material.map = textures.color;
+        if (textures.normal !== undefined)
+            material.normalMap = textures.normal;
+        if (textures.roughness !== undefined)
+            material.roughnessMap = textures.roughness;
+        if (textures.ao !== undefined)
+            material.aoMap = textures.ao;
+        if (textures.metalness !== undefined)
+            material.metalnessMap = textures.metalness;
+        material.needsUpdate = true;
+    }
+    return material;
+}

package/dist/terrain/GrassField.d.ts

@@ -28,4 +28,5 @@ export interface GrassFieldProps extends Omit<ThreeElements["mesh"], "args" | "c
     normalLift?: number;
     roughness?: number;
 }
-export declare function GrassField({ count, density, budget, area, seed, segments, bladeHeight, bladeWidth, bladeBend, tuftBlades, tuftRadius, edgeFeather, exclude, heightAt, colorBase, colorTip, colorGround, colorVariation, wind, distanceFade, normalLift, roughness, castShadow, receiveShadow, frustumCulled, ...meshProps }: GrassFieldProps): import("react").JSX.Element;
+/** Seeded grass tufts with bounded per-camera chunk submission; density and budgets stay in blades. */
+export declare function GrassField({ count, density, budget, area, seed, segments, bladeHeight, bladeWidth, bladeBend, tuftBlades, tuftRadius, edgeFeather, exclude, heightAt, colorBase, colorTip, colorGround, colorVariation, wind, distanceFade, normalLift, roughness, castShadow, receiveShadow, frustumCulled, onBeforeRender, onBeforeShadow, onAfterRender, onAfterShadow, ...meshProps }: GrassFieldProps): import("react").JSX.Element;

package/dist/terrain/GrassField.js

@@ -1,14 +1,16 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useFrame } from "@react-three/fiber";
 import { useEffect, useMemo } from "react";
+import * as THREE from "three";
 import { useDisposable } from "../render/useDisposable.js";
-import { createGrassBladeGeometry, grassTuftCount, GRASS_TUFT_BLADES, } from "./grassGeometry.js";
+import { createGrassGeometryChunks, grassTuftCount, GRASS_TUFT_BLADES, } from "./grassGeometry.js";
 import { createGrassMaterial, } from "./grassMaterial.js";
 import { DEFAULT_GRASS_COUNT, DEFAULT_GRASS_DENSITY, resolveGrassInstanceBudget, } from "./grassBudget.js";
 export { DEFAULT_GRASS_COUNT, DEFAULT_GRASS_DENSITY, resolveGrassInstanceBudget } from "./grassBudget.js";
 export { GRASS_TUFT_BLADES } from "./grassGeometry.js";
-export function GrassField({ count = DEFAULT_GRASS_COUNT, density = DEFAULT_GRASS_DENSITY, budget, area = 40, seed = 1, segments = 4, bladeHeight, bladeWidth, bladeBend, tuftBlades = GRASS_TUFT_BLADES, tuftRadius, edgeFeather, exclude, heightAt, colorBase, colorTip, colorGround, colorVariation, wind, distanceFade, normalLift, roughness, castShadow = false, receiveShadow = true, frustumCulled = true, ...meshProps }) {
-    const geometry = useDisposable(() => createGrassBladeGeometry({
+/** Seeded grass tufts with bounded per-camera chunk submission; density and budgets stay in blades. */
+export function GrassField({ count = DEFAULT_GRASS_COUNT, density = DEFAULT_GRASS_DENSITY, budget, area = 40, seed = 1, segments = 4, bladeHeight, bladeWidth, bladeBend, tuftBlades = GRASS_TUFT_BLADES, tuftRadius, edgeFeather, exclude, heightAt, colorBase, colorTip, colorGround, colorVariation, wind, distanceFade, normalLift, roughness, castShadow = false, receiveShadow = true, frustumCulled = true, onBeforeRender, onBeforeShadow, onAfterRender, onAfterShadow, ...meshProps }) {
+    const chunks = useMemo(() => createGrassGeometryChunks({
         count,
         area,
         seed,
@@ -22,6 +24,7 @@ export function GrassField({ count = DEFAULT_GRASS_COUNT, density = DEFAULT_GRAS
         ...(exclude === undefined ? {} : { exclude }),
         heightAt,
     }), [area, bladeBend, bladeHeight, bladeWidth, count, edgeFeather, exclude, heightAt, seed, segments, tuftBlades, tuftRadius]);
+    useDisposable(() => chunks.map((chunk) => chunk.geometry), [chunks]);
     const handle = useMemo(() => createGrassMaterial({
         colorBase,
         colorTip,
@@ -34,10 +37,61 @@ export function GrassField({ count = DEFAULT_GRASS_COUNT, density = DEFAULT_GRAS
     }), [colorBase, colorTip, colorGround, colorVariation, distanceFade, normalLift, roughness, wind]);
     // Budgets stay in blades (the public unit); the instance buffer carries tufts.
     const instanceCount = useMemo(() => grassTuftCount(resolveGrassInstanceBudget(count, density, area, budget), tuftBlades), [count, density, area, budget, tuftBlades]);
-    geometry.instanceCount = Math.min(instanceCount, grassTuftCount(count, tuftBlades));
+    const draws = useMemo(() => {
+        const counts = chunks.map((chunk) => {
+            let low = 0, high = chunk.indices.length;
+            while (low < high) {
+                const mid = (low + high) >>> 1;
+                if (chunk.indices[mid] < instanceCount)
+                    low = mid + 1;
+                else
+                    high = mid;
+            }
+            return low;
+        });
+        const patchBounds = new THREE.Box3(new THREE.Vector3(-0.5, 0, 0), new THREE.Vector3(0.5, 1, 0));
+        const windExtent = (Math.abs(handle.uniforms.uWindStrength.value) + Math.abs(handle.uniforms.uWindFlutter.value)) * 1.2;
+        for (const chunk of chunks) {
+            chunk.bounds.copy(chunk.roots).expandByScalar(chunk.bladeExtent + windExtent);
+            chunk.geometry.boundingBox = chunk.bounds;
+            patchBounds.union(chunk.bounds);
+        }
+        const sphere = patchBounds.getBoundingSphere(new THREE.Sphere());
+        // All chunks retain the patch's shadow bounds; the factor also covers affine parent shear.
+        sphere.radius *= Math.sqrt(3);
+        const worldBounds = new THREE.Box3();
+        const cameraPosition = new THREE.Vector3();
+        const projection = new THREE.Matrix4();
+        const frustum = new THREE.Frustum();
+        return chunks.map((chunk, index) => {
+            chunk.geometry.boundingSphere = sphere;
+            chunk.geometry.instanceCount = counts[index];
+            const beforeRender = function (renderer, scene, camera, geometry, material, group) {
+                let visible = true;
+                if (frustumCulled) {
+                    projection.multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse);
+                    frustum.setFromProjectionMatrix(projection, camera.coordinateSystem, camera.reversedDepth);
+                    visible = frustum.intersectsBox(worldBounds.copy(chunk.bounds).applyMatrix4(this.matrixWorld));
+                }
+                const fade = handle.uniforms.uDistanceFade.value;
+                if (visible && fade.y > fade.x) {
+                    camera.getWorldPosition(cameraPosition);
+                    visible = worldBounds.copy(chunk.roots).applyMatrix4(this.matrixWorld).distanceToPoint(cameraPosition) <= fade.y;
+                }
+                chunk.geometry.instanceCount = visible ? counts[index] : 0;
+                onBeforeRender?.call(this, renderer, scene, camera, geometry, material, group);
+            };
+            const beforeShadow = function (...args) {
+                chunk.geometry.instanceCount = counts[index];
+                onBeforeShadow?.apply(this, args);
+            };
+            return { geometry: chunk.geometry, beforeRender, beforeShadow };
+        });
+    }, [chunks, frustumCulled, handle, instanceCount, onBeforeRender, onBeforeShadow]);
     useFrame((state) => {
         handle.uniforms.uTime.value = state.clock.elapsedTime;
     });
     useEffect(() => () => handle.material.dispose(), [handle]);
-    return (_jsx("mesh", { ...meshProps, geometry: geometry, material: handle.material, castShadow: castShadow, receiveShadow: receiveShadow, frustumCulled: frustumCulled }));
+    const root = draws[0];
+    return (_jsx("mesh", { ...meshProps, geometry: root.geometry, material: handle.material, castShadow: castShadow, receiveShadow: receiveShadow, frustumCulled: frustumCulled, onBeforeRender: root.beforeRender, onBeforeShadow: root.beforeShadow, onAfterRender: onAfterRender, onAfterShadow: onAfterShadow, dispose: null, children: draws.slice(1).map((draw, index) => (_jsx("mesh", { geometry: draw.geometry, material: handle.material, castShadow: castShadow, receiveShadow: receiveShadow, frustumCulled: frustumCulled, onBeforeRender: draw.beforeRender, onBeforeShadow: draw.beforeShadow, onAfterRender: onAfterRender, onAfterShadow: onAfterShadow, dispose: null }, index))) }));
 }

package/dist/terrain/grassGeometry.d.ts

@@ -60,3 +60,13 @@ export declare function grassTuftCount(bladeCount: number, tuftBlades?: number):
  * @internal
  */
 export declare function createGrassBladeGeometry(options?: GrassBladeGeometryOptions): THREE.InstancedBufferGeometry;
+/** One bounded draw, retaining the original tuft indices for density/budget prefix selection. @internal */
+export interface GrassGeometryChunk {
+    geometry: THREE.InstancedBufferGeometry;
+    indices: Uint32Array;
+    roots: THREE.Box3;
+    bounds: THREE.Box3;
+    bladeExtent: number;
+}
+/** Partition one existing seeded bake into at most 64 draws without resampling any tuft. @internal */
+export declare function createGrassGeometryChunks(options?: GrassBladeGeometryOptions): GrassGeometryChunk[];

package/dist/terrain/grassGeometry.js

@@ -140,3 +140,58 @@ export function createGrassBladeGeometry(options = {}) {
     geometry.boundingSphere = new THREE.Sphere(new THREE.Vector3(0, 0, 0), Math.max(size.width, size.depth) * 0.75 + resolved.height[1]);
     return geometry;
 }
+/** Partition one existing seeded bake into at most 64 draws without resampling any tuft. @internal */
+export function createGrassGeometryChunks(options = {}) {
+    const source = createGrassBladeGeometry(options);
+    const size = resolveTerrainSize(options.area ?? 40);
+    const columns = Math.max(1, Math.min(8, Math.ceil(size.width / 16)));
+    const rows = Math.max(1, Math.min(8, Math.ceil(size.depth / 16)));
+    const buckets = Array.from({ length: columns * rows }, () => []);
+    const offsets = source.getAttribute("instanceOffset");
+    if (source.instanceCount === 0)
+        return [{ geometry: source, indices: new Uint32Array(), roots: new THREE.Box3(), bounds: new THREE.Box3(), bladeExtent: 0 }];
+    for (let i = 0; i < source.instanceCount; i++) {
+        const x = Math.max(0, Math.min(columns - 1, Math.floor(size.width > 0 ? (offsets.getX(i) / size.width + 0.5) * columns : 0)));
+        const z = Math.max(0, Math.min(rows - 1, Math.floor(size.depth > 0 ? (offsets.getZ(i) / size.depth + 0.5) * rows : 0)));
+        buckets[z * columns + x].push(i);
+    }
+    const vary = source.getAttribute("bladeVary");
+    const bendScale = source.getAttribute("bladeBendScale");
+    const bladeOffset = source.getAttribute("bladeOffset");
+    let heightScale = 0, widthScale = 0, bendFactor = 0, radius = 0;
+    for (let i = 0; i < vary.count; i++) {
+        heightScale = Math.max(heightScale, Math.abs(vary.getY(i)));
+        widthScale = Math.max(widthScale, Math.abs(vary.getZ(i)));
+        bendFactor = Math.max(bendFactor, Math.abs(bendScale.getX(i)));
+        radius = Math.max(radius, Math.hypot(bladeOffset.getX(i), bladeOffset.getY(i)));
+    }
+    const point = new THREE.Vector3();
+    const chunks = buckets.filter((indices) => indices.length > 0).map((indices) => {
+        const geometry = new THREE.InstancedBufferGeometry();
+        geometry.setIndex(source.index);
+        for (const [name, attribute] of Object.entries(source.attributes)) {
+            if (!(attribute instanceof THREE.InstancedBufferAttribute)) {
+                geometry.setAttribute(name, attribute);
+                continue;
+            }
+            const values = new Float32Array(indices.length * attribute.itemSize);
+            for (let i = 0; i < indices.length; i++) {
+                values.set(attribute.array.subarray(indices[i] * attribute.itemSize, (indices[i] + 1) * attribute.itemSize), i * attribute.itemSize);
+            }
+            geometry.setAttribute(name, new THREE.InstancedBufferAttribute(values, attribute.itemSize));
+        }
+        const roots = new THREE.Box3();
+        let extent = radius;
+        for (const i of indices) {
+            roots.expandByPoint(point.set(offsets.getX(i), offsets.getY(i), offsets.getZ(i)));
+            const height = Math.abs(source.getAttribute("instanceHeight").getX(i)) * heightScale;
+            const bend = Math.abs(source.getAttribute("instanceBend").getX(i)) * bendFactor;
+            const width = Math.abs(source.getAttribute("instanceWidth").getX(i)) * widthScale * 1.2;
+            extent = Math.max(extent, radius + width + height * (1 + bend * 1.18));
+        }
+        geometry.instanceCount = indices.length;
+        return { geometry, indices: Uint32Array.from(indices), roots, bounds: roots.clone(), bladeExtent: extent };
+    });
+    source.dispose();
+    return chunks;
+}

package/dist/terrain/grassMaterial.js

@@ -111,7 +111,7 @@ void jgComputeGrassBlade() {
   // triangle blades leave the ground visible between tufts and read as stubble.
   float taper = (1.0 - 0.3 * t) * (1.0 - smoothstep(0.5, 1.0, t) * 0.95);
   // Surviving distant tufts widen to hold silhouette coverage as neighbors thin out.
-  float width = instanceWidth * bladeVary.z * taper * (1.0 + fadeT * 1.4);
+  float width = instanceWidth * bladeVary.z * taper * (1.0 + fadeT * 1.4) * keep;
   float arc = instanceBend * bladeBendScale * t * t;
   vec3 localPosition = vec3(side * width, heightScale * t - arc * heightScale * 0.18, arc * heightScale);
   vec3 localNormal = normalize(vec3(0.0, -instanceBend * bladeBendScale * t, 1.0));
@@ -134,7 +134,7 @@ ${wind.layered
     + sin(gustPhase * 1.7 + crossPhase * 0.4 + 4.3) * 0.13;`
             : `  float gust = sin(gustPhase) * 0.7 + sin(gustPhase * 0.43 + 2.4) * 0.3;`}
   float flutter = sin(uTime * 7.5 + instancePhase * 2.7 + bladeVary.w * 6.2832) * uWindFlutter;
-  vec2 windOffset = uWindDirection * (gust * uWindStrength + flutter) * t * t * (0.4 + 0.6 * bladeVary.y);
+  vec2 windOffset = uWindDirection * (gust * uWindStrength + flutter) * t * t * (0.4 + 0.6 * bladeVary.y) * keep;
   jgGrassPosition = instanceOffset + tuftOffset + yawedPosition + vec3(windOffset.x, 0.0, windOffset.y);
   // Lifting normals toward straight-up lights the field like a continuous meadow surface —
   // side-lit individual blade planes read as dark stubble, not turf.

package/dist/terrain/terrainDetailMaterial.d.ts

@@ -7,13 +7,13 @@ export interface TerrainDetailMaterialHandle {
 /**
  * Loaded PBR textures matching a resolved `ResolvedTerrainDetailMaterial.maps`' roles. The caller
  * (a React component, via `useTexture`/`useLoader`) owns loading and disposal; `core` never touches
- * `THREE.Texture` and this shell function never fetches a URL itself.
+ * `THREE.Texture` and this shell function never fetches a URL itself. Omitted AO/roughness skip sampling.
  */
 export interface TerrainDetailMaterialTextures {
     color: THREE.Texture;
     normal: THREE.Texture;
-    roughness: THREE.Texture;
-    ao: THREE.Texture;
+    roughness?: THREE.Texture;
+    ao?: THREE.Texture;
 }
 /**
  * A `MeshStandardMaterial` whose fragment shader keeps the biome-tinted vertex

package/dist/terrain/terrainDetailMaterial.js

@@ -60,8 +60,8 @@ export function createTerrainDetailMaterial(detail, textures) {
             ? {
                 uMatColor: { value: textures.color },
                 uMatNormal: { value: textures.normal },
-                uMatRoughness: { value: textures.roughness },
-                uMatAo: { value: textures.ao },
+                ...(textures.roughness !== undefined ? { uMatRoughness: { value: textures.roughness } } : {}),
+                ...(textures.ao !== undefined ? { uMatAo: { value: textures.ao } } : {}),
                 uMatRepeat: { value: Math.max(0.01, repeat) },
                 uMatStrength: { value: strength },
                 uMatTint: { value: tint },
@@ -88,8 +88,8 @@ vJgWorldPos = (modelMatrix * vec4(transformed, 1.0)).xyz;`);
             ? `
 uniform sampler2D uMatColor;
 uniform sampler2D uMatNormal;
-uniform sampler2D uMatRoughness;
-uniform sampler2D uMatAo;
+${textures.roughness !== undefined ? "uniform sampler2D uMatRoughness;" : ""}
+${textures.ao !== undefined ? "uniform sampler2D uMatAo;" : ""}
 uniform float uMatRepeat;
 uniform float uMatStrength;
 uniform float uMatTint;`
@@ -106,7 +106,7 @@ float jgMatLum = dot(jgMatColor, vec3(0.2126, 0.7152, 0.0722));
 jgCol *= mix(1.0, clamp(jgMatLum / 0.35, 0.55, 1.7), uMatStrength * (1.0 - uMatTint));
 jgCol = mix(jgCol, jgMatColor, uMatStrength * uMatTint);`
             : "";
-        const materialRoughnessGlsl = hasTexture
+        const materialRoughnessGlsl = hasTexture && textures.roughness !== undefined
             ? `
 float jgMatRough = texture2D(uMatRoughness, jgMatUv).g;
 roughnessFactor = mix(roughnessFactor, jgMatRough, uMatStrength);`
@@ -116,7 +116,7 @@ roughnessFactor = mix(roughnessFactor, jgMatRough, uMatStrength);`
 vec2 jgMatNormalXy = texture2D(uMatNormal, jgMatUv).rg * 2.0 - 1.0;
 normal = normalize(normal + vec3(jgMatNormalXy.x, 0.0, jgMatNormalXy.y) * uMatStrength * 0.6);`
             : "";
-        const materialAoGlsl = hasTexture
+        const materialAoGlsl = hasTexture && textures.ao !== undefined
             ? `
 float jgMatAo = texture2D(uMatAo, jgMatUv).r;
 reflectedLight.indirectDiffuse *= mix(1.0, jgMatAo, uMatStrength);`
@@ -178,6 +178,6 @@ ${materialNormalGlsl}`)
             .replace("#include <aomap_fragment>", `#include <aomap_fragment>
 ${materialAoGlsl}`);
     };
-    material.customProgramCacheKey = () => `jgengine-terrain-detail-${detail.rockSlopeStart}-${detail.snowHeight}-${hasTexture ? "tex" : "flat"}`;
+    material.customProgramCacheKey = () => `jgengine-terrain-detail-${detail.rockSlopeStart}-${detail.snowHeight}-${hasTexture ? "tex" : "flat"}-${hasTexture && textures.roughness !== undefined ? "rough" : "scalar"}-${hasTexture && textures.ao !== undefined ? "ao" : "unoccluded"}`;
     return { material };
 }

package/dist/touch/TouchControlsOverlay.js

@@ -548,8 +548,8 @@ function anchorInset(anchor) {
     }
     return style;
 }
-function AnchoredSlot({ anchor, children, slotRef, }) {
-    return (_jsx("div", { className: "pointer-events-none absolute z-40", style: { ...ANCHOR_POSITION[anchor], ...anchorInset(anchor) }, children: _jsx("div", { ref: slotRef, children: children }) }));
+function AnchoredSlot({ anchor, children, slotRef, movement = false, }) {
+    return (_jsx("div", { className: "pointer-events-none absolute", style: { zIndex: movement ? 10 : 40, ...ANCHOR_POSITION[anchor], ...anchorInset(anchor) }, children: _jsx("div", { ref: slotRef, children: children }) }));
 }
 function bucketByAnchor(buttons) {
     const map = new Map();
@@ -580,8 +580,8 @@ export function TouchControlsDock({ scheme, sink, style, scale = 1, joystickVari
     useRegisterLayoutRegion(UTILITY_ZONE, utilityRef, utility.length > 0);
     const actionsColumn = layout.actions === "left" || layout.actions === "right";
     const utilityColumn = layout.utility === "left" || layout.utility === "right";
-    return (_jsxs(ResolvedLayout, { children: [scheme.joystick !== null ? (_jsx(AnchoredSlot, { anchor: layout.movement, slotRef: joystickRef, children: joystickVariant === "floating" ? (_jsx(FloatingJoystick, { joystick: scheme.joystick, sink: sink, tokens: tokens, scale: scale })) : (_jsx(VirtualJoystick, { joystick: scheme.joystick, sink: sink, tokens: tokens, scale: scale })) })) : null, primary.length > 0 ? (_jsx(AnchoredSlot, { anchor: layout.actions, slotRef: actionsRef, children: ARC_ANCHORS.has(layout.actions) ? (_jsx(ThumbArcCluster, { buttons: primary, sink: sink, tokens: tokens, scale: scale })) : (_jsx(StackCluster, { buttons: primary, utility: [], sink: sink, tokens: tokens, column: actionsColumn, scale: scale })) })) : null, utility.length > 0 ? (_jsx(AnchoredSlot, { anchor: layout.utility, slotRef: utilityRef, children: _jsx(StackCluster, { buttons: [], utility: utility, sink: sink, tokens: tokens, column: utilityColumn, scale: scale }) })) : null, [...extras.entries()].map(([anchor, bucket]) => (_jsx(AnchoredSlot, { anchor: anchor, children: _jsx(StackCluster, { buttons: bucket.primary, utility: bucket.utility, sink: sink, tokens: tokens, column: anchor === "left" || anchor === "right", scale: scale }) }, anchor)))] }));
+    return (_jsxs(ResolvedLayout, { children: [scheme.joystick !== null ? (_jsx(AnchoredSlot, { anchor: layout.movement, slotRef: joystickRef, movement: true, children: joystickVariant === "floating" ? (_jsx(FloatingJoystick, { joystick: scheme.joystick, sink: sink, tokens: tokens, scale: scale })) : (_jsx(VirtualJoystick, { joystick: scheme.joystick, sink: sink, tokens: tokens, scale: scale })) })) : null, primary.length > 0 ? (_jsx(AnchoredSlot, { anchor: layout.actions, slotRef: actionsRef, children: ARC_ANCHORS.has(layout.actions) ? (_jsx(ThumbArcCluster, { buttons: primary, sink: sink, tokens: tokens, scale: scale })) : (_jsx(StackCluster, { buttons: primary, utility: [], sink: sink, tokens: tokens, column: actionsColumn, scale: scale })) })) : null, utility.length > 0 ? (_jsx(AnchoredSlot, { anchor: layout.utility, slotRef: utilityRef, children: _jsx(StackCluster, { buttons: [], utility: utility, sink: sink, tokens: tokens, column: utilityColumn, scale: scale }) })) : null, [...extras.entries()].map(([anchor, bucket]) => (_jsx(AnchoredSlot, { anchor: anchor, children: _jsx(StackCluster, { buttons: bucket.primary, utility: bucket.utility, sink: sink, tokens: tokens, column: anchor === "left" || anchor === "right", scale: scale }) }, anchor)))] }));
 }
 function ResolvedLayout({ children }) {
-    return _jsx("div", { className: "pointer-events-none absolute inset-0 z-40", children: children });
+    return _jsx("div", { className: "pointer-events-none absolute inset-0", children: children });
 }

package/dist/useShellMultiplayerSync.d.ts

@@ -1,6 +1,6 @@
 import { type Dispatch, type SetStateAction } from "react";
 import type { GameContext } from "@jgengine/core/runtime/gameContext";
-import type { PresencePoseRow } from "@jgengine/core/runtime/transport";
+import { type PresencePoseRow } from "@jgengine/core/runtime/transport";
 import { type AuthoritativeFrameHandler } from "./worldSync.js";
 import type { ShellMultiplayer } from "./multiplayer.js";
 import type { PlayableGame } from "./registry.js";

package/dist/useShellMultiplayerSync.js

@@ -1,5 +1,7 @@
 import { useEffect, useState, useCallback } from "react";
 import { isServerAuthoritative } from "@jgengine/core/runtime/adapter";
+import { bindCommandTransport } from "@jgengine/core/runtime/commandDispatch";
+import { createTransportSessionId } from "@jgengine/core/runtime/transport";
 import { attachWorldSync } from "./worldSync.js";
 /** Joins the multiplayer server for the live context and wires presence, feed relay, and chat sync until teardown. */
 export function useShellMultiplayerSync(ctx, multiplayer, playable, serverIdRef, setRemotePlayers, authoritativeFrameRef) {
@@ -14,8 +16,12 @@ export function useShellMultiplayerSync(ctx, multiplayer, playable, serverIdRef,
         setFailureReason(null);
         let disposed = false;
         const cleanups = [];
+        if (isServerAuthoritative(playable.game.multiplayer)) {
+            cleanups.push(bindCommandTransport(ctx, { transport: multiplayer.backend.transport, serverId: () => serverIdRef.current }));
+        }
+        const sessionId = createTransportSessionId();
         void multiplayer.backend.transport
-            .joinServer({ gameId: multiplayer.gameId })
+            .joinServer({ gameId: multiplayer.gameId, sessionId })
             .then((joined) => {
             if (!joined.ok) {
                 if (!disposed) {
@@ -25,7 +31,7 @@ export function useShellMultiplayerSync(ctx, multiplayer, playable, serverIdRef,
                 return;
             }
             if (disposed) {
-                void multiplayer.backend.transport.leaveServer({ serverId: joined.serverId });
+                void multiplayer.backend.transport.leaveServer({ serverId: joined.serverId, sessionId }).catch(() => undefined);
                 return;
             }
             serverIdRef.current = joined.serverId;
@@ -110,7 +116,7 @@ export function useShellMultiplayerSync(ctx, multiplayer, playable, serverIdRef,
             serverIdRef.current = null;
             setRemotePlayers([]);
             if (serverId !== null) {
-                void multiplayer.backend.transport.leaveServer({ serverId }).catch(() => undefined);
+                void multiplayer.backend.transport.leaveServer({ serverId, sessionId }).catch(() => undefined);
             }
         };
     }, [ctx, multiplayer, playable, attempt]);

package/dist/vfx/ParticleField.d.ts

@@ -1,32 +1,35 @@
 import { type ReactElement } from "react";
 import type { ParticleSystem } from "@jgengine/core/vfx/particles";
-/** How particle fragments composite: `additive` for fire/sparks/magic glow, `normal` for smoke/dust. */
+import type { ParticleRenderHint } from "@jgengine/core/vfx/particleDirector";
+/** How particle fragments composite on screen. */
 export type ParticleBlending = "additive" | "normal";
-/** Props for {@link ParticleField}. */
+/** @internal Mutable resource/upload counters read through the shell's supported diagnostics probe. */
+export interface ParticleFieldMetrics {
+    fieldsMounted: number;
+    fieldsUnmounted: number;
+    liveFields: number;
+    attributeBytes: number;
+    totalUploadMs: number;
+    maxUploadMs: number;
+    uploadSamples: number;
+}
+/** Props for the existing pooled particle renderer. */
 export interface ParticleFieldProps {
-    /** The core simulation to render (from `createParticleSystem`). */
     system: ParticleSystem;
-    /**
-     * Advance the simulation each frame with the render delta. Leave `true` for a
-     * fire-and-forget effect; set `false` when your game loop already ticks the
-     * system (so it advances exactly once per fixed step).
-     */
+    /** Disable when an external loop already advances this system. Default true. */
     advance?: boolean;
-    /** Compositing mode. Default `additive` (glowy). */
     blending?: ParticleBlending;
-    /** Pixel-size multiplier applied to every particle's world radius. Default 300. */
+    /** Pixel multiplier for point output. Quad outputs use particle sizes in world units. */
     scale?: number;
-    /** Write depth (occludes particles behind geometry). Default `false` so a glow layer never self-occludes. */
     depthWrite?: boolean;
+    /** Point, instanced sprite, velocity streak, connected ribbon, or ground ripple output. */
+    render?: ParticleRenderHint;
+    /** @internal Optional diagnostics; omitted in production. */
+    metrics?: ParticleFieldMetrics;
 }
 /**
- * Renders a core `ParticleSystem` as a GPU point cloud: one draw call, per-particle
- * size / color / alpha via a soft-round shader, and a `drawRange` clamped to the live
- * count so dead particles cost nothing. The simulation stays engine-side and
- * genre-agnostic; this is purely how it reaches the screen. By default it advances
- * the sim with the frame delta — pass `advance={false}` to drive it from your own
- * fixed loop instead.
- *
- * @capability particle-field render a core particle system as a soft-point GPU cloud with per-particle size, color, and alpha
+ * Render one pooled simulation through a point cloud or instanced quads. Output
+ * selection does not replace spawn, forces, collisions, or deterministic state.
+ * @capability particle-field render a core particle pool as soft points, velocity streaks, connected ribbons, flakes, flames, smoke sprites, or ground ripples
  */
-export declare function ParticleField({ system, advance, blending, scale, depthWrite, }: ParticleFieldProps): ReactElement;
+export declare function ParticleField({ system, advance, blending, scale, depthWrite, render, metrics }: ParticleFieldProps): ReactElement;