@jgengine/core 0.5.0 → 0.7.0

package/dist/world/placementController.js

@@ -0,0 +1,97 @@
+import { footprintAabb, snapToGrid } from "./geometry.js";
+import { validatePlacement } from "./placement.js";
+const SNAP_ORDER = ["grid", "free", "surface"];
+export function quarterTurnsToRotationY(quarterTurns) {
+    const turns = ((quarterTurns % 4) + 4) % 4;
+    return turns === 0 ? 0 : -turns * (Math.PI / 2);
+}
+export function createPlacementController(config) {
+    let footprint = config.footprint;
+    let rules = config.rules ?? {};
+    let snapMode = config.snapMode ?? "grid";
+    let grid = config.grid ?? rules.snap ?? 1;
+    let quarterTurns = ((config.quarterTurns ?? 0) % 4 + 4) % 4;
+    let lastHit = null;
+    let preview = null;
+    function snapCenter(raw) {
+        if (snapMode === "grid")
+            return snapToGrid(raw, grid);
+        return raw;
+    }
+    function compute(hit) {
+        const raw = [hit.point[0], hit.point[2]];
+        const center = snapCenter(raw);
+        const rulesWithoutSnap = snapMode === "grid" ? { ...rules, snap: undefined } : rules;
+        const result = validatePlacement({ center, footprint, quarterTurns }, rulesWithoutSnap);
+        const aabb = result.status === "ok" ? result.aabb : footprintAabb(center, footprint, quarterTurns);
+        const next = {
+            center: result.status === "ok" ? result.center : center,
+            y: hit.point[1],
+            quarterTurns,
+            footprint,
+            aabb,
+            valid: result.status === "ok",
+            snapMode,
+            normal: hit.normal,
+            ...(result.status === "rejected" ? { reason: result.reason } : {}),
+        };
+        preview = next;
+        return next;
+    }
+    return {
+        hover(hit) {
+            lastHit = hit;
+            return compute(hit);
+        },
+        current() {
+            return preview;
+        },
+        rotate(steps = 1) {
+            quarterTurns = ((quarterTurns + steps) % 4 + 4) % 4;
+            return lastHit === null ? null : compute(lastHit);
+        },
+        setSnapMode(mode) {
+            snapMode = mode;
+            return lastHit === null ? null : compute(lastHit);
+        },
+        cycleSnapMode() {
+            const index = SNAP_ORDER.indexOf(snapMode);
+            snapMode = SNAP_ORDER[(index + 1) % SNAP_ORDER.length];
+            if (lastHit !== null)
+                compute(lastHit);
+            return snapMode;
+        },
+        setFootprint(next) {
+            footprint = next;
+            if (lastHit !== null)
+                compute(lastHit);
+        },
+        setRules(next) {
+            rules = next;
+            if (lastHit !== null)
+                compute(lastHit);
+        },
+        setGrid(next) {
+            grid = next;
+            if (lastHit !== null)
+                compute(lastHit);
+        },
+        commit() {
+            if (preview === null || !preview.valid)
+                return null;
+            return {
+                center: preview.center,
+                y: preview.y,
+                rotationY: quarterTurnsToRotationY(quarterTurns),
+                quarterTurns,
+                footprint: preview.footprint,
+                aabb: preview.aabb,
+            };
+        },
+        reset() {
+            lastHit = null;
+            preview = null;
+            quarterTurns = ((config.quarterTurns ?? 0) % 4 + 4) % 4;
+        },
+    };
+}

package/dist/world/realm.d.ts

