CActionFactoryParticleSpawnerBase

From PopcornFX
Jump to: navigation, search

CActionFactoryParticleSpawnerBase.med.png Last update: v1.11.3 - Main page : Particle layers Particle layers


A particle spawner allows you to add particles in the simulation. They are seen as particle layers in the editor treeview, and contain the whole definition of a particle layer.

See any basic Particle tutorials for more details on how to use this node.


CActionFactoryParticleSpawnerBase.med.png Node properties

Field name Default value Description
CActionFactoryParticleSpawnerBase.png Action
Delay 0 Delay in seconds before emission start.
RandomDelay 0 in the [0,1] range. Random coefficient to apply to the delay.

The final delay is computed as: Delay * (1 + rand(-1,1) * RandomDelay)
Basically, when 'RandomDelay' is 0.0, the real delay will be equal to 'Delay'.
When 'RandomDelay' is 1.0, the real delay will take a random value between '0' and 'Delay * 2'
When 'RandomDelay' is 0.5, the real delay will take a random value between 'Delay * 0.5' and 'Delay * 1.5'. etc...

Weight 1.0 When the layer is inside a folder that has a child evaluation mode set to 'random', tells the spawn probability of that layer. Higher values compared to other childs will mean that layer will have more chance to be spawned
CActionFactoryParticleSpawnerBase.png General
Infinite false If checked, the spawner will spawn forever, until it is explicitely stopped from game code, or the whole level is shutdown
DurationInSeconds 0 Emission duration in seconds. (Does not include the 'Delay' property).

If the duration is 2 seconds and the delay is 1 second, the spawner will start spawning at time t=1 and stop spawning at t=3.
A value of 0 will spawn all the particles in one frame.

DurationRelativeRandomDeviation 0 in the [0,1] range. Random coefficient to apply to the duration.

RealDuration =
DurationInSeconds * (1 + rand(-1,1) * DurationRelativeRandomDeviation)

SpawnCountMode ParticlesPerSecond Determines how the 'SpawnCount' property should be interpreted
  • ParticlesPerSecond
  • TotalParticleCount
SpawnCount 1 Spawn count. See 'SpawnCountMode' for how it should be interpreted.
  • Regular spawners : particles per second, or total particle count, based on 'SpawnCountMode'
  • Instant spawners : total particle count (Duration = 0 sec).
  • Infinite spawners : particles per second.
SpawnCountRelativeRandomDeviation 0 in the [0,1] range. Random coefficient to apply to the delay.

RealCount =
SpawnCount * (1 + rand(-1,1) * SpawnCountRelativeRandomDeviation)

FirstSpawnDelay 0 Time offset in the [0,1] range that controls when the child particles are spawned. A value of 0 will make the spawner spawn a child particle right when emission starts. A value of 1 will offset it forward in time to the next child spawn.
ContinuousSpawner true

enables sub-frame continuous spawns: Takes into account the fx instance movement in the world to create continuous streams of particles, and avoid discrete "bags" of particles being spawned each frame.

InheritInitialVelocity 0 Coefficient in the [0,1] range that controls how much of the parent's velocity will be inherited by the particles spawned by this spawner.

If the parent is the effect instance, it uses the instance's velocity.
If the parent is a particle, it uses the particle's velocity.

  • 0.0 : does not take parent velocity into account
  • 1.0 : parent velocity is fully added to the spawn velocity of each particle
EnableSpawnerIDs false Reserved for internal use, might be subject to change. do not use directly.
EnableParentIDs false Reserved for internal use, might be subject to change. do not use directly.
UseSimulationCache false If enabled, allows you to pickup a simulation file cache (.pksc). Enabling this options stops taking in account flux functions and base spawn count/rate entirely as it becomes driven by the simulation cache.

See the simulation cache tutorial for more detail.

EnableDeterminism false If checked, will make the layer deterministic, it will produce the exact same simulation results each time it is run.

Requires a special build of the editor and of the ingame SDK

PrefferedSimLocation Auto v1.9.0 Hints the runtime as to where it should try running the simulation for this layer
  • Auto: will automatically choose what it thinks is best on the current platform.
  • CPU: will force the sim to run on the CPU.
  • GPU: will try, if possible, to run the sim on the GPU.
PrefferedStorageSize Auto v1.9.0 Hints the runtime as to how large the storage for this layer will need to be ingame.

It has to take into account the number of simultaneous ingame instances of the effect
So a layer with few particles but many ingame instances will need a larger storage.
It's usually best to keep this to 'Auto', unless the storage size has been specifically spotted as being a problem.


  • Auto : the runtime will try its best to dynamically scale the storage's particle page size based on the platform and total particle count (will usually be around 512-1024 particles per page, will be able to grow to 2048 for very large particle counts)
  • Tiny : will force particle pages to be tiny (32 particles / page)
  • Small : will force particle pages to be small (128 particles / page)
  • Medium : will force particle pages to be medium (512 particles / page)
  • Large : will force particle pages to be large (1024 particles / page)


