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.
/// @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.
/// @function add(obj)
/// @description Adds an object to the pool (if it is not already contained)
/// @param {any} obj The object to add
/// @function remove(obj)
/// @description Removes an object from the pool
/// @param {any} obj The object to remove
/// @function size()
/// @description Get the number of elements in the pool
/// @function clear()
/// @description Remove all elements from the pool
/// @function destroy()
/// @description Destroy the ds_list that is used internally
/// @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 StateMachine
s. 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 StateMachine
s.