Mods are a feature of the full game, not the demo. They open when the full game launches, and details may change before then.

Blueprints (buildings)

Make a building that appears in the wild on its own: an abandoned hut, an old shrine, a camp. Put guards and a chest inside; they trigger when the player arrives, and the building leaves a mark on the world map.

What this lets you make#

A blueprint is one small building. You decide what it looks like (built from blocks), which terrain it appears in and how common it is, and you can put guard creatures and a chest inside. While exploring, players will run into your building at random places. You never have to place each one by hand.

A blueprint has two parts: an entry in the data table (colours, spawn rules, creatures, chest) and a model, which says where every block of the building goes. The model can be written right in the table, or kept in a separate file (usually a .json under models/) that the table points to with a path.

If you would rather not type coordinates, build the structure in MagicaVoxel and import it. See "Importing a .vox" below and In-game tools. A mod can have up to 16 blueprints.

In the editor#

Open the Blueprints tab under World in the left column (if it is not there, add it from Add new content at the bottom) and press Add. A new entry starts with a single block. Replace it with a real building using Box one in the world or Import a building file below.

There are two buttons at the top of the form:

  • Box one in the world: the editor saves first, then takes you into a creative test world. Walk to a building or landform you like, box it and save it as a blueprint. See "Boxing" below.
  • Import a building file: imports a .vox made in MagicaVoxel. After importing, go back to the mod list and reopen the editor to see the new content. See In-game tools.

The rest of the form:

  • Name.
  • Blocks: read only, showing Size and Blocks. Blocks are not edited in the form; box them in the world or import them.
  • Ground point: which cell of the building sits on the spot in the world. The default is the bottom centre.
  • How blocks look: the colour or kind of each block (Solid, Glass, Water, Hollow, Furniture), with Add one for more. Change a colour and the whole building follows.
  • Where it appears: Regions, How common, At least apart, Away from villages, Steepest ground, Sunk into the ground and May stand underwater.
  • Creatures inside: up to 8 entries, each with Which creature, Spot and How many.
  • Chests: up to 4, each with a Spot and What is inside (Item, At least, At most, Chance).
  • Map icon: the marker shown on the map once found (Tower, Ruin, Camp, Shrine, Cave or House). Leave it empty for none.

The right column is a preview you can switch between From above and From the front. The white square is the ground point, red dots are creatures and yellow dots are chests.

Boxing: save a place in the world as a blueprint#

  1. 1
    Go in

    Press Box one in the world. A bar at the top reads "Capture mode: go to the spot you want, set two corners in the panel", and the Box a building panel appears on the right. Press Esc to free the mouse before using the panel buttons.

  2. 2
    Set two corners

    Walk next to the building and set the First corner and the Second corner. Each can be set with Under my feet or The block I look at, then adjusted with the + and - buttons for Across, Up and Deep. A yellow box is drawn in the world and the panel shows Box size and Blocks.

  3. 3
    Name it and save

    Type a name under Name this building, press Save as blueprint, and after Saved appears press Back to editor.

  • There are size limits: at most 64 blocks wide and deep, 48 high, and 20000 blocks in total. The panel tells you when a box is too big, so box a smaller area.
  • When parts of the box are not loaded yet, the panel asks you to move closer and wait before saving.
  • If you came in from a blank entry you had just added in the editor, the saved building replaces that entry and keeps its name. Otherwise a new entry is added.
  • The new blueprint appears in the region you were standing in when you saved. Everything else starts at its default, so tune it back in the editor.

Advanced: writing the JSON by hand#

This is the same content as it is written in the file. The editor saves exactly this format. You can also press Open folder at the top of the editor and edit the file in an outside text editor; when you save, the editor picks up the change. Fields the form does not have are kept as they are. Where the file goes and how it is listed: Mod folder and mod.json.

The table lives at data/blueprints.json, and mod.json points to it with "blueprints": "data/blueprints.json" under content.

A minimal working example#

A small hut, 5 blocks wide and 4 tall: a grey floor, brown walls with a doorway, and a blue roof. Inside are a crate and two wolves. It only appears on grassland and in forests, and shows as a house icon on the map. This example uses only built-in creatures and items, and the model is written straight into the table:

