af-motion 0.0.0-stage → 1.0.0

package/dist/3d/terrain/types.d.ts

@@ -0,0 +1,235 @@
+/**
+ * AF Motion — 3D Procedural Terrain Types & Architecture
+ *
+ * Strongly-typed data structures for procedural heightmaps, multi-octave noise,
+ * hydraulic/thermal erosion, biomes, materials, vegetation scattering, LOD chunks,
+ * and heightfield physics integration.
+ */
+import type { Vector3, AABB3D, Quaternion, Collider3D } from "../physics/types.js";
+export type TerrainNoiseType = "perlin" | "simplex" | "fbm" | "ridged" | "domain-warp" | "cellular" | "voronoi";
+export type NoiseBlendMode = "add" | "multiply" | "max" | "min" | "lerp";
+export interface NoiseLayerConfig {
+    /** Noise algorithm. Default: "fbm". */
+    type?: TerrainNoiseType;
+    /** Octaves count for fractal noise. Default: 6. */
+    octaves?: number;
+    /** Base spatial frequency. Default: 0.005. */
+    frequency?: number;
+    /** Amplitude multiplier per octave (lacunarity persistence). Default: 0.5. */
+    persistence?: number;
+    /** Frequency multiplier per octave. Default: 2.0. */
+    lacunarity?: number;
+    /** Output height scale amplitude. Default: 50. */
+    amplitude?: number;
+    /** Seed value for deterministic procedural generation. */
+    seed?: number | string;
+    /** Domain warping distortion strength. Default: 0. */
+    warpStrength?: number;
+    /** Cellular noise jitter factor in [0, 1]. Default: 1.0. */
+    cellularJitter?: number;
+    /** Layer blending mode. Default: "add". */
+    blendMode?: NoiseBlendMode;
+    /** Layer blending weight in [0, 1]. Default: 1.0. */
+    weight?: number;
+    /** Vertical elevation offset. Default: 0. */
+    offset?: number;
+    /** Exponent curve applied to height output (e.g. 2.0 for mountain valleys). Default: 1.0. */
+    exponent?: number;
+}
+export type TerrainPreset = "flat" | "rolling-hills" | "mountain-ranges" | "valleys" | "plateaus" | "canyons" | "islands" | "archipelagos" | "craters" | "custom";
+export interface HeightmapData {
+    /** Width dimension in world units (along X axis). */
+    width: number;
+    /** Length dimension in world units (along Z axis). */
+    length: number;
+    /** Number of discrete grid points along X (columns). */
+    cols: number;
+    /** Number of discrete grid points along Z (rows). */
+    rows: number;
+    /** Flat array of elevation values of size cols * rows. */
+    heights: Float32Array;
+    /** Minimum recorded elevation. */
+    minHeight: number;
+    /** Maximum recorded elevation. */
+    maxHeight: number;
+    /** Spacing between adjacent grid samples along X. */
+    stepX: number;
+    /** Spacing between adjacent grid samples along Z. */
+    stepZ: number;
+}
+export interface TerrainMeshBuffers {
+    /** Vertex positions [x0, y0, z0, x1, y1, z1, ...]. */
+    positions: Float32Array;
+    /** Vertex surface normals [nx0, ny0, nz0, ...]. */
+    normals: Float32Array;
+    /** Vertex UV texture coordinates [u0, v0, u1, v1, ...]. */
+    uvs: Float32Array;
+    /** Triangle indices for indexed drawing. */
+    indices: Uint32Array;
+    /** Optional RGBA vertex colors for multi-biome splat blending [r0, g0, b0, a0, ...]. */
+    colors?: Float32Array;
+}
+export interface HydraulicErosionConfig {
+    /** Number of simulated water droplets. Default: 50000. */
+    dropletCount?: number;
+    /** Maximum steps a droplet can survive. Default: 30. */
+    maxLifetime?: number;
+    /** Erosion rate coefficient. Default: 0.3. */
+    erosionSpeed?: number;
+    /** Deposition rate coefficient. Default: 0.3. */
+    depositionSpeed?: number;
+    /** Evaporation rate per step [0, 1]. Default: 0.01. */
+    evaporationRate?: number;
+    /** Minimum slope angle to prevent zero-capacity stalling. Default: 0.01. */
+    minSlope?: number;
+    /** Sediment capacity factor. Default: 4.0. */
+    sedimentCapacity?: number;
+    /** Inertia factor [0, 1] weighting direction continuity. Default: 0.05. */
+    inertia?: number;
+    /** Droplet initial water volume. Default: 1.0. */
+    initialWater?: number;
+    /** Droplet initial speed. Default: 1.0. */
+    initialSpeed?: number;
+    /** Erosion brush radius in grid cells. Default: 2. */
+    radius?: number;
+    /** Deterministic PRNG seed. */
+    seed?: number | string;
+}
+export interface ThermalErosionConfig {
+    /** Number of thermal relaxation iterations. Default: 5. */
+    iterations?: number;
+    /** Talus angle threshold in degrees (slope beyond which scree falls). Default: 35. */
+    talusAngleDegrees?: number;
+    /** Fraction of excess material moved per step [0, 1]. Default: 0.5. */
+    displacementRate?: number;
+}
+export type BiomeType = "desert" | "grassland" | "forest" | "tundra" | "snow" | "alpine" | "tropical" | "wetlands" | "rocky" | string;
+export interface BiomeRule {
+    name: BiomeType;
+    /** Elevation range normalized to [0, 1]. */
+    elevationRange?: [number, number];
+    /** Slope range in degrees [0, 90]. */
+    slopeRangeDegrees?: [number, number];
+    /** Moisture range in [0, 1]. */
+    moistureRange?: [number, number];
+    /** Temperature range in [0, 1]. */
+    temperatureRange?: [number, number];
+    /** Base surface color for this biome (RGB tuple). */
+    color?: [number, number, number];
+    /** Surface roughness. Default: 0.8. */
+    roughness?: number;
+    /** Surface metalness. Default: 0.0. */
+    metalness?: number;
+}
+export interface BiomeWeightMap {
+    /** Dominant biome name per grid vertex. */
+    dominantBiome: BiomeType[];
+    /** Normalized biome weights per vertex of size cols * rows * activeBiomes. */
+    weights: Float32Array;
+    /** Active biome names ordered by index. */
+    biomeNames: string[];
+}
+export type VegetationCategory = "trees" | "grass" | "rocks" | "bushes" | "flowers" | "props" | string;
+export interface VegetationScatterRule {
+    id: string;
+    category: VegetationCategory;
+    /** Target density (instances per 100 square meters). Default: 5. */
+    density?: number;
+    /** Minimum spacing distance between instances. Default: 2.0. */
+    minSpacing?: number;
+    /** Allowed biomes for this prop type. If undefined, allowed everywhere. */
+    allowedBiomes?: BiomeType[];
+    /** Elevation range in world units [minY, maxY]. */
+    elevationRange?: [number, number];
+    /** Slope range in degrees [minSlope, maxSlope]. */
+    slopeRangeDegrees?: [number, number];
+    /** Minimum and maximum scale multipliers. Default: [0.8, 1.2]. */
+    scaleRange?: [number, number];
+    /** Whether to align prop orientation with the terrain surface normal. Default: false. */
+    alignToNormal?: boolean;
+}
+export interface VegetationInstance {
+    id: string;
+    category: VegetationCategory;
+    position: Vector3;
+    rotation: Quaternion;
+    scale: Vector3;
+    biome: BiomeType;
+    normal: Vector3;
+}
+export interface TerrainChunkConfig {
+    chunkX: number;
+    chunkZ: number;
+    worldOrigin: Vector3;
+    chunkWidth: number;
+    chunkLength: number;
+    resolution: number;
+}
+export interface TerrainChunk {
+    id: string;
+    chunkX: number;
+    chunkZ: number;
+    worldBounds: AABB3D;
+    lodLevel: number;
+    buffers: TerrainMeshBuffers;
+    disposed: boolean;
+}
+export interface TerrainConfig {
+    id?: string;
+    /** Total world width along X axis. Default: 200. */
+    width?: number;
+    /** Total world length along Z axis. Default: 200. */
+    length?: number;
+    /** Discrete grid divisions along X. Default: 128. */
+    resolutionX?: number;
+    /** Discrete grid divisions along Z. Default: 128. */
+    resolutionZ?: number;
+    /** Terrain world position origin (center or min). Default: { x: 0, y: 0, z: 0 }. */
+    origin?: Vector3;
+    /** Macro height preset. Default: "rolling-hills". */
+    preset?: TerrainPreset;
+    /** Noise layer configurations composing the terrain. */
+    noiseLayers?: NoiseLayerConfig[];
+    /** Deterministic global PRNG seed. Default: 1337. */
+    seed?: number | string;
+    /** Hydraulic erosion options. If true or config object, applied after noise. */
+    hydraulicErosion?: boolean | HydraulicErosionConfig;
+    /** Thermal erosion options. If true or config object, applied after noise. */
+    thermalErosion?: boolean | ThermalErosionConfig;
+    /** Custom biome classification rules. */
+    biomes?: BiomeRule[];
+    /** Vegetation scattering rules. */
+    vegetationRules?: VegetationScatterRule[];
+    /** Chunk subdivision count along each axis (e.g. 4 for 4x4 chunks). Default: 1. */
+    chunkCount?: number;
+    /** Whether to compute and register a physics heightfield collider. Default: true. */
+    enablePhysics?: boolean;
+    /** Whether to enable GPU acceleration where hardware allows. Default: false. */
+    useGPU?: boolean;
+}
+export interface Terrain3D {
+    id: string;
+    config: Required<Pick<TerrainConfig, "width" | "length" | "resolutionX" | "resolutionZ">> & TerrainConfig;
+    heightmap: HeightmapData;
+    meshBuffers: TerrainMeshBuffers;
+    bounds: AABB3D;
+    biomes: BiomeWeightMap;
+    vegetation: VegetationInstance[];
+    chunks: TerrainChunk[];
+    collider?: Collider3D;
+    /** Sample surface elevation at arbitrary world coordinate (X, Z). */
+    sampleHeight(worldX: number, worldZ: number): number;
+    /** Sample surface normal vector at arbitrary world coordinate (X, Z). */
+    sampleNormal(worldX: number, worldZ: number): Vector3;
+    /** Sample dominant biome at arbitrary world coordinate (X, Z). */
+    sampleBiome(worldX: number, worldZ: number): BiomeType;
+    /** Raycast against the terrain surface. */
+    raycast(rayOrigin: Vector3, rayDir: Vector3, maxDistance?: number): {
+        hit: boolean;
+        point: Vector3;
+        normal: Vector3;
+        distance: number;
+    } | null;
+    /** Dispose all allocated buffers and colliders. */
+    dispose(): void;
+}

