A biome or region objects[] entry distributes objects over terrain. A dimension staticObjects[] entry places one saved object at an exact world position with fixed rotation, scale, and block edits. Building the objects themselves is 19 - Objects. Multi-piece assemblies are 21 - Jigsaw Structures.

Use dimension staticObjects for a landmark, spawn building, or other object that must generate at a particular position. Prerequisites: the saved .iob file and a Studio or disposable world whose target chunks have not generated.

1. Save the object as, for example, objects/landmarks/tower.iob.
2. Add this entry to dimensions/<dimension>.json:

{
  "staticObjects": [
    {
      "object": "landmarks/tower",
      "position": { "x": 100, "y": 100, "z": -100 },
      "rotation": { "y": 90 },
      "scale": 1,
      "edit": [
        {
          "find": [{ "block": "minecraft:oak_planks" }],
          "replace": { "palette": [{ "block": "minecraft:stone_bricks" }] }
        }
      ]
    }
  ]
}

3. Validate with /iris pack validate pack=<pack> on Bukkit or /iris pack validate <pack> on modded, then open Studio or create a test world.
4. Visit world coordinates 100 100 -100. That coordinate is the object's saved origin, usually its center, rather than its bottom or a terrain sample. Check the footprint on both sides of any chunk boundary.

Static objects generate after terrain and decoration, regardless of biome, slope, water, caves, density, or chance, and later native structures cannot overwrite them. Entries apply in array order and the later entry wins where they overlap. Saved air writes air; unsaved space stays unchanged unless bore or smartBore fills it. This can replace terrain, including the bedrock layer.

Rotation uses fixed degrees on x, y, and z, all zero by default. Negative and fractional angles work, but angles other than multiples of 90 round onto the block grid and can create holes or merge voxels. Saved block-entity data accompanies its transformed blocks; edits apply before rotation, leave the source .iob unchanged, and changing a block's material discards incompatible block-entity data. A non-solid directional block that cannot represent its rotated orientation is skipped along with its tile data; the rest of the object still places.

Missing objects and invalid settings are errors. The origin and the full transformed object must fit inside the dimension's build height; an overflowing object is rejected outright rather than placed as a clipped fragment.

These settings affect newly generated chunks only. They do not repair objects players break, paste into existing chunks, or rewrite existing buildings after a reload — test in fresh chunks or a disposable world. See 05 - Concepts & Pack Layout.

Prerequisites: a saved object such as objects/tutorial/lookout.iob, a biome or region the target dimension actually uses, and a Studio or disposable test world. Placements only affect chunks generated after the JSON existed. Every check below needs fresh terrain.

Merge this into one focused biome, keeping the biome other fields:

{
  "objects": [
    {
      "place": ["tutorial/lookout"],
      "chance": 1,
      "density": 1,
      "mode": "CENTER_HEIGHT",
      "rotation": { "enabled": false }
    }
  ]
}

1. Paste the object by hand first: /iris object paste tutorial/lookout. If the geometry or the origin is wrong, fix the object before you touch placement JSON.
2. Validate the pack: /iris pack validate pack=<pack> on Bukkit, /iris pack validate <pack> on a modded loader.
3. Open or hotload Studio and fly into fresh chunks whose center column uses the edited biome. At chance: 1 you get one in nearly every such chunk.
4. Confirm ownership: run /iris find object tutorial/lookout, or get /iris object dust and right-click a placed block. Iris names the placement that owns that block.
5. Pick the terrain mode that fixes what you see. Use PAINT for ground-hugging clutter. Use a stilt mode for support over uneven ground. Use CEILING_HANG for cave roofs. Use a VACUUM mode to pull the terrain up to a flat base.
6. Adjust chance and density to set how often the object appears.

objects[] exists on exactly two resource types:

