Extensible 3D (X3D)
Part 1: Architecture and base components

40 Particle systems component

# 40.1 Introduction

## 40.1.1 Name

The name of this component is "ParticleSystems". This name shall be used when referring to this component in the COMPONENT statement (see 7.2.5.4 Component statement).

## 40.1.2 Overview

This component specifies how to model particles and their interactions through the application of basic physics principles to affect motion. Table 40.1 provides links to the major topics in this clause.

Table 40.1 — Topics

40.1 Introduction 40.1.1 Name 40.1.2 Overview 40.2 Concepts 40.2.1 Overview 40.2.2 Physics models 40.2.3 Colour ramps 40.2.4 Randomness and variation 40.2.5 Event model interaction 40.2.6 Interaction with other components 40.3 Abstract types 40.3.1 X3DParticleEmitterNode 40.3.2 X3DParticlePhysicsModelNode 40.4 Node reference 40.4.1 BoundedPhysicsModel 40.4.2 ConeEmitter 40.4.3 ExplosionEmitter 40.4.4 ForcePhysicsModel 40.4.5 ParticleSystem 40.4.6 PointEmitter 40.4.7 PolylineEmitter 40.4.8 SurfaceEmitter 40.4.9 VolumeEmitter 40.4.10 WindPhysicsModel 40.5 Support levels Table 40.1 — Topics Table 40.2 — Particle systems component support levels

# 40.2 Concepts

## 40.2.1 Overview

A particle system specifies a process for rendering such effects as fire, smoke, and snow. Although various physics models are available, it is not meant to be used as a simulation engine for testing particle behaviour models. Thus, particle systems are designed for visual effects, not rigid analysis systems.

A particle system is a shape node type as both appearance and texturing need to be controlled in order to create realistic particle system effects. A particle system in and of itself is not considered geometry because it dynamically creates and destroys geometrically shaped particles on the fly. A particle system also has other factors feeding into the visual output different from a typical geometry node.

EXAMPLE Particles may have time-varying colour values.

The geometry node of a shape node is not used at the first support level. If a node supports both levels of the specification, the geometry node takes preference over the geometryType field.

Particles are generated using the current geometry, allowing particle geometry to be changed over time. Old particles that are still current when the specified geometry changes continue to use the original geometry.

## 40.2.2 Physics models

To allow aggregating a collection of nodes with a particular physics model, an X3DParticlePhysicsModelNode abstract node type is provided that is used to derive nodes in which all children nodes of that group are bound by the specified physics model. This can be used to support simple effects such as gravity. The physics models are designed to be composable.

EXAMPLE The BoundedPhysicsModel node can be used with an extrusion as the geometry and then a WindPhysicsModel node can be used with the geometry to produce smoke tunneling effects.

## 40.2.3 Colour ramps

A colour ramp is used to specify the colour cycle over time. A colour ramp is a variation on the normal use of a colour interpolator. The key represents relative time values from the start of the lifetime of the particle. There should be the same number of colours in the node as there are key values. If not, the smaller number of the two values shall be used. For particles that last longer than the last time value, the colour associated with the last time value shall be continued for the rest of the lifetime of the particle.

## 40.2.4 Randomness and variation

Many nodes describe emission as using a random pattern. The random generation model shall use a linear distribution of equal probability across the defined output spectrum.

Nodes that describe a variation field allow for deviation from the described main field value. The variation field is the maximum bound of that value, described as a proportion of the original value. A variation field value of zero does not allow any randomness.

EXAMPLE If field has a value of 10, a variation of 0.25 will allow values to be randomly generated in the range of 7.5 to 12.5. The same field with a value of 1 will only allow a range of randomly generated values between 0.75 and 1.25.

## 40.2.5 Event model interaction

Evaluation of emission and interactions of particles are performed as specified in 4.4.8.3 Execution model. All changes made during current event cascade are first applied. Then, the particles are generated, particle system physics are applied, and rendering of the particles takes place.

Particle systems interact with navigation, pointing device sensors, collision detection and picking according to the underlying geometry type. Point particles, point sprite particles and line particles cannot be picked; other types of particles can be picked.

## 40.2.6 Interaction with other components

