Loading...
Searching...
No Matches
Particle Scripts

Particle scripts allow you to define particle systems to be instantiated in your code without having to hard-code the settings themselves in your source code, allowing a very quick turnaround on any changes you make. Particle systems which are defined in scripts are used as templates, and multiple actual systems can be created from them at runtime.

Once scripts have been parsed, your code is free to instantiate systems based on them using the Ogre::SceneManager::createParticleSystem() method which can take both a name for the new system, and the name of the template to base it on (this template name is in the script).

A system can have top-level attributes set using the scripting commands available, such as ’quota’ to set the maximum number of particles allowed in the system. Emitters (which create particles) and affectors (which modify particles) are added as nested definitions within the script. The parameters available in the emitter and affector sections are entirely dependent on the type of emitter / affector.

For a detailed description of the core particle system attributes, see the list below:

# Particle System Attributes

This section describes to attributes which you can set on every particle system using scripts. All attributes have default values so all settings are optional in your script.

- quota
- material
- particle_width
- particle_height
- cull_each
- renderer
- sorted
- local_space
- iteration_interval
- nonvisible_update_timeout

Billboard Renderer Attributes

- billboard_type
- billboard_origin
- billboard_rotation_type
- common_direction
- common_up_vector
- point_rendering
- accurate_facing

See also
  Particle Emitters
  Particle Affectors

## quota

Sets the maximum number of particles this system is allowed to contain at one time. When this limit is exhausted, the emitters will not be allowed to emit any more particles until some destroyed (e.g. through their time_to_live running out). Note that you will almost always want to change this, since it defaults to a very low value (particle pools are only ever increased in size, never decreased).

format: quota <max_particles>
example: quota 10000
default: 10

## material

Sets the name of the material which all particles in this system will use. All particles in a system use the same material, although each particle can tint this material through the use of its colour property.

format: material <material_name>
example: material Examples/Flare
default: none (blank material)

## particle_width

Sets the width of particles in world coordinates. Note that this property is absolute when billboard_type (see below) is set to ’point’ or ’perpendicular_self’, but is scaled by the length of the direction vector when billboard_type is ’oriented_common’, ’oriented_self’ or ’perpendicular_common’.

format: particle_width <width>
example: particle_width 20
default: 100

## particle_height

Sets the height of particles in world coordinates. Note that this property is absolute when billboard_type (see below) is set to ’point’ or ’perpendicular_self’, but is scaled by the length of the direction vector when billboard_type is ’oriented_common’, ’oriented_self’ or ’perpendicular_common’.

format: particle_height <height>
example: particle_height 20
default: 100

## cull_each

All particle systems are culled by the bounding box which contains all the particles in the system. This is normally sufficient for fairly locally constrained particle systems where most particles are either visible or not visible together. However, for those that spread particles over a wider area (e.g. a rain system), you may want to actually cull each particle individually to save on time, since it is far more likely that only a subset of the particles will be visible. You do this by setting the cull_each parameter to true.

format: cull_each <true|false>
example: cull_each true
default: false

## renderer

Particle systems do not render themselves, they do it through ParticleRenderer classes. Those classes are registered with a manager in order to provide particle systems with a particular ’look’. OGRE comes configured with a default billboard-based renderer, but more can be added through plugins. Particle renders are registered with a unique name, and you can use that name in this attribute to determine the renderer to use. The default is ’billboard’.

Particle renderers can have attributes, which can be passed by setting them on the root particle system.

format: renderer <renderer_name>
default: billboard

## sorted

By default, particles are not sorted. By setting this attribute to ’true’, the particles will be sorted with respect to the camera, furthest first. This can make certain rendering effects look better at a small sorting expense.

format: sorted <true|false>
default: false

## local_space

By default, particles are emitted into world space, such that if you transform the node to which the system is attached, it will not affect the particles (only the emitters). This tends to give the normal expected behaviour, which is to model how real world particles travel independently from the objects they are emitted from. However, to create some effects you may want the particles to remain attached to the local space the emitter is in and to follow them directly. This option allows you to do that.

format: local_space <true|false>
default: false

## iteration_interval

