Iris/docs/13 - Biomes.md

# 13 - Biomes

A biome is where terrain height, surface materials, decoration and placement all come together. Files live at `biomes/<loadKey>.json`. Regions list root biomes; roots can nest children, swap themselves out under carvings, and publish custom datapack biomes for colours, tags and mob spawns.

Related: see `12 - Regions.md`, `14 - Generators & Noise.md`, `15 - Caves & Carving.md`, `16 - Surfaces, Decorators & Deposits.md`, `17 - Trees, Fungi, Coral, Crystals, Formations, Ruins.md`, `19 - Objects.md`, `20 - Object Placement.md`, `23 - Loot, Entities, Spawners, Markers.md`.

## The mental model

A biome file answers two separate questions, and they fail in different ways.

**Where does this biome appear?** Not from anything in the file. The region lists it, the role (land, sea, shore, cave) comes from which list it was in, and a noise value picks between the siblings in that list weighted by `1 / rarity`. See `12 - Regions.md`.

**What does the world look like where it appears?** That is the whole rest of the file, and it runs top to bottom per column:

```
column (x, z)
  |
  generators[]  ->  terrain height Y   (each link maps 0..1 noise into min..max, relative to fluidHeight)
  |
  layers[]      ->  block stack downward from Y
  |
  remaining depth below the layers  ->  dimension rock palette
  |
  if Y < fluidHeight: seaLayers[] fill downward from the water surface, remainder is fluid
  |
  decorators, objects, structures, procedural content go on top
  |
  derivative / customDerivitives  ->  what Minecraft calls this biome (colours, mobs, structure eligibility)
```

Three of those steps regularly surprise people:

- **Height is relative to `fluidHeight`, not to Y=0.** `min: 4, max: 10` means "4 to 10 blocks above the water line". Negative values put the surface under water, which is how ocean floors and river beds are made.
- **A biome has no `type` field.** `carving/drip` is a cave biome only because a region put it in `caveBiomes`. The same file placed in `landBiomes` would generate as land.
- **The role can be corrected after height is known.** If a land biome's height lands below the water line, Iris swaps in a sea biome from the same region; if it lands in the shore band, a shore biome. So a "land" biome with a negative generator will simply never render as itself.

### Children

`children` lets one biome dissolve into variants without adding entries to the region. At each column, Iris runs a second noise pass over the parent's children **plus the parent itself**, then repeats on whatever it picked, up to four times in total. The chain usually ends early because re-picking the parent stops it.

Child weighting is not the same as list rarity. Each candidate gets `(highestRarityInTheGroup + 1) - rarity` slots:

| Parent rarity | Child rarity | Parent slots | Child slots | Result |
|---|---|---|---|---|
| 1 | 1 | 1 | 1 | Half and half |
| 1 | 4 | 4 | 1 | Child covers a fifth of the parent |
| 1 | 3 and 3 (two children) | 3 | 1 each | Parent 60%, each child 20% |

Because the weights are relative to the highest rarity present, setting every candidate to the same number (all `1`, all `9`) gives a uniform split. Only differences matter.

`childShrinkFactor` scales the child selection noise coordinates, so higher values make each child patch smaller inside the parent. `childStyle` decides the patch shape.

## Walkthrough: add a biome to a region and see it

Prerequisites: a validating dimension, a region it lists, and `generators/flat.json` (see `26 - Example - Minimal Dimension.md`).

1. Save this as `biomes/tutorial/meadow.json`:

```json
{
  "name": "Tutorial Meadow",
  "derivative": "minecraft:plains",
  "vanillaDerivative": "minecraft:plains",
  "generators": [{ "generator": "flat", "min": 96, "max": 96 }],
  "layers": [
    { "palette": [{ "block": "minecraft:grass_block" }] },
    { "minHeight": 2, "maxHeight": 4, "palette": [{ "block": "minecraft:dirt" }] }
  ]
}
```

`min` equal to `max` gives a dead-flat surface at 96 blocks above `fluidHeight`, which makes any height problem obvious later.

2. Add `"tutorial/meadow"` to that region's `landBiomes`.

3. Set `"focus": "tutorial/meadow"` on the dimension, validate, and open Studio on seed `1337`.

4. Fly into new chunks and run `/iris what biome`.

Success: the load key is `tutorial/meadow`, the surface is grass over 2-4 dirt over stone, the terrain is perfectly flat, and there are no unresolved generator warnings.

If nothing generates, compare the region entry, the file path and the `focus` string character for character. If the biome resolves but sits on void, the generator link is wrong — check `generators/flat.json` exists and the key matches.

