A region selects the biomes and content allowed in part of a dimension. Files live at regions/<loadKey>.json. Each region defines land, sea, shore, and cave biome lists, their zoom levels, and the shoreline band width.

The dimension's regions list selects which regions can appear. Each region supplies separate landBiomes, seaBiomes, shoreBiomes, and caveBiomes lists.

Set the broad land and sea distribution with the dimension's continentalStyle and landChance. Regions supply the biome choices; include sea and shore biomes wherever terrain can reach the water line. See Land-only dimensions before leaving those lists empty.

Region zooms multiply the dimension zooms. For example, landBiomeZoom: 3.5 makes land biome patches in that region roughly 3.5 times wider than at the dimension's base scale.

rarity controls relative frequency: a candidate with rarity: 2 has half the selection weight of one with rarity: 1; rarity: 10 has a tenth. Region rarity is capped at 128, and biome rarity at 512. These ratios do not guarantee an exact percentage of the map.

Array order affects adjacency. Nearby entries tend to become neighbors in the world, so reordering a list can change biome borders. Distribution also depends on the dimension's regionStyle and regionZoom. Use /iris studio regions to measure each region's share of a sample area.

The dimension fluidHeight and the region's shore-height settings determine where sea, shore, and land biomes appear along the coast.

shoreHeightMin and shoreHeightMax set the vertical beach band. shoreHeightZoom controls how quickly its height varies along the coast: lower values give frequent changes, while higher values give longer, more uniform stretches.

Flat coastlines with a high shoreHeightMax produce wide beaches. Steep cliffs cross the same height band quickly, leaving narrow beaches. Set shoreMinimumWidth above zero to widen the band according to the local slope and preserve more beach across steep ground.

Renaming a region, changing landBiomeZoom, or changing the number of land biomes can also alter the shore-height pattern.

Start with a valid dimension and an existing root biome.

1. Create regions/tutorial.json:

{
  "name": "Tutorial",
  "rarity": 1,
  "color": "#9BEE61",
  "landBiomes": ["starter"],
  "seaBiomes": [],
  "shoreBiomes": []
}

Replace starter with the exact load key of your existing biome. List only root biomes, never a biome that is already another biome's child.

2. Add "tutorial" to the dimension regions array.
3. Set "focusRegion": "tutorial" on the dimension. This selects that region for every column while you edit.
4. Validate the pack. Then open Studio on seed 1337 (/iris studio open <pack> seed=1337 on Bukkit or /iris studio open <pack> 1337 on mod loaders).
5. Fly into freshly generated chunks and run /iris what region.

Success: it reports tutorial everywhere. /iris what biome reports starter. Validation logs no unresolved keys.

6. Remove focusRegion. Reopen Studio. Travel until tutorial shows up on its own. Now add sea and shore biomes together, then cave biomes. Validate after each group.

Suppose the tutorial region biomes are too small and choppy. The rest of the dimension is fine.

{
  "name": "Tutorial",
  "rarity": 1,
  "landBiomes": ["starter", "starter-hills"],
  "landBiomeZoom": 3.5
}

Observable result: individual land biome patches in this region become roughly 3.5x wider. Nothing outside the region changes. The dimension biomeZoom still applies on top. The bundled temperate region uses 3.5 for land, 6 for sea and 0.15 for shore. Shores are deliberately zoomed down so beach variants change every few dozen blocks along a coastline instead of running for hundreds of blocks.

Change one zoom at a time. Regenerate a fresh area between comparisons. Zooms do not affect already generated chunks.

{
  "shoreHeightMin": 1,
  "shoreHeightMax": 5.2,
  "shoreHeightZoom": 1.14
}

Observable result: the shore role now claims everything from one block under the water line up to about 5 blocks above it. Gently sloped coasts get much wider sand. If you lower shoreHeightZoom, the beach width varies more rapidly along the coast. If you raise it, you get long, uniform stretches.

For steep coastlines, set shoreMinimumWidth or adjust the terrain slope in the generator.

seaBiomes and shoreBiomes are optional in the schema. Leaving them empty is only safe when no column can ever land at or below fluidHeight. That means every biome in the region uses positive generator min values. The dimension landChance must also keep the continental noise on land. Otherwise the sea or shore role has an empty candidate list at those columns. When a declared land, sea, or shore pool loses every candidate to version content exclusions, the region is excluded from the dimension. Declare compatible alternatives or block fallbacks to keep that region available on older targets.

{
  "name": "Highlands",
  "rarity": 2,
  "landBiomes": ["highlands/plateau"],
  "seaBiomes": [],
  "shoreBiomes": []
}

landBiomes is always required.

Packs without caves, including superflat packs, can omit caveBiomes. This fallback does not enable cave generation or add entries to the cave decoration and structure pools.

List root parents only. Child biomes are declared on their parent via children (see 13 - Biomes). If you list a child here, it competes as a root as well and breaks the nesting you intended. Keys are load keys relative to biomes/. temperate/plains means biomes/temperate/plains.json.

A biome does not declare its own role. The role (LAND, SEA, SHORE, CAVE) comes from which list selected it. The same biome file can appear in more than one list. It then takes a different role in each.

hydrologyPolicy adjusts the water anywhere this region is selected; a biome policy overrides it again. Unset values inherit from the dimension. An explicitly empty shoreBiomes list clears the inherited list.

The drainage, tiers, pond and lake settings are dimension-owned. See 11 - Dimensions, 36 - Hydrology and 36b - Hydrology Policy.

Everything here applies anywhere this region is selected, on top of what the biome contributes.

Deposit precedence across tiers: biome variants, then region variants, then dimension variants. First match wins within each tier.

Path in the bundled pack: packs/overworld/regions/temperate.json.

The file sets no objects, structures, ores, entitySpawners or effects. All of that lives on the biomes.

Region keys listed by the bundled overworld dimension: frozen, hot, terralost, mushroom, forests, tundra, magnetics, temperate, estranged, tropical, swamp, prismatics.

Region objects obey each placement's carvingSupport; cave-only placements do not appear on the surface. Structure placements from the dimension, region, surface biome, and cave biome can all apply to a chunk. The region and biome choices use the chunk center; cave biomes contribute only structures with cave anchors.

Region changes affect newly generated chunks. Use fresh terrain when comparing rarity, zoom, or content settings.

Related:

• 05 - Concepts & Pack Layout
• 11 - Dimensions
• 13 - Biomes
• 14 - Generators & Noise
• 15 - Caves & Carving
• 16 - Surfaces, Decorators & Deposits
• 20 - Object Placement