Starting, stopping and waiting

This page covers the calls that keep an effect running, stop it, and change it while it runs. Part_Icles:Activate() and Part_Icles:Deactivate() are on Getting the module into a script.

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.

Starting

Call	`item`	What it does
`Part_Icles:Enable(item, link?, duration?)`	One emitter	Streams particles at the emitter’s Rate, for `duration` seconds. With no `duration` the stream has no end.
`Part_Icles:AbsoluteEnable(item)`	An emitter, a stock emitter or a container	Switches everything in `item` on and leaves it on.

Enable

Enable streams only while the emitter’s Enabled is on. With Enabled off, the call stops at once and makes nothing.

Subject	Behaviour
Rate	Read on every frame. A Rate of 0 or less makes nothing.
Emit count, Delay	Not used. There is no burst and no wait.
The stream ends when	`duration` has passed, Enabled goes off, the emitter is removed, or a stop call is made.
A second `Enable` on the same emitter	It replaces the first.
An Animate emitter	Loop is switched on and the cycle starts. Enabled is not consulted.
An instance that is not an emitter	Nothing happens.

link is as on Firing an effect.

AbsoluteEnable

AbsoluteEnable does not use the Emit count, Delay or Duration of anything.

Inside `item`	What happens
An emitter in Emit mode	Its Enabled is switched on. It streams at its Rate with no end.
An Animate emitter	Its Loop is switched on. The cycle starts.
A stock ParticleEmitter, Trail or Beam	Its `Enabled` is set to `true`.

The CAUTION under What “Absolute” means applies to AbsoluteEnable, AbsoluteDisable and the two Absolute timescale calls.

Stopping

A hard stop removes every particle at once. A soft stop makes no more particles and lets those in flight finish.

To	Call
Stop one emitter and let its particles finish	`Part_Icles:SoftDisable(emitter)`
Stop a whole effect and let its particles finish	`Part_Icles:AbsoluteDisable(container)`
Stop one play of an EmitAt call and let its particles finish	`handle:SoftDisable()`
Remove an emitter’s particles now	`Part_Icles:Disable(emitter)`
Remove a whole effect’s particles now	`Part_Icles:Disable(container)`
Remove one play’s particles now	`handle:Disable()`
Stop the whole module	`Part_Icles:Deactivate()`

Call	`item`	Kind of stop
`Part_Icles:Disable(item)`	An emitter or a container	Hard
`Part_Icles:SoftDisable(item)`	An emitter or a container	Soft
`Part_Icles:AbsoluteDisable(item)`	An emitter, a stock emitter or a container	Soft

What each stop does:

Subject	`Disable`	`SoftDisable` and `AbsoluteDisable`
The stream	Stops. Enabled and Loop are switched off.	Stops. Enabled and Loop are switched off.
Particles in flight	Removed at once, including those in their Linger time.	Left to finish their Lifetime and their Linger.
An Animate emitter	Snaps back to the look it was built with, and hides.	The cycle in progress plays to its end. The emitter then resets and hides.
Emitters inside `item`, nested ones included	Hard stop.	Soft stop.
Stock ParticleEmitters and Trails inside `item`	Switched off. A timed start still waiting is cancelled.	`Enabled` is set to `false`. Their particles fade as usual. A timed start still waiting is not cancelled.
Stock Beams inside `item`	Switched off.	`Enabled` is set to `false`.
A Delay still being waited out, on a play with a Duration above 0	Cancelled.	Cancelled.
A Delay still being waited out, on a play with a Duration of 0	Not cancelled. The burst, or the one Animate cycle, still fires when the Delay ends.	Not cancelled.

Disable and SoftDisable also switch off stock Highlights inside item. Disable leaves alone stock emitters that sit inside a RenderTemplate.

A stop call on an emitter also stops every play of that emitter made with EnableEmitAt or AbsoluteEmitAt. Disable removes the particles of those plays too. Their handles are not told. handle:Wait() on such a play still waits for its full Duration.

