@jgengine/core 0.5.0 → 0.6.0

package/dist/world/features.d.ts

@@ -2,6 +2,103 @@ export interface WorldBounds {
     w: number;
     d: number;
 }
+export type EnvironmentVec2 = readonly [number, number];
+export interface EnvironmentArea extends WorldBounds {
+    h?: number;
+}
+export interface TerrainEnvironmentConfig {
+    bounds?: WorldBounds;
+    height?: number;
+    heightMap?: string;
+    material?: string;
+    seed?: string;
+    frequency?: number;
+    octaves?: number;
+    ridged?: boolean;
+    baseHeight?: number;
+    waterLevel?: number;
+}
+export interface RainEnvironmentConfig {
+    area?: EnvironmentArea;
+    density?: number;
+    speed?: number;
+    dropLength?: number;
+    wind?: EnvironmentVec2;
+    color?: string;
+}
+export interface SnowEnvironmentConfig {
+    area?: EnvironmentArea;
+    density?: number;
+    speed?: number;
+    flakeSize?: number;
+    drift?: number;
+    wind?: EnvironmentVec2;
+    color?: string;
+}
+export interface GrassEnvironmentConfig {
+    area?: WorldBounds;
+    density?: number;
+    bladeHeight?: readonly [number, number];
+    bladeWidth?: number;
+    windStrength?: number;
+    colors?: readonly string[];
+    seed?: string;
+}
+export interface OceanEnvironmentConfig {
+    bounds?: WorldBounds;
+    level?: number;
+    waveHeight?: number;
+    waveScale?: number;
+    waveSpeed?: number;
+    color?: string;
+}
+export interface BuildingEnvironmentConfig {
+    count?: number;
+    footprint?: WorldBounds;
+    stories?: readonly [number, number];
+    storyHeight?: number;
+    spacing?: number;
+    style?: string;
+    seed?: string;
+}
+export type TerrainEnvironmentDescriptor = {
+    kind: "terrain";
+} & Required<Pick<TerrainEnvironmentConfig, "bounds" | "height">> & Omit<TerrainEnvironmentConfig, "bounds" | "height">;
+export type RainEnvironmentDescriptor = {
+    kind: "rain";
+} & Required<Pick<RainEnvironmentConfig, "area" | "density" | "speed" | "dropLength" | "wind" | "color">>;
+export type SnowEnvironmentDescriptor = {
+    kind: "snow";
+} & Required<Pick<SnowEnvironmentConfig, "area" | "density" | "speed" | "flakeSize" | "drift" | "wind" | "color">>;
+export type GrassEnvironmentDescriptor = {
+    kind: "grass";
+} & Required<Pick<GrassEnvironmentConfig, "area" | "density" | "bladeHeight" | "bladeWidth" | "windStrength" | "colors">> & Pick<GrassEnvironmentConfig, "seed">;
+export type OceanEnvironmentDescriptor = {
+    kind: "ocean";
+} & Required<Pick<OceanEnvironmentConfig, "bounds" | "level" | "waveHeight" | "waveScale" | "waveSpeed" | "color">>;
+export type BuildingEnvironmentDescriptor = {
+    kind: "building";
+} & Required<Pick<BuildingEnvironmentConfig, "count" | "footprint" | "stories" | "storyHeight" | "spacing" | "style">> & Pick<BuildingEnvironmentConfig, "seed">;
+export type WeatherEnvironmentDescriptor = RainEnvironmentDescriptor | SnowEnvironmentDescriptor;
+export type VegetationEnvironmentDescriptor = GrassEnvironmentDescriptor;
+export type WaterEnvironmentDescriptor = OceanEnvironmentDescriptor;
+export type StructureEnvironmentDescriptor = BuildingEnvironmentDescriptor;
+export type EnvironmentDescriptorList<T> = T | readonly T[];
+export interface EnvironmentWorldConfig {
+    terrain?: TerrainEnvironmentDescriptor;
+    weather?: EnvironmentDescriptorList<WeatherEnvironmentDescriptor>;
+    vegetation?: EnvironmentDescriptorList<VegetationEnvironmentDescriptor>;
+    water?: EnvironmentDescriptorList<WaterEnvironmentDescriptor>;
+    structures?: EnvironmentDescriptorList<StructureEnvironmentDescriptor>;
+}
+export interface EnvironmentWorldFeature {
+    kind: "environment";
+    terrain?: TerrainEnvironmentDescriptor;
+    weather?: readonly WeatherEnvironmentDescriptor[];
+    vegetation?: readonly VegetationEnvironmentDescriptor[];
+    water?: readonly WaterEnvironmentDescriptor[];
+    structures?: readonly StructureEnvironmentDescriptor[];
+}
 export interface BiomesWorldConfig {
     map: string;
     zones: string;
@@ -29,9 +126,16 @@ export type WorldFeature = ({
     kind: "plots";
 } & PlotsWorldConfig) | ({
     kind: "tilemap";
-} & TilemapWorldConfig) | {
+} & TilemapWorldConfig) | EnvironmentWorldFeature | {
     kind: "flat";
 };
