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

You are here:

Race - โœ”Race Flags - Race File Specs - Race Functions - Race Item Filters - RaceResult


Each race table has a property loot_count. It defines how many items will drop when this table is queried.
Each item 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.
If you set this to a negative value, the value is set to 0, when you start a query.
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.

loot_count

Defines how many items will drop from this table when it is queried.

Note

This value may be exceeded, if several items with the flag always = 1 are in the table!
See below at the always documentation.

enabled

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 filter 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!

Here's a short code example, how this could look in your code. Details about all this are explained in detail later, just keep on reading!

var subset = race.tables.monster_loot.filter_items()
    .for_attribute(function(a) { 
        return is_between(current_area_level, a.area_min_level, a.area_max_level); 
    })
    .execute();
race.tables.monster_loot.set_all_enabled(0);
race.tables.monster_loot.set_all_enabled(1, subset);

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 filter, you can generate entire random worlds with only a handful of race tables.

always

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.

Note

The always flag overrules the loot_count of a table!
If you set loot_count = 1, but have 3 always items in the table, the loot will always contain exactly all three of the always 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 (picked from all items, which are enabled = 1)

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.

unique

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.

How chance works

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. Almost all imaginable combinations are available for batch-processing chances on your loot items.


Tip

Let's combine the example of spawning monsters or dropping items based on the area_level, I showed in the enabled documentation above, with the knowledge of the chance property.
Nobody said, that the chance is constant or may not vary between queries. You could create an AnimCurve, that ranges from min_level to max_level (or 0..1 and you calculate the running value of the current area), and the curve value represents the chance!
With that, you could easily create an "increasing chance" for something to happen, the closer the player comes to the max_level of the area. This could be random mini bosses, elite monsters, special epic equipment, etc. You can create high dynamics in the chance value with designed AnimCurves for your race tables.


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


You are here:

Race - โœ”Race Flags - Race File Specs - Race Functions - Race Item Filters - RaceResult

โš ๏ธ **GitHub.com Fallback** โš ๏ธ