PopcornFX Requests

PopcornFX Requests Bus

The PopcornFX request bus is used to communicate with the PopcornFX runtime.
It also allow users to spawn and manipulate effects without having to create an emitter component in the scene.

Warning: Be careful, most of those events need the effect to be loaded and instantiated before being used!
The effect async loading and creation is triggered by:

  • PreloadEffectById

  • PreloadEffectByName

  • SpawnEmitterAtLocation

  • SpawnEmitterEntityAtLocation

  • SpawnEffectById

  • SpawnEffectByName

You can check if the emitter has been created by:

  • When using the SpawnEmitterEntityAtLocation event, you can use the emitter component requests bus with the returned AZ::EntityId and check if IsLoaded() returns true

  • Use the IsEffectsPreloadingDone() that will only return true if all effects have finished loading

  • Connect to the PopcornFX events bus and wait for the OnFxCreated() callback

Return type

Description

bool

PreloadEffectById(const AZ::Data::AssetId &assetId)
This function is used to preload an effect. This will avoid the SpawnEmitter* and SpawnEffect* functions to stall the first time an effect is instantiated.
assetId is the identifier corresponding to the “.pkfx” effect asset.
Returns false if assetId is invalid.

bool

PreloadEffectByName(const AZStd::string &path)
This function is used to preload an effect. This will avoid the SpawnEmitter* and SpawnEffect* functions to stall the first time an effect is instantiated.
path`is the path to the “.pkfx” effect asset.
Returns `false if path is invalid.

bool

IsEffectsPreloadingDone()
Returns true when preloading is finished for all effects.

void

SpawnEmitterAtLocation(const AZStd::string &path, const AZ::Transform &transform)
Spawns an emitter with the specified transform without creating any emitter component. The emitter is started automatically.
There is no way to manipulate the emitter properties once it has been created with this method.
`path`is the path to the “.pkfx” effect asset.

AZ::EntityId

SpawnEmitterEntityAtLocation(const AZStd::string &path, const AZ::Transform &transform, bool start)
Spawns an emitter component attached to an entity at the specified transform .
path`is the path to the “.pkfx” effect asset.
`start specifies if the emitter should be started at creation.
Returns an AZ::EntityId corresponding to the emitter component parent entity. You can then use the emitter component requests or emitter component events buses on this entity.

StandaloneEmitter*

SpawnEffectById(const AZ::Data::AssetId &assetId, const SpawnParams &spawnParams)
Spawn an emitter with the specified spawnParams properties without creating any emitter component in the scene. This should be more efficient than spawning effects using components.
assetId is the identifier corresponding to the “.pkfx” effect asset.
Returns a pointer to a StandaloneEmitter. This pointer is owned by the PopcornFX effect manager and should not be freed manually.

StandaloneEmitter*

SpawnEffectByName(const AZStd::string &path, const SpawnParams &spawnParams)
Spawn an emitter with the specified spawnParams properties without creating any emitter component in the scene. This should be more efficient than spawning effects using components.
path is the path to the “.pkfx” effect asset.
Returns a pointer to a StandaloneEmitter. This pointer is owned by the PopcornFX effect manager and should not be deleted manually.
If spawnParams.m_AutoRemove is set to true, the StandaloneEmitter will be destroyed automatically when the effect has finished playing. If not, you should destroy it by calling DestroyEffect.

void

DestroyEffect(StandaloneEmitter *emitter)
Destroys the emitter.

bool

IsEffectAlive(StandaloneEmitter *emitter)
Returns true if the emitter still has living particles.

void

EffectAttachToEntity(StandaloneEmitter *emitter, AZ::EntityId entityId)
Attaches a standalone emitter to the entity identified by entityId: the emitter will follow the entity transforms.
This will not add an emitter component to the entity and you will not be able to manipulate the emitter using the emitter component buses.

void

EffectDetachFromEntity(StandaloneEmitter *emitter)
Detaches the emitter from the entity it was attached to using EffectAttachToEntity.

AZ::EntityId

EffectGetAttachedEntity(StandaloneEmitter *emitter)
Returns the AZ::EntityId identifying the entity the emitter is attached to.

void

EffectSetTransform(StandaloneEmitter *emitter, const AZ::Transform &transform)
Transforms the emitter using the transform parameter.

void

EffectEnable(StandaloneEmitter *emitter, bool enable)
Same as Enable(bool enable)in the emitter component requests bus, but for the standalone emitter.

bool

EffectStart(StandaloneEmitter *emitter)
Same as Start()in the emitter component requests bus, but for the standalone emitter.

bool

EffectStop(StandaloneEmitter *emitter)
Same as Stop()in the emitter component requests bus, but for the standalone emitter.