5. Remove `focus`, reopen Studio, and travel until the biome turns up naturally. Only then add decorators, objects and children.

While `focus` is set, the focused biome is forced into the land role for the whole world, so sea and shore correction never runs. A sea biome under `focus` will render as if it were land.

## Walkthrough: make it hilly, then flatten part of it

The generator supplies the shape; the biome supplies the height band. To get hills, point at a generator with real relief and open the band:

```json
{ "generators": [{ "generator": "plain", "min": 4, "max": 40 }] }
```

Observable result: terrain now rolls between 4 and 40 blocks above the water line, with the shape coming from `generators/plain.json`.

To make one biome a plateau while its neighbours stay hilly, set `min` equal to `max` on that biome only:

```json
{ "generators": [{ "generator": "plain", "min": 22, "max": 22 }] }
```

Observable result: a flat table at 22, blending into its neighbours across the generator's interpolation range. The transition width is the generator's `interpolator.horizontalScale`, not anything on the biome.

To stack a rare feature on top of a base shape, use two links with different generators:

```json
{
  "generators": [
    { "generator": "smooth-dunes", "max": 12, "min": 5 },
    { "generator": "rare-hills", "max": 40, "min": 0 }
  ]
}
```

Observable result: rolling dunes 5-12 above water, with occasional hills adding up to another 40. The bands add, so the biome's full range is 5 to 52. How the two shapes combine depends on their generators' interpolators — see `14 - Generators & Noise.md`.

## Walkthrough: turn it into an ocean floor

Same biome, negative band, added to `seaBiomes` instead of `landBiomes`:

```json
{
  "name": "Temperate Ocean",
  "derivative": "minecraft:lukewarm_ocean",
  "vanillaDerivative": "minecraft:ocean",
  "generators": [{ "min": -32, "max": -10, "generator": "mountain" }],
  "layers": [{ "minHeight": 3, "maxHeight": 5, "palette": [{ "block": "minecraft:sand" }] }]
}
```

Observable result: the surface sits 10 to 32 blocks below the water line and the column above it fills with the dimension's fluid palette. `derivative` gives the water its warm colour; `vanillaDerivative` being an exact ocean key is what keeps ocean monuments and shipwrecks eligible here (see "Structure eligibility" below).

## Walkthrough: add a child variant

```json
{
  "name": "Oak Forest",
  "derivative": "minecraft:forest",
  "vanillaDerivative": "minecraft:forest",
  "children": ["temperate/oak-forest-extended"],
  "childShrinkFactor": 1.5,
  "childStyle": { "style": "CELLULAR_IRIS_DOUBLE" }
}
```

Create `biomes/temperate/oak-forest-extended.json` as an ordinary biome file and do **not** add it to any region list. Observable result: patches of the child appear inside the parent's footprint, sized by `childShrinkFactor` and shaped by `childStyle`, at roughly half the parent's area when both rarities are `1`.

Raise the child's `rarity` to shrink its share. Raise `childShrinkFactor` to break it into smaller patches without changing its share.

## Load key

| Rule | Detail |
|------|--------|
| Folder | `biomes/` |
| Key | Path relative to `biomes/` with `.json` stripped |
| Examples | `starter` -> `biomes/starter.json`; `temperate/plains` -> `biomes/temperate/plains.json` |

## Field reference (`IrisBiome`)

### Identity

| Field | Type | Default | What it does |
|-------|------|---------|--------------|
| `name` | string | `"Subterranean Land"` | Display name in tooling and `/iris what biome`. Required, minimum 2 characters. It is mixed into the biome's own noise seed, so renaming shifts scatter and custom-biome selection patterns. |
| `rarity` | int 1-512 | `1` | Divides this biome's share of its region list: `4` gives a quarter the area of a `1`. Also used, on a different scale, when this biome competes with its own children (see "Children"). |
| `color` | string | `null` | Hex colour for the studio map. Set it when debugging biome distribution visually. |

### Minecraft derivatives

