Creating an Item

## Item Definition

In **Dungeon Souls**, items are objects that aid the player during runs. These can behave in one of three ways:

* **Passive Effect**: stat increases or special actions that occur during specific events;
* **Active Effect**: stat increases or special actions that occur when the player triggers its active item ability. The player can only have one active item at a time;
* **Consumable Effect**: stat increases or other usually less significant actions that occur when the player consumes the item (triggering its active item ability). Consumable items can stack.

Items are found in chests and can sometimes be dropped by monsters and other special items. Depending on their **rarity** (*denoted by their outline color*), items can only spawn in certain chests. Usually, the rarer the item is, the more powerful the effect is. Each item can have one of the following rarities:

* **Common**: common items with normal/simple effects, spawning frequently in regular chests;
* **Uncommon**: these are less common than **Common** items, but can still spawn in regular chests;
* **Rare**: items that are rare to spawn, whose effects are quite powerful. These usually spawn in higher-end chests;
* **Legendary**: items with dramatic effects, spawning only in the rarest chests (or occasionally on the shop keeper);
* **Cursed**: items that usually give an *over-powered* effect, but have a terrible downside. These items only spawn in **Cursed Chests**

An **item** can be defined in one of the following ways:

1. Right-click on the target project, then select *Create New...>Item*
2. Selecting the desired target project on the Project Tree, then clicking the quick action **New Item**

After a request to create a sprite has been performed, a window will appear, asking the following set of information:

* **Name (required) -** The name of the item, which will be shown in-game.
* **Description (required)-** The description of the item that will be shown during game.
* **Max Stacks (required) -** The maximum amount of times the item stacks (a.k.a. the amount of times the player can pick up the same item).
* **Price (required) -** The base price of the item (when sold in shop). The price scales with the dungeon's level.
* **Type (required) -** The type of item.
* **Rarity (required) -** The rarity of the item.
* **onItemPickup Function -** The function to call when picking up the item.
* **onItemActivated Function -** The function to call when the player activates the item (only for active and consumable items).
* **stepTick Function -** The function to call at each step (only for passive items).

In this tutorial, we'll fill the information as follows:

* **Name (required) -** Life Alchemy Gem.
* **Description (required)-** [ACTIVE] Kills all nearby enemies and#converts their deaths into max hp
* **Max Stacks (required) -** 1
* **Price (required) -** 600
* **Type (required) -** item\_active
* **Rarity (required) -** item\_legendary
* **onItemActivated Function -** lifeAlchemyGemActiveFunction()

After filling the information, the editor should generate the following code:

```
define item itm_Life_Alchemy_Gem
{
[NAME]="Life Alchemy Gem";
[MAX_STACKS]=1;
[DESCRIPTION]="[ACTIVE] Kills all nearby enemies and#converts their deaths into max hp";
*//[SPRITE];*
[TYPE]="item_active";
[RARITY]="item_legendary";
*//[ON\_PICKUP\_FUNCTION];*
[ON_ACTIVE_FUNCTION]=lifeAlchemyGemActiveFunction();
*//[ON\_STEP\_FUNCTION];*

*//Place function declarations here...*
}

```

Despite the editor generating a lot of the code for the item, we still need to do a few changes:

* Set the sprite of the item (*to which we just need to set it as sprLifeAlchemyGem, as defined previously*);
* Define the **lifeAlchemyGemActiveFunction** that will be executed when the player activates the item.

It is important to note that, due to the way '*Game Maker Studio 1.4**(*****Dungeon Souls** *native game engine*), the special character **#** seen in the item's description corresponds to the new line operator, creating a new line at the specified place. For example, the example **"This is a line#This is another line"** would produce the following text:

```
This is a line
This is another line

```

Function definition is slightly more complicated (since it will be the first time we also introduce coding concepts). As such, the next subsection will provide a bit more information of the function that we need to define in our **Life Alchemy Gem** item.

## Function Definition

