steel_core/worldgen/generator/

vanilla.rs

use std::path::Path;
use std::{cell::Cell, iter, marker::PhantomData, sync::Arc};

use glam::{DVec3, IVec3};
use rustc_hash::FxHashSet;
use smallvec::SmallVec;
use steel_math::lerp2;
use steel_registry::biome::BiomeRef;
use steel_registry::blocks::block_state_ext::BlockStateExt;
use steel_registry::carver::ConfiguredCarverKind;
use steel_registry::{REGISTRY, RegistryEntry, RegistryExt, vanilla_biomes};
use steel_utils::random::{
    Random, RandomSource, RandomSplitter, legacy_random::LegacyRandom, xoroshiro::Xoroshiro,
};
use steel_utils::{BlockPos, BlockStateId, ChunkPos, DowncastType, DowncastTypeKey, Identifier};
use steel_worldgen::density::{ColumnCache, DimensionNoises, NoiseSettings};
use steel_worldgen::density_functions::{
    end::EndNoises, nether::NetherNoises, overworld::OverworldNoises,
};
use steel_worldgen::noise_parameters::get_noise_parameters;
use steel_worldgen::surface::{
    SurfaceBiomeProvider, SurfaceConditionNoiseCache, SurfaceRuleContext,
};

use crate::chunk::Chunk;
use crate::chunk::heightmap::{Heightmap, HeightmapType};
use crate::worldgen::carver::{
    CarveRun, CarverBlockIds, CarvingContext, CarvingMask, PreliminarySurfaceCorners, SourceChunk,
};
use crate::worldgen::feature::FeatureDecorationRunner;
use crate::worldgen::generator::surface_biomes::{
    FuzzedBiomeColumn, SurfaceBiomeClasses, SurfaceQuartBiomes,
};
use crate::worldgen::generator::{
    ChunkGenerator, GenerationChunk, TerrainPhase, worldgen_region_random_from_splitter,
};
use crate::worldgen::region::WorldGenRegion;
use crate::worldgen::structure::{StructureGenerator, create_structures};
use crate::worldgen::surface::SurfaceSystem;
use steel_worldgen::biomes::BiomeSourceKind;
use steel_worldgen::biomes::obfuscate_biome_seed;
use steel_worldgen::noise::Beardifier;
use steel_worldgen::noise::NoiseChunk;
use steel_worldgen::noise::OreVeinifier;
use steel_worldgen::noise::{Aquifer, AquiferResult, LazyAquifer, preliminary_surface_level};
use steel_worldgen::noise::{CornerColumnStore, PreliminarySurfaceStore};
use steel_worldgen::structure::GenerationContext;
use steel_worldgen::surface_partial::PartialSurfaceOutcome;

const CARVER_SOURCE_CHUNK_COUNT: usize = 17 * 17;

/// Associates a dimension's statically typed Aquifer with its transient erased state.
///
/// Custom dimension noise implementations own their state type and downcast key. Steel
/// only erases the value between stages; every hot-path Aquifer call remains monomorphized.
pub trait VanillaPostNoiseStateType: DimensionNoises + 'static {
    /// Concrete state stored transiently on the generating chunk.
    type State: DowncastType + Send + Sync;

    /// Wraps the Noise-stage state for the remaining Terrain work.
    fn wrap_post_noise_state(
        aquifer: Aquifer<Self>,
        material_ore_vein_values: Arc<[f32]>,
    ) -> Self::State;

    /// Recovers the concrete Aquifer at a later generation stage.
    fn post_noise_aquifer(state: &mut Self::State) -> &mut Aquifer<Self>;

    /// dense ore values from `Settings::MIN_Y`, up to `material_ore_vein_value_height`
    fn material_ore_vein_values(state: &mut Self::State) -> Arc<[f32]>;
}

/// Steel-owned post-Noise state for the built-in dimensions.
#[doc(hidden)]
pub struct SteelPostNoiseState<N: DimensionNoises> {
    aquifer: Aquifer<N>,
    material_ore_vein_values: Arc<[f32]>,
}

// SAFETY: Each key uniquely identifies this exact Steel-owned specialization.
unsafe impl DowncastType for SteelPostNoiseState<OverworldNoises> {
    const TYPE_KEY: DowncastTypeKey =
        DowncastTypeKey::new("steel:worldgen_state/post_noise_overworld");
}

// SAFETY: Each key uniquely identifies this exact Steel-owned specialization.
unsafe impl DowncastType for SteelPostNoiseState<NetherNoises> {
    const TYPE_KEY: DowncastTypeKey =
        DowncastTypeKey::new("steel:worldgen_state/post_noise_nether");
}

// SAFETY: Each key uniquely identifies this exact Steel-owned specialization.
unsafe impl DowncastType for SteelPostNoiseState<EndNoises> {
    const TYPE_KEY: DowncastTypeKey = DowncastTypeKey::new("steel:worldgen_state/post_noise_end");
}

macro_rules! impl_post_noise_state_type {
    ($noises:ty) => {
        impl VanillaPostNoiseStateType for $noises {
            type State = SteelPostNoiseState<Self>;

            fn wrap_post_noise_state(
                aquifer: Aquifer<Self>,
                material_ore_vein_values: Arc<[f32]>,
            ) -> Self::State {
                SteelPostNoiseState {
                    aquifer,
                    material_ore_vein_values,
                }
            }

            fn post_noise_aquifer(state: &mut Self::State) -> &mut Aquifer<Self> {
                &mut state.aquifer
            }

            fn material_ore_vein_values(state: &mut Self::State) -> Arc<[f32]> {
                Arc::clone(&state.material_ore_vein_values)
            }
        }
    };
}

impl_post_noise_state_type!(OverworldNoises);
impl_post_noise_state_type!(NetherNoises);
impl_post_noise_state_type!(EndNoises);

