@jgengine/core 0.5.0 → 0.7.0

package/dist/world/buildingIndex.d.ts

@@ -0,0 +1,16 @@
+import { type Aabb, type Vec2 } from "./geometry.js";
+import type { GeneratedBuilding } from "./buildings.js";
+export interface BuildingHit {
+    building: GeneratedBuilding;
+    distance: number;
+}
+export interface BuildingIndex {
+    readonly buildings: readonly GeneratedBuilding[];
+    at(point: Vec2): GeneratedBuilding | undefined;
+    within(area: Aabb): GeneratedBuilding[];
+    nearest(point: Vec2): BuildingHit | undefined;
+    isInside(point: Vec2): boolean;
+    blockers(margin?: number): Aabb[];
+    readonly bounds: Aabb | undefined;
+}
+export declare function buildingIndex(buildings: readonly GeneratedBuilding[]): BuildingIndex;

package/dist/world/buildingIndex.js

@@ -0,0 +1,63 @@
+import { aabbOverlap, expandAabb, pointInAabb } from "./geometry.js";
+function centerDistance(point, center) {
+    const dx = point[0] - center[0];
+    const dz = point[1] - center[1];
+    return Math.sqrt(dx * dx + dz * dz);
+}
+function unionBounds(buildings) {
+    if (buildings.length === 0)
+        return undefined;
+    let { minX, minZ, maxX, maxZ } = buildings[0].bounds;
+    for (let index = 1; index < buildings.length; index += 1) {
+        const b = buildings[index].bounds;
+        if (b.minX < minX)
+            minX = b.minX;
+        if (b.minZ < minZ)
+            minZ = b.minZ;
+        if (b.maxX > maxX)
+            maxX = b.maxX;
+        if (b.maxZ > maxZ)
+            maxZ = b.maxZ;
+    }
+    return { minX, minZ, maxX, maxZ };
+}
+export function buildingIndex(buildings) {
+    const bounds = unionBounds(buildings);
+    function at(point) {
+        let best;
+        let bestDistance = Infinity;
+        for (const building of buildings) {
+            if (!pointInAabb(point, building.bounds))
+                continue;
+            const distance = centerDistance(point, building.center);
+            if (distance < bestDistance) {
+                bestDistance = distance;
+                best = building;
+            }
+        }
+        return best;
+    }
+    return {
+        buildings,
+        bounds,
+        at,
+        within(area) {
+            return buildings.filter((building) => aabbOverlap(building.bounds, area));
+        },
+        nearest(point) {
+            let best;
+            for (const building of buildings) {
+                const distance = centerDistance(point, building.center);
+                if (best === undefined || distance < best.distance)
+                    best = { building, distance };
+            }
+            return best;
+        },
+        isInside(point) {
+            return at(point) !== undefined;
+        },
+        blockers(margin = 0) {
+            return buildings.map((building) => margin === 0 ? building.bounds : expandAabb(building.bounds, margin));
+        },
+    };
+}

package/dist/world/buildings.d.ts

