Skip to main content

​
What is a Dimension?

A dimension in Iris is the top-level configuration that defines an entire world. It serves as the root container for all world generation settings, including:
  • Regional structure and biome organization
  • Height limits and world bounds
  • Default generators and noise configurations
  • Environmental settings (fluids, rock layers, effects)
  • World-specific features (strongholds, caves, structures)
Dimensions in Iris are analogous to Minecraft’s vanilla dimensions (Overworld, Nether, End), but are fully customizable through JSON configuration files.

​
Dimension Hierarchy

Iris uses a hierarchical generation system: 
Dimension (World-level)
  └─ Regions (Large areas)
      └─ Biomes (Local terrain)
          └─ Objects & Decorators (Details)
A dimension defines the “what can spawn where” rules. Regions group biomes by theme, and biomes define the actual terrain.

​
Core Configuration

​
Basic Structure

Every dimension requires at minimum:
dimensions/example.json
{
  "name": "My Custom Dimension",
  "regions": [
    "plains",
    "mountains",
    "desert"
  ]
}

​
Key Fields

​
name
string
required
The human-readable name of this dimension (minimum 2 characters)
​
regions
string[]
required
List of region file names (without .json extension) that can spawn in this dimension
​
logicalHeight
integer
default:"256"
Maximum height for player teleportation (1-2032). Controls the effective world height.
​
dimensionAngleDeg
number
default:"0.0"
Rotation angle in degrees for the dimension coordinate space
​
environment
string
default:"NORMAL"
Bukkit environment type: NORMAL, NETHER, or THE_END

​
World Generation Settings

​
Height Configuration

{
  "minHeight": -64,
  "maxHeight": 320,
  "logicalHeight": 256
}
​
minHeight
integer
default:"0"
Minimum world height. Affects bedrock placement and generation bounds.
​
maxHeight
integer
default:"256"
Maximum world height. Defines the build limit.

​
Rock and Fluid Layers

{
  "rockPalette": {
    "palette": [
      { "block": "stone" },
      { "block": "deepslate" }
    ],
    "style": { "style": "STATIC" }
  },
  "fluidPalette": {
    "palette": [
      { "block": "water" }
    ]
  },
  "fluidHeight": 63
}
​
rockPalette
IrisMaterialPalette
Defines the base rock layer (what fills below terrain). Uses block palettes with noise-based variation.
​
fluidPalette
IrisMaterialPalette
Defines the fluid (typically water or lava) that fills below fluidHeight
​
fluidHeight
integer
default:"63"
The Y-level at which fluid generates (sea level)

​
Environmental Features

​
Caves and Ravines

{
  "caves": ["limestone-caves", "crystal-caves"],
  "ravines": ["deep-ravines"],
  "carving": ["canyon-carving"]
}
​
caves
string[]
List of cave generator files from caves/ folder
​
ravines
string[]
List of ravine generator files from ravines/ folder
​
carving
string[]
Advanced carving generators for custom terrain features

​
Jigsaw Structures

{
  "jigsawStructures": ["villages", "temples"],
  "stronghold": "custom-stronghold"
}
​
jigsawStructures
string[]
List of jigsaw structure files that can spawn in this dimension
​
stronghold
string
Custom jigsaw structure to use for strongholds (replaces vanilla strongholds)

​
Advanced Features

​
Coordinate Manipulation

{
  "coordFractureDistance": 150,
  "coordFractureZoom": 0.02
}
These settings create coordinate “fractures” that warp the terrain, creating more organic borders between biomes.

​
Overlay Dimensions

{
  "overlay": true,
  "vanillaBiomeZoom": 4.0
}
​
overlay
boolean
default:"false"
If true, Iris decorates vanilla terrain instead of generating its own
​
vanillaBiomeZoom
number
Zoom level for vanilla biome sampling (when overlay mode is enabled)

​
Example: Complete Dimension

dimensions/overworld.json
{
  "name": "Custom Overworld",
  "environment": "NORMAL",
  "minHeight": -64,
  "maxHeight": 320,
  "logicalHeight": 256,
  "fluidHeight": 63,
  
  "regions": [
    "temperate",
    "tropical",
    "arctic",
    "mountains"
  ],
  
  "rockPalette": {
    "palette": [
      { "block": "minecraft:stone", "weight": 8 },
      { "block": "minecraft:andesite", "weight": 1 },
      { "block": "minecraft:diorite", "weight": 1 }
    ],
    "style": {
      "style": "GLOB",
      "zoom": 0.2
    }
  },
  
  "fluidPalette": {
    "palette": [
      { "block": "minecraft:water" }
    ]
  },
  
  "caves": ["standard-caves"],
  "ravines": ["deep-ravines"],
  "jigsawStructures": ["village-plains", "temple-desert"],
  
  "coordFractureDistance": 180,
  "coordFractureZoom": 0.015
}

​
Best Practices

  • Start with 3-5 regions for a balanced dimension
  • Keep logicalHeight at or below maxHeight
  • Use coordFracture settings to create natural biome transitions
  • Test cave and ravine density before finalizing
Changing minHeight or maxHeight on existing worlds requires regeneration. These cannot be modified without data loss.

​
Next Steps

Regions

Learn how regions organize biomes

Create a Dimension

Step-by-step dimension creation guide

Build docs developers (and LLMs) love

Get started for freeTalk to us