Particle fields

From PopcornFX
Jump to navigation Jump to search
! IMPORTANT ! This is a PopcornFX v1 page. PopcornFX v2 documentation can be found here

Particle fields Last update: v1.10.0 - See also: Node reference | Particle system overview

Particles can have various properties: Position, Velocity, Color, Life-duration, Rotation, Sub-Texture index, etc...
All these properties are called "particle fields".

Particle fields Overview

The particle fields panel shows detailed information about the particle fields, and allows you to add, remove, or modify the particle fields. The more fields a particle has, the more space it will take in memory.

All the particles of the same layer have the same field-set, and each particle has its own version of each field.
For example, in a particle layer that has "Position", "Rotation", and "Color" fields, each particle will have its own "Position", "Rotation" and "Color", but won't have any Velocity or Sub-texture index, or rotation speed.

To access the particle fields panel, unroll the layer you want to see, and select its 'Fields' node.

Particle fields

The fields will appear inside the node properties panel:

Particle fields

1. Total size of a particle, in bytes
2. 'Preset' buttons, click here to quick-add one of the few often-used preset fields
3. New field name box. Enter the name of the custom field you want to add in here.
4. 'Add' button, click here to add the new field
5. Delete field
6. Field type
int : 32-bit integer
int2 : vector of 2 32-bit integers
int3 : vector of 3 32-bit integers
int4 : vector of 4 32-bit integers
float : 32-bit floating point value
float2 : vector of 2 32-bit floating point values
float3 : vector of 3 32-bit floating point values
float4 : vector of 4 32-bit floating point values
u8 : reserved for some evolvers. you shouldn't use this type directly, and the scripts forbid its use.
i8 : reserved for some evolvers. you shouldn't use this type directly, and the scripts forbid its use.
7. Field footprint in bytes
Directly related to the space a particle layer will take in memory. Just multiply this number by the number of particles.
for example, in the screenshot above, we have a footprint of 80 bytes per particle.
Therefore, a particle layer containing 2000 of these particles will consume 80*2000/1024 = 156 Kb of memory.
8. Stream mode
Information only. automatically deduced by the particle system
_ : unused. See unused fields below
c : constant, does not change, neither at spawn or during evolve. This is good for memory, it allows the Fx runtime to make some optimizations.
s : spawn, is variable at spawn, but stays constant through the particle's lifetime
d : dynamic, might be constant at spawn, but is written to by evolvers during the simulation
9. Transform mode

Tells the particle system how it should treat the field regarding the location of the spawner.
TransformNone.png TransformNone : tells the system this stream shouldn't be transformed to worldspace
TransformTranslate.png TransformTranslate : translates the values to worldspace, without rotations
TransformRotate.png TransformRotate : rotates the values to worlspace, without translations. useful for vectors representing a direction (ex: particle velocities/accelerations/lookat/orientation vectors, etc..)
TransformFull.png TransformFull : transforms the values to worldspace (ex: particle positions)
10. Field name
This is the name you need to give to particle nodes, and the name you can use inside the particle scripts (more on that later)
11. Manually created or overridden fields.
12. Auto-fields
These are needed by some nodes in the particle effect, and automatically generated, can be read/written to from scripts.
13. Private fields
These are needed by some internals of the runtime, are automatically generated, and cannot be accessed from scripts.
14. Virtual parent fields section
This is where you specify parent fields for layers that will be spawned by other particles, and where you will need to access parent particle data in the child spawn-script.

Particle fields Adding a new field

To add a new field, Setup the fild as you want by typing its name in the input-box (UI item #3, see previous section), selecting its type, and transform flags, then hit the '+' button (UI item #4)
Alternatively, you can click on one of the two presets buttons (UI item #2), and choose which preset you wish to use. The editor will then auto-fill the field name, type, and transform flags based on this preset. You can then create the field by clicking on the '+' add button.

Particle fields Unused fields

Note that sometimes a field may appear on a red background with a warning sign:

FieldPanel Unused.png

This happens when the field is unused by the effect.
The field is considered unused if:

  • The field is not used internally by the system
  • The field is not read from by any evolvers in any of the states
  • The field is not read from by any renderers
  • The field is not read from by any spawners

Fields used internally by the system are the 'LifeRatio' and 'InvLife' fields.

Particle fields Auto-fields

Fields automatically generated by evolvers, renderers, spawners, or the internal particle system engine, are called auto-fields.

There are two fields always generated by the particle engine:

  • InvLife : The inverse of the total particle life in seconds (1.0 / Life). For example, if the particle has a life of 16 seconds, its InvLife field will be equal to 0.0625
  • LifeRatio : The Age of the particle, as a fraction of its total life. For example, if the particle lives 15 seconds, and has been spawned 6 seconds ago, its life ratio will be equal to 6/15 = 0.4

Most evolvers/Renderers/Spawners will generate auto-fields, like the Position, Size, or Velocity fields.

Some auto-fields won't be accessible within scripts, for safety/encapsulation/abstraction reasons, some others will be hidden through an abstract field that makes it easier to modify the original field. for example, the 'InvLife' field isn't directly accessible in-script. However, there is a virtual 'Life' field, that allows you to read and write the particle's life in seconds. Behind the scenes however, the 'Life' field maps to the inverse of the 'InvLife' field.

So when you write within a script

Life = 5.0;

the particle system converts that to

InvLife = 1.0 / 5.0;

The life is stored as the invLife only for performance reasons. and exposed to the user as the life only for usability reasons.

See the individual node's description in the Particle node reference for detailed information on their auto-fields, if any.

Particle fields Overriding auto-fields

Auto-fields cannot be modified or removed through the Fields panel.

Sometimes, you might want to still change some properties. You still can do it by manually re-adding the field. the new definition overrides the automatic one, and lets you change some parameters. If you delete the overridden field, the default-one reappears.

For example, by default, positions and velocities are auto-fields, and have their transform mode set to 'full' and 'rotate', respectively. This is what works for most particle systems.

However, in some rare occasions, you might want to spawn in worldspace directly, without the particles being transformed by the spawner's local to world matrix. In that case, you need to override these fields and set their transform mode to 'none'. Just type in 'Velocity' or 'Position', as if you were adding a new field, set the type to float3, transform mode to none, and click the add button:

FieldPanel OverridingAutoFields.png

Note that in most cases, you shouldn't change the field type of overridden auto-fields.

Particle fields Virtual parent-fields