yog_worldgen/

lib.rs

//! yog-worldgen — terrain as data: a dimension's ground described in its
//! `.ydef` (`terrain`), generated by the runtime chunk by chunk and drawn
//! by Yog-IDLE's designer from the same code.
//!
//! ```json5
//! terrain: {
//!   seed: 1234,
//!   base_height: 64,
//!   noise: [ { scale: 160, amplitude: 28, octaves: 4 }, { scale: 24, amplitude: 3 } ],
//!   fill: "@block:minecraft:stone",
//!   layers: [ { block: "@block:minecraft:grass_block", depth: 1 }, { block: "@block:minecraft:dirt", depth: 3 } ],
//!   bedrock: "@block:minecraft:bedrock",
//!   fluid: { block: "@block:minecraft:water", level: 62 },
//!   caves: { scale: 24, threshold: 0.55 },
//!   ores: [ { block: "@block:minecraft:iron_ore", size: 8, per_chunk: 12, min: 0, max: 64 } ],
//! }
//! ```
//!
//! The height of the ground is `base_height` plus each noise layer
//! (`amplitude` blocks up or down, features `scale` blocks wide); the
//! column is `layers` from the top, then `fill`; above the ground up to
//! the fluid's level, the fluid. This is the low-level generator's
//! declarative side: a mod still writes any generator of its own in code
//! (`Registry::register_chunk_generator`).

pub mod noise;
pub mod preview;

use yog_data::Schema;
use yog_data::kinds::Block;
use yog_data::with::{Opt, RefTo};

use noise::{Perlin, Rng, mix};

/// A layer of height: `amplitude` blocks up or down, features `scale` blocks wide.
#[derive(Schema, Debug, Clone, PartialEq)]
pub struct NoiseLayer {
    #[data(range = "1..=100000")]
    pub scale: f64,
    pub amplitude: f64,
    /// Finer layers on top of it, each half as strong (`persistence`).
    #[data(default = "one", range = "1..=16")]
    pub octaves: u32,
    #[data(default = "half", range = "0..=1")]
    pub persistence: f64,
}

/// A layer of the ground's top: `depth` blocks of `block`.
#[derive(Schema, Debug, Clone, PartialEq)]
pub struct SurfaceLayer {
    #[data(with = "RefTo<Block>")]
    pub block: String,
    #[data(range = "1..=256")]
    pub depth: u32,
}

/// What fills the low ground up to `level` (a sea, lava lakes).
#[derive(Schema, Debug, Clone, PartialEq)]
pub struct Fluid {
    #[data(with = "RefTo<Block>")]
    pub block: String,
    pub level: i32,
}

/// Caves: where 3D noise of features `scale` blocks wide is above
/// `threshold` (0–1: the higher, the fewer), under the ground.
#[derive(Schema, Debug, Clone, PartialEq)]
pub struct Caves {
    #[data(range = "1..=10000")]
    pub scale: f64,
    #[data(range = "0..=1")]
    pub threshold: f64,
}

/// Veins of `block` in the ground (in `replaces`, the fill by default).
#[derive(Schema, Debug, Clone, PartialEq)]
pub struct TerrainOre {
    #[data(with = "RefTo<Block>")]
    pub block: String,
    #[data(with = "Opt<RefTo<Block>>")]
    pub replaces: Option<String>,
    #[data(range = "1..=64")]
    pub size: u32,
    #[data(range = "0..=256")]
    pub per_chunk: u32,
    pub min: i32,
    pub max: i32,
}

/// A dimension's ground.
#[derive(Schema, Debug, Clone, PartialEq)]
pub struct Terrain {
    /// The same seed, the same ground.
    #[data(default)]
    pub seed: u64,
    #[data(default = "sea_level")]
    pub base_height: i32,
    #[data(default)]
    pub noise: Vec<NoiseLayer>,
    /// What the ground is made of.
    #[data(with = "RefTo<Block>")]
    pub fill: String,
    /// The ground's top, from the surface down.
    #[data(default)]
    pub layers: Vec<SurfaceLayer>,
    /// The world's floor (one block at the bottom).
    #[data(with = "Opt<RefTo<Block>>")]
    pub bedrock: Option<String>,
    pub fluid: Option<Fluid>,
    pub caves: Option<Caves>,
    #[data(default)]
    pub ores: Vec<TerrainOre>,
}

fn one() -> u32 {
    1
}

fn half() -> f64 {
    0.5
}

fn sea_level() -> i32 {
    64
}

/// A [`Terrain`] ready to generate: its noise built from its seed.
#[derive(Debug, Clone)]
pub struct Generator {
    pub terrain: Terrain,
    height: Vec<Perlin>,
    caves: Perlin,
}

impl Generator {
    pub fn new(terrain: Terrain) -> Generator {
        let height = (0..terrain.noise.len())
            .map(|i| Perlin::new(mix(terrain.seed, i as u64 + 1)))
            .collect();
        let caves = Perlin::new(mix(terrain.seed, 0xCA7E));
        Generator {
            terrain,
            height,
            caves,
        }
    }

    /// The height of the ground's top block at `x`, `z`.
    pub fn surface(&self, x: i32, z: i32) -> i32 {
        let t = &self.terrain;
        let mut h = t.base_height as f64;
        for (layer, noise) in t.noise.iter().zip(&self.height) {
            h += layer.amplitude
                * noise.fbm2(
                    x as f64 / layer.scale,
                    z as f64 / layer.scale,
                    layer.octaves,
                    layer.persistence,
                );
        }
        h.round() as i32
    }

