Skip to main content

​
What is an Object?

An object in Iris is a pre-built 3D structure that can be placed during world generation. Objects range from simple features like single trees to complex multi-block structures like buildings or ruins. Unlike decorators (which place single blocks), objects are:
  • Multi-block structures saved as .iob files
  • Rotatable and transformable
  • Can contain tile entities (chests, spawners, signs)
  • Support advanced features (loot tables, entity spawning, clipping)

​
Object Types

​
Natural Objects

  • Trees (oak, birch, custom species)
  • Rocks and boulders
  • Fallen logs
  • Vegetation clusters

​
Structural Objects

  • Buildings and ruins
  • Temples and shrines
  • Bridges and pathways
  • Decorative features

​
Technical Objects

  • Ore veins (custom ore placement)
  • Cave features
  • Underground structures
Objects are created in Studio Mode using the /iris object commands, then saved as .iob files in the objects/ folder.

​
Object File Structure

Objects are stored as .iob (Iris Object Binary) files: 
packs/
  my-dimension/
    objects/
      trees/
        oak-tree.iob
        birch-tree.iob
      rocks/
        boulder-small.iob
        boulder-large.iob
      structures/
        ruin-1.iob
Each .iob file contains:
  • Block data (position, type, properties)
  • Tile entity data (chest contents, spawner settings)
  • Metadata (size, center point)

​
Object Configuration

While .iob files store the structure, JSON files configure how they’re placed:
objects/oak-tree.json
{
  "name": "Oak Tree",
  "file": "trees/oak-tree",
  "height": 12,
  "width": 7,
  "centerX": 3,
  "centerZ": 3
}
​
name
string
required
Human-readable object name
​
file
string
Path to the .iob file (relative to objects/ folder, without extension)
​
height
integer
Object height in blocks
​
width
integer
Object width (X/Z dimensions)
​
centerX
integer
X-offset of the center/origin point
​
centerZ
integer
Z-offset of the center/origin point

​
Placement Configuration

Objects are placed through IrisObjectPlacement in biome files:
biomes/forest.json
{
  "objects": [
    {
      "chance": 0.01,
      "density": 2,
      "place": [
        "oak-tree",
        "birch-tree"
      ],
      "mode": "PAINT",
      "translate": {
        "y": -1
      }
    }
  ]
}

​
Placement Parameters

​
chance
number
Probability (0.0-1.0) of attempting to place this object per chunk
​
density
integer
Number of placement attempts per successful spawn roll
​
place
string[]
List of object files that can be randomly selected
​
mode
ObjectPlaceMode
Placement mode:
  • PAINT: Replace existing blocks
  • OVERLAY: Only place in air
  • STILT: Place on stilts/pillars
  • MAX_HEIGHT: Place at terrain surface
  • FAST_MAX_HEIGHT: Faster surface placement

​
Translation and Rotation

{
  "translate": {
    "x": 0,
    "y": -2,
    "z": 0
  },
  "rotation": {
    "enabled": true,
    "yAxis": {
      "enabled": true,
      "min": 0,
      "max": 360,
      "interval": 90
    }
  }
}
​
translate
IrisObjectTranslate
Offset the object placement in X/Y/Z
​
rotation
IrisObjectRotation
Configure rotation on X/Y/Z axes. interval sets rotation snapping (e.g., 90 = only 0/90/180/270 degrees)

​
Scaling

{
  "scale": {
    "enabled": true,
    "multiplier": {
      "x": 1.0,
      "y": 1.2,
      "z": 1.0
    }
  }
}
​
scale
IrisObjectScale
Stretch or shrink the object. Values less than 1.0 = smaller, greater than 1.0 = larger.

​
Advanced Features

​
Loot Tables

Objects can contain chests with custom loot:
objects/treasure-chest.json
{
  "name": "Treasure Chest",
  "file": "structures/treasure-chest",
  "loot": {
    "mode": "ADD",
    "tables": [
      "treasure-common",
      "treasure-rare"
    ]
  }
}
​
loot.mode
IrisLootMode
REPLACE (clear chest, add loot) or ADD (add to existing)
​
loot.tables
string[]
List of loot table files from loot/ folder

​
Entity Spawning

{
  "entity": {
    "types": [
      "minecraft:zombie",
      "minecraft:skeleton"
    ],
    "interval": 32
  }
}
​
entity.types
string[]
Entity types to spawn near this object
​
entity.interval
integer
Spacing between entity spawns

​
Slope Clipping

Prevent placement on steep terrain: 
{
  "slopeCondition": {
    "minimumSlope": 0.0,
    "maximumSlope": 0.3
  }
}
​
slopeCondition
IrisSlopeClip
Slope constraints (0.0 = flat, 1.0 = vertical)

​
Creating Objects

​
Using Studio Mode

1

Enter Studio Mode

/iris studio create myworld overworld
2

Build Your Structure

Use WorldEdit, building tools, or manual placement to create the structure
3

Save the Object

/iris object save my-tree
This creates objects/my-tree.iob
4

Test Placement

/iris object place my-tree
Set your object’s center point carefully. This determines the rotation pivot and placement origin.

​
Example: Tree Configuration

objects/custom-oak.json
{
  "name": "Custom Oak Tree",
  "file": "trees/custom-oak",
  "height": 15,
  "width": 9,
  "centerX": 4,
  "centerZ": 4,
  
  "rotation": {
    "enabled": true,
    "yAxis": {
      "enabled": true,
      "min": 0,
      "max": 360,
      "interval": 1
    }
  },
  
  "scale": {
    "enabled": true,
    "multiplier": {
      "x": 1.0,
      "y": 1.1,
      "z": 1.0
    }
  },
  
  "slopeCondition": {
    "minimumSlope": 0.0,
    "maximumSlope": 0.2
  }
}
Then place it in a biome:
biomes/oak-forest.json
{
  "objects": [
    {
      "chance": 0.15,
      "density": 3,
      "place": ["custom-oak"],
      "mode": "PAINT",
      "translate": {
        "y": -1
      }
    }
  ]
}

​
Best Practices

  • Keep objects under 32x32x32 blocks for performance
  • Use object variants (create 3-5 versions of trees/rocks)
  • Set appropriate chance values (0.01-0.2 for large objects)
  • Test slope conditions to prevent floating structures
Very large objects (greater than 64x64x64) can cause significant generation lag. Break them into smaller pieces or use jigsaw structures instead.

​
Next Steps

Object Creation Guide

Learn to create custom objects

Jigsaw Structures

Advanced procedural structures

Build docs developers (and LLMs) love

Get started for freeTalk to us