/// A chunk generator for vanilla (normal) world generation.
///
/// Matches vanilla's `NoiseBasedChunkGenerator`. The biome source is pluggable
/// per-dimension — overworld, nether, and end each provide a different
/// [`BiomeSourceKind`] variant.
///
/// Generic over `N: DimensionNoises` to support different dimensions with
/// their own transpiled density functions and noise settings.
pub struct VanillaGenerator<N: DimensionNoises> {
    /// Biome source for this dimension. Determines biomes at each quart position.
    biome_source: BiomeSourceKind,
    /// Representative biome when every possible biome has the same carver list.
    /// Mixed lists retain vanilla's per-source biome lookup.
    uniform_carver_biome: Option<BiomeRef>,
    /// Noise generators for this dimension's density functions.
    /// Boxed because noise structs can be large.
    noises: Box<N>,
    /// Seed positional splitter for per-chunk construction of aquifers.
    splitter: RandomSplitter,
    /// Preliminary surface levels shared by every aquifer this generator builds.
    preliminary_surface: Arc<PreliminarySurfaceStore>,
    /// boundary corner columns shared with neighbors
    corner_columns: CornerColumnStore,
    /// Ore vein generator for replacing stone with ore blocks.
    ore_veinifier: Option<OreVeinifier>,
    /// Surface system for biome-specific block replacement.
    surface_system: SurfaceSystem,
    /// Which vanilla surface extension biomes this source can produce.
    surface_extension_biomes: SurfaceExtensionBiomes,
    /// Biome classes the surface rule cannot tell apart.
    surface_biome_classes: Option<SurfaceBiomeClasses>,
    /// Block state ID for the default block, cached at construction time.
    default_block_id: BlockStateId,
    /// Obfuscated seed for `BiomeManager` biome zoom fuzzing.
    biome_zoom_seed: i64,
    /// World seed as i64 (matching Java's long), used for structures and carver seeding.
    seed: i64,
    /// Shared structure placement/selection engine.
    structure_generator: StructureGenerator,
    /// Cached placed-feature order for biome decoration.
    feature_runner: FeatureDecorationRunner,
    _phantom: PhantomData<N>,
}

#[derive(Clone, Copy)]
struct SurfaceExtensionBiomes {
    eroded_badlands: bool,
    frozen_ocean: bool,
}

impl SurfaceExtensionBiomes {
    fn from_possible(possible_biomes: &FxHashSet<Identifier>) -> Self {
        Self {
            eroded_badlands: possible_biomes.contains(&vanilla_biomes::ERODED_BADLANDS.key),
            frozen_ocean: possible_biomes.contains(&vanilla_biomes::FROZEN_OCEAN.key)
                || possible_biomes.contains(&vanilla_biomes::DEEP_FROZEN_OCEAN.key),
        }
    }

    const fn needs_surface_biome(self) -> bool {
        self.eroded_badlands || self.frozen_ocean
    }
}

impl<N: DimensionNoises> VanillaGenerator<N> {
    /// Creates a new `VanillaGenerator` with the given biome source and seed.
    ///
    /// # Panics
    /// Panics if SHA-256 hash output is shorter than 8 bytes (cannot happen).
    #[must_use]
    pub fn new(
        world_path: Option<&Path>,
        biome_source: BiomeSourceKind,
        seed: u64,
        thread_pool: &rayon::ThreadPool,
    ) -> Self {
        // Nether uses Java's LCG; overworld/end use Xoroshiro.
        let splitter = if N::Settings::LEGACY_RANDOM_SOURCE {
            LegacyRandom::from_seed(seed).next_positional()
        } else {
            Xoroshiro::from_seed(seed).next_positional()
        };
        let noise_params = get_noise_parameters();
        let noises = N::create(seed, &splitter, &noise_params);

        let ore_veinifier = if N::Settings::MATERIAL_ORE_VEINS_ENABLED {
            Some(OreVeinifier::new(&splitter))
        } else {
            None
        };

        let default_block_id = N::Settings::default_block_id();
        let surface_system = SurfaceSystem::new(
            &splitter,
            &noise_params,
            N::surface_noise_ids(),
            N::surface_gradient_ids(),
            default_block_id,
            N::Settings::SEA_LEVEL,
        );

        let biome_zoom_seed = obfuscate_biome_seed(seed as i64);

        // Force the lazy parameter-list R-tree inside the configured generation
        // pool so its parallel construction does not initialize Rayon's global pool.
        let possible_biome_refs = thread_pool.install(|| biome_source.possible_biome_refs());
        let possible_biomes = biome_source.possible_biomes();
        let surface_extension_biomes = SurfaceExtensionBiomes::from_possible(&possible_biomes);
        let structure_generator =
            StructureGenerator::vanilla(seed as i64, world_path, &biome_source, thread_pool);
        let feature_runner = FeatureDecorationRunner::new(&possible_biome_refs, &REGISTRY);
        let uniform_carver_biome = Self::uniform_carver_biome(&possible_biomes);

        Self {
            biome_source,
            uniform_carver_biome,
            noises: Box::new(noises),
            splitter,
            preliminary_surface: Arc::default(),
            corner_columns: CornerColumnStore::default(),
            ore_veinifier,
            surface_system,
            surface_extension_biomes,
            surface_biome_classes: SurfaceBiomeClasses::new::<N>(),
            default_block_id,
            biome_zoom_seed,
            seed: seed as i64,
            structure_generator,
            feature_runner,
            _phantom: PhantomData,
        }
    }

    fn uniform_carver_biome(possible_biomes: &FxHashSet<Identifier>) -> Option<BiomeRef> {
        let mut possible_biomes = possible_biomes.iter();
        let first_key = possible_biomes.next()?;
        let first = REGISTRY.biomes.by_key(first_key)?;

        possible_biomes
            .all(|key| {
                REGISTRY
                    .biomes
                    .by_key(key)
                    .is_some_and(|biome| biome.carvers == first.carvers)
            })
            .then_some(first)
    }
}