| Field | Type | Default | What it does |
|-------|------|---------|--------------|
| `derivative` | biome key | `"minecraft:the_void"` | The Minecraft biome this one presents as: grass and water tint, ambient sound, mob spawning, temperature effects. Required — leaving it at the default gives a void-tinted world. Bare names are namespaced automatically, so `plains` becomes `minecraft:plains`. |
| `vanillaDerivative` | biome key | `null` (falls back to `derivative`) | The biome used when Minecraft asks "may this structure generate here". Set it when you want a decorative `derivative` (`lukewarm_ocean`) but a structure-standard one (`ocean`). |
| `biomeScatter` | string[] | empty | Alternative derivatives mixed across the biome for the underground portion of the column. One entry is used as-is; several are picked per position by `biomeStyle` noise. Use it to break up flat colour. |
| `biomeSkyScatter` | string[] | empty | Alternative derivatives for the surface and above. When this list is non-empty it takes over the visible biome for the column; when it is empty the column falls back to `biomeScatter`, then to `derivative`. |
| `biomeStyle` | `IrisGeneratorStyle` | `SIMPLEX` | The noise that disperses the scatter lists and picks between multiple `customDerivitives`. Change its `zoom` to make the colour patches larger or smaller. |

Where the split between "underground" and "surface" applies depends on the generation path. On platforms where Iris supplies a 3D biome source to native worldgen, positions below the terrain surface resolve through the cave biome and `biomeScatter`, and positions above resolve through `biomeSkyScatter`. On the path where Iris writes biomes into the chunk itself, one biome is written for the whole column using the sky resolution. Either way, setting only `biomeSkyScatter` changes what players see; setting only `biomeScatter` may not.

### Structure eligibility

Native and datapack structures are filtered by the biome Minecraft sees, so Iris enforces the generated role before handing the key over:

| Situation | Key handed to structure selection |
|---|---|
| Land or cave role | `vanillaDerivative`, else `derivative` |
| Sea role, key contains `ocean` or ends in `river` | unchanged |
| Sea role, any other `minecraft:` key | `minecraft:the_void`, so no native structure is eligible |
| Shore role, key ends in `beach` or `shore` | unchanged |
| Shore role, any other `minecraft:` key | `minecraft:beach` |
| Non-`minecraft:` namespace (mod biomes) | unchanged, always authoritative |

That is why a sea biome with `vanillaDerivative: "minecraft:plains"` gets no ocean structures at all. See `22 - Native Structures & Datapacks.md`.

### Children and carving

| Field | Type | Default | What it does |
|-------|------|---------|--------------|
| `children` | string[] | empty | Biome keys that portions of this biome morph into. Cycles are allowed; a column resolves at most four child hops. Do not also list these in a region. |
| `childShrinkFactor` | double | `1.5` | Scales the child selection noise. Higher means smaller child patches inside the parent. Useful range is roughly 1 to 3. |
| `childStyle` | `IrisGeneratorStyle` | `CELLULAR_IRIS_DOUBLE` | Shape of the child patches. Cellular styles give distinct blobs; simplex gives soft gradients. |
| `carvingBiome` | string | `""` | Biome key used instead of this one under a carving. Reachability indexes follow it, so the referenced biome is loaded and registered even if no region lists it. |
| `caveMinDepthBelowSurface` | int 0-256 | `0` | When this biome is used as a cave biome, columns less than this many blocks below the terrain surface fall back to the surface biome instead. Raise it to keep a deep-cave palette out of shallow openings. |

### Height (`generators`)

Type: `IrisBiomeGeneratorLink`, available as the `generator-layer` snippet.

| Field | Type | Default | What it does |
|-------|------|---------|--------------|
| `generator` | string | `"default"` | Load key under `generators/`. A missing or blank key resolves to `default`; an unresolvable key falls back to an empty generator, which contributes zero height. |
| `min` | int -2032..2032 | `0` | Bottom of this link's height band, in blocks relative to `fluidHeight`. Required. |
| `max` | int -2032..2032 | `0` | Top of the band. Required. |

Each link clamps its generator's output to 0..1 and maps it into `min`..`max`. Multiple links add, so a biome's total band is the sum of its links' bands. The final column height is clamped to the dimension's usable range.

The generator's raw 0..1 shape and the band are combined through the generator's interpolator, which is also what blends this biome's heights into its neighbours'. Generators sharing an interpolator are averaged together; generators with distinct interpolators add as independent layers. That behaviour and its tuning live in `14 - Generators & Noise.md`.

### Layers (block palettes)

Type: `IrisBiomePaletteLayer`, available as the `biome-palette` snippet.

