 |
OGRE
1.10.12
Object-Oriented Graphics Rendering Engine
|
|
OGRE
1.10.12
Object-Oriented Graphics Rendering Engine
|
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.
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).
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:
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:
See also: Particle Emitters, Particle Affectors
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.
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
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)
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
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
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
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
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
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
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:
The default arrangement, this approximates spherical particles and the billboards always fully face the camera.
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).
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.
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).
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.
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:
The billboard origin is the top-left corner.
The billboard origin is the center of top edge.
The billboard origin is the top-right corner.
The billboard origin is the center of left edge.
The billboard origin is the center.
The billboard origin is the center of right edge.
The billboard origin is the bottom-left corner.
The billboard origin is the center of bottom edge.
The billboard origin is the bottom-right corner.
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:
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.
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.
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
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
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:
You will almost certainly want to enable in your material pass both point attenuation and point sprites if you use this option.
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
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
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 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
See also: Particle Scripts, Particle Affectors
This section describes the common attributes of all particle emitters. Specific emitter types may also support their own extra attributes.
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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).
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:
Please note that the name of the emitter (’Point’) is case-sensitive.
This emitter emits particles from a random location within a 3-dimensional box. It’s extra attributes are:
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
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
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:
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.
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.
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:
The width of the inner area which does not emit any particles.
The height of the inner area which does not emit any particles.
The depth of the inner area which does not emit any particles.
This emitter emits particles from a ring-shaped area, i.e. a little like Hollow Ellipsoid Emitter except only in 2 dimensions.
The width of the inner area which does not emit any particles.
The height of the inner area which does not emit any particles.
See also: Particle Scripts, Particle 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:
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.
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.
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 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
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).
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:
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)
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:
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.
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:
Please note that the name of the affector type (’LinearForce’) is case-sensitive.
This affector modifies the colour of particles in flight. It’s extra attributes are:
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
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
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
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:
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.
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
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
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
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
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
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
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
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
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:
This affector scales particles in flight. It’s extra attributes are:
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:
This affector rotates particles in flight. This is done by rotating the texture. It’s extra attributes are:
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
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
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
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:
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:
The point in time of stage 0.
format: time0 <0-1 based on lifetime>
example: time0 0
default: 1
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
The point in time of stage 1.
format: time1 <0-1 based on lifetime>
example: time1 0.5
default: 1
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
The point in time of stage 2.
format: time2 <0-1 based on lifetime>
example: time2 1
default: 1
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:
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:
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:
This affector defines a plane which deflects particles which collide with it. The attributes are:
A point on the deflector plane. Together with the normal vector it defines the plane.
default: plane_point 0 0 0
The normal vector of the deflector plane. Together with the point it defines the plane.
default: plane_normal 0 1 0
The amount of bouncing when a particle is deflected. 0 means no deflection and 1 stands for 100 percent reflection.
default: bounce 1.0
This affector applies randomness to the movement of the particles. Its extra attributes are:
The amount of randomness to introduce in each axial direction.
example: randomness 5
default: randomness 1
The percentage of particles affected in each run of the affector.
example: scope 0.5
default: scope 1.0
Determines whether the velocity of particles is unchanged.
example: keep_velocity true
default: keep_velocity false
1.8.13