@jgengine/core 0.7.0 → 0.8.0

package/dist/world/environmentSummary.d.ts

@@ -0,0 +1,53 @@
+import { type GeneratedBuilding } from "./buildings.js";
+import type { BuildingEnvironmentDescriptor, EnvironmentWorldFeature, WorldBounds } from "./features.js";
+import type { Aabb } from "./geometry.js";
+export declare function resolveStructureBuildings(descriptor: BuildingEnvironmentDescriptor): GeneratedBuilding[];
+export interface TerrainHeightStats {
+    min: number;
+    max: number;
+    mean: number;
+    finite: boolean;
+}
+export interface TerrainSummary {
+    bounds: WorldBounds;
+    height: TerrainHeightStats;
+    waterLevel?: number;
+}
+export interface StructureSummary {
+    style: string;
+    requested: number;
+    buildings: number;
+    parts: number;
+    bounds: Aabb;
+}
+export interface VegetationSummary {
+    area: WorldBounds;
+    density: number;
+}
+export interface WaterSummary {
+    level: number;
+    bounds: WorldBounds;
+}
+export interface WeatherSummary {
+    kind: "rain" | "snow";
+    density: number;
+}
+export interface EnvironmentCounts {
+    terrain: number;
+    structureGroups: number;
+    buildings: number;
+    buildingParts: number;
+    vegetationFields: number;
+    waterBodies: number;
+    weatherSystems: number;
+}
+export interface EnvironmentSummary {
+    terrain?: TerrainSummary;
+    structures: readonly StructureSummary[];
+    vegetation: readonly VegetationSummary[];
+    water: readonly WaterSummary[];
+    weather: readonly WeatherSummary[];
+    counts: EnvironmentCounts;
+    isEmpty: boolean;
+}
+export declare function summarizeEnvironment(feature: EnvironmentWorldFeature): EnvironmentSummary;

package/dist/world/environmentSummary.js