package/dist/3d/terrain/vegetation.d.ts

@@ -0,0 +1,14 @@
+/**
+ * AF Motion — 3D Terrain Vegetation & Prop Scattering
+ *
+ * Deterministic spatial distribution of vegetation, trees, rocks, bushes,
+ * and environmental props using stratified jittered sampling, biome filtering,
+ * slope constraints, and surface normal alignment.
+ */
+import type { HeightmapData, BiomeWeightMap, VegetationScatterRule, VegetationInstance } from "./types.js";
+export declare const DEFAULT_VEGETATION_RULES: VegetationScatterRule[];
+/**
+ * Scatters vegetation instances across the terrain matching biome, slope,
+ * elevation rules, and minimum proximity constraints.
+ */
+export declare function scatterTerrainVegetation(heightmap: HeightmapData, biomes: BiomeWeightMap, rules?: VegetationScatterRule[], seed?: number | string): VegetationInstance[];

package/dist/3d/types.d.ts

@@ -0,0 +1,176 @@
+/**
+ * AF Motion 3D Scene & Rendering Contracts
+ *
+ * Framework-independent contracts for 3D scenes, cameras, lighting,
+ * environments, object graphs, renderer adapters, and capability detection.
+ */
+export type CameraType = "perspective" | "orthographic";
+export type Vector3Tuple = readonly [x: number, y: number, z: number];
+export type EulerTuple = readonly [x: number, y: number, z: number];
+export interface Camera3DConfig {
+    readonly type?: CameraType;
+    readonly fov?: number;
+    readonly aspect?: number;
+    readonly near?: number;
+    readonly far?: number;
+    readonly zoom?: number;
+    readonly position?: Vector3Tuple;
+    readonly target?: Vector3Tuple;
+    readonly up?: Vector3Tuple;
+}
+export interface AmbientLightConfig {
+    readonly color?: string;
+    readonly intensity?: number;
+}
+export interface DirectionalLightConfig {
+    readonly color?: string;
+    readonly intensity?: number;
+    readonly position?: Vector3Tuple;
+    readonly target?: Vector3Tuple;
+    readonly castShadow?: boolean;
+}
+export interface PointLightConfig {
+    readonly color?: string;
+    readonly intensity?: number;
+    readonly position?: Vector3Tuple;
+    readonly distance?: number;
+    readonly decay?: number;
+    readonly castShadow?: boolean;
+}
+export interface SpotLightConfig {
+    readonly color?: string;
+    readonly intensity?: number;
+    readonly position?: Vector3Tuple;
+    readonly target?: Vector3Tuple;
+    readonly angle?: number;
+    readonly penumbra?: number;
+    readonly distance?: number;
+    readonly decay?: number;
+    readonly castShadow?: boolean;
+}
+export interface Lighting3DConfig {
+    readonly ambient?: AmbientLightConfig;
+    readonly directional?: readonly DirectionalLightConfig[];
+    readonly point?: readonly PointLightConfig[];
+    readonly spot?: readonly SpotLightConfig[];
+}
+export type FogType = "linear" | "exponential";
+export interface FogConfig {
+    readonly type?: FogType;
+    readonly color?: string;
+    readonly near?: number;
+    readonly far?: number;
+    readonly density?: number;
+}
+export interface Environment3DConfig {
+    readonly background?: string;
+    readonly transparent?: boolean;
+    readonly fog?: FogConfig;
+    readonly ground?: {
+        readonly enabled?: boolean;
+        readonly size?: number;
+        readonly color?: string;
+        readonly receiveShadow?: boolean;
+    };
+}
+export type Object3DType = "mesh" | "group" | "light" | "camera" | "custom";
+export interface Object3DConfig {
+    readonly id: string;
+    readonly name?: string;
+    readonly type: Object3DType;
+    readonly position?: Vector3Tuple;
+    readonly rotation?: EulerTuple;
+    readonly scale?: Vector3Tuple;
+    readonly visible?: boolean;
+    readonly castShadow?: boolean;
+    readonly receiveShadow?: boolean;
+    readonly userData?: Record<string, unknown>;
+}
+export type Renderer3DBackend = "three" | "webgl" | "null";
+export type PowerPreference = "default" | "high-performance" | "low-power";
+export interface Renderer3DConfig {
+    readonly backend?: Renderer3DBackend;
+    readonly powerPreference?: PowerPreference;
+    readonly antialias?: boolean;
+    readonly alpha?: boolean;
+    readonly dpr?: number | "auto";
+    readonly shadowMap?: boolean;
+    readonly preserveDrawingBuffer?: boolean;
+}
+export interface Scene3DCapabilities {
+    readonly webgl: boolean;
+    readonly webgl2: boolean;
+    readonly webgpu: boolean;
+    readonly maxTextureSize: number;
+    readonly maxAnisotropy: number;
+    readonly floatTextures: boolean;
+    readonly isSupported: boolean;
+    readonly reducedMotion: boolean;
+    readonly devicePixelRatio: number;
+}
+export interface Scene3DDefinition {
+    readonly id: string;
+    readonly name?: string;
+    readonly version?: string;
+    readonly camera?: Camera3DConfig;
+    readonly lighting?: Lighting3DConfig;
+    readonly environment?: Environment3DConfig;
+    readonly objects?: readonly Object3DConfig[];
+    readonly renderer?: Renderer3DConfig;
+    readonly autoStart?: boolean;
+    readonly respectReducedMotion?: boolean;
+}
+export interface ScenePerformanceStats {
+    readonly fps: number;
+    readonly avgFrameTimeMs: number;
+    readonly totalObjects: number;
+    readonly isRunning: boolean;
+    readonly backend: Renderer3DBackend;
+}
+export interface Renderer3DAdapter {
+    readonly id: string;
+    readonly name: string;
+    readonly backend: Renderer3DBackend;
+    isSupported(): boolean;
+    init(canvas: HTMLCanvasElement, config?: Renderer3DConfig): Promise<void> | void;
+    render(scene: Scene3DInstance, deltaTimeMs: number): void;
+    setSize(width: number, height: number, dpr?: number): void;
+    dispose(): void;
+    getDomElement(): HTMLCanvasElement | null;
+    onContextLost?(callback: () => void): () => void;
+    onContextRestored?(callback: () => void): () => void;
+}
+export interface CreateScene3DOptions {
+    readonly autoStart?: boolean;
+    readonly adapter?: Renderer3DAdapter;
+    readonly dpr?: number | "auto";
+    readonly respectReducedMotion?: boolean;
+}
+export interface Scene3DInstance {
+    readonly id: string;
+    readonly definition: Scene3DDefinition;
+    readonly adapter: Renderer3DAdapter | null;
+    readonly capabilities: Scene3DCapabilities;
+    readonly isRunning: boolean;
+    readonly isAttached: boolean;
+    readonly camera: Camera3DConfig;
+    readonly lighting: Lighting3DConfig;
+    readonly environment: Environment3DConfig;
+    attach(canvas: HTMLCanvasElement): Promise<void> | void;
+    detach(): void;
+    start(): void;
+    stop(): void;
+    requestFrame(): void;
+    addObject(object: Object3DConfig): void;
+    removeObject(objectId: string): boolean;
+    getObject(objectId: string): Object3DConfig | undefined;
+    listObjects(): readonly Object3DConfig[];
+    updateCamera(config: Partial<Camera3DConfig>): void;
+    updateLighting(config: Partial<Lighting3DConfig>): void;
+    updateEnvironment(config: Partial<Environment3DConfig>): void;
+    resize(width?: number, height?: number, dpr?: number): void;
+    getPerformanceStats(): ScenePerformanceStats;
+    onContextLost(cb: () => void): () => void;
+    onContextRestored(cb: () => void): () => void;
+    destroy(): void;
+}