impl<N: VanillaPostNoiseStateType> VanillaGenerator<N> {
    fn preliminary_surface_corners(
        &self,
        chunk: GenerationChunk<'_, TerrainPhase>,
        chunk_min_x: i32,
        chunk_min_z: i32,
    ) -> PreliminarySurfaceCorners {
        let noises = &*self.noises;
        if let Some(corners) = chunk.with_post_noise_state_mut::<N::State, _>(|state| {
            let aquifer = N::post_noise_aquifer(state);
            PreliminarySurfaceCorners {
                nw: aquifer.preliminary_surface_level(noises, chunk_min_x, chunk_min_z),
                ne: aquifer.preliminary_surface_level(noises, chunk_min_x + 16, chunk_min_z),
                sw: aquifer.preliminary_surface_level(noises, chunk_min_x, chunk_min_z + 16),
                se: aquifer.preliminary_surface_level(noises, chunk_min_x + 16, chunk_min_z + 16),
            }
        }) {
            return corners;
        }

        let mut cache = N::ColumnCache::default();
        PreliminarySurfaceCorners {
            nw: preliminary_surface_level::<N>(noises, &mut cache, chunk_min_x, chunk_min_z),
            ne: preliminary_surface_level::<N>(noises, &mut cache, chunk_min_x + 16, chunk_min_z),
            sw: preliminary_surface_level::<N>(noises, &mut cache, chunk_min_x, chunk_min_z + 16),
            se: preliminary_surface_level::<N>(
                noises,
                &mut cache,
                chunk_min_x + 16,
                chunk_min_z + 16,
            ),
        }
    }
}

impl<N: VanillaPostNoiseStateType> ChunkGenerator for VanillaGenerator<N> {
    fn min_y(&self) -> i32 {
        N::Settings::MIN_Y
    }

    fn gen_depth(&self) -> i32 {
        N::Settings::HEIGHT
    }

    fn noise_biome(&self, quart_x: i32, quart_y: i32, quart_z: i32) -> BiomeRef {
        self.biome_source
            .chunk_sampler()
            .sample(quart_x, quart_y, quart_z)
    }

    fn initial_spawn_search_origin(&self) -> steel_utils::BlockPos {
        self.biome_source.initial_spawn_search_origin()
    }

    fn structure_generator(&self) -> Option<&StructureGenerator> {
        Some(&self.structure_generator)
    }

    fn create_structures(&self, chunk: &Chunk) {
        let pos = chunk.pos();
        let chunk_x = pos.0.x;
        let chunk_z = pos.0.y;

        let mut sampler = self.biome_source.chunk_sampler();
        let chunk_min_x = chunk_x * 16;
        let chunk_min_z = chunk_z * 16;

        let mut height_cache = N::ColumnCache::default();
        let sea_level = N::Settings::SEA_LEVEL;

        // No eager `init_grid`: most chunks' structures (mineshaft, village)
        // use their own caches, and the 1–4 column probes of the remainder
        // hit this cache's lazy single-entry mode cheaply. Eager 5×5 quart
        // init cost ~36µs per chunk with no payoff.
        let mut aquifer = LazyAquifer::new(
            chunk_min_x,
            chunk_min_z,
            &self.splitter,
            &*self.noises,
            &self.preliminary_surface,
        );
        let mut surface_y_cache: Option<i32> = None;
        let mut height_cache_grid_ready = false;
        let mut ctx = GenerationContext::<'_, '_, N>::new(
            self.seed,
            chunk_x,
            chunk_z,
            sea_level,
            &self.noises,
            &self.splitter,
            &self.preliminary_surface,
            self.structure_generator.template_pools(),
            self.structure_generator.templates(),
            &mut sampler,
            &mut height_cache,
            &mut aquifer,
            &mut surface_y_cache,
            &mut height_cache_grid_ready,
        );

        create_structures(&self.structure_generator, chunk, &mut ctx);
    }

    fn create_biomes(&self, chunk: &Chunk) {
        let pos = chunk.pos();
        let min_y = chunk.min_y();
        let section_count = chunk.sections().sections.len();

        let chunk_x = pos.0.x;
        let chunk_z = pos.0.y;

        let mut sampler = self.biome_source.chunk_sampler();
        // Pre-compute the flat (xz-only) climate-noise grid for this chunk so the
        // per-cell sampling below does O(1) column lookups instead of recomputing
        // the flat noise for all 1536 cells (the noise stage's `fill_from_noise`
        // already does this). Values are bit-identical — same functions, same quart
        // coordinates — so biome selection is unchanged.
        sampler.init_grid(chunk_x * 16, chunk_z * 16);

        // Match vanilla's iteration order: Section(Y) → X → Y → Z.
        // This is critical because the R-tree biome cache (persistent warm-start)
        // determines tie-breaking for equal-distance entries, and the cache state
        // depends on the order of biome lookups.
        for section_index in 0..section_count {
            let section_y = (min_y / 16) + section_index as i32;
            let section = &chunk.sections().sections[section_index];
            let mut section_guard = section.write();

            for local_quart_x in 0..4i32 {
                let quart_x = chunk_x * 4 + local_quart_x;

                for local_quart_y in 0..4i32 {
                    let quart_y = section_y * 4 + local_quart_y;

                    for local_quart_z in 0..4i32 {
                        let quart_z = chunk_z * 4 + local_quart_z;

                        let biome = sampler.sample(quart_x, quart_y, quart_z);
                        let biome_id = biome.id() as u16;

                        section_guard.biomes.set(
                            local_quart_x as usize,
                            local_quart_y as usize,
                            local_quart_z as usize,
                            biome_id,
                        );
                    }
                }
            }
        }

        chunk.mark_dirty();
    }