Disable and SoftDisable do nothing to a stock emitter passed by itself. AbsoluteDisable sets its Enabled to false.

A Disable called from an event script, before the script’s first wait, takes effect later in the same frame. It acts once every particle has been updated. SoftDisable acts at once. See The event script and its payload.

Waiting

After	Wait with
`Part_Icles:AbsoluteEmit(item)`	The number it gives back. See Waiting for the effect.
`Part_Icles:AbsoluteEmitAt(...)` or `Part_Icles:EnableEmitAt(...)`	`handle:Wait()`. It returns early if the play is stopped. See The play handle.

An effect that never ends gives back nil in place of a number. Check for nil before waiting.

Speed

The timescale calls change how fast particles run: their motion, their graphs and their Lifetime.

Call	`item`	What it does
`Part_Icles:SetTimescale(item, scale, duration?, permanent?)`	One emitter or one stock ParticleEmitter	Sets the speed for that emitter’s particles.
`Part_Icles:ClearTimescale(item)`	One emitter or one stock ParticleEmitter	Removes the speed set by the script. The emitter’s own Timescale applies again.
`Part_Icles:AbsoluteSetTimescale(item, scale, duration?, permanent?)`	An emitter, a stock ParticleEmitter or a container	The same, for the item and for every emitter and stock ParticleEmitter inside.
`Part_Icles:AbsoluteClearTimescale(item)`	An emitter, a stock ParticleEmitter or a container	Clears them all.

`scale`	Result
`1`	Normal speed
`0.5`	Half speed
`2`	Double speed
`0`	Frozen
Below 0	The particles play backwards

Part_Icles:AbsoluteSetTimescale(effect, 0.25, 2)
Part_Icles:AbsoluteSetTimescale(effect, 0.25, nil, true)
Part_Icles:AbsoluteClearTimescale(effect)

The first line sets quarter speed for 2 seconds. The second sets quarter speed until the third line clears it.

Subject	Rule
Which particles	Those in flight, and those made while the speed is in force.
The emitter’s Timescale graph	Replaced while the speed is in force.
A timed speed	Ends by itself after `duration` seconds of real time.
`permanent` set to `true`	`duration` is ignored.
Rate, Delay and Duration	Not changed. The speed changes how particles run, not how they are made.
Emitters nested in a `RenderTemplate`	Not affected by a call on the parent emitter. To slow a play with its nested particles, use `handle:SetTimescale`.
A stock ParticleEmitter	Its `TimeScale` property is set. The old value is put back afterwards.
`item` is `nil`, or `scale` is not a number	Nothing happens.

A speed set by a script is stored on the emitter. A permanent speed set from the command bar, in the editor, is saved with the place until it is cleared.

A permanent speed of 0 freezes particles in flight. A particle frozen part-way through its life never ends, and it keeps its place under the Particle Cap. Clear the speed, or call Part_Icles:Disable(item).

Links

Call	Values	What it does
`Part_Icles:SetLink(item, target, mode?)`	`item`: one emitter. `target`: an instance, the text `"camera"`, or `nil` for no link. `mode`: a Link Mode as text.	Changes the emitter’s own Link settings, for every later firing. These are the settings of the Link section of the Properties panel.
`Part_Icles:SetEmitParent(item, parent)`	`item`: one emitter. `parent`: an instance, or `nil` to go back to the starting place.	Changes the emitter’s Emit Into.

mode is one of "Follow", "Pivot", "Weld", "WeldWithoutRotation" and "RigidLocal". Link describes each.

SetLink does nothing when item is nil or is not an emitter.

To link one play only, pass Link in the options of an EmitAt call.

LinkService

Part_Icles.LinkService makes a Part, Model or Attachment follow another instance. No particles are involved.

Call	Gives back	What it does
`LinkService:Activate()`	Nothing	Starts the service. It may be called twice.
`LinkService:Deactivate()`	Nothing	Stops the service and ends every link. Linked parts get their `Anchored` state back.
`LinkService:Link(part, target, mode?, duration?)`	Nothing	Makes `part` follow `target` on every frame. `part` keeps the offset it had at the moment of the call.
`LinkService:Clear(part)`	Nothing	Ends the link of `part`. Its `Anchored` state is put back.
`LinkService:IsLinked(part)`	`true` or `false`	Says whether `part` is linked.

