Events

An event is a moment in a particle’s life that the emitter can act on. At that moment the emitter can fire another emitter, run a script, or both. On Hit can also remove the particle, hold it in place or bounce it. Exercise 12 uses an event for the first time.

What it makes possible:

Sparks where a bolt lands. A Lightning emitter in Seek, On Hit on, Emit set to a spark emitter, Mode AtPosition.
Debris that bounces, tips onto a face and comes to rest. A Part emitter with an Acceleration, On Hit on, Collide Bounce.
An arrow that sticks in a wall. On Hit on, Collide Stop.
A bullet that vanishes in a puff. On Hit on, Collide Kill, Emit set to a puff emitter, Mode AtPosition.
An explosion built from several emitters in a Folder, fired at each impact with its layout intact. Pick the Folder in Emit. Mode AtCFrame turns the layout the way the projectile was flying.
A stream that follows a flying particle. On Emit on, Emit set to an emitter with a Duration, Mode AtPosition.
A firework in stages. On Death fires a burst emitter, and that emitter’s own On Death fires the next stage.
Projectiles that pass through the character that shot them. Hit Filter ▸ + Add Exclude, then pick the character.
Game logic on impact. A script on On Hit reads the part that was touched and the contact point. See The event script and its payload.

The four events

Event	Runs when	How often
On Emit	A particle has been made.	Once for each particle.
On Death	The particle’s Lifetime ends, or Collide `Kill` ends it.	Once for each particle.
On Destruction	The particle is removed for good. That is after its Linger, if it has one.	Once for each particle.
On Hit	The particle meets a surface.	It depends on Collide. See The Collide modes.

With no Linger, On Death and On Destruction run in the same frame, On Death first.

On an emitter in Animate mode with Loop on, On Emit runs at the start of every cycle. On Death runs at the end of every cycle. On Destruction runs once, when the last cycle finishes.

Two emitter types run On Hit by their own rules:

Emitter type	On Hit runs
Lightning	Each time a `Seek` bolt finds a strike point.
Rocks	At the first chunk impact of a burst. With Hit Per Chunk on, at every chunk’s first impact.

Which emitter types have which events

Emitter type	On Emit, On Death, On Destruction	On Hit
Part, Attachment, Model, Rocks	Yes	Yes
Lightning	Yes	Only while Target Mode is `Seek`
Beam, Light, Highlight, Trail emitter, Sound, Rope, ImageLabel, Blur, Bloom, ColorCorrection, Atmosphere, Camera Shake, Distortion	Yes	No. The block is not shown.
A stock ParticleEmitter, Trail or Beam	No	No

What an event does

An event that is switched on does up to three things, in this order:

It fires the target, if the Emit row holds one. The target is the emitter picked in that row.
It runs the script, if Script is on.
On Hit only: it applies Collide.

The target and the script are independent. An event with no target and with Script off does nothing.

A script can also move, recolour, resize, freeze, push or remove the particle. The panel has no rows for those. They are functions of the payload.

The Events section

Every emitter type has an Events section in the Properties panel, above Advanced. It starts collapsed. Expanded, it shows these parts from the top:

Part	Shown on
Hit Filter row	Part, Attachment, Model, Lightning and Rocks emitters.
On Emit block	Every emitter type.
On Death block	Every emitter type.
On Destruction block	Every emitter type.
On Hit block	Part, Attachment, Model and Rocks emitters. Lightning emitters while Target Mode is `Seek`.

The blocks are always present. Each block is a header with a switch at its right.

To	Do this	What happens
Switch an event on	Switch on the block’s header.	The rows of the block appear. The first time, the event gets its starting values, an empty Emit row and a script that holds the plugin’s template.
Switch an event off	Switch off the block’s header.	The rows hide and the event stops running. Its values, its target and its script are kept.
Clear an event	Press Reset Event, then press it again.	After the first press the button reads Click again to confirm for 2 seconds. The second press deletes the event’s values, target and script, and switches the event off.

Every switch, edit, pick and reset is one step in Studio’s undo history.

While an event is on, its header also reads the target’s name, the Mode, and the word script if Script is on. An example is On Death → Sparks · AtPosition · script.

With several emitters selected, the rows show only when every selected emitter has the event on. A row whose values differ reads ~. An edit is written to every selected emitter.

The values of an event are read when a particle is made. An edit affects the particles made after it. An Animate emitter with Loop on reads them again at each cycle.

The rows of a block

