Emitters

Overview

A PopcornFX Emitter (PKFxEmitter.cs) is an instance of a PopcornFX Effect (PKFxEffectAsset.cs).
Emitters are updated and rendered in a scene, allowing configuration during edition and control over emitters during runtime.

Emitter properties

Unity_Emitters_Property

The emitter can be started, stopped, restarted and terminated using the three buttons.
Exposes general properties of the emitter.
Provides control and configuration over attributes and attributes samplers.

You can also interact with the emitter by getting the component and calling the appropriates methods:

Return type

Description

void

StartEffect()
Starts the emitter.

void

StartEffectWithDt(float dt)
Starts the emitter with a specific dt in the current frame.

Warning: The dt value cannot be greater than Time.smoothDeltaTime` * PKFxManager.TimeMultiplier` as this is not meant to replace the "prewarm" feature.

void

TerminateEffect()
Stops the particle emission on the current emitter. The particles that are still alive will not get the parent game object transforms anymore, as if the effect was detached from the entity when this is called.

void

TerminateEffectWithDt(float dt)
Stops the particle emission on the current emitter at a specific dt in the current frame. The particles that are still alive will not get the parent game object transforms anymore, as if the effect was detached from the entity when this is called.

Warning: The dt value cannot be greater than Time.smoothDeltaTime` * PKFxManager.TimeMultiplier`

void

StopEffect()
Stops the particle emission on the current emitter. The particles that are still alive will continue to follow the parent game object transforms and you will not be able to call StartEffect on this component until the last particle has died.

void

StopEffectWithDt(float dt)
Stops the particle emission on the current emitter at a specific dt in the current frame. The particles that are still alive will continue to follow the parent game object transforms and you will not be able to call StartEffect on this component until the last particle has died.

Warning: The dt value cannot be greater than Time.smoothDeltaTime` * PKFxManager.TimeMultiplier`

void

KillEffect()
Stops the particle emission on the current emitter and kill all the particles emitted from this instance.

void

KillEffectWithDt(float dt)
Stops the particle emission on the current emitter at a specific dt in the current frame and kill all the particles emitted from this instance.

Warning: The dt value cannot be greater than Time.smoothDeltaTime` * PKFxManager.TimeMultiplier`

bool

EffectRegisterEvent(string eventName, PKFxRaiseEventCallback callback)
Use this function to register a callback to be called when this instance triggers a specific event.
Returns false if the register event fails.

bool

EffectUnregisterEvent(string eventName, PKFxRaiseEventCallback callback)
Unregister a user callback from an event.
Returns false if the unregister event fails.

void

EffectUnregisterAllEvents()
Unregister all events callbacks.

bool

UpdateEffectAsset(PKFxEffectAsset updatedAsset, bool resetAllAttributes, bool mismatchAttribsWarning = false)
Use this function when creating a new component from script and assigning a pkfx asset to it.
updatedAsset is the asset to update the component with.
If resetAllAttributes is true, the previous attributes, samplers and event callbacks that were set on this component will be resetted to their default values.
If mismatchAttribsWarning `is `true, this function will log warnings in case of missmatching attributes or samplers between the asset and the component.

void

SetSamplerSafe(Sampler sampler)
Sets the value of an attribute sampler. The sampler parameter contains the name of the attribute sampler to set as well as its description. You should use the constructors of the Sampler class that takes the sampler name and the sampler description as parameter.

int

GetAttributeId(string name, EAttributeType type)
Retrieves the index of an attribute in the emitter.
name is the name of the attribute to get the index of.
type is the type of this attribute.
Returns the attribute index if the attribute name with the corresponding type is found, -1 otherwise.

float

GetAttributeFloat(string name)
Returns the value of the float attribute name. If no attribute of type float with the right name is found, returns 0.0f.

Vector2

GetAttributeFloat2(string name)
Returns the value of the Vector2 attribute name. If no attribute of type float2 with the right name is found, returns Vector2.zero.

Vector3

GetAttributeFloat3(string name)
Returns the value of the Vector3 attribute name. If no attribute of type float3 with the right name is found, returns Vector3.zero.

Vector4

GetAttributeFloat4(string name)
Returns the value of the Vector4 attribute name. If no attribute of type float4 with the right name is found, returns Vector4.zero.

float

GetAttributeFloat(int attributeIdx)
Returns the value of the float attribute at index attributeIdx. If no attribute of type float with the index attributeIdx is found, returns 0.0f.

Vector2

GetAttributeFloat2(int attributeIdx)
Returns the value of the Vector2 attribute at index attributeIdx. If no attribute of type float2 with the index attributeIdx is found, returns Vector2.zero.

Vector3

GetAttributeFloat3(int attributeIdx)
Returns the value of the Vector3 attribute at index attributeIdx. If no attribute of type float3 with the index attributeIdx is found, returns Vector3.zero.

