Race Flags and the Chance - Grisgram/gml-raptor GitHub Wiki

Each race table has a property loot_count. It defines how many items will drop when this table is queried.
Each race entry in a table has three flags, enabled, always and unique, as well as a chance value.

loot_count is an integer value and should be zero or greater. It is undefined (not tested and makes no sense) if you set this to a negative value.
The flags are booleans, which means in terms of a json file, 1 = true and 0 = false.

Even though race tables are created through a json config file, they are all but read-only!
Race is designed for manipulating these tables at runtime.

There is a get... and a set... function for each single entry, property, or value a race table contains.

Defines how many items will drop from this table when it is queried.
NOTE: This may not be true, if several items with the flag always = 1 are in the table! See below at the always documentation.

Any item in a race table can be enabled or disabled.

The thought behind this flag is:
Say, you build a loot table of all weapons in your game (or all armor, or even all monsters). You would not want the player to find the "ultimate legendary raid boss endgame weapon" by beating a critter rabbit in the level 1 dungeon of the starting area of your game.

So, you will very likely have attributes on all those items. Two of them might read area_min_level and area_max_level which define in what level range this item can drop.
When calculating loot after a monster has been slain, you loop through the table and set all items to enabled = 1 where their area_min_level and area_max_level covers the area level of the current region where your player is, and you set all others to enabled = 0 and voilá: You can be sure the player cannot find that legendary weapon in this poor rabbit!

This example works 1:1 if you create random maps or want to spawn random monsters in a dungeon/an area. In a race-organized game, you will have one or more race tables containing monsters, treasures, etc. So, when creating the level, you enable/disable all monsters and treasures whose area_level fits (or does not fit) the area level you are generating. With a simple loop, you can generate entire random worlds with only a handful of race tables.

If you set always = 1 on an item, it will drop, guaranteed, every time this table is queried.

The thought behind this flag is:
It could be a random amount of gold/coins that will drop from every monster, or it could be quest items that become enabled for specific monsters in a specific area if the player is currently active on this quest. If you want every monster to drop one of the quest items, then you should use always.

The always flag overrules the loot_count of a table!

If you set loot_count = 1 on the table but it contains 5 items that are always = 1, each query will deliver exactly those 5 items!
This is necessary for scenarios like the one above (quest items for instance).

The calculation during the query of a table works like this:

• First, all always = 1 items are added to the result set
• Next, the number of items in the result set is subtracted from loot_count
• If loot_count is still greater than zero, that many random picks will drop

Example:

• loot_count = 5
• 2 items are always = 1
• those two items get added to result set
• 5 - 2 = 3 items remaining
• the result set gets filled up with three random picks

Those remaining random picks could again be some of the already dropped always = 1 items! In that case, multiple copies of this item would drop, unless you set it to unique = 1. See below.

Defines, whether an item can be part of the result set only once or multiple times.
This does not mean that it's a guaranteed drop. It just means that if this item gets selected by a query, it is selected only once.

You can combine all of these flags freely.

I said in the introduction of the Race pages that Race is a weighted randomizer. Let's take a closer look at this.

When you query a table, it looks through all the items contained in the table and builds the sum of all chance-values.
So, in a table with 2 entries, each with a chance of 10, the sum is 20.
This means that each entry has equal chance of 50%, or, in other words, a chance of "10 out of 20".
If you set the chance of one of these to 5, it only has a 33% chance ("5 out of 15"), and the other one a 66% chance ("10 out of 15").

This chance system allows you to weight drops in relation to all other items in the table. There are helper functions available to modify or multiply all chances by a given amount or to modify only enabled items. Almost all imaginable combinations are available for batch-processing chances on your loot items.

---

---

Now that you know what flags and settings exist, it is time to take a closer look at the Race File Specifications.