Value of `Link`	Accepted
`part`	A Part or MeshPart, a Model, or an Attachment
`target`	A Part or MeshPart, a Model, an Attachment, a Bone, or the camera
`mode`	`"Weld"`: position and rotation follow. It is used when `mode` is left out or is not known.
`mode`	`"Follow"`, `"Pivot"`, `"WeldWithoutRotation"`: position follows and the offset swings with the target. Rotation stays as it was. In this service the three are the same.
`duration`	Seconds. Left out, the link lasts until it is cleared.

local LinkService = Part_Icles.LinkService
LinkService:Activate()
LinkService:Link(lantern, hand, "Weld")

Subject	Rule
`Anchored`	`part` is anchored while linked. For a Model, all its parts are. The old values come back on `Clear`, when the `duration` ends, or when either instance is removed.
An Attachment as `part`	It moves only if its parent is a Part or MeshPart.
A second `Link` on the same `part`	It replaces the first. The `Anchored` value put back later is the one from before the first link.
`Link` called before `LinkService:Activate()`	The link is recorded and does nothing. Output shows one warning that begins `[Part-Icles LinkService] Link called before Activate();`.
Ignored without a message	A `nil` value. `part` and `target` being the same instance. A `part` of another class. Either instance without a parent.

Textures

Call	What it does
`Part_Icles:Preload(root, force?)`	Keeps textures loaded for `root` and everything under it. It covers every emitter, stock ParticleEmitter and stock Trail whose Preload Texture is on.
`Part_Icles:Deload(root, force?)`	Releases what `Preload(root)` held. A texture stays loaded while anything else still holds it.

Subject	Rule
`force` set to `true`	Everything under `root` is covered, whatever its Preload Texture reads.
Return	`Preload` returns at once. Loading goes on in the background. One exception: in the first moments of a LocalScript it can wait up to 5 seconds for the player’s PlayerGui.
What is covered	Decals, Textures, ParticleEmitters, Beams, Trails, ImageLabels, SpecialMeshes, MeshPart textures and the maps of a SurfaceAppearance. That holds for each item covered and for everything under it.
Where it works	In a LocalScript only. In a server Script both calls do nothing.
`root` is `nil`	Nothing happens.

Part_Icles:Activate() already does a Preload on a player’s machine. It covers emitters whose Preload Texture is on, and only those in place at that moment. It looks in Workspace, Lighting, ReplicatedStorage, StarterGui, StarterPack and ReplicatedFirst.

An effect added later is not picked up in a game. That holds for an effect made by a script and for one that arrives after Activate. Call Part_Icles:Preload(effect) on it.

Part_Icles:Deactivate() releases every texture.

Advanced lists which textures Preload Texture covers.

Limits and helpers

The Particle Cap

Part_Icles.MAX_ACTIVE_PARTICLES is a number. It starts at 1000.

Part_Icles.MAX_ACTIVE_PARTICLES = 3000

Subject	Rule
In the game	The cap is 1000 until a script sets it. ≡ ▸ Settings ▸ Particle Cap changes the cap in the editor only.
What counts	Particles in flight, and particles still showing in their Linger time.
What does not count	The particles of a stock ParticleEmitter.
At the cap	New particles are skipped until some end.
The value	The module does not check it.

At the cap the Output window shows this line, at most once a second. N is the cap.

[Part-Icles] active particle cap (N) reached  -  new emits skipped (user Module code still runs).

Other members