Vector4

GetAttributeFloat4(int attributeIdx)
Returns the value of the Vector4 attribute at index attributeIdx. If no attribute of type float4 with the index attributeIdx is found, returns Vector4.zero.

int

GetAttributeInt(string name)
Returns the value of the int attribute name. If no attribute of type int with the right name is found, returns 0.

Vector2Int

GetAttributeInt2(string name)
Returns the value of the Vector2Int attribute name. If no attribute of type int2 with the right name is found, returns Vector2Int.zero.

Vector3Int

GetAttributeInt3(string name)
Returns the value of the Vector3Int attribute name. If no attribute of type int3 with the right name is found, returns Vector3Int.zero.

PopcornFX.Vector4Int

GetAttributeInt4(string name)
Returns the value of the PopcornFX.Vector4Int attribute name. If no attribute of type int4 with the right name is found, returns Vector4Int.zero.

int

GetAttributeInt(int attributeIdx)
Returns the value of the int attribute at index attributeIdx. If no attribute of type int with the index attributeIdx is found, returns 0.

Vector2Int

GetAttributeInt2(int attributeIdx)
Returns the value of the Vector2Int attribute at index attributeIdx. If no attribute of type int with the index attributeIdx is found, returns 0.

Vector3Int

GetAttributeInt3(int attributeIdx)
Returns the value of the Vector3Int`attribute at index `attributeIdx. If no attribute of type int with the index attributeIdx is found, returns 0.

PopcornFX.Vector4Int

GetAttributeInt4(int attributeIdx)
Returns the value of the PopcornFX.Vector4Int attribute at index attributeIdx. If no attribute of type int with the index attributeIdx is found, returns 0.

bool

GetAttributeBool(string name)
Returns the value of the bool attribute name. If no attribute of type bool with the right name is found, returns false.

PopcornFX.Vector2Bool

GetAttributeBool2(string name)
Returns the value of the PopcornFX.Vector2Bool attribute name. If no attribute of type bool2 with the right name is found, returns PopcornFX.Vector2Bool(false).

PopcornFX.Vector3Bool

GetAttributeBool3(string name)
Returns the value of the PopcornFX.Vector3Bool attribute name. If no attribute of type bool3 with the right name is found, returns PopcornFX.Vector3Bool(false).

PopcornFX.Vector4Bool

GetAttributeBool4(string name)
Returns the value of the PopcornFX.Vector4Bool attribute name. If no attribute of type bool4 with the right name is found, returns PopcornFX.Vector4Bool(false).

bool

GetAttributeBool(int attributeIdx) `Returns the value of the `bool attribute at index attributeIdx. If no attribute of type bool with the index attributeIdx is found, returns false.

PopcornFX.Vector2Bool

GetAttributeBool2(int attributeIdx)
Returns the value of the PopcornFX.Vector2Bool attribute at index attributeIdx. If no attribute of type bool2 with the index attributeIdx is found, returns PopcornFX.Vector2Bool(false).

PopcornFX.Vector3Bool

GetAttributeBool3(int attributeIdx)
Returns the value of the PopcornFX.Vector3Bool attribute at index attributeIdx. If no attribute of type bool3 with the index attributeIdx is found, returns PopcornFX.Vector3Bool(false).

PopcornFX.Vector4Bool

GetAttributeBool4(int attributeIdx)
Returns the value of the PopcornFX.Vector4Bool attribute at index attributeIdx. If no attribute of type bool4 with the index attributeIdx is found, returns PopcornFX.Vector4Bool(false).

void

SetAttributeSafe(string name, float valueX, [float valueY, [float valueZ, [float valueW]]])
Set the attribute name`to the `float values specified. This will not set the attribute if the number of parameters doesn’t match the attribute dimension or if no attribute matches name.

void

SetAttributeSafe(string name, bool valueX, [bool valueY, [bool valueZ, [bool valueW]]])
Set the attribute name`to the `bool values specified. This will not set the attribute if the number of parameters doesn’t match the attribute dimension or if no attribute matches the name.

void

SetAttributeSafe(string name, int valueX, [int valueY, [int valueZ, [int valueW]]])
Set the attribute name`to the `int values specified. This will not set the attribute if the number of parameters doesn’t match the attribute dimension or if no attribute matches the name.

void

SetAttributeSafe(int attribId, float valueX, [float valueY, [float valueZ, [float valueW]]])
Set the attribute at index attribId to the float values specified. This will not set the attribute if the number of parameters doesn’t match the attribute dimension or if attribId is out of bounds.

void

SetAttributeSafe(int attribID, Vector4 value)
Set the attribute at index attribId to the Vector4 value specified. This will not set the attribute if the attribute dimension is not 4 or if attribId is out of bounds.

