22.3. The ParticleArchetype Object

Added SDK 0.28.0

The ParticleArchetype is used to fully describe a particle system for use with the ParticleManager. An archetype is constructed from an easily serializable data description, whose format is described as below.

Serialization and deserialization of the archetypes should be done using the methods on ParticleManager which will both serialize and compress the archetype description to reduce file sizes.

{
    // Properties of the ParticleSystem
    system: {
        center         : [0, 0, 0],
        halfExtents    : [1, 1, 1],
        zSorted        : false,
        maxSortSteps   : 136,
        trackingEnabled: false
    },
    // Properties of the ParticleRenderer
    renderer: {
        name: "default"
        .. renderer parameters
    },
    // Properties of the ParticleUpdater
    updater: {
        name: "default"
        .. updater parameters
    },
    // Properties of the ParticleSynchronizer
    synchronizer: {
        name: "default"
        .. synchronization parameters
    },
    // Animation system definition.
    animationSystem: "default",
    // Pre-packed textures.
    packedTexture0: null,
    ...
    packedTextureN: null
    // Particle descriptions.
    particles: {
        "particle-name": {
            // Particle animation definition.
            animation: null,
            // Particle animation tweaks.
            tweaks: null,
            // Per particle textures when not using pre-packed textures.
            texture0: null,
            ...
            texture4: null,
            // Per particle uv-maps when using pre-packed textures.
            texture-uv0: null,
            ...
            texture-uvN: null
        }
        ...
    },
    // ParticleEmitter descriptions.
    emitters: [
        {
            name: "default",
            ... emitter parameters
        }
        ...
    ]
}

This data description does not require every field to be specified, as part of this data-driven API, the individual components of the particle systems will verify the structure of the input description, filling in missing fields with default values and reporting useful errors and/or warnings when the input description is in error.

The values shown above, are the basic default values for an archetype description.

system

Parameters of the ParticleSystems that will be created for an instance of this archetype.

center (Default [0, 0, 0])

The center of the particle system’s local extents. The extents of the particle systems limit the positions of particles within the systems, and provide a means of culling non-visible systems in a Scene.

halfExtents (Default [1, 1, 1])

The local half-extents of the particle system.

maxParticles (Optional)

The maximum number of particles the system will be able to hold. The absolute maximum value for this property is 65536.

If unspecified, this value will be computed from the archetype emitters.

maxSpeed (Optional)

The maximum speed (in local coordinates) achievable for a particle in the system. This field is required to define a suitable normalization of particle velocities into texture storage for the GPU.

If unspecified, this value will be computed from the archetype emitters.

maxLifeTime (Optional)

The maximum time for which any particle in the system will be able to live for. This field is required to define a suitable normalization of particle life-times into texture storage for the GPU.

If unspecified, this value will be computed from the archetype emitters.

zSorted (Default false)

Whether this system will have its views z-sorted for correct alpha-blending. Enabling z-sorting for a system will have performance implications with sorting performed on the GPU through a sequence of draw calls that iteratively improve the sorting of the view, the additional cost may be severe for larger particle systems.

maxSortSteps (Default 136)

The maximum number of draw calls to make in any frame to sort a particle system. The actual number will be no more than is required to completely sort the system (Of which 136 is the amount needed to completely sort a system with 65536 particles. Aka, the default value for maxSortSteps indicates a complete sort for all values of maxParticles).

trackingEnabled (Default false)

If true, then particles are able to be co-simulated on the CPU when requested. This will enable more complex emitters to function.

Note

No pre-defined emitter requires this.

renderer

Parameters of the ParticleRenderer that will be used for this archetype.

name (Default “default”)

The name of a registered ParticleRenderer.

Other parameters for this object depend on the specific ParticleRenderer in use.

By default, there are 4 registered renderers defined for a manager:

• “default”

  A DefaultParticleRenderer using the alpha blend-mode.

• “alpha”

  Same as “default”.

• “additive”

  A DefaultParticleRenderer using the additive blend-mode.

• “opaque”

  A DefaultParticleRenderer using the opaque blend-mode.

The parameters supported for the archetype by these renderers are listed and described here. You may also find its createUserData function to be useful.

updaters

Parameters of the ParticleUpdater that will be created for this archetype.

name (Default “default”)

The name of a registered ParticleUpdater.

By default, there is a single updater defined for a manager:

• “default”

  A DefaultParticleUpdater.

The parameters supported for the archetype by this updater are listed and described here. You may also find use of its createUserData function to be useful.

synchronizer

Parameters of the ParticleSynchronizer that will be created for each system of this archetype.

name (Default “default”)

The name of a registered ParticleSynchronizer.

By default, there is a single synchronizer defined for a manager.

• “default”

  A DefaultParticleSynchronizer.

The parameters supported for the archetype by this synchronizer are listed and described here.

animationSystem (Default “default”)

The animation system used by particle animations in the archetype.

By default, there is a single animation system compatible with all pre-defined updaters and renderers.

• “default”

  The default animation system, as specified here

packedTexture0..N

These parameters of the archetype can be used to specify that pre-packed textures exist containing all flip-book animations of every particle in the archetype, and that this texture should be used in-place of run-time packed textures generated by the manager.

Indices should match the particle animation system in use, noting that packedTexture0 is permitted to be defined by the name packedTexture instead.

If a packed texture is defined, then particles in the archetype will be permitted to have a corresponding texture-uv0..N field specifying a normalized uv-rectangle of the packed texture to be used in re-mapping particle animation uv-rectangles as described in ParticleBuilder.compiler (uvMap parameter). If this field is not specified then [0, 0, 1, 1] will be implied, indicating the particle animation is already aware of how the textures are packed.

If a packed texture is not specified, then particles in the archetype should themselves specify the textures to be used for that particle that the manager may pack them at run-time.

particles

A dictionary of named particle animations usable by the particle system.

Each field of this object is the name of the particle to be referenced by emitters, and a description of that particle with the following fields:

animation (Default “default”)

The name of a registered particle animation in the manager. The default particle animation is a single frame animation specifying no attribute values (Indicating the system defaults will be filled in). This animation will have a reported life time of 0.

Particle animations are described in ParticleBuilder.compile (particles parameter).

tweaks

A dictionary of tweaks (As described in ParticleBuilder.compile tweaks parameters), to be applied to the animation for this particle.

texture-uv0..N

A normalized uv-rectangle describing the sub-set of the packed texture to which this particles defined animation uv-rectangles should be mapped to as described in ParticleBuilder.compile uvMap parameter.

If using a corresponding packed texture, and this field is omitted, then [0, 0, 1, 1] will be used.

If not using a corresponding packed texture, this field must not be present.

texture0..N

A texture to be used for this individual particle including its entire flip-book animation if applicable.

This field must not be present if using packed textures.

This fields value should be a string specifying the path to the texture used for this particle.

If not using a corresponding packed texture, and this field is omitted, then the TextureManager default texture will be used.

emitters

An array of ParticleEmitters for this particle system archetype.

name (Default “default”)

The name of a registered ParticleEmitter.

By default, there is a single emitter defined for a manager:

• “default”

  A DefaultParticleEmitter.

The parameters supported for the archetype by this emitter are listed and described here.