ObjectPool

class ObjectPool

Object pooling - a technique that might speed up your game if used properly.
If some of your classes will be instantiated and removed a lot at a time, it is a good idea to add the class to this object pool. A separate pool for that class will be created, which will reuse objects of the class. That way they won't be instantiated each time you need a new one (slowing your game), but stored into that pool and taking one already instantiated when you need it.

This technique is also used by the engine to instantiate objects defined in the map, which means, that on level loading the engine will try to instantiate every object found in the map, based on the user defined name in each Object Properties

See: pool the default global instance of ObjectPool

Summary

Methods from ObjectPool

boolean	exists(name: string)
number	getInstanceCount()
boolean	poolable(obj: object)
object	pull(name: string, args: unknown)
	purge()
boolean	push(obj: object, throwOnError: boolean)
	register(className: string, classObj: object, recycling: boolean)

Public Methods

exists pooling.js:135

exists(name: string) → {boolean}

Check if an object with the provided name is registered

Parameters:
Name	Type	Description
name	string	of the registered object class

Returns:
Type	Description
boolean	true if the classname is registered

getInstanceCount pooling.js:164

getInstanceCount() → {number}

returns the amount of object instance currently in the pool

Returns:
Type	Description
number	amount of object instance

poolable pooling.js:144

poolable(obj: object) → {boolean}

Check if an object is poolable (was properly registered with the recycling feature enable)

if (!me.pool.poolable(myCherryEntity)) {
    // object was not properly registered
}

Parameters:
Name	Type	Description
obj	object	object to be checked

Returns:
Type	Description
boolean	true if the object is poolable

See: register

pull pooling.js:51

pull(name: string, args: unknown) → {object}

Pull a new instance of the requested object (if added into the object pool)

me.pool.register("bullet", BulletEntity, true);
me.pool.register("enemy", EnemyEntity, true);
// ...
// when we need to manually create a new bullet:
let bullet = me.pool.pull("bullet", x, y, direction);
// ...
// params aren't a fixed number
// when we need new enemy we can add more params, that the object construct requires:
let enemy = me.pool.pull("enemy", x, y, direction, speed, power, life);
// ...
// when we want to destroy existing object, the remove
// function will ensure the object can then be reallocated later
me.game.world.removeChild(enemy);
me.game.world.removeChild(bullet);

Parameters:
Name	Type	Attributes	Description
name	string		as used in pool.register
args	unknown	<optional>	arguments to be passed when instantiating/reinitializing the object

Returns:
Type	Description
object	the instance of the requested object

purge pooling.js:95

purge() → {}

purge the object pool from any inactive object
Object pooling must be enabled for this function to work
note: this will trigger the garbage collector

push pooling.js:109

push(obj: object, throwOnError: boolean) → {boolean}

Push back an object instance into the object pool
Object pooling for the object class must be enabled, and object must have been instantiated using pool#pull, otherwise this function won't work

Parameters:
Name	Type	Attributes	Default	Description
obj	object			instance to be recycled
throwOnError	boolean	<optional>	true	throw an exception if the object cannot be recycled

Returns:
Type	Description
boolean	true if the object was successfully recycled in the object pool

register(className: string, classObj: object, recycling: boolean) → {}

register an object to the pool.
Pooling must be set to true if more than one such objects will be created.
(Note: for an object to be poolable, it must implements a onResetEvent method)

// implement CherryEntity
class Cherry extends Sprite {
   onResetEvent() {
       // reset object mutable properties
       this.lifeBar = 100;
   }
};
// add our users defined entities in the object pool and enable object recycling
me.pool.register("cherrysprite", Cherry, true);

Parameters:
Name	Type	Attributes	Default	Description
className	string			as defined in the Name field of the Object Properties (in Tiled)
classObj	object			corresponding Class to be instantiated
recycling	boolean	<optional>	false	enables object recycling for the specified class