@@ -0,0 +1,129 @@
+import { generateBuildingDistrict } from "./buildings.js";
+import { resolveTerrainField } from "./terrain.js";
+export function resolveStructureBuildings(descriptor) {
+    const columns = Math.max(1, Math.ceil(Math.sqrt(descriptor.count)));
+    const rows = Math.max(1, Math.ceil(descriptor.count / columns));
+    const spacing = descriptor.spacing;
+    const [centerX, centerZ] = descriptor.position ?? [0, 0];
+    const origin = [
+        centerX - ((columns - 1) * (descriptor.footprint.w + spacing)) / 2,
+        centerZ - ((rows - 1) * (descriptor.footprint.d + spacing)) / 2,
+    ];
+    return generateBuildingDistrict({
+        rows,
+        columns,
+        origin,
+        lotSize: descriptor.footprint,
+        streetWidth: spacing,
+        floorRange: descriptor.stories,
+        base: { floorHeight: descriptor.storyHeight },
+        ...(descriptor.seed === undefined ? {} : { seed: descriptor.seed }),
+    }).slice(0, descriptor.count);
+}
+const TERRAIN_SAMPLE_RESOLUTION = 16;
+function sampleTerrainHeights(descriptor) {
+    const field = resolveTerrainField(descriptor);
+    const halfW = descriptor.bounds.w / 2;
+    const halfD = descriptor.bounds.d / 2;
+    const steps = TERRAIN_SAMPLE_RESOLUTION;
+    let min = Infinity;
+    let max = -Infinity;
+    let sum = 0;
+    let finite = true;
+    for (let ix = 0; ix <= steps; ix += 1) {
+        for (let iz = 0; iz <= steps; iz += 1) {
+            const x = -halfW + (descriptor.bounds.w * ix) / steps;
+            const z = -halfD + (descriptor.bounds.d * iz) / steps;
+            const height = field.sampleHeight(x, z);
+            if (!Number.isFinite(height)) {
+                finite = false;
+                continue;
+            }
+            if (height < min)
+                min = height;
+            if (height > max)
+                max = height;
+            sum += height;
+        }
+    }
+    const count = (steps + 1) * (steps + 1);
+    if (!finite)
+        return { min: NaN, max: NaN, mean: NaN, finite: false };
+    return { min, max, mean: sum / count, finite: true };
+}
+function unionAabb(buildings) {
+    if (buildings.length === 0)
+        return { minX: 0, minZ: 0, maxX: 0, maxZ: 0 };
+    let minX = Infinity;
+    let minZ = Infinity;
+    let maxX = -Infinity;
+    let maxZ = -Infinity;
+    for (const building of buildings) {
+        if (building.bounds.minX < minX)
+            minX = building.bounds.minX;
+        if (building.bounds.minZ < minZ)
+            minZ = building.bounds.minZ;
+        if (building.bounds.maxX > maxX)
+            maxX = building.bounds.maxX;
+        if (building.bounds.maxZ > maxZ)
+            maxZ = building.bounds.maxZ;
+    }
+    return { minX, minZ, maxX, maxZ };
+}
+function summarizeStructures(descriptor) {
+    const buildings = resolveStructureBuildings(descriptor);
+    return {
+        style: descriptor.style,
+        requested: descriptor.count,
+        buildings: buildings.length,
+        parts: buildings.reduce((sum, building) => sum + building.parts.length, 0),
+        bounds: unionAabb(buildings),
+    };
+}
+function summarizeTerrain(descriptor) {
+    return {
+        bounds: descriptor.bounds,
+        height: sampleTerrainHeights(descriptor),
+        ...(descriptor.waterLevel === undefined ? {} : { waterLevel: descriptor.waterLevel }),
+    };
+}
+export function summarizeEnvironment(feature) {
+    const terrain = feature.terrain === undefined ? undefined : summarizeTerrain(feature.terrain);
+    const structures = (feature.structures ?? []).map(summarizeStructures);
+    const vegetation = (feature.vegetation ?? []).map((entry) => ({
+        area: entry.area,
+        density: entry.density,
+    }));
+    const water = (feature.water ?? []).map((entry) => ({
+        level: entry.level,
+        bounds: entry.bounds,
+    }));
+    const weather = (feature.weather ?? []).map((entry) => ({
+        kind: entry.kind,
+        density: entry.density,
+    }));
+    const buildings = structures.reduce((sum, entry) => sum + entry.buildings, 0);
+    const counts = {
+        terrain: terrain === undefined ? 0 : 1,
+        structureGroups: structures.length,
+        buildings,
+        buildingParts: structures.reduce((sum, entry) => sum + entry.parts, 0),
+        vegetationFields: vegetation.length,
+        waterBodies: water.length,
+        weatherSystems: weather.length,
+    };
+    const isEmpty = counts.terrain === 0 &&
+        buildings === 0 &&
+        counts.vegetationFields === 0 &&
+        counts.waterBodies === 0 &&
+        counts.weatherSystems === 0;
+    return {
+        ...(terrain === undefined ? {} : { terrain }),
+        structures,
+        vegetation,
+        water,
+        weather,
+        counts,
+        isEmpty,
+    };
+}

package/dist/world/features.d.ts

@@ -6,17 +6,36 @@ export type EnvironmentVec2 = readonly [number, number];
 export interface EnvironmentArea extends WorldBounds {
     h?: number;
 }
