Procedural Generation: Items

Flare v1.15 introduces a way to create "infinite" items by mutating existing items. This page will cover the options that are available to modders.

Level-scaled Values

First, it's important to familiarize yourself with the level_scaled_value syntax, since it is used for many of the base item properties as well as bonuses. The simplest form of a level-scaled value is one that simply defines the base value. As an example, let's set the base buy price of an item to 10. This can be written as:

price=base:10

But base is a special case. If we omit it, the value is treated as a base value.

price=10

Let's say we want the item to cost an additional 5 gold per item level. We can define our price as:

price=base:10,item_level:5

When we get to the part where we start randomizing the item, you'll probably notice some additional values delimited by colons. These values represent the maximum possible value and the "step". The step determines the increment between the randomized values. For example:

price=item_level:0:10:2

This will result in the price ranging from 0 to 10, in increments of 2 (so the possible values are 0, 2, 4, 6, 8, and 10).

Besides base and item_level, there is also player_level. As you might guess, it uses the player's level as a scaling factor.

Finally, there are a few other options to control the output value. Given this example:

price=base:1,10,0.5,round:true,min:2,max:5

round being set to true will round the output value to the nearest whole integer. min and max are used to clamp the output value on either end. So the example here would output a whole number between 2 and 5. Setting the min and max might seem useless in this specific example because base:2:5 would do the same thing. However, min and max are more useful when using a combination of base, item_level and player_level.

Randomizer Definitions

So we have an item that has a price dependent on its level. But the level for this item never changes. What if whenever we encounter this item, its level was different?

We begin by defining a randomizer_def for the base item, like so:

randomizer_def=items/random/example.txt

Now, any time this item is dropped, an item with a new ID (see Technical Details) is created and dropped in place of it.

Let's start with a basic randomizer definition:

[option]
chance=100
quality=normal
level_src=base
level_range=-2,2

[option]
chance=5
quality=high
bonus_count=1,2
level_src=base
level_range=-1,3

[bonuses]
bonus=hp,base:1:25,item_level:1:25
bonus=mp,base:1:3,item_level:1:3
bonus_power_level=122,base:1:2

When a randomized item is generated, one of the [option] sections is chosen at random based on their chance values. From there, the option will set the item quality, level, and number of bonuses.

• quality - The ID of a quality from items/qualities.txt
• bonus_count - The minimum and maximum number of bonuses.
• level_src - Determines how level_range will be applied. If base, the source item's level will be used. If hero, the player's current level will be used.
• level_range - The minimum and maximum level range, relative to the level referenced by level_src.

If we look at our example, 5% chance of getting a high quality item with 1-2 bonuses and a level between -1 and +3 of the base item's level. Otherwise, we'll get a normal quality item with a level between -2 and +2 of the base item's level.

Technical details

These randomized items are referred to as "extended" items internally. By default their IDs will start right after the last item ID from items/items.txt.

When you're developing your mod/game, it is wise to explicitly define where the IDs start in order to leave room for hand-crafted items. This can be defined in engine/loot.txt, like so:

extended_items_offset=3000

Since extended items can be placed in shared stashes, they are saved in their own file that can be read by all player characters. This file is extended_items.txt, located within your mod's save prefix. It contains item definitions much like those found in items/items.txt. The only difference here is that the id property has two values: the generated ID and the ID of the base item.