@@ -0,0 +1,61 @@
+import { type EnvironmentField, type EnvironmentFieldConfig } from "./envField.js";
+import type { WeatherState } from "./weather.js";
+/** The recomposable environment parameters a realm card can override. */
+export interface RealmEnvironmentParams {
+    baseTemperature: number;
+    nightDrop: number;
+    altitudeLapse: number;
+    /** Game-seconds per day (a "long night" minor card shortens the day cycle). */
+    dayLength: number;
+    /** Ambient rain intensity 0..1. */
+    rain: number;
+    /** Ambient light floor 0..1 (moonlight). */
+    ambientFloor: number;
+}
+export declare const DEFAULT_REALM_ENVIRONMENT: RealmEnvironmentParams;
+/** Spawn-table edits a card layers on: replace weights, add/scale, or remove ids. */
+export interface SpawnTableOverride {
+    set?: Record<string, number>;
+    add?: Record<string, number>;
+    scale?: Record<string, number>;
+    remove?: readonly string[];
+}
+export interface RealmCard {
+    id: string;
+    /** A major card sets the biome base; minors layer weather/day-length/aesthetic on top. */
+    kind: "major" | "minor";
+    /** Environment param overrides (last write wins across the ordered deck). */
+    environment?: Partial<RealmEnvironmentParams>;
+    /** Weather state overrides (kind/intensity/wind). */
+    weather?: Partial<WeatherState>;
+    /** Spawn-table edits applied in deck order. */
+    spawn?: SpawnTableOverride;
+    /** Opaque aesthetic tag (skybox, palette) the renderer maps — engine never inspects it. */
+    aesthetic?: string;
+}
+export interface RealmBase {
+    environment?: Partial<RealmEnvironmentParams>;
+    weather?: WeatherState;
+    spawn?: Record<string, number>;
+}
+export interface ComposedRealm {
+    params: RealmEnvironmentParams;
+    weather: WeatherState;
+    spawnTable: Record<string, number>;
+    aesthetics: readonly string[];
+    cards: readonly RealmCard[];
+    /**
+     * Build an environment field (#91) from the composed params, wired to the composed
+     * weather's rain intensity. Extra config (terrain, occluders, heat sources) merges on top.
+     */
+    environmentField(extra?: Omit<EnvironmentFieldConfig, "baseTemperature" | "nightDrop" | "altitudeLapse" | "dayLength" | "rain" | "ambientFloor">): EnvironmentField;
+}
+/**
+ * Assemble a played realm instance at runtime from a deck of modifier cards — the
+ * Nightingale "realm card" model. A major card is the biome base; minor cards layer
+ * weather, day length, and spawn edits. The result recomposes both the environment
+ * (into a sampleable field via `environmentField()`) and the spawn table, and it depends
+ * on the weather hooks in this group (#92) to turn its `weather` into gameplay modifiers.
+ * Cards apply in array order; sort your deck (majors first) before composing.
+ */
+export declare function composeRealm(base: RealmBase, cards: readonly RealmCard[]): ComposedRealm;

package/dist/world/realm.js

@@ -0,0 +1,66 @@
+import { createEnvironmentField } from "./envField.js";
+export const DEFAULT_REALM_ENVIRONMENT = {
+    baseTemperature: 20,
+    nightDrop: 12,
+    altitudeLapse: 0,
+    dayLength: 24 * 3600,
+    rain: 0,
+    ambientFloor: 0.05,
+};
+function applySpawn(table, override) {
+    if (override === undefined)
+        return;
+    if (override.set !== undefined)
+        for (const [id, weight] of Object.entries(override.set))
+            table[id] = weight;
+    if (override.add !== undefined)
+        for (const [id, weight] of Object.entries(override.add))
+            table[id] = (table[id] ?? 0) + weight;
+    if (override.scale !== undefined)
+        for (const [id, factor] of Object.entries(override.scale))
+            table[id] = (table[id] ?? 0) * factor;
+    if (override.remove !== undefined)
+        for (const id of override.remove)
+            delete table[id];
+}
+/**
+ * Assemble a played realm instance at runtime from a deck of modifier cards — the
+ * Nightingale "realm card" model. A major card is the biome base; minor cards layer
+ * weather, day length, and spawn edits. The result recomposes both the environment
+ * (into a sampleable field via `environmentField()`) and the spawn table, and it depends
+ * on the weather hooks in this group (#92) to turn its `weather` into gameplay modifiers.
+ * Cards apply in array order; sort your deck (majors first) before composing.
+ */
+export function composeRealm(base, cards) {
+    const params = { ...DEFAULT_REALM_ENVIRONMENT, ...base.environment };
+    let weather = base.weather ?? { kind: "clear", intensity: 0 };
+    const spawnTable = { ...base.spawn };
+    const aesthetics = [];
+    for (const card of cards) {
+        if (card.environment !== undefined)
+            Object.assign(params, card.environment);
+        if (card.weather !== undefined)
+            weather = { ...weather, ...card.weather };
+        applySpawn(spawnTable, card.spawn);
+        if (card.aesthetic !== undefined)
+            aesthetics.push(card.aesthetic);
+    }
+    return {
+        params,
+        weather,
+        spawnTable,
+        aesthetics,
+        cards,
+        environmentField(extra) {
+            return createEnvironmentField({
+                ...extra,
+                baseTemperature: params.baseTemperature,
+                nightDrop: params.nightDrop,
+                altitudeLapse: params.altitudeLapse,
+                dayLength: params.dayLength,
+                rain: weather.kind === "clear" ? 0 : params.rain,
+                ambientFloor: params.ambientFloor,
+            });
+        },
+    };
+}

