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 { "name" : "Grassland" , "layers" : [ { "palette" : [ { "block" : "grass_block" } ] }, { "minHeight" : 1 , "maxHeight" : 3 , "palette" : [ { "block" : "dirt" } ] } ] }
Human-readable biome name (minimum 2 characters)
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 } ] }
List of terrain generators with min/max height constraints. Generators are referenced from generators/ folder.
File name of the generator (without .json)
Minimum height this generator can produce
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 } } ] }
Array of blocks for this layer. Can include multiple blocks for variety.
Minimum thickness of this layer in blocks
Maximum thickness of this layer in blocks
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" } ] } ] }
Surface decorations placed on top of the terrain
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" } ] }
Large structures and objects placed in the biome
List of object files from objects/ folder
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 } }
List of child biome files that can spawn within this biome
Higher values = smaller child biome patches
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 } ] }
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