Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/VolmitSoftware/Iris/llms.txt

Use this file to discover all available pages before exploring further.

​
What is a Biome?

A biome in Iris defines the local terrain characteristics for a specific area. Unlike Minecraft’s vanilla biomes which only control block types and decorations, Iris biomes define:
  • Terrain shape (height, slopes, noise patterns)
  • Block layers (surface blocks, underground strata)
  • Decorations (flowers, grass, mushrooms)
  • Objects (trees, rocks, structures)
  • Effects (particles, sounds, potion effects)
  • Environmental settings (sky color, fog, water color)

​
Biome Hierarchy

Region
  └─ Biome
      ├─ Layers (Block palettes by height)
      ├─ Generators (Terrain height/shape)
      ├─ Decorators (Surface details)
      ├─ Objects (Trees, rocks, structures)
      └─ Children (Sub-biomes)
Biomes are where most terrain generation happens. They combine noise generators, block layers, and decorations to create the final landscape.

​
Basic Structure

​
Minimal Biome

biomes/grassland.json
{
  "name": "Grassland",
  "layers": [
    {
      "palette": [
        { "block": "grass_block" }
      ]
    },
    {
      "minHeight": 1,
      "maxHeight": 3,
      "palette": [
        { "block": "dirt" }
      ]
    }
  ]
}
​
name
string
required
Human-readable biome name (minimum 2 characters)
​
layers
IrisBiomePaletteLayer[]
Stack of block layers that make up the terrain. Layers descend from the surface.

​
Terrain Generation

​
Height Generators

Generators control the height and shape of terrain: 
{
  "generators": [
    {
      "generator": "plains-terrain",
      "min": 64,
      "max": 78
    }
  ]
}
​
generators
IrisBiomeGeneratorLink[]
List of terrain generators with min/max height constraints. Generators are referenced from generators/ folder.
​
generators[].generator
string
File name of the generator (without .json)
​
generators[].min
integer
Minimum height this generator can produce
​
generators[].max
integer
Maximum height this generator can produce

​
Multiple Generators (Composite Terrain)

Blend multiple noise patterns: 
{
  "generators": [
    {
      "generator": "base-hills",
      "min": 64,
      "max": 90
    },
    {
      "generator": "mountain-peaks",
      "min": 85,
      "max": 140
    }
  ]
}
Iris blends these generators to create varied terrain height.

​
Block Layers

​
Layer Stack

Layers descend from the surface: 
{
  "layers": [
    {
      "palette": [
        { "block": "grass_block" }
      ]
    },
    {
      "minHeight": 2,
      "maxHeight": 4,
      "palette": [
        { "block": "dirt" }
      ]
    },
    {
      "minHeight": 40,
      "maxHeight": 60,
      "palette": [
        { "block": "stone" },
        { "block": "andesite" }
      ],
      "style": {
        "style": "GLOB",
        "zoom": 0.15
      }
    }
  ]
}
​
layers[].palette
BlockData[]
Array of blocks for this layer. Can include multiple blocks for variety.
​
layers[].minHeight
integer
Minimum thickness of this layer in blocks
​
layers[].maxHeight
integer
Maximum thickness of this layer in blocks
​
layers[].style
IrisGeneratorStyle
Noise pattern for varying block selection within the layer

​
Varying Block Palettes

Add variety with weighted blocks: 
{
  "palette": [
    { "block": "stone", "weight": 10 },
    { "block": "andesite", "weight": 1 },
    { "block": "diorite", "weight": 1 }
  ]
}
Higher weights make blocks more common.

​
Decorations and Objects

​
Decorators (Small Details)

{
  "decorators": [
    {
      "chance": 0.1,
      "palette": [
        { "block": "grass" },
        { "block": "tall_grass" }
      ]
    },
    {
      "chance": 0.02,
      "palette": [
        { "block": "poppy" },
        { "block": "dandelion" }
      ]
    }
  ]
}
​
decorators
IrisDecorator[]
Surface decorations placed on top of the terrain
​
decorators[].chance
number
Probability (0.0-1.0) of placing this decorator per surface block

​
Objects (Large Features)

{
  "objects": [
    {
      "chance": 0.008,
      "place": [
        "oak-tree",
        "birch-tree"
      ],
      "mode": "PAINT"
    }
  ]
}
​
objects
IrisObjectPlacement[]
Large structures and objects placed in the biome
​
objects[].chance
number
Spawn chance per chunk
​
objects[].place
string[]
List of object files from objects/ folder
​
objects[].mode
ObjectPlaceMode
Placement mode: PAINT (replace blocks), STILT (on pillars), MAX_HEIGHT (at surface)

​
Sub-Biomes (Children)

​
Creating Variation

{
  "name": "Forest",
  "children": [
    "dense-forest",
    "forest-clearing"
  ],
  "childShrinkage": 3,
  "childStyle": {
    "style": "CELLULAR",
    "zoom": 0.5
  }
}
​
children
string[]
List of child biome files that can spawn within this biome
​
childShrinkage
integer
Higher values = smaller child biome patches
​
childStyle
IrisGeneratorStyle
Noise pattern controlling child biome distribution

​
Environmental Settings

​
Custom Derivatives (Minecraft Biome)

{
  "customDerivitives": [
    {
      "id": "minecraft:plains",
      "foliageColor": "#88CC66",
      "grassColor": "#77BB55"
    }
  ]
}
This maps your Iris biome to a vanilla Minecraft biome with custom colors.

​
Effects (Particles, Sounds, Potions)

{
  "effects": [
    {
      "particleEffect": "CLOUD",
      "particleChance": 0.01,
      "particleOffset": 2.5
    },
    {
      "sound": "AMBIENT_CAVE",
      "soundChance": 0.005,
      "volume": 0.3
    }
  ]
}
​
effects
IrisEffect[]
Ambient particle, sound, and potion effects for this biome

​
Example: Complete Biome

biomes/mountain-peaks.json
{
  "name": "Mountain Peaks",
  "rarity": 1,
  
  "generators": [
    {
      "generator": "mountain-height",
      "min": 100,
      "max": 180
    }
  ],
  
  "layers": [
    {
      "palette": [
        { "block": "snow_block" }
      ]
    },
    {
      "minHeight": 1,
      "maxHeight": 2,
      "palette": [
        { "block": "stone" }
      ]
    },
    {
      "minHeight": 50,
      "maxHeight": 80,
      "palette": [
        { "block": "stone", "weight": 8 },
        { "block": "andesite", "weight": 1 },
        { "block": "gravel", "weight": 1 }
      ],
      "style": {
        "style": "GLOB",
        "zoom": 0.12
      }
    }
  ],
  
  "decorators": [
    {
      "chance": 0.05,
      "palette": [
        { "block": "snow" }
      ]
    }
  ],
  
  "objects": [
    {
      "chance": 0.002,
      "place": ["ice-spikes"],
      "mode": "PAINT"
    }
  ],
  
  "children": [
    "snow-cap",
    "rocky-cliff"
  ],
  "childShrinkage": 4,
  
  "customDerivitives": [
    {
      "id": "minecraft:snowy_plains",
      "temperature": 0.0
    }
  ]
}

​
Best Practices

  • Use 2-5 layers for most biomes (surface, subsurface, deep)
  • Add variety with weighted block palettes
  • Limit decorator chance to 0.01-0.2 to avoid lag
  • Test object density before finalizing
Too many decorators or objects can severely impact generation performance. Start conservative and increase gradually.

​
Next Steps

Generators

Learn about terrain height generation

Create a Biome

Step-by-step biome creation guide

Build docs developers (and LLMs) love

Get started for freeTalk to us