bool

EffectTerminate(StandaloneEmitter *emitter)
Same as Terminate()in the emitter component requests bus, but for the standalone emitter.

bool

EffectKill(StandaloneEmitter *emitter)
Same as Kill()in the emitter component requests bus, but for the standalone emitter.

bool

EffectRestart(StandaloneEmitter *emitter, bool killOnRestart)
Same as Restart(bool killOnRestart)in the emitter component requests bus, but for the standalone emitter.

bool

EffectIsEnabled(StandaloneEmitter *emitter)
Same as IsEnabled() in the emitter component requests bus, but for the standalone emitter.

bool

EffectIsPlaying(StandaloneEmitter *emitter)
Same as IsPlaying() in the emitter component requests bus, but for the standalone emitter.

void

EffectSetVisible(StandaloneEmitter *emitter, bool visible)
Same as SetVisible(bool visible) in the emitter component requests bus, but for the standalone emitter.

bool

EffectGetVisible(StandaloneEmitter *emitter)
Same as GetVisible() in the emitter component requests bus, but for the standalone emitter.

void

EffectSetTimeScale(StandaloneEmitter *emitter, float timeScale)
Same as SetTimeScale(float timeScale) in the emitter component requests bus, but for the standalone emitter.

float

EffectGetTimeScale(StandaloneEmitter *emitter)
Same as GetTimeScale() in the emitter component requests bus, but for the standalone emitter.

void

EffectSetPrewarmEnable(StandaloneEmitter *emitter, bool enable)
Same as SetPrewarmEnable(bool enable) in the emitter component requests bus, but for the standalone emitter.

bool

EffectGetPrewarmEnable(StandaloneEmitter *emitter)
Same as EffectGetPrewarmEnable() in the emitter component requests bus, but for the standalone emitter.

void

EffecSetPrewarmTime(StandaloneEmitter *emitter, float time)
Same as EffecSetPrewarmTime(float time) in the emitter component requests bus, but for the standalone emitter.

float

EffecGetPrewarmTime(StandaloneEmitter *emitter)
Same as EffecGetPrewarmTime() in the emitter component requests bus, but for the standalone emitter.

AZ::u32

GetAttributesCount(StandaloneEmitter *emitter)
Same as GetAttributesCount() in the emitter component requests bus, but for the standalone emitter.

AZ::s32

GetAttributeType(StandaloneEmitter *emitter, AZ::u32 attribId)
Same as GetAttributeType(AZ::u32 attribId) in the emitter component requests bus, but for the standalone emitter.

AZ::s32

EffectGetAttributeId(StandaloneEmitter *emitter, const AZStd::string &name)
Same as EffectGetAttributeId(const AZStd::string &name) in the emitter component requests bus, but for the standalone emitter.

bool

EffectResetAttributeToDefault(StandaloneEmitter *emitter, AZ::u32 attribId)
Same as EffectResetAttributeToDefault(AZ::u32 attribId) in the emitter component requests bus, but for the standalone emitter.

bool

EffectSetAttributeAsFloat(StandaloneEmitter *emitter, AZ::u32 attribId, float value)
Same as EffectSetAttributeAsFloat(AZ::u32 attribId, float value) in the emitter component requests bus, but for the standalone emitter.

bool

EffectSetAttributeAsFloat2(StandaloneEmitter *emitter, AZ::u32 attribId, const AZ::Vector2 &value)
Same as EffectSetAttributeAsFloat2(AZ::u32 attribId, const AZ::Vector2 &value) in the emitter component requests bus, but for the standalone emitter.

bool

EffectSetAttributeAsFloat3(StandaloneEmitter *emitter, AZ::u32 attribId, const AZ::Vector3 &value)
Same as EffectSetAttributeAsFloat3(AZ::u32 attribId, const AZ::Vector3 &value) in the emitter component requests bus, but for the standalone emitter.

bool

EffectSetAttributeAsFloat4(StandaloneEmitter *emitter, AZ::u32 attribId, const AZ::Vector4 &value)
Same as EffectSetAttributeAsFloat4(AZ::u32 attribId, const AZ::Vector4 &value) in the emitter component requests bus, but for the standalone emitter.

bool

EffectSetAttributeAsInt(StandaloneEmitter *emitter, AZ::u32 attribId, AZ::s32 value)
Same as EffectSetAttributeAsInt(AZ::u32 attribId, AZ::s32 value) in the emitter component requests bus, but for the standalone emitter.

bool

