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

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.

FieldWhat it does
NameWhat players see. Use Other languages underneath to add English, Simp. Chinese or Trad. Chinese names.
DescriptionThe text in the item tooltip (same Other languages option).
TypeSword, bow, helmet, potion and so on. The rest of the form changes to fit the type you pick.
RaritySets the name colour.
ShapeThe 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.
ColorsMain color is the base colour for the icon and the dropped item. Second color is for trim such as a guard or grip.
LevelRoughly what level of player uses it. Only shown for gear.
StatsThe 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 usedOnly for consumables. Kind is Potion (heal), Tonic (buff) or Food. Then Heal, At least, Buff (tonics need one) and Duration.
Lantern lightOnly for lanterns: Light color, Brightness and Reach.
AdvancedStarts 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.

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#

FieldRequired?What it meansAllowed values
idYesThe item’s name inside your mod. Other files use it to point at this itemStarts with a lowercase letter or digit; only lowercase letters, digits and underscores; up to 48 characters. No repeats in one file
name, namesAt least oneDisplay name. names holds other languages, for example { "zh-TW": "霜刃" }Up to 48 characters each
description, descriptionsNoItem descriptionUp to 400 characters
typeYesWhat kind of thing this isWEAPON SHIELD BOW STAFF GUN HELMET CHESTPLATE LEGGINGS BOOTS GLIDER LANTERN BOAT HOOK CHARM GLOVES CAPE RING AMULET TOOL ROD MATERIAL CONSUMABLE
rarityNoRarity (sets the name colour)COMMON (default) UNCOMMON RARE EPIC LEGENDARY
iconNoName of the small inventory iconAn unknown name falls back to the default icon of that type, no error
color, modelColor, secondaryColorNoMain colour, model colour, second colour"#rrggbb", six hex digits. If color is missing, the most common block colour is used
statsNoNumbers, see the table belowOnly the fields in the table below
referenceLevelNoRoughly which level of gear this is meant to matchWhole number, 1 to 200
voxels or modelNoThe look: write the blocks inline, or point at a model file in the modSee "Look" below
voxelScaleNo0.5 cuts the blocks twice as fine (detailed models)0.5 or 1
lightColor, lightIntensity, lightDistanceNoLight given off by lantern-type itemsA colour; strength 0 to 5; distance 0 to 40
useNoWhat a consumable does when usedOnly on CONSUMABLE, see "Consumables" below
levelPoolNoWhen true, this gear can also drop from the normal level-based drop pooltrue 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".

FieldMeaningRange
powerAttack power0 to 2000
armorArmor0 to 2000
critCritical hit0 to 60
tempoAttack speed-50 to 100
hpHealth0 to 20000
mpMana0 to 2000
resourcePctResource (rage, energy and so on) bonus, in percent0 to 100
moveSpeedMovement speed-30 to 40
magazineSizeMagazine size (guns)1 to 120, whole number
reloadMsReload time in milliseconds (guns)200 to 8000, whole number
blockBlocking (shields)0 to 95
guardStaminaStamina 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 }:

models/frost_whistle.json
{
  "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:

data/items.json
[
  {
    "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:

FieldRequired?What it meansAllowed values
kindYesWhat sort of use this ispotion (healing), tonic (power-up, must have a buff), food
healPctNoPercent of health restored0 to 100
healFloorNoMinimum health restored, so it still helps at low max health0 to 1000, whole number
buffNo (yes for tonics)The effect you get, see BuffsA base game buff id, your own buff, or @modid/name
minutesNoHow many minutes the buff lasts1 to 120
data/items.json
[
  {
    "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.buff can be a base game buff id (for example meal_hearty), a local id from your own buffs table, or @modid/name from 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 your dependsOn (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 as attack. Use power, or you will see: "stats.attack" cannot be changed by mods.
  • Adding use to something that is not a CONSUMABLE.
  • 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.
  • name longer than 48 characters, or an id with capitals, spaces or non-English letters.
  • Repeating an id in one file, or reusing the name of another item, fish or dish.
  • 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.