Row	Kind	Starts at	Takes	What it does
Emit	Instance, picked with `...`	`(none)`	One instance	Holds the target. The row shows the target’s full path.
Mode	List	`AtPosition`	`AtPosition`, `AtSource`, `AtTarget`, `AtCFrame`	Where the target is fired. A hint under the list describes the choice.
Script	Switch, with an Edit Script button	Off		On, the event’s script runs each time the event runs. In the editor, the place must also allow event scripts. See Allowing event scripts in a place.
Chain	Number	4	A whole number from 1 to 32	How far events may fire one another in a row. See Chain.
Reset Event	Button		Two presses	Clears the event.

Edit Script opens the event’s script in Studio’s Script Editor. With several emitters selected it opens the first six scripts. Pressed on an event that is off, it makes the script and leaves the event off.

Chain is taken when you press Enter or click elsewhere. A fraction is rounded down. A number outside 1 to 32 is moved to the nearer end. Text that is not a number becomes 4.

The On Hit block has five more rows. See On Hit. A block on an Inventory asset also shows a Trust Script button. See Events on Inventory assets.

Picking the target

Step	Control	Action	Result
1	The event’s Emit ▸ …	Press	The selection is cleared. A small panel opens with the line `Instance: <nil>` and the buttons Set, Clear and Cancel.
2	Explorer or viewport	Select the target	The line reads `Instance:` and the target’s full path.
3	Set	Press	The Emit row shows the path. The selection of step 1 returns.

The panel is titled after the event. For On Death the title reads Set OnDeath Emit Target.

Set writes the target to every emitter that was selected in step 1. Clear empties the row. Cancel changes nothing. If several instances are selected in step 2, the first one counts.

Set takes these:

An emitter of any type.
A stock ParticleEmitter or a stock Trail.
A Folder.
A Part, an Attachment or a Model, transformed or not.

Anything else is refused. The line then reads Pick a Part-Icle, raw ParticleEmitter / Trail, Folder, or container (Attachment / Part / Model). With nothing selected it reads No instance selected - click one in Studio first.

A stock Beam cannot be picked. Pick the Part or the Folder that holds it.
A plain light cannot be picked. Transform it first.
An emitter can be picked as its own target. Chain stops the loop.
A target can be picked while the event is off. The pick is kept.

Where the target is fired

Mode decides the place. The hint under the list changes with the choice.

Mode	Hint under the list	The target is fired
`AtPosition`	`Spawns where the event happened (emit, death or hit point).`	At the place of the event. The target keeps its own rotation.
`AtSource`	`Spawns at the source emitter's current position.`	At the emitter that owns the event, where that emitter is at that moment. The target keeps its own rotation.
`AtTarget`	`Spawns at the target's own authored placement.`	Where the target sits, as if it had been fired by itself.
`AtCFrame`	`Spawns at the event position and rotation.`	At the place of the event, turned the way the particle is turned.

The place of the event depends on the event:

Event	`AtPosition`	`AtCFrame`
On Emit	Where the particle is at the moment the target makes each of its particles.	The same place, with the particle’s rotation at that moment.
On Hit	The contact point, moved 0.1 stud off the surface so that the new effect does not start inside the wall.	The particle’s own place and rotation at the hit, moved off the surface in the same way.
On Death, On Destruction	Where the particle was when it ended.	The same place, with the particle’s rotation when it ended.

Under On Emit the place is read again for every particle the target makes. A target with a Delay fires where the particle is after the Delay. A target with a Duration streams from the moving particle for that long.

AtSource is read the same way: the emitter’s place at the moment the target makes each particle.

What each kind of target does

With Mode AtTarget, every kind of target fires where it sits, with its own Link. A Folder, Model, Part or Attachment fires everything inside it.

With AtPosition, AtSource or AtCFrame, the result depends on the target:

Target	What happens
An emitter made from a Part, an Attachment or a Model, in Emit mode. Also a Lightning, Rocks, Rope, Camera Shake or Distortion emitter.	It emits with its spawn point moved to the place of the event. Its own Spawn rows still apply on top. Its Link is not used for this emission.
A Folder, or a Model that is not transformed	Every child is fired separately, at the place of the event plus the child’s own offset in the Folder or Model. The layout is kept.
A Part or an Attachment that is not transformed and holds emitters	The emitters inside fire at the place of the event, plus their offset from the Part or Attachment. Stock ParticleEmitters, Trails and Beams inside fire from a temporary copy of it, placed at the event.
A stock ParticleEmitter	A copy placed at the event emits its Emit count. It keeps the emission area of the Part it sits in.
A stock Trail	It fires where it sits.
An emitter in Animate mode. A Beam, Light, Highlight, Sound, Trail emitter or ImageLabel emitter. A Blur, Bloom, ColorCorrection or Atmosphere emitter.	It fires where it sits. See Emits in place.

