@jgengine/shell 0.19.0 → 0.22.0

package/dist/structures/BuildingKitBatch.js

@@ -1,50 +1,29 @@
 import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
-import { useEffect, useMemo, useRef } from "react";
+import { useEffect, useLayoutEffect, useMemo, useRef } from "react";
 import { useLoader } from "@react-three/fiber";
 import * as THREE from "three";
+import { useModelMaterialTextures } from "../render/materialAsset.js";
 import { sharedGltfLoader } from "../render/modelLoad.js";
 import { buildScatterModelSources, disposeScatterModelSources, } from "../scatter/scatterModels.js";
-import { composeBuildingKitMatrix, measureBuildingKitModel, } from "./buildingKitFit.js";
-import { applyBuildingSurface, surfaceKey, useBuildingSurfaceTextures } from "./buildingSurface.js";
+import { measureBuildingKitModel, } from "./buildingKitFit.js";
+import { useBuildingSurfaceTextures } from "./buildingSurface.js";
+import { groupBuildingKitInstances, buildBuildingKitSources, validateBuildingKitSource } from "./buildingKitMaterials.js";
+import { useBuildingChunkBudget } from "./BuildingRenderBudget.js";
+import { applyBuildingChunk, partitionBuildingMatrices } from "./buildingSpatialBatch.js";
 function KitSourceInstances({ source, material, matrices, }) {
+    const chunks = useMemo(() => partitionBuildingMatrices(source.geometry, matrices, source.localMatrix), [source, matrices]);
+    return _jsx(_Fragment, { children: chunks.map((chunk) => _jsx(KitSourceChunk, { source: source, material: material, chunk: chunk }, chunk.key)) });
+}
+function KitSourceChunk({ source, material, chunk }) {
     const meshRef = useRef(null);
-    useEffect(() => {
+    useBuildingChunkBudget(meshRef, chunk.bounds);
+    useLayoutEffect(() => {
         const mesh = meshRef.current;
         if (mesh === null)
             return;
-        const composed = new THREE.Matrix4();
-        for (let i = 0; i < matrices.length; i += 1) {
-            composed.multiplyMatrices(matrices[i], source.localMatrix);
-            mesh.setMatrixAt(i, composed);
-        }
-        mesh.count = matrices.length;
-        mesh.instanceMatrix.needsUpdate = true;
-        mesh.computeBoundingSphere();
-    }, [matrices, source]);
-    return (_jsx("instancedMesh", { ref: meshRef, args: [source.geometry, material, matrices.length], castShadow: true, receiveShadow: true }, matrices.length));
-}
-function styleOne(material, tint, surface, textures) {
-    const clone = material.clone();
-    const tintable = clone;
-    if (tint !== undefined && tintable.color !== undefined)
-        tintable.color.copy(tint);
-    if (surface !== undefined && clone.isMeshStandardMaterial === true) {
-        applyBuildingSurface(clone, surface, textures);
-    }
-    return clone;
-}
-function styleMaterial(material, tint, surface, textures) {
-    const color = tint === "" ? undefined : new THREE.Color(tint);
-    return Array.isArray(material)
-        ? material.map((entry) => styleOne(entry, color, surface, textures))
-        : styleOne(material, color, surface, textures);
-}
-function disposeMaterial(material) {
-    if (Array.isArray(material))
-        for (const entry of material)
-            entry.dispose();
-    else
-        material.dispose();
+        return applyBuildingChunk(mesh, chunk);
+    }, [chunk, source, material]);
+    return (_jsx("instancedMesh", { ref: meshRef, args: [source.geometry, material, chunk.matrices.length], castShadow: true, receiveShadow: true, dispose: null }, chunk.matrices.length));
 }
 /**
  * GPU-instances one kit model across every building part bound to it: the GLB loads once, its meshes
@@ -52,31 +31,27 @@ function disposeMaterial(material) {
  * while the GLB loads — mount it inside a `<Suspense>` so one slow model never blanks the rest.
  * @internal
  */