+export interface TerrainColors {
+    low?: string;
+    high?: string;
+    waterline?: string;
+}
+export interface TerrainFlattenMask {
+    center: EnvironmentVec2;
+    radius: number;
+    /** Target flat height; defaults to the noise field's height at `center`. */
+    height?: number;
+    /** Extra blend-ring width outside `radius` where the flat height smoothsteps back to the noise value; default `radius * 0.5`. */
+    falloff?: number;
+}
 export interface TerrainEnvironmentConfig {
     bounds?: WorldBounds;
     height?: number;
     heightMap?: string;
+    /** Named palette preset (see `TERRAIN_MATERIAL_PALETTES` in `world/terrain`); default "grass". Overridden field-by-field by `colors`. */
     material?: string;
+    /** Explicit low/high/waterline hex colors; any field left unset falls back to the resolved `material` preset. */
+    colors?: TerrainColors;
+    segments?: number;
     seed?: string;
     frequency?: number;
     octaves?: number;
     ridged?: boolean;
     baseHeight?: number;
     waterLevel?: number;
+    /** Flat pads carved into the noise field, e.g. for building pads or spawn circles. */
+    flatten?: readonly TerrainFlattenMask[];
 }
 export interface RainEnvironmentConfig {
     area?: EnvironmentArea;
@@ -46,14 +65,31 @@ export interface GrassEnvironmentConfig {
 }
 export interface OceanEnvironmentConfig {
     bounds?: WorldBounds;
+    position?: EnvironmentVec2;
     level?: number;
     waveHeight?: number;
     waveScale?: number;
     waveSpeed?: number;
     color?: string;
 }
+export interface SkyEnvironmentConfig {
+    /** Fixed look used when `timeOfDay` is off (or no clock is available); default "day". */
+    preset?: "day" | "dusk" | "night";
+    /** Drive sun/sky from the world clock's `calendar().dayFraction` instead of the fixed `preset`. */
+    timeOfDay?: boolean;
+    horizonColor?: string;
+    zenithColor?: string;
+    sunIntensity?: number;
+    ambientIntensity?: number;
+    fog?: {
+        color?: string;
+        near?: number;
+        far?: number;
+    };
+}
 export interface BuildingEnvironmentConfig {
     count?: number;
+    position?: EnvironmentVec2;
     footprint?: WorldBounds;
     stories?: readonly [number, number];
     storyHeight?: number;
@@ -61,6 +97,18 @@ export interface BuildingEnvironmentConfig {
     style?: string;
     seed?: string;
 }
+export type PadSize = readonly [number, number] | {
+    radius: number;
+};
+export interface PadEnvironmentConfig {
+    center: EnvironmentVec2;
+    size: PadSize;
+    /** Surface offset above the terrain height at `center`; default `0.05` — just proud of the ground. */
+    height?: number;
+    color?: string;
+    /** Rotation applied to rectangular pads; ignored for circular pads. */
+    rotationY?: number;
+}
 export type TerrainEnvironmentDescriptor = {
     kind: "terrain";
 } & Required<Pick<TerrainEnvironmentConfig, "bounds" | "height">> & Omit<TerrainEnvironmentConfig, "bounds" | "height">;
@@ -75,10 +123,16 @@ export type GrassEnvironmentDescriptor = {
 } & 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">>;
+} & Required<Pick<OceanEnvironmentConfig, "bounds" | "level" | "waveHeight" | "waveScale" | "waveSpeed" | "color">> & Pick<OceanEnvironmentConfig, "position">;
 export type BuildingEnvironmentDescriptor = {
     kind: "building";
-} & Required<Pick<BuildingEnvironmentConfig, "count" | "footprint" | "stories" | "storyHeight" | "spacing" | "style">> & Pick<BuildingEnvironmentConfig, "seed">;
+} & Required<Pick<BuildingEnvironmentConfig, "count" | "footprint" | "stories" | "storyHeight" | "spacing" | "style">> & Pick<BuildingEnvironmentConfig, "seed" | "position">;
+export type PadEnvironmentDescriptor = {
+    kind: "pad";
+} & Required<Pick<PadEnvironmentConfig, "center" | "size" | "height" | "color">> & Pick<PadEnvironmentConfig, "rotationY">;
+export type SkyEnvironmentDescriptor = {
+    kind: "sky";
+} & Required<Pick<SkyEnvironmentConfig, "preset" | "timeOfDay">> & Omit<SkyEnvironmentConfig, "preset" | "timeOfDay">;
 export type WeatherEnvironmentDescriptor = RainEnvironmentDescriptor | SnowEnvironmentDescriptor;
 export type VegetationEnvironmentDescriptor = GrassEnvironmentDescriptor;
 export type WaterEnvironmentDescriptor = OceanEnvironmentDescriptor;