There are many different ways to implement particle systems. This specification does not require any particular technology or means of implementation. However, a popular implementation is to use programmable shaders to perform the per-frame evaluation of the particles. While it is not advised, it is possible and legal to supply programmable shaders as part of the particle system's appearance field. If the user supplies a programmable shader, the implementation shall use a CPU-generated model for this case.

The physics model nodes in this component are independent of the physics evaluation defined in 37 Rigid body physics component. This document does not explicitly prohibit interaction between the two models, but does not cater for direct implementation of one by the other ( e.g., use of hardware accelerated physics cards to implement particle systems).

# 40.3 Abstract types

## 40.3.1 X3DParticleEmitterNode

    X3DParticleEmitterNode : X3DNode {
      SFFloat [in,out] mass        0    [0,∞)
      SFNode  [in,out] metadata    NULL [X3DMetadataObject]
      SFBool  [in,out] on          TRUE
      SFFloat [in,out] speed       0    [0,∞)
      SFFloat [in,out] surfaceArea 0    [0,∞)
      SFFloat [in,out] variation   0.25 [0,∞)
    }

The X3DParticleEmitterNode abstract type represents any node that is an emitter of particles. The shape and distribution of particles is dependent on the type of the concrete node.

The on field specifies whether the particle emitter node is enabled or disabled. If the value is FALSE, the node is disabled and no new particles are emitted. If the value is TRUE, particles are emitted. If the node is generating particles and value of the on field is subsequently set to FALSE, no further particles are emitted and already-existing particles finish their expected presentation.

The speed field specifies an initial linear speed that will be imparted to all particles, in speed derived units. It does not signify the direction of the particles. The directional component of the velocity is specified by the concrete node representation.

The variation field specifies a multiplier for the randomness that is used to control the range of possible output values. The bigger the value, the more random the output and the bigger the range of possible initial values possible. A variation of zero does not allow any randomness.

The mass field specifies the basic mass of each particle in mass base units. Mass is needed if gravity or other force-related calculations are to be performed per-particle.

The surfaceArea field specifies the surface area of the particle in area derived units. Surface area is used for calculations such as wind effects per particle. The surfaceArea field value represents an average frontal area that would be presented to the wind, assuming a spherical model for each particle ( i.e., the surface area is the same regardless of direction).

## 40.3.2 X3DParticlePhysicsModelNode

    X3DParticlePhysicsModelNode : X3DNode {
      SFBool [in,out] enabled  TRUE
      SFNode [in,out] metadata NULL [X3DMetadataObject]
    }

The X3DParticlePhysicsModelNode abstract type represents any node that applies a form of constraints on the particles after they have been generated.

The enabled field specifies whether this physics model is currently being applied to the particles.

# 40.4 Node reference

## 40.4.1 BoundedPhysicsModel

    BoundedPhysicsModel : X3DParticlePhysicsModelNode {
      SFBool [in,out] enabled  TRUE
      SFNode [in,out] geometry NULL [X3DGeometryNode]
      SFNode [in,out] metadata NULL [X3DMetadataObject]
    }

The BoundedPhysicsModel node specifies a physics model that applies a user-defined set of geometrical bounds to the particles.

The geometry field specifies a piece of geometry that models the bounds that constrain the location of the particles. When a particle touches the surface of the bounds, it is reflected. The particles may be restricted to an inside location or an outside location. All geometry defined by the bounds are considered to be non-solid, regardless of the setting of the solid field. It does not matter whether the particle impacts the front or back side of the geometry. Particles are reflected at the same angle to the normal of the surface to which they impact, continuing in the same direction. The calculation of the correct normal is determined by the rules of the geometry that forms the bounds.

EXAMPLE A particle can be made to bounce off an elevation grid representing terrain.

## 40.4.2 ConeEmitter

    ConeEmitter : X3DParticleEmitterNode {
      SFFloat [in,out] angle       π/4   [0,π]
      SFVec3f [in,out] direction   0 1 0 [-1,1]
      SFFloat [in,out] mass        0     [0,∞)
      SFNode  [in,out] metadata    NULL  [X3DMetadataObject]
      SFBool  [in,out] on          TRUE
      SFVec3f [in,out] position    0 0 0
      SFFloat [in,out] speed       0     [0,∞)
      SFFloat [in,out] surfaceArea 0     [0,∞)
      SFFloat [in,out] variation   0.25  [0,∞)
    }