+export declare function environment(config?: EnvironmentWorldConfig): EnvironmentWorldFeature;
+export declare function terrain(config?: TerrainEnvironmentConfig): TerrainEnvironmentDescriptor;
+export declare function rain(config?: RainEnvironmentConfig): RainEnvironmentDescriptor;
+export declare function snow(config?: SnowEnvironmentConfig): SnowEnvironmentDescriptor;
+export declare function grass(config?: GrassEnvironmentConfig): GrassEnvironmentDescriptor;
+export declare function ocean(config?: OceanEnvironmentConfig): OceanEnvironmentDescriptor;
+export declare function building(config?: BuildingEnvironmentConfig): BuildingEnvironmentDescriptor;
 export declare function biomes(config: BiomesWorldConfig): WorldFeature;
 export declare function voxel(config: VoxelWorldConfig): WorldFeature;
 export declare function plots(config?: PlotsWorldConfig): WorldFeature;

package/dist/world/features.js

@@ -1,3 +1,98 @@
+function list(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    return Array.isArray(value) ? value : [value];
+}
+function withOptional(base, optional) {
+    return optional === undefined ? base : { ...base, ...optional };
+}
+export function environment(config = {}) {
+    const weather = list(config.weather);
+    const vegetation = list(config.vegetation);
+    const water = list(config.water);
+    const structures = list(config.structures);
+    return {
+        kind: "environment",
+        ...(config.terrain === undefined ? {} : { terrain: config.terrain }),
+        ...(weather === undefined ? {} : { weather }),
+        ...(vegetation === undefined ? {} : { vegetation }),
+        ...(water === undefined ? {} : { water }),
+        ...(structures === undefined ? {} : { structures }),
+    };
+}
+export function terrain(config = {}) {
+    return withOptional({
+        kind: "terrain",
+        bounds: config.bounds ?? { w: 512, d: 512 },
+        height: config.height ?? 0,
+    }, {
+        ...(config.heightMap === undefined ? {} : { heightMap: config.heightMap }),
+        ...(config.material === undefined ? {} : { material: config.material }),
+        ...(config.seed === undefined ? {} : { seed: config.seed }),
+        ...(config.frequency === undefined ? {} : { frequency: config.frequency }),
+        ...(config.octaves === undefined ? {} : { octaves: config.octaves }),
+        ...(config.ridged === undefined ? {} : { ridged: config.ridged }),
+        ...(config.baseHeight === undefined ? {} : { baseHeight: config.baseHeight }),
+        ...(config.waterLevel === undefined ? {} : { waterLevel: config.waterLevel }),
+    });
+}
+export function rain(config = {}) {
+    return {
+        kind: "rain",
+        area: config.area ?? { w: 256, d: 256, h: 80 },
+        density: config.density ?? 0.65,
+        speed: config.speed ?? 18,
+        dropLength: config.dropLength ?? 0.8,
+        wind: config.wind ?? [0, 0],
+        color: config.color ?? "#9ec8ff",
+    };
+}
+export function snow(config = {}) {
+    return {
+        kind: "snow",
+        area: config.area ?? { w: 256, d: 256, h: 80 },
+        density: config.density ?? 0.35,
+        speed: config.speed ?? 2.4,
+        flakeSize: config.flakeSize ?? 0.08,
+        drift: config.drift ?? 0.4,
+        wind: config.wind ?? [0, 0],
+        color: config.color ?? "#ffffff",
+    };
+}
+export function grass(config = {}) {
+    return withOptional({
+        kind: "grass",
+        area: config.area ?? { w: 128, d: 128 },
+        density: config.density ?? 4,
+        bladeHeight: config.bladeHeight ?? [0.25, 0.9],
+        bladeWidth: config.bladeWidth ?? 0.035,
+        windStrength: config.windStrength ?? 0.35,
+        colors: config.colors ?? ["#3f7d2d", "#66a83f"],
+    }, config.seed === undefined ? undefined : { seed: config.seed });
+}
+export function ocean(config = {}) {
+    return {
+        kind: "ocean",
+        bounds: config.bounds ?? { w: 1024, d: 1024 },
+        level: config.level ?? 0,
+        waveHeight: config.waveHeight ?? 1.2,
+        waveScale: config.waveScale ?? 18,
+        waveSpeed: config.waveSpeed ?? 0.55,
+        color: config.color ?? "#1d7fa3",
+    };
+}
+export function building(config = {}) {
+    return withOptional({
+        kind: "building",
+        count: config.count ?? 1,
+        footprint: config.footprint ?? { w: 8, d: 8 },
+        stories: config.stories ?? [1, 4],
+        storyHeight: config.storyHeight ?? 3,
+        spacing: config.spacing ?? 2,
+        style: config.style ?? "generic",
+    }, config.seed === undefined ? undefined : { seed: config.seed });
+}
 export function biomes(config) {
     return { kind: "biomes", ...config };
 }

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;