    #[expect(
        clippy::too_many_lines,
        reason = "mirrors Vanilla's terrain fill stage"
    )]
    fn fill_from_noise(
        &self,
        chunk: GenerationChunk<'_, TerrainPhase>,
        beardifier: Option<&Beardifier>,
    ) {
        let pos = chunk.pos();
        let chunk_min_x = pos.0.x * 16;
        let chunk_min_z = pos.0.y * 16;

        let min_y = N::Settings::MIN_Y;
        let height = N::Settings::HEIGHT;

        let mut noise_chunk = NoiseChunk::<N>::new(chunk_min_x, chunk_min_z);
        let noises = &*self.noises;

        let mut column_cache = N::ColumnCache::default();
        column_cache.init_grid(chunk_min_x, chunk_min_z, noises);

        let default_block_id = self.default_block_id;
        let mut aquifer = Aquifer::<N>::new(
            chunk_min_x,
            chunk_min_z,
            min_y,
            height,
            &self.splitter,
            noises,
            &self.preliminary_surface,
            // Aquifer samples at arbitrary (x,z) outside the chunk, so it needs its own cache
            column_cache.clone(),
        );

        // Collect writes per (x,z) column and flush in batch to avoid per-block
        // write lock acquisition on sections.
        let mut pending_writes: Vec<(usize, BlockStateId)> = Vec::new();
        let mut prev_x: usize = usize::MAX;
        let mut prev_z: usize = usize::MAX;

        let mut ocean_floor_complete = false;
        let mut world_surface_complete = false;

        let mut ocean_floor_wg =
            Heightmap::new(HeightmapType::OceanFloorWg, min_y, N::Settings::HEIGHT);
        let mut world_surface_wg =
            Heightmap::new(HeightmapType::WorldSurfaceWg, min_y, N::Settings::HEIGHT);

        let material_value_count = N::material_ore_vein_value_count();
        let material_value_height = if material_value_count == 0 {
            0
        } else {
            N::material_ore_vein_value_height()
        };

        let unsampled_air_min_y = aquifer
            .unsampled_air_min_y()
            .max(min_y + material_value_height as i32);

        // An exact-length iterator allocates the retained Arc slice directly.
        let mut material_ore_vein_values: Arc<[f32]> = iter::repeat_n(
            0.0_f32,
            16 * 16 * material_value_height * material_value_count,
        )
        .collect();

        let material_values = Arc::make_mut(&mut material_ore_vein_values);
        let mut material_cache = N::ColumnCache::default();
        noise_chunk.fill(
            noises,
            &mut column_cache,
            beardifier,
            unsampled_air_min_y,
            &self.corner_columns,
            |local_x, world_y, local_z, density, interpolated, _| {
                // Flush when we move to a new column
                if local_x != prev_x || local_z != prev_z {
                    if !pending_writes.is_empty() {
                        chunk.write_noise_column(prev_x, prev_z, &pending_writes);
                        pending_writes.clear();
                    }
                    prev_x = local_x;
                    prev_z = local_z;
                    ocean_floor_complete = false;
                    world_surface_complete = false;
                }

                let relative_y = (world_y - min_y) as usize;
                let world_x = chunk_min_x + local_x as i32;
                let world_z = chunk_min_z + local_z as i32;

                if material_value_count != 0 && relative_y < material_value_height {
                    let offset =
                        (relative_y * 16 * 16 + local_z * 16 + local_x) * material_value_count;
                    noises.fill_material_ore_vein_values(
                        &mut material_cache,
                        interpolated,
                        world_x,
                        world_y,
                        world_z,
                        &mut material_values[offset..offset + material_value_count],
                    );
                }

                let substance = aquifer.compute_substance(
                    noises,
                    world_x,
                    world_y,
                    world_z,
                    f64::from(density),
                );
                match substance {
                    AquiferResult::Solid => {
                        pending_writes.push((relative_y, default_block_id));
                        ocean_floor_complete = ocean_floor_complete
                            || ocean_floor_wg.update_for_initial_fill(
                                local_x,
                                world_y,
                                local_z,
                                default_block_id,
                            );
                        world_surface_complete = world_surface_complete
                            || world_surface_wg.update_for_initial_fill(
                                local_x,
                                world_y,
                                local_z,
                                default_block_id,
                            );
                    }
                    AquiferResult::Fluid(id) => {
                        pending_writes.push((relative_y, id));
                        ocean_floor_complete = ocean_floor_complete
                            || ocean_floor_wg
                                .update_for_initial_fill(local_x, world_y, local_z, id);
                        world_surface_complete = world_surface_complete
                            || world_surface_wg
                                .update_for_initial_fill(local_x, world_y, local_z, id);

                        if aquifer.should_schedule_fluid_update() && id.has_fluid() {
                            chunk.mark_pos_for_postprocessing(BlockPos::new(
                                world_x, world_y, world_z,
                            ));
                        }
                    }
                    AquiferResult::Air => {}
                }
            },
        );

        // Flush remaining writes
        if !pending_writes.is_empty() {
            chunk.write_noise_column(prev_x, prev_z, &pending_writes);
        }
        chunk.replace_noise_heightmaps(ocean_floor_wg, world_surface_wg);
        chunk.install_post_noise_state(N::wrap_post_noise_state(aquifer, material_ore_vein_values));
    }

    #[expect(clippy::too_many_lines, reason = "splitting would hurt readability")]
    fn build_surface(
        &self,
        chunk: GenerationChunk<'_, TerrainPhase>,
        neighbor_biomes: &dyn Fn(IVec3) -> u16,
    ) {
        let min_y = N::Settings::MIN_Y;
        let pos = chunk.pos();
        let chunk_min_x = pos.0.x * 16;
        let chunk_min_z = pos.0.y * 16;
        let surface_rule_block_states = N::surface_rule_block_states();
        let surface_rule_uses_biome = N::surface_rule_uses_biome();
        let surface_rule_uses_preliminary_surface = N::surface_rule_uses_preliminary_surface();
        let surface_rule_uses_surface_secondary = N::surface_rule_uses_surface_secondary();
        let surface_rule_uses_steep = N::surface_rule_uses_steep();
        let material_ore_vein_values = chunk
            .with_post_noise_state_mut::<N::State, _>(N::material_ore_vein_values)
            .unwrap_or_else(|| Arc::from([]));
        let material_ore_vein_value_count = N::material_ore_vein_value_count();
        let material_ore_vein_count = material_ore_vein_value_count / 2;
        let mut material_cache = N::ColumnCache::default();
        let lazy_surface_rule_biome =
            surface_rule_uses_biome && surface_rule_uses_preliminary_surface;
        let surface_needs_min_surface_level =
            surface_rule_uses_preliminary_surface || self.surface_extension_biomes.frozen_ocean;
        let surface_needs_biomes =
            surface_rule_uses_biome || self.surface_extension_biomes.needs_surface_biome();
        let chunk_quart_x = pos.0.x * 4;
        let chunk_quart_z = pos.0.y * 4;

        chunk.prime_world_surface_heightmap();

        // Pre-compute preliminary surface corners only for rules/extensions that read them.
        let preliminary_surface_corners = surface_needs_min_surface_level
            .then(|| self.preliminary_surface_corners(chunk, chunk_min_x, chunk_min_z));

        let eroded_badlands_id = (*vanilla_biomes::ERODED_BADLANDS).id() as u16;
        let frozen_ocean_id = (*vanilla_biomes::FROZEN_OCEAN).id() as u16;
        let deep_frozen_ocean_id = (*vanilla_biomes::DEEP_FROZEN_OCEAN).id() as u16;

        // Pre-extract biome palette values only if surface rules/extensions need them.
        let biome_data = surface_needs_biomes.then(|| chunk.read_all_biomes());
        let mut quart_biomes = biome_data.as_deref().map(|biome_data| {
            SurfaceQuartBiomes::new(
                biome_data,
                chunk.section_count(),
                min_y,
                chunk_quart_x,
                chunk_quart_z,
                neighbor_biomes,
            )
        });

        let mut pending_writes: Vec<(usize, BlockStateId)> = Vec::new();
        let mut column_buf: Vec<BlockStateId> = Vec::new();
        let mut material_ore_vein_results: SmallVec<[Option<BlockStateId>; 2]> = SmallVec::new();
        let condition_noise_values = N::surface_noise_ids()
            .iter()
            .map(|_| Cell::new(0.0))
            .collect::<Vec<_>>();
        let condition_noise_initialized = N::surface_noise_ids()
            .iter()
            .map(|_| Cell::new(false))
            .collect::<Vec<_>>();
        let condition_noise_cache =
            SurfaceConditionNoiseCache::new(&condition_noise_values, &condition_noise_initialized);

        for local_x in 0..16usize {
            for local_z in 0..16usize {
                let block_x = chunk_min_x + local_x as i32;
                let block_z = chunk_min_z + local_z as i32;

                // Start scanning from one above the highest non-air block
                let mut start_height = chunk.world_surface_height_at(local_x, local_z);

                // Column-local Voronoi cache for fuzzed biome lookups.
                let mut biome_col = quart_biomes.as_mut().map(|quart_biomes| {
                    FuzzedBiomeColumn::new(
                        quart_biomes,
                        self.surface_biome_classes.as_ref(),
                        self.biome_zoom_seed,
                        block_x,
                        block_z,
                    )
                });

                // Eroded badlands extension: add terracotta pillars above surface
                let surface_biome_id = if self.surface_extension_biomes.needs_surface_biome() {
                    biome_col
                        .as_mut()
                        .map(|biome_col| biome_col.get(start_height))
                } else {
                    None
                };
                if self.surface_extension_biomes.eroded_badlands
                    && surface_biome_id == Some(eroded_badlands_id)
                {
                    start_height = self.surface_system.eroded_badlands_extension(
                        chunk,
                        local_x,
                        local_z,
                        block_x,
                        block_z,
                        start_height,
                        min_y,
                    );
                }

                // Snapshot the column once — avoids per-block section locking in the Y scan.
                // Taken after eroded_badlands_extension which may write blocks above the surface.
                chunk.read_column_into(local_x, local_z, &mut column_buf);

                // Surface depth for this column
                let surface_depth = self.surface_system.get_surface_depth(block_x, block_z);

                let surface_secondary = if surface_rule_uses_surface_secondary {
                    self.surface_system.get_surface_secondary(block_x, block_z)
                } else {
                    0.0
                };
                condition_noise_cache.reset();

                let min_surface_level = if let Some(corners) = preliminary_surface_corners {
                    // Vanilla: (float)(blockX & 15) / 16.0F — exact for 0-15.
                    let t_x = f64::from(local_x as u8) / 16.0;
                    let t_z = f64::from(local_z as u8) / 16.0;
                    let interp = lerp2(
                        t_x,
                        t_z,
                        f64::from(corners.nw),
                        f64::from(corners.ne),
                        f64::from(corners.sw),
                        f64::from(corners.se),
                    );
                    interp.floor() as i32 + surface_depth - 8
                } else {
                    0
                };

                // Steep condition: vanilla only checks south >= north + 4 and
                // west >= east + 4 (asymmetric, not absolute difference).
                let steep = surface_rule_uses_steep && {
                    let z_north = local_z.saturating_sub(1);
                    let z_south = (local_z + 1).min(15);
                    let h_north = chunk.world_surface_height_at(local_x, z_north) - 1;
                    let h_south = chunk.world_surface_height_at(local_x, z_south) - 1;
                    if h_south >= h_north + 4 {
                        true
                    } else {
                        let x_west = local_x.saturating_sub(1);
                        let x_east = (local_x + 1).min(15);
                        let h_west = chunk.world_surface_height_at(x_west, local_z) - 1;
                        let h_east = chunk.world_surface_height_at(x_east, local_z) - 1;
                        h_west >= h_east + 4
                    }
                };

                let mut stone_depth_above: i32 = 0;
                let mut water_height: i32 = i32::MIN;
                let mut next_ceiling_stone_y: i32 = i32::MAX;
                pending_writes.clear();

                for y in (min_y..=start_height).rev() {
                    let relative_y = (y - min_y) as usize;
                    let state = column_buf[relative_y];

                    if state.is_air() {
                        stone_depth_above = 0;
                        water_height = i32::MIN;
                        continue;
                    }

                    if state.get_block().config.liquid {
                        if water_height == i32::MIN {
                            water_height = y + 1;
                        }
                        continue;
                    }

                    // Solid block — scan for stone_depth_below (lookahead)
                    if next_ceiling_stone_y >= y {
                        next_ceiling_stone_y = i32::MIN;
                        for la_y in (min_y - 1..y).rev() {
                            if la_y < min_y {
                                next_ceiling_stone_y = la_y + 1;
                                break;
                            }
                            let la_rel = (la_y - min_y) as usize;
                            let la_state = column_buf[la_rel];
                            // isStone = !isAir && !isLiquid
                            if la_state.is_air() || la_state.get_block().config.liquid {
                                next_ceiling_stone_y = la_y + 1;
                                break;
                            }
                        }
                    }

                    stone_depth_above += 1;
                    let stone_depth_below = y - next_ceiling_stone_y + 1;

                    // Below the preliminary surface the rule is mostly
                    // decided by Y and biome class; run it only when not.
                    let outcome = if y < min_surface_level && preliminary_surface_corners.is_some()
                    {
                        biome_col
                            .as_mut()
                            .map_or(PartialSurfaceOutcome::Evaluate, |col| {
                                col.below_preliminary_outcome(y)
                            })
                    } else {
                        PartialSurfaceOutcome::Evaluate
                    };
                    match outcome {
                        PartialSurfaceOutcome::Keep => continue,
                        PartialSurfaceOutcome::Place(index) => {
                            pending_writes.push((relative_y, surface_rule_block_states[index]));
                            continue;
                        }
                        PartialSurfaceOutcome::Evaluate => {}
                    }

                    material_ore_vein_results.clear();
                    material_ore_vein_results.resize(material_ore_vein_count, None);
                    if let Some(ore_veinifier) = &self.ore_veinifier {
                        let offset = (relative_y * 16 * 16 + local_z * 16 + local_x)
                            * material_ore_vein_value_count;
                        if let Some(values) = material_ore_vein_values
                            .get(offset..offset + material_ore_vein_value_count)
                        {
                            N::fill_prefilled_material_ore_vein_results(
                                &self.noises,
                                &mut material_cache,
                                ore_veinifier,
                                values,
                                block_x,
                                y,
                                block_z,
                                &mut material_ore_vein_results,
                            );
                        }
                    }

                    let eager_biome_id = if surface_rule_uses_biome && !lazy_surface_rule_biome {
                        biome_col
                            .as_mut()
                            .map(|biome_col| biome_col.get_for_surface_rule(y))
                    } else {
                        None
                    };
                    let biome_provider = if lazy_surface_rule_biome {
                        biome_col
                            .as_mut()
                            .map(|biome_col| biome_col as &mut dyn SurfaceBiomeProvider)
                    } else {
                        None
                    };

                    let mut ctx = SurfaceRuleContext::new(
                        block_x,
                        block_z,
                        surface_depth,
                        surface_secondary,
                        min_surface_level,
                        steep,
                        y,
                        stone_depth_above,
                        stone_depth_below,
                        water_height,
                        eager_biome_id,
                        biome_provider,
                        &self.surface_system,
                        &condition_noise_cache,
                        surface_rule_block_states,
                    )
                    .with_ore_vein_results(&material_ore_vein_results);

                    if let Some(new_block) = N::try_apply_surface_rule(&mut ctx) {
                        pending_writes.push((relative_y, new_block));
                    }
                }

                // Flush batched writes — holds each section's write guard once
                if !pending_writes.is_empty() {
                    chunk.write_column(local_x, local_z, &pending_writes);
                    for &(relative_y, state) in &pending_writes {
                        column_buf[relative_y] = state;
                    }
                }

                // Frozen ocean iceberg extension: add packed ice and snow
                if self.surface_extension_biomes.frozen_ocean
                    && let Some(surface_biome_id) = surface_biome_id
                        .filter(|id| *id == frozen_ocean_id || *id == deep_frozen_ocean_id)
                {
                    pending_writes.clear();
                    self.surface_system.collect_frozen_ocean_extension_writes(
                        surface_biome_id,
                        block_x,
                        block_z,
                        start_height,
                        min_surface_level,
                        min_y,
                        &column_buf,
                        &mut pending_writes,
                    );
                    if !pending_writes.is_empty() {
                        chunk.write_column(local_x, local_z, &pending_writes);
                    }
                }
            }
        }
    }

    #[expect(
        clippy::too_many_lines,
        reason = "keeps retained aquifer state, source carvers, and biome sampling in one flow"
    )]
    fn apply_carvers(&self, chunk: GenerationChunk<'_, TerrainPhase>) {
        if self
            .uniform_carver_biome
            .is_some_and(|biome| biome.carvers.is_empty())
        {
            chunk.clear_post_noise_state();
            return;
        }

        chunk.consume_post_noise_state::<N::State, _>(|mut retained_state| {
            chunk.prime_world_surface_heightmap();

            let pos = chunk.pos();
            let chunk_min_x = pos.0.x * 16;
            let chunk_min_z = pos.0.y * 16;
            let min_y = N::Settings::MIN_Y;
            let height = N::Settings::HEIGHT;
            let noises = &*self.noises;

            let material_ore_vein_values = retained_state
                .as_deref_mut()
                .map_or_else(|| Arc::from([]), N::material_ore_vein_values);

            let mut rebuilt_aquifer = None;
            let aquifer = if let Some(state) = retained_state {
                N::post_noise_aquifer(state)
            } else {
                let mut column_cache = N::ColumnCache::default();
                if N::Settings::AQUIFERS_ENABLED {
                    column_cache.init_grid(chunk_min_x, chunk_min_z, noises);
                }
                rebuilt_aquifer.insert(Aquifer::<N>::new(
                    chunk_min_x,
                    chunk_min_z,
                    min_y,
                    height,
                    &self.splitter,
                    noises,
                    &self.preliminary_surface,
                    column_cache,
                ))
            };

            // Preliminary surface level at the chunk's 4 corners — used by
            // top_material min_surface_level interpolation.
            let psl_corners = PreliminarySurfaceCorners {
                nw: aquifer.preliminary_surface_level(noises, chunk_min_x, chunk_min_z),
                ne: aquifer.preliminary_surface_level(noises, chunk_min_x + 16, chunk_min_z),
                sw: aquifer.preliminary_surface_level(noises, chunk_min_x, chunk_min_z + 16),
                se: aquifer.preliminary_surface_level(noises, chunk_min_x + 16, chunk_min_z + 16),
            };

            let mut ctx = CarvingContext {
                noises,
                min_y,
                gen_depth: height,
                sea_level: N::Settings::SEA_LEVEL,
                surface_system: &self.surface_system,
                aquifer,
                default_block_id: self.default_block_id,
                psl_corners,
                chunk_min_x,
                chunk_min_z,
                material_ore_vein_values,
                ore_veinifier: self.ore_veinifier.as_ref(),
                material_cache: N::ColumnCache::default(),
            };

            let ids = CarverBlockIds::load();

            // Pre-fetch the 17×17 source-chunk carver lists before borrowing the
            // sampler for the top-material biome lookup.
            let mut biome_sampler = self.biome_source.chunk_sampler();
            let mut source_biomes: SmallVec<[SourceChunk; CARVER_SOURCE_CHUNK_COUNT]> =
                SmallVec::new();
            for dx in -8i32..=8 {
                for dz in -8i32..=8 {
                    let sx = pos.0.x + dx;
                    let sz = pos.0.y + dz;
                    let biome = if let Some(biome) = self.uniform_carver_biome {
                        biome
                    } else {
                        let qx = (sx * 16) >> 2;
                        let qz = (sz * 16) >> 2;
                        biome_sampler.sample(qx, 0, qz)
                    };
                    source_biomes.push(SourceChunk {
                        pos: ChunkPos::new(sx, sz),
                        biome,
                    });
                }
            }

            // `WorldgenRandom(LegacyRandomSource(generateUniqueSeed()))` — initial
            // seed is irrelevant; every carver overwrites it via
            // `set_large_feature_seed` before its probability check.
            let mut random = LegacyRandom::from_seed(0);
            let seed_i64 = self.seed;

            let biome_zoom_seed = self.biome_zoom_seed;
            // BiomeManager-fuzzed lookup — matches vanilla's `BiomeManager.getBiome`
            // used by the carver's top-material path. An unfuzzed quart lookup
            // would mismatch vanilla at quart-cell boundaries.
            let mut biome_getter = |pos: BlockPos| -> u16 {
                fuzzed_biome_at_block(biome_zoom_seed, pos, |q_pos| {
                    biome_sampler.sample(q_pos.x, q_pos.y, q_pos.z).id() as u16
                })
            };

            let context_min_y = chunk.min_y().max(min_y);
            let context_height = chunk.height().min(height);
            let mut mask = CarvingMask::for_worldgen_context(context_min_y, context_height);
            let mut run = CarveRun {
                ctx: &mut ctx,
                noises,
                chunk,
                chunk_min_x,
                chunk_min_z,
                biome_getter: &mut biome_getter,
                mask: &mut mask,
                ids,
            };

            run.run_all(&source_biomes, seed_i64, &mut random);
            if !run.mask.is_empty() {
                run.apply_carving_mask();
            }
        });
    }

    fn create_worldgen_region_random(&self, _world_seed: i64, center: ChunkPos) -> RandomSource {
        worldgen_region_random_from_splitter(&self.splitter, center)
    }

    fn apply_biome_decorations(&self, region: &mut WorldGenRegion<'_>) {
        self.feature_runner
            .decorate(region, &REGISTRY, self.seed, self.biome_zoom_seed);
    }
}

