scena3d 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { Vector3, Group, Mesh, DirectionalLight, AmbientLight, HemisphereLight, Scene } from 'three';
+import { Vector3, Group, Mesh, DirectionalLight, AmbientLight, HemisphereLight, Scene, Object3D, Material } from 'three';
 
 /**
  * Deterministic seeded randomness — the backbone of SCENA. Same seed,
@@ -48,8 +48,15 @@ interface Palette {
     skyTop: number;
     skyBottom: number;
     fog: number;
+    water: number;
+    sand: number;
+    path: number;
+    /** Building plaster/wall color. */
+    wall: number;
+    /** Building roof color. */
+    roof: number;
 }
-declare const PALETTES: Record<'meadow' | 'autumn' | 'dusk', Palette>;
+declare const PALETTES: Record<'meadow' | 'autumn' | 'dusk' | 'winter', Palette>;
 declare const DEFAULT_PALETTE: Palette;
 
 /**
@@ -135,6 +142,65 @@ interface LampOptions {
 /** A street lamp: post, head, glowing bulb, optional real PointLight. */
 declare function createLamp(options?: LampOptions): Prop;
 
+interface GrassOptions {
+    seed?: number;
+    /** Blades per tuft. Default 4–6 by seed. */
+    blades?: number;
+    palette?: Palette;
+}
+/**
+ * A tuft of grass blades — pure scatter fodder (zero obstacle footprint,
+ * walk straight through). Sways beautifully under `applyWind`.
+ */
+declare function createGrassTuft(options?: GrassOptions): Prop;
+interface BushOptions {
+    seed?: number;
+    size?: number;
+    palette?: Palette;
+}
+/** A low foliage bush: two or three squashed blobs. Small footprint. */
+declare function createBush(options?: BushOptions): Prop;
+
+interface HouseOptions {
+    seed?: number;
+    /** Footprint width (gable side). Default seeded 3.2–4.2. */
+    width?: number;
+    depth?: number;
+    wallHeight?: number;
+    palette?: Palette;
+}
+/**
+ * A cottage: plastered walls, gabled roof, door, chimney and emissive
+ * windows. Pass the house in `createDayCycle`'s `lamps` list and its
+ * windows glow at night along with the street lamps. A stone foundation
+ * extends below ground so sloped terrain never shows a gap.
+ */
+declare function createHouse(options?: HouseOptions): Prop;
+interface TowerOptions {
+    seed?: number;
+    height?: number;
+    palette?: Palette;
+}
+/** A wooden watchtower: splayed legs, platform with railing, pyramid roof. */
+declare function createTower(options?: TowerOptions): Prop;
+interface WellOptions {
+    seed?: number;
+    palette?: Palette;
+}
+/** A stone well: ring, posts, little gabled roof, hanging bucket. */
+declare function createWell(options?: WellOptions): Prop;
+interface RuinOptions {
+    seed?: number;
+    /** Footprint width. Default seeded 3.5–5. */
+    size?: number;
+    palette?: Palette;
+}
+/**
+ * A ruined building: a partial rectangle of crumbling wall segments with
+ * seeded gaps and heights, and tumbled blocks around the floor.
+ */
+declare function createRuin(options?: RuinOptions): Prop;
+
 interface TerrainOptions {
     seed?: number;
     /** Square side length. Default 80. */
@@ -148,6 +214,8 @@ interface TerrainOptions {
     octaves?: number;
     /** Flatten low areas into meadows (0–1, higher = flatter valleys). Default 0.55. */
     valleyFlatness?: number;
+    /** Blend low bands toward sand below (waterLevel + shore margin). */
+    waterLevel?: number;
     palette?: Palette;
 }
 interface Terrain {
@@ -200,6 +268,215 @@ type FogPreset = 'clear' | 'haze' | 'thick' | 'eerie';
 /** Distance fog matched to the palette's fog color. 'clear' removes it. */
 declare function applyFog(scene: Scene, preset: FogPreset, palette?: Palette): void;
 
+interface WaterOptions {
+    /** World-space water surface height. Default 0.8. */
+    level?: number;
+    size?: number;
+    resolution?: number;
+    /** Wave height. Default 0.06. */
+    amplitude?: number;
+    /** Wave speed multiplier. Default 1. */
+    speed?: number;
+    palette?: Palette;
+}
+interface Water {
+    mesh: Mesh;
+    level: number;
+    /** Advance the wave animation. Call from your frame loop. */
+    update(dt: number): void;
+    /** Is ground at this height below the surface? */
+    isUnderwater(groundHeight: number): boolean;
+}
+/**
+ * A low-poly animated water plane at a fixed level. Pair it with a
+ * terrain built using the same `waterLevel` so shores blend to sand, and
+ * keep scatter/agents ashore with `aboveWater(terrain, water)`.
+ */
+declare function createWater(options?: WaterOptions): Water;
+/**
+ * A scatter mask keeping placements on dry land: true when the terrain
+ * at (x, z) sits above the water level plus `margin`.
+ */
+declare function aboveWater(terrain: Terrain, water: Pick<Water, 'level'>, margin?: number): (x: number, z: number) => boolean;
+
+interface DayCycleOptions {
+    sky?: Sky;
+    rig?: LightingRig;
+    /** Scene whose fog color should track the cycle. */
+    scene?: Scene;
+    /** Lamp props/objects whose PointLights + glow bulbs ignite at night. */
+    lamps?: Array<{
+        object: Object3D;
+    } | Object3D>;
+    palette?: Palette;
+    /** Seconds per full day. Default 60. */
+    dayLength?: number;
+    /** Initial time: 0 = midnight, 0.25 = dawn, 0.5 = noon, 0.75 = dusk. */
+    timeOfDay?: number;
+}
+interface DayCycle {
+    timeOfDay: number;
+    /** Sun elevation in [-1, 1]; negative = below the horizon. */
+    readonly sunElevation: number;
+    readonly isNight: boolean;
+    /** Advance by dt seconds of real time and re-apply everything. */
+    update(dt: number): void;
+    /** Jump to a time of day and re-apply everything. */
+    set(t: number): void;
+}
+/**
+ * One `timeOfDay` parameter driving the whole environment in lockstep:
+ * sun position/color/intensity, sky gradient, ambient level, fog color,
+ * and lamps that ignite as the sun drops below the horizon.
+ *
+ * ```ts
+ * const cycle = createDayCycle({ sky, rig, scene, lamps: [lampA, lampB], dayLength: 120 });
+ * game.onUpdate((t) => cycle.update(t.delta));
+ * ```
+ */
+declare function createDayCycle(options?: DayCycleOptions): DayCycle;
+
+interface WindOptions {
+    /** Sway amplitude in world units at the top of a prop. Default 0.06. */
+    strength?: number;
+    /** Oscillation speed. Default 1.2. */
+    frequency?: number;
+    /** Local height where sway begins (keeps trunks planted). Default 0.6. */
+    anchorHeight?: number;
+}
+interface Wind {
+    /** Advance the animation. Call from your frame loop. */
+    update(dt: number): void;
+    /** Materials that were patched (for debugging/cleanup). */
+    materials: Material[];
+}
+/**
+ * Vertex-shader wind sway for scattered vegetation: displacement grows
+ * with local height (trunk bases stay planted), phase varies per
+ * instance so a forest shimmers instead of marching in step. Works on
+ * meshes and InstancedMeshes; patches each unique material once via
+ * onBeforeCompile.
+ *
+ * ```ts
+ * const wind = applyWind(forest.group, { strength: 0.08 });
+ * game.onUpdate((t) => wind.update(t.delta));
+ * ```
+ */
+declare function applyWind(target: Object3D, options?: WindOptions): Wind;
+
+interface PathOptions {
+    /** Ribbon width. Default 1.8. */
+    width?: number;
+    /** Ground height lookup; a number means flat ground. Default 0. */
+    surface?: number | ((x: number, z: number) => number);
+    /** Samples per world unit of path length. Default 1. */
+    samplesPerUnit?: number;
+    /** Close the path into a loop. Default false. */
+    loop?: boolean;
+    /** Extra clearance added to scatter keep-out circles. Default 0.6. */
+    keepOutMargin?: number;
+    palette?: Palette;
+}
+interface WorldPath {
+    mesh: Mesh;
+    /** Smoothed centerline draped on the surface — feed straight into a
+     *  GAMA `Path` for patrols, or use as camera dolly points. */
+    route: Vector3[];
+    /** Keep-out circles for `scatter()` so nothing grows on the road. */
+    keepOut: Array<{
+        center: {
+            x: number;
+            z: number;
+        };
+        radius: number;
+    }>;
+    /** Is (x, z) on the path surface? (e.g. to exclude grass) */
+    contains(x: number, z: number): boolean;
+    loop: boolean;
+}
+/**
+ * A dirt path: a Catmull-Rom-smoothed ribbon draped over the surface.
+ * One authored polyline feeds three things at once — the visual ribbon,
+ * scatter keep-out, and a patrol route for agents. That's the SCENA
+ * handshake applied to level design.
+ *
+ * ```ts
+ * const road = createPath([a, b, c], { surface: terrain.heightAt, loop: true });
+ * scene.add(road.mesh);
+ * scatter({ ..., keepOut: road.keepOut });
+ * agent.addBehavior(new FollowPath(new Path(road.route, road.loop), 1.5));
+ * ```
+ */
+declare function createPath(points: Array<Vector3 | {
+    x: number;
+    z: number;
+}>, options?: PathOptions): WorldPath;
+
+interface VillageOptions {
+    seed?: number;
+    /** Village center in the XZ plane. Default origin. */
+    center?: {
+        x: number;
+        z: number;
+    };
+    /** Ring radius the houses settle on. Default 12. */
+    radius?: number;
+    /** House count. Default 5. */
+    houses?: number;
+    /** Ground height lookup; a number means flat ground. Default 0. */
+    surface?: number | ((x: number, z: number) => number);
+    /** Veto candidate spots (e.g. water, roads). Return false to reject. */
+    mask?: (x: number, z: number, y: number) => boolean;
+    /** Add real PointLights to this many street lamps. Default 3. */
+    lampLights?: number;
+    /** Add a watchtower at the edge. Default true. */
+    tower?: boolean;
+    /** Add a ruin outside the ring. Default true. */
+    ruin?: boolean;
+    palette?: Palette;
+}
+interface Village {
+    group: Group;
+    /** Every placed prop (houses, well, lamps, crates, tower, ruin). */
+    props: Prop[];
+    /** World-space steering obstacles — feed GAMA's ObstacleAvoidance. */
+    obstacles: Obstacle[];
+    /**
+     * Props with something to ignite at night (street lamps AND house
+     * windows). Pass straight to `createDayCycle({ lamps })`.
+     */
+    lamps: Prop[];
+    /** One clearing circle covering the village — feed `scatter`'s keepOut. */
+    keepOut: Array<{
+        center: {
+            x: number;
+            z: number;
+        };
+        radius: number;
+    }>;
+    center: {
+        x: number;
+        z: number;
+    };
+}
+/**
+ * A seeded hamlet: a well at the center, houses ringed around it facing
+ * inward, street lamps between them, crates by the doors, a watchtower on
+ * the edge and a ruin beyond. Everything is placed on the given surface
+ * (steep or masked spots are rejected and re-rolled), and the result
+ * carries the full gameplay handshake: `obstacles` for steering,
+ * `keepOut` for scatter, and `lamps` for the day-night cycle — windows
+ * and lamps ignite together at dusk.
+ *
+ * ```ts
+ * const village = createVillage({ seed: 5, radius: 10, surface: terrain.heightAt, palette });
+ * scene.add(village.group);
+ * const cycle = createDayCycle({ sky, rig, scene, lamps: village.lamps, palette });
+ * const forest = scatter({ ..., keepOut: village.keepOut });
+ * ```
+ */
+declare function createVillage(options?: VillageOptions): Village;
+
 interface ScatterItem {
     /** Prop factory, called once per visual variant with a seeded Rng. */
     create(rng: Rng): Prop;
@@ -285,4 +562,4 @@ interface ScatterResult {
  */
 declare function scatter(options: ScatterOptions): ScatterResult;
 
-export { type CrateOptions, DEFAULT_PALETTE, type FenceOptions, type FogPreset, type LampOptions, type LightingPreset, type LightingRig, type Obstacle, PALETTES, type Palette, type Placement, type Prop, Rng, type RockOptions, type ScatterItem, type ScatterOptions, type ScatterResult, type Sky, type SkyOptions, type Terrain, type TerrainOptions, type TreeOptions, applyFog, collectObstacles, createCrate, createFence, createLamp, createLightingRig, createRock, createSky, createTerrain, createTree, fractalNoise2, hash2, scatter, valueNoise2 };
+export { type BushOptions, type CrateOptions, DEFAULT_PALETTE, type DayCycle, type DayCycleOptions, type FenceOptions, type FogPreset, type GrassOptions, type HouseOptions, type LampOptions, type LightingPreset, type LightingRig, type Obstacle, PALETTES, type Palette, type PathOptions, type Placement, type Prop, Rng, type RockOptions, type RuinOptions, type ScatterItem, type ScatterOptions, type ScatterResult, type Sky, type SkyOptions, type Terrain, type TerrainOptions, type TowerOptions, type TreeOptions, type Village, type VillageOptions, type Water, type WaterOptions, type WellOptions, type Wind, type WindOptions, type WorldPath, aboveWater, applyFog, applyWind, collectObstacles, createBush, createCrate, createDayCycle, createFence, createGrassTuft, createHouse, createLamp, createLightingRig, createPath, createRock, createRuin, createSky, createTerrain, createTower, createTree, createVillage, createWater, createWell, fractalNoise2, hash2, scatter, valueNoise2 };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Vector3, Group, Mesh, DirectionalLight, AmbientLight, HemisphereLight, Scene } from 'three';
+import { Vector3, Group, Mesh, DirectionalLight, AmbientLight, HemisphereLight, Scene, Object3D, Material } from 'three';
 
 /**
  * Deterministic seeded randomness — the backbone of SCENA. Same seed,
@@ -48,8 +48,15 @@ interface Palette {
     skyTop: number;
     skyBottom: number;
     fog: number;
+    water: number;
+    sand: number;
+    path: number;
+    /** Building plaster/wall color. */
+    wall: number;
+    /** Building roof color. */
+    roof: number;
 }
-declare const PALETTES: Record<'meadow' | 'autumn' | 'dusk', Palette>;
+declare const PALETTES: Record<'meadow' | 'autumn' | 'dusk' | 'winter', Palette>;
 declare const DEFAULT_PALETTE: Palette;
 
 /**
@@ -135,6 +142,65 @@ interface LampOptions {
 /** A street lamp: post, head, glowing bulb, optional real PointLight. */
 declare function createLamp(options?: LampOptions): Prop;
 
+interface GrassOptions {
+    seed?: number;
+    /** Blades per tuft. Default 4–6 by seed. */
+    blades?: number;
+    palette?: Palette;
+}
+/**
+ * A tuft of grass blades — pure scatter fodder (zero obstacle footprint,
+ * walk straight through). Sways beautifully under `applyWind`.
+ */
+declare function createGrassTuft(options?: GrassOptions): Prop;
+interface BushOptions {
+    seed?: number;
+    size?: number;
+    palette?: Palette;
+}
+/** A low foliage bush: two or three squashed blobs. Small footprint. */
+declare function createBush(options?: BushOptions): Prop;
+
+interface HouseOptions {
+    seed?: number;
+    /** Footprint width (gable side). Default seeded 3.2–4.2. */
+    width?: number;
+    depth?: number;
+    wallHeight?: number;
+    palette?: Palette;
+}
+/**
+ * A cottage: plastered walls, gabled roof, door, chimney and emissive
+ * windows. Pass the house in `createDayCycle`'s `lamps` list and its
+ * windows glow at night along with the street lamps. A stone foundation
+ * extends below ground so sloped terrain never shows a gap.
+ */
+declare function createHouse(options?: HouseOptions): Prop;
+interface TowerOptions {
+    seed?: number;
+    height?: number;
+    palette?: Palette;
+}
+/** A wooden watchtower: splayed legs, platform with railing, pyramid roof. */
+declare function createTower(options?: TowerOptions): Prop;
+interface WellOptions {
+    seed?: number;
+    palette?: Palette;
+}
+/** A stone well: ring, posts, little gabled roof, hanging bucket. */
+declare function createWell(options?: WellOptions): Prop;
+interface RuinOptions {
+    seed?: number;
+    /** Footprint width. Default seeded 3.5–5. */
+    size?: number;
+    palette?: Palette;
+}
+/**
+ * A ruined building: a partial rectangle of crumbling wall segments with
+ * seeded gaps and heights, and tumbled blocks around the floor.
+ */
+declare function createRuin(options?: RuinOptions): Prop;
+
 interface TerrainOptions {
     seed?: number;
     /** Square side length. Default 80. */
@@ -148,6 +214,8 @@ interface TerrainOptions {
     octaves?: number;
     /** Flatten low areas into meadows (0–1, higher = flatter valleys). Default 0.55. */
     valleyFlatness?: number;
+    /** Blend low bands toward sand below (waterLevel + shore margin). */
+    waterLevel?: number;
     palette?: Palette;
 }
 interface Terrain {
@@ -200,6 +268,215 @@ type FogPreset = 'clear' | 'haze' | 'thick' | 'eerie';
 /** Distance fog matched to the palette's fog color. 'clear' removes it. */
 declare function applyFog(scene: Scene, preset: FogPreset, palette?: Palette): void;
 
+interface WaterOptions {
+    /** World-space water surface height. Default 0.8. */
+    level?: number;
+    size?: number;
+    resolution?: number;
+    /** Wave height. Default 0.06. */
+    amplitude?: number;
+    /** Wave speed multiplier. Default 1. */
+    speed?: number;
+    palette?: Palette;
+}
+interface Water {
+    mesh: Mesh;
+    level: number;
+    /** Advance the wave animation. Call from your frame loop. */
+    update(dt: number): void;
+    /** Is ground at this height below the surface? */
+    isUnderwater(groundHeight: number): boolean;
+}
+/**
+ * A low-poly animated water plane at a fixed level. Pair it with a
+ * terrain built using the same `waterLevel` so shores blend to sand, and
+ * keep scatter/agents ashore with `aboveWater(terrain, water)`.
+ */
+declare function createWater(options?: WaterOptions): Water;
+/**
+ * A scatter mask keeping placements on dry land: true when the terrain
+ * at (x, z) sits above the water level plus `margin`.
+ */
+declare function aboveWater(terrain: Terrain, water: Pick<Water, 'level'>, margin?: number): (x: number, z: number) => boolean;
+
+interface DayCycleOptions {
+    sky?: Sky;
+    rig?: LightingRig;
+    /** Scene whose fog color should track the cycle. */
+    scene?: Scene;
+    /** Lamp props/objects whose PointLights + glow bulbs ignite at night. */
+    lamps?: Array<{
+        object: Object3D;
+    } | Object3D>;
+    palette?: Palette;
+    /** Seconds per full day. Default 60. */
+    dayLength?: number;
+    /** Initial time: 0 = midnight, 0.25 = dawn, 0.5 = noon, 0.75 = dusk. */
+    timeOfDay?: number;
+}
+interface DayCycle {
+    timeOfDay: number;
+    /** Sun elevation in [-1, 1]; negative = below the horizon. */
+    readonly sunElevation: number;
+    readonly isNight: boolean;
+    /** Advance by dt seconds of real time and re-apply everything. */
+    update(dt: number): void;
+    /** Jump to a time of day and re-apply everything. */
+    set(t: number): void;
+}
+/**
+ * One `timeOfDay` parameter driving the whole environment in lockstep:
+ * sun position/color/intensity, sky gradient, ambient level, fog color,
+ * and lamps that ignite as the sun drops below the horizon.
+ *
+ * ```ts
+ * const cycle = createDayCycle({ sky, rig, scene, lamps: [lampA, lampB], dayLength: 120 });
+ * game.onUpdate((t) => cycle.update(t.delta));
+ * ```
+ */
+declare function createDayCycle(options?: DayCycleOptions): DayCycle;
+
+interface WindOptions {
+    /** Sway amplitude in world units at the top of a prop. Default 0.06. */
+    strength?: number;
+    /** Oscillation speed. Default 1.2. */
+    frequency?: number;
+    /** Local height where sway begins (keeps trunks planted). Default 0.6. */
+    anchorHeight?: number;
+}
+interface Wind {
+    /** Advance the animation. Call from your frame loop. */
+    update(dt: number): void;
+    /** Materials that were patched (for debugging/cleanup). */
+    materials: Material[];
+}
+/**
+ * Vertex-shader wind sway for scattered vegetation: displacement grows
+ * with local height (trunk bases stay planted), phase varies per
+ * instance so a forest shimmers instead of marching in step. Works on
+ * meshes and InstancedMeshes; patches each unique material once via
+ * onBeforeCompile.
+ *
+ * ```ts
+ * const wind = applyWind(forest.group, { strength: 0.08 });
+ * game.onUpdate((t) => wind.update(t.delta));
+ * ```
+ */
+declare function applyWind(target: Object3D, options?: WindOptions): Wind;
+
+interface PathOptions {
+    /** Ribbon width. Default 1.8. */
+    width?: number;
+    /** Ground height lookup; a number means flat ground. Default 0. */
+    surface?: number | ((x: number, z: number) => number);
+    /** Samples per world unit of path length. Default 1. */
+    samplesPerUnit?: number;
+    /** Close the path into a loop. Default false. */
+    loop?: boolean;
+    /** Extra clearance added to scatter keep-out circles. Default 0.6. */
+    keepOutMargin?: number;
+    palette?: Palette;
+}
+interface WorldPath {
+    mesh: Mesh;
+    /** Smoothed centerline draped on the surface — feed straight into a
+     *  GAMA `Path` for patrols, or use as camera dolly points. */
+    route: Vector3[];
+    /** Keep-out circles for `scatter()` so nothing grows on the road. */
+    keepOut: Array<{
+        center: {
+            x: number;
+            z: number;
+        };
+        radius: number;
+    }>;
+    /** Is (x, z) on the path surface? (e.g. to exclude grass) */
+    contains(x: number, z: number): boolean;
+    loop: boolean;
+}
+/**
+ * A dirt path: a Catmull-Rom-smoothed ribbon draped over the surface.
+ * One authored polyline feeds three things at once — the visual ribbon,
+ * scatter keep-out, and a patrol route for agents. That's the SCENA
+ * handshake applied to level design.
+ *
+ * ```ts
+ * const road = createPath([a, b, c], { surface: terrain.heightAt, loop: true });
+ * scene.add(road.mesh);
+ * scatter({ ..., keepOut: road.keepOut });
+ * agent.addBehavior(new FollowPath(new Path(road.route, road.loop), 1.5));
+ * ```
+ */
+declare function createPath(points: Array<Vector3 | {
+    x: number;
+    z: number;
+}>, options?: PathOptions): WorldPath;
+
+interface VillageOptions {
+    seed?: number;
+    /** Village center in the XZ plane. Default origin. */
+    center?: {
+        x: number;
+        z: number;
+    };
+    /** Ring radius the houses settle on. Default 12. */
+    radius?: number;
+    /** House count. Default 5. */
+    houses?: number;
+    /** Ground height lookup; a number means flat ground. Default 0. */
+    surface?: number | ((x: number, z: number) => number);
+    /** Veto candidate spots (e.g. water, roads). Return false to reject. */
+    mask?: (x: number, z: number, y: number) => boolean;
+    /** Add real PointLights to this many street lamps. Default 3. */
+    lampLights?: number;
+    /** Add a watchtower at the edge. Default true. */
+    tower?: boolean;
+    /** Add a ruin outside the ring. Default true. */
+    ruin?: boolean;
+    palette?: Palette;
+}
+interface Village {
+    group: Group;
+    /** Every placed prop (houses, well, lamps, crates, tower, ruin). */
+    props: Prop[];
+    /** World-space steering obstacles — feed GAMA's ObstacleAvoidance. */
+    obstacles: Obstacle[];
+    /**
+     * Props with something to ignite at night (street lamps AND house
+     * windows). Pass straight to `createDayCycle({ lamps })`.
+     */
+    lamps: Prop[];
+    /** One clearing circle covering the village — feed `scatter`'s keepOut. */
+    keepOut: Array<{
+        center: {
+            x: number;
+            z: number;
+        };
+        radius: number;
+    }>;
+    center: {
+        x: number;
+        z: number;
+    };
+}
+/**
+ * A seeded hamlet: a well at the center, houses ringed around it facing
+ * inward, street lamps between them, crates by the doors, a watchtower on
+ * the edge and a ruin beyond. Everything is placed on the given surface
+ * (steep or masked spots are rejected and re-rolled), and the result
+ * carries the full gameplay handshake: `obstacles` for steering,
+ * `keepOut` for scatter, and `lamps` for the day-night cycle — windows
+ * and lamps ignite together at dusk.
+ *
+ * ```ts
+ * const village = createVillage({ seed: 5, radius: 10, surface: terrain.heightAt, palette });
+ * scene.add(village.group);
+ * const cycle = createDayCycle({ sky, rig, scene, lamps: village.lamps, palette });
+ * const forest = scatter({ ..., keepOut: village.keepOut });
+ * ```
+ */
+declare function createVillage(options?: VillageOptions): Village;
+
 interface ScatterItem {
     /** Prop factory, called once per visual variant with a seeded Rng. */
     create(rng: Rng): Prop;
@@ -285,4 +562,4 @@ interface ScatterResult {
  */
 declare function scatter(options: ScatterOptions): ScatterResult;
 
-export { type CrateOptions, DEFAULT_PALETTE, type FenceOptions, type FogPreset, type LampOptions, type LightingPreset, type LightingRig, type Obstacle, PALETTES, type Palette, type Placement, type Prop, Rng, type RockOptions, type ScatterItem, type ScatterOptions, type ScatterResult, type Sky, type SkyOptions, type Terrain, type TerrainOptions, type TreeOptions, applyFog, collectObstacles, createCrate, createFence, createLamp, createLightingRig, createRock, createSky, createTerrain, createTree, fractalNoise2, hash2, scatter, valueNoise2 };
+export { type BushOptions, type CrateOptions, DEFAULT_PALETTE, type DayCycle, type DayCycleOptions, type FenceOptions, type FogPreset, type GrassOptions, type HouseOptions, type LampOptions, type LightingPreset, type LightingRig, type Obstacle, PALETTES, type Palette, type PathOptions, type Placement, type Prop, Rng, type RockOptions, type RuinOptions, type ScatterItem, type ScatterOptions, type ScatterResult, type Sky, type SkyOptions, type Terrain, type TerrainOptions, type TowerOptions, type TreeOptions, type Village, type VillageOptions, type Water, type WaterOptions, type WellOptions, type Wind, type WindOptions, type WorldPath, aboveWater, applyFog, applyWind, collectObstacles, createBush, createCrate, createDayCycle, createFence, createGrassTuft, createHouse, createLamp, createLightingRig, createPath, createRock, createRuin, createSky, createTerrain, createTower, createTree, createVillage, createWater, createWell, fractalNoise2, hash2, scatter, valueNoise2 };