EffectSetAttributeAsInt2(StandaloneEmitter *emitter, AZ::u32 attribId, AZ::s32 valueX, AZ::s32 valueY)
Same as EffectSetAttributeAsInt2(AZ::u32 attribId, AZ::s32 valueX, AZ::s32 valueY) in the emitter component requests bus, but for the standalone emitter.

bool

EffectSetAttributeAsInt3(StandaloneEmitter *emitter, AZ::u32 attribId, AZ::s32 valueX, AZ::s32 valueY, AZ::s32 valueZ)
Same as EffectSetAttributeAsInt3(AZ::u32 attribId, AZ::s32 valueX, AZ::s32 valueY, AZ::s32 valueZ) in the emitter component requests bus, but for the standalone emitter.

bool

EffectSetAttributeAsInt4(StandaloneEmitter *emitter, AZ::u32 attribId, AZ::s32 valueX, AZ::s32 valueY, AZ::s32 valueZ, AZ::s32 valueW)
Same as EffectSetAttributeAsInt4(AZ::u32 attribId, AZ::s32 valueX, AZ::s32 valueY, AZ::s32 valueZ, AZ::s32 valueW) in the emitter component requests bus, but for the standalone emitter.

bool

EffectSetAttributeAsBool(StandaloneEmitter *emitter, AZ::u32 attribId, bool value)
Same as EffectSetAttributeAsBool(AZ::u32 attribId, bool value) in the emitter component requests bus, but for the standalone emitter.

bool

EffectSetAttributeAsBool2(StandaloneEmitter *emitter, AZ::u32 attribId, bool valueX, bool valueY)
Same as EffectSetAttributeAsBool2(AZ::u32 attribId, bool valueX, bool valueY) in the emitter component requests bus, but for the standalone emitter.

bool

EffectSetAttributeAsBool3(StandaloneEmitter *emitter, AZ::u32 attribId, bool valueX, bool valueY, bool valueZ)
Same as EffectSetAttributeAsBool3(AZ::u32 attribId, bool valueX, bool valueY, bool valueZ) in the emitter component requests bus, but for the standalone emitter.

bool

EffectSetAttributeAsBool4(StandaloneEmitter *emitter, AZ::u32 attribId, bool valueX, bool valueY, bool valueZ, bool valueW)
Same as EffectSetAttributeAsBool4(AZ::u32 attribId, bool valueX, bool valueY, bool valueZ, bool valueW) in the emitter component requests bus, but for the standalone emitter.

bool

EffectSetAttributeAsQuaternion(StandaloneEmitter *emitter, AZ::u32 attribId, const AZ::Quaternion &value)
Same as EffectSetAttributeAsQuaternion(AZ::u32 attribId, const AZ::Quaternion &value) in the emitter component requests bus, but for the standalone emitter.

bool

EffectSetAttributeAsColor(StandaloneEmitter *emitter, AZ::u32 attribId, const AZ::Color &value)
Same as EffectSetAttributeAsColor(AZ::u32 attribId, const AZ::Color &value) in the emitter component requests bus, but for the standalone emitter.

float

EffectGetAttributeAsFloat(StandaloneEmitter *emitter, AZ::u32 attribId)
Same as EffectGetAttributeAsFloat(AZ::u32 attribId) in the emitter component requests bus, but for the standalone emitter.

AZ::Vector2

EffectGetAttributeAsFloat2(StandaloneEmitter *emitter, AZ::u32 attribId)
Same as EffectGetAttributeAsFloat2(AZ::u32 attribId) in the emitter component requests bus, but for the standalone emitter.

AZ::Vector3

EffectGetAttributeAsFloat3(StandaloneEmitter *emitter, AZ::u32 attribId)
Same as EffectGetAttributeAsFloat3(AZ::u32 attribId) in the emitter component requests bus, but for the standalone emitter.

AZ::Vector4

EffectGetAttributeAsFloat4(StandaloneEmitter *emitter, AZ::u32 attribId)
Same as EffectGetAttributeAsFloat4(AZ::u32 attribId) in the emitter component requests bus, but for the standalone emitter.

AZ::s32

EffectGetAttributeXAsInt(StandaloneEmitter *emitter, AZ::u32 attribId)
Same as EffectGetAttributeXAsInt(AZ::u32 attribId) in the emitter component requests bus, but for the standalone emitter.

AZ::s32

EffectGetAttributeYAsInt(StandaloneEmitter *emitter, AZ::u32 attribId)
Same as EffectGetAttributeYAsInt(AZ::u32 attribId) in the emitter component requests bus, but for the standalone emitter.

AZ::s32

EffectGetAttributeZAsInt(StandaloneEmitter *emitter, AZ::u32 attribId)
Same as EffectGetAttributeZAsInt(AZ::u32 attribId) in the emitter component requests bus, but for the standalone emitter.