| Field | Type | Default | What it does |
|-------|------|---------|--------------|
| `palette` | `IrisBlockData[]` | one grass block | The blocks this layer may use. Required, at least one entry. With several entries the choice is made per block by `style`. |
| `minHeight` | int 0-2032 | `1` | Thinnest this layer can be at a column. `0` lets the layer vanish in places. |
| `maxHeight` | int 1-2032 | `1` | Thickest it can be. Iris picks a per-column thickness between min and max using noise. |
| `style` | `IrisGeneratorStyle` | `STATIC` | How multi-block palettes are distributed. `STATIC` is white noise, which reads as speckle; a coherent style like `IRIS` gives patches. |
| `zoom` | double >= 0.0001 | `5` | Horizontal scale for both the thickness noise and the palette noise. Larger makes broader, smoother patches. |
| `slopeCondition` | `IrisSlopeClip` | min `0`, max `10` | When narrowed, this layer is skipped entirely at columns whose slope falls outside the range. Use it for snow caps that avoid cliffs, or gravel that only appears on steep ground. The default range is inert. |

`IrisBlockData` entries:

| Field | Type | Default | What it does |
|-------|------|---------|--------------|
| `block` | string | `"air"` | Block id. Namespaced or bare. Required. |
| `weight` | int 1-1000 | `1` | Duplicates this entry in the palette, so `weight: 3` makes it three times as likely as a `weight: 1` sibling. |
| `data` | map | empty | Block state properties, e.g. `{"waterlogged": true}`. |
| `tileData` | map | empty | Tile-entity data for blocks that carry it. |
| `backup` | `IrisBlockData` | null | Used when `block` does not exist on this Minecraft version. |
| `debug` | boolean | `false` | Prints the resolved block to the console when Iris debug is on. Diagnostic only. |

The stacks:

| Field | What it fills |
|-------|---------------|
| `layers` | The column downward from the terrain surface. First entry is the top. Anything below the stack becomes the dimension's rock palette (or an ore, if an ore generator claims that block). Required; the default is a single grass layer. |
| `seaLayers` | The water column, indexed **downward from the water surface**, not upward from the sea floor. Index 0 sits at `fluidHeight`. Anything the stack does not cover becomes the dimension fluid. This is how you get a layer of ice or a band of murky water on top of an ocean. |
| `caveCeilingLayers` | The underside of carved ceilings, downward from the ceiling. Defaults to one grass layer, which is almost never what you want in a cave — set it explicitly. |
| `slab` | Palette for the half-slabs the post processor adds on single-block steps. Default is an empty palette, meaning no slabs. |
| `wall` | Palette for the vertical faces the post processor paints when a neighbouring column is more than two blocks lower. Default is empty. Set it to stone/andesite to stop cliffs showing dirt. |
| `lockLayers` | When true, the stack repeats as horizontal bands keyed to world height instead of following the surface, giving mesa striping. |
| `lockLayersMax` | Depth cap, in blocks, for locked layers. Default `7`. |

`caveCeilingLayers` reuses the per-layer thickness generators built from `layers`, so it must not have more entries than `layers` does. Give the biome at least as many surface layers as ceiling layers.

Slabs and walls only appear when the dimension has `postProcessing`, `postProcessingSlabs` and `postProcessingWalls` enabled. See `11 - Dimensions.md`.

### Custom biomes (`customDerivitives`)

The JSON key really is `customDerivitives`. The misspelling is baked into the engine field; `customDerivatives` is silently ignored.

Type: `IrisBiomeCustom`, available as the `custom-biome` snippet. Iris compiles these into a datapack and registers them as `<dimensionLoadKey>:<id>`.

When a biome has any custom derivative, that custom biome becomes the visible biome for the column and `derivative` / `biomeScatter` / `biomeSkyScatter` stop driving what players see. `vanillaDerivative` still drives structure eligibility and tag inheritance. With several entries, `biomeStyle` picks between them per position.

| Field | Type | Default | What it does |
|-------|------|---------|--------------|
| `id` | string | `""` | Resource path, lowercased on read. Must be unique in the pack. Required. |
| `category` | `IrisBiomeCustomCategory` | `plains` | Vanilla category written into the biome JSON. Required. |
| `temperature` | double -3..3 | `0.8` | Vanilla temperature: drives snow versus rain, water freezing and some mob behaviour. |
| `humidity` | double -3..3 | `0.4` | Written as vanilla `downfall`. Affects foliage tint and fire spread. |
| `downfallType` | `IrisBiomeCustomPrecipType` | `rain` | `none`, `rain` or `snow`. `none` also clears the `has_precipitation` flag. |
| `spawnRarity` | int 0-20 | `0` | Written straight into `creature_spawn_probability`. Leave at `0` unless you are also supplying `spawns`. |
| `spawns` | `IrisBiomeCustomSpawn[]` | empty | Mob spawn entries grouped by category. Only meaningful together with `spawnRarity`. |
| `tags` | string[] | empty | Extra biome tags, e.g. `minecraft:allows_surface_slime_spawns`. |
| `ambientParticle` | `IrisBiomeCustomParticle` | `null` | Client-rendered ambient particle. No server cost. |
| `skyColor` | hex | `#79a8e1` | Upper sky colour. |
| `fogColor` | hex | `#c0d8e1` | Horizon fog colour. |
| `waterColor` | hex | `#3f76e4` | Water surface tint. |
| `waterFogColor` | hex | `#050533` | Underwater fog tint. |
| `grassColor` | hex | `""` | Forces a grass tint. Empty means "leave it to the category", which is usually what you want unless you are matching a specific look. |
| `foliageColor` | hex | `""` | Same for leaves. Empty means inherit. |