@@ -86,36 +140,59 @@ export type StructureEnvironmentDescriptor = BuildingEnvironmentDescriptor;
 export type EnvironmentDescriptorList<T> = T | readonly T[];
 export interface EnvironmentWorldConfig {
     terrain?: TerrainEnvironmentDescriptor;
+    sky?: SkyEnvironmentDescriptor;
     weather?: EnvironmentDescriptorList<WeatherEnvironmentDescriptor>;
     vegetation?: EnvironmentDescriptorList<VegetationEnvironmentDescriptor>;
     water?: EnvironmentDescriptorList<WaterEnvironmentDescriptor>;
     structures?: EnvironmentDescriptorList<StructureEnvironmentDescriptor>;
+    /** Ground pads, e.g. platforms or paved patches; each implicitly flattens the terrain beneath it. */
+    pads?: readonly PadEnvironmentDescriptor[];
 }
 export interface EnvironmentWorldFeature {
     kind: "environment";
     terrain?: TerrainEnvironmentDescriptor;
+    sky?: SkyEnvironmentDescriptor;
     weather?: readonly WeatherEnvironmentDescriptor[];
     vegetation?: readonly VegetationEnvironmentDescriptor[];
     water?: readonly WaterEnvironmentDescriptor[];
     structures?: readonly StructureEnvironmentDescriptor[];
+    pads?: readonly PadEnvironmentDescriptor[];
+}
+export interface WorldGridCell {
+    x: number;
+    z: number;
+    /** Extruded box height for this cell; falls back to the config's `baseHeight`, then `1`. */
+    height?: number;
+    /** Per-cell tint; falls back to the config's `defaultColor`. */
+    color?: string;
+}
+/** Shared by `biomes()`/`voxel()`/`plots()`/`tilemap()` so the shell can render their declared content as instanced boxes without a hand-written renderer. */
+export interface WorldGridConfig {
+    cells?: readonly WorldGridCell[];
+    /** World-unit size of one grid cell. Default 1. */
+    cellSize?: number;
+    /** Height used for cells that omit their own `height`. Default 1. */
+    baseHeight?: number;
+    /** Color used for cells that omit their own `color`. */
+    defaultColor?: string;
 }