AZ::s32

EffectGetAttributeWAsInt(StandaloneEmitter *emitter, AZ::u32 attribId)
Same as EffectGetAttributeWAsInt(AZ::u32 attribId) in the emitter component requests bus, but for the standalone emitter.

bool

EffectGetAttributeXAsBool(StandaloneEmitter *emitter, AZ::u32 attribId)
Same as EffectGetAttributeXAsBool(AZ::u32 attribId) in the emitter component requests bus, but for the standalone emitter.

bool

EffectGetAttributeYAsBool(StandaloneEmitter *emitter, AZ::u32 attribId)
Same as EffectGetAttributeYAsBool(AZ::u32 attribId) in the emitter component requests bus, but for the standalone emitter.

bool

EffectGetAttributeZAsBool(StandaloneEmitter *emitter, AZ::u32 attribId)
Same as EffectGetAttributeZAsBool(AZ::u32 attribId) in the emitter component requests bus, but for the standalone emitter.

bool

EffectGetAttributeWAsBool(StandaloneEmitter *emitter, AZ::u32 attribId)
Same as EffectGetAttributeWAsBool(AZ::u32 attribId) in the emitter component requests bus, but for the standalone emitter.

AZ::Quaternion

EffectGetAttributeAsQuaternion(StandaloneEmitter *emitter, AZ::u32 attribId)
Same as EffectGetAttributeAsQuaternion(AZ::u32 attribId) in the emitter component requests bus, but for the standalone emitter.

AZ::Color

EffectGetAttributeAsColor(StandaloneEmitter *emitter, AZ::u32 attribId)
Same as EffectGetAttributeAsColor(AZ::u32 attribId) in the emitter component requests bus, but for the standalone emitter.

AZ::s32

EffectGetAttributeSamplersCount(StandaloneEmitter *emitter)
Same as EffectGetAttributeSamplersCount() in the emitter component requests bus, but for the standalone emitter.

AZ::s32

EffectGetAttributeSamplerId(StandaloneEmitter *emitter, const AZStd::string &name)
Same as EffectGetAttributeSamplerId(const AZStd::string &name) in the emitter component requests bus, but for the standalone emitter.

bool

EffectSetAttributeSampler(StandaloneEmitter *emitter, AZ::u32 attribId, AZ::EntityId entityId)
Same as EffectSetAttributeSampler(AZ::u32 attribId, AZ::EntityId entityId) in the emitter component requests bus, but for the standalone emitter.

bool

EffectResetSamplerToDefault(StandaloneEmitter *emitter, AZ::u32 attribId)
Same as EffectResetSamplerToDefault(AZ::u32 attribId) in the emitter component requests bus, but for the standalone emitter.

AZ::EntityId

EffectGetAttributeSampler(StandaloneEmitter *emitter, AZ::u32 attribId)
Same as EffectGetAttributeSampler(AZ::u32 attribId) in the emitter component requests bus, but for the standalone emitter.

void

EffectSetTeleportThisFrame(StandaloneEmitter *emitter)
Same as EffectSetTeleportThisFrame() in the emitter component requests bus, but for the standalone emitter.

float

GetLODBias()
Returns the current level of details bias value.

void

SetLODBias(float bias)
Sets the level of details bias.

void

SetBakingThreadpool()
Internal function used to build the ".pkfx" assets.

StandaloneEmitter

The StandaloneEmitter class is just a handler to an emitter that is was not spawn as a component. It is a way to handle effects in your C++ code without having to add components in your scene.

Warning You cannot directly manipulate the StandaloneEmitter, it is just a handle that should be used with the PopcornFX requests bus functions.

SpawnParams

The SpawnParams class is used to configure an emitter at spawn. It allows for controlling the initial properties of the emitter when it is instantiated.

It holds the following members:

  • m_Enable: If true, the effect is enabled by default.

  • m_AutoRemove: If true, the StandaloneEmitter will be automatically removed. Otherwise you will need to call the Destroy function on the PopcornFX requests bus.

  • m_Transform: Initial emitter transforms.

  • m_PrewarmTime: Prewarm time. If set to 0.0f, the emitter will not be prewarmed and GetPrewarmEnable will return false.

  • m_ParentEntityId: If valid, this will attach the emitter to this entity transforms.

  • m_Attributes: List of attributes to initially set in the emitter. All the attributes not specified here will have their default values.
    You can use AddAttribute(const Attribute &attribute) to set attributes in this list.

  • m_AttributeSamplers: List of samplers to initially set in the emitter. All the samplers not specified here will have their default values.
    You can use AddAttributeSampler(const AttributeSampler &attributeSampler) to set samplers in this list.