On Minecraft 26.2, sky, fog, water-fog and ambient-particle values are published through the biome environment-attribute registry while water, grass and foliage stay biome effects. The conversion is automatic; the pack fields are unchanged.

Effective tags are your `tags` plus the direct tag membership of the vanilla derivative, deduplicated. Structure tags (`has_structure/*`) are deliberately not inherited, because native structure placement already resolves through the structure derivative and inheriting them would place structures twice.

Custom spawn entry (`IrisBiomeCustomSpawn`):

| Field | Type | Default | What it does |
|-------|------|---------|--------------|
| `type` | entity key | `minecraft:cow` | Entity to spawn. Bare names are namespaced. |
| `minCount` / `maxCount` | int >= 1 | `2` / `5` | Pack size range. |
| `weight` | int 1-1000 | `1` | Relative chance against other entries in the same group. |
| `group` | `IrisBiomeCustomSpawnType` | `MISC` | Vanilla spawn category, which also decides the mob cap the spawn counts against. |

Spawn groups: `MONSTER`, `CREATURE`, `AMBIENT`, `AXOLOTLS`, `UNDERGROUND_WATER_CREATURE`, `WATER_CREATURE`, `WATER_AMBIENT`, `MISC`.

Categories (`IrisBiomeCustomCategory`): `beach`, `desert`, `extreme_hills`, `forest`, `icy`, `jungle`, `mesa`, `mushroom`, `nether`, `none`, `ocean`, `plains`, `river`, `savanna`, `swamp`, `taiga`, `the_end`.

Ambient particle (`IrisBiomeCustomParticle`):

| Field | Default | What it does |
|-------|---------|--------------|
| `particle` | `minecraft:flash` | Particle id, namespaced automatically. |
| `rarity` | `35` (1-10000) | Written as probability `1 / rarity`, so higher means fewer particles. |

Custom biomes are installed by datapack compilation, so a world usually has to be reopened (sometimes the server restarted) before newly added ids resolve. If a custom biome does not appear, check for a leftover `derivative` typo before blaming the datapack.

### Content attached to the biome

| Field | Type | What it does |
|-------|------|--------------|
| `decorators` | `IrisDecorator[]` | Grass, flowers, cactus, kelp and similar surface scatter, bucketed by `partOf` (surface, ceiling, shore line, sea surface, sea floor). See `16 - Surfaces, Decorators & Deposits.md`. |
| `objects` | `IrisObjectPlacement[]` | `.iob` placements. Split at runtime into surface and carving sets by each placement's `carvingSupport`. See `20 - Object Placement.md`. |
| `proceduralObjects` | `IrisProceduralObjects` | Trees, coral, fungi, crystals, ruins and formations generated from parameters. See `17 - Trees, Fungi, Coral, Crystals, Formations, Ruins.md`. |
| `structures` | `IrisStructurePlacement[]` | Jigsaw and native placements evaluated where this biome owns the chunk centre. |
| `floatingChildBiomes` | `IrisFloatingChildBiomes[]` | Floating islands above this biome's columns, drawn using another biome's materials. See below. |
| `mergeFloatingChildBiomes` | boolean | When true every floating entry samples independently and islands can overlap; when false (default) one entry is chosen per column. |
| `deposits` | `IrisDepositGenerator[]` | Blob deposits added on top of regional and dimension deposits. |
| `depositVariants` | `IrisDepositVariant[]` | Y-banded ore remaps. This is the first tier evaluated, ahead of region and dimension; first match in the tier wins. |
| `oreDepositFrequencyMultiplier` | double 0-1 | Scales how many ore veins have their centre in this biome. `0.4` keeps 40% of them. Non-ore deposits are untouched. Use it to make a biome ore-poor without editing the global generators. |
| `oreDepositSizeMultiplier` | double 0.01-16 | Scales the block count of those veins. Use it for a biome with rare-but-huge veins (`frequency` down, `size` up). |
| `ores` | `IrisOreGenerator[]` | Vein generators owned by this biome, each flagged surface or underground. |
| `entitySpawners` | string[] | `IrisSpawner` keys replenished over time while a player is here. |
| `effects` | `IrisEffect[]` | Per-player packet ambience. |
| `loot` | `IrisLootReference` | Loot tables for containers generated here. |
| `blockDrops` | `IrisBlockDrops[]` | Custom drops for blocks broken here. |
| `caveProfile` | `IrisCaveProfile` | Overrides the region's cave profile for this biome. |

