scena3d 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,288 @@
+import { Vector3, Group, Mesh, DirectionalLight, AmbientLight, HemisphereLight, Scene } from 'three';
+
+/**
+ * Deterministic seeded randomness — the backbone of SCENA. Same seed,
+ * same tree; forests are reproducible, diffable and network-syncable.
+ */
+declare class Rng {
+    private state;
+    constructor(seed?: number);
+    /** Next float in [0, 1) (mulberry32). */
+    next(): number;
+    /** Float in [min, max). */
+    range(min: number, max: number): number;
+    /** Integer in [min, max] inclusive. */
+    int(min: number, max: number): number;
+    /** Random element of a non-empty array. */
+    pick<T>(items: readonly T[]): T;
+    /** value ± spread (uniform). */
+    jitter(value: number, spread: number): number;
+    /** A new independent Rng derived from this one. */
+    fork(): Rng;
+}
+/** Integer-lattice hash to [0, 1) — the base of the value noise. */
+declare function hash2(ix: number, iz: number, seed: number): number;
+/** 2D value noise in [0, 1). Continuous; used by terrain and scatter density. */
+declare function valueNoise2(x: number, z: number, seed: number): number;
+/** Fractal (octaved) value noise in [0, 1). */
+declare function fractalNoise2(x: number, z: number, seed: number, octaves?: number, lacunarity?: number, gain?: number): number;
+
+/**
+ * Theme palettes: one coherent set of colors shared by every generator,
+ * so procedural props look like a matched set rather than a junk drawer.
+ * Pass `palette` to any generator to restyle it; whole scenes retheme by
+ * building with a different palette.
+ */
+interface Palette {
+    foliage: number[];
+    trunk: number;
+    rock: number[];
+    wood: number;
+    woodDark: number;
+    metal: number;
+    lampGlow: number;
+    grassLow: number;
+    grassHigh: number;
+    cliff: number;
+    peak: number;
+    skyTop: number;
+    skyBottom: number;
+    fog: number;
+}
+declare const PALETTES: Record<'meadow' | 'autumn' | 'dusk', Palette>;
+declare const DEFAULT_PALETTE: Palette;
+
+/**
+ * A steering obstacle in world space — structurally identical to GAMA's
+ * `Obstacle`, so SCENA props plug straight into `ObstacleAvoidance`
+ * without either library importing the other.
+ */
+interface Obstacle {
+    center: Vector3;
+    radius: number;
+}
+/** What a prop generator returns: the visual plus gameplay metadata. */
+interface Prop {
+    object: Group;
+    /**
+     * Footprint radius for steering/placement, in the prop's local space
+     * (centered at its origin). 0 means walk-through (e.g. grass).
+     */
+    obstacleRadius: number;
+}
+/** Collect world-space obstacles from placed props (call after positioning). */
+declare function collectObstacles(props: Iterable<Prop>): Obstacle[];
+
+interface TreeOptions {
+    seed?: number;
+    /** Overall height in world units. Default ~3.5–5 by seed. */
+    height?: number;
+    style?: 'pine' | 'oak';
+    palette?: Palette;
+}
+/**
+ * A seeded low-poly tree. `pine` stacks cones; `oak` clusters foliage
+ * blobs on a forked trunk. Same seed → identical tree, forever.
+ */
+declare function createTree(options?: TreeOptions): Prop;
+
+interface RockOptions {
+    seed?: number;
+    /** Approximate radius. Default ~0.4–1.1 by seed. */
+    size?: number;
+    palette?: Palette;
+}
+/**
+ * A seeded low-poly boulder: an icosahedron with jittered vertices and a
+ * flattened underside so it sits on the ground.
+ */
+declare function createRock(options?: RockOptions): Prop;
+
+interface CrateOptions {
+    seed?: number;
+    size?: number;
+    /** 0–1 color wear. Default 0.3. */
+    weathering?: number;
+    palette?: Palette;
+}
+/** A wooden crate: panel box with darker edge framing, seeded wear tint. */
+declare function createCrate(options?: CrateOptions): Prop;
+
+interface FenceOptions {
+    seed?: number;
+    /** Run length along local +x. Default 6. */
+    length?: number;
+    postSpacing?: number;
+    height?: number;
+    palette?: Palette;
+}
+/**
+ * A rustic fence run along local +x, centered at the origin: posts with
+ * two slightly-crooked rails. Chain several and rotate to enclose areas.
+ * The obstacle radius covers the whole run (rough but steering-safe);
+ * for tight navigation, bake a navmesh — the geometry is authoritative.
+ */
+declare function createFence(options?: FenceOptions): Prop;
+
+interface LampOptions {
+    seed?: number;
+    height?: number;
+    /** Add a real PointLight. Off by default — lights are a budget. */
+    light?: boolean;
+    lightIntensity?: number;
+    palette?: Palette;
+}
+/** A street lamp: post, head, glowing bulb, optional real PointLight. */
+declare function createLamp(options?: LampOptions): Prop;
+
+interface TerrainOptions {
+    seed?: number;
+    /** Square side length. Default 80. */
+    size?: number;
+    /** Vertices per side. Default 96. */
+    resolution?: number;
+    /** Peak height. Default 6. */
+    amplitude?: number;
+    /** Noise feature size in world units. Default 28. */
+    noiseScale?: number;
+    octaves?: number;
+    /** Flatten low areas into meadows (0–1, higher = flatter valleys). Default 0.55. */
+    valleyFlatness?: number;
+    palette?: Palette;
+}
+interface Terrain {
+    mesh: Mesh;
+    /** Exact analytic height at any (x, z) — same function that built the
+     *  mesh, so agents/navmesh queries never disagree with the visuals. */
+    heightAt(x: number, z: number): number;
+    size: number;
+    seed: number;
+}
+/**
+ * A seeded low-poly terrain: fractal value noise displacing a plane, with
+ * height/slope-banded vertex colors (grass → high grass → cliff → peak).
+ * The height function is exported, not just baked into vertices — that's
+ * what lets gameplay (spawning, scattering, navmesh baking, agent ground
+ * clamping) agree exactly with what's rendered.
+ */
+declare function createTerrain(options?: TerrainOptions): Terrain;
+
+interface SkyOptions {
+    topColor?: number;
+    bottomColor?: number;
+    radius?: number;
+    palette?: Palette;
+}
+interface Sky {
+    mesh: Mesh;
+    setColors(top: number, bottom: number): void;
+}
+/**
+ * A gradient sky dome (vertical color blend on an inverted sphere).
+ * Colors default to the palette, so themed scenes get matching skies.
+ */
+declare function createSky(options?: SkyOptions): Sky;
+
+type LightingPreset = 'day' | 'golden-hour' | 'overcast' | 'night';
+interface LightingRig {
+    group: Group;
+    sun: DirectionalLight;
+    ambient: AmbientLight;
+    hemisphere: HemisphereLight;
+}
+/**
+ * The three lights every scene rebuilds, as a preset: warm directional
+ * "sun" (position doubles as light direction), ambient fill, and a
+ * hemisphere tint. Retune any of them via the returned rig.
+ */
+declare function createLightingRig(preset?: LightingPreset): LightingRig;
+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 ScatterItem {
+    /** Prop factory, called once per visual variant with a seeded Rng. */
+    create(rng: Rng): Prop;
+    /** Relative frequency among items. Default 1. */
+    weight?: number;
+    /** Distinct variants generated per item (visual variety). Default 4. */
+    variants?: number;
+    /** Per-instance uniform scale range. Default [0.8, 1.25]. */
+    scale?: [number, number];
+}
+interface ScatterOptions {
+    seed?: number;
+    items: ScatterItem[];
+    /** Placement region in the XZ plane. */
+    area: {
+        min: {
+            x: number;
+            z: number;
+        };
+        max: {
+            x: number;
+            z: number;
+        };
+    };
+    /** Ground height lookup; a number means flat ground. Default 0. */
+    surface?: number | ((x: number, z: number) => number);
+    /** Expected instances per square unit (thinned by density noise). */
+    density?: number;
+    /** Or an exact target count (before masks/spacing rejections). */
+    count?: number;
+    /** Veto function: return false to reject a candidate point. */
+    mask?: (x: number, z: number, y: number) => boolean;
+    /** Minimum distance between any two placements. Default 1.2. */
+    minSpacing?: number;
+    /** World-space circles to keep clear (paths, spawns, buildings). */
+    keepOut?: Obstacle[] | {
+        center: {
+            x: number;
+            z: number;
+        };
+        radius: number;
+    }[];
+    /** Density-noise feature size in world units. Default 18. */
+    clumpScale?: number;
+}
+interface Placement {
+    position: Vector3;
+    rotationY: number;
+    scale: number;
+    itemIndex: number;
+}
+interface ScatterResult {
+    /** One InstancedMesh per template part — a handful of draw calls total. */
+    group: Group;
+    placements: Placement[];
+    /** World-space steering obstacles for everything with a footprint. */
+    obstacles: Obstacle[];
+    count: number;
+}
+/**
+ * Populate an area with seeded, instanced props: "empty plane → forest"
+ * in one call. Placement uses density noise for natural clumping, a
+ * spatial hash for minimum spacing, and masks/keep-out circles for
+ * exclusion. Rendering merges every placement into InstancedMeshes — a
+ * few draw calls for thousands of props.
+ *
+ * ```ts
+ * const forest = scatter({
+ *   seed: 7,
+ *   area: { min: { x: -40, z: -40 }, max: { x: 40, z: 40 } },
+ *   surface: terrain.heightAt,
+ *   density: 0.04,
+ *   items: [
+ *     { create: (rng) => createTree({ seed: rng.int(1, 1e9) }), weight: 3 },
+ *     { create: (rng) => createRock({ seed: rng.int(1, 1e9) }) },
+ *   ],
+ *   mask: (x, z, y) => y > 0.5 && y < 5,        // between shore and peaks
+ *   keepOut: [{ center: village, radius: 12 }],
+ * });
+ * scene.add(forest.group);
+ * agent.addBehavior(new ObstacleAvoidance(() => forest.obstacles));
+ * ```
+ */
+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 };