impl<N, F> CarveRun<'_, '_, N, F>
where
    N: DimensionNoises,
    F: FnMut(BlockPos) -> u16,
{
    /// Drive the 17×17 source-chunk carver loop. Each carver in each source
    /// biome is seeded via `set_large_feature_seed`, probability-checked,
    /// then dispatched to the appropriate `carve_*` method.
    fn run_all(&mut self, source_biomes: &[SourceChunk], seed_i64: i64, random: &mut LegacyRandom) {
        for source in source_biomes {
            for (index, carver_key) in source.biome.carvers.iter().enumerate() {
                let Some(carver) = REGISTRY.configured_carvers.by_key(carver_key) else {
                    panic!(
                        "biome {} references unknown configured carver {}",
                        source.biome.key, carver_key
                    );
                };
                let index_i64 = index as i64;
                random.set_large_feature_seed(
                    seed_i64.wrapping_add(index_i64),
                    source.pos.0.x,
                    source.pos.0.y,
                );

                let probability = carver.base().probability;
                if random.next_f32() > probability {
                    continue;
                }

                match &carver.kind {
                    ConfiguredCarverKind::Cave(cfg) => {
                        self.carve_cave(cfg, source.pos, random);
                    }
                    ConfiguredCarverKind::Canyon(cfg) => {
                        self.carve_canyon(cfg, source.pos, random);
                    }
                }
            }
        }
    }
}