Placements are gathered per chunk from the biome at the chunk centre, the cave biome at the same point, the region and the dimension. A surface biome contributes all of its `structures[]`; the cave biome contributes only placements whose resolved anchor is `CAVE_FLOOR`, `CAVE_CEILING`, `CAVE_CENTER` or `CAVE_ANY`. Surface and height-band placements written into cave-biome files are ignored. A placement's own `caveBiomes` list is an additional allowlist rechecked at each candidate anchor. See `15 - Caves & Carving.md` and `21 - Jigsaw Structures.md`.

## Floating child biomes (`IrisFloatingChildBiomes`)

`floatingChildBiomes` builds islands in the air above columns owned by this biome. Each entry names a target biome whose generators, layers, derivative, decorators and objects supply the island's look, while the entry's own fields control size, shape, altitude, rarity and internal water. With `mergeFloatingChildBiomes: false` (the default), `pickerStyle` and `rarity` choose one entry per column; with it true, every entry samples independently and islands may intersect.

Reachability follows region roots, dimension carving biomes, ordinary children, carving replacements, floating targets and floating `carving` references, recursively and deduplicated, so every biome that generation can reach is registered for spawns, placements, structures and lookups. Custom-biome datapack installation still scans the pack's complete authored biome set, not just the reachable ones.

### Target, footprint and altitude

| Field | Default / range | What it does |
|-------|-----------------|--------------|
| `biome` | `""` | Target biome key. Empty, missing, or the parent's own key means reuse the parent. |
| `rarity` | `1` (1-512) | Relative share when several entries compete for a column. Lower is more common. |
| `footprintStyle` | `SIMPLEX` | 2D outline noise. `CELLULAR` gives angular shards, `VASCULAR` gives branching strips, `FRACTAL_FBM_SIMPLEX` gives large irregular blankets. Fracture it for swirled silhouettes. |
| `footprintThreshold` | `0.5` (0-1) | Minimum footprint sample that counts as island. `0.0` is a continuous sky blanket, `0.8` is sparse scattered islands, `1.0` produces nothing. |
| `pickerStyle` | `SIMPLEX` | Chooses which entry owns a column when entries are not merged. Use a large zoom so each entry owns broad coherent regions. |
| `altitudeStyle` | `SIMPLEX` | Varies the island base between the two height bounds. Large zoom keeps one island at one altitude. |
| `minHeightAboveSurface` / `maxHeightAboveSurface` | `160` / `210` (0-2032) | Despite the names, these are absolute world Y bounds for the island base, independent of the terrain below. |
| `minAbsoluteY` | `null` | Optional clamp that pushes the base up so the hanging tail stays above this Y. |
| `maxAbsoluteY` | `null` | Optional clamp that pulls the island top down. |

### Edge, top and underside shape