@@ -0,0 +1,98 @@
+import { type Aabb, type Footprint, type Vec2 } from "./geometry.js";
+export type BuildingSeed = number | string;
+export type Vec3 = readonly [number, number, number];
+export type BuildingFacade = "front" | "back" | "left" | "right" | "roof";
+export type BuildingPartKind = "wall" | "window" | "awning" | "airConditioner" | "clothesline" | "storefront" | "shutter" | "storeSign" | "roof" | "roofProp" | "guardrail" | "corner";
+export type BuildingPartTag = "ground" | "upper" | "open" | "closed" | "decor" | "structure";
+export interface BuildingProbabilities {
+    window: number;
+    openStore: number;
+    awning: number;
+    airConditioner: number;
+    clothesline: number;
+    storeSign: number;
+    roofProp: number;
+}
+export interface BuildingVariantCounts {
+    wall: number;
+    window: number;
+    awning: number;
+    airConditioner: number;
+    clothesline: number;
+    storefront: number;
+    shutter: number;
+    storeSign: number;
+    roofProp: number;
+}
+export interface BuildingConfig {
+    id: string;
+    seed: BuildingSeed;
+    center: Vec2;
+    floors: number;
+    baysWide: number;
+    baysDeep: number;
+    bayWidth: number;
+    floorHeight: number;
+    facadeDepth: number;
+    roofOverhang: number;
+    probabilities: BuildingProbabilities;
+    variants: BuildingVariantCounts;
+}
+export type BuildingConfigInput = Partial<Omit<BuildingConfig, "probabilities" | "variants">> & {
+    probabilities?: Partial<BuildingProbabilities>;
+    variants?: Partial<BuildingVariantCounts>;
+};
+export interface BuildingKitSlot {
+    key: string;
+    variant: number;
+}
+export interface BuildingCellRef {
+    facade: BuildingFacade;
+    level: number;
+    bay: number;
+}
+export interface BuildingPartPlacement {
+    id: string;
+    buildingId: string;
+    kind: BuildingPartKind;
+    facade: BuildingFacade;
+    position: Vec3;
+    rotationY: number;
+    scale: Vec3;
+    kit: BuildingKitSlot;
+    cell?: BuildingCellRef;
+    tags?: readonly BuildingPartTag[];
+}
+export interface GeneratedBuilding {
+    id: string;
+    seed: BuildingSeed;
+    center: Vec2;
+    footprint: Footprint;
+    floors: number;
+    floorHeight: number;
+    bounds: Aabb;
+    parts: readonly BuildingPartPlacement[];
+}
+export interface BuildingLot {
+    id: string;
+    center: Vec2;
+    footprint: Footprint;
+    quarterTurns: number;
+    config: BuildingConfig;
+}
+export interface BuildingGridConfig {
+    rows: number;
+    columns: number;
+    origin?: Vec2;
+    lotSize?: Footprint;
+    streetWidth?: number;
+    seed?: BuildingSeed;
+    idPrefix?: string;
+    base?: BuildingConfigInput;
+    floorRange?: readonly [number, number];
+}
+export declare const DEFAULT_BUILDING_CONFIG: BuildingConfig;
+export declare function createBuildingConfig(input?: BuildingConfigInput): BuildingConfig;
+export declare function generateBuilding(input?: BuildingConfigInput): GeneratedBuilding;
+export declare function createBuildingGrid(config: BuildingGridConfig): BuildingLot[];
+export declare function generateBuildingDistrict(config: BuildingGridConfig): GeneratedBuilding[];

package/dist/world/buildings.js

