@jgengine/core 0.10.0 → 0.12.0

package/dist/world/features.d.ts

@@ -1,4 +1,9 @@
 import type { BuildingPaletteOverrides, BuildingStyle } from "./buildings.js";
+import type { AvoidZone } from "./geometry.js";
+import type { TerrainPathProfile } from "./pathTerrain.js";
+import type { PlaceWorldFeature } from "./place.js";
+import type { TerraformSnapshot } from "./terraform.js";
+import type { VolumetricCloudsConfig } from "./volumetricClouds.js";
 export interface WorldBounds {
     w: number;
     d: number;
@@ -42,6 +47,35 @@ export interface TerrainDetailConfig {
     roughness?: number;
     /** Overall detail intensity 0..1. Default 1. */
     strength?: number;
+    /** Real PBR texture maps blended over the procedural detail — the seam for `@jgengine/assets` `buildMaterialCatalog` output. Omit to keep the procedural-only look. */
+    material?: TerrainDetailMaterialConfig;
+}
+/**
+ * PBR map URLs for a real ground texture — the same shape
+ * `buildMaterialCatalog({ basePath }).resolve(id)!.maps` from `@jgengine/assets` returns. Kept
+ * dependency-free here so `core` never imports the assets package; any URLs (pulled maps, a CDN, a
+ * data URI) satisfy it.
+ */
+export interface TerrainMaterialMaps {
+    color: string;
+    normal: string;
+    roughness: string;
+    ao: string;
+    displacement: string;
+}
+/**
+ * Real PBR texture applied over the ground surface — the seam that lets a game put a
+ * `buildMaterialCatalog` material on terrain. Blends with, never replaces, the procedural detail
+ * shader: color/roughness/ao tile the maps by world position, `strength` fades them over the
+ * existing vertex-colour + noise look.
+ */
+export interface TerrainDetailMaterialConfig {
+    /** e.g. `buildMaterialCatalog({ basePath: "/materials" }).resolve("material/grass")!.maps`. */
+    maps: TerrainMaterialMaps;
+    /** World units per texture tile; smaller tiles the texture more densely. Default 4. */
+    repeat?: number;
+    /** Blend strength of the texture over the procedural/vertex-colour base, 0..1. Default 1. */
+    strength?: number;
 }
 export interface TerrainFlattenMask {
     center: EnvironmentVec2;
@@ -88,11 +122,26 @@ export interface TerrainRectRegion extends TerrainRegionStyle {
  * and blend back across `falloff`; later regions in the list win overlaps.
  */
 export type TerrainMaterialRegion = TerrainCircleRegion | TerrainPolylineRegion | TerrainRectRegion;
+/** Per-band fog override cross-faded along z by `createBiomeFogSampler`; unset fields fall through to the base sky fog. */
+export interface BiomeFog {
+    color?: string;
+    near?: number;
+    far?: number;
+    density?: number;
+}
+/** Per-band sky/light override cross-faded along z by `createBiomeSkySampler`; unset fields fall through to the base sky. */
+export interface BiomeSky {
+    horizonColor?: string;
+    zenithColor?: string;
+    sunIntensity?: number;
+    ambientIntensity?: number;
+}
 /**
  * A z-ordered ground palette zone — the linear-boundary counterpart to the radial `materialRegions`.
  * Adjacent bands cross-fade into each other across a `fade`-wide window centered on the midpoint z
  * between their centers, so a multi-biome world (vale → marsh → peaks along z) blends its ground
- * color instead of hard-switching. Order the list by ascending `z`.
+ * color instead of hard-switching. Bands may also carry per-zone `fog`, `sky`, and `weather`. Order
+ * the list by ascending `z`.
  */
 export interface BiomeBand {
     /** World-space center z of the zone. */
@@ -103,6 +152,12 @@ export interface BiomeBand {
     material?: TerrainMaterial;
     /** Explicit low/high/waterline hex colors for the zone. */
     colors?: TerrainColors;
+    /** Fog color/near/far/density for the zone, cross-faded per camera z; unset fields keep the base sky fog. */
+    fog?: BiomeFog;
+    /** Sky horizon/zenith colors and sun/ambient intensity for the zone, cross-faded per camera z; unset fields keep the base sky. */
+    sky?: BiomeSky;
+    /** Precipitation covering the zone — expands into a full-width weather strip centered at `[0, z]`, `fade`-deep. */
+    weather?: "rain" | "snow";
 }
 export interface TerrainEnvironmentConfig {
     bounds?: WorldBounds;
@@ -131,22 +186,50 @@ export interface TerrainEnvironmentConfig {
     waterLevel?: number;
     /** Flat pads carved into the noise field, e.g. for building pads or spawn circles. */
     flatten?: readonly TerrainFlattenMask[];
+    /** Authored path profiles that flatten/grade/carve the heightfield along a centerline (roads, rivers, ramps) with optional retaining walls. Applied after `flatten`. */
+    pathProfiles?: readonly TerrainPathProfile[];
     /** Procedural detail surface (noise-driven rock/sand/snow over the biome base). Omit for the flat vertex-colour ground. */
     detail?: TerrainDetailConfig;
 }
 export interface RainEnvironmentConfig {
+    /**
+     * `w`/`d`/`h` size a wrap-volume of raindrops **anchored to and re-centered on the camera every
+     * frame** — not a world-space region. `area.position` (and the `position` sugar below) has **no
+     * visual effect** on rain/snow: the shell's `RainField`/`SnowField` always run `followCamera` and
+     * never apply the mesh's transform, only `camera.position`. Keep `w`/`d`/`h` near camera scale
+     * (roughly 50-120 per axis) so drops stay a visible size at normal view distance — sizing the
+     * volume to a world region (e.g. matching a district's footprint) spreads the same drop count
+     * across that much more space until they're sub-pixel and the storm reads as empty sky, even
+     * though `summarizeEnvironment` shows the layer exists. Reach for `density`, `width`, and `opacity`
+     * to make a storm read heavier/taller instead of enlarging `area`.
+     */
     area?: EnvironmentArea;
-    /** World-space center `[x, z]` of the band, matching `building()`/`ocean()` — sugar for `area.position`, letting a biome zone site its own weather away from the origin. */
+    /** World-space center `[x, z]` of the band, matching `building()`/`ocean()` — sugar for `area.position`. No visual effect on rain/snow (see `area`); kept for API symmetry with other weather-adjacent features. */
     position?: EnvironmentVec2;
     density?: number;
     speed?: number;
     dropLength?: number;
     wind?: EnvironmentVec2;
     color?: string;
+    /** Streak width of each raindrop quad, in world units. Default 0.018 — raise for a heavier-reading storm without enlarging `area`. */
+    width?: number;
+    /** Drop opacity, 0-1. Default 0.48 — raise for a denser-reading storm without enlarging `area`. */
+    opacity?: number;
 }
 export interface SnowEnvironmentConfig {
+    /**
+     * `w`/`d`/`h` size a wrap-volume of snowflakes **anchored to and re-centered on the camera every
+     * frame** — not a world-space region. `area.position` (and the `position` sugar below) has **no
+     * visual effect** on rain/snow: the shell's `RainField`/`SnowField` always run `followCamera` and
+     * never apply the mesh's transform, only `camera.position`. Keep `w`/`d`/`h` near camera scale
+     * (roughly 50-120 per axis) so flakes stay a visible size at normal view distance — sizing the
+     * volume to a world region (e.g. matching a district's footprint) spreads the same flake count
+     * across that much more space until they're sub-pixel and the storm reads as empty sky, even
+     * though `summarizeEnvironment` shows the layer exists. Reach for `density`, `flakeSize`, and
+     * `opacity` to make a storm read heavier instead of enlarging `area`.
+     */
     area?: EnvironmentArea;
-    /** World-space center `[x, z]` of the band, matching `building()`/`ocean()` — sugar for `area.position`, letting a biome zone site its own weather away from the origin. */
+    /** World-space center `[x, z]` of the band, matching `building()`/`ocean()` — sugar for `area.position`. No visual effect on rain/snow (see `area`); kept for API symmetry with other weather-adjacent features. */
     position?: EnvironmentVec2;
     density?: number;
     speed?: number;
@@ -154,6 +237,8 @@ export interface SnowEnvironmentConfig {
     drift?: number;
     wind?: EnvironmentVec2;
     color?: string;
+    /** Flake opacity, 0-1. Default 0.86 — raise for a denser-reading storm without enlarging `area`. */
+    opacity?: number;
 }
 export interface GrassEnvironmentConfig {
     area?: EnvironmentArea;
@@ -192,11 +277,19 @@ export interface SkyEnvironmentConfig {
     zenithColor?: string;
     sunIntensity?: number;
     ambientIntensity?: number;
+    /** Sky-dome sphere radius in world units. Enlarge for a playfield sited far from the origin so the viewer never exits the dome. Default 260. */
+    radius?: number;
+    /** Horizon haze-band strength: 0 removes the dusty band, ~1 makes it heavy. Default 0.5. */
+    hazeStrength?: number;
+    /** Sun-glow brightness multiplier around the sun disc. Default 1. */
+    sunGlowStrength?: number;
     fog?: {
         color?: string;
         near?: number;
         far?: number;
     };
+    /** Raymarched volumetric cloud layer over the sky dome. Off by default — omit for no clouds. */
+    volumetricClouds?: VolumetricCloudsConfig;
 }
 export interface BuildingEnvironmentConfig {
     count?: number;
@@ -239,10 +332,10 @@ export type TerrainIslandDescriptor = Omit<TerrainEnvironmentDescriptor, "kind">
 };
 export type RainEnvironmentDescriptor = {
     kind: "rain";
-} & Required<Pick<RainEnvironmentConfig, "area" | "density" | "speed" | "dropLength" | "wind" | "color">>;
+} & Required<Pick<RainEnvironmentConfig, "area" | "density" | "speed" | "dropLength" | "wind" | "color" | "width" | "opacity">>;
 export type SnowEnvironmentDescriptor = {
     kind: "snow";
-} & Required<Pick<SnowEnvironmentConfig, "area" | "density" | "speed" | "flakeSize" | "drift" | "wind" | "color">>;
+} & Required<Pick<SnowEnvironmentConfig, "area" | "density" | "speed" | "flakeSize" | "drift" | "wind" | "color" | "opacity">>;
 export type GrassEnvironmentDescriptor = {
     kind: "grass";
 } & Required<Pick<GrassEnvironmentConfig, "area" | "density" | "bladeHeight" | "bladeWidth" | "windStrength" | "colors">> & Pick<GrassEnvironmentConfig, "seed">;
@@ -306,6 +399,18 @@ export interface EnvironmentWorldConfig {
     roads?: EnvironmentDescriptorList<RoadEnvironmentDescriptor>;
     /** Ground pads, e.g. platforms or paved patches; each implicitly flattens the terrain beneath it. */
     pads?: readonly PadEnvironmentDescriptor[];
+    /**
+     * An authored editor {@link TerraformSnapshot} whose offsets layer over the base terrain — the
+     * editor-to-runtime ground seam. The same snapshot in a game's `editorLayers.terrain` renders and
+     * collides identically at runtime.
+     */
+    sculpt?: TerraformSnapshot;
+    /**
+     * Clearance discs flattened into the ground (spawns, plots, paths) — the terrain half of a
+     * clearance zone whose foliage half is scatter's `avoid`. Derive them from a document with
+     * `clearanceZonesFrom`.
+     */
+    clearings?: readonly AvoidZone[];
 }
 export interface EnvironmentWorldFeature {
     kind: "environment";
@@ -318,6 +423,10 @@ export interface EnvironmentWorldFeature {
     structures?: readonly StructureEnvironmentDescriptor[];
     roads?: readonly RoadEnvironmentDescriptor[];
     pads?: readonly PadEnvironmentDescriptor[];
+    /** Authored sculpt snapshot layered over the base terrain — see {@link EnvironmentWorldConfig.sculpt}. */
+    sculpt?: TerraformSnapshot;
+    /** Clearance discs flattened into the ground — see {@link EnvironmentWorldConfig.clearings}. */
+    clearings?: readonly AvoidZone[];
 }
 export interface WorldGridCell {
     x: number;
@@ -356,8 +465,13 @@ export interface PlotsWorldConfig extends WorldGridConfig {
 export interface TilemapWorldConfig extends WorldGridConfig {
     map: string;
 }
-/** A declared world shape — biomes, voxel grid, plots, tilemap, environment, or flat — passed to `defineGame`. */
-export type WorldFeature = ({
+/**
+ * A declared world shape passed to `defineGame`. The preferred model is the place feature from
+ * `world()` (`@jgengine/core/world/place`): substrate + laws, with all dressing authored in the
+ * editor. The remaining members — biomes, voxel grid, plots, tilemap, environment, flat — are the
+ * legacy code-declared shapes kept for existing games.
+ */
+export type WorldFeature = PlaceWorldFeature | ({
     kind: "biomes";
 } & BiomesWorldConfig) | ({
     kind: "voxel";
@@ -370,14 +484,23 @@ export type WorldFeature = ({
 };
 /** Derives implicit `TerrainFlattenMask`s carving each pad's footprint into the terrain beneath it. Elevated pads (absolute `elevation`) float free and carve nothing. */
 export declare function padFlattenMasks(pads: readonly PadEnvironmentDescriptor[]): readonly TerrainFlattenMask[];
-/** Composes an `environment()` world feature from terrain, sky, weather, vegetation, water, structures, roads, and pads. */
+/** Composes an `environment()` feature from terrain, sky, weather, vegetation, water, structures, roads, and pads.
+ *
+ * Legacy dressing-in-code path — not how a world is defined. A world is the place you play in
+ * (`world()` from `world/place`: ground + laws); sky look, foliage scatter, props, and sculpt are
+ * scene content authored in the editor. Reach for `environment()` only when consuming
+ * editor/preset-written scene data (`environmentContentFromDocument`) or maintaining an existing
+ * game; never scaffold new worlds from it.
+ *
+ * @capability world-environment compose editor/preset-derived outdoor dressing — terrain, weather, water, structures — into a legacy environment feature
+ */
 export declare function environment(config?: EnvironmentWorldConfig): EnvironmentWorldFeature;
 /** Declares a heightfield terrain patch for `environment()` — bounds, noise, materials, and flatten masks. */
 export declare function terrain(config?: TerrainEnvironmentConfig): TerrainEnvironmentDescriptor;
 export declare function sky(config?: SkyEnvironmentConfig): SkyEnvironmentDescriptor;
-/** Declares a rainfall weather effect for `environment()` — area, density, speed, and wind. */
+/** Declares a rainfall weather effect for `environment()` — area, density, speed, wind, and drop width/opacity. */
 export declare function rain(config?: RainEnvironmentConfig): RainEnvironmentDescriptor;
-/** Declares a snowfall weather effect for `environment()` — area, density, drift, and wind. */
+/** Declares a snowfall weather effect for `environment()` — area, density, drift, wind, and flake opacity. */
 export declare function snow(config?: SnowEnvironmentConfig): SnowEnvironmentDescriptor;
 /** Declares a grass vegetation patch for `environment()` — area, blade sizing, density, and colors. */
 export declare function grass(config?: GrassEnvironmentConfig): GrassEnvironmentDescriptor;

package/dist/world/features.js

@@ -27,9 +27,37 @@ function withPadFlatten(terrainDescriptor, pads) {
         flatten: [...(terrainDescriptor.flatten ?? []), ...padFlattenMasks(pads)],
     };
 }
-/** Composes an `environment()` world feature from terrain, sky, weather, vegetation, water, structures, roads, and pads. */
+/** Expands each `biomeBand.weather` into a full-width precipitation strip centered on the band's z, `fade`-deep. */
+function bandWeatherDescriptors(terrainDescriptor) {
+    const bands = terrainDescriptor?.biomeBands;
+    if (bands === undefined || bands.length === 0)
+        return [];
+    const width = terrainDescriptor.bounds.w;
+    const out = [];
+    for (const band of bands) {
+        if (band.weather === undefined)
+            continue;
+        const area = { w: width, d: band.fade ?? 64, h: 80 };
+        const position = [0, band.z];
+        out.push(band.weather === "rain" ? rain({ area, position }) : snow({ area, position }));
+    }
+    return out;
+}
+/** Composes an `environment()` feature from terrain, sky, weather, vegetation, water, structures, roads, and pads.
+ *
+ * Legacy dressing-in-code path — not how a world is defined. A world is the place you play in
+ * (`world()` from `world/place`: ground + laws); sky look, foliage scatter, props, and sculpt are
+ * scene content authored in the editor. Reach for `environment()` only when consuming
+ * editor/preset-written scene data (`environmentContentFromDocument`) or maintaining an existing
+ * game; never scaffold new worlds from it.
+ *
+ * @capability world-environment compose editor/preset-derived outdoor dressing — terrain, weather, water, structures — into a legacy environment feature
+ */
 export function environment(config = {}) {
-    const weather = list(config.weather);
+    const explicitWeather = list(config.weather);
+    const bandWeather = bandWeatherDescriptors(config.terrain);
+    const weatherAll = [...(explicitWeather ?? []), ...bandWeather];
+    const weather = weatherAll.length === 0 ? undefined : weatherAll;
     const vegetation = list(config.vegetation);
     const water = list(config.water);
     const structures = list(config.structures);
@@ -46,6 +74,8 @@ export function environment(config = {}) {
         ...(structures === undefined ? {} : { structures }),
         ...(roads === undefined ? {} : { roads }),
         ...(config.pads === undefined ? {} : { pads: config.pads }),
+        ...(config.sculpt === undefined ? {} : { sculpt: config.sculpt }),
+        ...(config.clearings === undefined || config.clearings.length === 0 ? {} : { clearings: config.clearings }),
     };
 }
 /** Declares a heightfield terrain patch for `environment()` — bounds, noise, materials, and flatten masks. */
@@ -75,6 +105,7 @@ export function terrain(config = {}) {
         ...(config.baseHeight === undefined ? {} : { baseHeight: config.baseHeight }),
         ...(config.waterLevel === undefined ? {} : { waterLevel: config.waterLevel }),
         ...(config.flatten === undefined ? {} : { flatten: config.flatten }),
+        ...(config.pathProfiles === undefined ? {} : { pathProfiles: config.pathProfiles }),
         ...(config.detail === undefined ? {} : { detail: config.detail }),
     });
 }
@@ -88,35 +119,64 @@ export function sky(config = {}) {
         ...(config.zenithColor === undefined ? {} : { zenithColor: config.zenithColor }),
         ...(config.sunIntensity === undefined ? {} : { sunIntensity: config.sunIntensity }),
         ...(config.ambientIntensity === undefined ? {} : { ambientIntensity: config.ambientIntensity }),
+        ...(config.radius === undefined ? {} : { radius: config.radius }),
+        ...(config.hazeStrength === undefined ? {} : { hazeStrength: config.hazeStrength }),
+        ...(config.sunGlowStrength === undefined ? {} : { sunGlowStrength: config.sunGlowStrength }),
         ...(config.fog === undefined ? {} : { fog: config.fog }),
+        ...(config.volumetricClouds === undefined ? {} : { volumetricClouds: config.volumetricClouds }),
     });
 }
 function withAreaPosition(area, position) {
     return position !== undefined && area.position === undefined ? { ...area, position } : area;
 }
-/** Declares a rainfall weather effect for `environment()` — area, density, speed, and wind. */
+/**
+ * Practical ceiling (world units per axis) past which an author-specified rain/snow `area` is almost
+ * certainly a world-region size mistakenly handed to the camera-anchored wrap-volume — see the
+ * `area` doc on `RainEnvironmentConfig`/`SnowEnvironmentConfig`.
+ */
+const WEATHER_AREA_CAMERA_SCALE_HINT = 120;
+function warnIfOversizedWeatherArea(kind, area) {
+    if (typeof console === "undefined")
+        return;
+    if (area.w <= WEATHER_AREA_CAMERA_SCALE_HINT &&
+        area.d <= WEATHER_AREA_CAMERA_SCALE_HINT &&
+        (area.h ?? 0) <= WEATHER_AREA_CAMERA_SCALE_HINT) {
+        return;
+    }
+    console.warn(`[jgengine:${kind}] area ${area.w}x${area.d}x${area.h ?? "default"} is far larger than the camera-anchored wrap-volume ${kind}() actually renders — area.position is ignored, and an oversized area.w/d/h just spreads drops/flakes thinner until they're sub-pixel at normal view distance, not wider visible coverage. Keep area near camera scale (~50-120 per axis); use density/width/opacity (or flakeSize for snow) to make a storm read heavier instead.`);
+}
+/** Declares a rainfall weather effect for `environment()` — area, density, speed, wind, and drop width/opacity. */
 export function rain(config = {}) {
+    const area = withAreaPosition(config.area ?? { w: 256, d: 256, h: 80 }, config.position);
+    if (config.area !== undefined)
+        warnIfOversizedWeatherArea("rain", area);
     return {
         kind: "rain",
-        area: withAreaPosition(config.area ?? { w: 256, d: 256, h: 80 }, config.position),
+        area,
         density: config.density ?? 0.65,
         speed: config.speed ?? 18,
         dropLength: config.dropLength ?? 0.8,
         wind: config.wind ?? [0, 0],
         color: config.color ?? "#9ec8ff",
+        width: config.width ?? 0.018,
+        opacity: config.opacity ?? 0.48,
     };
 }
-/** Declares a snowfall weather effect for `environment()` — area, density, drift, and wind. */
+/** Declares a snowfall weather effect for `environment()` — area, density, drift, wind, and flake opacity. */
 export function snow(config = {}) {
+    const area = withAreaPosition(config.area ?? { w: 256, d: 256, h: 80 }, config.position);
+    if (config.area !== undefined)
+        warnIfOversizedWeatherArea("snow", area);
     return {
         kind: "snow",
-        area: withAreaPosition(config.area ?? { w: 256, d: 256, h: 80 }, config.position),
+        area,
         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",
+        opacity: config.opacity ?? 0.86,
     };
 }
 /** Declares a grass vegetation patch for `environment()` — area, blade sizing, density, and colors. */

package/dist/world/footprintGrid.d.ts

@@ -0,0 +1,59 @@
+import type { Footprint, Vec2 } from "./geometry.js";
+import type { PlacementObstacle } from "./placement.js";
+/** One integer cell address on a {@link FootprintGrid}. */
+export interface GridCell {
+    col: number;
+    row: number;
+}
+/** Config for {@link createFootprintGrid}. */
+export interface FootprintGridOptions {
+    /** World units per cell. Default 1. */
+    cellSize?: number;
+}
+/** A live claim on a {@link FootprintGrid}: which cells `id` (a `kind` tag for adjacency checks) holds. */
+export interface FootprintReservation {
+    id: string;
+    kind: string;
+    cells: readonly GridCell[];
+}
+/** Handle returned by {@link createFootprintGrid}. */
+export interface FootprintGrid {
+    readonly cellSize: number;
+    /** The cells a `footprint` centered on `origin` (world units) covers, honoring `quarterTurns` — feed straight into `reserve`/`isFree`. */
+    cellsFor(origin: Vec2, footprint: Footprint, quarterTurns?: number): GridCell[];
+    isFree(cells: readonly GridCell[]): boolean;
+    /** Claims every cell for `id`/`kind`; fails (no partial reservation) if `id` already holds a reservation or any cell is occupied. */
+    reserve(id: string, kind: string, cells: readonly GridCell[]): boolean;
+    release(id: string): boolean;
+    occupantAt(cell: GridCell): string | null;
+    kindAt(cell: GridCell): string | null;
+    reservationOf(id: string): FootprintReservation | null;
+    list(): readonly FootprintReservation[];
+    clear(): void;
+}
+/**
+ * Multi-cell footprint occupancy/reservation on a shared build grid — `world/placementController`
+ * only owns the ghost preview; this is the persistent claim a committed placement holds so the next
+ * hover's `isFree` check (or another player's, in a shared world) sees it. Bridge into
+ * `world/placement`'s `PlacementRules.obstacles` with {@link footprintObstacles} instead of
+ * hand-rolling an occupancy map per game.
+ *
+ * @capability footprint-grid multi-cell footprint occupancy/reservation on a shared build grid
+ */
+export declare function createFootprintGrid(options?: FootprintGridOptions): FootprintGrid;
+/** One occupied neighbor cell reported by {@link boundaryNeighbors}. */
+export interface AdjacentCell {
+    cell: GridCell;
+    kind: string;
+}
+/** Every occupied cell orthogonally touching `cells` but outside them — the connective-piece neighbor set. */
+export declare function boundaryNeighbors(grid: FootprintGrid, cells: readonly GridCell[]): AdjacentCell[];
+/**
+ * Connective-piece adjacency validity: every occupied neighbor of `cells` must satisfy `accepts`
+ * (no incompatible piece touching), and when `requireConnection` is true at least one neighbor must
+ * (a road/pipe/belt segment placed with nothing to connect to is invalid). An empty-bordered footprint
+ * (no occupied neighbors at all) passes unless `requireConnection` demands one.
+ */
+export declare function hasValidAdjacency(grid: FootprintGrid, cells: readonly GridCell[], accepts: (neighborKind: string) => boolean, requireConnection?: boolean): boolean;
+/** Bridges live reservations into `world/placement`'s `PlacementRules.obstacles` so `validatePlacement`/`createPlacementController` see the grid's committed footprints unchanged. */
+export declare function footprintObstacles(grid: FootprintGrid): PlacementObstacle[];

package/dist/world/footprintGrid.js

@@ -0,0 +1,141 @@
+function cellKey(cell) {
+    return `${cell.col}:${cell.row}`;
+}
+/**
+ * Multi-cell footprint occupancy/reservation on a shared build grid — `world/placementController`
+ * only owns the ghost preview; this is the persistent claim a committed placement holds so the next
+ * hover's `isFree` check (or another player's, in a shared world) sees it. Bridge into
+ * `world/placement`'s `PlacementRules.obstacles` with {@link footprintObstacles} instead of
+ * hand-rolling an occupancy map per game.
+ *
+ * @capability footprint-grid multi-cell footprint occupancy/reservation on a shared build grid
+ */
+export function createFootprintGrid(options = {}) {
+    const cellSize = options.cellSize ?? 1;
+    const occupied = new Map();
+    const reservations = new Map();
+    return {
+        cellSize,
+        cellsFor(origin, footprint, quarterTurns = 0) {
+            const turned = ((quarterTurns % 2) + 2) % 2 === 1;
+            const cols = Math.max(1, Math.round((turned ? footprint.d : footprint.w) / cellSize));
+            const rows = Math.max(1, Math.round((turned ? footprint.w : footprint.d) / cellSize));
+            const originCol = Math.round(origin[0] / cellSize - cols / 2);
+            const originRow = Math.round(origin[1] / cellSize - rows / 2);
+            const cells = [];
+            for (let row = 0; row < rows; row += 1) {
+                for (let col = 0; col < cols; col += 1)
+                    cells.push({ col: originCol + col, row: originRow + row });
+            }
+            return cells;
+        },
+        isFree(cells) {
+            return cells.every((cell) => !occupied.has(cellKey(cell)));
+        },
+        reserve(id, kind, cells) {
+            if (reservations.has(id))
+                return false;
+            if (!cells.every((cell) => !occupied.has(cellKey(cell))))
+                return false;
+            for (const cell of cells)
+                occupied.set(cellKey(cell), id);
+            reservations.set(id, { id, kind, cells: cells.slice() });
+            return true;
+        },
+        release(id) {
+            const reservation = reservations.get(id);
+            if (reservation === undefined)
+                return false;
+            for (const cell of reservation.cells)
+                occupied.delete(cellKey(cell));
+            reservations.delete(id);
+            return true;
+        },
+        occupantAt(cell) {
+            return occupied.get(cellKey(cell)) ?? null;
+        },
+        kindAt(cell) {
+            const id = occupied.get(cellKey(cell));
+            if (id === undefined)
+                return null;
+            return reservations.get(id)?.kind ?? null;
+        },
+        reservationOf(id) {
+            return reservations.get(id) ?? null;
+        },
+        list() {
+            return Array.from(reservations.values());
+        },
+        clear() {
+            occupied.clear();
+            reservations.clear();
+        },
+    };
+}
+const CARDINAL_OFFSETS = [
+    { col: 0, row: -1 },
+    { col: 1, row: 0 },
+    { col: 0, row: 1 },
+    { col: -1, row: 0 },
+];
+/** Every occupied cell orthogonally touching `cells` but outside them — the connective-piece neighbor set. */
+export function boundaryNeighbors(grid, cells) {
+    const own = new Set(cells.map(cellKey));
+    const seen = new Set();
+    const out = [];
+    for (const cell of cells) {
+        for (const offset of CARDINAL_OFFSETS) {
+            const neighbor = { col: cell.col + offset.col, row: cell.row + offset.row };
+            const key = cellKey(neighbor);
+            if (own.has(key) || seen.has(key))
+                continue;
+            seen.add(key);
+            const kind = grid.kindAt(neighbor);
+            if (kind !== null)
+                out.push({ cell: neighbor, kind });
+        }
+    }
+    return out;
+}
+/**
+ * Connective-piece adjacency validity: every occupied neighbor of `cells` must satisfy `accepts`
+ * (no incompatible piece touching), and when `requireConnection` is true at least one neighbor must
+ * (a road/pipe/belt segment placed with nothing to connect to is invalid). An empty-bordered footprint
+ * (no occupied neighbors at all) passes unless `requireConnection` demands one.
+ */
+export function hasValidAdjacency(grid, cells, accepts, requireConnection = false) {
+    const neighbors = boundaryNeighbors(grid, cells);
+    if (requireConnection && neighbors.length === 0)
+        return false;
+    if (!neighbors.every((neighbor) => accepts(neighbor.kind)))
+        return false;
+    return !requireConnection || neighbors.some((neighbor) => accepts(neighbor.kind));
+}
+/** Bridges live reservations into `world/placement`'s `PlacementRules.obstacles` so `validatePlacement`/`createPlacementController` see the grid's committed footprints unchanged. */
+export function footprintObstacles(grid) {
+    return grid.list().map((reservation) => {
+        let minCol = Infinity;
+        let minRow = Infinity;
+        let maxCol = -Infinity;
+        let maxRow = -Infinity;
+        for (const cell of reservation.cells) {
+            if (cell.col < minCol)
+                minCol = cell.col;
+            if (cell.col > maxCol)
+                maxCol = cell.col;
+            if (cell.row < minRow)
+                minRow = cell.row;
+            if (cell.row > maxRow)
+                maxRow = cell.row;
+        }
+        return {
+            id: reservation.id,
+            aabb: {
+                minX: minCol * grid.cellSize,
+                maxX: (maxCol + 1) * grid.cellSize,
+                minZ: minRow * grid.cellSize,
+                maxZ: (maxRow + 1) * grid.cellSize,
+            },
+        };
+    });
+}

package/dist/world/geometry.d.ts

@@ -1,4 +1,6 @@
 export type Vec2 = readonly [number, number];
+/** A 3D point/vector as an `[x, y, z]` tuple — the engine's zero-allocation spatial primitive. */
+export type Vec3 = readonly [number, number, number];
 export interface Footprint {
     w: number;
     d: number;
@@ -13,11 +15,73 @@ export interface MoveOptions {
     bounds?: Aabb;
     radius?: number;
 }
+/**
+ * A circular clearance around a gameplay spot (spawn, plot, path point, POI): scatter is repelled
+ * from it and terrain is flattened toward its center. `feather` (meters) is the soft outer band —
+ * full effect within `radius - feather`, ramping to zero at `radius`.
+ */
+export interface AvoidZone {
+    x: number;
+    z: number;
+    radius: number;
+    feather?: number;
+}
+/**
+ * A clearance *corridor* along a polyline (a path/road): scatter is repelled within `halfWidth` of
+ * the centerline, feathered over the outer band. Clean straight edges — unlike approximating a
+ * corridor with a scalloped chain of discs.
+ */
+export interface AvoidCorridor {
+    points: readonly Vec2[];
+    halfWidth: number;
+    feather?: number;
+}
+/** A clearance region: point discs (spawns/plots) plus centerline corridors (paths). */
+export interface AvoidMasks {
+    discs: readonly AvoidZone[];
+    corridors: readonly AvoidCorridor[];
+}
+/**
+ * How strongly a point falls inside a clearance zone: 1 at/inside the solid core, ramping to 0 at
+ * the zone's outer `radius` across its `feather` band, 0 outside. The max over all zones.
+ * @internal — the falloff math behind scatter avoid and terrain flatten.
+ */
+export declare function zoneInfluence(x: number, z: number, zones: readonly AvoidZone[]): number;
+/** Clearance influence of a corridor: nearest-segment distance vs `halfWidth`, feathered. @internal */
+export declare function corridorInfluence(x: number, z: number, corridor: AvoidCorridor): number;
+/** Combined clearance influence of discs + corridors — the max over every mask. @internal */
+export declare function masksInfluence(x: number, z: number, masks: AvoidMasks): number;
+/** @internal */
 export declare function snapToGrid(point: Vec2, size: number): Vec2;
+/** @internal */
 export declare function footprintAabb(center: Vec2, footprint: Footprint, quarterTurns?: number): Aabb;
+/** @internal */
 export declare function expandAabb(aabb: Aabb, margin: number): Aabb;
+/** @internal */
 export declare function aabbOverlap(a: Aabb, b: Aabb): boolean;
+/** @internal */
 export declare function aabbContains(outer: Aabb, inner: Aabb): boolean;
+/** @internal */
 export declare function pointInAabb(point: Vec2, aabb: Aabb): boolean;
+/** @internal */
 export declare function clampToAabb(point: Vec2, aabb: Aabb): Vec2;
+/** @internal */
 export declare function resolveMove(from: Vec2, delta: Vec2, blockers: readonly Aabb[], options?: MoveOptions): Vec2;
+/** An axis-aligned ellipse: `center` with semi-axes `radiusX` and `radiusY`. */
+export interface Ellipse {
+    center: Vec2;
+    radiusX: number;
+    radiusY: number;
+}
+/** True when `point` sits inside (or on) the ellipse — the oval-arena containment test.
+ * @internal
+ */
+export declare function pointInEllipse(point: Vec2, ellipse: Ellipse): boolean;
+/** Clamp `point` to the ellipse boundary when it strays outside, else return it unchanged.
+ * @internal
+ */
+export declare function clampToEllipse(point: Vec2, ellipse: Ellipse): Vec2;
+/** Outward unit normal of the ellipse at the point nearest `point` — the boundary bounce direction.
+ * @internal
+ */
+export declare function ellipseNormal(point: Vec2, ellipse: Ellipse): Vec2;