• Biome (biomes/**.json): wherever that biome generates.
• Region (regions/**.json): every biome in the region.

Dimensions use staticObjects[] for fixed-coordinate placements, as described above. Random objects[] entries belong only to biomes and regions. Dimensions also carry two knobs that tighten every random placement underneath them (requireObjectSurfaceSupport, objectSurfaceSupportBuffer, section 4) and two that gate the inverted upper dimension (upperDimensionObjects, upperObjectsForcePlace).

Per chunk, Iris samples the biome and region once at the chunk center (block 8,8). It then walks four lists in this fixed order: biome surface, biome cave, region surface, region cave. Every entry rolls independently. A biome entry and a region entry can both fire in the same chunk. A biome that only clips the corner of a chunk contributes nothing there. The center biome objects can spill a few blocks into its neighbors.

A whole placement can be replaced by a snippet reference. "objects": ["snippet/object-placer/my-camp"] loads snippet/object-placer/my-camp.json.

Minimal entry:

{
  "objects": [
    {
      "place": ["clutter/boulder1"],
      "chance": 0.05
    }
  ]
}

place entries are object keys: the path under objects/ without .iob.

Two numbers do the work. chance decides whether the entry runs at all in this chunk. density decides how many stamps it then attempts.

{
  "place": ["clutter/boulder1", "clutter/boulder2"],
  "chance": 0.05,
  "density": 3
}

Roughly chance x density objects per chunk, before rejections. chance: 0.002 is about one chunk in five hundred.

Each of the density attempts independently picks a random object out of place and a random column inside the chunk. It then runs every gate in sections 3 to 5. Density is a budget of tries, not a guarantee of placements.

place is an unweighted, uniform pick. To bias one object, list its key more than once or split the entry in two. A key that does not resolve costs the attempt and logs Couldn't find Object: <key> once per lookup.

Surface entries add uniform +/- 0.005 jitter to chance before rolling. Cave entries roll the raw value. Two consequences, each worth about one chunk in eight hundred: chance: 1 occasionally fails, and chance: 0 occasionally succeeds. Omit an entry to disable it. Do not set it to zero.

densityStyle replaces density with a noise-driven count, so density varies across the world instead of being flat:

{
  "densityStyle": { "min": 1, "max": 4, "style": { "style": "IRIS_THICK", "zoom": 8 } }
}

Always set min and max. The class defaults are 16 and 32. A bare "densityStyle": {} would ask for 16 to 32 attempts in every chunk that passes the chance roll. /iris pack validate rejects a densityStyle that omits both. It warns when only one is set.

By default a placement is surface-only, unlimited in height, unlimited in slope, and refuses to sit over a cave mouth. Each field below narrows one of those.

Surface or cave. carvingSupport sorts the entry into the surface list, the cave list, or both.

{ "carvingSupport": "CARVING_ONLY", "caveAnchorMode": "FLOOR" }

SURFACE_ONLY (the default) rejects any anchor in carved space. CARVING_ONLY requires carved space at the anchor or within three blocks below it, and hunts for an anchor Y inside the cave column instead of using the terrain surface. A biome-owned cave placement accepts only cells owned by that exact cave biome; a region-owned one spans every cave biome in the region. Unless underwater: true opts into fluid anchors, the anchor must be dry carved air above the dimension cave-lava height. ANYWHERE sits in both lists, so it rolls chance twice per chunk, once for each pass. A cave pass resolves its biome by sampling 48, 80, and 112 blocks down and taking the deepest sample that differs from the surface biome.

caveAnchorMode picks which carved cells count. FLOOR needs solid support below. CEILING needs solid above. CENTER needs neither. ANY takes anything carved. PROFILE_DEFAULT defers to the cave profile (15 - Caves & Carving). CEILING_HANG overrides this to CEILING regardless of what you wrote. Later placement retains the underlying cave-fluid boundaries used to select anchors. Authored subterrain floors, shelves, rims, seals and pillars are protected, as are reserved passage cells. A placement touching those protected cells is rejected even when another cave crosses the room.

Height band. clamp rejects placements whose resolved top or bottom leaves the band.

{ "clamp": { "minimumHeight": 40, "maximumHeight": 225 } }

These are engine-internal Y values: 0 to (dimension height), not world Y. In a -64..320 dimension, world Y 0 is internal Y 64.

Slope. slopeCondition gates on the terrain slope sampled around the anchor column.

{ "slopeCondition": { "minimumSlope": 0, "maximumSlope": 2 } }

The default (0 to 10) is treated as "no condition" and skips the check entirely. maximumSlope: 2 keeps buildings off hillsides. Going below about 1 excludes nearly all natural terrain. rotateTowardsSlope: true finds whichever of the four footprint edges sits lowest. It rotates the object to face that way in 90 degree steps. It adds the yAxis min. It discards yAxis max and interval.

Neighbors. forbiddenCollisions lists object keys this object refuses to intersect. If any block of an already-placed object with that key falls inside this object transformed bounding box, the attempt is dropped. Rotation, rotated translation, warp reach, ceiling inversion, and random Y translation are included. allowedCollisions names exceptions that win over the forbidden list. Both are empty by default. The check only runs when at least one of them is non-empty.

Overlapping surface and cave objects on the main terrain use a repeatable placement order for the same pack and seed, including parallel chunk generation. Empty collision lists permit overlaps without making their result depend on which chunk generates first.

Overrides. forcePlace: true (JSON also accepts "force") skips the usual placement gates. Those gates are the slope check, the carving-anchor check, surface support, underwater rejection, fluid-height and cave-height checks, clamp, the bedrock guard, and the collision lists. It does not skip the native-structure veto or the automatic surface-river veto. An object whose blocks would land inside a vanilla or datapack structure piece is always rejected, forced or not.

Iris refuses surface objects that roof over, bridge, or overhang a carved opening. It takes the object lowest solid non-foliage layer and rasterizes those columns. It dilates the stencil by surfaceSupportBuffer. Every column in the result must have surfaceSupportDepth blocks of un-carved, surface-solid ground. A failure drops the placement with no log line at all. That makes it the usual cause of "my object never appears" near caves, canyon rims, and ravines.

Natural scatter also rejects a surface placement whose support columns intersect accepted river water or lava. forcePlace, underwater, onwater, and requireSurfaceSupport: false do not bypass that river exclusion; only an explicit-Y call such as /iris object paste can build in a river.

{ "requireSurfaceSupport": true, "surfaceSupportBuffer": 2, "surfaceSupportDepth": 2 }

The dimension acts as a floor, not a ceiling. The effective buffer is max(placement, dimension) and the guard is on only if both the placement and the dimension ask for it. A dimension can therefore widen the ring or force the guard on pack-wide. It can never loosen it. surfaceSupportDepth is not merged. The placement value is used as written.

The check is skipped entirely for forcePlace, fromBottom, mode: FLOATING, mode: STRUCTURE_PIECE, underwater, onwater, cave-anchored placements, and requireSurfaceSupport: false.

Loosen in this order, stopping as soon as the object appears: surfaceSupportBuffer: 0, then surfaceSupportDepth: 1, then requireSurfaceSupport: false, then force: true, and only then the dimension-wide switch.

A second guard rejects surface-anchored placements that resolve to y <= 1 in a bedrock dimension. That one does log, throttled to one line per object and mode every five seconds: Implausible object placement rejected.

mode decides how the object Y is chosen and whether the terrain moves to meet it. The default, CENTER_HEIGHT, takes a single height sample at the anchor column and uses it for the whole object. Cheap, and fine for anything small or anything on flat ground.

Height sampling. These four modes only change which sample wins.

{ "mode": "MAX_HEIGHT" }

MAX_HEIGHT samples every column in the transformed footprint and takes the highest: nothing gets buried, but the object floats off cliffs. MIN_HEIGHT takes the lowest: nothing overhangs, but slopes swallow it. The FAST_ variants sample representative edge points instead of the full footprint. PAINT follows a connected surface from the anchor, allowing up to four blocks of change per step; beneath an overhang it follows the nearby exposed ledge rather than jumping to the roof, and the patch stops where no nearby surface connects.

Stilts. Stilt modes take a height mode, then repeat the object bottom blocks downward until they hit ground.

{
  "mode": "CENTER_STILT",
  "stiltSettings": { "yMax": 4, "yRand": 1, "overStilt": 1 }
}

STILT is MAX_HEIGHT plus columns. MIN_STILT is MIN_HEIGHT plus columns. CENTER_STILT is CENTER_HEIGHT plus columns. The FAST_ variants sample fewer columns. Use overStilt to extend the legs below the surface. ERODE_STILT tapers the legs like a cone: deepest at the footprint centroid, dropping off toward the edges, with the lower portion randomly broken up.

Occluding blocks and full ice or glass blocks can stilt; containers, block entities, stairs, slabs, and dirt paths cannot, and stiltSettings.exclude adds more material keys to that list. Grass, mycelium, podzol, and dirt-path bottoms are substituted with dirt so you do not get grass columns, and a palette overrides the column material entirely. A column stops as soon as it hits a fluid, so stilts never punch through a lake floor.

ORGANIC_STILT and CEILING_HANG are for caves. ORGANIC_STILT scans down to the first solid block and fills the gap with noise-varied roots. CEILING_HANG flips the object vertically, anchors its top to the roof, and grows the same organic column up into the ceiling. Both read organicMaxScan, organicJitter, and organicScratch.

Terrain shaping. The vacuum modes bend the terrain instead of extending the object.

{
  "mode": "VACUUM_ORGANIC",
  "vacuumSettings": { "radius": 14, "falloff": 2.0, "organicJitter": 4 }
}

They anchor like CENTER_HEIGHT. They then raise or carve every column out to a radius so the surface meets the object lowest placed block. They ease off by falloff (1 is a cone, 2 a parabolic bowl, higher stays flat near the object then drops). Raised columns are filled with the biome rock. Lowered columns are cleared to air. Inside the footprint the carve never eats into the object. VACUUM uses radius 12, VACUUM_HIGH 20, VACUUM_FAST 8 with every other column sampled. VACUUM_ORGANIC jitters the radius per column for a ragged edge. VACUUM_WAVY adds a smooth simplex wave that fades to zero under the object and at the rim.

Two cases where Iris overrides your mode. An object whose key contains imports/ (anything brought in by /iris structure import or /iris studio importvanilla) is forced to FAST_MIN_STILT unless you asked for FLOATING or STRUCTURE_PIECE. And a cave placement left at the default CENTER_HEIGHT takes the active cave profile defaultObjectPlaceMode instead, if the profile sets one. Write any other mode and it is honored as-is.

Special. FLOATING ignores terrain entirely. Y comes from the rotated object center plus translate.y and translate.yRandom. The terrain, water, cave-anchor, and surface-support checks are all skipped. Use it for sky islands and anything that must not fall to the ground. STRUCTURE_PIECE is reserved for native structures; do not use it in objects[].

Fine positioning. translate shifts the object after rotation, so the offsets rotate with it.

{ "translate": { "x": 0, "y": -1, "z": 0, "yRandom": 0 } }

translate.y: -1 seats clutter one block into the ground and is the standard fix for objects riding on top of grass. yRandom adds a random 0..yRandom per placement. A negative value randomizes downward instead.

rotation is on by default, with free Y rotation in 90-degree steps.

{ "rotation": { "enabled": true, "yAxis": { "enabled": true, "min": 0, "max": 270, "interval": 90 } } }

Per axis (xAxis, yAxis, zAxis, each {enabled, min, max, interval}): min == max == 0 means any multiple of interval. min == max at some other value locks the object to that angle. Anything else picks a multiple of interval and clips it into [min, max]. In the free case an interval below 1 is treated as 1 (one-degree steps). In a clipped range always set a real interval. Non-90-degree angles look bad at block resolution. Turn rotation off with "rotation": { "enabled": false }. X and Z rotation are incompatible with bottom: true.

An omitted scale inherits the dimension's allObjectScaleFactor, which defaults to 1. An explicit scale object replaces that default entirely, including { "size": 1 } or {}. Use { "size": 1 } to keep one placement at its saved size when the rest of the pack is scaled.

Jigsaw structure pieces are excluded from allObjectScaleFactor and retain their authored size.

{ "scale": { "size": 1, "minimumScale": 0.75, "maximumScale": 1.25, "variations": 7, "interpolation": "TRILINEAR" } }

size is a fixed multiplier and overrides the range when it is not 1. With size: 1 and a min/max spread, each placement uses one of variations evenly spaced sizes across the range. interpolation only matters when scaling up. NONE gives blocky output. TRILINEAR smooths it. TRICUBIC and TRIHERMITE provide additional smoothing.

heightmap replaces terrain height sampling with a noise generator, so the object seats against a virtual surface. Surface support still samples the real terrain.

Water. A surface placement whose anchor column is submerged is rejected unless you opt in.

{ "underwater": true, "waterloggable": true, "isDolphinTarget": true }

underwater: true places on the terrain floor and ignores the fluid surface. It additionally rejects the placement if the resolved Y is at or above the solved head at that X/Z, so it really is an underwater-only switch. Ordinary columns use the dimension fluid height; an accepted wet hydrology layer uses its exact local head, and a dry footprint exposes no fluid. Structure placements invert this flag: underwater: true allows submerged starts, and false skips underwater columns. See 35 - Vanilla Passthrough. onwater: true places on the fluid surface instead, for boats and docks. waterloggable: true waterlogs any placed block that can be waterlogged and lands in actual water. Authored waterlogged=true states are cleared in dry space or lava, including ceiling-hung placements. underwater implies the same behavior. isDolphinTarget: true combined with underwater marks placed storage chests as buried-treasure points of interest so dolphins swim players to them.

Snow. snow caps the snow layer depth dripped over the top of every column the object writes.

{ "snow": 0.5 }

The value scales to vanilla eight layers. Each column gets a random count from 0 to floor(snow * 7), placed one block above the highest block that the placement wrote in that column. Schematic air and blocks skipped by placement rules do not raise the snow surface. Small values are effectively fixed. snow: 0.1 is always a single layer.

Air pockets and interiors. By default the object only writes its own blocks. Terrain left standing inside a hollow object stays there.

{ "bore": true, "boreExtendMaxY": 4, "boreExtendMinY": 0 }

bore: true clears the object's entire bounding box to air, including its rotation, translation, warp, and inversion. boreExtendMaxY and boreExtendMinY extend that box upward and downward. smartBore: true clears only the enclosed interior, so a house keeps its rooms clear without erasing the trees around it. Debug rendering affects only the current placement.

smartBore applies only to placements that enable it. Other placements of the same object retain the saved interior. Random block edits and snow depths reproduce for the same placement seed and settings, regardless of object loading or chunk generation order.

meld: true inverts the rule. The object only writes where a solid block already exists, which carves the object into terrain rather than adding to it. It is expensive. The placer samples the world per block.

edit rewrites materials at placement time, so one saved object can serve several biomes:

{
  "edit": [
    { "find": [{ "block": "minecraft:oak_planks" }], "replace": { "palette": ["minecraft:spruce_planks"] }, "chance": 1, "exact": false }
  ]
}

A chance: 1 rule whose find matches a block that does not exist on this Minecraft version also rescues the object from the version content gate, because the block is rewritten before it is ever written to the world. See 11. Content unavailable on this Minecraft version.

exact: false matches on material alone. exact: true requires a full block-data match. When the replacement resolves to the same material as the matched block, Iris merges the two block states. It does not overwrite. Facing and other properties survive. A different material replaces outright and clears saved block-entity data unless the replacement supplies its own. chance is rolled once per rule per block.

warp displaces each block X and Z through a noise field, so a rigid object ripples like a flag. The displacement range is +/- multiplier / 2 and is truncated to whole blocks. The default multiplier: 1 gives at most a one-block jitter. Raise multiplier for a warp you can actually see.

{ "warp": { "style": "IRIS_DOUBLE", "zoom": 0.4, "multiplier": 6 } }

Loot. Two arrays attach loot tables to container blocks inside the placed object. Only storage chests receive them.

{
  "loot": [
    { "name": "global-treasure", "filter": [{ "block": "minecraft:chest" }], "exact": false, "weight": 3 },
    { "name": "global-tools", "weight": 1 }
  ],
  "vanillaLoot": [
    { "name": "minecraft:chests/simple_dungeon", "weight": 1 }
  ],
  "overrideGlobalLoot": false
}

loot[].name is a key under the pack loot/ folder. vanillaLoot[].name is a vanilla or datapack loot-table key. For each chest, an exact: true full block-data match wins over a material match, which wins over an entry with no filter at all. Among the survivors one table is picked by weight. overrideGlobalLoot: true makes the placement table the only one, suppressing dimension, region, and biome loot for the containers it matched. An unresolvable name logs Couldn't find loot table <name> and is skipped.

Iris fills storage chests after generation. Separately, a chest saved into the .iob with a vanilla loot table already on it keeps that table (19 - Objects).

Markers. Placements have no entity field. markers[] tags matching blocks with a marker resource. The marker carries the spawners.

{
  "markers": [
    { "mark": [{ "block": "minecraft:mossy_cobblestone" }], "marker": "camp-spawns", "maximumMarkers": 4, "exact": false }
  ]
}

Candidate blocks are shuffled, so which ones get marked varies per placement. maximumMarkers (default 8, hard max 16) caps the count. markers/camp-spawns.json lists the spawner resources. Its emptyAbove (default true) requires two air blocks above the marked block inside the object.

Saplings. When a sapling grows, Iris scans the biome objects[] for placements whose trees[] matches the grown tree type and the sapling square size. It falls back to the region list if the biome had no match. It picks one and stamps it. A single placement can serve both natural generation and sapling override. Procedural tree generation (proceduralObjects) is a separate system. See 17b - Procedural Trees.

Rare surface camp:

{
  "place": ["clutter/camp1"],
  "chance": 0.00175,
  "rotation": { "enabled": true, "yAxis": { "enabled": true, "min": 0, "max": 270, "interval": 90 } }
}

Pine forest, kept off the steep ground and lightly dusted:

{
  "place": ["trees/spruce/pine1", "trees/spruce/pine2", "trees/spruce/pine3"],
  "chance": 0.6,
  "density": 1,
  "slopeCondition": { "maximumSlope": 2 },
  "rotation": { "enabled": true, "yAxis": { "enabled": true, "interval": 90, "min": 0, "max": 270 } },
  "snow": 0.1
}

Ruins on stilts with loot:

{
  "place": ["structures/ruin-small-a", "structures/ruin-small-b"],
  "chance": 0.08,
  "density": 2,
  "mode": "CENTER_STILT",
  "stiltSettings": { "yMax": 4, "yRand": 1, "overStilt": 1 },
  "translate": { "y": -1 },
  "slopeCondition": { "maximumSlope": 3 },
  "loot": [
    { "name": "global-treasure", "filter": [{ "block": "minecraft:chest" }], "weight": 2 },
    { "name": "global-clutter", "weight": 1 }
  ]
}

Cave floor clutter:

{
  "place": ["clutter/stoneclutt4", "clutter/stoneclutt5"],
  "chance": 0.21,
  "density": 6,
  "carvingSupport": "CARVING_ONLY",
  "caveAnchorMode": "PROFILE_DEFAULT",
  "translate": { "y": -1 },
  "bottom": true,
  "force": true,
  "scale": { "size": 0.75 }
}

Ground-hugging mushroom carpet:

{
  "place": ["trees/mushroom/mushclut1", "trees/mushroom/mushclut2"],
  "chance": 0.15,
  "density": 2,
  "mode": "PAINT",
  "translate": { "y": -1 },
  "rotation": { "enabled": true, "yAxis": { "enabled": true, "min": 0, "max": 270, "interval": 90 } }
}

A .iob saved on a newer Minecraft can contain blocks an older server does not have. Iris reads only the object palette header when it builds a placement's pool, checks every key against the live registry, and decides per object per placement. There are no version fields; see 25 - Pack Management for the gate, the startup listing, and /iris pack compat.

The decision is made once when the pool is first built, and again on Studio hotload. An edit rule with chance below 1 does not save an object, because the missing block would still be written on the rolls that fail. exact: true only saves it when the rule actually matches the saved block state. A dropped object is reported once per missing palette key (dropped object <key> at <placement> place[<index>]), so every fallback it would need is visible at once; a kept object produces no finding, and two placements that list the same single object share one report line. The placement itself keeps its position in the owning objects list, so the other placements in that biome or region roll their chances exactly as before.