Race Item Filters - Grisgram/gml-raptor GitHub Wiki

Item filters in Race follow the builder pattern, which means, they are a group of chainable functions, which you may combine freely to build the item filter you need for your next set_all_* call.
A filter must be completed by a call to .build();, which is a common finalizer for builder pattern classes.

How to create a filter

A filter, or subset of items in a table is started by calling table.filter_items().
This method creates a filter attached to the items of the table.

You can then combine any of these filter functions (see a full example at the end of this page):

/// @func for_name(_name_wildcard)
/// @desc Filters item names by a string_match pattern, like "monster*" or "*treasure"
///       A wildcard may contain a `*` at the beginning, the end, or both.
static for_name = function(_name_wildcard) {

/// @func for_type(_type_wildcard)
/// @desc Filters item types by a string_match pattern, like "monster*" or "*treasure"
///       A wildcard may contain a `*` at the beginning, the end, or both.
static for_type = function(_type_wildcard) {

/// @func for_always(_always)
/// @desc Supply 1 or 0 as _always
static for_always = function(_always) {

/// @func for_unique(_unique)
/// @desc Supply 1 or 0 as _unique
static for_unique = function(_unique) {

/// @func for_enabled(_enabled)
/// @desc Supply 1 or 0 as _enabled
static for_enabled = function(_enabled) {

/// @func for_chance(_predicate)
/// @desc The predicate receives the chance of the item
static for_chance = function(_predicate) {

/// @func for_attribute(_predicate)
/// @desc The predicate receives the entire attributes struct
static for_attribute = function(_predicate) {

Predicate functions

The .for_chance and .for_attribute filters take a predicate function as argument.
These are functions, that receive one argument and must return a bool value.

Return true to include the item in the result set
Return false to skip it

Here is an example for a chance predicate, which will include all items with a chance less than 100 to the result set:

var subset = mytable.filter_items().for_chance(
    function(chance) {
        return chance < 100;
    })
    .build();

Here is an example for an attributes predicate, which will include all items, which have an attribute value min_level greater than or equal to the current area level:

var subset = mytable.filter_items().for_attribute(
    function(attrs) {
        return attrs.min_level >= area_level; // area_level is assumed to be a variable in your game
    })
    .build();

Build

[!NOTE] All filters must end with a call to .build()!
This function builds the subset by applying all filters to all items of the table

/// @func build()
/// @desc Executes the filter and returns a struct with matching items
static build = function() {

Example

Here is an example for a query to a table that contains monsters. Only beast and undead monsters shall appear in that imaginary level. To avoid clustering of too many monsters of the same type, they all shall have a maximum chance of 100, and, if they are elite monsters, their level must be 20 or less.

Look closely, this example creates a sub-filter of another filter. This means, only the items, that passed the first filter will be processed in the second filter. This way, you can build hierarchical filters, or manipulate only a subset of pre-filtered items.
In this example, it is used, to reduce the chance to 100, but only for the items, that have been filtered by the first pass (beasts, undead and elites < level 20).

var table = race.tables.monsters;
table.reset();
table.set_all_enabled(0);

var subset_monsters = table.filter_items()
    .for_attribute(function(attrs) { 
        var rv = is_any_of(attrs.monster_type, "undead", "beast");
        if (attrs.elite == 1 && attrs.level > 20) rv = false;
        return rv;
    })
    .build();

var subset_chances = table.filter_items(subset_monsters)
    .for_chance(function(chance) { return chance > 100; })
    .build();

table.set_all_enabled(1, subset_monsters);
table.set_all_chances(100, subset_chances);

var spawns = table.query(); // contains only beasts and undead and elites < level 20 with a max-chance of 100