Usually particle systems are updated based on the frame rate; however this can give variable results with more extreme frame rate ranges, particularly at lower frame rates. You can use this option to make the update frequency a fixed interval, whereby at lower frame rates, the particle update will be repeated at the fixed interval until the frame time is used up. A value of 0 means the default frame time iteration.

format: iteration_interval <secs>
example: iteration_interval 0.01
default: iteration_interval 0

## nonvisible_update_timeout

Sets when the particle system should stop updating after it hasn’t been visible for a while. By default, visible particle systems update all the time, even when not in view. This means that they are guaranteed to be consistent when they do enter view. However, this comes at a cost, updating particle systems can be expensive, especially if they are perpetual. This option lets you set a ’timeout’ on the particle system, so that if it isn’t visible for this amount of time, it will stop updating until it is next visible. A value of 0 disables the timeout and always updates.

format: nonvisible_update_timeout <secs>
example: nonvisible_update_timeout 10
default: nonvisible_update_timeout 0

# Billboard Renderer Attributes

These are actually attributes of the `billboard` particle renderer (the default), but can be passed to a particle renderer by declaring them directly within the system declaration. Particles using the default renderer are rendered using billboards, which are rectangles formed by 2 triangles which rotate to face the given direction.

## billboard_type

There is more than 1 way to orient a billboard. The classic approach is for the billboard to directly face the camera: this is the default behaviour. However this arrangement only looks good for particles which are representing something vaguely spherical like a light flare. For more linear effects like laser fire, you actually want the particle to have an orientation of its own.

format: billboard_type <point|oriented_common|oriented_self|perpendicular_common|perpendicular_self>
example: billboard_type oriented_self
default: point

The options for this parameter are:

point

  The default arrangement, this approximates spherical particles and the billboards always fully face the camera.

oriented_common

  Particles are oriented around a common, typically fixed direction vector (see common_direction), which acts as their local Y axis. The billboard rotates only around this axis, giving the particle some sense of direction. Good for rainstorms, starfields etc where the particles will traveling in one direction - this is slightly faster than oriented_self (see below).

oriented_self

  Particles are oriented around their own direction vector, which acts as their local Y axis. As the particle changes direction, so the billboard reorients itself to face this way. Good for laser fire, fireworks and other ’streaky’ particles that should look like they are traveling in their own direction.

perpendicular_common

  Particles are perpendicular to a common, typically fixed direction vector (see common_direction), which acts as their local Z axis, and their local Y axis coplanar with common direction and the common up vector (see common_up_vector). The billboard never rotates to face the camera, you might use double-side material to ensure particles never culled by back-facing. Good for aureolas, rings etc where the particles will perpendicular to the ground - this is slightly faster than perpendicular_self (see below).

perpendicular_self

  Particles are perpendicular to their own direction vector, which acts as their local Z axis, and their local Y axis coplanar with their own direction vector and the common up vector (see common_up_vector). The billboard never rotates to face the camera, you might use double-side material to ensure particles never culled by back-facing. Good for rings stack etc where the particles will perpendicular to their traveling direction.

## billboard_origin

This setting controls the fine tuning of where a billboard appears in relation to it's position. It could be that a billboard's position represents it's center (e.g. for fireballs), it could mean the center of the bottom edge (e.g. a tree which is positioned on the ground), the top-left corner (e.g. a cursor).

format: billboard_origin <top_left|top_center|top_right|center_left|center|center_right|bottom_left|bottom_center|bottom_right>
example: billboard_origin top_right
default: center

## billboard_rotation_type

By default, billboard particles will rotate the texture coordinates to according with particle rotation. But rotate texture coordinates has some disadvantage, e.g. the corners of the texture will lost after rotate, and the corners of the billboard will fill with unwanted texture area when using wrap address mode or sub-texture sampling. This settings allow you specifying other rotation type.

format: billboard_rotation_type <vertex|texcoord>
example: billboard_rotation_type vertex
default: texcoord

The options for this parameter are:

vertex

  Billboard particles will rotate the vertices around their facing direction to according with particle rotation. Rotate vertices guarantee texture corners exactly match billboard corners, thus has advantage mentioned above, but should take more time to generate the vertices.

texcoord

  Billboard particles will rotate the texture coordinates to according with particle rotation. Rotate texture coordinates is faster than rotate vertices, but has some disadvantage mentioned above.

