Underground Feature Configuration

Carve a depth-bounded region with its own rock, ores, and structures into cave or surface world generation.

An underground feature carves out a depth-bounded region (e.g. a glowing cavern biome) with its own surface/wall block overrides, ore/structure/static-object spawns, and optional secondary cave shape — independent from a world builder’s own top-level cave generation. Features are referenced by name from a World Builder Configuration preset’s global-underground-features list (or from a biome’s own underground-features list, applying only within that biome).

File Location

Unlike other catalog files, underground features are not referenced from your mod’s manifest — every YAML file in a fixed folder is scanned and loaded automatically:

mods/<YourMod>/underground-features/<name>.yaml

Each file is a single feature (no wrapping list).

Minimal Example

name: my_underground_feature
min-altitude: -200
max-altitude: -20

This registers a feature spanning world-Y -200 up to -20, using every field’s default otherwise (no ore/structure/static-object spawns, all block layers defaulting to air).

Full Field Reference

name: my_underground_feature  # Required
min-altitude: -200             # Required. Lower (deeper) world-Y bound
max-altitude: -20              # Required. Upper (shallower) world-Y bound; must be > min-altitude
zone-generator:                 # Optional. Which algorithm shapes the feature's own boundary
  type: warped_octaves           # `warped_octaves` (default) or `warped_simplex`
  noise-scale: 0.004
  noise-threshold: 0.6
  warp-scale: 0.003
  warp-strength: 0.0
surface-block: YourMod:my_block   # Optional. Namespaced automatically if unqualified
block-layers:                      # Optional. Any layer you omit defaults to Creation:air
  - layer: 0
    block: YourMod:my_wall_block
  - layer: 1
    block: YourMod:my_block
ores:                               # Optional. Names from ore-config.yaml
  - YourMod:my_ore
structures:                          # Optional. Names from structure-config.yaml
  - YourMod:my_structure
static-object-spawns:                  # Optional. Names of registered trees/interactables
  - YourMod:my_interactable
cave-generator:                         # Optional. Open space carved *inside* the feature
  type: simplex_threshold                #   `simplex_threshold` (pockets) or `channel` (one tube)
  noise-scale: 0.020
  noise-threshold: 0.45
flood:                                    # Optional. Standing water filling the carve
  block: water
  to-altitude: -500
  fishing-water-type: YourMod:my_water

A malformed or missing optional field falls back to its own default independently — it doesn’t fail the whole feature. Only name, min-altitude, and max-altitude are load-bearing.

Boundary shape

A feature’s extent is decided by one of two algorithms, named by zone-generator’s type:

Omitting zone-generator entirely is warped_octaves with every default.

This used to be an untagged either/or, and that’s what the type fixes. The two systems were selected by presence: the analytic fields sat bare at the feature’s top level (noise-scale-x, noise-threshold, warp-scale, warp-strength), and adding a zone-grid-options block silently replaced all of them at once. Nothing in the file said which was in effect, so the shipped glow_cave.yaml carried a hand-written comment explaining it. Both are now type values of one block, so setting fields the active algorithm can’t use is a load error rather than a silent no-op.

noise-scale-y is gone. It was documented as a per-axis frequency, and both sample sites read the x scale for both axes — it never did anything. Use the single noise-scale.

Caveat: only the ground-terrain and cave-dimension paths consult warped_simplex. The sky-island overlay path always evaluates the analytic form, so a feature attached to a sky-island biome and set to warped_simplex is shaped by warped_octaves defaults instead. Give such a feature an explicit warped_octaves generator.

Interior shape

cave-generator’s own type picks how the feature’s interior is opened up:

A channel’s centreline wanders by up to amplitude blocks from the middle of the feature’s band, and the whole bore is kept inside min-altitude/max-altitude — an amplitude larger than the band makes the tube meander along the band’s inner edge rather than leave it.

Mind the zone under a channel. A feature is carved only where its zone-generator says the feature is, and the zone settings that suit a pocket feature — a blobby region with chambers in it — will chop a channel into fragments, because the tube only exists where the blob happens to cover it. Measured on the shipped terrain, a channel under a warped_simplex zone at noise-threshold: 0.35 is carved in about a fifth of its columns. If you want a passage that can actually be followed, give a channel a permissive zone (a low threshold, and warped_octaves with warp-strength: 0.0 for an unwarped boundary) over a narrow band. The trade is that the feature then owns most of that band: its block-layers replace the rock there and ordinary caves are suppressed inside it.

Flooding

flood fills whatever the feature carved, up to to-altitude, with a fluid block. It works with either interior shape: on simplex_threshold it gives flooded chambers, and on a channel whose centreline crosses the flood level it gives sumps — submerged stretches you have to swim, with air pockets where the tube rises back above the water.

Two things fail the whole feature rather than loading a broken one, because both would generate something the config says is holding water when it is not:

• flood with no cave-generator — there is nothing carved to fill.
• flood whose layer-1 block is air — the feature has no wall to hold the water in.

A flooded feature also insets its carve by one cell from its own boundary: a cell whose lower or side neighbour falls outside the feature stays solid. That is what lets the water be placed as full, sealed cells instead of being spread by the flood fill, which would run it out through whatever the cave pass left next door. It applies only when flood is present, so adding it is the only thing that can change a feature’s shape.

The water does not move. The fluid simulation conserves volume and has no source blocks, so a flooded channel is still water at a level, not a running one, and no waterfall inside it persists. Traversal along it is a current — persistent AoE zones — not the simulation.

Complete Example

Based on the real shipped glow_cave feature — its boundary uses warped_simplex and its interior caves the per-block threshold (see Boundary shape above):

name: glow_cave

min-altitude: -2000
max-altitude: -20

surface-block: glow_rock

block-layers:
  - layer: 0
    block: stone_wall
  - layer: 1
    block: glow_rock

ores:
  - coal_ore

zone-generator:
  type: warped_simplex
  noise-scale: 0.001
  noise-threshold: 0.35

# Interior caves carved through the zone.
cave-generator:
  type: simplex_threshold
  noise-scale: 0.020
  noise-threshold: 0.30

Last updated Sep 29, 2026