The ConeEmitter node is an emitter that generates all the available particles from a specific point in space. Particles are emitted from the single point specified by the position field emanating in a direction randomly distributed within the cone specified by the angle and direction fields at the speed specified by the speed field. The direction field shall be a non-degenerate vector; a value of `0 0 0` is not allowed.

## 40.4.3 ExplosionEmitter

    ExplosionEmitter : X3DParticleEmitterNode {
      SFFloat [in,out] mass        0     [0,∞)
      SFNode  [in,out] metadata    NULL  [X3DMetadataObject]
      SFBool  [in,out] on          TRUE
      SFVec3f [in,out] position    0 0 0
      SFFloat [in,out] speed       0     [0,∞)
      SFFloat [in,out] surfaceArea 0     [0,∞)
      SFFloat [in,out] variation   0.25  [0,∞)
    }

The ExplosionEmitter node is an emitter that generates all the available particles from a specific point in space at the initial time. Particles are emitted from the single point specified by the position field in all directions at the speed specified by the speed field.

## 40.4.4 ForcePhysicsModel

    ForcePhysicsModel : X3DParticlePhysicsModelNode {
      SFBool  [in,out] enabled  TRUE
      SFVec3f [in,out] force    0 -9.8 0 (∞,∞)
      SFNode  [in,out] metadata NULL     [X3DMetadataObject]
    }

The ForcePhysicsModel node specifies a physics model that applies a constant force value to the particles. Force may act in any given direction vector at any strength.

The force field is used to indicate the strength and direction of the force ( e.g., gravity) that should be applied. Force is specified in force base units. If the particles are defined to have zero mass by the emitter, the ForcePhysicsModel node has no effect.

## 40.4.5 ParticleSystem

    ParticleSystem : X3DShapeNode {
      SFNode   [in,out] appearance        NULL      [X3DAppearanceNode]
      SFBool   [in,out] bboxDisplay       FALSE
      SFBool   [in,out] castShadow        TRUE
      SFBool   [in,out] createParticles   TRUE
      SFNode   [in,out] geometry          NULL      [X3DGeometryNode]
      SFBool   [in,out] enabled           TRUE
      SFFloat  [in,out] lifetimeVariation 0.25      [0,1]
      SFInt32  [in,out] maxParticles      200       [0,∞)
      SFNode   [in,out] metadata          NULL      [X3DMetadataObject]
      SFFloat  [in,out] particleLifetime  5         [0,∞)
      SFVec2f  [in,out] particleSize      0.02 0.02 [0,∞)
      SFBool   [in,out] visible           TRUE
      SFBool   [out]    isActive
      SFVec3f  []       bboxCenter        0 0 0
      SFVec3f  []       bboxSize          -1 -1 -1  [0,∞) or -1 -1 -1
      SFNode   []       color             NULL      [X3DColorNode]
      MFFloat  []       colorKey          []        [0,∞)
      SFNode   []       emitter           NULL      [X3DParticleEmitterNode]
      SFString []       geometryType      "QUAD"    ["LINE"|"POINT"|"QUAD"|"SPRITE"|"TRIANGLE"|"GEOMETRY"|...]
      MFNode   []       physics           []        [X3DParticlePhysicsModelNode]
      SFNode   []       texCoord          NULL      [TextureCoordinate|TextureCoordinateGenerator]
      MFFloat  []       texCoordKey       []        [0,∞)
    }

The ParticleSystem node specifies a complete particle system.

The geometryType field specifies the type of geometry that should be used to represent individual particles. Typically, a particle is calculated as a point in space at which the geometry is placed and then rendered using the appearance attributes.

The types of geometry are defined to render in the following way:

- "LINE": A line is drawn along the particle's current velocity vector, for this frame, centered about the particle's position. The length of the line is specified by the particle's height from the particleSize field value.
- "POINT": A point geometry is rendered at the particle's position.
- "QUAD": A 2D quad is rendered aligned in the local coordinate space of the particle system with the face normal pointing along the positive Z axis. Individual quads are not aligned to the user's eye position but are affected in depth by the physics model. The particle's position is at the center of the quad.
- "SPRITE": A point sprite that uses a 2D point position to locate a screen-aligned quad at the center of the particle's location is rendered.
- "TRIANGLE": A 2D quad is rendered using a pair of triangles aligned in the local coordinate space of the particle system with the face normal pointing along the positive Z axis. Individual triangles are not aligned to the user's eye position, but are affected in depth by the physics model. The particle's position is at the center of the triangle.
- "GEOMETRY": The geometry specified by the geometry field is rendered for each particle using the local coordinate system. Changing the value of the geometry field or the definition of the geometry node shall be applied during current computation of the next frame to be rendered.

The geometry field specifies the geometry to be used for each particle when the geometryType field has value "GEOMETRY".

The appearance field holds information that is used for the geometry. All effects, such as material colours and/or multi-textures, are applied to each particle. If a texture coordinate ramp and key is supplied with this geometry, it shall be used in preference to any automatic texture coordinate generation. If automatic texture coordinate generation is used, results shall be based on the entire volume that the particles consume, not locally applied to each particle.

Procedural shaders may also be supplied. The particle system shall manage the position of all particles each frame. This position becomes the initial geometry input to the shader.

The emitter field specifies the type of emitter geometry and properties that the particles are given for their initial positions. After being created, the individual particles are then manipulated according to the physics model(s) specified in the physics field.

The enabled field enables or disables all contained emitter nodes, without changing values of their respective on fields.

The color and colorKey fields specify how to change the base colour of the particle over the lifetime of an individual particle. The colorKey field represents the time of the particle in seconds, while the color field holds a series of colour values to be used at the given key points in time. Between keys, colour values are interpreted in a linear HSV space, using the same rules defined for the ColorInterpolator node. The colour values are defined as per-vertex colour values. Consequently, if an appearance node with material is provided, the material properties will override the colour ramp.

NOTE the original name for the ParticleSystem color field in X3D version 3 is colorRamp.

The isActive outputOnly field indicates whether the particle system is currently running, based on the setup of the node.

EXAMPLE Using an explosion emitter that generates all of its particles at the first time and has them all die at a fixed time later, the particle system will only run for a short amount of time. After that, nothing is visible on-screen or the particle geometry does not need updating any more.

The isActive field sends a value of FALSE when activity has stopped occurring. A particle system without an emitter set can never be active. If the emitter is defined by an EXTERNPROTO that has not yet resolved, isActive shall initially be FALSE, until the point the EXTERNPROTO has loaded and is verified as being a correct node type. If these validity checks pass, isActive is set to TRUE and this defines the local time zero to start the particle effects.

The enabled field controls whether this ParticleSystem is currently active and rendering particles this frame. Setting this value to FALSE will immediately remove all visible particles from the scene from the next frame onwards. Setting the field to TRUE will start the system again from a local time zero. It does not start off from where it was previously. In doing so, it will issue another value of TRUE for isActive. If a value of FALSE is set for enabled, isActive will also be set to FALSE.

The createParticles field is used to control whether any further new particles should be created. This allows the user to stop production of new particles, but keep those already existing in the scene to continue to animate. This differs from the enabled field that would immediately remove all particles. The createParticles field keeps the existing particles in existence until the end of their lifetimes. If there are no particles left in the scene, the system is still considered both active and enabled.

The maxParticles field specifies the maximum number of particles to be generated at one time (subject to player limitations). Support for at least 10,000 particles is required.

The particleLifetime field specifies the nominal duration in seconds of any particle.

The lifetimeVariation field specifies the proportion of the total lifetime that is the amount of allowed linear random variation from the value specified by the particleLifetime field.

The particleSize field describes the dimensions in length base units of the width and height of each particle. Changing this value dynamically will only change new particles created after the change. Particles created before this timestamp will remain at the old size. This field only effects particles using "LINE", "QUAD", "SPRITE", and "TRIANGLE" geometry types.

The texCoord and texCoordKey fields control the texture coordinates of the provided texture(s) in the Appearance node, over time. Particle systems frequently like to change the texture on a particle as it ages, yet there is no good way of accomplishing this through standard interpolators because interpolators have no concept of particle time. This pair of fields hold time-dependent values for the texture coordinates to be applied to the particle. When a particle reaches the next time stamp it moves to the next set of texture coordinates. There is no interpolation of the texture coordinates, just sequenced according to the times defined by texCoordKey.