    /// The block at `x`, `y`, `z` (`None`: air) with the ground at `surface`
    /// and the world's bottom at `min_y` — before ores.
    pub fn block_at(&self, x: i32, y: i32, z: i32, surface: i32, min_y: i32) -> Option<&str> {
        let t = &self.terrain;
        if y == min_y
            && let Some(b) = &t.bedrock
        {
            return Some(b);
        }
        if y > surface {
            return t
                .fluid
                .as_ref()
                .filter(|f| y <= f.level)
                .map(|f| f.block.as_str());
        }
        if let Some(c) = &t.caves
            && y > min_y
            && y < surface
        {
            let n = self
                .caves
                .get3(x as f64 / c.scale, y as f64 / c.scale, z as f64 / c.scale);
            // Perlin is about -1..1; the threshold is over 0..1.
            if (n + 1.0) / 2.0 > c.threshold {
                return None;
            }
        }
        let depth = (surface - y) as u32;
        let mut top = 0;
        for l in &t.layers {
            top += l.depth;
            if depth < top {
                return Some(&l.block);
            }
        }
        Some(&t.fill)
    }

    /// Generates chunk `cx`, `cz` of a world `height` blocks from `min_y`:
    /// `set(x, y, z, block)` for every block that isn't air (`x`, `z` 0..16).
    pub fn generate(
        &self,
        cx: i32,
        cz: i32,
        min_y: i32,
        height: i32,
        mut set: impl FnMut(i32, i32, i32, &str),
    ) {
        let top = min_y + height - 1;
        let mut surfaces = [[0i32; 16]; 16];
        for lx in 0..16 {
            for lz in 0..16 {
                let (x, z) = (cx * 16 + lx, cz * 16 + lz);
                let s = self.surface(x, z).clamp(min_y, top);
                surfaces[lx as usize][lz as usize] = s;
                let up = self
                    .terrain
                    .fluid
                    .as_ref()
                    .map_or(s, |f| f.level.max(s))
                    .min(top);
                for y in min_y..=up {
                    if let Some(b) = self.block_at(x, y, z, s, min_y) {
                        set(lx, y, lz, b);
                    }
                }
            }
        }
        // Ores: veins started at random in the chunk, kept inside it.
        for (i, ore) in self.terrain.ores.iter().enumerate() {
            let mut rng = Rng::new(mix(
                mix(self.terrain.seed, i as u64 + 100),
                ((cx as u64) << 32) ^ (cz as u32 as u64),
            ));
            let replaces = ore.replaces.as_deref().unwrap_or(&self.terrain.fill);
            for _ in 0..ore.per_chunk {
                let (lo, hi) = (ore.min.max(min_y), ore.max.min(top));
                if hi < lo {
                    break;
                }
                let (mut lx, mut y, mut lz) = (
                    rng.below(16) as i32,
                    lo + rng.below((hi - lo + 1) as u32) as i32,
                    rng.below(16) as i32,
                );
                for _ in 0..ore.size {
                    if (0..16).contains(&lx) && (0..16).contains(&lz) && y >= min_y && y <= top {
                        let (x, z) = (cx * 16 + lx, cz * 16 + lz);
                        let s = surfaces[lx as usize][lz as usize];
                        if self.block_at(x, y, z, s, min_y) == Some(replaces) {
                            set(lx, y, lz, &ore.block);
                        }
                    }
                    match rng.below(6) {
                        0 => lx += 1,
                        1 => lx -= 1,
                        2 => y += 1,
                        3 => y -= 1,
                        4 => lz += 1,
                        _ => lz -= 1,
                    }
                }
            }
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    pub(crate) fn hills() -> Terrain {
        let text = r#"{ seed: 7, base_height: 64,
            noise: [ { scale: 64, amplitude: 20, octaves: 3 } ],
            fill: "@block:minecraft:stone",
            layers: [ { block: "@block:minecraft:grass_block", depth: 1 }, { block: "@block:minecraft:dirt", depth: 3 } ],
            bedrock: "@block:minecraft:bedrock",
            fluid: { block: "@block:minecraft:water", level: 62 },
            ores: [ { block: "@block:minecraft:iron_ore", size: 8, per_chunk: 20, min: 0, max: 60 } ] }"#;
        yog_data::from_text::<Terrain>(text).unwrap().value
    }

    #[test]
    fn a_column_is_layers_then_fill_with_water_over_low_ground() {
        let g = Generator::new(hills());
        let mut blocks = std::collections::HashMap::new();
        g.generate(0, 0, 0, 128, |x, y, z, b| {
            blocks.insert((x, y, z), b.to_string());
        });
        let s = g.surface(0, 0);
        assert_eq!(
            blocks.get(&(0, 0, 0)).map(String::as_str),
            Some("minecraft:bedrock")
        );
        let top = blocks.get(&(0, s, 0)).map(String::as_str);
        assert!(
            matches!(top, Some("minecraft:grass_block" | "minecraft:iron_ore")),
            "{top:?} at {s}"
        );
        assert!(
            blocks
                .get(&(0, s - 2, 0))
                .is_some_and(|b| b == "minecraft:dirt" || b == "minecraft:iron_ore")
        );
        assert!(
            blocks.values().any(|b| b == "minecraft:iron_ore"),
            "ores in the stone"
        );
        // Somewhere in a 16×16 chunk of hills ±20 around 64 the ground is under 62: water there.
        let low = (0..16)
            .flat_map(|x| (0..16).map(move |z| (x, z)))
            .find(|&(x, z)| g.surface(x, z) < 61);
        if let Some((x, z)) = low {
            assert_eq!(
                blocks.get(&(x, 62, z)).map(String::as_str),
                Some("minecraft:water")
            );
        }
        // The same terrain, the same chunk.
        let mut again = std::collections::HashMap::new();
        Generator::new(hills()).generate(0, 0, 0, 128, |x, y, z, b| {
            again.insert((x, y, z), b.to_string());
        });
        assert_eq!(again, blocks);
    }
}