In **DSML**, functions are, in a nutshell, blocks of code that can be called by other blocks of code. The difference between regular blocks of code and functions is that functions can accept input values (*known as arguments*), as well as produce an output value (*known as the function's return value*). Functions are useful for a wide variety of reasons, since they allow for code to be reused.

One of the possible uses is to keep the **code modular and easy to understand**. Let's briefly explore this concept in a simple example. Let's assume that we're making a piece of code where we need to use the total defense of the player several times. We'll also assume, for now, that the player only has defense and magic resist. As such, the code would look something like this:

```
...
defensePercentage=defense/(defense+resist);
resistPercentage=resist/(defense+resist);

...

```

In the example above, we're calculating what percentage does the 'defense' stat occupy from the player's total defense and doing the exact same thing for the 'resist' stat. At a first glance, this bit of code might seem okay, but shortly becomes a problem when we ask ourselves a simple question: What if the total defense of the player changes over time?

For example, it's perfectly plausible to think that the total defense of the player might include bonus defense or bonus resist (or some other variable that we do not know yet). If this happens, this means we'll have to change **all**lines of code that calculate the total player's defense. This is where functions come in handy. If we had a function that would return the total defense of the player, then we would only need to make changes in one place! Such a function could be defined as follows:

```
define function totalPlayerDefense
{
functionOutput result;
*//...*
result=defense+resist;
}

```

And done! With the function above, we would replace our existing code with the following:

```
...
defensePercentage=defense/totalPlayerDefense();
resistPercentage=resist/totalPlayerDefense();

...

```

As we can see, not only is it easier make any changes to the total player defense behaviour, as it is also easier to know what our code is doing! Even though this is a small example, **keeping this kind of mindset is highly encouraged and recommended**, as it will make your life easier in the future.

Now, back to the definition of our **lifeAlchemyGemActiveFunction**! Remember that our item is supposed to kill all nearby enemies and then increase the maximum health of the player by the amount of enemies killed. This effect can be composed into smaller tasks that make it easier for us to code the behaviour:

* Start the enemy kill count with the value zero;
* Get all enemies within a certain radius;
* For each enemy found:

* + Kill the enemy;
	+ Add 1 to the enemy kill count;
* Get the player's maximum health;
* Add the kill count value to the player's maximum health;
* Set the player's new maximum health;

Now that we've described the foundations of our code into simple tasks, it's time to translate these tasks into something the machine can understand (*in this case, translate it into* *DSML*)! We can do this as follows (*feel free to take your time analyzing the code*):

```
define function lifeAlchemyGemActiveFunction
{
*//We'll start by getting a list of all the enemies in a 96 radius of the player*
playerX = getPlayerAttribute("x");
playerY = getPlayerAttribute("y");
enemyList = enemiesInRadius(playerX,playerY,96); *//enemiesInRadius returns an id to a list that contains all enemies found in a specific radius.*
enemyCount = 0;
*//Start the variable that will count how many enemies we've killed. Now, we'll cycle through it using a for statement.*
size = listSize(enemyList);
for (i=0:i<size;i=i+1)
{
enemy = listGet(enemyList,i); *//Get the id of the enemy*
enemyKill(enemy);
enemyCount = enemyCount+1; *//Count one more enemy killed*
}
maxHp = getPlayerAttribute("hpmax");
maxHp = maxHp+enemyCount; *//Add the amount of enemies killed to the player's max hp*
setPlayerAttribute("hpmax",maxHp); *//Set the player's max hp*
listDestroy(enemyList); *//Every list allocates memory in the game. When we no longer need it, we destroy it!*
}

```

If you have any questions about the code presented previously, you should visit the reference links that explain what each function does. Apart from the function, the only more complex piece of code is the **for statement**. This statement is used when you intend to cycle a fixed amount of times and you need to know which iteration you're currently at. A translation of the for statement is as follows:

```
for (i=0 <start by setting a value to a variable>;
i<10 <keep running the code after the for statement until this condition is false>;
i=i+1 <at the end of each iteration, execute this block of code>)
{<the block of code to execute at each iteration. The variable initialized will hold the value of the current iteration (in this case, the variable i)>}

```

And that's it! Our item is finally complete! You can now test your item by pressing the **Play Button**. It will load the game in a special room where you can test your mods at ease. Pressing the **F2 key** will allow you to spawn the items of your module. Next, we'll learn how to publish your module!