## common_direction

Only required if billboard_type is set to oriented_common or perpendicular_common, this vector is the common direction vector used to orient all particles in the system.

format: common_direction <x> <y> <z>
example: common_direction 0 -1 0
default: 0 0 1

## common_up_vector

Only required if billboard_type is set to perpendicular_self or perpendicular_common, this vector is the common up vector used to orient all particles in the system.

format: common_up_vector <x> <y> <z>
example: common_up_vector 0 1 0
default: 0 1 0

## point_rendering

This sets whether or not the BillboardSet will use point rendering rather than manually generated quads.

By default a billboardset is rendered by generating geometry for a textured quad in memory, taking into account the size and orientation settings, and uploading it to the video card. The alternative is to use hardware point rendering, which means that only one position needs to be sent per billboard rather than 4 and the hardware sorts out how this is rendered based on the render state.

Using point rendering is faster than generating quads manually, but is more restrictive. The following restrictions apply:

- Only the Ogre::BBT_POINT type is supported
- Size and appearance of each billboard is controlled by the material
  - Ogre::Pass::setPointSize
  - Ogre::Pass::setPointAttenuation
  - Ogre::Pass::setPointSpritesEnabled
- Per-billboard size is not supported (stems from the above)
- Per-billboard rotation is not supported, this can only be controlled through texture unit rotation
- Only Ogre::BBO_CENTER origin is supported
- Per-billboard texture coordinates are not supported

You will almost certainly want to enable in your material pass both point attenuation and point sprites if you use this option.

## accurate_facing

This sets whether or not the BillboardSet will use a slower but more accurate calculation for facing the billboard to the camera. By default it uses the camera direction, which is faster but means the billboards don’t stay in the same orientation as you rotate the camera. The ’accurate_facing on’ option makes the calculation based on a vector from each billboard to the camera, which means the orientation is constant even whilst the camera rotates.

format: accurate_facing on|off
default: accurate_facing off

## texture_sheet_size

format: texture_sheet_size <stacks> <slices>

A texture sheet is a grid of images that can be used to create simple animations. This method will generate the uv coordinates for the individual sub-rectangles.

These can then be addressed by Ogre::Billboard::setTexcoordIndex().

If the texture size is 512x512 and 'stacks' is 4 and 'slices' is 8, each sub-rectangle of the texture would be 128 texels tall and 64 texels wide.

The numbering counts first across, then down, so top-left is 0, the one to the right of that is 1, and the lower-right is stacks*slices-1.

If you need more flexibility, you can use Ogre::BillboardSet::setTextureCoords() instead.

Parameters

  stacks | number of vertical tiles (rows)
  slices | number of horizontal tiles (columns)

# Particle Emitters

Particle emitters are classified by ’type’ e.g. ’Point’ emitters emit from a single point whilst ’Box’ emitters emit randomly from an area. New emitters can be added to Ogre by creating plugins. You add an emitter to a system by nesting another section within it, headed with the keyword ’emitter’ followed by the name of the type of emitter (case sensitive). Ogre currently supports ’Point’, ’Box’, ’Cylinder’, ’Ellipsoid’, ’HollowEllipsoid’ and ’Ring’ emitters.

See also
  Particle Affectors

## Emitting Emitters

It is possible to ’emit emitters’ - that is, have new emitters spawned based on the position of particles,, for example to product ’firework’ style effects.

This is controlled via the following directives:

emit_emitter_quota

  This parameter is a system-level parameter telling the system how many emitted emitters may be in use at any one time. This is just to allow for the space allocation process.

name

  This parameter is an emitter-level parameter, giving a name to an emitter. This can then be referred to in another emitter as the new emitter type to spawn.

emit_emitter

  This is an emitter-level parameter, and if specified, it means that the particles spawned by this emitter, are themselves emitters of the named type.

## Common Emitter Attributes

This section describes the common attributes of all particle emitters. Specific emitter types may also support their own extra attributes.

- angle
- colour
- colour_range_start
- colour_range_end
- direction
- direction_position_reference
- emission_rate
- position
- velocity
- velocity_min
- velocity_max
- time_to_live
- time_to_live_min
- time_to_live_max
- duration
- duration_min
- duration_max
- repeat_delay
- repeat_delay_min
- repeat_delay_max

