.. index:: single: ParticleArchetype .. highlight:: javascript .. _particlearchetype: ============================ The ParticleArchetype Object ============================ **Added SDK 0.28.0** The `ParticleArchetype` is used to fully describe a particle system for use with the :ref:`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 :ref:`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 :ref:`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 :ref:`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 :ref:`ParticleRenderer ` that will be used for this archetype. ``name`` (Default `"default"`) The name of a registered :ref:`ParticleRenderer `. Other parameters for this object depend on the specific :ref:`ParticleRenderer ` in use. By default, there are 4 registered renderers defined for a manager: * `"default"` A :ref:`DefaultParticleRenderer ` using the `alpha` blend-mode. * `"alpha"` Same as `"default"`. * `"additive"` A :ref:`DefaultParticleRenderer ` using the `additive` blend-mode. * `"opaque"` A :ref:`DefaultParticleRenderer ` using the `opaque` blend-mode. The parameters supported for the archetype by these renderers are listed and described :ref:`here `. You may also find its `createUserData` function to be useful. ``updaters`` Parameters of the :ref:`ParticleUpdater ` that will be created for this archetype. ``name`` (Default `"default"`) The name of a registered :ref:`ParticleUpdater `. By default, there is a single updater defined for a manager: * `"default"` A :ref:`DefaultParticleUpdater `. The parameters supported for the archetype by this updater are listed and described :ref:`here `. You may also find use of its `createUserData` function to be useful. ``synchronizer`` Parameters of the :ref:`ParticleSynchronizer ` that will be created for each system of this archetype. ``name`` (Default `"default"`) The name of a registered :ref:`ParticleSynchronizer `. By default, there is a single synchronizer defined for a manager. * `"default"` A :ref:`DefaultParticleSynchronizer `. The parameters supported for the archetype by this synchronizer are listed and described :ref:`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 :ref:`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 :ref:`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 :ref:`ParticleBuilder.compile ` (`particles` parameter). ``tweaks`` A dictionary of tweaks (As described in :ref:`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 :ref:`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 :ref:`TextureManager ` default texture will be used. ``emitters`` An array of :ref:`ParticleEmitters ` for this particle system archetype. ``name`` (Default `"default"`) The name of a registered :ref:`ParticleEmitter `. By default, there is a single emitter defined for a manager: * `"default"` A :ref:`DefaultParticleEmitter `. The parameters supported for the archetype by this emitter are listed and described :ref:`here `.