package/dist/3d/world/hydrology.d.ts

@@ -0,0 +1,12 @@
+/**
+ * AF Motion — 3D World Hydrology & Procedural Water Engine
+ *
+ * Simulates oceans, inland lakes, river paths flowing along steepest terrain gradients,
+ * shoreline water planes, and buoyancy sampling hooks.
+ */
+import type { HeightmapData } from "../terrain/types.js";
+import type { WorldHydrologyConfig, WorldHydrology } from "./types.js";
+/**
+ * Creates and simulates procedural hydrology for a world heightmap.
+ */
+export declare function createWorldHydrology(heightmap: HeightmapData, config?: WorldHydrologyConfig, seed?: number | string): WorldHydrology;

package/dist/3d/world/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * AF Motion — 3D Procedural World & Environment Generator
+ *
+ * Unified world orchestration layer combining procedural terrain, hydrology,
+ * clustered population, environmental simulation, diurnal lighting/atmosphere,
+ * chunk streaming, and physics into cohesive procedural 3D environments.
+ */
+export * from "./types.js";
+export * from "./hydrology.js";
+export * from "./population.js";
+export * from "./lighting.js";
+export * from "./streaming.js";
+export * from "./presets.js";
+export * from "./pipeline.js";
+export * from "./world.js";

package/dist/3d/world/lighting.d.ts

