Modding Tutorial - Item Modding
Item Modding Tutorial

--- Supported by Alpha v0.7 and later (Yet to be released) ---

Adding new items to the game may sound hard to do, but it is actually easier to than you think, all you need is a 3D program (preferably 3dsmax) and a notepad.

In the game folder "media/items" you will see a long list of different item names


All xml files in this folder will get automatically imported into the game. We have simple items like iron, and more complex items like weapons and armours, but they all follow the same rules.

Getting started

Lets get started with introducing something simple like a diamond into the game. Start by creating a new xml file in the items folder and name it "diamond.xml", xml files can be created in notepad as they are simple txt documents, it is just that they need to follow certain coding rules.

As a start we need to write the text..
<?xml version="1.0" encoding="UTF-8"?> the beginning of the file. Once this is done we can get started with the coding.

All item xml files needs to have a starting tag "item", it looks like this:

In this tag we need to create some children tags as well that will define the item to what we want it to be. This is how a finished diamond.xml document may look like:

<?xml version="1.0" encoding="UTF-8"?>


I will go through the tags one by one here and explain what they means:
  • <name> - The item name ID in game, this name is used as a reference for other game objects that needs to call on it.
  • <model> - The model filename (needs to be in the format ".3ds").
  • <texturecolor> - The color texture filename that will be assigned to the model.
  • <texturespec> - The specular texture filename that will be assigned to the model.
  • <texturenormal> - The normal texture filename that will be assigned to the model.
  • <icon> - The icon image filename.
  • <language> - The item language file containing the title and description of the item.
  • <unlimitedresource> - If this item can be produced endlessly without any cooldown, like fetching water from a well, setting this to the value "1" will hinder the game from stocking it up.
  • <dropable> - Setting this to anything other than "1" will delete all items of this type being dropped to the ground. This is for projectile purposes.
  • <inventory> - Setting this value to "1" will make the item visible in the inventory. Items used for graphical purposes only like "burning wood" should have this value set to "0".
  • <startingitem> - Setting this value to "1" will make this item visible in the inventory from start. This also means that the player can craft this item right from start if it is craftable.
  • <chestrarity> - This is a percentage value, setting this value to "2" means that there is a 2% chance of this item to be created inside a chest for every item created in the chest. So if 10 items are created in the chest there is a 20% that one of these items will be amongst them.
  • <handle> - The item handle filename, this will be explained in more detail below.

Create a folder for the item

Once the diamond.xml file has been created we need to make a folder for it with all the files it needs. As we have created a "diamond.xml" file we are required to name the folder "diamond" as well. In this folder we add the files needed.

The 3D model

We can begin by creating a model for the diamond, it may look something like this:


The way you position the 3d model is the way it will get positioned on the shelves in the storage room or on the ground. Once finished modelling it we export it as a 3ds file to the newly created "diamond" folder and name it "diamond.3ds" as defined in <model>diamond.3ds</model>. But before exporting it it is very important to make sure that the models world matrix is set to zero, this is something that very easily can get out of hand, therefore I will make a youtube video explaining this in more detail at a later occasion.

The textures

When you created the model you probably made a texture to it as well. This texture should be saved as color.png in the "diamond" folder as defined in <texturecolor>color.png</texturecolor>. Note that any pixel that have a alpha value below 50% will not be drawn in the game. The game don't support semi transparent items, only solid or fully see-through.

Even if you don't have any normal map texture made for the item model you must add it, just make sure that you fill it with the color rgb(127, 127, 255), otherwise the light reflected from it will get distorted. Once done save it as normal.png in the "diamond" folder.

The same goes for the specular texture, you need to add it! Save it as "spec.png" in the "diamond" folder. If you want it to have specular as we probably will when creating a diamond it is defined by the green color in the specular texture, the more green the more specular. The red color in the specular texture defines self-luminosity. The blue color is still undefined and changing its color will have no effect in the game, but it is always for the better to set it to zero so that the item don't get distorted when the blue color comes to use in future updates.

The language file

We also need to add a "language.xml" file into the "diamond" folder. This content of this file can look something like this:

<?xml version="1.0" encoding="UTF-8"?>

  <description>Besides its indescribable beauty the diamond is the hardest crystal known on earth. It is very rare and can only be found in the deepest depth. Its indestructible properties makes this a perfect crafting material for making weapons that can cut through anything.</description>
  • <name> - The name of the item that will be displayed in game.
  • <description> - The description of the item that will be displayed in game.

Why we have a language file for the item and not have the name and description defined in the "diamond.xml" file is because of translation purposes. More about this can be read here:

The handle file
Almost done, all that is needed now is to add a handle file. This part can be a bit complicated, it is worth trying out and understand how it works, but I fully understand if you run into problems and can't get it right, therefore I will also present a "cheat" method below this section. The cheat method will not require you to use 3ds max.

