Firing an effect: Emit, AbsoluteEmit, EnableEmit

Three calls fire an effect where it was built. A fourth starts one Animate cycle. Each needs Part_Icles:Activate() first. See Getting the module into a script.

To	Call
Fire a whole effect, as the Emit button of the HUD does	Part_Icles:AbsoluteEmit(item)
Fire one emitter with its own Emit count, Delay and Duration	Part_Icles:EnableEmit(item)
Make exactly one particle, now	Part_Icles:Emit(item)
Start one Animate cycle, now	Part_Icles:EmitAnimate(item)

To fire an effect somewhere else, use the EmitAt calls. To start a stream that stays on, use Enable or AbsoluteEnable.

The calls

On this page a stock emitter is a ParticleEmitter, Trail or Beam that the plugin has not transformed. A container is a Folder, Model, Part or Attachment that holds emitters.

Call	item	Other values	Gives back
Part_Icles:AbsoluteEmit(item)	An emitter, a stock emitter or a container	None	The seconds until the effect has finished, or nil. See The number given back.
Part_Icles:EnableEmit(item, link?)	One emitter	link: an instance. It may be left out.	Nothing
Part_Icles:Emit(item, link?)	One emitter	link: an instance. It may be left out.	Nothing
Part_Icles:EmitAnimate(item, link?)	One emitter	link: an instance. It may be left out.	Nothing

link may be a Part or MeshPart, a Model, an Attachment, a Bone or the camera. A Model is followed at its pivot. A Bone is followed at its animated pose.

With a link, the particles of that call follow it in place of the emitter’s own Link target. The emitter’s Link Mode still applies. Link describes the modes.

AbsoluteEmit

AbsoluteEmit plays everything in item once. Each emitter uses its own Emit count, Delay and Duration. The HUD’s Emit button and the Emit Code tool use this call.

What the call does depends on the kind of item.

item is	What happens
An emitter	The emitter fires as with EnableEmit. The call does not look at the emitter’s children. Emitters nested in its RenderTemplate fire with each particle it makes.
A stock ParticleEmitter	After its Delay it emits its Emit count. With a Duration above 0, its Enabled is then on for that many seconds. An Emit count that was never set counts as 1. Emit count 0 with Duration 0 emits nothing.
A stock Trail	It acts only with a Duration above 0. After its Delay, its Enabled is on for that many seconds. A Duration written "min,max" picks a random length.
A stock Beam	It acts only with a Duration above 0. After its Delay, its Enabled is on for that many seconds.
A Part, Attachment or Model that is not an emitter	Every stock emitter anywhere below it fires as above. Stock emitters inside an emitter are left out. The call then goes on into the children.
A Folder, or anything else	The call goes on into the children.

For a stock emitter, Emit count, Delay and Duration are the values of the HUD’s three boxes. They are kept on it as the attributes EmitCount, EmitDelay and EmitDuration. See Editing stock ParticleEmitters, Trails and Beams.

The Emit count, Delay and Duration of a container mean nothing. Only each emitter’s own values count.

CAUTION

A container fires every stock ParticleEmitter inside it, whether or not the plugin was ever used on it. Each emits one particle unless its Emit count was set. A character or the Workspace passed as item also fires emitters that are no part of the effect. Pass the effect’s own Folder or Model.

CAUTION

AbsoluteEmit does not look inside an ordinary Part that sits directly inside another ordinary Part. An emitter below such a Part is missed. Stock emitters below it still fire. Group the emitters of an effect with a Folder or a Model.

EnableEmit

EnableEmit fires one emitter with the values it was built with. It does not look at the emitter’s children.

Order	In Emit mode	In Animate mode
1	The call waits for the Delay.	The call waits for the Delay.
2	The emitter makes its Emit count of particles at once.	The emitter plays one cycle. The Emit count is not used.
3	With a Duration above 0, the emitter then streams at its Rate for that many seconds.	With a Duration above 0, Loop is on for that many seconds. The cycle then running finishes.

During the Duration the emitter’s Enabled is switched on. It is switched off when the Duration ends.

Emit

Emit makes exactly one particle from one emitter, at once.

Subject	What Emit does
Emit count, Delay, Duration, Enabled	It ignores all four.
Mode	It ignores the Mode. An Animate emitter still gives one ordinary particle.
A destroyed emitter, an ordinary Part, a Folder, a stock ParticleEmitter	Nothing happens.
A stock Trail or Beam with a Duration above 0	After its Delay, its Enabled is on for that many seconds.
The Particle Cap is reached	The particle is skipped. See Limits and helpers.

