The event script and its payload

Every event of an emitter can run a script. The script receives one value, payload. It describes one particle and holds the functions that change that particle. Events describes the four events and their rows in the Properties panel. Exercise 12 switches an event on for the first time.

What it makes possible:

• Sparks only from particles that lived long enough. An On Death script reads payload.Age and calls payload.Emit.
• A particle that bounces twice and is removed at the third hit. An On Hit script counts the hits of each payload.Particle and calls payload.Kill().
• Game logic on impact. An On Hit script reads payload.HitInstance and payload.HitPosition.
• A particle that changes colour and slows where it touches something. An On Hit script calls payload.SetColor and payload.SetSpeedMultiplier.
• An effect chosen at the moment of the event. Any script calls payload.Emit with the emitter it has chosen.

The script

Each event of each emitter has its own script. In the Explorer it sits under the emitter, in the folder named after the event:

<Emitter>
    PartIcleProperties
        Events
            OnEmit, OnDeath, OnDestruction or OnHit
                Module

Kind	A ModuleScript named Module.
Made	The first time the event is switched on, Edit Script is pressed, or a target is picked.
Opened with	Events ▸ the event’s block ▸ Script ▸ Edit Script.
Must return	A function that takes payload.
Runs	Once for one particle, each time the event happens to that particle.
Runs only while	The event is switched on and its Script switch is on. In the editor, the place must also allow event scripts.
A saved change	Takes effect the next time the event runs. Nothing needs switching off and on.
An error	Shows in the Output window with the script’s path. The effect carries on.
A new name	The plugin puts the name back. The script must stay named Module.

If the script returns anything but a function, the Output window reads [Part-Icles Events] <script path>, then module must return function(payload).

You may see a temporary copy next to the script while the plugin is running. Leave it alone.

In the editor, the plugin asks once for each place before it runs any event script. See Allowing event scripts in a place.

A script on an asset inserted from the Inventory does not run until its event is trusted. See Events on Inventory assets.

The starting template

The plugin writes the same template into every new script, for all four events. The template is a block of comments followed by an empty function.

Part of the template	Holds
Header	What the function is, when the script runs, and where errors show.
WHEN DOES THIS RUN?	One line for each of the four events.
QUICK EXAMPLE	An On Death script. It fires workspace.Sparks for particles that lived more than one second.
THINGS YOU CAN READ	The fields of payload.
THINGS YOU CAN DO	The functions of payload, in four groups: spawn and end, look, time, motion.
GOOD TO KNOW	Three notes. See Good to know.
The function	The last lines of the script. Write the code between them.

return function(payload)
  -- your code here
end

Keep these lines. The script must return a function that takes payload.

Fields

A field is a value taken at the moment the event runs. Writing to a field does nothing.

Field	Type	Events	Meaning	Notes
payload.Source	Instance	All	The emitter, as set up in the plugin.	payload.SourceItem is the same value. Its Parent is nil if the emitter was deleted.
payload.Particle	Instance or nil	All	The particle this event is about.	nil on a Camera Shake or Distortion emitter. In Animate mode it is the emitter’s own RenderTemplate.
payload.RenderTemplate	Instance or nil	All	Another name for payload.Particle.	It is the particle, not the template. Use payload.Particle in new scripts.
payload.WorldPosition	Vector3 or nil	All	Where the particle is.	For a Beam, the midpoint between its two Attachments. See Particles with no position.
payload.WorldCFrame	CFrame or nil	All	The particle’s position with its rotation.	nil in the same cases as WorldPosition. For a Beam, position only. For Camera Shake, the camera.
payload.LifeTime	number	All	The seconds this particle is set to live.
payload.LifeProgress	number, 0 to 1	All	0 is newly made. 1 is at the end.	Measured in real time since the particle was made. Timescale is not counted.
payload.TimeRemaining	number	All	The seconds left, by the same real-time measure.
payload.StartTime	number	All	The value of os.clock() when the particle was made.
payload.SpeedMultiplier	number	All	The current scale of the particle’s Speed. 1 is the Speed as set.	Each bounce lowers it.
payload.ChainDepth	number	All	0 for a particle emitted in the normal way. 1, 2 and up for a particle made by an event.	See Chain.
payload.EmitPosition	Vector3 or nil	On Emit	The same value as WorldPosition.
payload.EmitIndex	number or nil	On Emit	The particle’s number in its burst. 1 is the first.	nil for a particle of a Rate stream, and for the restart of an Animate loop. A stream particle of an emitter with an Even dot on reads 1.
payload.EmitCount	number or nil	On Emit	How many particles the burst made.	nil outside a burst. A stream particle of an emitter with an Even dot on reads 1.
payload.HitInstance	Instance	On Hit	The part that was touched.	payload.Other is the same value.
payload.HitPosition	Vector3	On Hit	The exact contact point.
payload.HitNormal	Vector3, length 1	On Hit	The direction the surface faces at the contact point.
payload.DeathPosition	Vector3 or nil	On Death, On Destruction	The same value as WorldPosition.
payload.Age	number	On Death	The seconds the particle lived, in real time.	Less than LifeTime when the particle was ended early.
payload.LingerElapsed	number	On Destruction	The seconds the particle spent in its Linger.	0 with no Linger.

Particles with no position

payload.WorldPosition and payload.WorldCFrame are nil when the particle has no position:

• On a Blur, Bloom, ColorCorrection or Atmosphere emitter.
• On an ImageLabel, Highlight or Trail emitter.
• On a Light or Sound emitter whose parent is not a Part or an Attachment.

