Custom items

It's possible to create custom items in mods. This page will guide you through the process. If you haven't yet, make sure you create the base for the mod first.

Making some items

In this example, we're going to create 2 items called "Quad Damage" and "Staff of Awesomeness", and they will have a custom sprite as well:

In your mod folder, create a folder called items. In there, you have to create a new sval file. You can for example call this awesome_items.sval, or something else. Keep in mind: the assets between base and mods are shared! This means you should use a unique filename here that no other mod is going to use. (You could also put it in a separate (or different) folder if you want to be extra cautious.)

Sval files is the main serializable data structure used throughout the engine, and sval files describe a single SValue object. Sval files however have a special property; you can specify a loader tag to tell the engine which script function to load the sval with. These are called SValue Loaders. Using this loader, we can make the file load item definitions. For example, we can make an sval file containing this to add 2 items, a "Quad Damage" item and a "Staff of Awesomeness".

<loader>AddItemFile</loader>
<dict>
  <dict name="quad-damage">
    <string name="name">Quad Damage</string>
    <string name="desc">Everything does 4 times as much damage.</string>
    <string name="quality">rare</string>
    <int name="cost">7500</int>

    <bool name="has-blueprints">true</bool>

    <array name="icon">
      <string>items/awesome_items.png</string>
      <int>100</int><vec4>0 0 12 12</vec4>
    </array>

    <array name="modifiers">
      <dict>
        <string name="class">Modifiers::Damage</string>
        <float name="attack-mul">4</float>
        <float name="spell-mul">4</float>
      </dict>
    </array>
  </dict>

  <dict name="staff-of-awesomeness">
    <string name="name">Staff of Awesomeness</string>
    <string name="desc">You take half as much damage as normally.</string>
    <string name="quality">rare</string>
    <int name="cost">7500</int>

    <bool name="has-blueprints">true</bool>
    <bool name="can-attune">false</bool>

    <array name="icon">
      <string>items/awesome_items.png</string>
      <int>100</int><vec4>12 0 12 12</vec4>
    </array>

    <array name="modifiers">
      <dict>
        <string name="class">Modifiers::Armor</string>
        <float name="dmg-taken-mul">0.5</float>
      </dict>
    </array>
  </dict>
</dict>

Specified here is the name, description, quality, cost, and more information of the item. The icon is contained in a new image, because for this example I wanted to use a custom sprite as well. I quickly drew this with my great art skills in Aseprite:

The modifiers array here corresponds to a modifier script class. Here, Modifiers::Damage and Modifiers::Armor are used, which are built-in modifiers. There's a lot of modifiers you can choose from.

In the end, your mod's file structure might look something like this: