Objects

The things that literally make the world

This page will cover all advanced options for Objects within biome or region files. To see how to create an object and use it, see Understanding Objects

This tutorial will make use of multiple examples to provide you with the best understanding of how different parameters can be used in different scenarios.

Recap of the Basics

In case you forget everything you learned, here is what was shown previously:

{
    "chance": 1,
    "density": 2,
    "place": [
        "trees/oak/generic1",
        "trees/oak/generic2",
        "trees/oak/generic3",
        "trees/oak/generic4"
    ]
}

  • chance - The chance to place this object in this chunk

  • density - How many to place per chunk if the chance is successful.

  • place - An array of objects to place

Easy enough, right? Lets get started then!

First Example

{
    "place": [
        "structures/ruins-greek-temple"
    ],
    "chance": 0.0005,
    "mode": "VACUUM",
    "carvingSupport": "SURFACE_ONLY"
    "translate": {
        "y": -4
    },
    "rotation": {
        "enabled": true,
        "yAxis": {
            "interval": 90,
            "min": 0,
            "max": 360,
            "enabled": true
        }
    },
    "edit": [
        {
            "find": [
                {
                    "block": "gold_block"
                }
            ],
            "replace": {
                "palette": [
                    {
                        "block": "chest",
                        "weight": 1
                    },
                    {
                        "block": "dirt",
                        "weight": 5
                    }
                ]
            },
            "chance": 1
        }
    ]
}

This example places a buried greek temple underground and replaces the gold blocks in it (placeholder chest locations) with either dirt or a chest to fill with loot.

Mode

"mode" is used to define how the object is placed.

Mode

Description

CENTER_HEIGHT (default)

This mode picks a center point (where the center of the object will be) and takes the height. That height is used for the whole object.

MAX_HEIGHT

Samples only 4 points where the object will cover (horizontally) and picks the highest height, that height is then used to place the object. This mode is useful for preventing any part of your object from being buried, though it will often float off of cliffs.

FAST_MAX_HEIGHT

Very similar to MAX_HEIGHT but it uses a slightly different method to make this mode faster to calculate. Best to use this one over MAX_HEIGHT if possible.

MIN_HEIGHT

Samples a lot of points where the object will cover (horizontally) and picks the lowest height, that height is then used to place the object. This mode is useful for preventing any part of your object from overhanging a cliff, though it gets buried a lot

FAST_MIN_HEIGHT

Just like FAST_MAX_HEIGHT, it is similar to MIN_HEIGHT but is faster. Once again, it's best to use this over MIN_HEIGHT if you can.

STILT

Stilt uses MAX_HEIGHT but it repeats the bottom-most block of your object until it hits the surface. This is what vanilla villages use. Use with caution as it is very intensive and should only be done when neccassary.

FAST_STILT

Just like stilting but very inaccurate. Useful for stilting a lot of objects without too much care on accuracy (you can use the over-stilt value to force stilts underground further)

PAINT

Samples the height of the terrain at every x,z position of your object and pushes it down to the surface. It's pretty much like a melt function over the terrain. This is what village paths use to meld the object to the terrain.

VACUUM

Pulls the terrain heightmap up to meet the object's surface. This ensures the terrain will be flat where the object is.

There are more options to combine with mode bellow at Other Placement Options

Carving Support

Where should this object be placed? Supports SURFACE_ONLY, CARVING_ONLY and ANYWHERE, placing on the surface, in caves or anywhere, respectively.

Translate

Translating an object's position changes where it is placed on the terrain. Making this negative (on the Y-axis) will make the object place in to the terrain and making this positive will place it above the terrain.

You can also translate the X and Z if you really want to.

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

yRandom allows you to randomize the output of the translated Y value. This value is always positive, so in the example above, the Y will range from -10 all the way to +2

Rotation

Rotation allows you to randomly rotate your object when it's placed. We recommend always allowing rotation on the Y axis with intervals of 90 degrees to let it placed in all 4 directions.

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