-export interface BiomesWorldConfig {
+export interface BiomesWorldConfig extends WorldGridConfig {
     map: string;
     zones: string;
     bounds?: WorldBounds;
 }
-export interface VoxelWorldConfig {
+export interface VoxelWorldConfig extends WorldGridConfig {
     seed: string;
     generate?: string;
     streaming?: {
         radius: number;
     };
 }
-export interface PlotsWorldConfig {
+export interface PlotsWorldConfig extends WorldGridConfig {
     city?: string;
     interiors?: string;
 }
-export interface TilemapWorldConfig {
+export interface TilemapWorldConfig extends WorldGridConfig {
     map: string;
 }
 export type WorldFeature = ({
@@ -129,13 +206,17 @@ export type WorldFeature = ({
 } & TilemapWorldConfig) | EnvironmentWorldFeature | {
     kind: "flat";
 };
+/** Derives implicit `TerrainFlattenMask`s carving each pad's footprint into the terrain beneath it. */
+export declare function padFlattenMasks(pads: readonly PadEnvironmentDescriptor[]): readonly TerrainFlattenMask[];
 export declare function environment(config?: EnvironmentWorldConfig): EnvironmentWorldFeature;
 export declare function terrain(config?: TerrainEnvironmentConfig): TerrainEnvironmentDescriptor;
+export declare function sky(config?: SkyEnvironmentConfig): SkyEnvironmentDescriptor;
 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 pad(config: PadEnvironmentConfig): PadEnvironmentDescriptor;
 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

@@ -7,18 +7,39 @@ function list(value) {
 function withOptional(base, optional) {
     return optional === undefined ? base : { ...base, ...optional };
 }
+/** Derives implicit `TerrainFlattenMask`s carving each pad's footprint into the terrain beneath it. */
+export function padFlattenMasks(pads) {
+    return pads.map((padDescriptor) => ({
+        center: padDescriptor.center,
+        radius: padHalfExtent(padDescriptor.size) * 1.2,
+    }));
+}
+function padHalfExtent(size) {
+    return "radius" in size ? size.radius : Math.max(size[0], size[1]) / 2;
+}
+function withPadFlatten(terrainDescriptor, pads) {
+    if (terrainDescriptor === undefined || pads === undefined || pads.length === 0)
+        return terrainDescriptor;
+    return {
+        ...terrainDescriptor,
+        flatten: [...(terrainDescriptor.flatten ?? []), ...padFlattenMasks(pads)],
+    };
+}
 export function environment(config = {}) {
     const weather = list(config.weather);
     const vegetation = list(config.vegetation);
     const water = list(config.water);
     const structures = list(config.structures);
+    const terrainDescriptor = withPadFlatten(config.terrain, config.pads);
     return {
         kind: "environment",
-        ...(config.terrain === undefined ? {} : { terrain: config.terrain }),
+        ...(terrainDescriptor === undefined ? {} : { terrain: terrainDescriptor }),
+        ...(config.sky === undefined ? {} : { sky: config.sky }),
         ...(weather === undefined ? {} : { weather }),
         ...(vegetation === undefined ? {} : { vegetation }),
         ...(water === undefined ? {} : { water }),
         ...(structures === undefined ? {} : { structures }),
+        ...(config.pads === undefined ? {} : { pads: config.pads }),
     };
 }
 export function terrain(config = {}) {
@@ -29,12 +50,28 @@ export function terrain(config = {}) {
     }, {
         ...(config.heightMap === undefined ? {} : { heightMap: config.heightMap }),
         ...(config.material === undefined ? {} : { material: config.material }),
+        ...(config.colors === undefined ? {} : { colors: config.colors }),
+        ...(config.segments === undefined ? {} : { segments: config.segments }),
         ...(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 }),
+        ...(config.flatten === undefined ? {} : { flatten: config.flatten }),
+    });
+}
+export function sky(config = {}) {
+    return withOptional({
+        kind: "sky",
+        preset: config.preset ?? "day",
+        timeOfDay: config.timeOfDay ?? false,
+    }, {
+        ...(config.horizonColor === undefined ? {} : { horizonColor: config.horizonColor }),
+        ...(config.zenithColor === undefined ? {} : { zenithColor: config.zenithColor }),
+        ...(config.sunIntensity === undefined ? {} : { sunIntensity: config.sunIntensity }),
+        ...(config.ambientIntensity === undefined ? {} : { ambientIntensity: config.ambientIntensity }),
+        ...(config.fog === undefined ? {} : { fog: config.fog }),
     });
 }
 export function rain(config = {}) {
@@ -80,6 +117,7 @@ export function ocean(config = {}) {
         waveScale: config.waveScale ?? 18,
         waveSpeed: config.waveSpeed ?? 0.55,
         color: config.color ?? "#1d7fa3",
+        ...(config.position === undefined ? {} : { position: config.position }),
     };
 }
 export function building(config = {}) {
@@ -91,7 +129,19 @@ export function building(config = {}) {
         storyHeight: config.storyHeight ?? 3,
         spacing: config.spacing ?? 2,
         style: config.style ?? "generic",
-    }, config.seed === undefined ? undefined : { seed: config.seed });
+    }, {
+        ...(config.seed === undefined ? {} : { seed: config.seed }),
+        ...(config.position === undefined ? {} : { position: config.position }),
+    });
+}
+export function pad(config) {
+    return withOptional({
+        kind: "pad",
+        center: config.center,
+        size: config.size,
+        height: config.height ?? 0.05,
+        color: config.color ?? "#8b8680",
+    }, config.rotationY === undefined ? undefined : { rotationY: config.rotationY });
 }
 export function biomes(config) {
     return { kind: "biomes", ...config };

package/dist/world/gridInstances.d.ts

@@ -0,0 +1,13 @@
+import type { WorldGridConfig } from "./features.js";
+export interface GridInstanceTransform {
+    position: readonly [number, number, number];
+    scale: readonly [number, number, number];
+    color: string;
+}
+/**
+ * Pure cell→instance math for `biomes()`/`voxel()`/`plots()`/`tilemap()` world features: one
+ * extruded box per declared cell, grounded at y=0 and centered on its cell in x/z. Consumed by
+ * the shell's grid-world renderer so it can drive a single `THREE.InstancedMesh` without
+ * duplicating this math per game.
+ */
+export declare function resolveGridInstances(config: WorldGridConfig): readonly GridInstanceTransform[];

package/dist/world/gridInstances.js

@@ -0,0 +1,22 @@
+const DEFAULT_CELL_SIZE = 1;
+const DEFAULT_BASE_HEIGHT = 1;
+const DEFAULT_GRID_COLOR = "#8a8f98";
+/**
+ * Pure cell→instance math for `biomes()`/`voxel()`/`plots()`/`tilemap()` world features: one
+ * extruded box per declared cell, grounded at y=0 and centered on its cell in x/z. Consumed by
+ * the shell's grid-world renderer so it can drive a single `THREE.InstancedMesh` without
+ * duplicating this math per game.
+ */
+export function resolveGridInstances(config) {
+    const cells = config.cells ?? [];
+    const cellSize = config.cellSize ?? DEFAULT_CELL_SIZE;
+    const defaultColor = config.defaultColor ?? DEFAULT_GRID_COLOR;
+    return cells.map((cell) => {
+        const height = cell.height ?? config.baseHeight ?? DEFAULT_BASE_HEIGHT;
+        return {
+            position: [cell.x * cellSize, height / 2, cell.z * cellSize],
+            scale: [cellSize, height, cellSize],
+            color: cell.color ?? defaultColor,
+        };
+    });
+}

package/dist/world/placementController.d.ts

@@ -6,12 +6,24 @@ export interface PlacementHit {
     point: PlacementVec3;
     normal: PlacementVec3;
 }
+/** A fixed buildable slot the placement controller snaps to instead of grid/free positioning. */
+export interface PlacementSlot {
+    id: string;
+    center: PlacementVec3;
+    /** Capture radius around `center`. Defaults to `config.slotRadius`, then `1.5`. */
+    radius?: number;
+    /** `false` hides the slot from hover resolution without releasing it. Default `true`. */
+    enabled?: boolean;
+}
 export interface PlacementControllerConfig {
     footprint: Footprint;
     rules?: PlacementRules;
     snapMode?: SnapMode;
     grid?: number;
     quarterTurns?: number;
+    slots?: readonly PlacementSlot[];
+    /** Fallback capture radius for slots that don't set their own. Default `1.5`. */
+    slotRadius?: number;
 }
 export interface PlacementPreview {
     center: Vec2;
@@ -20,9 +32,11 @@ export interface PlacementPreview {
     footprint: Footprint;
     aabb: Aabb;
     valid: boolean;
-    reason?: "out-of-bounds" | "overlap";
+    reason?: "out-of-bounds" | "overlap" | "no-slot";
     snapMode: SnapMode;
     normal: PlacementVec3;
+    /** Id of the resolved slot, when the controller is in slot mode and a slot matched. */
+    slotId?: string;
 }
 export interface PlacementCommit {
     center: Vec2;
@@ -31,6 +45,8 @@ export interface PlacementCommit {
     quarterTurns: number;
     footprint: Footprint;
     aabb: Aabb;
+    /** Id of the slot this commit occupied, when the controller is in slot mode. */
+    slotId?: string;
 }
 export interface PlacementController {
     hover(hit: PlacementHit): PlacementPreview;
@@ -41,6 +57,11 @@ export interface PlacementController {
     setFootprint(footprint: Footprint): void;
     setRules(rules: PlacementRules): void;
     setGrid(grid: number): void;
+    setSlots(slots: readonly PlacementSlot[]): void;
+    /** Id of the currently hovered slot, or `null` when idle, out of slot mode, or unmatched. */
+    hoveredSlotId(): string | null;
+    /** Frees a previously committed slot so it can match again. */
+    releaseSlot(id: string): void;
     commit(): PlacementCommit | null;
     reset(): void;
 }

package/dist/world/placementController.js

@@ -1,6 +1,10 @@
 import { footprintAabb, snapToGrid } from "./geometry.js";
 import { validatePlacement } from "./placement.js";
 const SNAP_ORDER = ["grid", "free", "surface"];
+const DEFAULT_SLOT_RADIUS = 1.5;
+function distanceVec3(a, b) {
+    return Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
+}
 export function quarterTurnsToRotationY(quarterTurns) {
     const turns = ((quarterTurns % 4) + 4) % 4;
     return turns === 0 ? 0 : -turns * (Math.PI / 2);
@@ -11,6 +15,9 @@ export function createPlacementController(config) {
     let snapMode = config.snapMode ?? "grid";
     let grid = config.grid ?? rules.snap ?? 1;
     let quarterTurns = ((config.quarterTurns ?? 0) % 4 + 4) % 4;
+    let slots = config.slots;
+    const slotRadius = config.slotRadius ?? DEFAULT_SLOT_RADIUS;
+    const occupiedSlots = new Set();
     let lastHit = null;
     let preview = null;
     function snapCenter(raw) {
@@ -18,7 +25,40 @@ export function createPlacementController(config) {
             return snapToGrid(raw, grid);
         return raw;
     }
+    function nearestSlot(hit) {
+        let best = null;
+        let bestDistance = Number.POSITIVE_INFINITY;
+        for (const slot of slots ?? []) {
+            if (slot.enabled === false || occupiedSlots.has(slot.id))
+                continue;
+            const distance = distanceVec3(hit.point, slot.center);
+            if (distance <= (slot.radius ?? slotRadius) && distance < bestDistance) {
+                best = slot;
+                bestDistance = distance;
+            }
+        }
+        return best;
+    }
+    function computeSlotPreview(hit) {
+        const slot = nearestSlot(hit);
+        const center = slot === null ? [hit.point[0], hit.point[2]] : [slot.center[0], slot.center[2]];
+        const next = {
+            center,
+            y: slot === null ? hit.point[1] : slot.center[1],
+            quarterTurns,
+            footprint,
+            aabb: footprintAabb(center, footprint, quarterTurns),
+            valid: slot !== null,
+            snapMode,
+            normal: hit.normal,
+            ...(slot === null ? { reason: "no-slot" } : { slotId: slot.id }),
+        };
+        preview = next;
+        return next;
+    }
     function compute(hit) {
+        if (slots !== undefined)
+            return computeSlotPreview(hit);
         const raw = [hit.point[0], hit.point[2]];
         const center = snapCenter(raw);
         const rulesWithoutSnap = snapMode === "grid" ? { ...rules, snap: undefined } : rules;
@@ -76,9 +116,24 @@ export function createPlacementController(config) {
             if (lastHit !== null)
                 compute(lastHit);
         },
+        setSlots(next) {
+            slots = next;
+            if (lastHit !== null)
+                compute(lastHit);
+        },
+        hoveredSlotId() {
+            return preview?.slotId ?? null;
+        },
+        releaseSlot(id) {
+            occupiedSlots.delete(id);
+            if (lastHit !== null)
+                compute(lastHit);
+        },
         commit() {
             if (preview === null || !preview.valid)
                 return null;
+            if (preview.slotId !== undefined)
+                occupiedSlots.add(preview.slotId);
             return {
                 center: preview.center,
                 y: preview.y,
@@ -86,6 +141,7 @@ export function createPlacementController(config) {
                 quarterTurns,
                 footprint: preview.footprint,
                 aabb: preview.aabb,
+                ...(preview.slotId !== undefined ? { slotId: preview.slotId } : {}),
             };
         },
         reset() {