## angle

Sets the maximum angle (in degrees) which emitted particles may deviate from the direction of the emitter (see direction). Setting this to 10 allows particles to deviate up to 10 degrees in any direction away from the emitter’s direction. A value of 180 means emit in any direction, whilst 0 means emit always exactly in the direction of the emitter.

format: angle <degrees>
example: angle 30
default: 0

## colour

Sets a static colour for all particle emitted. Also see the colour_range_start and colour_range_end attributes for setting a range of colours. The format of the colour parameter is "r g b a", where each component is a value from 0 to 1, and the alpha value is optional (assumes 1 if not specified).

format: colour <r> <g> <b> [<a>]
example: colour 1 0 0 1
default: 1 1 1 1

## colour_range_start & colour_range_end

As the ’colour’ attribute, except these 2 attributes must be specified together, and indicate the range of colours available to emitted particles. The actual colour will be randomly chosen between these 2 values.

format: as colour
example (generates random colours between red and blue):
colour_range_start 1 0 0
colour_range_end 0 0 1
default: both 1 1 1 1

## direction

Sets the direction of the emitter. This is relative to the SceneNode which the particle system is attached to, meaning that as with other movable objects changing the orientation of the node will also move the emitter.

format: direction <x> <y> <z>
example: direction 0 1 0
default: 1 0 0

## direction_position_reference

Sets the position reference of the emitter. This supersedes direction when present. The last parameter must be 1 to enable it, 0 to disable. You may still want to set the direction to setup orientation of the emitter’s dimensions. When present, particles direction is calculated at the time of emission by doing (particlePosition - referencePosition); therefore particles will travel in a particular direction or in every direction depending on where the particles are originated, and the location of the reference position. Note angle still works to apply some randomness after the direction vector is generated. This parameter is specially useful to create explosions and implosions (when velocity is negative) best paired with HollowEllipsoid and Ring emitters. This is relative to the SceneNode which the particle system is attached to, meaning that as with other movable objects changing the orientation of the node will also move the emitter.

format: direction_position_reference <x> <y> <z> <enable>
example: direction_position_reference 0 -10 0 1
default: direction_position_reference 0 0 0 0

## emission_rate

Sets how many particles per second should be emitted. The specific emitter does not have to emit these in a continuous manner - this is a relative parameter and the emitter may choose to emit all of the second’s worth of particles every half-second for example, the behaviour depends on the emitter. The emission rate will also be limited by the particle system’s ’quota’ setting.

format: emission_rate <particles_per_second>
example: emission_rate 50
default: 10

## position

Sets the position of the emitter relative to the SceneNode the particle system is attached to.

format: position <x> <y> <z>
example: position 10 0 40
default: 0 0 0

## velocity

Sets a constant velocity for all particles at emission time. See also the velocity_min and velocity_max attributes which allow you to set a range of velocities instead of a fixed one.

format: velocity <world_units_per_second>
example: velocity 100
default: 1

## velocity_min & velocity_max

As ’velocity’ except these attributes set a velocity range and each particle is emitted with a random velocity within this range.

format: as velocity
example:
velocity_min 50
velocity_max 100
default: both 1

## time_to_live

Sets the number of seconds each particle will ’live’ for before being destroyed. NB it is possible for particle affectors to alter this in flight, but this is the value given to particles on emission. See also the time_to_live_min and time_to_live_max attributes which let you set a lifetime range instead of a fixed one.

format: time_to_live <seconds>
example: time_to_live 10
default: 5

## time_to_live_min & time_to_live_max

As time_to_live, except this sets a range of lifetimes and each particle gets a random value in-between on emission.

format: as time_to_live
example:
time_to_live_min 2
time_to_live_max 5
default: both 5

## duration

Sets the number of seconds the emitter is active. The emitter can be started again, see repeat_delay. See also the duration_min and duration_max attributes which let you set a duration range instead of a fixed one.

format: duration <seconds>
example:
duration 2.5
default: 0

Note
  A value of 0 means infinite duration. A value < 0 means "burst" where `emission_rate` of particles are emitted once in the next frame.