// ── BiomeManager biome zoom helpers ──────────────────────────────────────────

/// Vanilla's `LinearCongruentialGenerator.next()`.
#[inline]
pub(super) const fn lcg_next(mut rval: i64, c: i64) -> i64 {
    rval = rval.wrapping_mul(
        rval.wrapping_mul(6_364_136_223_846_793_005)
            .wrapping_add(1_442_695_040_888_963_407),
    );
    rval = rval.wrapping_add(c);
    rval
}

/// Vanilla's `BiomeManager.getFiddle()`.
#[inline]
pub(super) fn get_fiddle(rval: i64) -> f64 {
    let uniform = ((rval >> 24).rem_euclid(1024)) as f64 / 1024.0;
    (uniform - 0.5) * 0.9
}

/// Single-shot fuzzed biome lookup at a block position. Matches vanilla's
/// `BiomeManager.getBiome(BlockPos)`: the block is shifted by `-2`, snapped to
/// the enclosing quart cell, and the winning biome is chosen from the 8
/// corners of that cell by `get_fiddle`-perturbed squared distance.
///
/// `quart_biome` returns the unfuzzed biome at a quart-coordinate — typically
/// `biome_sampler.sample(qx, qy, qz).id()`.
///
/// Used by carver top-material lookups where a simple unfuzzed lookup would
/// differ from vanilla at the quart-cell boundaries.
pub(crate) fn fuzzed_biome_at_block<F: FnMut(IVec3) -> u16>(
    biome_zoom_seed: i64,
    pos: BlockPos,
    mut quart_biome: F,
) -> u16 {
    let abs = pos.0 - IVec3::splat(2);
    let parent = IVec3::new(abs.x >> 2, abs.y >> 2, abs.z >> 2);
    let fract = DVec3::new(
        f64::from(abs.x & 3),
        f64::from(abs.y & 3),
        f64::from(abs.z & 3),
    ) / 4.0;

    let mut min_i = 0usize;
    let mut min_dist = f64::INFINITY;

    for i in 0..8usize {
        let x_even = (i & 4) == 0;
        let y_even = (i & 2) == 0;
        let z_even = (i & 1) == 0;
        let cx = if x_even { parent.x } else { parent.x + 1 };
        let cy = if y_even { parent.y } else { parent.y + 1 };
        let cz = if z_even { parent.z } else { parent.z + 1 };
        let dx = if x_even { fract.x } else { fract.x - 1.0 };
        let dy = if y_even { fract.y } else { fract.y - 1.0 };
        let dz = if z_even { fract.z } else { fract.z - 1.0 };

        // BiomeManager.getFiddledDistance — identical sequence to
        // FuzzedBiomeColumn::compute_cy_group but without the column cache.
        let mut rval = lcg_next(biome_zoom_seed, i64::from(cx));
        rval = lcg_next(rval, i64::from(cy));
        rval = lcg_next(rval, i64::from(cz));
        rval = lcg_next(rval, i64::from(cx));
        rval = lcg_next(rval, i64::from(cy));
        rval = lcg_next(rval, i64::from(cz));
        let fx = get_fiddle(rval);
        rval = lcg_next(rval, biome_zoom_seed);
        let fy = get_fiddle(rval);
        rval = lcg_next(rval, biome_zoom_seed);
        let fz = get_fiddle(rval);

        let dx = dx + fx;
        let dy = dy + fy;
        let dz = dz + fz;
        let dist = dz * dz + dy * dy + dx * dx;
        if min_dist > dist {
            min_i = i;
            min_dist = dist;
        }
    }

    let b = IVec3::new(
        if (min_i & 4) == 0 {
            parent.x
        } else {
            parent.x + 1
        },
        if (min_i & 2) == 0 {
            parent.y
        } else {
            parent.y + 1
        },
        if (min_i & 1) == 0 {
            parent.z
        } else {
            parent.z + 1
        },
    );
    quart_biome(b)
}

