Race Functions - Grisgram/gml-raptor GitHub Wiki

Creating a Race instance

/// @func Race(_filename_without_extension, _add_file_to_cache = false)
/// @desc Create a new random content engine
function Race(_filename = "", _add_file_to_cache = false) constructor {

Instantiate by loading a file

Supply the filename, without extension as first argument.
The second 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

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	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(...)

/// @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
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.