Ryzom

h1. Particle System Editor

h2. Describes

Most game projects use special effects such as: smoke, rain, snow, fire, explosions, magic fx, etc. To create these special effects it is convenient to use a particle system ( http://en.wikipedia.org/wiki/Particle_system ). Ryzom Core using the NeL engine provides a special editor called Object Viewer to create particle systems.

When working with particle systems it is useful to know the following terms:

Attrib maker edition widget - attribute maker is the object that can produce an attribute following some rule. This allow, for example, creation of a color gradient, or color flicker, size strectching and so on...

h3. Workspace

Container for the particle systems.Has the following actions available:

New

Load

Unload

Save

Save as

Insert

New

Reset

h3. Animation Dialog

Play/Stop - ...

Loop - ...

Display bbox - ...

Display helpers - ...

All particle systems - Play all particles systems.

Enable auto count - In this mode, when a particle is spawned, it is guaranteed to be  created. Particle arrays are resized accordingly. This helps to tune the size of arrays that contain particles. (This is well adapted for editing?)?, but shouldn't be used at runtime because array reallocation costs much performance. When the system is  modified by the user, he should click 'Reset auto count' button, so that the array will match the current number of particles. This is useful if the user modified the system causing a decrease in particle number.

Reset auto count - ...

h3. Particles of system

*Integration*

Enable load balancing - ...

Accurate integration - enables a more accurate integration of movement. When activated, integration is performed in a more accurate way when the ellapsed time goes over a threshold, but it is slower to perform.

Enable motion slow down - allows the system to slow down in speed but to keep accuracy in its movement. It is useful for critical situations where the framerate is  very low.

Time threshold - sets integration time.

Max steps - sets the max number of integrations to perform, when accurate integration is activated.

User parameters (1-4) - Saves a user defined value. Ranges from 0 to 1. The values are not saved and their default is 0.f.

Bind - bind/unbind a global value to a user param. For example: global strenght of wind.

*Precompute bounding box (PBBox)* 

Enable precomputed bounding box

Auto - the particle system will recompute the bounding box each time. This may be needed for particle systems that move fast.

Position

Reset

*Level of detail (LOD) managment*

Hand tuned LOD (for emission, color, size: this uses LOD as an input for attribute makers).

Auto LOD

With non-shared systems: modulates the emission period, quantity etc.. to get the desired result.

With shared systems: one version is animated with full LOD (no hand tuned LOD should be applied !).

All versions are displayed with fewer particle than the full LOD, depending on their distance. Visually however, this is not as good as a hand-tuned system, or auto-LOD on non-shared systems.

Sharable - enable/disable sharing. When sharing is enabled, the state of a particle system is the same for all systems that have the same shape. This allows to save memory. However, such system should not be built with LOD in mind (for example, less emission with distance). LOD should be automatic for these systems (see Auto-LOD). This means that sharing is only useful for systems that have the same state, and if they are numerous: motion is performed once, but only for one system with no LOD. LOD is done during display only (when activated).

Auto-LOD - enable / disbale Auto-LOD. When enabled, less particles are displayed when the system is far away. This applies to all particles in a system (unless they override that behaviour).

Start percent DIST - start the Auto-LOD at the given percentage of the max view distance.

Max distance BIAS - when Auto-LOD on a non shared system is used, this sets the degradation of the system when it is far.

A value of 0 means no more emissions at all.

A value of 0.1 means 10% of emission.

A value of 1 means there's no LOD at all.

Degradation exponent - The degradation speed. It is interpreted as an exponent.

Skip Particles - There are 2 modes for the Auto-LOD (applies to shared systems only):

Particles are skipped in the source container when display is performed (default)

Less particles are displayed. Can lead to 'pulse' effects, but is faster.

Maximum view distance - maximum view distance for the particle system (in meters).

LOD ratio - a percentage that indicates where the 2nd LOD is located.

*Global color*

Force global color lighting

Edit global color (Warning: By pass multitexturing, not supported by all types)

Setup a color attenuation scheme with the distance from the viewer. Doesn't act on a particle basis, instead the whole color of the system is changed in an uniform way so it is fast (the same can be achieved on a particle basis). This bypass the source of the scheme : it is set to 0 when the system is on the user, and to 1 when it is at its max distance.

*Life managment parameters*

Presets:

Environment FX - environment FX, not animated when not visible, persistent.

Running environment FX - an environment fx that should run when in a parsed cluster: cascade for example, so that it doesn't start when the player first see it.

Spell FX - always animated, not persistent, garanteed to match the good frame even if framerate is low

Looping spell FX - always animated, persistent until emitter are stopped.

Minor FX - animated when visible, discarded when not visible.

Moving looping FX - persistent, moving fx.

Spawned environment FX - environment fx, not animated when not visible, not persistent

Ground FX - usually fx of foot steps (dust clouds etc.). Always animated, persistents, duration of fxs is garanteed, but not velocity of particle if framerate is too choppy (usually ok because particle stay in place with those fxs).

Projectile FX - like moving looping fx, but not persistent.

UserBehaviour:

Model removed when out of range - Invalidity flags (no direct effect, just indications for a third party, a model holding the system for example). Tell the system that it is invalid when its out of range. This is only a indication flag and must be checked by third party (a model holding the system for example)

PS resource removed when not visible - tells the model holding this system that it will become invalid when its out of the view frustum. This is only an indication flag and must be checked by third party (a model holding it for example). It has no direct effects.

Force life time update

No max numbers steps - when activated, this bypasses the limit on the max number of integration steps. This should NOT be used on FXs that are looping, because it would slow endlessly. Anyway if you try to do that an assertion will ocurr. Typically, this is useful for spell fx because they are short, and it is important that they don't slow down when framerate is too choppy.

Anim Type - tells when animation must be performed

When visible - visible particle systems only are animated.

When visible clusters - particle systems that are in cluster are animated.

Always visible - animate always when not too far.

Die on event - when don't disable, the model holding this particle system will be considered invalid when dieCondition is met. This is only an indication flag and must be checked by third party (a model holding it for example).

Auto delay - tells that the particle system should recompute the delay before death test itself.

This delay is updated when:

The system structure is changed (located added, merge ..)

The lifetime of a located is changed

Emitter parameters are modified

Apply after delay - set a delay before to apply the death condition test. This may be necessary: the particle system could be destroyed because there are no particles, but no particles were emitted yet.

*Link to skeleton (_future, instead additional settings in animation dialog!_)*

Link to skeleton

Unlink

h3. Located

Represents any kind of object that has a position in the world and belongs to a particle system. A located doesn't do anything by itself. You must bind objects to it, such as a particle, a force and so on. Note that a located holds all instances of a object of one type (force, emitter, particles or both...), not only one. Instance of these types are created by emmiters or manually by the user. Not sharable accross systems.

*General*

Coord system:

Particles are local to the system

Particles are in world

User defined

Disgrade with LOD - Force LOD degradation. This will suppress instances immediately, (during the motion pass)  so that there won't be more than maxNumberInstance * dist / maxDist instances. This may not be desirable every time since particles dissapear on screen, which may be noticeable.

Parametric motion -  enable parametric motion. This is needed in a few case only, and can only work if all the forces that apply to the system are integrable.

Max numbers of particles (instances)

Warning (ovqt bug): can not set count max number < manually created instanciates

Set current count particles

*Life time*

Limited life time - At the end of the defined life time particles disappear from the screen if life time is enabled.

Triger on death - Enable a trigger on death. This is used to create emissions on an emitter with a given ID.

Value time - Life time duration.

*Particle mass*

Value mass - Set the mass of locateds.

h3. Emitter

Generate particles.

*General*

Emitted type - Sets the type of located to be emitted. Default is no emission. It can fail when this cause the system to last forever, which is incompatible with the 'BypassMaxNumIntegrationSteps' flag in ParticleSystem)

