OGRE  1.10.12
Object-Oriented Graphics Rendering Engine
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.

Loading scripts

Particle system scripts are loaded at initialisation time by the system: by default it looks in all common resource locations (see Root::addResourceLocation) for files with the ’.particle’ extension and parses them. If you want to parse files with a different extension, use the ParticleSystemManager::getSingleton().parseAllSources method with your own extension, or if you want to parse an individual file, use ParticleSystemManager::getSingleton().parseScript.

Once scripts have been parsed, your code is free to instantiate systems based on them using the 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).

Format

Several particle systems may be defined in a single script. The script format is pseudo-C++, with sections delimited by curly braces ({}), and comments indicated by starting a line with ’//’ (note, no nested form comments allowed). The general format is shown below in a typical example:

// A sparkly purple fountain.
particle_system Examples/PurpleFountain
{
material Examples/Flare2
particle_width 20
particle_height 40
cull_each false
quota 10000
billboard_type oriented_self
// Area emitter.
emitter Point
{
angle 15
emission_rate 75
time_to_live 3
direction 0 1 0
velocity_min 250
velocity_max 300
colour_range_start 0 0 0
colour_range_end 1 1 1
}
// Gravity.
affector LinearForce
{
force_vector 0 -100 0
force_application add
}
// Fader.
affector ColourFader
{
red -0.25
green -0.25
blue -0.25
}
}

Every particle system in the script must be given a name, which is the line before the first opening ’{’, in the example this is ’Examples/PurpleFountain’. This name must be globally unique. It can include path characters (as in the example) to logically divide up your particle systems, and also to avoid duplicate names, but the engine does not treat the name as hierarchical, just as a string.

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:

Available Particle System Attributes

See also: Particle Emitters, Particle Affectors

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

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 it’s 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

billboard_type

This is actually an attribute of the ’billboard’ particle renderer (the default), and is an example of passing attributes 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. However, 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 it’s 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

Specifying the point which acts as the origin point for all billboard particles, controls the fine tuning of where a billboard particle appears in relation to it’s position.

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

The options for this parameter are:

top_left

The billboard origin is the top-left corner.

top_center

The billboard origin is the center of top edge.

top_right

The billboard origin is the top-right corner.

center_left

The billboard origin is the center of left edge.

center

The billboard origin is the center.

center_right

The billboard origin is the center of right edge.

bottom_left

The billboard origin is the bottom-left corner.

bottom_center

The billboard origin is the center of bottom edge.

bottom_right

The billboard origin is the bottom-right corner.

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
See also: Particle Emitters, Particle Affectors

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
See also: Particle Emitters, Particle Affectors

point_rendering

This is actually an attribute of the ’billboard’ particle renderer (the default), and 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 ’point’ orientation type is supported
  • Size and appearance of each particle is controlled by the material pass (point_size, point_size_attenuation, point_sprites)
  • Per-particle size is not supported (stems from the above)
  • Per-particle rotation is not supported, and this can only be controlled through texture unit rotation in the material definition
  • Only ’center’ origin is supported
  • Some drivers have an upper limit on the size of points they support - this can even vary between APIs on the same card! Don’t rely on point sizes that cause the point sprites to get very large on screen, since they may get clamped on some cards. Upper sizes can range from 64 to 256 pixels.

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 is actually an attribute of the ’billboard’ particle renderer (the default), and sets whether or not the BillboardSet will use a slower but more accurate calculation for facing the billboard to the camera. Bt 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 true’ 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 0

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

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.

It is also possible to ’emit emitters’ - that is, have new emitters spawned based on the position of particles. See Emitting Emitters

Particle Emitter Universal Attributes

See also: Particle Scripts, Particle Affectors

Particle Emitter Attributes

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

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 burst - 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. A value of 0 means infinite duration. 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

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

See also: Standard Particle Emitters, Particle Scripts, Particle Affectors

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

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
}


Please note that the name of the emitter (’Point’) is case-sensitive.

Box Emitter

This emitter emits particles from a random location within a 3-dimensional box. It’s extra attributes are:

width

Sets the width of the box (this is the size of the box along it’s 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 it’s 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 it’s 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 it’s 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.

See also: Particle Scripts, Particle Emitters

Emitting Emitters

It is possible to spawn new emitters on the expiry 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 when an emitted particle dies.

emit_emitter

This is an emitter-level parameter, and if specified, it means that when particles emitted by this emitter die, they spawn a new emitter of the named type.

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). Ogre currently supports ’LinearForce’ and ’ColourFader’ affectors.

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

See also: Standard Particle Affectors, Particle Scripts, 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

This affector applies a force vector to all particles to modify their trajectory. Can be used for gravity, wind, or any other linear force. It’s 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
}

Please note that the name of the affector type (’LinearForce’) is case-sensitive.

ColourFader Affector

This affector modifies the colour of particles in flight. It’s 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. It’s extra attributes are:

rate

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

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. This is done by rotating the texture. It’s 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. It’s 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

[...]

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.
example: randomness 5
default: randomness 1

scope

The percentage of particles affected in each run of the affector.
example: scope 0.5
default: scope 1.0

keep_velocity

Determines whether the velocity of particles is unchanged.
example: keep_velocity true
default: keep_velocity false