CParticleEvolver Physics

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

Physics evolver Last update: v1.10.0 - Main page : Particle evolvers Particle evolvers

The physics evolver is the most frequently found evolver in a standard particle evolve state. It is the main dynamics evolver, that will make your particles move with velocity, acceleration, friction, force-fields, velocity fields, and scene interactions (collisions and impulse distribution in your own physical simulation, allowing you to create particles that will actually push your own physics objects around in your scene)

Physics evolver

Physics evolver Node properties

Field name Default value Description
Physics evolver Dynamics
ConstantAcceleration {0,0,0} Constant acceleration to apply to the particles. Usually, this will be gravity.
ConstantVelocityField {0,0,0} Constant velocity field to advect the particles against. Usually, this will be wind. Will be combined with 'VelocityFieldSampler'
Mass 1 INVERSE mass (1.0 / mass) of the particles. Affects drag and force calculations if you supply an external 'Force' particle field. (See 'ForceField' in the 'Field customization' category)
Drag 0 Amount of drag affecting the particles. This will allow the particles to be affected by external winds and turbulent flows. The higher the value, the stronger the drag. 0.0 means no drag.
DragType Linear Type of drag to apply.
  • Linear : default velocity dependent drag. Velocity decreases towards zero (similarly to exponential damping).
  • Aerodynamic : Realistic aerodynamic drag, more costly squared-velocity dependent drag computation (Currently disabled in SDK v1.9.0)
SceneWindInfluence 0 How much the ingame wind affects the particles. See the Wind backdrop Wind backdrop
VelocityFieldSampler <none> Name of the sampler to use as a velocity / wind field. (affects particles based on their 'Drag' and 'Mass'). Will be combined with 'ConstantVelocityField'.

Typically a Turbulence sampler CParticleSamplerProceduralTurbulence

IntegrationStrategy Adaptive Integration strategy to use when evaluating motion equations.
  • Fast : simplest and fastest form. It assumes high constant framerate, and will produce inconsistent particle motion if the framerate is jerky.
  • Stable : evaluates the full analytical motion integrals, and will lead to physically correct results no matter what the simulation steps are. It is also slightly slower than the 'Fast' version.
  • Adaptive : switches between 'Fast' and 'Stable' versions based on the simulation timestep, and the 'IntegrationDtTreshold' value

See #Choosing the integration strategy for more details

IntegrationDtTreshold 0.02 Only used if 'IntegrationStrategy' is set to 'Adaptive'. The integration will switch from 'Fast' to 'Stable' if the simulation timestep becomes greater than 'IntegrationDtTreshold'.
CParticleEvolver Physics.png Collisions
FilterID 0 Custom low-level FilterID that will be passed to the ingame collision callbacks, allowing code to track and filter "Physical layers" of particles
WorldInteractionMode None Type of collision handling performed.
  • None : No collisions with world
  • OneWay : Particles collide with world, world repels particles
  • TwoWay : Particles collide with world, world repels particles, particles apply forces on world.
DieOnContact false If checked, the particle will die as soon as a collision is detected. Active only if WorldInteractionMode is not set to 'None'.
BouncesBeforeDeath 1 Number of bounces before the particle is forced to die. 0 = never dies because of collisions. If death on first contact is needed, activate the 'DieOnContact' property

range : [0, 127]

BounceRestitution 0.5 Determines how much the particle will bounce back. 0 = doesn't bounce, 1 = bounces back with the full pre-impact speed.

range : [0, 1]

ContactFrictionModel Absorbsive v1.9.0 Friction model to apply :
  • Coulomb : traditional, more realistic behaviour, with a separate friction property
  • Absorbsive
ContactFriction 0.7 v1.9.0

0 = no friction, for examples of physically-based friction coefficients, see here: coefficients of friction