package/dist/world/regions.d.ts

@@ -0,0 +1,66 @@
+import type { WorldBounds } from "./features.js";
+import { type TerrainField } from "./terrain.js";
+export type Rgb = readonly [number, number, number];
+export type ColorInput = string | Rgb;
+export interface RegionHeight {
+    baseHeight: number;
+    amplitude: number;
+    frequency: number;
+    octaves?: number;
+    lacunarity?: number;
+    persistence?: number;
+    ridged?: boolean;
+}
+/**
+ * A content-agnostic region. The engine blends `height` and the visual/physical
+ * knobs (`tint`, `water`, `fog`, `speedMultiplier`, …) across region borders and
+ * selects the dominant region by nearest center in `selector` space. `data` is an
+ * opaque payload the engine never inspects — games hang their own content off it
+ * (spawn tables, prop palettes, structure ids, names, …).
+ */
+export interface RegionDef<T = unknown> {
+    id: string;
+    selector: readonly number[];
+    height: RegionHeight;
+    tint?: ColorInput;
+    steepTint?: ColorInput;
+    water?: ColorInput;
+    fog?: ColorInput;
+    fogDensity?: number;
+    speedMultiplier?: number;
+    data?: T;
+}
+export interface RegionSample<T = unknown> {
+    region: RegionDef<T>;
+    weight: number;
+    selector: readonly number[];
+    tint: Rgb;
+    steepTint: Rgb;
+    water: Rgb | null;
+    fog: Rgb | null;
+    fogDensity: number;
+    speedMultiplier: number;
+    data: T | undefined;
+}
+export interface RegionField<T = unknown> extends TerrainField {
+    sampleRegion(x: number, z: number): RegionSample<T>;
+    readonly regions: readonly RegionDef<T>[];
+    readonly seaLevel: number;
+    readonly seed: number;
+}
+export interface RegionFieldConfig<T = unknown> {
+    regions: readonly RegionDef<T>[];
+    seed?: number;
+    bounds?: WorldBounds;
+    seaLevel?: number;
+    /** Noise frequency per selector axis (defaults to 0.004 for every axis). */
+    selectorFrequencies?: readonly number[];
+    /** Per-axis distance weight when picking the nearest region (defaults to 1). */
+    axisWeights?: readonly number[];
+    /** Border sharpness; higher = tighter blends. */
+    sharpness?: number;
+    /** Domain-warp distance applied to selector sampling (0 disables). */
+    warp?: number;
+}
+export declare function createRegionField<T = unknown>(config: RegionFieldConfig<T>): RegionField<T>;
+export declare function isRegionField(field: TerrainField): field is RegionField;

package/dist/world/regions.js

