Multiple Emitters - Grisgram/gml-raptor GitHub Wiki

As explained at the beginning of Emitter Functions, each emitter is a unique instance of an emitter object.
To distinguish them, you can give them a name. However, you do not always want to create an empty, new emitter. In most cases, you want to create a copy of an emitter, you defined in the Particle Editor, a clone.

In fact, it is a very rare case, that you have only one emitter of a specific type. In most cases, you will have several clones active in your scene. Think about thrust beams of space ships (each ship has its own beam), multiple torches, whatever.

Not only can you clone emitters with the ParticleManager, you can even attach them to specific object instances in your scene and make them follow the instance automatically! The thrust beam of a ship will follow the ship without any coding needed.

Let's take a closer look:

Whenever you clone an emitter, a new Emitter object is created in your scene. The default object is the ParticleEmitter, provided in the _gml_raptor_/_generic_objects_ folder of the project template.
It may be the case, that you created one or more child objects from this default ParticleEmitter, that do specialized things needed in your game.
With this function you can set, with object shall be instantiated, when you clone something. The only rule to obey is, that it must be a child of ParticleEmitter (or the ParticleEmitter itself).

/// @function		set_emitter_object(_emitter_object)
/// @description	Set an object type to use when attaching or cloning emitters (default = ParticleEmitter)
static set_emitter_object = function(_emitter_object) {

/// @function		reset_emitter_object()
/// @description	Reset the emitter object to the default ParticleEmitter
static set_emitter_object = function(_emitter_object) {

This one creates a free floating clone, not bound to any object. If your game design is not interested in specific names of your emitters, you may omit the new_name parameter. In this case, a unique string is created for you.

/// @function		emitter_clone(name_or_emitter, new_name = undefined)
/// @description	clone an emitter (and its range) to a new name
/// @returns {Emitter}	The cloned emitter
static emitter_clone = function(name_or_emitter, new_name = undefined) {

Here you find the promised automatic follow option! By attaching an emitter to an existing instance in your scene, you can make this emitter auto-follow the instance (i.e. the space ship that "owns" the thrust beam), but supplying true for the follow_instance argument.
For more information on how to adapt the offset between the emitter and its parent, it is following, see the details at The ParticleEmitter Object.
However keep in mind, that this attaches the one existing emitter to the instance. If you have multiple ships rendering a thrust beam, you might want to use emitter_attach_clone (see below).

/// @function		emitter_attach(
///				name_or_emitter, instance, layer_name_or_depth = undefined, 
///				particle_type_name = undefined, 
///				follow_this_instance = true, use_object_pools = true)
/// @description	Attach a new ParticleEmitter instance on the specified layer to an instance
///			with optional follow-setting.
///			NOTE: If you need more than one emitter of this kind,
///			      look at attach_emitter_clone
/// @returns {ParticleEmitter}	the created object instance on the layer
///				for cleanup if you no longer need it
///				(use pool_return_instance if you have use_object_pools = true!)
static emitter_attach = function(
				name_or_emitter, instance, layer_name_or_depth = undefined, 
				particle_type_name = undefined,
				follow_this_instance = true, use_object_pools = true) {

This function does the same as emitter_attach above, with one important difference:
It creates a clone of the specified emitter first and attaches the clone to the instance!
In most cases you will use this function over emitter_attach, as it's a rare case, that you only have one single emitter of any kind.

/// @function		emitter_attach_clone(
///				name_or_emitter, instance, layer_name_or_depth = undefined, 
///				particle_type_name = undefined, 
///				follow_this_instance = true, use_object_pools = true)
/// @description	Attach a clone of an existing ParticleEmitter instance on the specified layer 
///			to an instance with optional follow-setting.
///			NOTE: If you need more than one emitter of this kind,
///			      look at attach_emitter_clone
/// @returns {ParticleEmitter}	the created object instance on the layer
///				for cleanup if you no longer need it
///				(use pool_return_instance if you have use_object_pools = true!)
static emitter_attach = function(
				name_or_emitter, instance, layer_name_or_depth = undefined, 
				particle_type_name = undefined,
				follow_this_instance = true, use_object_pools = true) {

The final chapter: The ParticleEmitter Object