Valid axis are xAxis, yAxis and zAxis. Not specifying an axis will disable it by default

  • enabled - Whether to enable rotation. It can also be enabled/disabled within an individual axis as shown above

  • interval - Within the minimum and maximum range of degrees, what should the angle always be a multiple of. We recommend keeping this to 90.

  • min - The minimum angle to rotate

  • max - The maximum angle to rotate

Edit / Replace

The edit section allows you to edit an object's blocks and replace them with others. You can even use styles to change which blocks are chosen to replace.

"edit": [
    {
        "find": [
            {
                "block": "gold_block"
            }
        ],
        "replace": {
            "palette": [
                {
                    "block": "chest",
                    "weight": 1
                },
                {
                    "block": "dirt",
                    "weight": 5
                }
            ],
            "style": {
                "style": "STATIC"
            },
            "zoom": 1
        },
        "chance": 1,
        "exact": false
    }
]

  • find - A Pallete array of blocks to find to replace

  • chance - The chance a block in the find will be replaced.

  • exact - If this is true, the find pallete must match the block found EXACTLY (so the block data must be the same and not just the material). Defaults to false.

  • replace.pallete - The Pallete array of blocks to replace with.

  • replace.style - The style to replace with. If not provided, STATIC is used.

  • replace.zoom - How zoomed the style should be. Defaults to 1

Loot

We can define what loot to populate this object with when the object is placed. If we don't provide anything, the containers will just be filled from the loot tables provided by the biome/region/dimension

"loot": [
    {
        "name": "global-treasure",
        "exact": false,
        "filter": [
            {
                "block": "chest"
            }
        ],
        "weight": 1
    },
    {
        "name": "global-clutter",
        "filter": [
            {
                "block": "barrel"
            }
        ]
    },
    {
        "name": "trap",
        "filter": [
            {
                "block": "dispenser"
            }
        ]
    }
]

  • name - The name of the loot table to use

  • exact - Whether to match the filter pallete exactly (match block data as well as material)

  • filter - A pallete array of all the blocks to fill. Blocks MUST be a container of some sort (chests, barrels, dispensers, etc)

  • weight - The weight of this entry. If more than one entry are put in the array that have the same filter, higher weights will mean that entry will be picked more.

Scale

Scale allows you to resize an object. It can be scaled up and scaled down and the size can even be randomized. The scaling is done on pack load and the objects are cached, so objects are not scaled when cached, but rather, placed from a cached version of the scaled object.

We suggest you play with scaling using the paste command to figure out what you think looks best.

"scale": {
    "interpolation": "TRILINEAR",
    "maximumScale": 2,
    "minimumScale": 2,
    "variations": 1
}

  • interpolation - The interpolation method. Should be either TRILINEAR, TRICUBIC, TRIHERMITE or NONE. If the names seem familiar, it's because they are the same interpolation methods a lot of image editing software use but in 3D (2D is Bilinear and Bicubic).

  • minimumScale - The minimum size this object will scale to.

  • maximumScale - The maximum size an object will scale to.

  • variantions - If the scale range is randomized (from the range decided by the min/max), how many size variations should we cache in memory. Set this to 1 if you're planning on having a single size scaled object

Trees / Saplings

The option that allows you to regrow this object with saplings!

{
    "chance": 1,
    "density": 2,
    "trees": [{
        "sizes": [{
            "depth": 1, 
            "width": 1
        }], 
        "treeTypes": ["TREE"],
        "anyTree": false,
        "anySize": false
    }],
    "rotation": {
        "yAxis": {
            "min": 0,
            "max": 360,
            "interval": 90,
            "enabled": true
        },
        "enabled": true
    },
    "place": [
        "trees/oak/antioch3",
        "trees/oak/antioch4",
        "trees/oak/antioch5",
        "trees/oak/antioch6",
        "trees/oak/antioch7",
        "trees/oak/antioch8",
        "trees/oak/antioch9",
        "trees/oak/antioch10",
        "trees/oak/antioch11",
        "trees/oak/antioch12",
        "trees/oak/antioch13"
    ]
},

