ListPool - Grisgram/gml-raptor GitHub Wiki

This is a quite simple class contained in the Tools folder of the _gml_raptor_ section of the project template.
The StateMachine and the Animation class, both create one of these to manage their living instances.

raptor defines two macros (with a global variable behind), which are named STATEMACHINES and ANIMATIONS respectively.
The ROOMCONTROLLER owns those two ListPools and processes them in its Step event.


This means, the StateMachine and Animation classes only work, if you use a RoomController object (or a child of it) in your room!

A ListPool uses a ds_list internally, so you have to make sure, to call the destroy method on the ListPool when you no longer need it or you risk a memory leak in your game! For the two globally managed STATEMACHINES and ANIMATIONS this is done for you in the CleanUp event of the ROOMCONTROLLER.


The key element in this class (which you can use for your own purposes too, of course) is the process_all method, which will invoke a method on each element contained in the pool.
The ROOMCONTROLLER does exactly that in its Step event for all active StateMachines and all active Animations. Without that, no Animation would run and no StateMachine would receive its onStep callback.

In most Animations and StateMachines there is no need for a specific Step event, so under normal circumstances, this is no performance loss, as the Step methods are simply undefined. But in those cases, where you need to do things each step, especially in the StateMachines, it is extremely handy, that you do not have to write extra code and declare an extra event (which would have to check the current state) to make this work.

ListPool functions

ListPool constructor

/// @function			ListPool(_name = "listPool")
/// @description		Create a new ListPool. You must destroy this due to the use
///				of a ds_list internally or you risk a memory leak!
/// @param {string} _name	The name of the pool. For logging purposes only.

add

/// @function		add(obj)
/// @description	Adds an object to the pool (if it is not already contained)
/// @param {any} obj	The object to add

remove

/// @function		remove(obj)
/// @description	Removes an object from the pool
/// @param {any} obj	The object to remove

size

/// @function		size()
/// @description	Get the number of elements in the pool

clear

/// @function		clear()
/// @description	Remove all elements from the pool

destroy

/// @function		destroy()
/// @description	Destroy the ds_list that is used internally

process_all

/// @function		process_all(function_name = "step",...)
/// @description	Invokes the named function on each element in the pool
///			and forwards any additional parameters specified.
///			This is done via self[$ function_name]() and NOT through
///			script_execute which would be very slow.
///			NOTE: The function is called SCOPED in a with(list[| i])
///			statement which means "self" in the function is the owner
///			of the function.
/// @param {string} function_name The function to invoke on each element
/// @param {any...} up to 15 additional parameters that will be forwarded to the invoked function.

Tip

To optimize performance of the process_all method, there's a flag you can set on objects/structs to skip them from being processed. This is especially useful, if you have a large amount of items in a list pool and if you only want to process a subset of them.

Instead of doing a first-line-exit in the step-function (which is still a function call that will cost some CPU cycles, you can set

    __listpool_processible = false;

in any struct or object that is contained in the ListPool.
raptor uses this flag internal on its StateMachines. When they enter a state, that does not have a step function declared, this flag is set to false to increase processing speed of all existing StateMachines.


⚠️ **GitHub.com Fallback** ⚠️