A Folder or Model target keeps its layout by these rules:

The layout is measured from one reference point. For a Model it is the pivot. For a Folder it is the place of the first child that has a position.
AtPosition and AtSource move the layout to the place of the event. Every child keeps its own rotation.
AtCFrame moves the layout and turns it the way the particle is turned.
A Folder inside the Folder is measured from the outer Folder’s reference point.
A child with a Delay is placed when it fires. Three children with three Delays each land at their own offset.

Emits in place

A target that cannot be moved fires where it sits, whatever the Mode says. The panel reports it with a line under the hint: Emits in place: <reason>. The line shows when a target is picked and Mode is not AtTarget.

Target	Reason in the line
An emitter whose Emission ▸ Mode is `Animate`	`Animate-mode targets animate their own instance`
A Beam, Trail, Light, Highlight, Sound, ImageLabel, Blur, Bloom, ColorCorrection or Atmosphere, transformed or not	The class name, then `has no position to move`. An example is `PointLight has no position to move`.
A Folder in which nothing has a position	`the folder holds nothing with a position`

When such a target fires, the Output window reads [Part-Icles Events] <path> emits in place: <reason>.

To move one of these effects to the event, put it inside an emitter made from a Part and pick that emitter. Nesting describes how.

The target’s own Emit, Delay and Duration

A target that is an emitter fires as its own HUD boxes say. It waits its Delay, makes its Emit count at once, then emits at its Rate for its Duration. Emission and the HUD describes the boxes.

The rule covers the target and every emitter reached inside a Folder, Model, Part or Attachment target.
The rule does not cover emitters nested in the target’s RenderTemplate. Each of those needs its own Emit count or Duration.
A stock ParticleEmitter uses its own Emit count. With Emit 0 and Duration 0 it does nothing.
A target with a Duration runs its own stream each time it is fired. Several streams can run at once. The target’s Enabled switch is not changed.

On Hit

What a particle can hit

The hit test follows the particle’s centre point. The size of the particle plays no part.

A particle hits any Part and any terrain that its path crosses.

A Part with CanCollide off is hit by the particles of a Part, Attachment or Model emitter.
Rocks and Seek Lightning pass through a Part with CanCollide off.
A Part with CanQuery off is never hit.

A particle never hits these:

Itself, its emitter, or the emitter’s RenderTemplate.
The instance in Advanced ▸ Emit Into, and everything inside it.
For a particle of an Attachment emitter, the Part that the Attachment sits on.
Terrain water.
Anything the Hit Filter rules out.
Other particles.

The On Hit rows

Row	Kind	Starts at	Takes	Shown	What it does
Collide	List	`Off`	`Off`, `Kill`, `Stop`, `Bounce`	Always	What the particle does at the surface.
Bounce%	Number	0.7	0 to 1	While Collide is `Bounce`	The share of the speed into the surface that comes back out.
Friction	Number	0.2	0 to 1	While Collide is `Bounce`	The share of the sideways speed lost at each bounce.
Spin	Number	0.5	0 to 2	While Collide is `Bounce`	How strongly the sideways speed at impact turns into tumbling.
HitTick	Number	0	0 to 0.5 seconds	Always	The shortest time between two hit tests of one particle.

A value is taken when you press Enter or click elsewhere. A number outside the range is moved to the nearer end. Text that is not a number becomes the starting value.

The Collide modes

In every mode the target fires and the script runs before Collide acts.

Collide	What the particle does	On Hit runs again
`Off`	It flies on through the surface. Nothing changes.	At the next surface. It does not run again while the particle is still crossing the same surface.
`Kill`	It moves to the contact point and is removed on the next frame. On Death runs. Linger is skipped, so On Destruction runs at once.	No.
`Stop`	It moves to the contact point and stays there for the rest of its Lifetime. It then ends as usual, with On Death, Linger and On Destruction.	No.
`Bounce`	It rebounds off the surface.	At every bounce.

A stopped particle that has a Link stays fixed to the link, not to the wall.

Bounce

Row	At 0	At 1
Bounce%	No rebound. The particle keeps its sideways motion and slides along the surface.	A full rebound.
Friction	No sideways speed is lost at a bounce.	All sideways speed is lost at a bounce.