data/blueprints.json
[
  {
    "id": "hunter_hut",
    "name": "Hunter's Hut",
    "names": { "zh-TW": "獵人小屋", "zh-CN": "猎人小屋" },
    "anchor": [2, 0, 2],
    "palette": {
      "f": { "kind": "solid", "color": "#6e6a60" },
      "w": { "kind": "solid", "color": "#8a5a3c" },
      "r": { "kind": "solid", "color": "#3f6fa8" },
      "c": { "kind": "furn", "furn": "CRATE", "facing": 0 }
    },
    "blocks": {
      "size": [5, 4, 5],
      "blocks": [
      [0,0,0,"f"], [0,0,1,"f"], [0,0,2,"f"], [0,0,3,"f"], [0,0,4,"f"], [1,0,0,"f"], [1,0,1,"f"], [1,0,2,"f"], [1,0,3,"f"], [1,0,4,"f"], [2,0,0,"f"], [2,0,1,"f"], [2,0,2,"f"], [2,0,3,"f"], [2,0,4,"f"], [3,0,0,"f"], [3,0,1,"f"], [3,0,2,"f"], [3,0,3,"f"], [3,0,4,"f"], [4,0,0,"f"], [4,0,1,"f"], [4,0,2,"f"], [4,0,3,"f"], [4,0,4,"f"],
      [0,1,0,"w"], [0,1,1,"w"], [0,1,2,"w"], [0,1,3,"w"], [0,1,4,"w"], [1,1,0,"w"], [1,1,4,"w"], [2,1,0,"w"], [3,1,0,"w"], [3,1,4,"w"], [4,1,0,"w"], [4,1,1,"w"], [4,1,2,"w"], [4,1,3,"w"], [4,1,4,"w"], [3,1,3,"c"],
      [0,2,0,"w"], [0,2,1,"w"], [0,2,2,"w"], [0,2,3,"w"], [0,2,4,"w"], [1,2,0,"w"], [1,2,4,"w"], [2,2,0,"w"], [3,2,0,"w"], [3,2,4,"w"], [4,2,0,"w"], [4,2,1,"w"], [4,2,2,"w"], [4,2,3,"w"], [4,2,4,"w"],
      [0,3,0,"r"], [0,3,1,"r"], [0,3,2,"r"], [0,3,3,"r"], [0,3,4,"r"], [1,3,0,"r"], [1,3,1,"r"], [1,3,2,"r"], [1,3,3,"r"], [1,3,4,"r"], [2,3,0,"r"], [2,3,1,"r"], [2,3,2,"r"], [2,3,3,"r"], [2,3,4,"r"], [3,3,0,"r"], [3,3,1,"r"], [3,3,2,"r"], [3,3,3,"r"], [3,3,4,"r"], [4,3,0,"r"], [4,3,1,"r"], [4,3,2,"r"], [4,3,3,"r"], [4,3,4,"r"]
      ]
    },
    "place": {
      "biomes": ["GRASSLAND", "FOREST"],
      "rarity": 0.2,
      "minSpacing": 300,
      "awayFromVillages": 120,
      "maxSlope": 3,
      "allowUnderwater": false,
      "sinkInto": 1
    },
    "spawns": [ { "species": "WOLF", "at": [2, 1, 2], "count": 2 } ],
    "chests": [
      { "at": [3, 1, 3], "loot": [ { "item": "iron_ore", "min": 1, "max": 3, "chance": 0.8 } ] }
    ],
    "mapIcon": "house"
  }
]

Every block in the model is [x, y, z, "letter"]. The letter must be defined in palette. Coordinates start at 0: x and z are the horizontal directions, and y is up. Positions you do not list leave the natural terrain alone. If you write the same cell twice, the later one wins.

To keep the model in its own file, change blocks in the table to a path. The file holds the same size and blocks:

text
"blocks": "models/hunter_hut.json"

{ "size": [5, 4, 5], "blocks": [ [0,0,0,"f"], [0,0,1,"f"], [0,1,0,"w"] ] }

Fields#

FieldRange and meaning
id (required)Your own name for it, same rules as other tables
name, names (required)The building's name, up to 60 characters. Players see it when they discover it, and the map uses it
anchor[x, y, z], which cell of the model sits on the spot where the building is placed in the world. If left out it is the middle of the bottom layer, which is also what you usually want, for example [2, 0, 2] for a 5-wide model
palette (required)The colour palette: one letter or digit per kind of block, up to 64. See "Palette"
blocks (required)The model: a file path, or an inline { "size": [width, height, depth], "blocks": [...] }
placeWhere and how often it appears, see "How buildings appear in the wild". Leave it out entirely to use all the defaults
spawnsUp to 8 guard entries, see "Guards and chests"
chestsUp to 4 chests, see "Guards and chests"
mapIconThe icon on the world map: tower, ruin, camp, shrine, cave or house. Left out, the building is not marked on the map

Palette#

Each letter in the palette (one letter or digit) maps to a kind of fill:

`kind`MeaningFields needed
solidA solid blockcolor: "#rrggbb"
glassGlasscolor
waterWatercolor
airHollow: carves the natural terrain awaynone
furnFurniturefurn: the furniture name; optional facing (0 to 3, which way it faces)

Furniture names you can use for furn: TABLE, CHAIR, BED, BARREL, SHELF, STOOL, ANVIL, WEAPON_RACK, SCARECROW, CRATE, LANTERN, BRAZIER, FLOWER_BOX, HAY_BALE, SIGN, BANNER, FLAG, TROUGH, FENCE, STREET_LAMP, SIGN_INN, SIGN_SMITH, SIGN_STABLE, SIGN_STORE, SIGN_HOME, SIGN_MAP, SIGN_ANCHOR. Colours are drawn exactly as you write them, with no darkening or weathering added by the game.