Physics evolver Collisions: Events
EventOnCollide "OnCollide" Name of the event to trigger when a collision is detected
EventUsesPostContactVelocity false If active, will forward the post-contact (bounced) velocity to the triggered events
EventTransformsMode ContactSurface Determines the way the triggered event's transforms will be built
  • World : New v1.10.0 transforms will be aligned to the world axes.
  • ContactSurface : transforms will be aligned to the surface normal.
  • PreContactVelocity : transforms will be aligned to the particle's velocity before collision.
  • PostContactVelocity : transforms will be aligned to the particle's velocity after collision.
EventIsSticky false If enabled, the action spawned by the OnCollide event will be parented to the ingame object that was hit
Collisions evolver Collisions: Advanced
BounceOffset 0.002 Offset along the contact normal the particle is displaced by after it has collided. useful to avoid numerical imprecisions with low bounce restitutions, or large bounce counts. Should be kept small
WeightBounceWithNdotV false if activated, bounce restutution will be scaled down when the particle collide at grazing angles with the surface.
MaxIterations 1 v1.9.0 Control the max number of scene raycast iterations the physics evolver will perform when intersecting the scene. 1 gives the best performance.
StopIfFinalIterationHits false v1.9.0 If enabled and the last move iteration collided, will not keep the particle at the last impact location to avoid risking penetrating the scene.

Tells the runtime which kind of collision queries to perform with the world.

  • Raytrace : when moving, the particles will trace a ray in the world along their movement to see if they collide. This assumes the particle is an infinitely small point.
  • SphereSweep : more compute-intensive. When moving, the particles will be treated as a sphere swept into the world, and produce more realistic collisions.
1.0f Factor to apply to the particle sweep radius field, controls how large the particle appears to the collision system.
IgnoreSurfaceProperties false if checked, Particles will ignore surface properties on hit.
RestitutionCombineMode Surface

v1.9.0 Defines how the particle restitution and contact surface restitution are combined.

  • Surface : uses the combine mode of the game engine
  • Average : averages both frictions : (a+b)/2
  • Multiplies : multiplies both frictions together : a*b
  • Min : uses the smallest friction : min(a,b)
  • Max : uses the largest friction : max(a,b)
FrictionCombineMode Surface

v1.9.0 Defines how the particle friction and contact surface friction are combined.

  • Surface : uses the combine mode of the game engine
  • Average : averages both frictions : (a+b)/2
  • Multiplies : multiplies both frictions together : a*b
  • Min : uses the smallest friction : min(a,b)
  • Max : uses the largest friction : max(a,b)
Physics evolver Field customization
PositionField "Position" If this field is declared as a <float3>, it will be used as the particle position
VelocityField "Velocity" If this field is declared as a <float3>, it will be used as the particle velocity
MassField "Mass" If this field is declared as a <float>, it will be scaled by the static 'Mass' field, before being used as the particle INVERSE mass (1.0 / mass)..
AccelField "Accel" If this field is declared as a <float3>, it will be used as an acceleration affecting particles. (in addition to 'ConstantAcceleration' and 'ForceField')
ForceField "Force" If this field is declared as a <float3>, it will be used as a force affecting particles. (in addition to 'ConstantAcceleration' and 'AccelField')
VelocityFieldField "Velocity" If this field is declared as a <float3>, it will be used as the VelocityField (Wind Field) and OVERRIDE VelocityFieldSampler.
BounceRestitutionField "BounceRestitution" If this field is declared as a <float>, it will be scaled by the static 'BounceRestitution' field, before being used as the particle bounce restitution.
ContactFrictionField "Friction" If this field is declared as a <float>, it will be scaled by the static 'ContactFriction' field, before being used as the particle contact/impact friction.
CollisionCountField "CollisionCount" If this field is declared as an <int>, it will be incremented by the evolver each time the particle collides.
"Size" Name of the field the physics evolver should use as the sweep radius of the particles, type = <float>. If empty, uses 'SweepRadiusFactor' as a constant sweep radius
Layout CParticleEvolver Physics.png

Physics evolver Auto-fields

The physics evolver automatically creates, if they don't exist, the following particle fields:

Name Type Footprint TransformMode self access to field
Position float3 16 bytes Transform read/write
Velocity float3 16 bytes Rotate read/write
if 'WorldInteractionMode' != None, the following fields are also added:
PrevPosition float3 16 bytes none read/write
CollisionFlags u8 1 bytes none read/write

Physics evolver Advanced

Choosing the integration strategy

The physics evolver implements two main movement integration computations:

  • Fast : Pretty fast, and uses simplified movement equations to approximate the movement. When the simulation step becomes too large (low FPS, high time factor, excessively high accelerations), You will start seeing glitches. Note that this might occur some times if the framerate of your final games becomes jerky, with occasional spikes at lower framerates, or if there is a framerate stall at the start of a level, or when streaming-in resources, etc...
  • Stable : a bit slower (although not much slower, you will hardly notice a real difference between the two, except perhaps for pretty hardcore effects), however, it evaluates the full motion equations integrals, with friction + acceleration, and therefore produces a rock-solid motion, no matter what the timestep is.

The image below shows four simple fountains:

  • number 1 and 4 have downward gravity and friction
  • number 2 and 3 only have a downward gravity.
  • number 1 and 2 use the 'Stable' integrator.
  • number 3 and 4 use the 'Fast' integrator.

For the sake of the demonstration, the timestep has been exaggerately increased : The framerate was clamped to 15 fps, and the time scale was set to 4x, producing huge simulation steps of 4 * (1/15) = 0.26 seconds per frame. (when usually, the steps are closer to 0.016 seconds per frame)

At normal framerates and time scales, fountains 4 is strictly identical to fountain 1, same goes for fountains 3 and 2.

Physics integration errors

As you can see, the fountains 3 and 4 differ pretty badly from the reference shape of fountains 1 and 2, due only to the approximations of the 'Fast' version.

You can tell the physics evolver which one it should use, using the 'IntegrationStrategy' property.
There is also a third option in addition to 'Fast' and 'Stable', which is the default value when creating a new physics evolver: 'Adaptive'

The 'Adaptive' mode will basically switch between 'Fast' and 'Stable' based on the input timestep. it the timestep becomes larger than the value in the 'IntegrationDtTreshold' property, the evolver will switch to the 'Stable' version. If it gets lower, it will switch back to the 'Fast' version.

The value of 'IntegrationDtTreshold' is basically 1 / framerate.
If you want the 'Stable' version to kick in when your framerate drops below 60 fps, you should set 'IntegrationDtTreshold' to 1/60, so to 0.01666
By default, it is set to 0.02 (which is 50 fps)

Dealing with turbulences at low framerates

Even with the 'Stable' integrator, there can be visual glitches when sampling Turbulence sampler turbulences in the physics evolver.
At high framerates, the particles will precisely follow the turbulent flow. At low framerates, they will appear as drifting away from it, and/or following a coarser version of the flow.

To address that issue, we first have to understand why. Here are a few pictures illustrating what happens at different framerates to a particle advected across a turbulent flow:

turbulence field @ 60 fps 60 fps : particle follows closely the turbulence
turbulence field @ 30 fps 30 fps : particle jumps larger steps and error accumulates
end position diverges a bit.
turbulence field @ 15 fps 15 fps : huge jumps across the turbulence field
unpredictable path, inconsistent with original turbulence.

One solution to that problem is to use the Micro-Updates feature of the Particle evolvers evolve states. They basically allow you to tell the state to subdivite its update step into multiple sub-updates if the framerate gets too low, keeping the sampling errors low.

turbulence field @ 15 fps with micro-updates 15 fps + micro-updates : particle follows closely the turbulence

To customize the Micro-Updates behavior, click on the particle state in the treeview, and tweak the following properties:

  • 'MicroUpdatesMinFPS' : minimum number of updates per second this state should run at.
  • 'MaxMicroUpdatesPerFrame' : maximum number of sub-steps acceptable (to avoid the simulation going down a vicious circles of more updates causing slower framerate causing more updates causing slower framerate, etc...

Particle state : tweaking micro-updates

For more details on tweaking the micro-updates, see the micro-updates section in the evolve state page.