Friction also slows spin the particle already has. It acts as the friction of the surface once the particle is resting.

Spin at 0 adds no spin. A higher value turns more of the sideways speed at impact into a forward roll.

What a bouncing particle does:

A bounce reflects all of the particle’s motion: Speed, Acceleration, Accel toward and Displacement.
Each particle multiplies Bounce% and Friction by a random factor of its own, between 0.8 and 1.2. A burst does not bounce in step.
An impact slower than about 0.5 studs a second into the surface does not rebound. This stops endless small bounces.
Below about 1 stud a second after a bounce, a particle of a Part, Model or Attachment emitter starts to settle. It comes to rest after about half a second spent almost still. Its spin and its Rotation Speed fade out.
If the emitter has an Acceleration, the resting particle tips onto its nearest flat face. It stays flush with the surface while its Size graph shrinks it.
Without an Acceleration the particle does not tip.

HitTick

With HitTick at 0, each particle is tested once in every frame. The test covers the whole path travelled since the last test. A fast particle therefore cannot pass through a thin wall between two tests. A particle is tested again once it is more than 0.05 studs from the last point tested.

A HitTick above 0 is the shortest time, in seconds, between two tests of one particle. The path skipped is still covered by the next test. A particle that has travelled further than half its own diagonal is tested at once, whatever HitTick says. For an Attachment or Model emitter that distance is 1 stud. HitTick therefore saves work only on slow particles.

The test uses the particle’s final place for the frame. A particle carried into a wall by its Link triggers On Hit too.

On Hit with other settings

Setting	Effect on On Hit
Motion ▸ Reverse Motion on	Collide `Bounce` acts as `Kill`. `Off`, `Kill` and `Stop` work as usual.
Emission ▸ Mode `Animate`	`Kill`, `Stop` and `Bounce` act as `Off`. On Hit still fires its target and runs its script.
A Timescale below 0	On Hit does not run while time runs backward. Rewinding past a bounce or a stop undoes it. Only the last 16 hits of a particle can be undone. A `Kill` cannot be undone.
A Timescale of 0	The particle does not move, so nothing is tested.
A Link	The place of a bounce or a stop is kept relative to the link.

Hit Filter

The Hit Filter row is at the top of the Events section. It has a summary and a … button.

The filter is saved on the emitter, not on the On Hit block. It applies to On Hit, to the collisions of a Rocks emitter and to Seek Lightning. It applies while On Hit is switched off too.

Summary	Meaning
`(none)`	Nothing is set.
`Group: <name>, <N> excludes`	A collision group and an exclude list are set. If only one is set, only that part shows.
`~`	The selected emitters hold different filters.

Press … to open the Hit Filter box. Press its X to close it.

Control	What it does
Collision Group	A list of `(none)` and every collision group of the place. The hit test is made with the chosen group. Roblox’s collision group settings then decide which Parts that group meets. A choice is written at once.
Exclude List (ignores instance + descendants)	One row for each excluded instance, shown by its full path. A particle never hits an excluded instance or anything inside it. The list reads `(no excludes)` when empty.
X on a row	Removes that instance from the list of every selected emitter.
+ Add Exclude	Opens the picker of the Emit row, titled `Add Exclude`. Any instance can be picked, except the emitters being edited.

With several emitters selected, the list shows every instance that any of them excludes.
If some selected emitters cannot hit, the box reads Filter applies to <n> of <m> selected items.
Everything done between opening the box and closing it is one step in Studio’s undo history.
The filter is read when a particle is made. An edit affects the particles made after it.
The filter has an exclude list only. It cannot name the instances to hit.

If no selected emitter can hit, the box does not open. The Output window reads [Part-Icles] Hit Filter not applicable to this selection - Beam / PointLight / Trail / screens do not raycast.

Allowing event scripts in a place

In the editor, an event’s script runs only in a place where you have allowed event scripts. The plugin asks once for each place.

The question is a bar across the top of the screen. It reads Part-Icles: event scripts in this place run with plugin permissions. Allow them here? Only allow a place you trust. The bar appears the first time a script is due to run. It also appears when an event’s Script is switched on in a place that is not yet allowed.

Button	What it does
Allow	Event scripts run in this place, from the next time an event happens. A message reads Event scripts are allowed in this place. The choice is remembered for this place on this machine. The bar does not return.
Not now	Event scripts stay off for the rest of the session. A message reads Event scripts stay off in this place. Turn an event’s Script toggle on to be asked again.