Type of emission - Sets the emission type. Please note that if the type is 'External only', the located needs to be attached to the system (the system is holding the ID-Located map).

Regular - Use defined emission period  and generation number (the number of particles to generate when an emission occurs).

On death - Emit when the emitter is destroyed.

Once - Emit when the emitter is created.

On bounce - Emit when the emitter bounces.

External only - Emitted explicitly by the system user. A 4 letter ID must be used to identify this kind of emitter. The default ID is NONE.

Direction:

Default - By default, the direction of emission is supposed to be expressed in the same coordinate system as the one of the emitter.

Direction is aligned on the emitter direction - Align the direction of emission on the emitter speed. (This also implies that the coord. system in which the speed vector is expressed if the same than the one of the emitter. ??)

Direction is in world - Sets the particle system identity matrix mode (coord. system) for the direction of emission and allows to change that behaviour. Example of use: a fire p.s is linked to a torch, but the torch doesn't point to the top. So particles are emitted in the axis aligned to the torch. If matrix mode for direction emission is set to the particle system identity matrix, then the direction is interpreted to be in world, and is thus independant from the torch orientation: particles are always spawned in the +K direction.

Direction is local to the system - Sets the particle system world matrix mode (coord. system) for the direction of emission.

User - Sets the particle system user matrix mode (coord. system) for the direction of emission.

