Torque Game Engine DocumentationVersion 1.3.x
| Torque Game Engine Documentation Version 1.3.x |
Another derivative of GameBaseData, ExplosionData's fields can be used to create impressive explosion effects involving particles, debris objects, dts shapes, sound, and camera shaking. Multiple explosion objects sharing the same datablock can be made to exhibit varied behavior, much as with the DebrisData and SplashData datablocks.
The table below lists each of ExplosionData's fields, along with detailed descriptions.
Table D.16. ExplosionData Member Fields
| Field Name | Type | Default Value | Description |
|---|---|---|---|
| Special Effects Data | |||
| soundProfile | AudioProfilePtr | NULL | Points to the sound profile used to generate sounds for the explosion. Must adhere to semantics associated with the AudioProfilePtr datatype, as defined in the engine. |
| particleEmitter | ParticleEmitterDataPtr | NULL | Points to the ParticleEmitterData datablock used in the generation of particles when the explosion first occurs. particleEmitter is deleted once it's particle count reaches zero. Must adhere to the semantics associated with the ParticleEmitterDataPtr type, as defined in the engine. |
| emitter | ParticleEmitterDataPtr (array) | NULL [EC_NUM_EMITTERS] | Array of pointers to the ParticleEmitterData datablocks used in the generation of particles as the explosion is updated over time. Each entry in the array must adhere to the semantics associated with the ParticleEmitterDataPtr type, as defined in the engine. |
| Debris | DebrisDataPtr (array) | 0 [EC_NUM_DEBRIS_TYPES] | Array of pointers to the DebrisData datablocks used in the generation of debris when the explosion occurs. Note that there will be multiple debris objects created for an entry in the Debris array; the number of debris objects created is determined by the values of the debrisNum and debrisNumVariance fields (see the documentation for each of these fields for more information). Each entry in the array must adhere to the semantics associated with the DebrisDataPtr type, as defined in the engine. |
| subExplosion | ExplosionDataPtr (array) | 0 [EC_MAX_SUB_EXPLOSIONS] | Array of pointers to the ExplosionData datablocks used in the generation of sub-explosions when the explosion occurs. Each entry in the array must adhere to the semantics associated with the ExplosionDataPtr type, as defined in the engine. |
| shockwave | ShockwaveDataPtr | NULL | Note: this field currently has no tangible effect in the engine. The ShockWaveData class is only named, but not fleshed out, in the engine. |
| Rendering Data | |||
| playSpeed | Float | 1.0 | The speed at which to play the explosion's shape animation. Value must be greater than or equal to 0.05, otherwise a console warning is produced and the value is forced to 0.05. Also note: the actual playSpeed used is only guaranteed to be accurate within 0.05 of the specified value. |
| explosionScale | Point3F | The speed at which to play the explosion's shape animation. Value must be greater than or equal to 0.05, otherwise a console warning is produced and the value is forced to 0.05. Also note: the actual playSpeed used is only guaranteed to be accurate within 0.05 of the specified value. | |
| faceViewer | Boolean | False | Specifies whether the explosion shape should be oriented toward the camera. |
| lightStartRadius | Float | 0.0 | The point light radius to use at the beginning of the explosion. If a value of zero is specified for both lightStartRadius and lightEndRadius, no light will be generated from the explosion. |
| lightEndRadius | Float | 0.0 | The point light radius to use at the end of the explosion. The explosion's light radius follows a linear progression from lightStartRadius to lightEndRadius. If a value of zero is specified for both lightStartRadius and lightEndRadius, no light will be generated from the explosion. |
| lightStartColor | ColorF | (1.0, 1.0, 1.0) | The point light color to use at the beginning of the explosion. |
| lightEndColor | ColorF | (1.0, 1.0, 1.0) | The point light color to use at the end of the explosion. The explosion's light color follows a linear progression from lightStartRadius to lightEndRadius. |
| Behavior Data | |||
| playSpeed | float | 1.0 | The speed at which to play the explosion's shape animation. Note: the actual playSpeed used is only guaranteed to be accurate within +/- 0.05 of the value specified. The specified value must be no less 0.05, otherwise a console warning is generated, and the value is forced to 0.05. |
| explosionScale | Point3F | (1.0, 1.0, 1.0) | Contains x, y, and z scale factors for the explosion's size. Note: the actual explosionScale used is only guaranteed to be accurate within +/- 0.01 of the value specified. Each component value must be no less than 0.01, otherwise a console warning is generated and the offending value(s) will be forced to 0.01. |
| explosionScale | Point3F | (1.0, 1.0, 1.0) | Contains x, y, and z scale factors for the explosion's size. Note: the actual explosionScale used is only guaranteed to be accurate within +/- 0.01 of the value specified. Each component value must be no less than 0.01, otherwise a console warning is generated and the offending value(s) will be forced to 0.01. |
| times | Float (array) | [0.0, 1.0, .., 1.0] [EC_NUM_TIME_KEYS] | Array of percentage values representing time thresholds at which to change the explosion's size. Each entry must be between 0.0 and 1.0. If a value greater than 1.0 is supplied, all subsequent entries in the array are ignored. The entries should be supplied in ascending order, if any entry has a value less than a previous entry, it will be ignored. |
| sizes | Point3F (array) | (1.0, 1.0, 1.0) [EC_NUM_TIME_KEYS] | Each entry contains x, y, and z scale factors for the explosion's size. The explosion's size begins at size[0] (with each component scaled by the x, y, and z values of explosionScale). Over time, the size is linearly interpolated to size[1] (also scaled by explosionScale) such that size[1] is achieved when the explosion's life-time is time[1] percent done. From there, the size is interpolated between size[1] and size[2] (each scaled by explosionScale), and so on. Note: the actual sizes used are only guaranteed to be accurate within +/- 0.01 of the value specified. Each component value of each entry is clamped to the range 0.0 to 160.0. |
| lifetimeMS | Integer | 1000 | Used with lifetimeVariance to determine the life-time of the explosion. Measured in milliseconds. The total lifetime is used to set the interpolation scale for the explosion's size and light colors over time. 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 16-bits of precision as well; thus, values of more than about 35 minutes will not behave as expected. |
| lifetimeVariance | Integer | 0 | Used along with lifetimeMS to determine the explosion's total life-time. A random number between -1*lifetimeVariance and lifetimeVariance is generated, and this is added to the value specified in the lifetime field to arrive at the explosions total life-time. Thus, explosions using the same ExplosionData datablock can have varied behavior. Like the lifetime field, lifetimeVariance is measured in milliseconds. The value specified must be no more than the value specified for the lifetime field, otherwise a console warning is generated and lifetimeVariance is set equal to lifetime. The delayMS value is shifted right 5 bits and then clamped to 16-bits of precision, exactly like the lifetime field. |
| delayMS | Integer | 0 | Used along with delayVariance to determine the number of milliseconds to wait before exploding. Value must be non-negative, otherwise a console warning is generated and the value is set to zero. The delayMS value is shifted right 5 bits and then clamped to 16-bits of precision, exactly like the lifetime field. |
| delayVariance | Integer | 0 | Used along with delayMS to determine the number of milliseconds to wait before exploding. A random number between -1*delayVariance and delayVariance is produced and added to the delayMS value to determine the total explosion delay. Value must be no greater than delayMS, otherwise a console warning is generated and the value is set to delayMS. The delayVariance value is shifted right 5 bits and then clamped to 16-bits of precision, exactly like the lifetime field. |
| offset | Float | 0.0 | Scalar value which is multiplied by a normalized random vector with entries ranging from x: [-1.0, 1.0], y: [0.0, 1.0], and z: [-1.0, 1.0], and the result is used to adjust the initial orientation and position of the vector. Thus, explosions sharing the same datablock can have varied initial positions and orientations. Value specified must be non-negative, otherwise a console warning is generated and the value is forced to zero. Values less than 0.001 are ignored. |
| particleDensity | Integer | 10 | The inital particle density to be used, particleDensity specifies the number of particles to be generated and spread over the particleEmitter field's ParticleEmitter hemisphere. The value has 14 bits of precision. |
| particleRadius | Float | 1.0 | The radius used for the particleEmitter field's ParticleEmitterData datablock. |
| debrisThetaMin | Float | 0.0 | Specifies the lower-bound of the range of debris ejection angles relative to the x-axis. If the explosion ejects debris, the debris will be ejected at a random theta-angle (about the x-axis) between debrisThetaMin and debrisThetaMax. Measured in degrees. Value must be in the range of zero to the value of debrisThetaMax. |
| debrisThetaMax | Float | 90.0 | Specifies the upper-bound of the range of debris ejection angles relative to the x-axis. If the explosion ejects debris, the debris will be ejected at a random theta-angle (about the x-axis) between debrisThetaMin and debrisThetaMax. Measured in degrees. Value must be in the range of 0 to 180. |
| debrisPhiMin | Float | 0.0 | Specifies the lower-bound of the range of debris ejection angles relative to the z-axis. If the explosion ejects debris, the debris will be ejected at a random phi-angle (about the x-axis) between debrisPhiMin and debrisPhiMax. Measured in degrees. Value must be in the range of zero to the value of debrisPhiMax. |
| debrisPhiMax | Float | 360.0 | Specifies the upper-bound of the range of debris ejection angles relative to the z-axis. If the explosion ejects debris, the debris will be ejected at a random phi-angle (about the x-axis) between debrisPhiMin and debrisPhiMax. Measured in degrees. Value must be in the range of 0 to 360. |
| debrisNum | Integer | 1 | Used along with debrisNumVariance to determine the number of Debris objects the explosion will emit. Value must be no greater than 1000, otherwise a console warning is produced and the value is forced to 1000. |
| debrisNumVariance | Integer | 0 | A random number between -1*debrisNumVariance and debrisNumVariance is generated and added to debrisNum to determine the number of Debris objects the explosion will create and eject. Thus, multiple Explosion objects can share the same ExplosionData datablock, but produce varied behavior. Value must be no greater than 1000, otherwise a console warning is produced and the value is forced to 1000. Values greater than debrisNum are accepted; if the total number of Debris objects to be ejected is negative, no Debris objects are created. |
| debrisVelocity | Float | 2.0 | Used along with debrisVelocityVariance to determine the velocity at which Debris objects will emit from the explosion. Values less than 0.1 produce a console warning and are clamped to 0.1. To save network transmission, debrisVelocity values are multiplied by ten and stored as integers with 14 bits of precision, so the velocity value used is only guaranteed to be within 0.1 of the value specified, and values above 1639 are not possible. |
| debrisVelocityVariance | Float | 0.0 | A random number between -1*debrisVelocityVariance and debrisVelocityVariance is generated and added to debrisVelocity to determine the velocity at which Debris objects the will emit from the explosion. Values greater than 1000 produce a console warning and are clamped to 1000. debrisVelocityVariance is multiplied by ten, and stored as an integer with 14 bits of precision exactly like debrisVelocity is. |
| shakeCamera | Boolean | False | Specifies whether the camera shake effect will be played when the camera is within camShakeRadius distance from the explosion. |
| camShakeFreq | Point3F | (10.0, 10.0, 10.0) | The frequency with which to shake the camera on the x-, y-, and z- axes. |
| camShakeAmp | Point3F | (1.0, 1.0, 1.0) | The amplitude with which to shake the camera on the x-, y-, and z- axes. |
| camShakeDuration | Float | 1.5 | The amount of time to shake the camera. |
| camShakeRadius | Float | 10.0 | The maximum distance the camera can be from the explosion in order to get shaken. Also used to dampen the camera's initial shake amplitude; the closer the camera is to the end of the explosion's camera shake area, as defined by camShakeRadius, the smaller the camera's initial shake amplitude. |
| camShakeFalloff | Float | 10.0 | The camera shake fall-off factor used to dampen the amplitude of shaking over time. |
| shockwaveOnTerrain | Boolean | False | Note: this field currently has no tangible effect in the engine. Shockwave effects are currently not implemented. |
As you can see, ExplosionData is a fairly large and complicated datablock, but it provides data for Torque's very flexible explosion system which can create some complicated, cool-looking effects.
In the next section, we begin examining Torque's particle datablock system. First we study ParticleEmitterNodeData and ParticleEmitterData. These two datablocks will finish off the GameBaseData-derived tree. Then we finish the particle system by looking at the ParticleData datablock, which derives simply from SimBlockData.