Skip to content

ParticlePlayer Guide

Jump to bottom
Peter Robinson edited this page Jul 5, 2020 · 2 revisions

Introduction

All scene objects are known engine types that allow instances to be created at runtime. The "ParticlePlayer", like all other objects, is derived from a base type of "SceneObject". That means it includes all the fields from that type as well as adding its own fields specific to itself.

The ParticlePlayer, as its name suggests, is the physical representation of a particle effect in a scene. To play a particle effect, a ParticlePlayer must be assigned a valid "ParticleAsset".

TorqueScript Bindings

Exposed Fields

The ParticlePlayer type exposes the following fields in addition to those it inherits. Shown are the equivalent methods available that perform the same action in setting and getting the respective field:

  • Particle
  • setParticleAsset(assetId)
  • getParticleAsset()
  • CameraIdleDistance
  • setCameraIdleDistance(float)
  • getCameraIdleDistance()
  • ParticleInterpolation
  • setParticleInterpolation(bool)
  • getParticleInterpolation()
  • EmissionRateScale
  • setEmissionRateScale(float)
  • getEmissionRateScale()
  • SizeScale
  • setSizeScale(float)
  • getSizeScale()
  • ForceScale
  • setForceScale(float)
  • getForceScale()
  • TimeScale
  • setTimeScale(float)
  • getTimeScale()

The following is a complete description of each of these fields.

Particle (assetId)

Sets the ParticleAsset to play. This must be given in the form of a valid asset ID. A simple example:

%player = new ParticlePlayer();
%player.Particle = "ToyAssets:Bonfire";

For more information on creating an asset, see the ParticleAsset guide.

CameraIdleDistance (float)

This allows you to set the distance (in world units) from any camera in order for the ParticlePlayer to become idle. When idle, the ParticlePlayer does not integrate or render. By default, no distance is specified so the ParticlePlayer will never enter an idle state.

ParticleInterpolation (bool)

Turn on or off particle interpolation with this field. Interpolation calculates intermediate world position, rotation, and size data points between ticks. The default is false.

EmissionRateScale (float)

Controls the scale factor for the particle player emission rate. The emission rate scale is multiplied against the emitter graph field values for "Quantity" and "QuantityVariation" and the effect graph field "QuantityScale". An emitter rate scale of 2 will generate twice the number of particles per second, while a scale of 0.5 will reduce the number of particles emitted by half. This property can be set as a preference globally under "$pref::T2D::ParticlePlayerEmissionRateScale".

SizeScale (float)

Sets the scale factor for the particle player particle sizes. The size scale is multiplied against the emitter field values of "EmitterOffset" and "EmitterSize". It is also multiplied against the emitter graph field values: "SizeX", "SizeXVariation", "SizeXLife", "SizeY", "SizeYVariation", and "SizeYLife" along with the effect graph fields "SizeXScale" and "SizeYScale". Note that the scale is not applied to each value individually but instead follows the equation: ((base +/- variation) * scale) * SizeScale. This property can be set as a preference globally under "$pref::T2D::ParticlePlayerSizeScale".

ForceScale (float)

Adjusts the scale factor for the particle player forces. The force scale is multiplied against the emitter graph field values: "Speed", "SpeedVariation", "SpeedLife", "RandomMotion", "RandomMotionVariation", "RandomMotionLife", "EmissionForce", "EmissionForceVariation", "FixedForce", "FixedForceVariation", and "FixedForceLife". It is important to highlight that the force scale affects all of these graph fields when set. Note that the scale is not applied to each value individually but instead follows the equation: ((base +/- variation) * scale) * ForceScale. This property can be set as a preference globally under "$pref::T2D::ParticlePlayerForceScale".

TimeScale (float)

Sets the scale factor for the particle player particle lifetimes. The time scale is multiplied against the actual elapsed time. So a TimeScale of 2 will cause a particle to age twice as fast (halfing its lifetime), whereas a TimeScale of 0.5 will cause a particle to age twice as slow (doubling its lifetime). This property can be set as a preference globally under "$pref::T2D::ParticlePlayerTimeScale".

TAML Format

Using TorqueScript and the exposed fields or methods described in the previous section, you can programmatically create and configure a ParticlePlayer. You can then export this type to a TAML file or even create a TAML file manually and read it into your game at an appropriate time.

Here is an example ParticlePlayer TAML file in XML format:

<ParticlePlayer
    SceneLayer="5"
    Size="30 10"
    Particle="@asset=ToyAssets:Bonfire"
    EmissionRateScale="2" />

The same example in JSON format:

{
    "ParticlePlayer": {
        "SceneLayer": "5",
        "Size": "30 10",
        "Particle": "@asset=ToyAssets:Bonfire",
        "EmissionRateScale": "2"
    }
}

Additional API

The following methods are available to further configure and control a ParticlePlayer.

play([resetParticles])

This method starts the ParticlePlayer playing. There is an additional parameter that can be specified, "resetParticles", which defines whether to reset (i.e. delete) any existing particles in the scene from this player before starting to play. The default is true.

stop([waitForParticles], [killEffect])

This method stops the ParticlePlayer. There are two optional parameters that can be given when using stop(). The first one is a bool for "waitForParticles". This option defines whether the effect should wait until all particles have died naturally before finally signalling the effect as stopped, or to just stop immediately and delete all particles. The default is true. The second option, "killEffect" is also a bool that determines whether the ParticlePlayer should be deleted after it has stopped. If you are "waiting for particles", the player will be deleted when all particles have died naturally. The default here is false.

getIsPlaying()

This method returns whether the ParticlePlayer is playing or not. Note that in a paused state, a particle player is still considered to be playing.

setPaused(paused)

This method sets whether the ParticlePlayer is paused or not. In a paused state "setPaused(true)", a particle player's rendered particles are still visible and frozen in place in the scene. No further integration takes place until the particle player is unpaused "setPaused(false)", at which point the particle effect continues where it previously left off.

getPaused()

This method returns whether the ParticlePlayer is paused or not.

setEmitterPaused(paused, emitterIndex)

This method sets whether the specified particle emitter is paused or not. In a paused state, a particle emitter's rendered particles are still visible and frozen in place in the scene. All other emitters in a ParticleAsset will continue to play. No further integration of the specified emitter takes place until the emitter is unpaused, at which point the emitter continues where it previously left off.

getEmitterPaused()

This method returns whether the specified particle emitter is paused or not.

setEmitterVisible(visible, emitterIndex)

This method sets whether the specified particle emitter is visible or not. In a non-visible state, a particle emitter's rendered particles are immediately made invisible in the scene. All other emitters in a ParticleAsset will continue to be visible. Although invisible, further integration of the specified emitter still happens so this should not be confused with a paused state.

getEmitterVisible()

This method returns whether the specified particle emitter is visible or not.

Clone this wiki locally