Force consisten emission - Enable consistent emission. This tries to keep the number of emitted particle constant by allowing more than one emission cycle per iteration. This is useful to deal with poor framerate. This has several drawbacks though: the motion is in straight lines.

Note: In fact, this should be used when there can't be collisions with the emitted particles, and with main emitters only.

Note: this has no effect if the emission period is 0 (which means emit at each frame)

Bypass Auto-LOD - No Auto-LOD will be applied to that emitter.

Speed inheritance factor - Sets a speed value, to add the emitter speed to the emittee creation speed. this can be < 0.

Delayed emission - Sets a delay in seconds before the first emission (regular emitter only).

Max emission count - Sets a maximum number of particle emission (0 means no limit and is the default). Applies with regular emitter only.

*Emission param*

Emission period - Sets a period for emission (expressed in second).

Emission quantity - Sets the number of particles to be generated at once.

Strength modulation - Sets a speed modulation for the emitter.

Types of emitters:

Directional - Emits in one direction. This can be the 0, 0, 0 vector.

Omni directional - Emits randomly in all direction.

Rectangle - Emits directionnally in a rectangle (useful to produce snow, drop of water ...).

Conic - Same as a directional emitter, but user can also specify the radius for emission.

Spherical

Radial - Direction gives the normal to the plane of emission.

h3. Particle

A single particle\mesh in the system.

Types of particles

Point

Material

Blending mode:

Add - (out = arg0 + arg1)

Modulate - (out = arg0 * arg1)

Alpha blend - 

Alpha test - 

Global color lighting

Z-Test

No Auto-LOD

ZBias

Color

LookAt

Material (link to point material)

Size

Angle 2D

Independent size

Width

Height

Look At parameters

Align on motion - Forces faces to be aligned on motion. This bypass motion blur / align on z axis.

Z-Align - Forces look at particle to align with the z-axis.

Fake motion blur coefficient - Sets the coefficient for motion blur (too high value may give unrealistic result). 'Fake' motion blur (its done by deforming the quad). This is slower, however. This has no effect with rotated particles.

Fake motion blur threshold - Sets the motion blur threshold.

Texture parameters

Enable texture anim

Texture grouped

Multitexturing (using only two texture units)

Main texture

U/V speed 1 texture - set the scroll speed for texture 1(u/v axis) when the main op is used.

U/V speed 2 texture - set the scroll speed for texture 2(u/v axis) when the main op is used.

Texture operation

Add

Modulation

Decal

Bump

Bump factor

Texture name

Use particle data

Alternate texture (link to main texture without bump operation)

Force basic caps - This action as if the system had the most basic caps supported (no EMBM for example...). Should be used only in edition mode for test.

Enable alternate - Use the particle age rather than the global time to compute textures coordinates.

Texture name

FanLight

Material (link to point material)

Size\Angle 2D

Fan Light param

Number fan light - Number of fans used for drawing (minimum is 3, maximum is 128).

Phase smothnes - Smoothness of phases. The default is 0 which means no smoothness. 'n' mean that the phase will be linearly interpolated between each 'n + 1' fans. It ranges from 0 to 31.

Fan light speed - Speed for phase. If the located holding this particle has a limited lifetime, it defines how many 0-2Pi cycles it'll do during its life. Otherwise it defines how many cycles there are in a second.

Fan light intensity - Sets the intensity of fan movement.

Texture param

Ribbon

Material (link to point material)

Size

Tail parameters

Number of segments - Number of segments used with this particle. In this case, it can't be lower than 2.

Duration segment - How many seconds a seg needs to be traversed. Long times will create longer ribbons. It defines the sampling rate for each type of ribbon.

Texture U factor - U-factor for texture mapping.

Texture V factor - V-factor for texture mapping.

Constant length(m) - Length in meter of the ribbon. This is used only if the ribbon mode is set to constant length. These kinds of ribbons are usually slower than variable size ribbons.

LOD degradation - Allows degradation of ribbons with distance of the system (may not be suited when theit paths have wicked angles). Value 1 means no degradation, 0 means nothing will be draw when the system is at its max dist.

Trail coord. system - Coord. system in which trail will reside.

Local

World

User

Father coord. system

Use hermitte interpolation - Use hermitte interpolation.

Orientation - Orienation of slices.

Follow Path

Follow Path XY

Identity

Tail shape

Triangle

Quad

Octogon

