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
  noise-scale: 0.020
  noise-threshold: 0.45

Field	Required	Default	Description
`name`	Yes	—	Feature identifier. Registered as `ModName:name`.
`min-altitude`	Yes	—	Lower (deeper) world-Y bound of the feature’s vertical range. Usually negative (underground), but these are plain world-Y values — a feature can sit at positive altitude too (e.g. a hollow inside a sky island).
`max-altitude`	Yes	—	Upper (shallower) world-Y bound. Must be greater than `min-altitude`, or the whole feature fails to load. Ascending like every other vertical band in the schema.
`zone-generator`	No	`warped_octaves` with defaults	Which algorithm decides the feature’s extent, and its tuning — see Boundary shape.
`surface-block`	No	(none)	Block placed where the feature’s own carved space meets open air (e.g. cave floor). Namespaced to your mod automatically if written without a colon.
`block-layers`	No	(all air)	A list of `{layer, block}` entries filling the feature’s interior. `layer` is a layer index from `0` up to the world’s configured layer count; a layer the list doesn’t name defaults to `Creation:air`. Naming a layer the world doesn’t have, or the same layer twice, fails the entry.
`ores`	No	(none)	Ore names (from Ore Configuration) that can spawn within this feature.
`structures`	No	(none)	Structure names (from Structure Configuration) that can spawn within this feature.
`static-object-spawns`	No	(none)	Names of registered trees/interactables that can spawn within this feature. An object can anchor to a cave ceiling or wall (hanging vines, roots, stalactites) rather than the floor via its own `attach` field — this is the only spawn path that honors `attach`, and it requires a `cave-generator` to carve the open space to attach to.
`cave-generator`	No	(no interior caves)	Open space carved inside the feature (e.g. an interior cave network). Takes `type: simplex_threshold` plus `noise-scale` and `noise-threshold`.

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:

`type`	Fields	What it does
`warped_octaves` (default)	`noise-scale`, `noise-threshold`, `warp-scale`, `warp-strength`	Multi-octave domain-warped noise plus a rotated-quadrant term, thresholded. `warp-strength: 0.0` disables warping for a regular boundary; higher values distort it into an organic shape.
`warped_simplex`	`noise-scale`, `noise-threshold`	A thresholded simplex sum with warped coordinates and a per-block texture jitter, giving a jagged cave-wall-like edge.

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.

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 Aug 3, 2026