-export function BuildingKitBatch({ url, instances }) {
+export function BuildingKitBatch({ url, instances, materialAssets }) {
     const gltf = useLoader(sharedGltfLoader, url);
+    useMemo(() => {
+        const checked = new Set();
+        for (const instance of instances)
+            if (!checked.has(instance.part)) {
+                validateBuildingKitSource(gltf.scene, instance.part, materialAssets);
+                checked.add(instance.part);
+            }
+    }, [gltf, instances, materialAssets]);
     const { sources, root } = useMemo(() => buildScatterModelSources(gltf.scene, { url }), [gltf, url]);
     useEffect(() => () => disposeScatterModelSources(root), [root]);
     const bounds = useMemo(() => measureBuildingKitModel(root), [root]);
-    const groups = useMemo(() => {
-        const byKey = new Map();
-        for (const instance of instances) {
-            const matrix = composeBuildingKitMatrix(instance, bounds, new THREE.Matrix4());
-            const tint = instance.part.tint ?? "";
-            const surface = instance.part.material;
-            const key = `${tint}|${surfaceKey(surface)}`;
-            const bucket = byKey.get(key);
-            if (bucket === undefined)
-                byKey.set(key, { key, tint, surface, matrices: [matrix] });
-            else
-                bucket.matrices.push(matrix);
-        }
-        return [...byKey.values()];
-    }, [instances, bounds]);
-    return (_jsx(_Fragment, { children: groups.map((group) => group.tint === "" && group.surface === undefined ? (sources.map((source, index) => (_jsx(KitSourceInstances, { source: source, material: source.material, matrices: group.matrices }, `${group.key}:${index}`)))) : (_jsx(StyledKitSources, { sources: sources, group: group }, group.key))) }));
+    const groups = useMemo(() => groupBuildingKitInstances(instances, bounds, materialAssets), [instances, bounds, materialAssets]);
+    return (_jsx(_Fragment, { children: groups.map((group) => (group.part.tint ?? "") === "" && group.part.material === undefined && !group.part.materialAssignments?.length ? (sources.map((source, index) => (_jsx(KitSourceInstances, { source: source, material: source.material, matrices: group.matrices }, `${group.key}:${index}`)))) : (_jsx(StyledKitSources, { scene: gltf.scene, materialAssets: materialAssets, group: group }, group.key))) }));
 }
-function StyledKitSources({ sources, group }) {
-    const textures = useBuildingSurfaceTextures(group.surface);
-    const styled = useMemo(() => sources.map((source) => styleMaterial(source.material, group.tint, group.surface, textures)), [sources, group.tint, group.surface, textures]);
-    useEffect(() => () => styled.forEach(disposeMaterial), [styled]);
-    return (_jsx(_Fragment, { children: sources.map((source, index) => (_jsx(KitSourceInstances, { source: source, material: styled[index], matrices: group.matrices }, index))) }));
+function StyledKitSources({ scene, materialAssets, group }) {
+    useMemo(() => validateBuildingKitSource(scene, group.part, materialAssets), [scene, group.key]);
+    const textures = useBuildingSurfaceTextures(group.part.material);
+    const materialTextures = useModelMaterialTextures({ materialAssets, materialAssignments: group.part.materialAssignments });
+    const { sources, root } = useMemo(() => buildBuildingKitSources(scene, group.part, materialAssets, textures, materialTextures.assets), [scene, group.key, textures, materialTextures]);
+    useEffect(() => () => disposeScatterModelSources(root), [root]);
+    return (_jsx(_Fragment, { children: sources.map((source, index) => (_jsx(KitSourceInstances, { source: source, material: source.material, matrices: group.matrices }, index))) }));
 }

package/dist/structures/BuildingRenderBudget.d.ts

@@ -0,0 +1,23 @@
+import { type ReactNode, type RefObject } from "react";
+import * as THREE from "three";
+import type { VisibilityConfig } from "@jgengine/core/visibility/config";
+/** Resolved shell distance policy for generated facade batches. @internal */
+export interface BuildingRenderPolicy {
+    enabled: boolean;
+    minDistance: number;
+    maxDistance: number;
+    hysteresis: number;
+}
+/** Resolve existing visibility overrides over the already resolved graphics-tier distance. @internal */
+export declare function resolveBuildingRenderPolicy(drawDistance: number, config?: VisibilityConfig, cullingDisabled?: boolean): BuildingRenderPolicy;
+/** Forward the shell's resolved graphics distance without registering generated parts as scene objects. @internal */
+export declare function BuildingRenderBudget({ drawDistance, visibility, cullingDisabled, children }: {
+    drawDistance: number;
+    visibility?: VisibilityConfig;
+    cullingDisabled?: boolean;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** Test world bounds; transforming the box first also conservatively encloses affine shear. @internal */
+export declare function buildingChunkWithinBudget(bounds: THREE.Box3, matrixWorld: THREE.Matrix4, cameraPosition: THREE.Vector3, policy: BuildingRenderPolicy, previouslyVisible: boolean, worldBounds: THREE.Box3, worldSphere: THREE.Sphere, frustumSphere?: THREE.Sphere | null): boolean;
+/** Distance-gate chunks only; Three retains independent main-camera and shadow-camera frustum tests. @internal */
+export declare function useBuildingChunkBudget(meshRef: RefObject<THREE.InstancedMesh | null>, bounds: THREE.Box3): void;

package/dist/structures/BuildingRenderBudget.js

@@ -0,0 +1,54 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo, useRef } from "react";
+import { useFrame } from "@react-three/fiber";
+import * as THREE from "three";
+import { culledByDistance } from "@jgengine/core/visibility/distance";
+import { DEFAULT_CULLING_SETTINGS } from "@jgengine/core/visibility/settings";
+import { CAMERA_POST_FRAME_PRIORITY } from "../camera/cameraRigs.js";
+const UNLIMITED = { enabled: false, minDistance: 0, maxDistance: Infinity, hysteresis: 0 };
+const BuildingRenderContext = createContext(UNLIMITED);
+/** Resolve existing visibility overrides over the already resolved graphics-tier distance. @internal */
+export function resolveBuildingRenderPolicy(drawDistance, config, cullingDisabled = false) {
+    const culling = config?.culling;
+    const scene = config?.scene;
+    return {
+        // Scene callbacks address visibility rows; generated parts have no row to evaluate safely.
+        enabled: !cullingDisabled && config?.enabled !== false && culling?.enabled !== false && culling?.distanceCulling !== false
+            && scene?.alwaysVisible !== true && scene?.cullingDisabled !== true && scene?.customVisibility === undefined,
+        minDistance: scene?.minRenderDistance ?? culling?.defaultMinRenderDistance ?? DEFAULT_CULLING_SETTINGS.defaultMinRenderDistance,
+        maxDistance: scene?.maxRenderDistance ?? culling?.defaultMaxRenderDistance ?? drawDistance,
+        hysteresis: culling?.hysteresis ?? DEFAULT_CULLING_SETTINGS.hysteresis,
+    };
+}
+/** Forward the shell's resolved graphics distance without registering generated parts as scene objects. @internal */
+export function BuildingRenderBudget({ drawDistance, visibility, cullingDisabled = false, children }) {
+    const policy = useMemo(() => resolveBuildingRenderPolicy(drawDistance, visibility, cullingDisabled), [drawDistance, visibility, cullingDisabled]);
+    return _jsx(BuildingRenderContext.Provider, { value: policy, children: children });
+}
+/** Test world bounds; transforming the box first also conservatively encloses affine shear. @internal */
+export function buildingChunkWithinBudget(bounds, matrixWorld, cameraPosition, policy, previouslyVisible, worldBounds, worldSphere, frustumSphere) {
+    worldBounds.copy(bounds).applyMatrix4(matrixWorld).getBoundingSphere(worldSphere);
+    if (frustumSphere !== undefined && frustumSphere !== null) {
+        bounds.getCenter(frustumSphere.center);
+        const worldScale = matrixWorld.getMaxScaleOnAxis();
+        // Three transforms this sphere using the largest matrix column, which can underbound shear.
+        frustumSphere.radius = Math.max(bounds.min.distanceTo(bounds.max) / 2, worldScale === 0 ? 0 : worldSphere.radius / worldScale);
+    }
+    if (!policy.enabled)
+        return true;
+    const { center, radius } = worldSphere;
+    return !culledByDistance(cameraPosition.x, cameraPosition.y, cameraPosition.z, center.x, center.y, center.z, policy.minDistance, policy.maxDistance, radius, previouslyVisible ? policy.hysteresis : 0);
+}
+/** Distance-gate chunks only; Three retains independent main-camera and shadow-camera frustum tests. @internal */
+export function useBuildingChunkBudget(meshRef, bounds) {
+    const policy = useContext(BuildingRenderContext);
+    const scratch = useRef({ box: new THREE.Box3(), sphere: new THREE.Sphere(), camera: new THREE.Vector3() });
+    useFrame(({ camera }) => {
+        const mesh = meshRef.current;
+        if (mesh === null)
+            return;
+        mesh.updateWorldMatrix(true, false);
+        camera.getWorldPosition(scratch.current.camera);
+        mesh.visible = buildingChunkWithinBudget(bounds, mesh.matrixWorld, scratch.current.camera, policy, mesh.visible, scratch.current.box, scratch.current.sphere, mesh.boundingSphere);
+    }, CAMERA_POST_FRAME_PRIORITY);
+}

package/dist/structures/GeneratedBuilding.js

@@ -1,9 +1,11 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Suspense, useLayoutEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
 import { buildingSurfaceColor, resolveBuildingSurface, } from "@jgengine/core/world/buildings";
 import { useDisposable } from "../render/useDisposable.js";
 import { BuildingKitBatch } from "./BuildingKitBatch.js";
+import { useBuildingChunkBudget } from "./BuildingRenderBudget.js";
+import { applyBuildingChunk, partitionBuildingMatrices } from "./buildingSpatialBatch.js";
 import { bucketBuildingParts, normalFor, outwardOffset } from "./buildingKitFit.js";
 import { applyBuildingSurface, useBuildingSurfaceTextures } from "./buildingSurface.js";
 const DEFAULT_PALETTE = {
@@ -54,17 +56,20 @@ function batchMaterialFor(kind, surface, textures) {
 function BuildingKindBatch({ kind, matrices, palette, geometry }) {
     const surface = useMemo(() => surfaceFor(kind, palette), [kind, palette]);
     const textures = useBuildingSurfaceTextures(surface);
-    const meshRef = useRef(null);
     const material = useDisposable(() => batchMaterialFor(kind, surface, textures), [kind, surface, textures]);
+    const chunks = useMemo(() => partitionBuildingMatrices(geometry, matrices), [geometry, matrices]);
+    return _jsx(_Fragment, { children: chunks.map((chunk) => _jsx(BuildingChunk, { chunk: chunk, material: material, geometry: geometry }, chunk.key)) });
+}
+function BuildingChunk({ chunk, material, geometry }) {
+    const meshRef = useRef(null);
+    useBuildingChunkBudget(meshRef, chunk.bounds);
     useLayoutEffect(() => {
         const mesh = meshRef.current;
         if (mesh === null)
             return;
-        matrices.forEach((matrix, index) => mesh.setMatrixAt(index, matrix));
-        mesh.instanceMatrix.needsUpdate = true;
-        mesh.computeBoundingSphere();
-    }, [matrices, material]);
-    return (_jsx("instancedMesh", { ref: meshRef, args: [geometry, material, matrices.length], castShadow: true, receiveShadow: true }, matrices.length));
+        return applyBuildingChunk(mesh, chunk);
+    }, [chunk, geometry, material]);
+    return (_jsx("instancedMesh", { ref: meshRef, args: [geometry, material, chunk.matrices.length], castShadow: true, receiveShadow: true, dispose: null }, chunk.matrices.length));
 }
 export function InstancedBuildings({ buildings, palette, kit, resolveModelUrl, visibleKinds, }) {
     const geometry = useDisposable(() => new THREE.BoxGeometry(1, 1, 1), []);
@@ -74,7 +79,7 @@ export function InstancedBuildings({ buildings, palette, kit, resolveModelUrl, v
     }, [buildings, visibleKinds, kit, resolveModelUrl]);
     if (boxes.size === 0 && models.size === 0)
         return null;
-    return (_jsxs("group", { children: [[...boxes.entries()].map(([kind, matrices]) => (_jsx(BuildingKindBatch, { kind: kind, matrices: matrices, palette: palette, geometry: geometry }, kind))), [...models.entries()].map(([url, instances]) => (_jsx(Suspense, { fallback: null, children: _jsx(BuildingKitBatch, { url: url, instances: instances }) }, url)))] }));
+    return (_jsxs("group", { children: [[...boxes.entries()].map(([kind, matrices]) => (_jsx(BuildingKindBatch, { kind: kind, matrices: matrices, palette: palette, geometry: geometry }, kind))), [...models.entries()].map(([url, instances]) => (_jsx(Suspense, { fallback: null, children: _jsx(BuildingKitBatch, { url: url, instances: instances, materialAssets: kit?.materialAssets }) }, url)))] }));
 }
 function BlockMesh({ part, palette }) {
     const [nx, nz] = normalFor(part.facade);

package/dist/structures/buildingKitMaterials.d.ts

@@ -0,0 +1,20 @@
+import * as THREE from "three";
+import type { BuildingKitPart } from "@jgengine/core/world/buildingKit";
+import { type MaterialAsset } from "@jgengine/core/material/materialAsset";
+import type { MaterialOverrideTextures } from "../materialOverride.js";
+import { buildScatterModelSources } from "../scatter/scatterModels.js";
+import { type BuildingKitInstance, type BuildingKitModelBounds } from "./buildingKitFit.js";
+/** The material values used by one kit variant, excluding unrelated document library entries. @internal */
+export declare function buildingKitMaterialKey(part: BuildingKitPart, assets?: readonly MaterialAsset[]): string;
+/** One material style shared by every fitted instance using it. @internal */
+export interface BuildingKitStyleGroup {
+    key: string;
+    part: BuildingKitPart;
+    matrices: THREE.Matrix4[];
+}
+/** Group fitted instances while resolving each repeated variant's material identity only once. @internal */
+export declare function groupBuildingKitInstances(instances: readonly BuildingKitInstance[], bounds: BuildingKitModelBounds, assets?: readonly MaterialAsset[]): BuildingKitStyleGroup[];
+/** Validate named kit materials and native targets before any owned model or texture allocation. @internal */
+export declare function validateBuildingKitSource(scene: THREE.Object3D, part: BuildingKitPart, assets?: readonly MaterialAsset[]): void;
+/** Prepare one style's owned model materials before harvesting shared geometry for bounded instanced chunks. @internal */
+export declare function buildBuildingKitSources(scene: THREE.Object3D, part: BuildingKitPart, assets?: readonly MaterialAsset[], surfaceTextures?: MaterialOverrideTextures, assetTextures?: ReadonlyMap<string, MaterialOverrideTextures>): ReturnType<typeof buildScatterModelSources>;

package/dist/structures/buildingKitMaterials.js

@@ -0,0 +1,70 @@
+import * as THREE from "three";
+import { validateMaterialAssignments } from "@jgengine/core/material/materialAsset";
+import { applyMaterialAssignments, validateMaterialAssignmentTargets } from "../render/materialAsset.js";
+import { buildScatterModelSources, disposeScatterModelSources } from "../scatter/scatterModels.js";
+import { composeBuildingKitMatrix } from "./buildingKitFit.js";
+import { applyBuildingSurface, surfaceKey } from "./buildingSurface.js";
+/** The material values used by one kit variant, excluding unrelated document library entries. @internal */
+export function buildingKitMaterialKey(part, assets = []) {
+    const ids = new Set(part.materialAssignments?.map(assignment => assignment.materialId));
+    return JSON.stringify([part.tint ?? "", surfaceKey(part.material), part.materialAssignments ?? [], assets.filter(asset => ids.has(asset.id))]);
+}
+/** Group fitted instances while resolving each repeated variant's material identity only once. @internal */
+export function groupBuildingKitInstances(instances, bounds, assets = []) {
+    const byKey = new Map();
+    const styleKeys = new Map();
+    for (const instance of instances) {
+        const matrix = composeBuildingKitMatrix(instance, bounds, new THREE.Matrix4());
+        let key = styleKeys.get(instance.part);
+        if (key === undefined) {
+            key = buildingKitMaterialKey(instance.part, assets);
+            styleKeys.set(instance.part, key);
+        }
+        const bucket = byKey.get(key);
+        if (bucket === undefined)
+            byKey.set(key, { key, part: instance.part, matrices: [matrix] });
+        else
+            bucket.matrices.push(matrix);
+    }
+    return [...byKey.values()];
+}
+/** Validate named kit materials and native targets before any owned model or texture allocation. @internal */
+export function validateBuildingKitSource(scene, part, assets = []) {
+    const assignments = part.materialAssignments ?? [];
+    const errors = validateMaterialAssignments(assignments, assets, { disallowedTextureRoles: ["height"] }).filter(item => item.severity === "error");
+    if (errors.length > 0)
+        throw new Error(`Building kit ${part.model}: ${errors.map(item => `${item.path}: ${item.message}`).join("; ")}`);
+    validateMaterialAssignmentTargets(scene, assets, assignments);
+}
+/** Prepare one style's owned model materials before harvesting shared geometry for bounded instanced chunks. @internal */
+export function buildBuildingKitSources(scene, part, assets = [], surfaceTextures, assetTextures = new Map()) {
+    validateBuildingKitSource(scene, part, assets);
+    const prepared = buildScatterModelSources(scene, { url: part.model });
+    try {
+        const tint = part.tint === undefined || part.tint === "" ? undefined : new THREE.Color(part.tint);
+        prepared.root.traverseVisible(node => {
+            const mesh = node;
+            if (!mesh.isMesh)
+                return;
+            for (const material of Array.isArray(mesh.material) ? mesh.material : [mesh.material]) {
+                if (tint !== undefined && "color" in material)
+                    material.color.copy(tint);
+                if (part.material !== undefined && material.isMeshStandardMaterial)
+                    applyBuildingSurface(material, part.material, surfaceTextures);
+            }
+        });
+        if (part.materialAssignments?.length)
+            applyMaterialAssignments(prepared.root, assets, part.materialAssignments, assetTextures);
+        let index = 0;
+        prepared.root.traverseVisible(node => {
+            const mesh = node;
+            if (mesh.isMesh)
+                prepared.sources[index++].material = mesh.material;
+        });
+        return prepared;
+    }
+    catch (error) {
+        disposeScatterModelSources(prepared.root);
+        throw error;
+    }
+}

package/dist/structures/buildingSpatialBatch.d.ts

@@ -0,0 +1,11 @@
+import * as THREE from "three";
+/** A spatially bounded group of final, geometry-local instance matrices. @internal */
+export interface BuildingSpatialChunk {
+    key: string;
+    matrices: THREE.Matrix4[];
+    bounds: THREE.Box3;
+}
+/** Partition final geometry bounds without changing instance transforms or material groups. @internal */
+export declare function partitionBuildingMatrices(geometry: THREE.BufferGeometry, matrices: readonly THREE.Matrix4[], sourceMatrix?: THREE.Matrix4, cellSize?: number): BuildingSpatialChunk[];
+/** Install matrices and bounds; cleanup releases only the mesh's instance buffers, retaining shared assets. @internal */
+export declare function applyBuildingChunk(mesh: THREE.InstancedMesh, chunk: BuildingSpatialChunk): () => void;

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

@@ -11,6 +11,7 @@ export interface CarvedTerrainProps extends Omit<ThreeElements["mesh"], "args" |
     colors?: FieldGroundOptions["colors"];
     heightRange?: FieldGroundOptions["heightRange"];
     paletteAt?: FieldGroundOptions["paletteAt"];
+    paintColorAt?: FieldGroundOptions["paintColorAt"];
     roughness?: number;
     metalness?: number;
     /** Override the default vertex-colour material (e.g. a procedural detail material). The caller owns its lifecycle; it is not disposed here. */
@@ -23,4 +24,4 @@ export interface CarvedTerrainProps extends Omit<ThreeElements["mesh"], "args" |
  * Because the geometry samples `field.sampleHeight`, a `CarvableField.carve(...)` shows as a real bowl
  * once `epoch` changes. Pair with `InstancedBodies` to see debris resting in the crater it blasted.
  */
-export declare function CarvedTerrain({ field, size, segments, center, colors, heightRange, paletteAt, roughness, metalness, surfaceMaterial, receiveShadow, epoch, ...meshProps }: CarvedTerrainProps): import("react").JSX.Element;
+export declare function CarvedTerrain({ field, size, segments, center, colors, heightRange, paletteAt, paintColorAt, roughness, metalness, surfaceMaterial, receiveShadow, epoch, ...meshProps }: CarvedTerrainProps): import("react").JSX.Element;

package/dist/terrain/CarvedTerrain.js

@@ -8,8 +8,8 @@ import { createFieldGroundGeometry } from "./terrainMath.js";
  * Because the geometry samples `field.sampleHeight`, a `CarvableField.carve(...)` shows as a real bowl
  * once `epoch` changes. Pair with `InstancedBodies` to see debris resting in the crater it blasted.
  */
-export function CarvedTerrain({ field, size, segments, center, colors, heightRange, paletteAt, roughness = 0.95, metalness = 0, surfaceMaterial, receiveShadow = true, epoch = 0, ...meshProps }) {
-    const geometry = useDisposable(() => createFieldGroundGeometry(field, { size, segments, center, colors, heightRange, paletteAt }), [field, size, segments, center, colors, heightRange, paletteAt, epoch]);
+export function CarvedTerrain({ field, size, segments, center, colors, heightRange, paletteAt, paintColorAt, roughness = 0.95, metalness = 0, surfaceMaterial, receiveShadow = true, epoch = 0, ...meshProps }) {
+    const geometry = useDisposable(() => createFieldGroundGeometry(field, { size, segments, center, colors, heightRange, paletteAt, paintColorAt }), [field, size, segments, center, colors, heightRange, paletteAt, paintColorAt, epoch]);
     const defaultMaterial = useDisposable(() => new THREE.MeshStandardMaterial({ color: "#ffffff", roughness, metalness, vertexColors: true }), [metalness, roughness]);
     const material = surfaceMaterial ?? defaultMaterial;
     return _jsx("mesh", { ...meshProps, geometry: geometry, material: material, receiveShadow: receiveShadow });

package/dist/terrain/GrassField.d.ts

@@ -19,6 +19,7 @@ export interface GrassFieldProps extends Omit<ThreeElements["mesh"], "args" | "c
     edgeFeather?: number;
     exclude?: readonly GrassExclusion[];
     heightAt?: TerrainHeightSampler;
+    coverageAt?: TerrainHeightSampler;
     colorBase?: GrassMaterialOptions["colorBase"];
     colorTip?: GrassMaterialOptions["colorTip"];
     colorGround?: GrassMaterialOptions["colorGround"];
@@ -28,4 +29,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, coverageAt, 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, coverageAt, 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,
@@ -21,7 +23,9 @@ export function GrassField({ count = DEFAULT_GRASS_COUNT, density = DEFAULT_GRAS
         ...(edgeFeather === undefined ? {} : { edgeFeather }),
         ...(exclude === undefined ? {} : { exclude }),
         heightAt,
-    }), [area, bladeBend, bladeHeight, bladeWidth, count, edgeFeather, exclude, heightAt, seed, segments, tuftBlades, tuftRadius]);
+        coverageAt,
+    }), [area, bladeBend, bladeHeight, bladeWidth, count, coverageAt, edgeFeather, exclude, heightAt, seed, segments, tuftBlades, tuftRadius]);
+    useDisposable(() => chunks.map((chunk) => chunk.geometry), [chunks]);
     const handle = useMemo(() => createGrassMaterial({
         colorBase,
         colorTip,
@@ -34,10 +38,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

@@ -31,6 +31,8 @@ export interface GrassBladeGeometryOptions {
     /** Patch-local rectangles kept clear of blades (soil patches, water) with a soft regrow ramp. */
     exclude?: readonly GrassExclusion[];
     heightAt?: TerrainHeightSampler;
+    /** Patch-local coverage, 0..1, composed with explicit rectangular exclusions. */
+    coverageAt?: TerrainHeightSampler;
 }
 export interface ResolvedGrassBladeGeometryOptions {
     count: number;
@@ -45,6 +47,7 @@ export interface ResolvedGrassBladeGeometryOptions {
     edgeFeather: number;
     exclude: readonly GrassExclusion[];
     heightAt: TerrainHeightSampler;
+    coverageAt: TerrainHeightSampler;
 }
 /** @internal */
 export declare function resolveGrassRange(value: GrassRange | undefined, fallback: readonly [number, number]): readonly [number, number];
@@ -60,3 +63,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[];