Skip to main content
Regions are organizational containers for biomes. They group related biomes together and control how they’re distributed across your dimension.

​
What is a Region?

A region represents a large-scale area type in your dimension. Think of regions as climate zones or geographical areas that contain related biomes:
  • A “Temperate” region might contain plains, forests, and rivers
  • A “Frozen” region might contain tundra, ice spikes, and frozen oceans
  • A “Tropical” region might contain jungles, beaches, and warm oceans

​
Creating Your First Region

1

Create the JSON file

Create a file in regions/ folder:
{
  "name": "Temperate Zone",
  "landBiomes": ["plains", "forest", "birch-forest"],
  "seaBiomes": ["ocean"],
  "shoreBiomes": ["beach"]
}
2

Add to dimension

Reference your region in a dimension’s regions array:
{
  "regions": ["temperate-zone", "frozen-zone"]
}
3

Test the region

Generate a world and explore to find your region’s biomes.

​
Essential Configuration

​
Basic Properties

FieldTypeDescription
nameStringHuman-readable region name (required)
rarityIntegerWeight for region selection (1-128, default: 1)
colorStringHex color for visualization (e.g., “#2ecc71”)

​
Biome Lists

Regions organize biomes by type: 
{
  "landBiomes": ["plains", "forest", "hills"],
  "seaBiomes": ["ocean", "deep-ocean"],
  "shoreBiomes": ["beach", "stone-beach"],
  "caveBiomes": ["cave", "lush-cave"]
}
  • landBiomes: Above sea level (required)
  • seaBiomes: Below sea level (required)
  • shoreBiomes: Transition between land/sea (required)
  • caveBiomes: Underground areas (optional)

​
Biome Distribution

Control how biomes are sized within the region: 
{
  "landBiomeZoom": 1.5,
  "seaBiomeZoom": 2.0,
  "shoreBiomeZoom": 0.5,
  "caveBiomeZoom": 1.0
}
Higher zoom = larger biomes of that type.

​
Shore Height

Define the transition zone between land and sea: 
{
  "shoreHeightMin": 1.2,
  "shoreHeightMax": 3.2,
  "shoreHeightZoom": 3.14
}
  • shoreHeightMin: Minimum height for shore biomes
  • shoreHeightMax: Maximum height for shore biomes
  • shoreHeightZoom: Variation in shore height

​
Advanced Features

​
Regional Objects

Place structures across the entire region: 
{
  "objects": [
    {
      "place": ["oak-tree", "birch-tree"],
      "chance": 0.001,
      "density": 1,
      "mode": "MAX_HEIGHT"
    },
    {
      "place": ["boulder"],
      "chance": 0.0005,
      "density": 1
    }
  ]
}
These objects can spawn anywhere in the region, across all biomes.

​
Carving

Region-level cave configuration: 
{
  "carving": {
    "enabled": true,
    "caveStyle": "NORMAL",
    "caveFrequency": 0.5
  }
}

​
Fluid Bodies

Regional rivers and lakes: 
{
  "fluidBodies": {
    "rivers": true,
    "riverStyle": {
      "style": "VASCULAR_THIN",
      "zoom": 7.77
    },
    "lakes": true,
    "lakeStyle": {
      "style": "CELLULAR_IRIS_THICK",
      "zoom": 1.0
    },
    "lakeChance": 0.15
  }
}
  • riverStyle: How rivers are shaped and distributed
  • lakeStyle: How lakes are shaped and distributed

​
Regional Deposits

Ore deposits that span the region: 
{
  "deposits": [
    {
      "type": "VEIN",
      "material": "coal_ore",
      "minHeight": 0,
      "maxHeight": 128,
      "rarity": 50,
      "size": 17
    }
  ]
}

​
Regional Ores

{
  "ores": [
    {
      "ore": "iron_ore",
      "minHeight": -64,
      "maxHeight": 320,
      "chance": 0.5,
      "size": 9
    }
  ]
}

​
Entity Spawning

Region-wide entity spawners: 
{
  "entitySpawners": ["passive-mobs", "common-hostiles"]
}

​
Effects

Ambient effects for the entire region: 
{
  "effects": [
    {
      "particleEffect": "SNOWFLAKE",
      "particleCount": 1,
      "interval": 5,
      "chance": 0.1
    }
  ]
}

​
Loot Tables

{
  "loot": {
    "tables": ["regional-treasures", "common-loot"]
  }
}

​
Block Drops

{
  "blockDrops": [
    {
      "block": "stone",
      "drops": [
        {
          "item": "flint",
          "chance": 0.1
        }
      ]
    }
  ]
}

​
Jigsaw Structures

{
  "jigsawStructures": [
    {
      "structure": "village_plains",
      "rarity": 512,
      "separation": 16
    }
  ]
}

​
Example Regions

​
Temperate Region

{
  "name": "Temperate Lands",
  "rarity": 1,
  "landBiomes": [
    "plains",
    "forest",
    "birch-forest",
    "flower-forest"
  ],
  "seaBiomes": [
    "ocean",
    "cold-ocean"
  ],
  "shoreBiomes": [
    "beach"
  ],
  "landBiomeZoom": 1.0,
  "seaBiomeZoom": 1.5,
  "shoreBiomeZoom": 0.8,
  "shoreHeightMin": 1.0,
  "shoreHeightMax": 3.5,
  "fluidBodies": {
    "rivers": true,
    "lakes": true
  }
}

​
Frozen Wasteland

{
  "name": "Frozen Wastes",
  "rarity": 2,
  "landBiomes": [
    "snowy-tundra",
    "ice-spikes",
    "snowy-taiga"
  ],
  "seaBiomes": [
    "frozen-ocean",
    "deep-frozen-ocean"
  ],
  "shoreBiomes": [
    "snowy-beach"
  ],
  "landBiomeZoom": 1.2,
  "effects": [
    {
      "particleEffect": "SNOWFLAKE",
      "particleCount": 3,
      "interval": 10
    }
  ],
  "deposits": [
    {
      "type": "CLUSTER",
      "material": "packed_ice",
      "rarity": 30
    }
  ]
}

​
Desert Region

{
  "name": "Arid Sands",
  "rarity": 3,
  "landBiomes": [
    "desert",
    "desert-hills",
    "badlands"
  ],
  "seaBiomes": [
    "warm-ocean"
  ],
  "shoreBiomes": [
    "desert"
  ],
  "landBiomeZoom": 1.8,
  "fluidBodies": {
    "rivers": false,
    "lakes": true,
    "lakeChance": 0.05
  },
  "objects": [
    {
      "place": ["desert-well"],
      "chance": 0.0001,
      "density": 1
    }
  ]
}

​
Tropical Region

{
  "name": "Tropical Paradise",
  "rarity": 2,
  "landBiomes": [
    "jungle",
    "bamboo-jungle",
    "jungle-edge"
  ],
  "seaBiomes": [
    "warm-ocean",
    "lukewarm-ocean"
  ],
  "shoreBiomes": [
    "tropical-beach"
  ],
  "caveBiomes": [
    "lush-cave"
  ],
  "landBiomeZoom": 1.3,
  "caveBiomeZoom": 2.0,
  "objects": [
    {
      "place": ["jungle-temple"],
      "chance": 0.00005,
      "density": 1,
      "mode": "PAINT"
    }
  ],
  "entitySpawners": [
    "tropical-animals",
    "jungle-hostiles"
  ]
}

​
Volcanic Region

{
  "name": "Volcanic Lands",
  "rarity": 4,
  "landBiomes": [
    "volcanic-plains",
    "lava-fields",
    "basalt-delta"
  ],
  "seaBiomes": [
    "lava-ocean"
  ],
  "shoreBiomes": [
    "obsidian-beach"
  ],
  "landBiomeZoom": 1.0,
  "deposits": [
    {
      "type": "BLOB",
      "material": "magma_block",
      "rarity": 20,
      "size": 33
    }
  ],
  "effects": [
    {
      "particleEffect": "FLAME",
      "particleCount": 2,
      "interval": 8,
      "chance": 0.05
    },
    {
      "particleEffect": "LAVA",
      "particleCount": 1,
      "interval": 15,
      "chance": 0.03
    }
  ]
}

​
Region Strategy

​
Climate-Based Regions

Organize by temperature/climate:
  • Frozen: Tundra, ice plains, frozen oceans
  • Cold: Taiga, mountains, cold oceans
  • Temperate: Plains, forests, rivers
  • Warm: Savanna, badlands, warm oceans
  • Hot: Desert, mesa, dry biomes

​
Terrain-Based Regions

Organize by landscape type:
  • Flatlands: Plains, grasslands
  • Highlands: Mountains, hills, plateaus
  • Wetlands: Swamps, marshes, deltas
  • Oceans: Various ocean depths

​
Theme-Based Regions

Organize by aesthetic:
  • Magical Forest: Enchanted woods, fairy rings
  • Corrupted Lands: Withered biomes, dead forests
  • Crystal Caves: Geode formations, mineral biomes
Start with 3-5 regions. Too many makes worlds feel repetitive, too few limits variety. Balance is key.
Yes, you must define landBiomes, seaBiomes, and shoreBiomes. Even if your region is all land, include at least one biome in each category.
Regional objects can spawn across all biomes in the region. Biome objects only spawn in that specific biome.
No, Iris selects one region at a time for each area. Use rarity to control how often each region appears.
Higher rarity makes the region less common. A region with rarity 3 appears 3x less often than one with rarity 1.

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us