symbios_ground/lib.rs
1//! # symbios-ground
2//!
3//! An algorithmic terrain engine for procedural heightmap generation, erosion
4//! simulation, and texture-weight (splat) mapping.
5//!
6//! ## Core types
7//!
8//! | Type | Description |
9//! |------|-------------|
10//! | [`HeightMap`] | 2-D grid of `f32` heights with world-space sampling helpers |
11//! | [`Lake`] | Pooled water body detected during hydraulic erosion |
12//! | [`TerrainGenerator`] | Trait implemented by all generators |
13//! | [`SplatMapper`] / [`WeightMap`] | 4-channel RGBA texture-weight map from height + slope |
14//!
15//! ## Generators
16//!
17//! | Type | Algorithm |
18//! |------|-----------|
19//! | [`DiamondSquare`] | Classic fractal Diamond-Square; preserves caller dimensions via bilinear downsample |
20//! | [`FbmNoise`] | Fractional Brownian Motion (multi-octave value noise) |
21//! | [`VoronoiTerracing`] | Voronoi-based stepped plateaus |
22//!
23//! ## Erosion
24//!
25//! | Type | Description |
26//! |------|-------------|
27//! | [`HydraulicErosion`] | Droplet-based particle erosion (carves valleys, pools lakes, splays river deltas) |
28//! | [`ThermalErosion`] | Talus/slope-smoothing erosion (with optional underwater rules) |
29//!
30//! ## Streaming / LOD
31//!
32//! | Type | Description |
33//! |------|-------------|
34//! | [`TiledHeightMap`] | Sparse, infinite-world heightmap generated tile-by-tile on demand |
35//! | [`HeightMapTile`] | One generated tile owned by a [`TiledHeightMap`] |
36//! | [`derive_tile_seed`] | Mixes a base seed with tile coordinates into a per-tile seed |
37//!
38//! ## World-space splat queries
39//!
40//! | Function | Description |
41//! |----------|-------------|
42//! | [`SplatMapper::sample_weights_at`] / [`sample_splat_weights_at`] | Normalised `[f32; 4]` splat weights at a world position |
43//! | [`SplatMapper::sample_biome_at`] / [`sample_biome_at`] | Dominant RGBA channel index (`0..=3`) at a world position |
44//!
45//! ## Quick start
46//!
47//! ```rust
48//! use symbios_ground::{DiamondSquare, HeightMap, HydraulicErosion,
49//! SplatMapper, TerrainGenerator, ThermalErosion};
50//!
51//! // 1. Create a 129×129 heightmap with 1 world-unit per cell.
52//! let mut heightmap = HeightMap::new(129, 129, 1.0);
53//!
54//! // 2. Generate fractal terrain.
55//! DiamondSquare::new(42, 0.6).generate(&mut heightmap);
56//!
57//! // 3. Smooth with thermal erosion, then carve with hydraulic erosion.
58//! ThermalErosion::new().erode(&mut heightmap);
59//! HydraulicErosion::new(42).erode(&mut heightmap);
60//!
61//! // 4. Build a 4-channel texture weight map (grass / dirt / rock / snow).
62//! let weight_map = SplatMapper::default().generate(&heightmap);
63//!
64//! // 5. Query world-space height and surface normal at any position.
65//! let height = heightmap.get_height_at(64.5, 64.5);
66//! let normal = heightmap.get_normal_at(64.5, 64.5);
67//! # let _ = (height, normal, weight_map);
68//! ```
69
70pub mod erosion;
71pub mod generator;
72pub mod generators;
73pub mod heightmap;
74pub mod splat;
75pub mod tile;
76
77pub use erosion::{HydraulicErosion, ThermalErosion};
78pub use generator::TerrainGenerator;
79pub use generators::{DiamondSquare, FbmNoise, VoronoiTerracing};
80pub use heightmap::{HeightMap, Lake};
81pub use splat::{SplatMapper, SplatRule, WeightMap, sample_biome_at, sample_splat_weights_at};
82pub use tile::{HeightMapTile, TiledHeightMap, derive_tile_seed};