The events of these emitters still run.

Functions

Each function acts on the one particle the event is about. An argument of the wrong type is ignored, with no message.

Function	Takes	What it does	Notes
payload.Emit(target, mode)	An Instance. Optionally "AtPosition", "AtSource", "AtTarget" or "AtCFrame".	Fires another emitter, Folder or Model from this particle.	With no mode, it uses the event’s Mode row. Any instance may be passed. It adds one to the depth, as the Emit row does.
payload.Kill()	Nothing	Removes the particle on the next frame.	On Death does not run. Linger is skipped. On Destruction still runs. In Animate mode it also switches the emitter’s Loop and Enabled off.
payload.Resurrect()	Nothing	Cancels a Kill() made earlier in the same run of the script.	It acts only before the particle has been removed.
payload.SetColor(color)	Color3	Sets the colour and stops the Color graph from changing it.	See What the look functions change.
payload.SetTransparency(n)	number, held to 0 to 1	Sets the transparency and stops the Transparency graph.	See the same table.
payload.SetSize(size)	Vector3. UDim2 on an ImageLabel emitter.	Sets the size and stops the Size graph.	See the same table.
payload.SetSkipColor(bool)	boolean	true stops the Color graph and leaves the current colour. false starts it again.
payload.SetSkipTransparency(bool)	boolean	The same for the Transparency graph.	On a Light emitter it acts on the Brightness graph.
payload.SetSkipSize(bool)	boolean	The same for the Size graph.	Part and ImageLabel emitters only.
payload.SetLifetime(seconds)	number	Sets a new total lifetime, counted from the moment the particle was made.	The lowest value is 0.001. A very small value ends the particle on the next frame.
payload.Pause(seconds)	number above 0	Freezes the particle’s own clock for that long, then lets it run.	The frozen time is added to the particle’s life. A later Pause replaces an earlier one.
payload.FreezeTime(bool)	boolean	true freezes the particle until FreezeTime(false).	A frozen particle never ends by itself.
payload.Teleport(cframe)	CFrame	Moves the particle to that place in the world.	Part, Attachment and Model emitters only. The jump is not tested for hits. The next hit test starts from the new place. It wakes a resting particle.
payload.SetVelocity(v)	Vector3 or nil	Makes the particle fly in that direction at that speed, in place of its Speed graph.	SetVelocity(nil) returns to the Speed graph and keeps the new direction. No effect with Reverse Motion on. It wakes a resting particle.
payload.SetSpeedMultiplier(n)	number	Scales the particle’s Speed. 2 is twice as fast.	Ignored while a SetVelocity is in force.
payload.AddImpulse(v)	Vector3	Adds a push to the particle’s velocity.	See the CAUTION below. It wakes a resting particle.
payload.AddSpin(v)	Vector3	Adds tumbling, in degrees per second around each axis.	Part, Model and Attachment emitters only.

CAUTION

payload.AddImpulse has an effect only when the emitter’s Acceleration is not 0, 0, 0. On an emitter with no Acceleration the push does nothing.

A resting particle is one that has come to rest after a bounce. See Bounce.

What the look functions change

Function	Changes	No effect on
payload.SetColor	Part: the Part’s colour, and the colour of a SurfaceAppearance. Beam and Trail emitter: one flat colour. Light: the colour. Highlight: the fill and the outline. ImageLabel: the image colour. ColorCorrection: the tint. Atmosphere: the colour. Lightning, Rocks and Rope: every piece.	Attachment, Blur, Bloom, Sound, Camera Shake, Distortion. Model, unless a SurfaceAppearance sits directly under the Model.
payload.SetTransparency	Part: the Part and its first Decal. Beam and Trail emitter: one flat value. Light: the Brightness. Highlight: the fill and the outline. ImageLabel: the image. Lightning, Rocks and Rope: every piece.	Attachment, Sound, Blur, Bloom, ColorCorrection, Atmosphere. Model, unless a Decal sits directly under the Model.
payload.SetSize	Part: the size. Model: the whole Model is scaled to the X value of the Vector3. ImageLabel: the size, as a UDim2.

On a Light emitter, payload.SetTransparency(1) switches the light off. payload.SetTransparency(0) gives the light its own Brightness.

Example

A script for On Hit, with Collide Off. It expects an emitter named Sparks in the workspace. A particle that touches a part named Shield bursts into sparks and is removed. Any other part halves the particle’s speed.

return function(payload)
  if payload.HitInstance.Name == "Shield" then
    payload.Emit(workspace.Sparks, "AtPosition")
    payload.Kill()
    return
  end

  payload.SetSpeedMultiplier(payload.SpeedMultiplier * 0.5)
end

Good to know

• The script may wait. After a wait the particle may be gone, and the functions of payload then do nothing useful.
• payload.Source.Parent is nil when the emitter was deleted while the particle was in flight.
• On an emitter in Animate mode, payload.Particle is the emitter’s own RenderTemplate. What the script changes there stays changed after the effect ends.

Limits

• No function sets or holds the Rotation graphs.
• payload.Kill() does not run On Death. Collide Kill does.
• A script may call the functions of the Part_Icles module. Disable called from inside an event acts later in the same frame. See Starting, stopping and waiting.
• An event script runs on the machine that plays the effect. Fired for every player, an On Hit script runs once on each player’s machine. Do not use it to decide damage or score.
• Each event allows a set depth of firing. A payload.Emit beyond the event’s Chain is dropped.