Member	Kind	What it is
`Part_Icles.Log.enabled`	`true` or `false`. Starts at `true`.	Set to `false`, it silences the module’s Output messages and warnings. Errors are never silenced.
`Part_Icles.Log.print(...)`, `Part_Icles.Log.warn(...)`	Calls	Write to the Output window through the same switch. A script may use them for its own messages.
`Part_Icles:GetFolder()`	Call. Gives back a Folder.	The folder that holds the particles in flight. It is named `EmittedPartsUsingPart_icle`. It is made on first use, and it is not saved with the place. It sits under the camera of the machine the script runs on.
`Part_Icles:GetPoolFolder()`	Call. Gives back a Folder.	The folder that holds the idle particles of emitters with Pool on. It is named `Part_IclesPooled` and sits beside the first.
`Part_Icles:GetData(item)`	Call. Gives back a table, or `nil`.	The emitter’s settings, as the module reads them at each emit. `nil` for an instance that is not an emitter. The table is the module’s own. Read it only. Its field names can change between versions.
`Part_Icles.ActiveEmits`	A list. Read it only.	`#Part_Icles.ActiveEmits` is the number of particles in flight. The plugin’s particle counter shows the same number.
`Part_Icles.TransformCompleted`	A BindableEvent	Its `Event` runs with the new emitter after each successful `Transform`.
`Part_Icles.parseDuration(value)`	Call. Gives back a number, or `nil`.	Reads a Duration as the HUD ▸ Duration box does. A number comes back as it is. Text of two numbers, such as `"1, 2"`, gives a random value between them. Text with no number gives `nil`.

Every particle carries the attribute _PartIcleEmit, set to true. A script that watches the Workspace can use it to tell a particle from the rest of the place.

The module has no call for the pool. Pooling is the emitter’s own Pool toggle, described on Advanced. An idle particle is discarded after 5 seconds without use. One emitter keeps at most about six times its Rate, plus 8. All emitters together keep at most 2048. Part_Icles:Deactivate() empties the pool. What mesh particles give and what they cost gives every rule.

Transform from a script

Part_Icles:Transform(item) turns an instance into an emitter, as the Transform button does. It gives nothing back.

Subject	Rule
Undo and selection	The call makes no step in Studio’s undo history and does not change the selection.
An emitter, or a class the plugin cannot transform	Nothing happens.
The new emitter	Emit count 1, Duration 0, Enabled off.
The types of the Transform as menu	The call does not choose them. Make these in the editor.

For AbsoluteEmit, a new emitter fires one particle. To change the size of the burst, set the emitter’s EmitCount attribute. The next section lists the attributes.

Attributes a script may read or write

Name	Where	Kind	Meaning
`EmitCount`	The emitter. Also a stock ParticleEmitter.	Number	Particles in one burst. Missing counts as 1. 0 means no burst.
`EmitDelay`	The emitter. Also a stock ParticleEmitter, Trail or Beam.	Number	Seconds before firing.
`EmitDuration`	The emitter. Also a stock ParticleEmitter, Trail or Beam.	Number, or text `"min,max"`	Seconds of stream after the burst.
`EmissionMode`	The emitter	Text: `"Emit"` or `"Animate"`	The Mode.
`AnimateLoop`	The emitter	`true` or `false`	The Loop of an Animate emitter. `Enable` and the stop calls write it.
`Enabled`	The emitter’s `PartIcleProperties`	`true` or `false`	The Enabled row. `EnableEmit` writes it during a Duration. `AbsoluteEnable` and the stop calls write it.
`Rate`	The emitter’s `PartIcleProperties`	Number	Read on every frame while the emitter streams.
`PreloadTexture`	The emitter. Also a stock ParticleEmitter or Trail.	`true` or `false`	The Preload Texture toggle.
`LinkMode`, `LinkSource`	The emitter	Text	Set them through `SetLink`, not by hand.
`Link`, `EmitParent`	ObjectValue children of the emitter	Instance	Set them through `SetLink` and `SetEmitParent`.
`Transformed`	The emitter	`true` or `false`	How the module knows an emitter.

Every other row of the Properties panel is an attribute on PartIcleProperties. The Property reference lists the names.

A value set by a script takes effect on the next particle made. Particles in flight keep what they had. See Edits and particles in flight.