void

SetAttributeSafe(int attribId, bool valueX, [bool valueY, [bool valueZ, [bool valueW]]])
Set the attribute at index attribId to the bool values specified. This will not set the attribute if the number of parameters doesn’t match the attribute dimension or if attribId is out of bounds.

void

SetAttributeSafe(int attribId, int valueX, [int valueY, [int valueZ, [int valueW]]])
Set the attribute at index attribId to the int values specified. This will not set the attribute if the number of parameters doesn’t match the attribute dimension or if attribId is out of bounds.

void

SetAttributeUnsafe(int attribId, float valueX, [float valueY, [float valueZ, [float valueW]]])
Set the attribute at index attribId to the float values specified.

Warning: This does not perform any check on the attribute type or on the attribute index bounds.

void

SetAttributeUnsafe(int attribId, Vector4 value)
Set the attribute at index attribId to the float4 value specified.

Warning: This does not perform any check on the attribute type or on the attribute index bounds.

void

SetAttributeUnsafe(int attribId, bool valueX, [bool valueY, [bool valueZ, [bool valueW]]])
Set the attribute at index attribId to the bool values specified.

Warning: This does not perform any check on the attribute type or on the attribute index bounds.

void

SetAttributeUnsafe(int attribId, int valueX, [int valueY, [int valueZ, [int valueW]]])
Set the attribute at index attribId to the int4 values specified.

Warning: This does not perform any check on the attribute type or on the attribute index bounds.

Property type

Description

Default value

bool

m_PlayOnStart
If true, starts the emitter when the MonoBehavior Start() method is called, so as soon as the component is enabled in the scene.

true

bool

m_TriggerAndForget
If true , the emitter will not be attached to the GameObject and you will be able to immediately call StartEffect() on the emitter even if the previous effect instance is still running.

false

bool

m_KillEffectOnDestroy
If true, the emitter will be killed when the MonoBehavior OnDestroy() method is called.

false

OnFxStoppedDelegate

m_OnFxStopped
You can set a delegate to be called when the effect has stopped playing.

null

float

PreWarm
Sets the prewarm time. If prewarm is enabled, the effect will look like it was simulated during PreWarm seconds as soon as it is started.

0

Sample code

Here’s an example of a class that can create new emitter components in a scene and sets one of its attributes when a key is pressed:

using UnityEngine;

public class SpawnEffectOnKeyPressed : MonoBehaviour
{
    // We expose a PopcornFX asset to be set in Unity's UI
    public PopcornFX.PKFxEffectAsset m_EffectAsset = null;

    private int m_ColorAttributeIndex = -1;

    private void Start()
    {
        // We retrieve the "ParticlesColor" attribute index in the asset:
        if (m_EffectAsset != null)
            m_ColorAttributeIndex = m_EffectAsset.AttributeIdFromName("ParticlesColor");
    }

    // Update is called once per frame
    void Update()
    {
        // When the player press the "space" key
        if (Input.GetKey(KeyCode.Space))
        {
            // We create a new GameObject in the scene at a random position:
            GameObject effectGameObject = new GameObject();
            Vector3 gameObjectRandomPosition = new Vector3(Random.value, Random.value, Random.value);
            effectGameObject.transform.position = gameObjectRandomPosition * 5.0f;
            // We attach a PopcornFX emitter component to this new GameObject:
            PopcornFX.PKFxEmitter emitterComponent = effectGameObject.AddComponent<PopcornFX.PKFxEmitter>();
            // We set the PopcornFX asset on the emitter component:
            emitterComponent.UpdateEffectAsset(m_EffectAsset, true);
            emitterComponent.m_OnFxStopped = new PopcornFX.PKFxEmitter.OnFxStoppedDelegate(OnEffectStoppedPlaying);
            // We check if the attribute "ParticlesColor" was indeed retrieved corretly in the "Start" method:
            if (m_ColorAttributeIndex != -1)
            {
                // We can now set the attributes values on the component
                Vector4 randomColor = Random.ColorHSV(0, 1); // We compute a random color value to set as the particles color
                // Here we use the attribute index instead of the attribute name to avoid string comparisons in the "SetAttributeSafe" method:
                emitterComponent.SetAttributeSafe(m_ColorAttributeIndex, randomColor);
                // We could also have used:
                // emitterComponent.SetAttributeSafe("ParticlesColor", randomColor);
                // This completly avoid retrieving the attribute index, but it is also less efficient.
            }
        }
    }

    void OnEffectStoppedPlaying(PopcornFX.PKFxEmitter emitterComponent)
    {
        // When the effect has stopped playing, we remove its parent GameObject from the scene:
        Destroy(emitterComponent.gameObject);
    }
}