scena3d 0.1.0 → 0.4.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Vector3, Group, Mesh, DirectionalLight, AmbientLight, HemisphereLight, Scene } from 'three';
+import { Group, Vector3, 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,9 +268,282 @@ 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;
+
+/**
+ * The kit grid: every kit piece snaps to this cell size (in world units).
+ * Shared snap dimensions are what make pieces combinable — a doorway cut
+ * in one wall lines up with the corridor on the other side.
+ */
+declare const KIT_UNIT = 2;
+interface KitOptions {
+    seed?: number;
+    /** Cell size override. Default KIT_UNIT. */
+    unit?: number;
+    /** Wall height. Default 2.6. */
+    wallHeight?: number;
+    /** Add real PointLights to this many torches. Default 4. */
+    torchLights?: number;
+    palette?: Palette;
+}
+interface Kit {
+    group: Group;
+    /** One obstacle per wall cell — feed GAMA's ObstacleAvoidance. */
+    obstacles: Obstacle[];
+    /** World positions of 'S' cells (player/NPC spawn points). */
+    spawns: Vector3[];
+    /** World positions of 'T' cells (torches), lit in placement order. */
+    torches: Vector3[];
+    /** Is (x, z) over a walkable floor cell? */
+    floorAt(x: number, z: number): boolean;
+    /** Footprint in world units: { width, depth } centered on the origin. */
+    size: {
+        width: number;
+        depth: number;
+    };
+}
+/**
+ * Assemble a dungeon/compound from an ASCII map — each character is one
+ * KIT_UNIT × KIT_UNIT cell, centered on the group origin:
+ *
+ * - `#` wall block (blocks movement, becomes an obstacle)
+ * - `.` floor tile
+ * - `D` doorway: floor + lintel spanning the gap overhead
+ * - `T` floor + standing torch (emissive flame; `createDayCycle` adopts it)
+ * - `S` floor + recorded spawn point
+ * - ` ` nothing
+ *
+ * ```ts
+ * const fort = assembleKit([
+ *   '#######',
+ *   '#..T..#',
+ *   '#.....D',
+ *   '#..S..#',
+ *   '#######',
+ * ], { palette });
+ * fort.group.position.set(20, terrain.heightAt(20, 5), 5);
+ * ```
+ *
+ * Walls and floors render as two InstancedMeshes regardless of map size.
+ */
+declare function assembleKit(rows: string[], options?: KitOptions): Kit;
+
 interface ScatterItem {
     /** Prop factory, called once per visual variant with a seeded Rng. */
     create(rng: Rng): Prop;
+    /**
+     * Simplified far-distance factory for LOD (e.g. a single cone for a
+     * tree). Only used when `ScatterOptions.lod` is set; items without one
+     * stay full-detail at every distance.
+     */
+    createFar?(rng: Rng): Prop;
     /** Relative frequency among items. Default 1. */
     weight?: number;
     /** Distinct variants generated per item (visual variety). Default 4. */
@@ -244,6 +585,18 @@ interface ScatterOptions {
     }[];
     /** Density-noise feature size in world units. Default 18. */
     clumpScale?: number;
+    /**
+     * Tile-based LOD: placements are bucketed into square tiles; tiles
+     * beyond `distance` from the camera swap full-detail instances for the
+     * items' `createFar` variants (with 10% hysteresis so tiles don't
+     * flicker at the boundary). Call `result.update(camera)` each frame.
+     */
+    lod?: {
+        /** Camera distance at which tiles switch to far variants. */
+        distance: number;
+        /** Tile side in world units. Default 16. */
+        tileSize?: number;
+    };
 }
 interface Placement {
     position: Vector3;
@@ -251,6 +604,14 @@ interface Placement {
     scale: number;
     itemIndex: number;
 }
+interface ScatterTile {
+    center: {
+        x: number;
+        z: number;
+    };
+    near: Group;
+    far: Group;
+}
 interface ScatterResult {
     /** One InstancedMesh per template part — a handful of draw calls total. */
     group: Group;
@@ -258,6 +619,12 @@ interface ScatterResult {
     /** World-space steering obstacles for everything with a footprint. */
     obstacles: Obstacle[];
     count: number;
+    /** LOD tiles (present when `lod` was requested). */
+    tiles?: ScatterTile[];
+    /** Re-evaluate tile LOD against the camera (present when `lod` was requested). */
+    update?(camera: {
+        position: Vector3;
+    }): void;
 }
 /**
  * Populate an area with seeded, instanced props: "empty plane → forest"
@@ -285,4 +652,168 @@ 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 };
+/** Prop vocabulary available to manifest scatters. */
+type ScatterPropType = 'tree' | 'rock' | 'bush' | 'grass' | 'crate' | 'fence' | 'lamp';
+interface ManifestScatterItem {
+    type: ScatterPropType;
+    weight?: number;
+    variants?: number;
+    scale?: [number, number];
+}
+interface ManifestScatter {
+    /** Defaults to the terrain footprint (slightly inset). */
+    area?: {
+        min: {
+            x: number;
+            z: number;
+        };
+        max: {
+            x: number;
+            z: number;
+        };
+    };
+    density?: number;
+    count?: number;
+    minSpacing?: number;
+    clumpScale?: number;
+    items: ManifestScatterItem[];
+    /** Reject spots above this ground height (keep peaks bare). */
+    maxHeight?: number;
+    /** Keep placements ashore. Default true when the scene has water. */
+    avoidWater?: boolean;
+    /** Keep placements off paths and out of the village. Default true. */
+    avoidPaths?: boolean;
+    /** Opt into tile-based LOD (see ScatterOptions.lod). */
+    lod?: {
+        distance: number;
+        tileSize?: number;
+    };
+}
+/**
+ * A whole world as plain JSON — every field is data, so manifests can be
+ * stored, diffed, sent over the network, or edited in a tool.
+ */
+interface SceneManifest {
+    seed?: number;
+    palette?: keyof typeof PALETTES;
+    terrain?: {
+        size?: number;
+        resolution?: number;
+        amplitude?: number;
+        noiseScale?: number;
+        octaves?: number;
+        valleyFlatness?: number;
+    };
+    water?: {
+        level: number;
+        size?: number;
+    };
+    /** Sky dome. Default true. */
+    sky?: boolean;
+    lighting?: LightingPreset;
+    /** Fog preset, or false for none. Default 'haze'. */
+    fog?: FogPreset | false;
+    /** Animated day-night cycle. Off unless specified. */
+    dayCycle?: {
+        dayLength?: number;
+        timeOfDay?: number;
+    };
+    paths?: Array<{
+        points: Array<{
+            x: number;
+            z: number;
+        }>;
+        width?: number;
+        loop?: boolean;
+    }>;
+    village?: {
+        center?: {
+            x: number;
+            z: number;
+        };
+        radius?: number;
+        houses?: number;
+        lampLights?: number;
+        tower?: boolean;
+        ruin?: boolean;
+    };
+    scatters?: ManifestScatter[];
+    /** Vegetation sway. Default on; false disables, or set the strength. */
+    wind?: boolean | {
+        strength?: number;
+    };
+}
+interface BuiltScene {
+    /** Everything visual, ready to add to a scene (already added if one was passed). */
+    group: Group;
+    palette: Palette;
+    terrain?: Terrain;
+    water?: Water;
+    sky?: Sky;
+    rig: LightingRig;
+    cycle?: DayCycle;
+    paths: WorldPath[];
+    village?: Village;
+    scatters: ScatterResult[];
+    /** Combined steering obstacles from the village and every scatter. */
+    obstacles: Obstacle[];
+    /** Ground height (terrain's, or 0 for flat scenes). */
+    heightAt(x: number, z: number): number;
+    /** Advance water, wind and the day cycle. Call from your frame loop. */
+    update(dt: number): void;
+}
+/**
+ * Compile a `SceneManifest` into a live world: terrain, water, sky,
+ * lighting, fog, paths, a village, scatters and the day cycle — with all
+ * the cross-feature wiring the forest demo does by hand applied
+ * automatically (scatters stay ashore, off paths and out of the village;
+ * the village avoids water and roads; village lamps and windows feed the
+ * day cycle).
+ *
+ * ```ts
+ * const world = buildScene(JSON.parse(manifestJson), scene);
+ * game.onUpdate((t) => world.update(t.delta));
+ * agent.addBehavior(new ObstacleAvoidance(() => world.obstacles));
+ * ```
+ */
+declare function buildScene(manifest: SceneManifest, scene?: Scene): BuiltScene;
+
+interface Markers {
+    /** `spawn_<name>` → world position. */
+    spawns: Record<string, Vector3>;
+    /** `route_<name>_<index>` → world positions ordered by index. */
+    routes: Record<string, Vector3[]>;
+    /** `obstacle_<name>` → steering obstacle (radius from the node's scale). */
+    obstacles: Obstacle[];
+    /** `keepout_<name>` → scatter keep-out circle (radius from scale). */
+    keepOut: Array<{
+        center: {
+            x: number;
+            z: number;
+        };
+        radius: number;
+    }>;
+}
+/**
+ * Extract gameplay markers from an object tree by naming convention — the
+ * bridge between a DCC tool (Blender empties, glTF nodes) and SCENA/GAMA:
+ *
+ * - `spawn_player`, `spawn_boss` → named spawn points
+ * - `route_patrol_0`, `route_patrol_1`, … → ordered patrol routes
+ * - `obstacle_statue` → steering obstacle; radius = max(scale.x, scale.z)
+ * - `keepout_plaza` → scatter keep-out circle; radius = max(scale.x, scale.z)
+ *
+ * Blender's duplicate suffixes (`.001`) are stripped, so `route_a_0.001`
+ * still parses. Positions are world-space (the tree is updated first).
+ *
+ * ```ts
+ * const gltf = await new GLTFLoader().loadAsync('level.glb');
+ * const markers = extractMarkers(gltf.scene);
+ * player.position.copy(markers.spawns.player);
+ * guard.addBehavior(new FollowPath(new Path(markers.routes.patrol, true), 1.5));
+ * scatter({ ..., keepOut: markers.keepOut });
+ * ```
+ */
+declare function extractMarkers(root: Object3D): Markers;
+
+export { type BuiltScene, type BushOptions, type CrateOptions, DEFAULT_PALETTE, type DayCycle, type DayCycleOptions, type FenceOptions, type FogPreset, type GrassOptions, type HouseOptions, KIT_UNIT, type Kit, type KitOptions, type LampOptions, type LightingPreset, type LightingRig, type ManifestScatter, type ManifestScatterItem, type Markers, type Obstacle, PALETTES, type Palette, type PathOptions, type Placement, type Prop, Rng, type RockOptions, type RuinOptions, type ScatterItem, type ScatterOptions, type ScatterPropType, type ScatterResult, type ScatterTile, type SceneManifest, 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, assembleKit, buildScene, collectObstacles, createBush, createCrate, createDayCycle, createFence, createGrassTuft, createHouse, createLamp, createLightingRig, createPath, createRock, createRuin, createSky, createTerrain, createTower, createTree, createVillage, createWater, createWell, extractMarkers, fractalNoise2, hash2, scatter, valueNoise2 };