Dungeon Souls Editor Quick Onboarding Modules Items Sprites Functions Steam Workshop Contact

Item Documentation

An item represents a Dungeon Souls item that is spawned in chests during runs. Items can have different classes, effects, prices and rarities, depending on what you desire. Keep in mind that an item will always have access to the current hero's data, such as health, damage, etc..

Game Variables

An item definition contains the following Game Variables:

Name Description Required
NAME The name of the item shown in-game. True
MAX_STACKS The maximum amount of stacks that the item can have. True
DESCRIPTION The description of the item shown in-game. False
SPRITE The sprite definition to assign to this item. True
TYPE The type of the item, which specifies the behaviour it will have. Can be one of the following:
  • "item_passive"
  • "item_active"
  • "item_consumable"
RARITY The rarity of the item, which determines on which chests it is allowed to be spawned. Can be one of the following:
  • "item_common"
  • "item_uncommon"
  • "item_rare"
  • "item_legendary"
  • "item_cursed"
PRICE The base price of the item. True
ON_PICKUP_FUNCTION The function to call when the item is picked up. False
ON_ACTIVE_FUNCTION The function to call when the item is activated, when rarity is "item_active" or "item_consumable". False
ON_STEP_FUNCTION The function to call at each step of the game, when rarity is "item_passive". False

Location and Extension

The item code is stored in the Dungeon Souls Item (.dsitem) file.

Description Format

In Dungeon Souls, items can have their description change depending on the amount of stacks the hero currently has. As such, the description of the item definition has a special format to support this case.

Anytime you want to specify another description, depending on the stack count, you should use the following format:

{first description here|second description here|...}

Depending if your description has a linear dependency on the stack count of the item, you can also use the following format to account for modularity in a easier manner:


Let's take a look at examples of these two formats. For the first format, let's say I have an item with the following description defined:

[DESCRIPTION]="{Increases your drop rate by a third|Increases your drop rate by a billion|You are the luckiest person ever.}";

With the previous description format, if its the first time the player is viewing the item description, then its description will be "Increases your drop rate by a third". However, if the player already had a stack count of two of this item, the description shown when picking the item the third time would be "You are the luckiest person ever.".

Similarly, the second format also completes the information, but this time around it is possible to define the description's behaviour, regardless of the max stacks defined. For example, let's consider the following description:

[DESCRIPTION]="Increases your max health by {2|+8} and reduces your defense by {2|+2}";

What this means is that, at first, the description will be completed to "Increases your max health by 2 and reduces your defense by 2". The second time the player picks the item, its description will be "Increases your max health by 10 and reduces your defense by 4". This happens because, for example, {2|+8} states to the engine that it should start with the value 2, then, for each stack count, add 8 to that value and complete the description.


Here follows an example of the definition of an item:

define item item_Red_Book
[NAME]="Red Book";
[DESCRIPTION]="+{4|+4} magical damage.";

#Place code here...