@@ -0,0 +1,158 @@
+import { fractalNoise, withNormal, } from "./terrain.js";
+function toRgb(color, fallback) {
+    if (color === undefined)
+        return fallback;
+    if (typeof color !== "string")
+        return color;
+    const value = color.startsWith("#") ? color.slice(1) : color;
+    const int = Number.parseInt(value, 16);
+    return [((int >> 16) & 255) / 255, ((int >> 8) & 255) / 255, (int & 255) / 255];
+}
+function clamp01(value) {
+    return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+function selectorNoise(x, z, seed, frequency) {
+    const config = { seed, frequency, octaves: 3, lacunarity: 2, persistence: 0.5, ridged: false };
+    return clamp01(0.5 + fractalNoise(x, z, config) * 0.9);
+}
+const DEFAULT_SELECTOR_FREQUENCY = 0.004;
+const DEFAULT_SHARPNESS = 6;
+export function createRegionField(config) {
+    if (config.regions.length === 0)
+        throw new Error("createRegionField: regions must be non-empty");
+    const seed = config.seed ?? 1337;
+    const regions = config.regions;
+    const seaLevel = config.seaLevel ?? 0;
+    const axes = regions[0].selector.length;
+    const sharpness = config.sharpness ?? DEFAULT_SHARPNESS;
+    const warp = config.warp ?? 40;
+    const heightConfigs = regions.map((region) => ({
+        seed: seed ^ hashId(region.id),
+        frequency: region.height.frequency,
+        octaves: region.height.octaves ?? 4,
+        lacunarity: region.height.lacunarity ?? 2,
+        persistence: region.height.persistence ?? 0.5,
+        ridged: region.height.ridged ?? false,
+    }));
+    const tints = regions.map((region) => toRgb(region.tint, [0.4, 0.42, 0.38]));
+    const steeps = regions.map((region, index) => toRgb(region.steepTint, tints[index]));
+    const waters = regions.map((region) => (region.water !== undefined ? toRgb(region.water, [0, 0, 0]) : null));
+    const fogs = regions.map((region) => (region.fog !== undefined ? toRgb(region.fog, [0, 0, 0]) : null));
+    const axisSeeds = Array.from({ length: axes }, (_, axis) => seed ^ (0x1111 * (axis + 1)));
+    const axisFrequencies = Array.from({ length: axes }, (_, axis) => config.selectorFrequencies?.[axis] ?? DEFAULT_SELECTOR_FREQUENCY);
+    const axisWeights = Array.from({ length: axes }, (_, axis) => config.axisWeights?.[axis] ?? 1);
+    const warpConfig = { seed: seed ^ 0x9e3779b1, frequency: 0.006, octaves: 2, lacunarity: 2, persistence: 0.5, ridged: false };
+    const sampleSelector = (x, z) => {
+        const wx = warp === 0 ? x : x + fractalNoise(x, z, warpConfig) * warp;
+        const wz = warp === 0 ? z : z + fractalNoise(z, x, warpConfig) * warp;
+        const values = new Array(axes);
+        for (let axis = 0; axis < axes; axis += 1) {
+            values[axis] = selectorNoise(wx, wz, axisSeeds[axis], axisFrequencies[axis]);
+        }
+        return values;
+    };
+    const weightsFor = (selector) => {
+        const raw = new Array(regions.length);
+        let total = 0;
+        for (let index = 0; index < regions.length; index += 1) {
+            const center = regions[index].selector;
+            let distanceSq = 0;
+            for (let axis = 0; axis < axes; axis += 1) {
+                const delta = (selector[axis] - center[axis]) * axisWeights[axis];
+                distanceSq += delta * delta;
+            }
+            const weight = Math.exp(-distanceSq * sharpness * regions.length);
+            raw[index] = weight;
+            total += weight;
+        }
+        if (total > 0)
+            for (let index = 0; index < raw.length; index += 1)
+                raw[index] /= total;
+        return raw;
+    };
+    const regionHeight = (index, x, z) => regions[index].height.baseHeight + regions[index].height.amplitude * fractalNoise(x, z, heightConfigs[index]);
+    const sampleHeight = (x, z) => {
+        const weights = weightsFor(sampleSelector(x, z));
+        let height = 0;
+        for (let index = 0; index < weights.length; index += 1) {
+            if (weights[index] < 0.01)
+                continue;
+            height += weights[index] * regionHeight(index, x, z);
+        }
+        return height;
+    };
+    const sampleRegion = (x, z) => {
+        const selector = sampleSelector(x, z);
+        const weights = weightsFor(selector);
+        let dominant = 0;
+        const tint = [0, 0, 0];
+        const steep = [0, 0, 0];
+        const water = [0, 0, 0];
+        let waterWeight = 0;
+        const fog = [0, 0, 0];
+        let fogWeight = 0;
+        let fogDensity = 0;
+        let speed = 0;
+        let speedWeight = 0;
+        for (let index = 0; index < weights.length; index += 1) {
+            const weight = weights[index];
+            if (weight > weights[dominant])
+                dominant = index;
+            if (weight < 0.01)
+                continue;
+            for (let channel = 0; channel < 3; channel += 1) {
+                tint[channel] += tints[index][channel] * weight;
+                steep[channel] += steeps[index][channel] * weight;
+            }
+            const w = waters[index];
+            if (w !== null) {
+                for (let channel = 0; channel < 3; channel += 1)
+                    water[channel] += w[channel] * weight;
+                waterWeight += weight;
+            }
+            const f = fogs[index];
+            if (f !== null) {
+                for (let channel = 0; channel < 3; channel += 1)
+                    fog[channel] += f[channel] * weight;
+                fogWeight += weight;
+                fogDensity += (regions[index].fogDensity ?? 0) * weight;
+            }
+            speed += (regions[index].speedMultiplier ?? 1) * weight;
+            speedWeight += weight;
+        }
+        const normalize = (rgb, weight) => weight > 0 ? [rgb[0] / weight, rgb[1] / weight, rgb[2] / weight] : rgb;
+        return {
+            region: regions[dominant],
+            weight: weights[dominant],
+            selector,
+            tint,
+            steepTint: steep,
+            water: waterWeight > 0.05 ? normalize(water, waterWeight) : null,
+            fog: fogWeight > 0.05 ? normalize(fog, fogWeight) : null,
+            fogDensity: fogWeight > 0.05 ? fogDensity / fogWeight : 0,
+            speedMultiplier: speedWeight > 0 ? speed / speedWeight : 1,
+            data: regions[dominant].data,
+        };
+    };
+    return {
+        sampleHeight,
+        sampleNormal: withNormal(sampleHeight),
+        sampleRegion,
+        regions,
+        seaLevel,
+        seed,
+        waterLevel: seaLevel,
+        bounds: config.bounds,
+    };
+}
+function hashId(id) {
+    let hash = 2166136261;
+    for (let index = 0; index < id.length; index += 1) {
+        hash ^= id.charCodeAt(index);
+        hash = Math.imul(hash, 16777619);
+    }
+    return hash | 0;
+}
+export function isRegionField(field) {
+    return "sampleRegion" in field;
+}

package/dist/world/scatter.d.ts

@@ -0,0 +1,24 @@
+import { type Aabb, type Vec2 } from "./geometry.js";
+export interface ScatterArea {
+    w: number;
+    d: number;
+    center?: Vec2;
+}
+export interface ScatterConfig {
+    area: ScatterArea | Aabb;
+    count?: number;
+    density?: number;
+    seed?: string | number;
+    minDistance?: number;
+    avoid?: readonly Aabb[];
+    avoidMargin?: number;
+    jitter?: number;
+    maxAttempts?: number;
+}
+export interface ScatterPoint {
+    x: number;
+    z: number;
+    index: number;
+}
+export declare function scatterAabb(area: ScatterArea | Aabb): Aabb;
+export declare function scatter(config: ScatterConfig): ScatterPoint[];

package/dist/world/scatter.js

@@ -0,0 +1,126 @@
+import { expandAabb, pointInAabb } from "./geometry.js";
+function isAabb(area) {
+    return (typeof area.minX === "number" &&
+        typeof area.minZ === "number" &&
+        typeof area.maxX === "number" &&
+        typeof area.maxZ === "number");
+}
+export function scatterAabb(area) {
+    if (isAabb(area)) {
+        return { minX: area.minX, minZ: area.minZ, maxX: area.maxX, maxZ: area.maxZ };
+    }
+    const cx = area.center ? area.center[0] : 0;
+    const cz = area.center ? area.center[1] : 0;
+    const halfW = area.w / 2;
+    const halfD = area.d / 2;
+    return { minX: cx - halfW, minZ: cz - halfD, maxX: cx + halfW, maxZ: cz + halfD };
+}
+function hashSeed(seed) {
+    const text = typeof seed === "number" ? seed.toString() : seed;
+    let h = 2166136261 >>> 0;
+    for (let i = 0; i < text.length; i++) {
+        h ^= text.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return h >>> 0;
+}
+function mulberry32(state) {
+    let a = state >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = a;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+export function scatter(config) {
+    const aabb = scatterAabb(config.area);
+    const width = aabb.maxX - aabb.minX;
+    const depth = aabb.maxZ - aabb.minZ;
+    const density = config.density ?? 0.01;
+    const target = config.count ?? Math.max(0, Math.floor(width * depth * density));
+    if (target <= 0 || width <= 0 || depth <= 0)
+        return [];
+    const minDistance = config.minDistance ?? 0;
+    const avoidMargin = config.avoidMargin ?? 0;
+    const jitter = config.jitter ?? 1;
+    const maxAttempts = config.maxAttempts ?? target * 30;
+    const avoid = (config.avoid ?? []).map((a) => (avoidMargin !== 0 ? expandAabb(a, avoidMargin) : a));
+    const rng = mulberry32(hashSeed(config.seed ?? "scatter"));
+    const useDistance = minDistance > 0;
+    const buckets = new Map();
+    const bucketKey = (x, z) => `${Math.floor(x / minDistance)}:${Math.floor(z / minDistance)}`;
+    const rejectedByAvoid = (point) => {
+        for (const a of avoid)
+            if (pointInAabb(point, a))
+                return true;
+        return false;
+    };
+    const rejectedByDistance = (point) => {
+        if (!useDistance)
+            return false;
+        const cx = Math.floor(point[0] / minDistance);
+        const cz = Math.floor(point[1] / minDistance);
+        const minSq = minDistance * minDistance;
+        for (let dx = -1; dx <= 1; dx++) {
+            for (let dz = -1; dz <= 1; dz++) {
+                const nearby = buckets.get(`${cx + dx}:${cz + dz}`);
+                if (!nearby)
+                    continue;
+                for (const other of nearby) {
+                    const ex = other[0] - point[0];
+                    const ez = other[1] - point[1];
+                    if (ex * ex + ez * ez < minSq)
+                        return true;
+                }
+            }
+        }
+        return false;
+    };
+    const accepted = [];
+    const commit = (point) => {
+        accepted.push({ x: point[0], z: point[1], index: accepted.length });
+        if (useDistance) {
+            const key = bucketKey(point[0], point[1]);
+            const bucket = buckets.get(key);
+            if (bucket)
+                bucket.push(point);
+            else
+                buckets.set(key, [point]);
+        }
+    };
+    const cols = Math.max(1, Math.ceil(Math.sqrt(target * (width / depth))));
+    const rows = Math.max(1, Math.ceil(target / cols));
+    const cellW = width / cols;
+    const cellD = depth / rows;
+    for (let row = 0; row < rows && accepted.length < target; row++) {
+        for (let col = 0; col < cols && accepted.length < target; col++) {
+            const baseX = aabb.minX + (col + 0.5) * cellW;
+            const baseZ = aabb.minZ + (row + 0.5) * cellD;
+            const x = baseX + jitter * (rng() - 0.5) * cellW;
+            const z = baseZ + jitter * (rng() - 0.5) * cellD;
+            const point = [x, z];
+            if (!pointInAabb(point, aabb))
+                continue;
+            if (rejectedByAvoid(point))
+                continue;
+            if (rejectedByDistance(point))
+                continue;
+            commit(point);
+        }
+    }
+    let attempts = 0;
+    while (accepted.length < target && attempts < maxAttempts) {
+        attempts++;
+        const x = aabb.minX + rng() * width;
+        const z = aabb.minZ + rng() * depth;
+        const point = [x, z];
+        if (rejectedByAvoid(point))
+            continue;
+        if (rejectedByDistance(point))
+            continue;
+        commit(point);
+    }
+    return accepted;
+}

package/dist/world/scatterItems.d.ts

@@ -0,0 +1,38 @@
+import type { Aabb } from "./geometry.js";
+import type { RegionField, RegionSample } from "./regions.js";
+/** One placeable class. `item` is an opaque id the caller maps to a mesh/entity. */
+export interface ScatterLayer {
+    item: string;
+    density: number;
+    minScale?: number;
+    maxScale?: number;
+    maxSlope?: number;
+    aboveWaterOnly?: boolean;
+}
+export interface ScatterInstance {
+    id: string;
+    item: string;
+    x: number;
+    z: number;
+    y: number;
+    scale: number;
+    rotation: number;
+    regionId: string;
+}
+/**
+ * Deterministically place opaque items across `area`, grounded on a region field.
+ * For each grid cell it asks `layersFor` which items may appear in that region and
+ * rolls one against their densities. The engine never interprets `item` — a game
+ * maps it to a mesh or entity. Content scatter (region-driven density) as opposed to
+ * `scatter` in `./scatter`, which is renderer-free geometric point distribution.
+ */
+export declare function scatterItems<T>(field: RegionField<T>, area: Aabb, layersFor: (sample: RegionSample<T>) => readonly ScatterLayer[], options?: {
+    cell?: number;
+    max?: number;
+    saltKey?: number;
+}): ScatterInstance[];
+/** Weighted pick from opaque entries; `roll` in [0, 1). Returns null when empty. */
+export declare function pickWeighted<T>(entries: readonly {
+    value: T;
+    weight: number;
+}[], roll: number): T | null;