Pentagram

Simple segment X

Simple segment Y

Simple segment Z

Simple brace

Texture param

TailDot

Material (link to point material)

Size

Tail param

Number of segments

Duration segment

Constant length(m)

LOD degradation

Trail coord. system

Local

World

User

Father coord. system

Use hermitte interpolation

Tail fading - Enables color fading to black along the tail.

Face

Material (link to point material)

Size

Rotation

Texture param

Shock wave

Material (link to point material)

Size

Angle 2D

Rotation

Shock wave param

Radius cut

Numbers of segments

Texture U factor

Texture param

Ribbon look at

Material (link to point material)

Size

Tail parm

Texture param

Types of mesh

Mesh

Size

Angle 2D

Rotation

Shape

Constraint mesh

Color

Size

Rotations

Hint/precomputed rotations - All meshs are turning in the same manner and only have a rotationnal bias. Any previous set scheme for 3d rotation is kept.

Rotation speed min - Minium angular velocity for particle rotation.

Rotation speed max - Maximum angular velocity for particle rotation.

Number models - Number of rotation configuration we have. The higher it is, the slower it'll be. If this is too low, a lot of particles will have the same orientation. If it is 0, then the hint is disabled. This can't be higher than ConstraintMeshMaxNumPrerotatedModels.

Shape

Morph

Morph mesh edit - Ssetups the mesh for morphing use. There are several restrictions:

All meshs must have the same number of vertices.

All meshes must have the same vertex format.

If these conditions are not met, a 'dummy' mesh will be used instead. If there's only one mesh, no morphing is performed. Note: Morphing not supported with precomputed rotations. First mesh is used instead.

The maximum number of vertices for a constraint mesh - 512.

Number of meshs to be processed at once... - 64.

The maximum number of meshs that can be prerotated - 32.

Force stage modulation (0-3 stages) - Forces the n-th stage of all material to be modulated by the mesh color. This allows to put colors on meshs that haven't got material that allow them.

Force vertex color lighting - Forces all materials to use vertex color lighting.

Texture animation type - None\Global

Reinit when new element is created - Forces the timer for global anim to be reseted when a new mesh is created.

Translation

U/V Start

U/V Speed

U/V Acceleration

Scale

U/V Start

U/V Speed

U/V Acceleration

Rotation

Speed

Acceleration

h3. Force

Description missing

Targets

Available targets

Force intensity

Types of zones:

Gravity - A force that has the -K direction. Mass isn't taken into account (true with a uniform gravity model, near earth).

Directional - A force that has the same direction everywhere. Mass is also taken into account (which is not the case for gravity).

Directions

Global

Spring

Fluid friction

Central gravity - Central gravity. Mass is taken in account here

Cylindric vortex - Has a limited extend. It has unlimited extension in the z direction.  The model is aimed at tunability rather than realism.

Radial viscosity

Tangential viscosity

Brownian - A brownian motion.

Parametric factor - Tells how fast the force acts on particle.

Magnetic -  A magnetic field that has the given direction.

Direction

h3. Collision zone

This is a kind of specialized force, and it has an attached list of the targets. Not sharable accross systems.

Targets

Avaible targets

Bounce/Destroy

Bounce factor - Only valid if the behaviour is set to bounce...

Types of zones:

Plane - A plane over which particles bounce.

Sphere

Rectangle

Disc

Cylinder

h3. Light

Dynamic light created by a particle system.

Color light - ...

Attenuation start - Radius for attenuation start, must be > 0 (TODO, OVQT Bug: OVQT do not check (> 0))

Attenuation end -  Radius for attenuation end.

h3. Sound

Description missing

Sound name - Name of the sound.

Play - ...

Spawn - ...

Mute - Sets mute on/off.

Keep original pitch - Force the sound to use the original pitch that has been entered in the .sound sheet.

Sound pitch - ...

Emission percent - Percent of sound emission. If set to 1, it tries to emit all sounds.

Sound volume - ...

h3. Instanciate

Description missing

Position - ...

Sub component - ...

Scale - ...

Direction - ...

Scale X/Y/Z - ...

h2. Examples of creating a particle system

h2. Videos

+*Ryzom Core: Object Viewer Qt - Particles editor*+

{{youtube(NEkjPbCR-j8,480,360)}}

+*Ryzom Core: Object Viewer Qt - Particle System Texture Animation*+

{{youtube(TDG22yRY9lY,480,360)}}

+*Ryzom Core: Object Viewer Qt - Particle System Demo*+

{{youtube(26ZN2Mki42E,480,360)}}