@@ -0,0 +1,16 @@
+/**
+ * AF Motion — 3D World Lighting & Atmospheric Day/Night Engine
+ *
+ * Diurnal solar tracking, directional sunlight/moonlight vector calculations,
+ * weather-reactive ambient radiance, and distance-based atmospheric fog transitions.
+ */
+import type { WeatherState } from "../../graphics/environment/types.js";
+import type { DayNightState, WorldLightingConfig, WorldLighting } from "./types.js";
+/**
+ * Creates and initializes the world lighting and atmospheric orchestration engine.
+ */
+export declare function createWorldLighting(config?: WorldLightingConfig, initialWeather?: WeatherState): WorldLighting;
+/**
+ * Computes solar celestial mechanics and diurnal illumination spectrums.
+ */
+export declare function computeDayNightState(timeHours: number, latitudeRad: number, weather?: WeatherState): DayNightState;

package/dist/3d/world/pipeline.d.ts

@@ -0,0 +1,20 @@
+/**
+ * AF Motion — 3D World 12-Stage Procedural Generation Pipeline
+ *
+ * Deterministic multi-stage compilation orchestrating terrain synthesis, erosion,
+ * biomes, materials, hydrology, population, environment, lighting, and physics
+ * with progress reporting, AbortSignal cancellation, and granular stage timing.
+ */
+import type { World3DConfig, WorldGenerationStage, PipelineProgressEvent, WorldBenchmarkResult, World3D } from "./types.js";
+export declare const PIPELINE_STAGES: WorldGenerationStage[];
+export interface RunPipelineOptions {
+    signal?: AbortSignal;
+    onProgress?: (event: PipelineProgressEvent) => void;
+}
+/**
+ * Executes the full 12-stage world generation pipeline.
+ */
+export declare function executeWorldPipeline(config: World3DConfig, options?: RunPipelineOptions): {
+    world: World3D;
+    benchmark: WorldBenchmarkResult;
+};