EmitAnimate

EmitAnimate starts one Animate cycle at once, whatever the emitter’s Mode reads.

Emitter made from	What happens	A second call while the cycle runs
A Part, Attachment, Beam, Model, Highlight or Trail	The emitter’s own RenderTemplate plays the cycle.	The cycle starts again from the beginning.
A Blur, Bloom, ColorCorrection, Atmosphere or ImageLabel	One cycle plays.	It is ignored.
Lightning, Camera Shake, Rocks, Rope, Distortion	One cycle plays.	It is ignored.
A Light or a Sound	Nothing happens. These emitters have no Animate mode.	Nothing happens.

If the emitter’s Loop is on, the cycle repeats until a stop call. See Starting, stopping and waiting.

Emit 0 with Duration 0 fires nothing

An emitter with an Emit count of 0 and a Duration of 0 has nothing to play. A new emitter starts with an Emit count of 1. An emitter made with an earlier version of the plugin can read 0 in both, and so can one whose count was set to 0.

Call	With Emit count 0 and Duration 0
EnableEmit, AbsoluteEmit	Nothing is made, and nothing is written to the Output window. An Animate emitter still plays its cycle.
Emit	One particle, as always.

To make such an emitter fire	Do this
In the editor	Select the emitter. Enter a number in the HUD’s Emit box or Duration box.
As a stream, from the script	Call Part_Icles:AbsoluteEnable(item).
For one play, from the script	Call Part_Icles:EnableEmitAt(item, item, { Count = 20 }).

One case differs. An emitter fired by an event fires once with an Emit count of 0. See Events.

What each call does with each kind of item

item	Emit	EnableEmit	AbsoluteEmit
One emitter	One particle	Its Emit count, Delay and Duration	Its Emit count, Delay and Duration
A container	Nothing	Nothing	Everything inside fires
A stock ParticleEmitter	Nothing	Not made for these	It fires, as in the table under AbsoluteEmit
A stock Trail or Beam	On for its Duration, if above 0	Not made for these	It fires, as in the table under AbsoluteEmit
An emitter nested in a RenderTemplate	It fires with the parent particle	It fires with each parent particle	It fires with each parent particle
An Animate emitter	One ordinary particle	One cycle after the Delay. A Duration keeps it looping.	One cycle after the Delay. A Duration keeps it looping.
An emitter that is destroyed or has no parent	Nothing	Nothing	Nothing fires. A number still comes back.

A second call on the same emitter

A burst with a Duration of 0 never disturbs another burst. Any number may overlap.

An emitter with a Duration above 0 runs one Duration at a time. A new EnableEmit or AbsoluteEmit on that emitter replaces the earlier one.

The earlier call is	After the new call
Still streaming	The earlier stream stops.
Still waiting out its Delay	The earlier call never fires.

The number given back

AbsoluteEmit gives back the time, in seconds, until the whole effect has finished.

Value	Meaning
A number above 0	The latest finish among everything fired.
nil	Some part of the effect never ends.
0	There was nothing to fire.

The number counts each emitter’s Delay, Duration, longest Lifetime and Linger. The emitter’s Timescale graph is taken into account. Emitters nested in a RenderTemplate are included.

For a stock ParticleEmitter or Trail it counts Delay, Duration and the longest Lifetime. For a stock Beam it counts Delay and Duration.

Two things make the answer nil. One is an Animate emitter with Loop on and no Duration. The other is a Timescale that is 0, or that never lets a particle reach the end of its life.

NOTE

The number is an estimate, worked out from the emitter’s settings at the moment of the call. A value entered as a range counts at its larger end. The number comes back even when nothing fired, as when the Particle Cap is reached.

NOTE

The first emit of an ImageLabel emitter waits until its image has loaded. The call does not return until then. Later emits of that emitter return at once.

Waiting for the effect

local seconds = Part_Icles:AbsoluteEmit(effect)
if seconds then
  task.wait(seconds)
end

Part_Icles.await(seconds) does the same in one line. It is written with a dot, not a colon.

Part_Icles.await(Part_Icles:AbsoluteEmit(effect))

Part_Icles.await is given	What it does
A number above 0	Waits that many seconds.
0, a number below 0, nil, or a value that is not a number	Returns at once.

CAUTION

An effect that never ends gives back nil. Part_Icles.await(nil) returns at once. It does not wait for such an effect.

To stop an effect before it finishes, see Starting, stopping and waiting.