VFXRecipe

VFXRecipe : Instance

Overview

VFXRecipe is a class that lets you place visual effects (VFX) in a scene and play and control them.

A single VFXRecipe has three layers—BaseLayer, DetailLayer, and ExtraLayer—and you compose a composite effect by registering VFXSources to each layer. Playback behavior is controlled through the play count (LoopCount) and infinite loop (InfiniteLoop) settings, and when AutoActivate is true, playback starts automatically the moment the recipe is placed in the Workspace.

You can control playback manually with the Play() / Stop() methods, and the Finished event fires when playback ends.

Properties

AutoActivate

boolean

A property that specifies whether the effect plays automatically when the VFXRecipe is activated in the scene.

If true, the effect plays immediately when the instance is initialized, without an explicit call to Play(). If false, playback starts only when you call Play() from a script. The default value is true.

Code Samples

BaseLayer

Array

A property representing the array of VFXSources that make up the primary visual elements of the effect.

It is one of the three VFXRecipe layers, together with DetailLayer and ExtraLayer, and is responsible for the main particle effects. Each entry in the array has a name (Name), and you can edit the layer composition in the editor.

Code Samples

DetailLayer

Array

A property representing the array of VFXSources that make up the detailed visual elements of the effect.

It is responsible for the supplementary particle effects added on top of the BaseLayer. Each entry in the array has a name (Name) and plays together with the BaseLayer and ExtraLayer.

Code Samples

ExtraLayer

Array

A property representing the array of VFXSources that make up the auxiliary visual elements of the effect.

It is responsible for additional particle effects on top of the BaseLayer and DetailLayer. Each entry in the array has a name (Name), and all three layers share the same lifecycle parameters (LoopDuration, LoopCount) so they play in a synchronized state.

Code Samples

InfiniteLoop

boolean

A property that specifies whether the effect plays in an infinite loop.

If true, the effect keeps repeating until Stop() is called or the instance is destroyed. If false, the effect plays the number of times specified by LoopCount, then stops automatically and the Finished event fires. The default value is false.

While InfiniteLoop is true, the LoopCount setting is ignored.

Code Samples

LoopCount

number

A property that specifies the total number of times the effect plays.

It is effective only when InfiniteLoop is false; after Play() is called, the effect repeats this many times and then stops automatically. The default value is 1.

Code Samples

LoopDuration

number

A read-only property representing the duration (in seconds) of a single playback of the effect.

It is calculated automatically by analyzing the Duration and Delay parameters of every VFXSource registered to the three layers (BaseLayer, DetailLayer, ExtraLayer) and cannot be modified directly. The total playback time is determined by LoopDuration × LoopCount.

Code Samples

Methods

GetParam

Gets the parameter value of the specified VFXSource.

Searches BaseLayer, DetailLayer, and ExtraLayer for a VFXSource matching SourceName and returns the current value of the parameter specified by ParamName. For Position and Rotation, the value stored on the VFXSource itself is returned; for other parameters, the value is read from the NiagaraComponent that is actually playing. If the source or the parameter cannot be found, a warning is logged and nil is returned.

Parameters

string SourceName	The name of the VFXSource to get the value from.
string ParamName	The name of the parameter to retrieve.

Return

Value	The value of the retrieved parameter. Depending on the parameter type, it can be a number, boolean, Vector2, Vector3, ColorSequence, NumberSequence, or similar.

Code Samples

GetParamAt

Gets the parameter value of the VFXSource specified by layer and index.

Behaves the same as GetParam(), except that the VFXSource is specified by LayerName and Index for a particular layer. If LayerName is not one of Base, Detail, or Extra, or if Index is out of range for that layer, a warning is logged and nil is returned.

Parameters

string LayerName	The name of the layer to retrieve the value from. Specify one of Base, Detail, or Extra (case-insensitive).
number Index	The index of the VFXSource to get the value from within that layer (starting at 0).
string ParamName	The name of the parameter to retrieve.

Return

Value	The value of the retrieved parameter. Depending on the parameter type, it can be a number, boolean, Vector2, Vector3, ColorSequence, NumberSequence, or similar.

Code Samples

IsPlaying

Returns whether the effect is currently playing.

Returns true from the time Play() is called until Stop() is called or playback completes.

Parameters

Return

boolean	Returns true if the effect is currently playing, or false if it is stopped.

Code Samples

Play

Starts playing the effect.

When called on the server, it is propagated to all clients via multicast. If called while the effect is already playing, playback restarts from the beginning. If InfiniteLoop is false, the effect plays LoopCount times, then stops automatically and the Finished event fires.

Parameters

Return

void

Code Samples

SetParam

Sets the parameter value of the specified VFXSource.

Searches BaseLayer, DetailLayer, and ExtraLayer for a VFXSource matching SourceName and applies Value to the parameter specified by ParamName. Passing an empty string for SourceName applies the same value to every VFXSource across all three layers at once. Values exposed as VFXRecipe properties—such as LoopCount—or parameters whose values are fixed by resources or internal playback logic cannot be set. When called on the server, it is propagated to all clients via multicast.

Parameters

string SourceName	The name of the VFXSource to set the value on. Passing an empty string applies the value to all VFXSources at once.
string ParamName	The name of the parameter to set.
Value Value	The value to set for the parameter. You must pass a number, boolean, Vector2, Vector3, ColorSequence, NumberSequence, or similar value matching the parameter's type.

Return

void

Code Samples

SetParamAt

Sets the parameter value of the VFXSource specified by layer and index.

Behaves the same as SetParam(), except that the VFXSource is specified by LayerName and Index for a particular layer. If LayerName is not one of Base, Detail, or Extra, or if Index is out of range for that layer, a warning is logged and nothing happens.

Parameters

string LayerName	The name of the layer to set the value on. Specify one of Base, Detail, or Extra (case-insensitive).
number Index	The index of the VFXSource to set the value on within that layer (starting at 0).
string ParamName	The name of the parameter to set.
Value Value	The value to set for the parameter. You must pass a number, boolean, Vector2, Vector3, ColorSequence, NumberSequence, or similar value matching the parameter's type.

Return

void

Code Samples

Stop

Stops playing the effect immediately.

When called on the server, it is propagated to all clients via multicast. Calling it while the effect is already stopped does not cause an error. When playback is stopped by calling Stop(), the Finished event does not fire.

Parameters

Return

void

Code Samples

Events

Finished

An event that fires when effect playback completes normally.

It fires when playback finishes LoopCount times while InfiniteLoop is false. It does not fire when playback is forcibly stopped with Stop().

Parameters

Code Samples