Skip to main content
Dimensions are the highest level of organization in Iris. They define entire worlds with their own regions, biomes, and generation settings.

​
What is a Dimension?

A dimension represents a complete world generator configuration. Each dimension contains:
  • Multiple regions that define areas of the world
  • Terrain generation settings
  • Biome placement rules
  • Environmental properties (overworld, nether, end)
  • Post-processing and decoration settings

​
Creating Your First Dimension

1

Create the JSON file

Create a new file in dimensions/ folder:
{
  "name": "My Custom Dimension",
  "regions": ["plains-region", "mountains-region"],
  "fluidHeight": 63,
  "dimensionHeight": {
    "min": -64,
    "max": 320
  },
  "mode": {
    "type": "NORMAL"
  }
}
2

Configure regions

Specify which regions your dimension will use in the regions array. These must match existing region files.
3

Test your dimension

Use /iris create <world> <dimension-name> to generate a world with your dimension.

​
Essential Configuration Fields

​
Basic Properties

FieldTypeDescription
nameStringHuman-readable name of the dimension (required)
regionsString[]List of region file names to include (required)
environmentEnumWorld type: NORMAL, NETHER, or THE_END
versionIntegerDimension version for compatibility tracking

​
Height & Terrain

FieldTypeDefaultDescription
dimensionHeightRange-64 to 320Min and max Y coordinates for the dimension
fluidHeightInteger63Sea level / water placement height
logicalHeightInteger256Maximum teleport height
caveLavaHeightInteger8Lava lake height in caves

​
Biome Placement

FieldTypeDefaultDescription
landBiomeStyleStyleCELLULAR_IRIS_DOUBLEHow land biomes are distributed
seaBiomeStyleStyleCELLULAR_IRIS_DOUBLEHow ocean biomes are distributed
shoreBiomeStyleStyleCELLULAR_IRIS_DOUBLEHow shore biomes are distributed
caveBiomeStyleStyleCELLULAR_IRIS_DOUBLEHow cave biomes are distributed
biomeZoomDouble1.0Scale multiplier for biome sizes
landZoomDouble1.0Scale for land mass distribution
seaZoomDouble1.0Scale for ocean distribution
regionZoomDouble1.0Scale for region sizes

​
Advanced Generation

Coordinate Fracturing creates natural-looking swirls and waves: 
{
  "coordFractureDistance": 20,
  "coordFractureZoom": 8,
  "dimensionAngleDeg": 12
}
  • coordFractureDistance (0-8192): Distance that warps push terrain features
  • coordFractureZoom (0.0001-512): Frequency of warping patterns
  • dimensionAngleDeg (0-360): Rotation angle to reduce sharp corners

​
Continental Settings

{
  "landChance": 0.625,
  "continentalStyle": {
    "style": "CELLULAR_IRIS_DOUBLE",
    "zoom": 1.0
  },
  "continentZoom": 1.0
}

​
Post-Processing

FieldTypeDefaultDescription
postProcessingBooleantrueEnable post-processing
postProcessingSlabsBooleantrueAdd slabs for smooth terrain
postProcessingWallsBooleantrueAdd walls on steep slopes
decorateBooleantruePlace decorators

​
Block Palettes

{
  "rockPalette": [
    { "block": "stone", "weight": 10 },
    { "block": "andesite", "weight": 1 }
  ],
  "fluidPalette": [
    { "block": "water" }
  ],
  "rockZoom": 5
}

​
Advanced Features

​
Bedrock Generation

{
  "bedrock": true
}
Set to false to disable bedrock layer.

​
Tree Settings

{
  "treeSettings": {
    "growthMultiplier": 1.0
  }
}

​
Entity Spawning

{
  "entitySpawners": ["passive-animals", "hostile-mobs"],
  "infiniteEnergy": false,
  "maximumEnergy": 1000
}

​
Carving & Caves

{
  "carving": {
    "enabled": true,
    "caveStyle": "NORMAL"
  },
  "fluidBodies": {
    "rivers": true,
    "lakes": true
  }
}

​
Ore Generation

{
  "ores": [
    {
      "ore": "coal_ore",
      "minHeight": 0,
      "maxHeight": 128,
      "chance": 0.5
    }
  ]
}

​
Deposits

{
  "deposits": [
    {
      "type": "VEIN",
      "material": "emerald_ore",
      "rarity": 100
    }
  ]
}

​
Jigsaw Structures

{
  "jigsawStructures": [
    {
      "structure": "village",
      "rarity": 256,
      "separation": 8
    }
  ],
  "jigsawStructureDivisor": 18
}

​
Strongholds

{
  "stronghold": "custom-stronghold",
  "strongholdJumpDistance": 1280,
  "maxStrongholds": 14
}

​
Loot Tables

{
  "loot": {
    "tables": ["dungeon-loot", "treasure-loot"]
  }
}

​
Block Drops

{
  "blockDrops": [
    {
      "block": "stone",
      "drops": [
        {
          "item": "cobblestone",
          "chance": 1.0
        }
      ]
    }
  ]
}

​
Testing & Debug Options

{
  "focus": "test-biome",
  "focusRegion": "test-region",
  "debugChunkCrossSections": false,
  "explodeBiomePalettes": false,
  "studioMode": "NORMAL"
}
  • focus: Force only one biome to generate (testing)
  • focusRegion: Force only one region to generate (testing)
  • debugChunkCrossSections: Visualize chunk boundaries
  • explodeBiomePalettes: Separate palette layers visually

​
Common Configurations

​
Vanilla-like Overworld

{
  "name": "Overworld",
  "environment": "NORMAL",
  "regions": ["plains", "forests", "mountains", "oceans"],
  "dimensionHeight": { "min": -64, "max": 320 },
  "fluidHeight": 63,
  "landChance": 0.625,
  "biomeZoom": 1.0,
  "bedrock": true
}

​
Floating Islands

{
  "name": "Sky Islands",
  "environment": "NORMAL",
  "regions": ["floating-islands"],
  "dimensionHeight": { "min": 0, "max": 256 },
  "fluidHeight": 0,
  "bedrock": false,
  "landChance": 0.3
}

​
Nether-like Dimension

{
  "name": "Infernal Realm",
  "environment": "NETHER",
  "regions": ["nether-wastes", "soul-sand-valley"],
  "dimensionHeight": { "min": 0, "max": 128 },
  "fluidHeight": 32,
  "caveLavaHeight": 31,
  "bedrock": true
}
A dimension is the entire world generator, while a region is a collection of biomes within that dimension. Think of dimensions as continents and regions as countries.
Yes! Create different JSON files for each dimension and use /iris create to generate separate worlds.
Modify the dimensionHeight min and max values. Note that Iris generates internally from 0 to (max - min), then shifts by the min height.
Higher values create larger biomes. A value of 2.0 doubles the biome size, 0.5 halves it.
Set disableExplorerMaps: true if you experience crashes when cartographers generate explorer maps.

​
Next Steps

  • Learn about Regions to organize your biomes
  • Explore Biomes for detailed terrain control
  • Add Objects to place structures

Build docs developers (and LLMs) love

Get started for freeTalk to us