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
.voxmade 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#
- 1Go 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.
- 2Set 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.
- 3Name 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:
[
{
"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:
"blocks": "models/hunter_hut.json"
{ "size": [5, 4, 5], "blocks": [ [0,0,0,"f"], [0,0,1,"f"], [0,1,0,"w"] ] }Fields#
| Field | Range 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": [...] } |
place | Where and how often it appears, see "How buildings appear in the wild". Leave it out entirely to use all the defaults |
spawns | Up to 8 guard entries, see "Guards and chests" |
chests | Up to 4 chests, see "Guards and chests" |
mapIcon | The 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` | Meaning | Fields needed |
|---|---|---|
solid | A solid block | color: "#rrggbb" |
glass | Glass | color |
water | Water | color |
air | Hollow: carves the natural terrain away | none |
furn | Furniture | furn: 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:
| Field | Range and default | In plain words |
|---|---|---|
biomes | ALL (default) or a list of GRASSLAND, FOREST, DESERT, MESA, TUNDRA, OCEAN | It only appears in these biomes. The biome at the building's anchor point is what counts |
rarity | 0.01 to 1, default 0.15 | How 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 |
minSpacing | 160 to 2000, default 300 | The 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 |
awayFromVillages | 0 to 600, default 120 | At least this many blocks from a village centre, and never inside a village |
maxSlope | 0 to 12, default 3 | How much the ground may differ in height across the building. The smaller, the flatter the ground it needs |
allowUnderwater | true / false, default false | Whether it may stand in water (at most 30 blocks deep). When not allowed, ground below sea level is skipped |
sinkInto | 0 to 8, default 1 | How 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#
| Field | Range and meaning |
|---|---|
spawns[].species | The 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[].count | 1 to 6 creatures |
chests[].at | [x, y, z] in model coordinates |
chests[].loot | Up 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#
| What | Limit |
|---|---|
| Blueprints per mod | 16 |
| Model size | 64 wide and 64 deep, 48 tall |
| Blocks | 20,000 |
| Palette | 64 entries |
| Guards | 8 entries, up to 6 creatures each |
| Chests | 4, 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.jsonand addspawns,chestsandmapIconyourself. 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
atoranchor, or going outsidesize. They are always model coordinates, starting at 0. - Using a letter in the model that the palette does not define.
- Treating
yas front to back.yis up, and the horizontal directions arexandz. - Writing
COLLIDERforfurn, or misspelling a furniture name. The load check lists the names that work. - A very low
raritytogether with a largeminSpacing, so you can walk all day and never find one. Raiserarityand lowerminSpacing. - A
maxSlopeso small that the building can hardly find a place. allowUnderwaterleftfalsewhilebiomesis onlyOCEAN. 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.
Related pages#
- In-game tools: import a
.voxbuilding without touching files. - Templates: the "Old Shrine" template.
- Species: make your own guard creature.
- Spawns: let creatures roam the wild without being tied to a building.
- Folder and mod.json
- The mod editor: build this kind of content with forms and test it in the game.