The node placed in texCoord shall have enough values to work with the numbers required by geometryType. The following numbers and rules for mapping texture coordinates to the quad shall be used:

- "LINE": The coordinates are paired such that the coordinate with lowest value index is associated with the end of the line that is closest to the emitter location and the coordinate with the next higher index is associated with the end of the line furthest from the emitter location. Each timestamp increases the index into the ramp by two.
- "POINT": Texture coordinates are ignored.
- "QUAD": Assuming a quad facing the current viewer position, coordinates are defined in a counter-clockwise order starting at the lower-left corner.
- "SPRITE": Texture coordinates are ignored for this type. Each particle uses the entire supplied texture.
- "TRIANGLE": Assuming two triangles facing the user, only four coordinates are supplied, representing the four corners of the quad. The order is the same as for "QUAD".
- "GEOMETRY": Texture coordinates ramps are ignored for this type. Texture coordinates from the geometry representation are used or automatic texture coordinate generation from the appearance node is used.

NOTE the original name for the ParticleSystem texCoord field in X3D version 3 is texCoordRamp.

## 40.4.6 PointEmitter

    PointEmitter : X3DParticleEmitterNode {
      SFVec3f [in,out] direction   0 1 0 [-1,1]
      SFFloat [in,out] mass        0     [0,∞)
      SFNode  [in,out] metadata    NULL  [X3DMetadataObject]
      SFBool  [in,out] on          TRUE
      SFVec3f [in,out] position    0 0 0
      SFFloat [in,out] speed       0     [0,∞)
      SFFloat [in,out] surfaceArea 0     [0,∞)
      SFFloat [in,out] variation   0.25  [0,∞)
    }

The PointEmitter node is an emitter that generates particles from the point in space specified by the position field. Particles are emitted in the specified direction and speed.

The direction field is a normalized unit vector that specifies a direction along which the particles are to be emitted. If the vector has value (0,0,0), particles are emitted in random directions.

## 40.4.7 PolylineEmitter

    PolylineEmitter : X3DParticleEmitterNode {
      MFInt32 [in]     set_coordIndex
      SFNode  [in,out] coord          NULL  [X3DCoordinateNode]
      SFVec3f [in,out] direction      0 1 0 [-1,1]
      SFFloat [in,out] mass           0     [0,∞)
      SFNode  [in,out] metadata       NULL  [X3DMetadataObject]
      SFBool  [in,out] on             TRUE
      SFFloat [in,out] speed          0     [0,∞)
      SFFloat [in,out] surfaceArea    0     [0,∞)
      SFFloat [in,out] variation      0.25  [0,∞)
      MFInt32 []       coordIndex     -1    [0,∞) or -1
    }

The PolylineEmitter node emits particles along a single polyline. The coordinates for the line along which particles should be randomly generated are taken from a combination of the coord and coordIndex fields. The starting point for generating particles is randomly distributed along this line and given the initial speed and direction. If no coordinates are available, the PolylineEmitter node shall act like a point source located at the local origin.

## 40.4.8 SurfaceEmitter

    SurfaceEmitter : X3DParticleEmitterNode {
      SFFloat [in,out] mass           0     [0,∞)
      SFNode  [in,out] metadata       NULL  [X3DMetadataObject]
      SFBool  [in,out] on             TRUE
      SFFloat [in,out] speed          0     [0,∞)
      SFFloat [in,out] surfaceArea    0     [0,∞)
      SFFloat [in,out] variation      0.25  [0,∞)
      SFNode  []       surface        NULL  [X3DGeometryNode]
    }

The SurfaceEmitter node is an emitter that generates particles from the surface of an object. New particles are generated by randomly choosing a point on that surface. Particles are generated with an initial direction of the normal to that point (including any normal averaging due to normalPerVertex and creaseAngle field settings). If the surface is indicated as not being solid ( solid field set to FALSE), randomly choose from which side of the surface to emit, negating the normal direction when generating from the back side. Only valid geometry shall be used.

The surface field specifies the geometry to be used as the emitting surface.