While scripts wait, the rest of the effect works. Emitters emit, and an event still fires the target in its Emit row.

A place opened from a file must be saved once after Allow. The message then adds Save the place to keep this choice. Without the save, the bar returns the next time the file is opened.

The bar belongs to the editor. In a play test and in the published game, event scripts run with no question.

The Part_Icles module, called from Studio’s command bar while the game is stopped, does not run event scripts. The Output window reads [Part-Icles Events] event scripts do not run in Studio edit mode outside the Part-Icles plugin once.

Events on Inventory assets

Events on assets inserted from the Inventory arrive switched off and must be trusted before they run. This covers every event on every emitter in the asset.

An event that is not trusted does not run, even with its switch on. It fires no target and runs no script. Its block shows its rows while the event is off. A line at the top of the block reads Untrusted - review the script, then click Trust before this can run. A Trust Script button shows near the bottom of the block.

Step	Control	Action	Result
1	The event’s Script ▸ Edit Script	Press	The script opens in the Script Editor. Read it.
2	The event’s Trust Script	Press	The line and the button go. The event is still off.
3	The event’s header	Switch on	The event runs.

Trust Script acts on that one event, on every selected emitter.

Trust is separate from the bar described in Allowing event scripts in a place. An event from the Inventory needs Trust Script, and the place needs Allow.

The Inventory has a faster way. With the inserted asset selected, press Trust Asset in the Inventory’s details panel. It trusts every event of every selected emitter and of every emitter inside the selection. The button then reads Trusted N, or Nothing to trust. The events stay off until each is switched on. The Inventory describes the details panel.

With the tools

Tool	Effect on events
Clipboard	Copies and pastes each event with its values, its target and the text of its script. The Hit Filter is not copied. An On Hit pasted onto an emitter type that cannot hit is dropped.
Fix	Repairs the events of an emitter. It removes events the type cannot have, puts back missing values, brings values into range, and makes a missing Emit row or script again.

Limits

Chain

Each particle has a depth. A particle emitted in the normal way has depth 0. A particle made by an event’s target has the depth of the particle that fired it, plus 1.

Chain is a limit on depth, set for each event:

An event runs only on a particle whose depth is below its Chain.
An event fires its target only if the new particles’ depth is below its Chain.

Chain on every event	Result
1	No target fires. A script still runs on the first particle.
2	The first particle fires one further generation.
4	The first particle fires three further generations, at depths 1, 2 and 3. Then the firing stops.

Emitters nested in a RenderTemplate do not add to the depth. A nested particle has the depth of its parent particle.

When the limit drops fires, the Output window reports it once a second: [Part-Icles Events] dropped N event fire(s) this second (chain depth limit reached on <Event>).

Other limits

Limit	What happens at the limit
Event fires in one frame, over the whole scene	256 are allowed. Beyond that, fires are dropped. The Output window reads `[Part-Icles Events] dropped N event fires this second.` once a second.
The Particle Cap	No target fires while the cap is reached. Scripts still run. The Output window reads `[Part-Icles Events] active-particle cap reached; event EmitTargets are being skipped` once. The cap is set in Settings.
Edit Script on several emitters	The first six scripts open.

A target is not fired as set in these cases:

Case	Result
The Emit row is empty	Nothing is fired. The script still runs.
The target has been deleted	Nothing is fired. The Output window stays silent.
The place of the event cannot be found, as with `AtSource` after the emitter was deleted	The target fires where it sits. The Output window reads `[Part-Icles Events] EmitMode "<mode>" has no resolvable origin; emitting in place`.
Firing the target fails	The Output window reads `[Part-Icles Events] emit target failed:` and the reason. The effect continues.

Events that do not run

The Stop Emits shortcut removes live particles at once. Neither On Death nor On Destruction runs for them. Disable from a script does the same.
A particle removed in this way during its Linger does not run On Destruction.
In the editor, no script runs in a place where event scripts have not been allowed. Targets still fire.

Cost

An event that is off costs nothing.
On Emit, On Death and On Destruction each cost one run for each particle.
On Hit costs one hit test in every frame, for each live particle whose On Hit is on.
An emitter is the cheapest target.
A stock ParticleEmitter target is copied at every fire. So is a plain Part or Attachment target that carries stock emitters.
A Folder or Model target is not copied, but each such child inside it is.
A high Rate with an On Emit target multiplies fast. Each particle of the emitter starts a full emission of the target.