Race Objects - Grisgram/gml-raptor GitHub Wiki
Race comes with three objects:
RaceController |
A Saveable controller object that auto-loads and manages a race file for you |
RaceTable |
A Saveable race table that connects to a RaceController and offers a query(...) method |
RaceObject |
A Saveable item that can drop. All your lootables must be RaceObjects! |
NOTE: RaceTable and RaceObject are also StatefulObjects. See StateMachine for details on this.
There are two method variables defined in those objects which you may override (redefine) to have code executed when Race is active.
When you inherit any of those objects, look into the parent's Create event to see which of them are available for the object you are currently working with.
Here is the documentation and signature of those two callbacks:
/// @function onQueryStarted(first_query_table, current_query_table)
/// @description A query started (on this table or controller / depends on the parent object)
/// @param {race_table} first_query_table The struct of the topmost table that started the current query
/// @param {race_table} current_query_table The struct of the table that is currently queried/// @function onQueryHit(item_dropped, first_query_table, current_query_table)
/// @description An item got dropped
/// @param {race_item} item_dropped The race struct (race_result_entry) that just dropped.
/// @param {race_table} first_query_table The struct of the topmost table that started the current query
/// @param {race_table} current_query_table The struct of the table where the dropped item here is contained inThis is a controller item that will load a json-table when it gets created. The name of the file is specified in the race_table_file_name instance variable of this object.
Note
Using a RaceController in your game is totally optional!
If you do not use a controller item, you must load your json tables in code by calling race_load_file(...).
It will receive onQueryHit and onQueryStarted callbacks for every RaceTable object that has set this controller in its race_controller instance variable.
Treat them as global watchdog events to have one central point where all those events come together to count up achievement progress, centralized logging, or any other information to track.
None.
race_table_file_name |
Holds the file name of the json file this controller shall load when created. |
onQueryStarted |
Whenever any RaceTable that has this controller set in its race_controller instance variable is queried, this callback is invoked |
onQueryHit |
Whenever any item contained in any RaceTable that has this controller set in its race_controller instance variable is dropped, this callback is invoked |
This object is what games call a loot table.
It can receive both callbacks, onQueryStarted and onQueryHit.
Race is a recursive System, so a table can be contained in another table, limited only by the maximum depth of structs in GameMaker (128 levels as far as I know at the time of writing this).
query(drop_on_layer) |
To make the table "drop loot", call this function. The drop_on_layer parameter is optional and is used to override the race_drop_on_layer instance variable of this table in case you have a special loot situation that will not follow the normal loot rules.This function returns the same array of Race Result Entry structs as its function counterpart race_query |
set_table(table_name) |
Change the table this object is controlling. This table must be contained in the same race file as the previous table if you have attached this RaceTable object to a RaceController instance. A RaceController always controls only one single race file! |
race_controller |
If this variable is set to a RaceController object instance, all callbacks (onQueryStarted and onQueryHit) will also be forwarded to this controller instance |
race_table_name |
The name of the table this object will use when query() is invoked |
race_drop_on_layer |
The layer name where to drop item loot. This variable may be overruled (but not overwritten) with the optional parameter of the query() function |
onQueryStarted |
onQueryHit |
Tip
A great possibility of use for this object are spawners. Create a child of a RaceTable, set the variables, and let it act as a normal living game item in your game that reacts on events, has its states (see StateMachine), and spawns new items/enemies by simply invoking query().
You can even drop RaceTable instances (or children of them) from a query in another table to have random spawners being dropped in your scene.
A RaceObject is a Saveable StatefulObject (see Savegame System and StateMachine) and must be the parent of all objects that you want to drop through a RaceTable.
It can receive the onQueryHit callback.
None.
None.
onQueryHit |
Continue reading in Race Functions.