Race Functions - coldrockgames/gml-raptor GitHub Wiki

Creating a Race instance

/// @func	Race(_filename, _load_async = true, _add_file_to_cache = RACE_CACHE_FILE_DEFAULT)
/// @desc	Create a new random content engine, optionally loading the file async
///		NOTE: When you load the file async, you may NOT use this race instance immediately after
///		creating it! Instead, you should add a callback through the on_load_finished(...) function
///		of this Race instance
///		Async loading should be the default and it should be done during game-startup
///		in the onLoadingScreen callback of the Game_Configuration script.
///		This callback handles all waiting and async management for you.
///		Recommendation: Load _all_ your Race files at startup async.
function Race(_filename = "", _load_async = true, _add_file_to_cache = RACE_CACHE_FILE_DEFAULT) constructor {

Instantiate by loading a file

Supply the filename, without extension as first argument.
You may choose to not load it async by setting the second argument to false.
NOTE: In this case, you will not receive the .on_load_finished callback!
The third and final argument tells raptor, whether it shall keep the file in the local cache
If the file is not found, an error is written to the log

Instantiate for building the table manually in code

Do not supply any arguments, just use var race = new Race(); to instantiate it

Read an Entire Tree of Race Files

In the Race_Configuration file, you set a RACE_ROOT_FOLDER (by default race/ in your included files directory).

Race offers a helper function to read this entire tree of files at startup into memory and create Race instances for each of them. This is, what most games do in their onLoadingScreenStarting() callback in the Game_Configuration of their game.

/// @func	race_read_tree_async(_file_task_callback = undefined, _folder = RACE_ROOT_FOLDER)
/// @desc	Reads an entire tree of race files recursively.
///		The folder read by default is the RACE_ROOT_FOLDER you set in the Race_Configuration file.
///		You receive a struct as return value but keep in mind, that this struct will
///		be filled async across several frames until all files are loaded and compiled,
///		but you should use it to store it in some global variable to gain access to all
///		race tables in one place.
function race_read_tree_async(_file_task_callback = undefined, _folder = RACE_ROOT_FOLDER) {

The file_task_callback will be invoked after every file loaded and it receives one argument: The Race instance created.

[!NOTE] As the name of the function tells, this is an async function. You can not access any Race instances in the code line after this one!
You must wait for the _file_task_callback to access the loaded race tables.

Race Functions

/// @func add_table(_race_table, _overwrite_if_exists = true)
/// @desc Add a class instance of type RaceTable to the tables of this Race
static add_table = function( _race_table, _overwrite_if_exists = true) {

/// @func get_table(_name)
/// @desc Retrieve a pointer to a table
///       Alternatively, you can access all tables directly through race.tables.tablename...
static get_table = function(_name) {

/// @func remove_table(_name, _clear_global_cache = false)
/// @desc Remove the specified table from this Race
///       The second argument tells race, if it shall even clear its cache
///       (If you set this to true, Race "forgets" the table entirely, you
///       have to load the entire file again, if you need this table again later)
static remove_table = function(_name, _clear_global_cache = false) {

/// @func reset_table(_name, _recursive = true)
/// @desc Reset the specified table to its original state it had, when it was loaded from the file
///       The second argument tells Race, whether it shall recursively even all sub tables to their
///       initial state
static reset_table = function(_name, _recursive = true) {

/// @func clone_table(_name)
/// @desc Clones the specified table to a TEMP table with a unique name. 
///	  This new table is returned and you can get the name from the .name property of the table.
///       Use this function to get an independent copy of any table
static clone_table = function(_name) {

/// @func table_exists(_name)
/// @desc Checks whether a table with the specified name exists in this Race
static table_exists = function(_name) {

/// @func on_load_finished(_callback)
/// @desc Register a function to be invoked when the async loading of this instance
///	  is finished.
static on_load_finished = function(_callback) {

/// @func	query_table(_name, _layer_name_or_depth = undefined, _pool_name = "")
/// @desc	Perform a loot query on the specified table
/// @returns {array}	Returns the "loot". This is an array of RaceItem instances.
///			Each RaceItem offers these properties:
///				instance	= The dropped instance (or undefined, if no layer was given)
///				table_name	= The name of the table, where it came from
///				item_name	= The item name in the table
///				item		= The item struct (also contains the .attributes)
///				
///			* All contained instances already exist on the layer.
///			* Their onCreate events have already been executed.
///			* If no drop was generated, instance contains undefined.
/// @param  {string} _name	The race table to query
/// @param  {string=""} _layer_name_or_depth	Optional. 
///			If not supplied, no items will be dropped by the query and all "instance"
///			members of the returned RaceItems will be undefined.
///			LOOT IS STILL GENERATED! There are just no items spawned.
/// @param {string=""} pool_name	Optional. If supplied, objects will be taken from the
///					specified ObjectPool, so less new instances are created.
static query_table = function(_name, _layer_name_or_depth = undefined, _pool_name = "") {

RaceTable Functions

Creating a RaceTable in code

Invoke the constructor, give the table a name and supply the table_struct.

[!NOTE] The table struct given, must match the Race File Specifications, so it must have:

a loot_count member

an items: { } struct

after creating it, add it to Race through race.add_table(...)

Alternatively you may create a correct empty table struct through new RaceTableStruct(_loot_count)

/// @func RaceTable(_name, _table_struct)
function RaceTable(_name = "", _table_struct = undefined) constructor {

/// @func	query(_layer_name_or_depth = undefined, _pool_name = "")
/// @desc	Perform a loot query
///		NOTE: If you do not supply a _layer_name_or_depth, NO INSTANCES
///		will be created by the query() function!
///		You can batch-create all instances from the result set through
///		create_instances(queryresult) on this table afterwards.
static query = function(_layer_name_or_depth = undefined, _pool_name = "") {

/// @func	reset(_recursive)
/// @desc	Reset this table to the state when it was loaded from file.
///		NOTE: Temp tables and manually added tables can not be reset!
static reset = function(_recursive) {

The RaceItem Class

Race offers a little convenience helper class, RaceItem, which allows you add new items with less typing.

To create the table struct, you can simply code the struct, as you would with any other struct:

race.add_table(new RaceTable("loot", {
	loot_count: 1,
	items: {
		item0: { type: "grp1_item0", chance: 10.0, enabled: 0, unique: 0, always: 0 },
		item1: { type: "grp1_item1", chance: 10.0, enabled: 0, unique: 0, always: 0 },
		item2: { type: "grp2_item2", chance: 10.0, enabled: 0, unique: 0, always: 0 },
		item3: { type: "grp2_item3", chance: 10.0, enabled: 0, unique: 0, always: 0 },
		nulldrop: { type: null, chance: 10.0, enabled: 0, unique: 0, always: 0 }
	}
}));

Alternatively, you can use the RaceItem class, which makes this a bit more compact:
In addition, there is another helper available, the RaceNullItem class, which allows you to add a null-drop to the table.

race.add_table(new RaceTable("loot", {
	loot_count: 1,
	items: {
		item0: new RaceItem("grp1_item0", 10, 0, 0, 0),
		item1: new RaceItem("grp1_item1", 10, 0, 0, 0),
		item2: new RaceItem("grp2_item2", 10, 0, 0, 0),
		item3: new RaceItem("grp2_item3", 10, 0, 0, 0),
		nulldrop: new RaceNullItem(10)
	}
}));

Manipulating item states

See more details about item filtering here: Race Item Filters.

/// @func filter_items(_items = undefined)
/// @desc Returns a new RaceItemFilter builder for all items of this table,
///       or for a subset of pre-filtered items, if you supply a filter result as argument
static filter_items = function(_items = undefined) {

/// @func set_all_enabled(_enabled, _items = undefined)
/// @desc Sets all items, or optionally a filtered item set, to the specified enabled value
static set_all_enabled = function(_enabled, _items = undefined) {

/// @func set_all_unique(_unique, _items = undefined)
/// @desc Sets all items, or optionally a filtered item set, to the specified unique value
static set_all_unique = function(_unique, _items = undefined) {

/// @func set_all_always(_always, _items = undefined)
/// @desc Sets all items, or optionally a filtered item set, to the specified always value
static set_all_always = function(_always, _items = undefined) {

/// @func set_all_chances(_chance, _items = undefined)
/// @desc Sets all items, or optionally a filtered item set, to the specified chance value
static set_all_chances = function(_chance, _items = undefined) {

/// @func set_all_chances_modify_by(_delta, _items = undefined)
/// @desc Modifies all chances, or optionally a filtered item set, by the specified delta
static set_all_chances_modify_by = function(_delta, _items = undefined) {

/// @func set_all_chances_multiply_by(_multiply, _items = undefined)
/// @desc Multiplies all chances, or optionally a filtered item set, by the specified multiplier
static set_all_chances_multiply_by = function(_multiply, _items = undefined) {

Continue reading in Race Item Filters.