Race Functions - Grisgram/gml-raptor GitHub Wiki
Race offers some #macro definitions that will help you create more readable code.
They follow the same scheme as the functions: Some start with RACE_ and are here for you to be used and others are internal and start with __RACE.
| Macro | Description |
|---|---|
RACE_TABLE_QUERIED |
Holds the struct of the topmost table that started the current query. |
RACE_TABLE_CURRENT |
Holds the struct of the table where the dropped item is contained. |
RACE_ITEM_DROPPED |
Holds the race struct (race_result_entry) that just dropped. |
The RACE_TABLE_* macros may hold the same value, but in a recursive scenario, they might be different.
One instance where these macros become handy is the Create event of your RaceObjects. If RACE_TABLE_CURRENT is anything but undefined, you know that there is currently a query running, and if RACE_ITEM_DROPPED == self, you know that it was this currently running query that caused the Create event that is running. There might be situations where this can be of interest.
This is the heart of race on function level. With this function you create loot and drop items (= object instances) into the world.
NOTE: This function returns an array of Race Result Entry structs.
Alternatively to creating loot via a function call, you might consider Race Objects which allow you to drop loot more or less automatically through controller and table objects. Which method is preferable depends on the situation and type of game. According to my experience, it's a mixture of both.
/// @function race_query(table_name, drop_on_layer = "")
/// @description Performs a loot drop on this table.
/// @param {string} table_name The name of the table to query.
/// @param {string=""} drop_on_layer Optional. If not supplied or if this is an empty string, the
/// instance variable race_drop_on_layer will be used to determine
/// on which layer to drop the loot. This parameter can override
/// this instance variable (without changing it!) for this one query,
/// in case this time the items shall drop on another layer.
/// If this is an empty string, no instances will be dropped.
/// @returns {array} Returns the "loot". This is a struct of type race_result_entry.
/// It contains:
/// name = item name
/// type = objecttype (asset name)
/// data = race data_struct (enabled, chance, ...)
/// attributes = attributes of this item (= data.attributes)
/// instance = dropped instance (or undefined)
/// All contained instances already exist on the layer.
/// Their onCreate and onQueryHit events have already been executed.
/// If no drop was generated, instance contains undefined.These functions work on table and/or file level.
/// @function race_load_file(filename_to_load, overwrite_existing = true)
/// @description Loads race tables from the specified file into __RACE_GLOBAL.
/// NOTE: If you (re)load a file that has already been loaded, all tables
/// in memory that match tables in that file will be replaced by a new instance of the struct!
/// (in other words: reloading a file overwrites in-memory values, and your pointers
/// become invalid).
/// If you do not want that (if you want to preserve in-memory values), set the second
/// parameter of this function (overwrite_existing) to false.
/// @param {string} filename_to_load The file to load. RACE_ROOT_FOLDER will be used as prefix for the path
/// (default is "race/". See Race_Configuration script!).
/// ".json" will be appended for you.
/// @param {bool} overwrite_existing Defaults to true. If true, any already loaded table in memory will be reset
/// to the values loaded from file. Set to false to preserve any existing
/// in-memory states./// @function race_get_table(table_name)
/// @description Gets a race table from __RACE_GLOBAL.
/// If table_name is not found in the globals, undefined is returned.
/// @param {string} table_name The table to get
/// @returns {struct} The race table struct./// @function race_get_table_names()
/// @description Gets a list of currently loaded race table names.
/// This list also contains all names of dynamically created
/// tables through recursive queries.
/// Dynamically created table names always start with '$'
/// @returns {array} An array of all known race table names./// @function race_add_table(table_name, table_struct, overwrite_existing = true)
/// @description Adds a table to __RACE_GLOBAL.
/// This function can be used to import a table that has not been loaded
/// through a regular race file, but from somewhere else, maybe the savegame
/// or it has been created in code.
/// NOTE: Overwriting an existing table means: Another INSTANCE is assigned!
/// All your current pointers to table old table are
/// now invalid/target the wrong struct!
/// Make sure to call set_table() on all object instances of the
/// RaceTable object in your current room that use this table!
/// @param {string} table_name The name of the table to add.
/// @param {struct} table_struct The race table struct to add.
/// @param {bool} overwrite_existing Default=true. Overwrite the table in race if it does already exist./// @function race_table_exists(table_name)
/// @description Test whether the specified table exists and is loaded.
/// @param {string} table_name The table to get
/// @returns {bool} True, if that table exists and is loaded, otherwise false./// @function race_table_reset(table_name, recursive = false)
/// @description Resets a table to the original state when it was added or loaded from a file.
/// All temp-tables (clones from "+" types) are destroyed.
/// Referenced subtables ("=" types) are only reset if you set recursive to true.
/// If table_name is not found in the globals, undefined is returned.
/// @param {string} table_name The table to reset
/// @param {bool} recursive (Default false). Set to true to have referenced sub tables reset also.
/// @returns {struct} The reset race table struct./// @function race_table_clone(table_name)
/// @description Clones a race table and returns the new name.
/// Use this function if specific objects need their own
/// private copy of a table. Make sure, to remember the return value
/// of this function. The new name is your only access point to the clone.
/// @param {string} table_name The name of the table to clone. If it does not exist, undefined is returned
/// @returns {string} The name of the clone or undefined if table_name does not exist or is not loaded./// @function race_table_dump(table_name)
/// @description Dumps the table and all items to the debug console.
/// @param {string|struct} table_name The table to iterate over. Can be the name of the table OR the table struct/// @function race_table_foreach_item(table_name, func, args)
/// @description Iterates over all items of a table, calling a specified function
/// on each of the items. This method is similar to juju's foreach from SNAP
/// but only sends the name and the struct to the callback.
/// The function will receive 2 parameters:
/// item_name -> the name of the item
/// item -> the struct of the item from the table
/// @param {string|struct} table_name The table to iterate over.
/// Can be the name of the table OR the table struct.
/// @param {function} func The function to call for each item.
/// @param {any} args Optional. Provide any value or an array or a struct to be
/// passed to the function.
/// This parameter allows you to send additionally any parameter
/// to the function while iterating over the table.These functions retrieve or modify the table data.
/// @function race_table_get_item(table, item_name)
/// @description Gets a single item from the table.
/// NOTE: This method may crash if table does not exist or is not loaded!
/// @param {struct} table The table to search
/// @param {string} item_name The item to get
/// @returns {struct} The sub-struct containing the item's properties/// @function race_table_get_items(table)
/// @description Gets the items contained in a table.
/// If the table is not found, undefined is returned.
/// @param {struct} table The table to search
/// @returns {struct} The items sub-struct of the table./// @function race_table_get_item_names(table)
/// @description Gets the names of the items contained in a table.
/// NOTE: This method may crash if table does not exist or is not loaded!
/// @param {struct} table The table to search
/// @returns {array} A string array containing all item names./// @function race_table_get_loot_count(table)
/// @description Gets the loot count of a table.
/// If the table is not found, undefined is returned.
/// @param {struct} table The table to search
/// @returns {integer} The loot count of this table./// @function race_table_get_name(table)
/// @description Gets the name of a table.
/// If the table is not found, undefined is returned.
/// @param {struct} table The table to search
/// @returns {string} The name of the table.The functions listed here focus on items in a table.
These are symmetrical pairs of functions -- a _get_ and _set_ for each of the members. To avoid bloating up the documentation too much, only the _get_ function header is listed here.
For all _set_ functions: They accept an additional parameter new_value.
/// @function race_get_type(table, item_name)
/// @description Gets the type of an item.
/// NOTE: This method may crash if table does not exist or is not loaded!
/// If item_name is not found in the table, undefined is returned.
/// @param {struct} table The table to search
/// @param {string} item_name The item to retrieve the type
/// @returns {string} The type of the item./// @function race_is_always(table, item_name)
/// @description Gets the always state of an item.
/// NOTE: This method may crash if table does not exist or is not loaded!
/// If item_name is not found in the table, undefined is returned.
/// @param {struct} table The table to search
/// @param {string} item_name The item to retrieve the always state
/// @returns {bool} True, if this item is set to "always", otherwise false./// @function race_is_unique(table, item_name)
/// @description Gets the unique state of an item.
/// NOTE: This method may crash if table does not exist or is not loaded!
/// If item_name is not found in the table, undefined is returned.
/// @param {struct} table The table to search
/// @param {string} item_name The item to retrieve the unique state
/// @returns {bool} True, if this item is set to "unique", otherwise false./// @function race_is_enabled(table, item_name)
/// @description Gets the enabled state of an item.
/// NOTE: This method may crash if table does not exist or is not loaded!
/// If item_name is not found in the table, undefined is returned.
/// @param {struct} table The table to search
/// @param {string} item_name The item to retrieve the enabled state
/// @returns {bool} True, if this item is set to "enabled", otherwise false./// @function race_get_chance(table, item_name)
/// @description Gets the drop chance of an item.
/// NOTE: This method may crash if table does not exist or is not loaded!
/// If item_name is not found in the table, undefined is returned.
/// @param {struct} table The table to search
/// @param {string} item_name The item to retrieve the drop chance
/// @returns {real} The drop chance for this item./// @function race_get_attribute(table, item_name, attribute_name)
/// @description Gets a custom named attribute from an item.
/// NOTE: This method may crash if table does not exist or is not loaded!
/// If the attribute is not found, undefined is returned.
/// @param {struct} table The table to search
/// @param {string} item_name The item to retrieve the attribute from
/// @param {string} attribute_name The attribute to get.
/// @returns {any} {any} datatype, you must know what you get!
/// Custom attributes are not restricted!These functions work on item level too, but they accept an item struct as a parameter and not a table struct.
They are mostly used while iterating over the items of a table or when you retrieved an item struct via race_table_get_item(...).
/// @function race_item_get_type(item_struct)
/// @description Gets the type of an item.
/// @param {struct} item_struct The item to retrieve the type
/// @returns {string} The type of the item./// @function race_item_is_enabled(item_struct)
/// @description Gets the enabled state of an item.
/// @param {struct} item_struct The item to retrieve the enabled state
/// @returns {bool} True, if this item is set to "enabled", otherwise false./// @function race_item_is_always(item_struct)
/// @description Gets the always state of an item.
/// @param {struct} item_struct The item to retrieve the always state
/// @returns {bool} True, if this item is set to "always", otherwise false./// @function race_item_is_unique(item_struct)
/// @description Gets the unique state of an item.
/// @param {struct} item_struct The item to retrieve the unique state
/// @returns {bool} True, if this item is set to "unique", otherwise false./// @function race_item_get_chance(item_struct)
/// @description Gets the drop chance of an item.
/// @param {struct} item_struct The item to retrieve the drop chance
/// @returns {real} The drop chance for this item./// @function race_item_get_attribute(item_struct, attribute_name)
/// @description Gets a custom named attribute from an item.
/// If the attribute is not found, undefined is returned.
/// @param {struct} item_struct The item to retrieve the attribute from
/// @param {string} attribute_name The attribute to get.
/// @returns {any} {any} datatype, you must know what you get!
/// Custom attributes are not restricted!