PopcornFX v2.13

Generic selectors
Exact matches only
Search in title
Search in content
Post Type Selectors
  1. Home
  2. Docs
  3. PopcornFX v2.13
  4. Plugins
  5. Unity Plugin
  6. Emitters

Emitters

Overview

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

 

  1. The emitter can be started, stopped, restarted and terminated using the three buttons.
  2. Exposes general properties of the emitter.
  3. 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 typeDescription
voidStartEffect()
Starts the emitter.
voidStartEffectWithDt(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.
voidTerminateEffect()
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.
voidTerminateEffectWithDt(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
voidStopEffect()
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.
voidStopEffectWithDt(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
voidKillEffect()
Stops the particle emission on the current emitter and kill all the particles emitted from this instance.
voidKillEffectWithDt(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
boolEffectRegisterEvent(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.
boolEffectUnregisterEvent(string eventName, PKFxRaiseEventCallback callback)
Unregister a user callback from an event.
Returns false if the unregister event fails.
voidEffectUnregisterAllEvents()
Unregister all events callbacks.
boolUpdateEffectAsset(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.

voidSetSamplerSafe(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.
intGetAttributeId(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.

floatGetAttributeFloat(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.
Vector2GetAttributeFloat2(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.
Vector3GetAttributeFloat3(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.
Vector4GetAttributeFloat4(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.
floatGetAttributeFloat(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.
Vector2GetAttributeFloat2(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.
Vector3GetAttributeFloat3(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.
Vector4GetAttributeFloat4(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.
intGetAttributeInt(string name)
Returns the value of the int attribute name. If no attribute of type int with the right name is found, returns 0.
Vector2IntGetAttributeInt2(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.
Vector3IntGetAttributeInt3(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.Vector4IntGetAttributeInt4(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.
intGetAttributeInt(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.
Vector2IntGetAttributeInt2(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.
Vector3IntGetAttributeInt3(int attributeIdx)
Returns the value of the Vector3Intattribute at index attributeIdx. If no attribute of type int with the index attributeIdx is found, returns 0.
PopcornFX.Vector4IntGetAttributeInt4(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.
boolGetAttributeBool(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.Vector2BoolGetAttributeBool2(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.Vector3BoolGetAttributeBool3(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.Vector4BoolGetAttributeBool4(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).
boolGetAttributeBool(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.Vector2BoolGetAttributeBool2(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.Vector3BoolGetAttributeBool3(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.Vector4BoolGetAttributeBool4(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).
voidSetAttributeSafe(string name, float valueX, [float valueY, [float valueZ, [float valueW]]])
Set the attribute nameto 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.
voidSetAttributeSafe(string name, bool valueX, [bool valueY, [bool valueZ, [bool valueW]]])
Set the attribute nameto 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.
voidSetAttributeSafe(string name, int valueX, [int valueY, [int valueZ, [int valueW]]])
Set the attribute nameto 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.
voidSetAttributeSafe(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.
voidSetAttributeSafe(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.
voidSetAttributeSafe(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.
voidSetAttributeSafe(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.
voidSetAttributeUnsafe(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.
voidSetAttributeUnsafe(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.
voidSetAttributeUnsafe(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.
voidSetAttributeUnsafe(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 typeDescriptionDefault value
boolm_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
boolm_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
boolm_KillEffectOnDestroy
If true, the emitter will be killed when the MonoBehavior OnDestroy() method is called.
false
OnFxStoppedDelegatem_OnFxStopped
You can set a delegate to be called when the effect has stopped playing.
null
floatPreWarm
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);
    }
}
Was this article helpful to you? Yes No

How can we help?