## duration_min & duration_max

As duration, except these attributes set a variable time range between the min and max values each time the emitter is started.

format: as duration
example:
duration_min 2
duration_max 5
default: both 0

## repeat_delay

Sets the number of seconds to wait before the emission is repeated when stopped by a limited duration. See also the repeat_delay_min and repeat_delay_max attributes which allow you to set a range of repeat_delays instead of a fixed one.

format: repeat_delay <seconds>
example:
repeat_delay 2.5
default: 0

## repeat_delay_min & repeat_delay_max

As repeat_delay, except this sets a range of repeat delays and each time the emitter is started it gets a random value in-between.

format: as repeat_delay
example:
repeat_delay 2
repeat_delay 5
default: both 0

# Standard Particle Emitters

Ogre comes preconfigured with a few particle emitters. New ones can be added by creating plugins: see the Plugin_ParticleFX project as an example of how you would do this (this is where these emitters are implemented).

- Point Emitter
- Box Emitter
- Cylinder Emitter
- Ellipsoid Emitter
- Hollow Ellipsoid Emitter
- Ring Emitter

## Point Emitter

This emitter emits particles from a single point, which is it’s position.

This emitter has no additional attributes over an above the standard emitter attributes.

To create a point emitter, include a section like this within your particle system script:

emitter Point
{
// Settings go here
}

## Box Emitter

This emitter emits particles from a random location within a 3-dimensional box.

Its extra attributes are:

width

  Sets the width of the box (this is the size of the box along its local X axis, which is dependent on the ’direction’ attribute which forms the box’s local Z).
  format: width <units>
  example: width 250
  default: 100

height

  Sets the height of the box (this is the size of the box along its local Y axis, which is dependent on the ’direction’ attribute which forms the box’s local Z).
  format: height <units>
  example: height 250
  default: 100

depth

  Sets the depth of the box (this is the size of the box along its local Z axis, which is the same as the ’direction’ attribute).
  format: depth <units>
  example: depth 250
  default: 100

To create a box emitter, include a section like this within your particle system script:

emitter Box
{
// Settings go here
}

## Cylinder Emitter

This emitter emits particles in a random direction from within a cylinder area, where the cylinder is oriented along the Z-axis.

This emitter has exactly the same parameters as the Box Emitter so there are no additional parameters to consider here - the width and height determine the shape of the cylinder along its axis (if they are different it is an ellipsoid cylinder), the depth determines the length of the cylinder.

## Ellipsoid Emitter

This emitter emits particles from within an ellipsoid shaped area, i.e. a sphere or squashed-sphere area. The parameters are again identical to the Box Emitter, except that the dimensions describe the widest points along each of the axes.

## Hollow Ellipsoid Emitter

This emitter is just like Ellipsoid Emitter except that there is a hollow area in the center of the ellipsoid from which no particles are emitted.

Therefore it has 3 extra parameters in order to define this area:

inner_width

  The width of the inner area which does not emit any particles.

inner_height

  The height of the inner area which does not emit any particles.

inner_depth

  The depth of the inner area which does not emit any particles.

## Ring Emitter

This emitter emits particles from a ring-shaped area, i.e. a little like Hollow Ellipsoid Emitter except only in 2 dimensions.

inner_width

  The width of the inner area which does not emit any particles.

inner_height

  The height of the inner area which does not emit any particles.

# Particle Affectors

Particle affectors modify particles over their lifetime. They are classified by ’type’ e.g. ’LinearForce’ affectors apply a force to all particles, whilst ’ColourFader’ affectors alter the colour of particles in flight. New affectors can be added to Ogre by creating plugins. You add an affector to a system by nesting another section within it, headed with the keyword ’affector’ followed by the name of the type of affector (case sensitive).

Particle affectors actually have no universal attributes; they are all specific to the type of affector.

See also
  Particle Emitters

# Standard Particle Affectors

Ogre comes preconfigured with a few particle affectors. New ones can be added by creating plugins: see the Plugin_ParticleFX project as an example of how you would do this (this is where these affectors are implemented).