@@ -0,0 +1,320 @@
+import { footprintAabb } from "./geometry.js";
+const DEFAULT_PROBABILITIES = {
+    window: 0.88,
+    openStore: 0.58,
+    awning: 0.45,
+    airConditioner: 0.42,
+    clothesline: 0.28,
+    storeSign: 0.62,
+    roofProp: 0.34,
+};
+const DEFAULT_VARIANTS = {
+    wall: 6,
+    window: 4,
+    awning: 3,
+    airConditioner: 3,
+    clothesline: 3,
+    storefront: 4,
+    shutter: 3,
+    storeSign: 5,
+    roofProp: 5,
+};
+export const DEFAULT_BUILDING_CONFIG = {
+    id: "building",
+    seed: 0,
+    center: [0, 0],
+    floors: 6,
+    baysWide: 6,
+    baysDeep: 3,
+    bayWidth: 2,
+    floorHeight: 2.8,
+    facadeDepth: 0.18,
+    roofOverhang: 0.35,
+    probabilities: DEFAULT_PROBABILITIES,
+    variants: DEFAULT_VARIANTS,
+};
+function hashU32(input) {
+    let hash = 2166136261;
+    for (let index = 0; index < input.length; index += 1) {
+        hash ^= input.charCodeAt(index);
+        hash = Math.imul(hash, 16777619);
+    }
+    hash ^= hash >>> 16;
+    hash = Math.imul(hash, 2246822507);
+    hash ^= hash >>> 13;
+    hash = Math.imul(hash, 3266489909);
+    hash ^= hash >>> 16;
+    return hash >>> 0;
+}
+function hash01(seed, key) {
+    return hashU32(`${seed}:${key}`) / 4294967296;
+}
+function probability(value) {
+    if (!Number.isFinite(value))
+        return 0;
+    return Math.min(Math.max(value, 0), 1);
+}
+function positiveInt(value, fallback) {
+    if (!Number.isFinite(value))
+        return fallback;
+    return Math.max(1, Math.floor(value));
+}
+function positiveNumber(value, fallback) {
+    return Number.isFinite(value) && value > 0 ? value : fallback;
+}
+function variantCount(value) {
+    return positiveInt(value, 1);
+}
+function variant(seed, key, count) {
+    return Math.floor(hash01(seed, key) * variantCount(count));
+}
+function chance(seed, key, p) {
+    return hash01(seed, key) < probability(p);
+}
+function rangeInt(seed, key, min, max) {
+    const lo = Math.min(min, max);
+    const hi = Math.max(min, max);
+    return lo + Math.floor(hash01(seed, key) * (hi - lo + 1));
+}
+export function createBuildingConfig(input = {}) {
+    return {
+        id: input.id ?? DEFAULT_BUILDING_CONFIG.id,
+        seed: input.seed ?? DEFAULT_BUILDING_CONFIG.seed,
+        center: input.center ?? DEFAULT_BUILDING_CONFIG.center,
+        floors: positiveInt(input.floors ?? DEFAULT_BUILDING_CONFIG.floors, DEFAULT_BUILDING_CONFIG.floors),
+        baysWide: positiveInt(input.baysWide ?? DEFAULT_BUILDING_CONFIG.baysWide, DEFAULT_BUILDING_CONFIG.baysWide),
+        baysDeep: positiveInt(input.baysDeep ?? DEFAULT_BUILDING_CONFIG.baysDeep, DEFAULT_BUILDING_CONFIG.baysDeep),
+        bayWidth: positiveNumber(input.bayWidth ?? DEFAULT_BUILDING_CONFIG.bayWidth, DEFAULT_BUILDING_CONFIG.bayWidth),
+        floorHeight: positiveNumber(input.floorHeight ?? DEFAULT_BUILDING_CONFIG.floorHeight, DEFAULT_BUILDING_CONFIG.floorHeight),
+        facadeDepth: positiveNumber(input.facadeDepth ?? DEFAULT_BUILDING_CONFIG.facadeDepth, DEFAULT_BUILDING_CONFIG.facadeDepth),
+        roofOverhang: Math.max(0, input.roofOverhang ?? DEFAULT_BUILDING_CONFIG.roofOverhang),
+        probabilities: {
+            window: probability(input.probabilities?.window ?? DEFAULT_PROBABILITIES.window),
+            openStore: probability(input.probabilities?.openStore ?? DEFAULT_PROBABILITIES.openStore),
+            awning: probability(input.probabilities?.awning ?? DEFAULT_PROBABILITIES.awning),
+            airConditioner: probability(input.probabilities?.airConditioner ?? DEFAULT_PROBABILITIES.airConditioner),
+            clothesline: probability(input.probabilities?.clothesline ?? DEFAULT_PROBABILITIES.clothesline),
+            storeSign: probability(input.probabilities?.storeSign ?? DEFAULT_PROBABILITIES.storeSign),
+            roofProp: probability(input.probabilities?.roofProp ?? DEFAULT_PROBABILITIES.roofProp),
+        },
+        variants: {
+            wall: variantCount(input.variants?.wall ?? DEFAULT_VARIANTS.wall),
+            window: variantCount(input.variants?.window ?? DEFAULT_VARIANTS.window),
+            awning: variantCount(input.variants?.awning ?? DEFAULT_VARIANTS.awning),
+            airConditioner: variantCount(input.variants?.airConditioner ?? DEFAULT_VARIANTS.airConditioner),
+            clothesline: variantCount(input.variants?.clothesline ?? DEFAULT_VARIANTS.clothesline),
+            storefront: variantCount(input.variants?.storefront ?? DEFAULT_VARIANTS.storefront),
+            shutter: variantCount(input.variants?.shutter ?? DEFAULT_VARIANTS.shutter),
+            storeSign: variantCount(input.variants?.storeSign ?? DEFAULT_VARIANTS.storeSign),
+            roofProp: variantCount(input.variants?.roofProp ?? DEFAULT_VARIANTS.roofProp),
+        },
+    };
+}
+function faceRotation(facade) {
+    if (facade === "front")
+        return Math.PI;
+    if (facade === "left")
+        return Math.PI / 2;
+    if (facade === "right")
+        return -Math.PI / 2;
+    return 0;
+}
+function faceDepth(facade, width, depth, config) {
+    if (facade === "front")
+        return config.center[1] + depth / 2 + config.facadeDepth / 2;
+    if (facade === "back")
+        return config.center[1] - depth / 2 - config.facadeDepth / 2;
+    if (facade === "left")
+        return config.center[0] - width / 2 - config.facadeDepth / 2;
+    return config.center[0] + width / 2 + config.facadeDepth / 2;
+}
+function panelPosition(config, facade, bay, level, width, depth) {
+    const y = level * config.floorHeight + config.floorHeight / 2;
+    if (facade === "front" || facade === "back") {
+        const x = config.center[0] - width / 2 + config.bayWidth * (bay + 0.5);
+        return [x, y, faceDepth(facade, width, depth, config)];
+    }
+    const z = config.center[1] - depth / 2 + config.bayWidth * (bay + 0.5);
+    return [faceDepth(facade, width, depth, config), y, z];
+}
+function panelScale(config, _facade, heightRatio, widthRatio = 0.92) {
+    const along = config.bayWidth * widthRatio;
+    const high = config.floorHeight * heightRatio;
+    return [along, high, config.facadeDepth];
+}
+function part(config, kind, facade, position, scale, key, cell, tags) {
+    const selectedVariant = kind === "airConditioner"
+        ? variant(config.seed, `${key}:variant`, config.variants.airConditioner)
+        : kind === "roofProp"
+            ? variant(config.seed, `${key}:variant`, config.variants.roofProp)
+            : kind === "storefront"
+                ? variant(config.seed, `${key}:variant`, config.variants.storefront)
+                : kind === "shutter"
+                    ? variant(config.seed, `${key}:variant`, config.variants.shutter)
+                    : kind === "storeSign"
+                        ? variant(config.seed, `${key}:variant`, config.variants.storeSign)
+                        : kind === "awning"
+                            ? variant(config.seed, `${key}:variant`, config.variants.awning)
+                            : kind === "clothesline"
+                                ? variant(config.seed, `${key}:variant`, config.variants.clothesline)
+                                : kind === "window"
+                                    ? variant(config.seed, `${key}:variant`, config.variants.window)
+                                    : kind === "wall"
+                                        ? variant(config.seed, `${key}:variant`, config.variants.wall)
+                                        : 0;
+    return {
+        id: `${config.id}:${key}:${kind}`,
+        buildingId: config.id,
+        kind,
+        facade,
+        position,
+        rotationY: faceRotation(facade),
+        scale,
+        kit: { key: `${facade}.${kind}`, variant: selectedVariant },
+        ...(cell === undefined ? {} : { cell }),
+        ...(tags === undefined ? {} : { tags }),
+    };
+}
+function pushUpperFloorParts(parts, config, facade, bay, level, width, depth) {
+    const cell = { facade, level, bay };
+    const key = `${facade}:${level}:${bay}`;
+    const position = panelPosition(config, facade, bay, level, width, depth);
+    parts.push(part(config, "wall", facade, position, panelScale(config, facade, 0.92), `${key}:wall`, cell, ["structure", "upper"]));
+    if (!chance(config.seed, `${key}:window`, config.probabilities.window))
+        return;
+    parts.push(part(config, "window", facade, position, panelScale(config, facade, 0.46, 0.58), `${key}:window`, cell, ["upper"]));
+    if (chance(config.seed, `${key}:awning`, config.probabilities.awning)) {
+        const awningPosition = [position[0], position[1] + config.floorHeight * 0.29, position[2]];
+        parts.push(part(config, "awning", facade, awningPosition, panelScale(config, facade, 0.1, 0.72), `${key}:awning`, cell, ["decor", "upper"]));
+    }
+    if (chance(config.seed, `${key}:ac`, config.probabilities.airConditioner)) {
+        const acPosition = [position[0], position[1] - config.floorHeight * 0.25, position[2]];
+        parts.push(part(config, "airConditioner", facade, acPosition, panelScale(config, facade, 0.16, 0.24), `${key}:ac`, cell, ["decor", "upper"]));
+    }
+    if (chance(config.seed, `${key}:clothesline`, config.probabilities.clothesline)) {
+        const linePosition = [position[0], position[1] - config.floorHeight * 0.36, position[2]];
+        parts.push(part(config, "clothesline", facade, linePosition, panelScale(config, facade, 0.04, 0.72), `${key}:line`, cell, ["decor", "upper"]));
+    }
+}
+function pushGroundFloorParts(parts, config, facade, bay, width, depth) {
+    const cell = { facade, level: 0, bay };
+    const key = `${facade}:0:${bay}`;
+    const position = panelPosition(config, facade, bay, 0, width, depth);
+    if (facade === "front" && chance(config.seed, `${key}:open`, config.probabilities.openStore)) {
+        parts.push(part(config, "storefront", facade, position, panelScale(config, facade, 0.86), `${key}:store`, cell, ["ground", "open"]));
+        if (chance(config.seed, `${key}:sign`, config.probabilities.storeSign)) {
+            const signPosition = [position[0], position[1] + config.floorHeight * 0.34, position[2]];
+            parts.push(part(config, "storeSign", facade, signPosition, panelScale(config, facade, 0.14, 0.76), `${key}:sign`, cell, ["decor", "ground"]));
+        }
+        return;
+    }
+    const kind = facade === "front" ? "shutter" : "wall";
+    parts.push(part(config, kind, facade, position, panelScale(config, facade, 0.86), `${key}:${kind}`, cell, ["ground", "closed"]));
+}
+function pushFacade(parts, config, facade, width, depth) {
+    const bays = facade === "front" || facade === "back" ? config.baysWide : config.baysDeep;
+    for (let bay = 0; bay < bays; bay += 1) {
+        pushGroundFloorParts(parts, config, facade, bay, width, depth);
+        for (let level = 1; level < config.floors; level += 1) {
+            pushUpperFloorParts(parts, config, facade, bay, level, width, depth);
+        }
+    }
+}
+function pushRoof(parts, config, width, depth) {
+    const height = config.floors * config.floorHeight;
+    parts.push(part(config, "roof", "roof", [config.center[0], height + config.facadeDepth / 2, config.center[1]], [width + config.roofOverhang * 2, config.facadeDepth, depth + config.roofOverhang * 2], "roof:slab", { facade: "roof", level: config.floors, bay: 0 }, ["structure"]));
+    const edges = ["front", "back", "left", "right"];
+    for (const facade of edges) {
+        const position = facade === "front" || facade === "back"
+            ? [config.center[0], height + config.floorHeight * 0.18, faceDepth(facade, width, depth, config)]
+            : [faceDepth(facade, width, depth, config), height + config.floorHeight * 0.18, config.center[1]];
+        const scale = facade === "front" || facade === "back"
+            ? [width + config.roofOverhang * 2, config.floorHeight * 0.28, config.facadeDepth]
+            : [depth + config.roofOverhang * 2, config.floorHeight * 0.28, config.facadeDepth];
+        parts.push(part(config, "guardrail", facade, position, scale, `roof:${facade}:rail`, undefined, ["structure"]));
+    }
+    const roofCells = config.baysWide * config.baysDeep;
+    for (let index = 0; index < roofCells; index += 1) {
+        if (!chance(config.seed, `roof:prop:${index}`, config.probabilities.roofProp))
+            continue;
+        const x = config.center[0] - width / 2 + config.bayWidth * ((index % config.baysWide) + 0.5);
+        const z = config.center[1] - depth / 2 + config.bayWidth * (Math.floor(index / config.baysWide) + 0.5);
+        parts.push(part(config, "roofProp", "roof", [x, height + config.facadeDepth + config.floorHeight * 0.16, z], [config.bayWidth * 0.34, config.floorHeight * 0.32, config.bayWidth * 0.34], `roof:prop:${index}`, { facade: "roof", level: config.floors, bay: index }, ["decor"]));
+    }
+}
+function pushCorners(parts, config, width, depth) {
+    const height = config.floors * config.floorHeight;
+    const positions = [
+        [config.center[0] - width / 2, height / 2, config.center[1] - depth / 2],
+        [config.center[0] + width / 2, height / 2, config.center[1] - depth / 2],
+        [config.center[0] - width / 2, height / 2, config.center[1] + depth / 2],
+        [config.center[0] + width / 2, height / 2, config.center[1] + depth / 2],
+    ];
+    positions.forEach((position, index) => {
+        parts.push(part(config, "corner", index < 2 ? "back" : "front", position, [config.facadeDepth * 1.35, height, config.facadeDepth * 1.35], `corner:${index}`, undefined, ["structure"]));
+    });
+}
+export function generateBuilding(input = {}) {
+    const config = createBuildingConfig(input);
+    const width = config.baysWide * config.bayWidth;
+    const depth = config.baysDeep * config.bayWidth;
+    const footprint = { w: width + config.roofOverhang * 2, d: depth + config.roofOverhang * 2 };
+    const parts = [];
+    pushFacade(parts, config, "front", width, depth);
+    pushFacade(parts, config, "back", width, depth);
+    pushFacade(parts, config, "left", width, depth);
+    pushFacade(parts, config, "right", width, depth);
+    pushCorners(parts, config, width, depth);
+    pushRoof(parts, config, width, depth);
+    return {
+        id: config.id,
+        seed: config.seed,
+        center: config.center,
+        footprint,
+        floors: config.floors,
+        floorHeight: config.floorHeight,
+        bounds: footprintAabb(config.center, footprint),
+        parts,
+    };
+}
+export function createBuildingGrid(config) {
+    const rows = positiveInt(config.rows, 1);
+    const columns = positiveInt(config.columns, 1);
+    const lotSize = config.lotSize ?? { w: 14, d: 10 };
+    const streetWidth = Math.max(0, config.streetWidth ?? 4);
+    const origin = config.origin ?? [0, 0];
+    const seed = config.seed ?? 0;
+    const idPrefix = config.idPrefix ?? "building";
+    const lots = [];
+    for (let row = 0; row < rows; row += 1) {
+        for (let column = 0; column < columns; column += 1) {
+            const index = row * columns + column;
+            const id = `${idPrefix}-${row}-${column}`;
+            const center = [
+                origin[0] + column * (lotSize.w + streetWidth),
+                origin[1] + row * (lotSize.d + streetWidth),
+            ];
+            const floorRange = config.floorRange ?? [3, 9];
+            const floors = rangeInt(seed, `${id}:floors`, floorRange[0], floorRange[1]);
+            const base = config.base ?? {};
+            const bayWidth = positiveNumber(base.bayWidth ?? DEFAULT_BUILDING_CONFIG.bayWidth, DEFAULT_BUILDING_CONFIG.bayWidth);
+            const baysWide = Math.max(1, Math.floor(lotSize.w / bayWidth));
+            const baysDeep = Math.max(1, Math.floor(lotSize.d / bayWidth));
+            const buildingConfig = createBuildingConfig({
+                ...base,
+                id,
+                seed: `${seed}:${index}`,
+                center,
+                floors,
+                baysWide: base.baysWide ?? baysWide,
+                baysDeep: base.baysDeep ?? baysDeep,
+                bayWidth,
+            });
+            lots.push({ id, center, footprint: lotSize, quarterTurns: 0, config: buildingConfig });
+        }
+    }
+    return lots;
+}
+export function generateBuildingDistrict(config) {
+    return createBuildingGrid(config).map((lot) => generateBuilding(lot.config));
+}