package/dist/3d/world/population.d.ts

@@ -0,0 +1,12 @@
+/**
+ * AF Motion — 3D World Population & Vegetation Clusters
+ *
+ * Coordinates clustered forest groves, biome-specific flora, rocks, and environmental props
+ * with water exclusion and packed 4x4 matrix instancing buffers for GPU batching.
+ */
+import type { HeightmapData, BiomeWeightMap } from "../terrain/types.js";
+import type { WorldHydrology, WorldPopulationConfig, WorldPopulation } from "./types.js";
+/**
+ * Generates world population including clustered forests and packed GPU instanced transform buffers.
+ */
+export declare function createWorldPopulation(heightmap: HeightmapData, biomes: BiomeWeightMap, hydrology: WorldHydrology, config?: WorldPopulationConfig, seed?: number | string): WorldPopulation;

package/dist/3d/world/presets.d.ts

@@ -0,0 +1,11 @@
+/**
+ * AF Motion — 3D World Presets
+ *
+ * Pre-engineered cohesive environmental biomes, atmospheric lighting,
+ * and hydrology presets composing existing terrain and simulation engines.
+ */
+import type { WorldPreset, World3DConfig } from "./types.js";
+/**
+ * Returns complete configuration for a named world preset.
+ */
+export declare function createWorldPreset(preset: WorldPreset, overrides?: World3DConfig): World3DConfig;

package/dist/3d/world/streaming.d.ts

@@ -0,0 +1,13 @@
+/**
+ * AF Motion — 3D World Chunking & Streaming Engine
+ *
+ * Coordinates continuous spatial chunk streaming around dynamic viewer positions,
+ * lazy chunk generation, distance-based LOD transitions, and LRU cache recycling.
+ */
+import type { Terrain3D } from "../terrain/types.js";
+import type { WorldPopulation } from "./types.js";
+import type { WorldStreamingConfig, WorldStreamingManager } from "./types.js";
+/**
+ * Creates and manages procedural world spatial streaming and chunk caching.
+ */
+export declare function createWorldStreamingManager(terrain: Terrain3D, population: WorldPopulation, config?: WorldStreamingConfig): WorldStreamingManager;