EXAMPLE A cylinder with both end caps turned off would only generate particles along the side of the cylinder. It would be an error to generate a particle with an initial direction that is not perpendicular to the axis.

NOTE The set_coordIndex and coordIndex were nonfunctional and removed in X3D version 4.0.

## 40.4.9 VolumeEmitter

    VolumeEmitter : X3DParticleEmitterNode {
      MFInt32 [in]     set_coordIndex
      SFNode  [in,out] coord          NULL  [X3DCoordinateNode]
      SFVec3f [in,out] direction      0 1 0 [-1,1]
      SFFloat [in,out] mass           0     [0,∞)
      SFNode  [in,out] metadata       NULL  [X3DMetadataObject]
      SFBool  [in,out] on             TRUE
      SFFloat [in,out] speed          0     [0,∞)
      SFFloat [in,out] surfaceArea    0     [0,∞)
      SFFloat [in,out] variation      0.25  [0,∞)
      MFInt32 []       coordIndex     -1    [0,∞) or -1
      SFBool  []       internal       TRUE
    }

A VolumeEmitter node emits particles from random positions on the surface of a volume, which then propagate either inside or outside the given closed geometry volume.

The internal field indicates whether particles are generated internally or else externally to the defined volume.

## 40.4.10 WindPhysicsModel

    WindPhysicsModel : X3DParticlePhysicsModelNode {
      SFVec3f [in,out] direction  1 0 0 [-1,1]
      SFBool  [in,out] enabled    TRUE
      SFFloat [in,out] gustiness  0.1   [0,∞)
      SFNode  [in,out] metadata   NULL  [X3DMetadataObject]
      SFFloat [in,out] speed      0.1   [0,∞)
      SFFloat [in,out] turbulence 0     [0,1]
    }

The WindPhysicsModel node specifies a physics model that applies a wind effect to the particles. The wind has a random variation factor that allows for the gustiness of the wind to be modelled.

The direction field specifies the direction in which the wind is travelling in the form of a normalized, unit vector. The direction field shall be a non-degenerate vector; a value of `0 0 0` is not allowed.

The speed field specifies the current wind speed in speed derived units. From the wind speed, the force applied per unit-area on the particle is calculated using the following formula. Particle speed is not accelerated faster than current wind speed.

> pressure = 10(2 × log(speed)) × 0.64615

The gustiness specifies how much the wind speed varies from the average value defined by the speed field. The wind speed variation is calculated once per frame and applied equally to all particles.

The turbulence field specifies how much the wind acts directly in line with the direction, and how much variation is applied in directions other than the wind direction. A turbulence value of 0 means no turbulence, while a turbulence value of 1 means maximum turbulence. This is determined per-particle to model how the particle is affected by turbulence.

# 40.5 Support levels

The Particle Systems component provides two levels of support as specified in Table 40.2.

Table 40.2 — Particle systems component support levels

Level | Prerequisites | Nodes/Features | Support
--- | --- | --- | ---
1 | Core 1 Grouping 1 Shape 1 Rendering 1 |  |
|  | X3DParticleEmitterNode | n/a
|  | X3DParticlePhysicsModelNode | n/a
|  | ConeEmitter | All fields fully supported.
|  | ExplosionEmitter | All fields fully supported.
|  | ForcePhysicsModel | All fields fully supported.
|  | ParticleSystem | All fields fully supported, except "SPRITE" and "GEOMETRY" geometry types and the geometry field.
|  | PointEmitter | All fields fully supported.
|  | PolylineEmitter | All fields fully supported.
|  | WindPhysicsModel | All fields fully supported.
2 | Core 1 Grouping 1 Shape 1 Rendering 1 Texturing 1 |  |
|  | All Level 1 nodes | All fields supported as specified for Level 1 except as specified below.
|  | BoundedPhysicsModel | All fields fully supported.
|  | ParticleSystem | All fields fully supported, except "GEOMETRY" geometry type and the geometry field.
|  | SurfaceEmitter | All fields fully supported.
|  | VolumeEmitter | All fields fully supported.
3 | Core 1 Grouping 1 Shape 1 Rendering 1 Texturing 1 |  |
|  | All Level 2 nodes | All fields fully supported.
|  | ParticleSystem | All fields fully supported.