Items
Add weapons, armor, tools, materials and consumables: give a name, a type, some numbers and a look, and the game has a new item.
The items table lets you add any of 22 kinds of things: swords, shields, bows, staves, guns, helmets, armor, capes, rings, lanterns, boats, fishing rods, materials, healing potions and more. Each item is one entry that says what it is called, what kind it is, what its numbers are and what it looks like. A field is one setting inside an entry, such as name or type.
In the editor#
Open the Items tab under Gear & items in the left column. Press Add to start a new item, or Copy from game to start from a base game item (its look comes along) and change what you like. The middle column is the form for the item you picked. The right column shows the item turning around, so you see changes as you make them.
| Field | What it does |
|---|---|
| Name | What players see. Use Other languages underneath to add English, Simp. Chinese or Trad. Chinese names. |
| Description | The text in the item tooltip (same Other languages option). |
| Type | Sword, bow, helmet, potion and so on. The rest of the form changes to fit the type you pick. |
| Rarity | Sets the name colour. |
| Shape | The look of the item, built from blocks. Press Draw shape (or Edit shape once you have one) to open the shape editor. If you do not draw one, the game uses its built-in look for that type. |
| Colors | Main color is the base colour for the icon and the dropped item. Second color is for trim such as a guard or grip. |
| Level | Roughly what level of player uses it. Only shown for gear. |
| Stats | The numbers that fit this type, for example Power, Tempo and Crit for a weapon. Each has a one-line hint. Rarely used stats are under Advanced as More stats. |
| When used | Only for consumables. Kind is Potion (heal), Tonic (buff) or Food. Then Heal, At least, Buff (tonics need one) and Duration. |
| Lantern light | Only for lanterns: Light color, Brightness and Reach. |
| Advanced | Starts collapsed. More stats, Shape tint (used by the built-in look), Icon, and for gear Drop like normal gear. |
In the shape editor you pick a tool (Add, Erase, Paint, Pick, Fill, Box, Extrude or Select), switch Mirror and Show grid lines on or off, and choose a Grid size: Coarse (10 cm cells, good for armor and big items) or Fine (5 cm cells, finer detail for held weapons). The views Front, Left, Right, Back and Top let you check every side. Press Done to keep the shape or Cancel to throw it away.
The right column also lists Recipes that make it, with Add a recipe for it if there is none yet.
To test, press Try this one above the form. The editor saves, reloads, and puts you in a flat daytime test arena with the item already in your bag. The top-bar Test loads the whole mod instead. If the bar at the bottom lists problems, fix those first.
Advanced: writing the JSON by hand#
Below is the same content as it looks 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 show are kept as they are. Where the file goes and how it is listed: Mod folder and mod.json.
The table is one JSON file. It starts with [ ] and holds one { } per item. Put the file inside your mod folder and list its path under content.items in mod.json (see Mod folder and mod.json). If one entry has a problem, only that entry is skipped and the rest still load.
Smallest working example#
A short ice sword: six blocks make the blade, attack power 34. Paste it into data/items.json.
[
{
"id": "frost_blade",
"name": "Frost Blade",
"names": { "zh-TW": "霜刃" },
"description": "A cold blade that swings light.",
"type": "WEAPON",
"rarity": "RARE",
"icon": "sword",
"color": "#9fd8ff",
"stats": { "power": 34, "tempo": 8 },
"voxels": [
{ "x": 0, "y": 0, "z": 0, "color": "#3a4a5c" },
{ "x": 0, "y": 1, "z": 0, "color": "#3a4a5c" },
{ "x": 0, "y": 2, "z": 0, "color": "#9fd8ff" },
{ "x": 0, "y": 3, "z": 0, "color": "#9fd8ff" },
{ "x": 0, "y": 4, "z": 0, "color": "#9fd8ff" },
{ "x": 0, "y": 5, "z": 0, "color": "#9fd8ff" }
]
}
]Fields#
| Field | Required? | What it means | Allowed values |
|---|---|---|---|
id | Yes | The item’s name inside your mod. Other files use it to point at this item | Starts with a lowercase letter or digit; only lowercase letters, digits and underscores; up to 48 characters. No repeats in one file |
name, names | At least one | Display name. names holds other languages, for example { "zh-TW": "霜刃" } | Up to 48 characters each |
description, descriptions | No | Item description | Up to 400 characters |
type | Yes | What kind of thing this is | WEAPON SHIELD BOW STAFF GUN HELMET CHESTPLATE LEGGINGS BOOTS GLIDER LANTERN BOAT HOOK CHARM GLOVES CAPE RING AMULET TOOL ROD MATERIAL CONSUMABLE |
rarity | No | Rarity (sets the name colour) | COMMON (default) UNCOMMON RARE EPIC LEGENDARY |
icon | No | Name of the small inventory icon | An unknown name falls back to the default icon of that type, no error |
color, modelColor, secondaryColor | No | Main colour, model colour, second colour | "#rrggbb", six hex digits. If color is missing, the most common block colour is used |
stats | No | Numbers, see the table below | Only the fields in the table below |
referenceLevel | No | Roughly which level of gear this is meant to match | Whole number, 1 to 200 |
voxels or model | No | The look: write the blocks inline, or point at a model file in the mod | See "Look" below |
voxelScale | No | 0.5 cuts the blocks twice as fine (detailed models) | 0.5 or 1 |
lightColor, lightIntensity, lightDistance | No | Light given off by lantern-type items | A colour; strength 0 to 5; distance 0 to 40 |
use | No | What a consumable does when used | Only on CONSUMABLE, see "Consumables" below |
levelPool | No | When true, this gear can also drop from the normal level-based drop pool | true or false. If missing, it only drops where you list it in the loot table |
Numbers (stats)#
stats accepts only the fields below, each with a range. A value outside its range is never quietly clamped. The whole entry is skipped and the game tells you "this field should be between A and B, but it is C".
| Field | Meaning | Range |
|---|---|---|
power | Attack power | 0 to 2000 |
armor | Armor | 0 to 2000 |
crit | Critical hit | 0 to 60 |
tempo | Attack speed | -50 to 100 |
hp | Health | 0 to 20000 |
mp | Mana | 0 to 2000 |
resourcePct | Resource (rage, energy and so on) bonus, in percent | 0 to 100 |
moveSpeed | Movement speed | -30 to 40 |
magazineSize | Magazine size (guns) | 1 to 120, whole number |
reloadMs | Reload time in milliseconds (guns) | 200 to 8000, whole number |
block | Blocking (shields) | 0 to 95 |
guardStamina | Stamina cost multiplier while blocking (shields) | 0.2 to 3 |
Look#
A look is a pile of small blocks. Each block is { "x", "y", "z", "color" }. Coordinates are whole numbers no larger than 64 in either direction, one item can have up to 4000 blocks, and if two blocks share a spot only the first is kept. Few blocks: write them in voxels. Many blocks: put them in a file under models/ and point at it with "model": "models/name.json". A model file can be a plain list of blocks or { "voxels": [...], "voxelScale": 0.5 }:
{
"voxels": [
{ "x": 0, "y": 0, "z": 0, "color": "#cfe8ff" },
{ "x": 1, "y": 0, "z": 0, "color": "#cfe8ff" },
{ "x": 0, "y": 1, "z": 0, "color": "#9fd8ff" }
],
"voxelScale": 0.5
}If you would rather not type coordinates, build the item in the item editor on the website, press Export, then use Paste an item on the Make Mods page. The game saves it as models/<id>.json and adds an entry for you. You can also drop the whole exported text in as one entry yourself. Uppercase letters in id are turned into lowercase, and a missing type becomes MATERIAL:
[
{
"schema": "voxel-world-item",
"id": "Custom_Lantern_Lx2K9",
"name": "Little Lantern",
"type": "LANTERN",
"voxels": [
{ "x": 0, "y": 0, "z": 0, "color": "#ffcc00" },
{ "x": 0, "y": 1, "z": 0, "color": "#ffe27a" }
]
}
]Consumables (use)#
To make a potion or a snack, set type to CONSUMABLE and add use:
| Field | Required? | What it means | Allowed values |
|---|---|---|---|
kind | Yes | What sort of use this is | potion (healing), tonic (power-up, must have a buff), food |
healPct | No | Percent of health restored | 0 to 100 |
healFloor | No | Minimum health restored, so it still helps at low max health | 0 to 1000, whole number |
buff | No (yes for tonics) | The effect you get, see Buffs | A base game buff id, your own buff, or @modid/name |
minutes | No | How many minutes the buff lasts | 1 to 120 |
[
{
"id": "warm_potion",
"name": "Warming Potion",
"names": { "zh-TW": "暖身藥水" },
"type": "CONSUMABLE",
"rarity": "UNCOMMON",
"color": "#e8a060",
"use": { "kind": "potion", "healPct": 30, "healFloor": 50, "buff": "meal_hearty", "minutes": 5 }
}
]How it points at other things#
use.buffcan be a base game buff id (for examplemeal_hearty), a local id from your own buffs table, or@modid/namefrom another mod.- When another file (recipes, loot, dishes) needs this item, it writes the local id,
frost_blade. If your mod has no item with that id, the game looks for a base game item with that id instead. - To use something from another mod, write
@icepack/frost_shard. That mod must be listed in yourdependsOn(see Mod folder and mod.json).
Common mistakes#
- Forgetting
type(only the whole-text export from the website may leave it out). The game says: "type" is missing. - Putting a made-up field in
stats, such asattack. Usepower, or you will see: "stats.attack" cannot be changed by mods. - Adding
useto something that is not aCONSUMABLE. - Writing a colour as
#fff. Use all six digits:#ffffff. - Block coordinates that are not whole numbers, are beyond 64, or more than 4000 blocks. You will see: the look could not be read, or has blocks out of range.
namelonger than 48 characters, or anidwith capitals, spaces or non-English letters.- Repeating an
idin one file, or reusing the name of another item, fish or dish.
Related pages#
- Recipes: let players craft your item.
- Loot: let enemies drop your item.
- Buffs: give a consumable an effect.
- Patches: adjust the numbers of base game items.
- The mod editor: build this kind of content with forms and test it in the game.