#[cfg(test)]
mod tests {
    use std::sync::Weak;

    use glam::IVec3;
    use steel_registry::{init_vanilla_registry, vanilla_dimension_types};
    use steel_worldgen::biomes::BiomeSourceKind;

    use crate::behavior::init_behaviors;
    use crate::chunk::{
        Chunk,
        heightmap::{ChunkHeightmaps, Heightmap, HeightmapType},
        section::{ChunkSection, Sections},
    };
    use crate::worldgen::generator::{
        ChunkGenerator as _, GenerationChunk, TerrainPhase, context::OverworldGenerator,
    };

    fn make_overworld_chunk() -> Chunk {
        let dimension = &vanilla_dimension_types::OVERWORLD;
        let sections = (0..dimension.height / 16)
            .map(|_| ChunkSection::new_empty())
            .collect::<Vec<_>>()
            .into_boxed_slice();
        Chunk::new(
            Sections::from_owned(sections),
            steel_utils::ChunkPos::new(0, 0),
            dimension.min_y,
            dimension.height,
            Weak::new(),
        )
    }

    fn self_neighbor_biome(chunk: &Chunk, quart: IVec3) -> u16 {
        let sections = chunk.sections();
        let min_quart_y = chunk.min_y() >> 2;
        let quart_y =
            (quart.y - min_quart_y).clamp(0, (sections.sections.len() * 4) as i32 - 1) as usize;
        sections.sections[quart_y / 4].read().biomes.get(
            (quart.x & 3) as usize,
            quart_y % 4,
            (quart.z & 3) as usize,
        )
    }