As states, adding a trees parameter allows you to regrow objects (like tree objects) with saplings.

The sizes parameter dictates the formation of saplings. You can put multiple sizes in here, but generally ,you want to keep both depth and width the same. Setting these both to 1 would mean it can be grown from a 1x1 sapling. Following the same logic, setting them both to 2 would mean a user needs to put the saplings in a 2x2 formation to grow this object/tree.

The anySize parameter will bypass any sizes specified when set to true, and will allow the object to be grown from any size sapling.

The anyType follows a similar style and when set to true, will allow the sapling to be grown from any type of sapling.

Types

treeTypes specifies what type of saplings can be used to grow the tree. Or more accurately, it dictates what kind of tree it should override when that tree is grown from a sapling (of the correct specified size)

Tree Type

Description

TREE

Small Oak Trees

BIG_TREE

Large Oak Trees (the ones with branches)

BIRCH

Birch Trees

REDWOOD

Small Spruce Trees

MEGA_REDWOOD

Large (2x2) Spruce Trees

SMALL_JUNGLE

Normal Jungle Trees

JUNGLE

Large (2x2) Jungle Trees

ACACIA

Acacia Trees

DARK_OAK

Dark oak trees (always 2x2)

AZALEA

The new tree type introduced in 1.17 with Lush caves

WARPED_FUNGUS

Warped fungus trees from the nether

CRIMSON_FUNGUS

Crimson fungus trees from the nether

CHORUS_PLANT

End chorus plants

RED_MUSHROOM

A large red mushroom

BROWN_MUSHROOM

A large brown mushroom

There are some types not includes on this list as while they are tree types, they cannot be grown with saplings. These include SWAMP, TALL_BIRCH, TALL_REDWOOD, JUNGLE_BUSH and COCOA_TREE

Other Placement Options

These are other options to do with the object being placed that may come in handy

Bore

"bore": true,
"boreExtendMaxY": 1,
"boreExtendMinY": 1,
"smartBore": true

  • bore - Makes the object place air before it is placed

  • boreExtendMinY - Extends the range of the bore

  • boreExtendMaxY - The same thing but the max the range of the extend bore can be

  • smartBore - Will make Iris try find "pockets" that should be air using raytracing

Water

"onwater": true,
"waterloggable": true

  • onwater - Whether to place on the top of the water rather than in the water. Useful for boat objects

  • waterloggable - Will make any block that can be waterlogged automatically waterlogged if placed in water

Vacuum Interpolation

"vacuumInterpolationMethod": "BILINEAR_STARCAST_3",
"vacuumInterpolationRadius": 10

  • vacuumInterpolationMethod - If using vacuum, what method should the terrain use to interpolate to the flat area.

  • vacuumInterpolationRadius - The radius of the interpolation

Bottom / Meld / Overstilt

"bottom": true,
"meld": true,
"overStilt": 1

  • bottom - Whether to place this object from the bottom up. Shouldn't be used with rotation.

  • meld - Will only place the object in places where blocks already exist. This allows you to spawn dungeons with caves carving into them, but is very performance intensive!

  • overStilt - If using stilt mode, this will extend the stilt into the ground by the number of blocks specified (1 would be stilt 1 block past the ground level).

Clamp

"clamp": {
    "minimumHeight": 0,
    "maximumHeight": 255
}

clamp allows you to make sure the object only spawns within the minimum and maximum y levels.

These values are the Y level values that the object should be placed on. So if you have the minimum set to 60 and the maximum set to 65, and have an object 10 blocks high, it will still be placed on terrain 60-65 blocks high.

PreviousMasteringNextDimensions

Last updated