- Linear Force Affector
- ColourFader Affector
- ColourFader2 Affector
- Scaler Affector
- Rotator Affector
- ColourInterpolator Affector
- ColourImage Affector
- DeflectorPlane Affector
- DirectionRandomiser Affector
- TextureAnimator Affector

## Linear Force Affector

This affector applies a force vector to all particles to modify their trajectory.

Its extra attributes are:

force_vector

  Sets the vector for the force to be applied to every particle. The magnitude of this vector determines how strong the force is.
  format: force_vector <x> <y> <z>
  example: force_vector 50 0 -50
  default: 0 -100 0 (a fair gravity effect)

force_application

  Sets the way in which the force vector is applied to particle momentum.
  format: force_application <add|average>
  example: force_application average
  default: add
  The options are:

  average

    The resulting momentum is the average of the force vector and the particle’s current motion. Is self-stabilising but the speed at which the particle changes direction is non-linear.

  add

    The resulting momentum is the particle’s current motion plus the force vector. This is traditional force acceleration but can potentially result in unlimited velocity.

To create a linear force affector, include a section like this within your particle system script:

affector LinearForce
{
// Settings go here
}

## ColourFader Affector

This affector modifies the colour of particles in flight.

Its extra attributes are:

red

  Sets the adjustment to be made to the red component of the particle colour per second.
  format: red <delta_value>
  example: red -0.1
  default: 0

green

  Sets the adjustment to be made to the green component of the particle colour per second.
  format: green <delta_value>
  example: green -0.1
  default: 0

blue

  Sets the adjustment to be made to the blue component of the particle colour per second.
  format: blue <delta_value>
  example: blue -0.1
  default: 0

alpha

  Sets the adjustment to be made to the alpha component of the particle colour per second.
  format: alpha <delta_value>
  example: alpha -0.1
  default: 0

To create a colour fader affector, include a section like this within your particle system script:

affector ColourFader
{
// Settings go here
}

## ColourFader2 Affector

This affector is similar to the ColourFader Affector, except it introduces two states of colour changes as opposed to just one. The second colour change state is activated once a specified amount of time remains in the particles life.

red1

  Sets the adjustment to be made to the red component of the particle colour per second for the first state.
  format: red <delta_value>
  example: red -0.1
  default: 0

green1

  Sets the adjustment to be made to the green component of the particle colour per second for the first state.
  format: green <delta_value>
  example: green -0.1
  default: 0

blue1

  Sets the adjustment to be made to the blue component of the particle colour per second for the first state.
  format: blue <delta_value>
  example: blue -0.1
  default: 0

alpha1

  Sets the adjustment to be made to the alpha component of the particle colour per second for the first state.
  format: alpha <delta_value>
  example: alpha -0.1
  default: 0

red2

  Sets the adjustment to be made to the red component of the particle colour per second for the second state.
  format: red <delta_value>
  example: red -0.1
  default: 0

green2

  Sets the adjustment to be made to the green component of the particle colour per second for the second state.
  format: green <delta_value>
  example: green -0.1
  default: 0

blue2

  Sets the adjustment to be made to the blue component of the particle colour per second for the second state.
  format: blue <delta_value>
  example: blue -0.1
  default: 0

alpha2

  Sets the adjustment to be made to the alpha component of the particle colour per second for the second state.
  format: alpha <delta_value>
  example: alpha -0.1
  default: 0

state_change

  When a particle has this much time left to live, it will switch to state 2.
  format: state_change <seconds>
  example: state_change 2
  default: 1

To create a ColourFader2 affector, include a section like this within your particle system script:

affector ColourFader2
{
// Settings go here
}

## Scaler Affector

This affector scales particles in flight.

Its extra attributes are:

rate
  The amount by which to scale the particles in both the x and y direction per second.

scale_range
  The scale factor range to be applied to emitted particles.

  example: scale_range 0.5 1.5
  default: 1.0 1.0

To create a scale affector, include a section like this within your particle system script:

affector Scaler
{
// Settings go here
}

## Rotator Affector

This affector rotates particles in flight.

Its extra attributes are:

rotation_speed_range_start

  The start of a range of rotation speeds to be assigned to emitted particles.
  format: rotation_speed_range_start <degrees_per_second>
  example: rotation_speed_range_start 90
  default: 0