How buildings appear in the wild#

You never say where a building goes. When the world is generated, the game finds suitable places itself, and the positions are fixed for each world (seed). Each building is turned to one of four directions at random (multiples of 90 degrees). Everything is controlled by place:

FieldRange and defaultIn plain words
biomesALL (default) or a list of GRASSLAND, FOREST, DESERT, MESA, TUNDRA, OCEANIt only appears in these biomes. The biome at the building's anchor point is what counts
rarity0.01 to 1, default 0.15How common. The world is cut into squares whose side is minSpacing, and each square has this chance of trying to place one. 0.2 means about one square in five tries. A bigger number is more common
minSpacing160 to 2000, default 300The side length of those squares, which is also roughly the least gap between two of the same building. The bigger it is, the fewer there are in the world
awayFromVillages0 to 600, default 120At least this many blocks from a village centre, and never inside a village
maxSlope0 to 12, default 3How much the ground may differ in height across the building. The smaller, the flatter the ground it needs
allowUnderwatertrue / false, default falseWhether it may stand in water (at most 30 blocks deep). When not allowed, ground below sea level is skipped
sinkInto0 to 8, default 1How many blocks the bottom layer sinks into the ground. The lowest layer also gets a solid foundation down to the ground (up to 16 blocks), so a building on a small dip does not float

The game also has rules of its own: built-in wonders, roads, altars, caves, mines, arenas, clue landmarks, boss camps and strongholds always come first, and your building steps aside rather than sit on top of them. Between two of your own blueprints, the one listed first wins.

Guards and chests#

FieldRange and meaning
spawns[].speciesThe guard creature: built-in, from your own species table, or @othermod/id. Bosses, mounts and sea creatures are not allowed
spawns[].at[x, y, z] in model coordinates. The guards appear near this spot
spawns[].count1 to 6 creatures
chests[].at[x, y, z] in model coordinates
chests[].lootUp to 8 lines: item, min, max (1 to 16), chance (0.01 to 1). Items must exist in the game and cannot be boss-only drops

You make the chest look like a chest yourself, by putting a furniture block (such as CRATE) at the same position in the palette. chests only decides what comes out of it.

Guards and chests trigger only once per world. The first time the player comes close to the building (about 24 blocks), the guards appear and the chest's items drop on the ground beside the chest for the player to pick up. A "discovered" notice pops up, and from then on the world map keeps a marker with your mapIcon. The same building never spawns them again. In multiplayer only the host spawns them, and everyone still sees the notice and the marker.

To use your own creature as a guard, put the Species entry in the same mod, for example "species": "ember_wolf".

Limits#

WhatLimit
Blueprints per mod16
Model size64 wide and 64 deep, 48 tall
Blocks20,000
Palette64 entries
Guards8 entries, up to 6 creatures each
Chests4, each with up to 8 loot lines

Importing a .vox#

Build the structure in MagicaVoxel and save it as a .vox file. On the game's Make Mods page, choose Import a building and pick the file. The game converts it into a model file (saved under models/) and an entry in the data table. All you choose is:

  • Which mod to add it to, and the building's name.
  • Which biomes it appears in, and whether it may stand in water.
  • How common it is (Common, Sometimes, Rare), the least gap between two of them, and the least distance from villages.

The preview is the view from above. A few things to know:

  • MagicaVoxel's z axis points up. On import it becomes the game's height. What you stack upward in MagicaVoxel stays upward in the game, and the model is not flipped or mirrored.
  • If the file holds several models, only the first is used.
  • With more than 62 colours, the least-used colours are merged into the nearest ones.
  • Empty space around the model is trimmed away, and the placement point is set to the middle of the bottom layer.
  • An imported building is all solid blocks. It has no guards, chests or map icon. After importing, open data/blueprints.json and add spawns, chests and mapIcon yourself. If you import the same building again later, what you added is kept.
  • The size limits are the ones in "Limits": at most 64 wide, 64 deep and 48 tall, and 20,000 blocks.

New mod on the Make Mods page also offers an "Old Shrine" template, a complete blueprint you can edit straight away. See Templates.

Common mistakes#

  • Using world coordinates for at or anchor, or going outside size. They are always model coordinates, starting at 0.
  • Using a letter in the model that the palette does not define.
  • Treating y as front to back. y is up, and the horizontal directions are x and z.
  • Writing COLLIDER for furn, or misspelling a furniture name. The load check lists the names that work.
  • A very low rarity together with a large minSpacing, so you can walk all day and never find one. Raise rarity and lower minSpacing.
  • A maxSlope so small that the building can hardly find a place.
  • allowUnderwater left false while biomes is only OCEAN. Nothing will ever match.
  • Putting a boss-only item in a chest's loot.
  • Expecting the guards to respawn every time the player comes near. Each building triggers once.