Ryzom

h1. Particle System Editor

{{>toc}}

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:

h3. Attribute maker

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...

Constant value
* Float
* Integer
* Color
* Basis

Scheme
* Type

> +Float+
> > Value blender
> > Values gradient
> > Curve
> > Value computed from emitter
> > Binary operator
> > > Arg 1/2
> > > Operator
> > > Arg1
> > > Arg2
> > > Modulate
> > > Add
> > > Subtract
>
> +Unsigned integer (link to float param)+
>
> +Color+
> > Color sampled blender
> > Color gradient
> > Color exact blender (unused?)
> > Value computed from emitter
> > Binary operator
> > Texture grouped
>
> +PlaneBasis+
> > Basis gradient
> > Follow path
> > Projection plane
> > No projection
> > XY plane
> > XZ plane
> > YZ plane
> > Spinner
> > Value computed from emitter
> > Binary operator
>
* Source
> Date
> Position
> Inverse mass
> Speed
> Random
> User parameter
> LOD
> Square LOD
> Clamped LOD
> Clamped square LOD
* Input multiplier
* Clamp

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.

!http://dev.ryzom.com/attachments/1459/emmiters.png!

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.

*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.

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_ - Setups 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.

!http://dev.ryzom.com/attachments/1460/zones.png!

Types of zones:
# Plane
# Sphere
# Rectangle
# Disc
# Cylinder

Targets
* Avaible targets
* Bounce/Destroy

_Bounce factor_ - Only valid if the behaviour is set to bounce...

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 - Turbulence force*+

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

+*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)}}