You can begin with downloading the "handle.3ds" file here:

When loading this file into a 3d program it will look something like this:


This 3d model is used as a tool for showing how the item should be held by creatures that carries it. If we take a look at this imp he has a handle model connected to his hand as well.


So the goal here is to position the handle you downloaded in a way that will make the imp hold the item correctly.

When positioning the handle the positioning should be done by moving and rotating the world matrix of the handle model, not by moving or rotating its vertices.

So the result of me positioning the handle to the item looks like this (I only moved the handle model, not the diamond model!)


And this will result in the imp holding the diamond like this


One way to picture this transformation is that the the diamond model and the handle are attached to eachother as one solid object. Then in the game the handle with the diamond is rotated, positioned and scaled to fit the exact location as the creatures handle.

You may have noticed that the handle file is of the unknown type ".hdl", this is because the handle is exported through a max script especially made for the game. It can be downloaded from here:

In the file you downloaded you will gain access to a couple of different exporting scripts, you can unzip them all to a folder of your choice, but at this moment we will only need the "" script.

To export the handle model to "handle.hdl" in your "diamond" folder you need to open the script in 3ds max. Once opened you select the handle model, then run the script. A save file dialog window should open and you are now able to save it as "handle.hdl" in your diamond folder.

Handle file cheating method

This method should only be followed if you can't can't get the handle exporting working or if you don't own 3dsmax. The downside to this method is that the way the items is held by the creatures or displayed in the storage room can be a little off.

Find a 3d model amongst the items that has the most similar shape and size as the diamond. In my case I choose the rock item.


Then position the diamond model as similar to rock item as possible. Remember that the world matrix of the diamond model should always be zero, so you need to move and rotate the diamond through its vertices.


Now when I have positioned the diamond as similar as the rocks as possible I export the diamond model again to the "diamond" folder as "diamond.3ds", then I copy the handle.hdl file in the "rock" folder and paste it into the "diamond" folder.

This is a much easier approach, but as you probably can see the handle got a different position in relations to the diamond model than before, and this may result in that it gets positioned wrong in creatures hand. Moving the diamond so that it fits the handle may also be dangerous because it will probably get the wrong position when stored on tables or laying on the ground.

There is a lot more to be added here about weapons, armours, projectiles and particle effects, but as my time is limited I will have to finish it up later
Any comments on this? Does it feel complicated or what do you think?
This seems pretty straight forward. I think the most complicated thing will be generating 3D models. I've not done that myself, but being here has inspired me to give it a go. For people who are familiar with 3D Max or any of the other modeling softwares, this should be cake. The coding in the XML was really well explained so there shouldn't be any hangups there.
Thanks Smile I will expand it soon with some other stuff as well, the downside with all this is that I don't have the buildings moddable yet, so it is hard to introduce new items into the game that aren't weapons or armours. The only way to introduce new items is to put the in chests atm, and when the player find this new item he will learn how to make it.

But.. One thing at a time Smile
I spend my live viewing games cores, I modded old games like Blade mistress back in the day, turning the entire world into a burning pit of ash and despair, for the fun of it, using compilers to view exe files and dirty joes for minecraft etc.. not to mention all the webbased games I never finished Big Grin you learn more this way than any book can teach you Big Grin.
So no it's not complicated. It's so awesome to have a good graphical artist, I'm all about coding, but photoshop etc.. has always been a struggle to me, it's in my head, but barely ends up the way I want it.
(22-04-2014, 09:30 AM)Orifiael Wrote: So no it's not complicated. It's so awesome to have a good graphical artist, I'm all about coding, but photoshop etc.. has always been a struggle to me, it's in my head, but barely ends up the way I want it.

I can definitely relate to that, my primary skill is coding, graphics is something I have been forced to learn. I do think it is fun modelling and creating textures, but the result easily becomes a little to mediocre in my own opinion. But still fun Tongue
Sorry to go on a tangent here, but this is interesting to me:

•<value1> - The number set here is the number of level 1 shards the player will obtain by letting the Dark Mother eat it.
•<value2> - The number set here is the number of level 2 shards the player will obtain by letting the Dark Mother eat it.
•<value3> - The number set here is the number of level 3 shards the player will obtain by letting the Dark Mother eat it.
•<value4> - The number set here is the number of level 4 shards the player will obtain by letting the Dark Mother eat it.

is there some behind-the-scenes system of currency going in? Maybe to power spells or some such?
Shards were in the game briefly, but was then removed when creatures were auto spawned. You can still see remnants of that system in the crafting panel, but crafting now exclusively uses mined resources. I wouldn't be surprised to see shards come back later on when we see more magical items enter the game.
I have updated and removed the shard text to avoid confusion. Nicely spotted Xaos Wink
So those were NOT the droids I was looking for... I see. Move along.

Forum Jump:

Users browsing this thread: 1 Guest(s)