| Field | Default / range | What it does |
|-------|-----------------|--------------|
| `edgeTaperWidth` | `10` (2-32) | Width in blocks of the rounded transition from the outline to full thickness. Small values give a hard rim, large values a broad domed underside. |
| `edgeTaperExponent` | `1.0` (0.25-4) | Curve of that transition. Below 1 fills the rim out; above 1 keeps it thin. |
| `edgeTaperVariationStyle` | `SIMPLEX` at zoom `0.18` | Varies the taper width coherently without moving the outline. |
| `edgeTaperVariationAmplitude` | `0` (0-8) | How much local widening or narrowing that style applies. `0` disables it. The runtime keeps the resulting width inside 2-32 so rims stay connected. |
| `topShapeMode` | `BIOME` | `BIOME` runs the target biome's own generators, so a mountains target grows real peaks. `NOISE` uses `topShapeStyle` as a heightmap. `FLAT` is a constant slab. |
| `maxTopHeight` | `40` (0-512) | Ceiling on how far the top rises above the base. |
| `topShapeStyle` | `SIMPLEX` | Heightmap used when the mode is `NOISE`. |
| `topShapeAmp` | `1` (0-1) | Scales that noise-driven profile down. |
| `bottomStyle` | `SIMPLEX` | Underside noise. `VASCULAR` gives drippy roots, `FRACTAL_RM_SIMPLEX` crystalline spikes, `PERLIN` smooth bowls. |
| `bottomDepthMin` / `bottomDepthMax` | `4` / `20` (0-512) | Tail depth range below the base. |
| `bottomExponent` | `1` (0.1-8) | Bias on tail depth. Above 1 makes deep tails rare spikes; below 1 makes most of the underside deep. |
| `maxThickness` | `96` (1-512) | Hard cap on total top-to-bottom thickness. |
| `wallWarpStyle` | `null` | Optional 3D noise that offsets the footprint sample per Y layer, so walls meander instead of extruding straight. |
| `wallWarpAmplitude` | `6` (0-64) | Maximum wall displacement. Ignored without `wallWarpStyle`. |

### Materials, fluids and carving

| Field | Default | What it does |
|-------|---------|--------------|
| `bottomPaletteMode` | `DEPTH` | `DEPTH` runs normal top-down layers. `MIRROR_TOP` mirrors the shallow palette onto the underside. `CUSTOM` uses `bottomPalette` near the underside and the target palette near the top. |
| `bottomPalette` | `[]` | Layers used only by `CUSTOM`. |
| `localFluidHeight` | `null` | Fluid surface relative to the island base. Set it to fill dips in the top profile with ponds. `null` means no internal water. |
| `fluidBlock` | `minecraft:water` | Block used for those pools. |
| `carveStyle` | `null` | Direct 3D pocket noise inside the island. |
| `carving` | `""` | Dimension carving-entry id or biome key. Dimension entries resolve first, and their cave profile overrides `carveStyle`. |
| `carveThreshold` | `1` (0-1) | With `carveStyle`, noise above this becomes air (`1` means no carving, `0.55` heavy swiss cheese). With `carving`, it biases the referenced cave profile instead. |

### Decoration and objects

| Field | Default | What it does |
|-------|---------|--------------|
| `inheritDecorators` | `true` | Apply the target biome's decorators to the island top. |
| `inheritObjects` | `true` | Allow the target biome's surface objects on the island top. |
| `objectShrinkFactor` | `1` (0.01-1) | Uniform scale for inherited, extra and free-floating objects. Drop it to about `0.5` so full-size trees do not dwarf a small island. |
| `extraObjects` | `[]` | Extra placements anchored to the island top. |
| `floatingObjects` | `[]` | Placements generated independently in mid-air, forced to floating placement mode. |
| `topObjectMode` | `INHERIT_ONLY` | `INHERIT_ONLY` ignores `topObjectOverrides`; `MERGE` appends them after the inherited set; `REPLACE` uses only the overrides. |
| `topObjectOverrides` | `[]` | Consumed according to `topObjectMode`. |
| `bottomObjectMode` | `INHERIT_ONLY` | `INHERIT_ONLY` places nothing on the underside. `MERGE` and `REPLACE` behave identically because there is no inherited bottom set. |
| `bottomObjectOverrides` | `[]` | Placements flipped 180 degrees around X and set flush against the lowest solid face. Directional blocks (stairs, doors, slabs) will not survive the flip; use logs, leaves, stone, ice or glass. |
| `color` | `null` | Studio visualisation colour. |

```json
{
  "floatingChildBiomes": [{
    "biome": "temperate/plains",
    "rarity": 2,
    "footprintStyle": { "style": "SIMPLEX", "zoom": 0.8 },
    "footprintThreshold": 0.7,
    "minHeightAboveSurface": 160,
    "maxHeightAboveSurface": 210,
    "topShapeMode": "BIOME",
    "bottomDepthMin": 6,
    "bottomDepthMax": 28,
    "objectShrinkFactor": 0.6,
    "inheritDecorators": true,
    "inheritObjects": true
  }]
}
```

## Overworld samples

### Land biome — `biomes/temperate/plains.json`