Note: you should not rely on the particle pages being exacly the number of particles specified in the above list. These are the current values for CPU storage on v1.10 (GPU storage uses a different heuristic), but they might change in the future. The important thing to consider is that one is "Tiny", and another one is "Large".

PageLocalization Default v1.10.0 Hints the runtime as to how insert particles in pages localized or not.
  • Default: will use the global configuration.
  • ON: will force pages to be localized.
  • OFF: will force pages to not be localized.
CActionFactoryParticleSpawnerBase.png Determinism
DeterminismMode FullyRandom Reserved, might be subject to change. do not use directly. Requires a special build of the editor and of the ingame SDK
InitialSeed 0 Reserved, might be subject to change. do not use directly. Requires a special build of the editor and of the ingame SDK
CActionFactoryParticleSpawnerBase.png FluxFunction
FluxFunction_ComputeIntegrals true If enabled, the spawner will compute the integral of the flux curve between two consecutive frames to have a correct particle flux, even with spiky flux curves.

For more details on what this does, see the side-nodes in the 'FluxFactorExpression' tutorial page.

FluxFunction_EnableTiling true If enabled, will tile the flux curve, based on the value of 'FluxFunctionTiledRelativeDuration'
FluxFunction_DiscreteSpawnKeys false v1.8.0 If enabled, the flux curve's keyframes will be used as discrete instantaneous burst times, their value being a scale applied to the particle rate.
FluxFunctionTiledRelativeDuration 1 Number of times the flux function will repeat itself across the life of the source particles. (you can see this as the "tiling" of the flux function)
FluxFactorExpression <empty> Fetches an attribute and uses it as a flux coefficient.
  • If the attribute is a 'float' or an 'int', just type the name of the attribute.
  • If the attribute is a 'float2', 'float3', or 'float4' (or equivalent int vectors), type the name of the attribute followed by '.x', '.y', '.z', or '.w' depending on the component you want to use as the flux factor
CActionFactoryParticleSpawnerBase.png Bounds Computation
BoundsPositionField Position Particle position (center) field to be used when computing the layer bounds.
BoundsSizeField Size Particle size field to be used when computing the layer bounds.
Layout CActionFactoryParticleSpawnerBase.png



CActionFactoryParticleSpawnerBase.med.png Flux functions

Creating a new flux function

Particle spawners support flux functions. A flux function allows to control the particle emission rate across the spawner's lifetime.
To create a new flux function, right-click on the evolver, and select 'New Flux Function'


Layout CActionFactoryParticleSpawnerBase Flux0.png



A "Flux Function" entry will be added in the treeview:

Layout CActionFactoryParticleSpawnerBase Flux1.png



When selecting the Flux Function node, you can change the curve to control the particle flux:

Layout CParticleEvolver Spawner Flux Curve0.png Layout CParticleEvolver Spawner Flux Viewport0.png
Default flux function. Constant flux = 1.0


Layout CParticleEvolver Spawner Flux Curve1.png Layout CParticleEvolver Spawner Flux Viewport1.png
Simple flux function. Starts with a low flux, ends with a high flux. Particles start wide apart and end close together


Layout CParticleEvolver Spawner Flux Curve2.png Layout CParticleEvolver Spawner Flux Viewport2.png
Complex flux function. Drops to zero at multiple places.


Tiling the flux function

Considering the following flux function: (high peak at the center that will produce a very high particle count)

Viewport Spawner VariationFlux2.png


Here we have an Fx with 8 layers that spawn a stream of particles using that flux function.
Each layer has a different 'SpawnCountRelativeRandomDeviation' that varies from 0.0 for the top layer to 1.0 for the bottom layer, producing increasingly chaotic streams.
The particles spawn at the left hand-side, move from left to right, and die on the right hand-side.
They are colored based on the spawner life ratio. When the spawner starts (life-ratio = 0), they are colored red. When it stops (life-ratio = 1.0), they are colored yellow.


It is easy to see the flux function pattern in the particle streams:

Viewport Spawner VariationFlux0.png


Here is the effect of changing the 'FluxFunctionTiledRelativeDuration' property from 1.0 to 4.0. The flux function will tile 4 times across the spawner's life:

Viewport Spawner VariationFlux1.png


NOTE : when using an infinite spawner, the 'FluxFunctionTiledRelativeDuration' will be the duration in seconds of the flux function.
For example, if an infinite spawner has its 'FluxFunctionTiledRelativeDuration' set to 3.5, the flux function will take 3.5 seconds to do a full loop, and start again.


Layer scripts

v1.8.0

Layer scripts allow you to control various properties of the layer _before_ it starts emitting particles each frame.
You can find the full layer-script reference on the scripting reference page


These are the values you can access. The ones tagged as 'RW' or 'W' mean you can write to them. the ones tagged as 'R' are read-only:

Layer spawn-scripts not yet available. In 1.8 you can only use layer evolve scripts.

Spawn Evolve type description
  R float Age