    fn blocks(chunk: &Chunk) -> Vec<steel_utils::BlockStateId> {
        let mut blocks = Vec::with_capacity((chunk.height() * 16 * 16) as usize);
        for relative_y in 0..chunk.height() as usize {
            for z in 0..16 {
                for x in 0..16 {
                    let Some(state) = chunk.get_relative_block(x, relative_y, z) else {
                        panic!("test coordinates must stay inside the chunk");
                    };
                    blocks.push(state);
                }
            }
        }
        blocks
    }

    fn has_overworld_post_noise_state(chunk: &Chunk) -> bool {
        chunk
            .with_transient_generation_state_mut::<
                super::SteelPostNoiseState<super::OverworldNoises>,
                _,
            >(|_| ())
            .is_some()
    }

    #[test]
    fn retained_and_rebuilt_aquifers_produce_identical_carver_output() {
        use std::panic;
        use std::thread;

        // Larger stack to match chunk_stage_hashes.rs — noise/carver generation
        // recurses deeply enough to overflow the default test thread stack.
        let result = thread::Builder::new()
            .stack_size(16 * 1024 * 1024)
            .spawn(retained_and_rebuilt_aquifers_produce_identical_carver_output_inner)
            .expect("Failed to spawn test thread")
            .join();

        if let Err(payload) = result {
            panic::resume_unwind(payload);
        }
    }

    fn retained_and_rebuilt_aquifers_produce_identical_carver_output_inner() {
        init_vanilla_registry();
        init_behaviors();
        let pool = rayon::ThreadPoolBuilder::new()
            .num_threads(1)
            .build()
            .expect("test generation pool should build");
        let generator = OverworldGenerator::new(None, BiomeSourceKind::overworld(0), 0, &pool);
        let warm = make_overworld_chunk();
        let cold = make_overworld_chunk();

        for chunk in [&warm, &cold] {
            generator.create_biomes(chunk);
            generator.fill_from_noise(GenerationChunk::<TerrainPhase>::for_test(chunk), None);

            let mut expected = ChunkHeightmaps::empty();
            expected.prime_from_sections(
                HeightmapType::worldgen_types(),
                chunk.min_y(),
                chunk.height(),
                &chunk.sections().sections,
            );
            let actual = chunk.heightmaps.read();
            for &heightmap_type in HeightmapType::worldgen_types() {
                assert_eq!(
                    actual.get(heightmap_type).map(Heightmap::raw_data),
                    expected.get(heightmap_type).map(Heightmap::raw_data),
                    "{heightmap_type:?} must match the generated blocks",
                );
            }
        }
        assert!(has_overworld_post_noise_state(&warm));
        assert!(has_overworld_post_noise_state(&cold));

        cold.clear_transient_generation_state();
        for chunk in [&warm, &cold] {
            generator.build_surface(GenerationChunk::<TerrainPhase>::for_test(chunk), &|quart| {
                self_neighbor_biome(chunk, quart)
            });
        }
        assert!(has_overworld_post_noise_state(&warm));
        assert!(!has_overworld_post_noise_state(&cold));

        generator.apply_carvers(GenerationChunk::<TerrainPhase>::for_test(&warm));
        generator.apply_carvers(GenerationChunk::<TerrainPhase>::for_test(&cold));
        assert!(!has_overworld_post_noise_state(&warm));
        assert!(!has_overworld_post_noise_state(&cold));

        assert_eq!(blocks(&warm), blocks(&cold));
        assert_eq!(&*warm.postprocessing.lock(), &*cold.postprocessing.lock());
        for x in 0..16 {
            for z in 0..16 {
                assert_eq!(
                    warm.generation_height_at(HeightmapType::WorldSurfaceWg, x, z),
                    cold.generation_height_at(HeightmapType::WorldSurfaceWg, x, z)
                );
            }
        }
    }
}