```json
{
  "name": "Plains",
  "color": "#42A616",
  "rarity": 2,
  "derivative": "minecraft:plains",
  "vanillaDerivative": "minecraft:plains",
  "generators": [{ "min": 4, "max": 10, "generator": "plain" }],
  "biomeStyle": { "style": "SIMPLEX" },
  "wall": { "palette": [{ "block": "minecraft:stone" }, { "block": "minecraft:andesite" }] },
  "layers": [
    { "palette": [{ "block": "minecraft:grass_block" }] },
    { "minHeight": 2, "maxHeight": 2, "palette": [{ "block": "minecraft:dirt" }] },
    { "minHeight": 1, "maxHeight": 3, "palette": [{ "block": "minecraft:dirt" }, { "block": "minecraft:coarse_dirt" }] },
    { "minHeight": 6, "maxHeight": 18, "style": { "style": "STATIC" },
      "palette": [{ "block": "minecraft:dirt" }, { "block": "minecraft:stone" }] }
  ]
}
```

A shallow 4-10 band, four layers ending in a thick speckled dirt/stone blend so the transition to bedrock rock is not a hard line, and a stone/andesite `wall` so cliff faces do not show dirt. The real file also carries `decorators` and `objects`.

### Parent with a child and a custom biome — `biomes/temperate/oak-forest.json`

```json
{
  "name": "Oak Forest",
  "derivative": "minecraft:forest",
  "vanillaDerivative": "minecraft:forest",
  "customDerivitives": [{
    "id": "oak_forest",
    "category": "forest",
    "grassColor": "#77A620",
    "foliageColor": "#64B233"
  }],
  "children": ["temperate/oak-forest-extended"],
  "generators": [
    { "generator": "smooth-dunes", "max": 12, "min": 5 },
    { "generator": "rare-hills", "max": 40, "min": 0 }
  ]
}
```

The custom derivative only changes colours; `derivative` and `vanillaDerivative` stay on `minecraft:forest` so forest structures and forest tags still apply.

### Colour-only custom biome — `biomes/vanilla/sunflower_plains.json` (excerpt)

```json
{
  "customDerivitives": [{
    "category": "plains",
    "id": "sunflower_plains",
    "grassColor": "#91BD59",
    "foliageColor": "#77AB2F",
    "waterColor": "#44AFF5",
    "downfallType": "none"
  }]
}
```

## Minimal biome JSON

```json
{
  "name": "Starter Plains",
  "derivative": "minecraft:plains",
  "vanillaDerivative": "minecraft:plains",
  "generators": [{ "generator": "flat", "min": 96, "max": 96 }],
  "layers": [{ "palette": [{ "block": "minecraft:grass_block" }] }]
}
```

Needs `generators/flat.json` to exist. Everything else in the file has a working default.

## Checklist for a new biome

1. Create `biomes/<path>/<name>.json`. The path is the load key regions will reference, so pick it before wiring anything.
2. Set `name`, `derivative` and `vanillaDerivative`.
3. Add one `generators` link and make sure the referenced generator file exists.
4. Define `layers` from the top down: surface, subsoil, then a blend into stone.
5. Add the key to exactly one region role first: land, sea, shore or cave.
6. Set the dimension's `focus` to the key, validate, open Studio, and confirm surface blocks, terrain Y and the relationship to the water line.
7. Add `wall` if the biome makes cliffs, then decorators, then objects, one group at a time.
8. For variants, create the child file and list it in the parent's `children` — never in a region.
9. For colours, tags or mob spawns, add `customDerivitives` with a unique `id` and `category`, then reopen the world so the datapack installs.
10. Remove `focus` and confirm the biome still appears through ordinary region selection.

## Common mistakes

| Mistake | What you will see |
|---------|-------------------|
| `derivative` left at `minecraft:the_void` | Void colours, no mob spawning, no structure eligibility |
| Generator key that does not resolve | The link silently contributes zero height; terrain flattens instead of erroring |
| Child biome also listed in a region | The child generates as a full-size root, so the nesting disappears |
| Spelling `customDerivatives` | Field ignored entirely; the engine key is `customDerivitives` |
| Sea biome with positive `min`/`max` | It generates above water, then gets replaced by a land biome anyway |
| Sea biome with a non-ocean `vanillaDerivative` | No native ocean structures generate there |
| Empty `palette` on the first layer | No surface block; the rock palette shows through |
| More `caveCeilingLayers` entries than `layers` entries | Ceiling generation fails at that biome |
| Expecting a `type` field on the biome | Role comes from the region list that selected it |
| Expecting `slopeCondition` to thin a layer gradually | Out-of-range columns skip the layer entirely; there is no taper |
| Judging changes in already-generated chunks | Biome and layer edits only apply to new chunks |