package/dist/world/carve.d.ts

@@ -0,0 +1,105 @@
+import { type TerrainField } from "./terrain.js";
+import type { WorldBounds } from "./features.js";
+export declare const EMPTY_VOXEL = 0;
+export interface VoxelMaterial {
+    /** Cell value stored in the grid; 0 is reserved for empty. */
+    id: number;
+    name: string;
+    /** A carve tool's strength must reach this to remove the material — hard rock resists a weak drill. Default 0 (anything digs it). */
+    strength: number;
+    /** Debris/harvest hint carried through to game code; the engine only tallies removed cells by id. */
+    drop?: string;
+}
+export type VoxelMaterialTable = Readonly<Record<number, VoxelMaterial>>;
+export interface VoxelVolumeConfig {
+    /** Grid resolution in cells: [nx, ny, nz]. */
+    dims: readonly [number, number, number];
+    /** World position of the min corner of cell [0,0,0]. Default [0,0,0]. */
+    origin?: readonly [number, number, number];
+    /** World-space edge length of one cubic cell. Default 1. */
+    scale?: number;
+    /** Material id every cell starts as. Default 1 (a solid volume waiting to be dug). */
+    fill?: number;
+    /** Strength lookup by material id; carve honours it against a tool strength. */
+    materials?: VoxelMaterialTable;
+}
+export interface CarveOp {
+    /** Sphere centre in world coordinates. */
+    center: readonly [number, number, number];
+    /** Sphere radius in world units. */
+    radius: number;
+    /** Only cells whose material `strength` is ≤ this are removed. Default Infinity (dig anything). */
+    toolStrength?: number;
+}
+export interface DepositOp {
+    center: readonly [number, number, number];
+    radius: number;
+    /** Material id to fill empty cells with (Engineer platform / Astroneer terrain add). */
+    material: number;
+}
+/**
+ * A runtime-editable dense voxel grid — the carve/deposit op behind destructible dig worlds (Deep
+ * Rock Galactic tunnels, Astroneer terrain). Cells hold a material id (0 = empty); `carve` clears a
+ * sphere of solid cells that a tool is strong enough to break and returns how many it removed (feed
+ * that to a loot roll), `deposit` fills a sphere with a material. World↔cell mapping is `origin`+`scale`.
+ */
+export declare class VoxelVolume {
+    readonly nx: number;
+    readonly ny: number;
+    readonly nz: number;
+    readonly scale: number;
+    readonly origin: readonly [number, number, number];
+    private readonly cells;
+    private readonly materials;
+    private solidCount;
+    constructor(config: VoxelVolumeConfig);
+    get solid(): number;
+    private index;
+    inBounds(ix: number, iy: number, iz: number): boolean;
+    get(ix: number, iy: number, iz: number): number;
+    set(ix: number, iy: number, iz: number, material: number): void;
+    worldToCell(x: number, y: number, z: number): readonly [number, number, number];
+    solidAtWorld(x: number, y: number, z: number): boolean;
+    private strengthOf;
+    private forEachCellInSphere;
+    /** Clear every solid cell in the sphere the tool can break; returns the number removed. */
+    carve(op: CarveOp): number;
+    /** Fill every empty cell in the sphere with `material`; returns the number filled. */
+    deposit(op: DepositOp): number;
+}
+export interface CraterOp {
+    /** Crater centre (x, z in world units). */
+    x: number;
+    z: number;
+    radius: number;
+    /** How deep the bowl cuts at its centre. */
+    depth: number;
+}
+export interface MoundOp {
+    x: number;
+    z: number;
+    radius: number;
+    /** How high the mound rises at its centre. */
+    height: number;
+}
+/**
+ * A `TerrainField` you can write craters and mounds into at runtime — the height-field side of
+ * destructible terrain (Helldivers 2 explosion craters, engineer-deposited berms). Wraps a base field
+ * and layers smooth radial deformations on top, so `sampleHeight` (and therefore ground-snap,
+ * collision, and the shell's terrain mesh) all read the deformed surface. `carve` digs a bowl,
+ * `deposit` raises a mound.
+ */
+export declare class CarvableField implements TerrainField {
+    readonly bounds?: WorldBounds;
+    readonly waterLevel?: number;
+    readonly sampleNormal: TerrainField["sampleNormal"];
+    private readonly base;
+    private readonly edits;
+    constructor(base: TerrainField);
+    get editCount(): number;
+    sampleHeight(x: number, z: number): number;
+    carve(op: CraterOp): void;
+    deposit(op: MoundOp): void;
+    clear(): void;
+}
+export declare function carvableTerrain(base: TerrainField): CarvableField;