Time in seconds the spawner has been spawning particles (at the beginning of the frame)

RW R float Life

Duration of the spawner, in seconds

  R float LifeRatio

Life-ratio of the spawner, in the [0, 1] range (at the beginning of the frame)

  R float EmittedCount

Number of particles already emitted by the spawner (at the beginning of the frame)

  R float LiveCount

v1.9.0 Estimated number of particles emitted by the spawner that are still alive (at the beginning of the frame)

  RW float Flux

Base value each frame is 1.0, you can write to this to weight the spawn rate by a custom value. Setting it to 2.0 will make the spawner emit twice as many particles as its base value.

  R float SpawnRate

number of particles emitted per spawn metric (per second, per world unit, or per custom metric, depending on the spawner's settings)

  R float SpawnCount

total number of particles the spawner will emit (if available, otherwise zero)

RW R float BaseSpawnRate

number of particles emitted per spawn metric, before being weighted by any spawn flux

RW R float BaseSpawnCount

total number of particles the spawner will emit (if available, otherwise zero), before being weighted by any spawn flux

RW R float FirstSpawnDelay

returns the value of the 'FirstSpawnDelay' property in the parent particle spawner action layer.

R R float3 Position

Position of the layer at the end of the current frame.

R R float3 PrevPosition

Position of the layer at the beginning of the current frame.

R R float3 Orientation

Orientation of the layer at the end of the current frame. (represented as euler angles in radians)

R R float3 PrevOrientation

Orientation of the layer at the beginning of the current frame. (represented as euler angles in radians)

R R float3 Velocity

v1.9.0 Velocity of the layer at the end of the current frame. (units per second)

R R float3 PrevVelocity

v1.9.0 Velocity of the layer at the beginning of the current frame. (units per second)

RW RW float3 PositionOffset

Position offset of the layer at the end of the current frame. Defaults to zero

RW RW float3 PrevPositionOffset

Position offset of the layer at the beginning of the current frame. Defaults to zero

RW RW float3 OrientationOffset

Orientation offset of the layer at the end of the current frame. Defaults to zero. (represented as euler angles in radians)

RW RW float3 PrevOrientationOffset

Orientation offset of the layer at the beginning of the current frame. Defaults to zero. (represented as euler angles in radians)


In addition to all the above, you can also access the common properties available inside each script: Scripting_reference#Common_to_particle_and_layer_scripts


Example of a layer script:

function void Run()
{
    Flux = remap(sin(scene.Time), -1, 1, 0.1, 2);
}

This will map the emission rate (flux) to a sinewave based on the elapsed time.


CActionFactoryParticleSpawnerBase.med.png Simulation caches

Experimental support for simulation caches has been added in v1.11.0. This feature allows:

  • Particle layers to have their emission driven by the simulation cache
  • Point attributes to be converted as particle fields
  • Adding realtime behavior to the offline simulation

Import

Our goal is to support any simulation software capable of exporting frames containing points and their attributes.

Supported softwares to this date (v1.11.3) are:

How it works

The .pksc file contains all the offline simulation frames, each one contains points and their attributes (Position, Life, ..). All points will represent a particle, and all point attribute will be converted to a particle field.

Spawn

Once this feature enabled, the particle spawner will stops taking in account the base spawn rate and flux informations as the simulation cache becomes the particle emission source. Modifying the layer's Flux in a LayerScript will not affect the spawn rate either.

ActionFactoryParticleSpawnerBase SimCache.jpg

Particles will be emitted smoothly even if the source frame rate is low by interpolating to match the game's framerate.

Particle's Life shouldn't be assigned in the Spawner Script to something else than Life = infinity; as their lifetime will be handled internally based off the sim cache. However, this means that LifeRatio will be invalid as for every infinite particles, and LifeRatio based evolvers won't work and cannot be used (ie. Field evolvers). An option to enable this is exporting a life attribute and assign Life = life; but this will increase the simulation cache size.

Note that simulation cache fields are not initialzied in the Spawner Script.

Evolve

A hidden simulation cache evolver will read the simulation cache and assign each field to the source point attribute value.

Interpolation can be activated on a per field basis as long as an ID attribute was exported in the simulation. The ID attribute is used internally to keep track of particles. Except from the ID field, all simulation cache fields can be interpolated.

The P (vector) point attribute is automatically mapped to Position and is mandatory.

As of v1.11.3, points inside a simulation cannot be removed (ie. die), unless all points from the sim die at once:

  • Invalid: Frame 10 has 100 points, frame 11 has 99 points
  • Invalid: Frame 10 has 100 points, frame 11 has 100 points but x particles died, and x particles spawned between those two frames (depending on the offline simulation software, IDs might be the same for the newly spawned particles)
  • Valid: Frame 10 has 100 points, frame 11 has 100 points
  • Valid: Frame 10 has 100 points, frame 11 has 0 points

Rendering

Nothing changes regarding rendering, like all particles, you can apply any renderer you want to simulation cache particles (Billboard, Ribbon, ..).