Guide: Adding armour to Veloren

\_ made by @Pfau


What you need:

An IDE of your choice (A programme that lets you view and edit code)

Examples: VSC, Atom, Notepad++

A Voxel Editor (To create the armour model)

Example: Magicavoxel

A guide on how to compile and run Veloren on your OS.

The character template. (Can be opened with any voxel-editor that supports layers; i.e. Magicavoxel.)

This is also included in the Veloren client’s assets.

Getting Started

Before creating your armour in a voxel editor there are a few things you should know:


In order to place “skin” (parts that are not covered by armour) to your work you have to use whatever colour is stored in the 1st (light tone) and 5th (dark tone) slot/index of your palette.

Note: The important thing is not the colour but the position on the palette to get the right result.


Armour can be coloured in the code, too.

To do that just use greyscale colours in your model. (Later you will learn how to apply the colours with code.)

Another thing you might notice is the neck added to the chest armour. This is needed to not make the head appear disconnected from the body when it’s turned.

Importing the model and adding it as an item to the game

To make the game actually load your creation there are several steps you have to follow.

They can be done in any order.

Copying the .vox into the asset folder:

Make sure to export your model(s) as .vox and NOT just copy a saved .vox file from magicavoxel. Just copying will result in a ~10x bigger file size.


The file path inside the assets folder is something like

assets/voxygen/voxel/armor/<Armor Type>/<Model Name>

So for a chest armour called “leather_vest-0.vox” it is:


Naming scheme for .vox files:

Single words are parted with an underscore (“_”)

Counting starts at zero.

Numbers are added with a single dash(“-”) in front of them.

Your item name should always end with a number, unless you are absolutely positive there isn't going to be an alternative version/design of the item

Load the file and store it inside the code

Those are the file paths you will need after opening the root folder of Veloren in your IDE:

assets/voxygen/voxel/humanoid_armor_<armour type>_manifest.ron

ONLY needed for armour with .vox files

(sets the filepath and offsets of the .vox)

assets/common/items/armor/<armour type>

(create a new .ron in here to create an ingame item)


(create a new entry in here to add an item image to the item)


ONLY needed for armour with .vox files

(list your new armour style in here)

Veloren has 12 types of armour:

  • Head
  • Neck (Necklaces)
  • Tabard
  • Shoulder
  • Chest
  • Hand
  • Lantern
  • Belt
  • Ring
  • Back (Capes, Backpacks...)
  • Legs
  • Feet
  • Red – Needs a 3d .vox file

Armour types that need a 3d .vox file need to be listed in every file above.

Example for adding a new cape:

  1. New entry in assets\voxygen\voxel\humanoid_armor_back_manifest.ron


The offset will be determined at a later point! Just keeping the numbers from the example you copied should be good for now.


Copy this part (make sure to include the brackets and comma!) and paste it:


Fill in the name of the item style. This is the name you’ll add in later.

Note: color: None indicates that grey parts won’t be recoloured.

To colour those parts put in “color: Some((<R>, <G>, <B>))” here.

Example of recoloured armour:

Brown: (
    vox_spec: ("armor.chest.grayscale", (-7.0, -3.5, 2.0)),
    color: Some((90, 49, 43))

2. New Entry in assets/common/items/armor/<armour type>


Copy and paste one of the existing .ron files (Note: Use numbers here too).

    name: "New Cape",
    description: "Example Item",
    kind: Armor(
        kind: Back(NewCape),
        stats: (20),

Edit the file to have the right kind.(The same kind you put in before.)


This creates a tooltip text similar to this.

3. Adding the armour style to common/src/comp/inventory/item/

Look for the armour style you want to add. If it’s not listed you are probably trying to add a style that doesn’t need a 3D asset.

#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum Back {
    Short0 = 1,
    Admin = 2,
pub const ALL_BACKS: [Back; 2] = [Back::Short0, Back::Admin];

Every armour style has an enum and a const.

In the enum you need to define the name and assign a number to it.

Inside the const definition you need to increase the number of available styles and add the name like it’s done for the other parts.

Example for the “NewCape”:

#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum Back {
    Short0 = 1,
    Admin = 2,
    NewCape= 3,
pub const ALL_BACKS: [Back; 3] = [Back::Short0, Back::Admin, Back::NewCape];

4. Add a new item image in assets\voxygen\item_image_manifest.ron

You can either use a .png or .vox file as an item image.

Example for a .png:

// Lanterns
Lantern(Black0): Png(

Example for a .vox:

Armor(Back(Short0)): VoxTrans(
    (0.0, 0.0, 0.0), (-90.0, 180.0, 0.0), 1.0,

In order to find the right posing numbers for the .vox it’s often a good idea to look for a similar item.

Armor(Back(NewCape)): VoxTrans(
    (0.0, 0.0, 0.0), (-90.0, 180.0, 0.0), 1.0,

You can use the same .vox as the actual 3D asset shown equipped on the character later.


5. Finding the right offset for your item

In order to test your item in-game you need to compile your game now.

Your new item will only be available locally, so make sure to connect to a local server or choose “Singleplayer”.

To drop the item into your inventory use the chat command/give_item:

/give_item common.items.armor.back.new_cape


When equipping your new item you might be presented with this sight.

To set the right offset you need to revisit ssets/voxygen/voxel/humanoid/<armour type>_manifest.ron

The values in there can be hot-reloaded. That means just saving them will immediately take effect ingame.

Admin: (
    vox_spec: ("armor.back.admin", (-5.0, -1.0, -0.0)),
    color: None

They represent the coordinates:

(X, Y, Z)

X = Left (lower the number) and Right (increase the number)
Y = Back (lower the number) and Forth (increase the number)
Z = Up(increase the number) and Down (lower the number)

Change the numbers until you get the desired offset.


Done. You added a new armour style and item to Veloren. :)