Particle System Attributes

From Multiverse

Particle Scripts

Syntax  •  Attributes  •  Emitters  •  Affectors

Material Scripts

Techniques  •  Texture Units  •  Passes  •  Vertex and Fragment Programs  •  Calling Vertex and Fragment Programs  •  Copying Materials

Compositor Framework

Compositor Scripts  •  Compositor Techniques  •  Compositor Target Passes  •  Compositor Passes

Shaders

Writing Custom Shaders  •  Built-in Shaders  •  Troubleshooting

Contents 1 Summary 2 Attribute descriptions 2.1 accurate_facing 2.2 billboard_origin 2.3 billboard_rotation_type 2.4 billboard_type 2.5 common_direction 2.6 common_up_vector 2.7 cull_each 2.8 iteration_interval 2.9 local_space 2.10 material 2.11 nonvisible_update_timeout 2.12 particle_height 2.13 particle_width 2.14 point_rendering 2.15 quota 2.16 renderer 2.17 sorted

Summary

This article describes attributes of particle systems. All attributes have a default value and thus are optional. Set attributes in a particle script as follows:

particle-effect-name 
{
 attribute value
 attribute value
 ...
}

Where particle-effect-name is the name of the particle effect, and each attribute-value pair is listed on a separate line. For example:

eruption
{
 quota 4000
 material lensflare
 particle_width 200
 particle_height 200
 cull_each false
...
}

Attribute	Valid Values	Default Value	Example
accurate_facing value	on, off	off	accurate_facing on
billboard_origin value	top_left, top_center, , top_right, center_left, center, center_right, bottom_left, bottom_center, bottom_right	center	billboard_origin top_right
billboard_rotation_type	vertex, texcoord	texcoord	billboard_rotation_type vertex
billboard_type value	point, oriented_common, oriented_self, perpendicular_common, perpendicular_self	point	billboard_type oriented_self
common_direction x-vlaue y-value z-value	Three-dimensional unit vector (triplet of numbers, each of which can be -1, 0, or 1)	0 0 1	common_direction 0 -1 0
common_up_vector x-vlaue y-value z-value	Three-dimensional unit vector (triplet of numbers, each of which can be -1, 0, or 1)	0 1 0	common_up_vector 0 1 0
cull_each value	true or false	false	cull_each true
iteration_interval value	Positive real number (seconds)	0	iteration_interval 0.01
local_space	true or false	false	local_space true
material name	Material name (string)	None (blank material)	material Examples/Flare
nonvisible_update_timeout value	Positive real number (seconds)	0	nonvisible_update_timeout 10
particle_height value	Positive integer	100	particle_height 20
particle_width value	Positive integer	100	particle_width 20
point_rendering value	true or false	false	point_rendering true
quota value	Positive integer	10	quota 10000
renderer value	String name	billboard
sorted value	true or false	false	sorted true

Attribute descriptions

accurate_facing

This is an attribute of the default billboard particle renderer, and determines whether or not the billboardset uses 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.

When this attribute is set to true, the calculation is based on a vector from each billboard to the camera, which means the orientation is constant even while the camera rotates.

billboard_origin

Specifies the point that acts as the origin point for all billboard particles, and controls fine tuning of where a billboard particle appears in relation to it's position.

Valid values for attribute are:

• top_left: Origin is the top-left corner.
• top_center: Origin is the center of top edge.
• top_right: Origin is the top-right corner.
• center_left: Origin is the center of left edge.
• center: Origin is the center.
• center_right: Origin is the center of right edge.
• bottom_left: Origin is the bottom-left corner.
• bottom_center: Origin is the center of bottom edge.
• bottom_right: Origin is the bottom-right corner.

billboard_rotation_type

By default, the Client uses vertex billboard rotation, which means billboard particles rotate the texture coordinates with particle rotation. But this technique has some disadvantages: for example, the corners of the texture are lost after rotation, and the corners of the billboard will fill with unwanted texture areas when using wrap address mode or sub-texture sampling.

The options for this parameter are:

• vertex: Billboard particles will rotate the vertices around their facing direction to align with particle rotation. This guarantees texture corners exactly match billboard corners, but takes more time to generate the vertices.
• texcoord: Billboard particles rotate texture coordinates to align with particle rotation. This is faster than the alternative, but has some disadvantages, as described above.

billboard_type

This is an attribute of the default billboard particle renderer, and is an example of passing attributes to a particle renderer by declaring them directly within the system declaration. Billboards are rectangles formed by two triangles which rotate to face the given direction. However, there is more than one 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 represent something roughly spherical like a light flare. Linear effects like laser fire look better with their own orientation.

Valid values for this attribute are:

• point (default): Approximates spherical particles; the billboards always fully face the camera.
• oriented_common: Particles are oriented around a common, typically fixed direction vector (see common_direction), that acts as their local Y axis. The billboard rotates only around this axis, giving the particle some sense of direction. Good for effects such as rainstorms and starfields, where the particles all travel in one direction. This option is slightly faster than oriented_self.
• oriented_self: Particles are oriented around their own direction vector, that acts as their local Y axis. As the particle changes direction, the billboard reorients itself accordingly. Good for 'streaky' particles effects such as laser fire and fireworks that should look like they are travelling 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. Use a double-sided material to ensure particles are not culled by back-facing. Good for effects such as aureolas and rings, where the particles are perpendicular to the ground. This option is slightly faster than perpendicular_self.
• 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. Use double-side material to ensure particles are not culled by back-facing. Good for effects such as rings, where the particles are perpendicular to their travelling direction.

common_direction

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

See also: Particle Emitters, Particle Affectors.

common_up_vector

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

See also: Particle Emitters, Particle Affectors.

cull_each

Particle systems are culled by the bounding box which contains all the particles in the system. This is normally sufficient for locally constrained particle systems where most particles are either visible or not visible together.

However, for particle effects spread over a wider area (for example, a rain system), you may want to cull each particle individually to save time, since it is far more likely that only a subset of the particles will be visible. To do this, set the cull_each attribute to true.

iteration_interval

Usually particle systems are updated based on the frame rate; however this can give variable results at lower frames. Use this option to make the update frequency a fixed interval, so 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.

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.

material

Sets the name of the material which all particles in this system will use. All paticles in a system use the same material.

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, since updating particle systems can be expensive.

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 zero (0) disables the timeout and always updates.

particle_height

Sets the height of particles in world coordinates. This attribute is absolute when billboard_type 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.

particle_width

Sets the width of particles in world coordinates. This attribute is absolute when billboard_type is 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.

point_rendering

This is an attribute of the default billboard particle renderer, and determines 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.
• 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.

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 are destroyed (for example, by their time_to_live running out).

You will almost always want to change this, since it defaults to ten (particle pools are only increased in size, never decreased).

renderer

Particle systems do not render themselves, they do it through ParticleRenderer classes that provide a particular 'look'. By default, the Multiverse Client use a billboard-based renderer. The Multiverse Client supports using alternative particle system renderers, however this capability is not currently exposed to developers.

sorted

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