Torque Game Engine DocumentationVersion 1.3.x
| Torque Game Engine Documentation Version 1.3.x |
Torque's particle system is very powerful. There are three kinds of datablocks associated with the particle system: ParticleEmitterNodeData, ParticleEmitterData, and ParticleData. In this section, we will examine the ParticleEmitterNodeData and ParticleEmitterData datablocks. We look at ParticleData separately in the next section.
ParticleEmitterNodeData and ParticleEmitterData both derive from GameBaseData. In fact, they are the only derivatives of GameBaseData which we have not yet studied so far. ParticleEmitterData datablocks are used for ParticleEmitter objects. ParticleEmitter objects are meant to be attached to other objects, such as players or vehicles. ParticleEmitterNode objects provides a "hook", of sorts, on which to create stand-alone ParticleEmitters.
So, rather than being forced to only use ParticleEmitters on shape objects, we can instead set up a ParticleEmitterNode and have a ParticleEmitter anywhere in our world.
The ParticleEmitterNodeData datablock is simple. It contains only one field, timeMultiple.
Table D.17. ParticleEmitterNodeData Member Fields
| Field Name | Type | Default Value | Description |
|---|---|---|---|
| timeMultiple | Float | 1.0 | Used to set the time scale for particle emissions (see the ParticleEmitterData documentation below for more details on how particle emission works). The value supplied for the timeMultiple field must be no less than 0.01, and no greater than 100.0, otherwise a console warning will be generated and the value will be clamped appropriately. |
Having looked at ParticleEmitterNodeData's single field, we are ready to look at the ParticleEmitterData datablock. It is not the most complicated datablock we've looked at, but it's data fields can be used to create an impressive, wide range of particle effects in the Torque Game Engine.
Table D.18. ParticleEmitterData Member Fields
| Field Name | Type | Default Value | Description |
|---|---|---|---|
| particles | String | NULL | String containing a tab-delimited list of ParticleData datablock names. When a particle is emitted from the emitter, its datablock is randomly selected from the list of valid datablocks supplied in the particles field string. The string must be non-empty and at least one token must evaluate to a valid ParticleData datablock name. String must also be less than 256 characters long. If either of these conditions is not met, a console warning will be produced and the datablock's onAdd() method will fail. |
| ejectionPeriodMS | Integer | 100 | Used along with periodVarianceMS to determine the frequency with which to emit particles. See the periodVarianceMS field for more details. Stored with only 10 bits of precision, so values above 1023 are not possible. If value is less than 1, a console warning is generated and the value is forced to 1. |
| periodVarianceMS | Integer | 0 | Used along with ejectionPeriodMS to determine the frequency with which to emit particles. Each time a particle is emitted, a random value between -1*periodVarianceMS and periodVarianceMS is generated and added to ejectionPeriodMS to determine the time at which to emit the next particle. So, with the default values ejectionPeriodMS = 100 and periodVarianceMS = 0, particles would be emitted exactly 10 times per second. This field's value is stored with only 10 bits of precision, so values above 1023 are not possible. Value must be less than the value of ejectionPeriodMS, otherwise a console warning is generated and the value is set to ejectionPeriodMS - 1. |
| thetaMin | Float | 0.0 | Each time a particle is emitted, it is given an ejection direction. This direction is defined by the thetaMin, thetaMax, phiReferenceVel, and phiVariance fields. A random angle between thetaMin and thetaMax is generated and provides the ejection direction angle relative to the x-axis. This field's value is measured in degrees. The value may range from 0.0 to 180.0, and must be less than thetaMax. If one of these conditions is not met, a consolw warning is generated and the value is clamped accordingly. |
| thetaMax | Float | 90.0 | Each time a particle is emitted, it is given an ejection direction. See the thetaMin field documentation for more information. thetaMax defines the maximum ejection direction angle relative to the x-axis. This field's value is measured in degrees. The value may range from 0.0 to 180.0; if it lies outside this range, a console warning is generated and the value is clamped. |
| phiReferenceVel | Float | 0.0 | Each time a particle is emitted, it is given an ejection direction, see the thetaMin field documentation for more information. phiReferenceVel and phiVariance determine the particle's ejection angle about the z-axis. Particles are emitted starting at 0 degrees, and the emission angle is rotated over time, according to the velocity specified in phiReferenceVel, as well as random numbers generated from phiVariance. See the phiVariance field documentation. This field's value is measured in degrees per second and may range from 0.0 to 360.0; if it lies outside this range, a console warning is generated and the value is clamped. |
| phiVariance | Float | 360.0 | Used along with phiReferenceVel to determine the angle relative to the z-axis at which to eject a particle. Each time a particle is generated, a new ejection direction is determined for it. The ejection angle about the z-axis is defined by adding a random variable between 0.0 and phiVariance to the angle determined by phiRefVelocity. See the phiRefVelocity field documentation for more information. This field's value is measured in degrees and must lie in the range of 0.0 to 360.0; if it does not, a console warning is generated and the value is clamped. |
| ejectionOffset | Float | 0.0 | Each particle is given an ejection direction at which to be emitted, and ejectionOffset specifies the distance in this direction from the particle emitter a particle will be emitted at. This field's value must be non-negative, otherwise a console warning is generated and the value is forced to 0.0. The actual ejectionOffset value used is only guaranteed to be within 0.01 of the value used, and values greater than 655 are not possible. |
| ejectionVelocity | Float | 2.0 | Used along with velocityVariance to determine the initial velocity at which a particle is emitted. See the velocityVariance field documentation for more details. This field's value must be non-negative, otherwise a console warning is generated and the value is forced to 0.0. The actual value used is only guaranteed to be within 0.01 of the value specified, and values larger than 655 are not valid. |
| velocityVariance | Float | 1.0 | Used along with ejectionVelocity to determine the speed at which a particle will be emitted. Each particle gets a new velocity, which is calculated by adding a random number between -1*velocityVariance and velocityVariance to ejectionVelocity. This field's value must be non-negative and must not be greater than ejectionVelocity, otherwise a console warning is generated and the value is clamped appropriately. The actual value used is only guaranteed to be within 0.01 of the value specified, and values larger than 163 are not valid. |
| orientParticles | Boolean | False | Specifies whether emitted particles should be oriented as billboards (always face directly towards the camera), or if they should face the emission direction (see the field documentation for thetaMin, thetaMax, phiReferenceVel, and phiVariance for more information on emission direction). True means the particles should be oriented toward the emission direction, False means particles should be oriented as billboards. |
| orientOnVelocity | Boolean | True | Only applicable when orientParticles is True. Specifies whether emitted particles will be checked for velocity. If True, and the particle has no velocity, it will not be rendered. If True, and the particle has a velocity, the velocity magnitude will affect the particle's rendered size. False means that the particle's velocity will not affect the rendered size. |
| useEmitterSizes | Boolean | True | Specifies whether the particle's datablock sizes array field should be over-ridden by the sizes array provided by the ParticleEmitter object. True implies that the particle's datablock should be over-ridden. |
| useEmitterColors | Boolean | True | Specifies whether the particle's datablock colors array field should be over-ridden by the colors array provided by the ParticleEmitter object. True implies that the particle's datablock should be over-ridden. |
| overrideAdvance | Boolean | False | Specifies whether a newly created particle's acceleration, color, and other settings should begin being updated immediately after it is created. If false, the new particle is updated immediately. If true, the particle's time advancement system is initially deferred. |
| lifetimeMS | Integer | 1000 | Used with lifetimeVarianceMS to determine the total life-time of each emitted particle. Measured in milliseconds. This field's value must be greater than zero, otherwise a console warning is generated and the value is forced to one. To save network transmission bandwidth, the value of lifetimeMS is shifted-right 5 bits, implying a loss of precision. Thus, the lifetime value used may be up to 31 milliseconds less than the value specified. After being shifted, the value is clamped to 10-bits of precision as well; thus, values of more than about 32000 milliseconds will not behave as expected. |
| lifetimeVarianceMS | Integer | 0 | Used with lifetimeVarianceMS to determine the total life-time of each emitted particle. Measured in milliseconds. Each time a particle is created, a random number between -1*lifetimeVarianceMS and lifetimeVarianceMS is generated and added to lifetimeMS to determine the particle's total lifetime. This field's value must be no greater than that of lifetimeMS, otherwise a console warning is generated and the value is clamped. The lifetimeVarianceMS value is shifted and stored with 10-bit precision in the exact manner that lifetimeMS's value is. |
Torque's particle system is very robust, yet simple to use. As you can see the ParticleEmitterData and ParticleEmitterNodeData datablocks are not overwhelmingly complex, yet they can be used to automatically produce some very cool effects.
There is still one particle-related datablock left to study: ParticleData. ParticleData does not derive from GameBaseData. Indeed, we have finished examing all of the datablocks in the GameBaseData tree. Now, with ParticleData in the next section, we move back to studying the datablocks which derive from the more basic SimData.