rotation_speed_range_end

  The end of a range of rotation speeds to be assigned to emitted particles.
  format: rotation_speed_range_end <degrees_per_second>
  example: rotation_speed_range_end 180
  default: 0

rotation_range_start

  The start of a range of rotation angles to be assigned to emitted particles.
  format: rotation_range_start <degrees>
  example: rotation_range_start 0
  default: 0

rotation_range_end

  The end of a range of rotation angles to be assigned to emitted particles.
  format: rotation_range_end <degrees>
  example: rotation_range_end 360
  default: 0

To create a rotate affector, include a section like this within your particle system script:

affector Rotator
{
// Settings go here
}

## ColourInterpolator Affector

Similar to the ColourFader and ColourFader2 Affectors, this affector modifies the colour of particles in flight, except it has a variable number of defined stages. It swaps the particle colour for several stages in the life of a particle and interpolates between them.

Its extra attributes are:

time0

  The point in time of stage 0.
  format: time0 <0-1 based on lifetime>
  example: time0 0
  default: 1

colour0

  The colour at stage 0.
  format: colour0 <r> <g> <b> [<a>]
  example: colour0 1 0 0 1
  default: 0.5 0.5 0.5 0.0

time1

  The point in time of stage 1.
  format: time1 <0-1 based on lifetime>
  example: time1 0.5
  default: 1

colour1

  The colour at stage 1.
  format: colour1 <r> <g> <b> [<a>]
  example: colour1 0 1 0 1
  default: 0.5 0.5 0.5 0.0

time2

  The point in time of stage 2.
  format: time2 <0-1 based on lifetime>
  example: time2 1
  default: 1

colour2

  The colour at stage 2.
  format: colour2 <r> <g> <b> [<a>]
  example: colour2 0 0 1 1
  default: 0.5 0.5 0.5 0.0

Note
  The number of stages is variable. The maximal number of stages is 6; where time5 and colour5 are the last possible parameters.

To create a colour interpolation affector, include a section like this within your particle system script:

affector ColourInterpolator
{
// Settings go here
}

## ColourImage Affector

This is another affector that modifies the colour of particles in flight, but instead of programmatically defining colours, the colours are taken from a specified image file. The range of colour values begins from the left side of the image and move to the right over the lifetime of the particle, therefore only the horizontal dimension of the image is used.

Its extra attributes are:

image

  The start of a range of rotation speed to be assigned to emitted particles.
  format: image <image_name>
  example: image rainbow.png
  default: none

To create a ColourImage affector, include a section like this within your particle system script:

affector ColourImage
{
// Settings go here
}

## DeflectorPlane Affector

This affector defines a plane which deflects particles which collide with it.

The attributes are:

plane_point

  A point on the deflector plane. Together with the normal vector it defines the plane.
  default: plane_point 0 0 0

plane_normal

  The normal vector of the deflector plane. Together with the point it defines the plane.
  default: plane_normal 0 1 0

bounce

  The amount of bouncing when a particle is deflected. 0 means no deflection and 1 stands for 100 percent reflection.
  default: bounce 1.0

## DirectionRandomiser Affector

This affector applies randomness to the movement of the particles.

Its extra attributes are:

randomness
  The amount of randomness to introduce in each axial direction.

  Default: randomness 1

scope
  The percentage of particles affected in each run of the affector.

  Default: scope 1.0

keep_velocity
  Determines whether the velocity of particles is unchanged.

  Default: keep_velocity false

## TextureAnimator Affector

This affector makes it possible to have an animated texture for each individual particle.

Its extra attributes are:

texcoord_start
  Sets the texcoord index at which the animation should start.

  Default: texcoord_start 0

texcoord_count
  Sets the number of texcoords to use.

  Default: texcoord_count 0

Note
  you must set this one and start + count must not exceed the number of frames in the sprite sheet

duration
  The length of time it takes to display the whole animation sequence, in seconds.

  If set to 0 (default) the duration equals the particle time to live. Using a different value here, you can play back the animation faster (looping) or slower. When negative, the animation is disabled. This is useful to just pick a random sprite (see below) and keep it.

  Default: duration 0

random_offset
  Start animation at random frame in the texture sheet.

  Default: random_offset false