Overview

This page describes the CryENGINE particle features and authoring environment.

Terminology

Particle Effect Usage

Emitters can be created in-game in 2 basic ways:

1. Saved emitters are placed in a level by creating a ParticleEffect entity. At runtime, they are loaded by the entity automatically.
2. Spawned emitters are created dynamically at runtime, in a variety of ways. They can be spawned and attached to an entity (script function LoadParticleEffect), or spawned independently of an entity (script function SpawnEffect).

ParticleEffect Entities

Creation

There are a couple ways to create a ParticleEffect entity:

The easiest is to open a Particles library from the Database window, select an effect, and drag it into the world.

• If the effect is dragged onto terrain or a brush, a new ParticleEffect entity is created, using the chosen effect.
• If the effect is dragged onto an existing ParticleEffect entity, that effect is assigned to the entity, replacing any previous one.
• If the effect is dragged onto any other type of entity, a new ParticleEffect entity is created, and attached to the selected entity. The ParticleEffect entity will move with the parent entity. You can also set the ParticleEffect entity's properties to cause the effect to emit from the parent entity's geometry, rather than the effect point.
• You can also create a blank ParticleEffect entity by selecting Particle/ParticleEffect from the Entity tree in the Objects roll-up bar, and dragging it into the world. You will then have to assign an effect to it.

Properties and Events

The ParticleEffect entity has the following properties:

• ParticleEffect: Name of the effect to spawn.
• Active: (flag) Sets the initially active or inactive. Can be toggled in the editor for testing.
• Prime: (flag) If true, and the assigned ParticleEffect is immortal, causes the emitter to start "primed" to its equilibrium state, rather than starting up from scratch. Very useful for placed effects such as fires or waterfalls, which are supposed to be already running when the level starts. Applies only to immortal, not mortal effects. Defaults to true.
• PulsePeriod: If not 0, restarts the emitter repeatedly at this time interval. Important: This property should be used to create emitters that pulse on and off at somewhat large intervals, a second or so. Do not set a low value such as 0.1 to try to make an instant effect into a continuous one. That method is inefficient, framerate-dependent, and won't look as good as it should. Instead, make sure the actual library effect is set Continuous and has an appropriate Count.
• Strength: A value that can be used by effect params to modify their value. If a param has an Emitter Strength curve, and the emitter entity's Strength property is not negative, then Strength will be used as input to this curve.
• Scale: Multiplies the overall size and velocity of the entire emitter.
• CountScale: Multiples the particle counts of the entire emitter.
• SpeedScale: Multiples the particle emission speed of the entire emitter.
• TimeScale: Multiples the elapsed time used to simulate the emitter. Less than 1 achieves a show-motion effect.
• RegisterByBBox: Uses the emitter's (automatically computed) bounding box to determine which VisAreas it is visible in. If this is unset (the default), the emitter's origin alone determines VisArea membership, as the bounding box is hard to exactly control by the designer.
• AttachType: If this entity is attached to a parent entity, as described above, this field can be used to cause particles to emit from the entity's geometry. Set it to one of these string values (heeding case):
  • blank: Emit from the effect origin, as normal.
  • BoundingBox: Emit from the parent effect's bounding box.
  • Physics: Emit from the parent effect's physics geometry.
  • Render: Emit from the parent effect's render geometry.
• AttachForm: If AttachType is non-blank, this property determines where particles emit from the attached geometry. Set it to Vertices , Edges , Surface , or Volume .
• CountPerUnit: (flag) If AttachType is non-blank, this multiples the particle count by the "extent" of the attached geometry. Depending on AttachForm , the extent is either total vertex count, edge length, surface area, or volume.
• EnableSound: Toggles sound emission on any sub-effects with a Sound parameter set.

The ParticleEffect entity has the following events. You can Send them in the editor to test the effect, or send them from script.

• Enable: Creates and starts the entity's attached emitter.
• Disable: Stops and deletes the entity's emitter. Mortal effects stop automatically, immortal effects keep running until Disabled.
• Kill: Removes the entity's emitter and all particles immediately.
• Restart: Performs a Disable, then Enable.
• Spawn: Creates a new emitter that is not attached to the entity. Every Spawn event will create a new emitter. These emitters cannot be subsequently stopped in script, so Spawn should only be used for finite emitters.

Particle Library Features

In the Particle library editor are various tools for creating, deleting, and editing effects and libraries. There are a couple of handy buttons as well:

• Assign Material to Selection: Assigns or attaches the effect to the chosen entity, as if you had dragged the effect onto it.
• Get Material from Selection: If a ParticleEffect entity is selected, loads and selects its effect in the library tool.

Particle Effect Parameters

Following is the list of parameters, grouped as they are in the Library editing pane.

Emitter

• Enabled: (flag) Effect is active.
• Continuous: (flag) If false, all Count particles are emitted at once, and the emitter then dies. If true, particles are emitted gradually; once Count particles have been emitted, particles continue to emit, maintaining Count at all times.
• Count: The total number of particles in the system, at one time. Applies to both Continuous and non-Continuous effects.
• Second Generation: (flag) For child effects, causes this emitter to be duplicated and attached to each particle of the parent emitter. See Child Effects below.
• Spawn on Parent Collision: (flag) For Second Generation effects, spawns only when the parent particle collides.
• Spawn Delay: Time after emitter spawns before particle emission starts. Useful for child effects.
• Emitter Life Time: For Continuous effects, specifies a time limit on emitter life if >0, or infinite lifetime if 0. Does not apply to non-Continuous effects, which are always destroyed as soon as they emit their particles.
• Pulse Period: If >0, emitter will restart continually at this interval.
• Particle Life Time: Lifetime of individual particles.
• Remain While Visible: Particles in the effect will not disappear until the emitter is out of view.

Location

By default, particles emit from the emitter center in all directions equally. The following parameters change this behavior.

• Attach Type (choice): Specifies the type of geometry particles emit from.
  • None: Particles ignore geometry and emit from emitter center as normal.
  • BoundingBox: Particles emit from the render bounding box of the object.
  • Render: (expensive) Particles emit from the geometry of the render object (usually static or animated mesh).
  • Physics: (expensive) Particles emit from the geometry of the attached physics object (can be a mesh or simple primitive).
• Attach Form (choice): Specifies the elements of the shape (box or mesh) that particles will emit from.
  • Vertices: Emit randomly from the vertices of the shape. Most efficient form of Mesh emission.
  • Edges: Emit randomly from the edges. Useful for effects on breaking element pieces.
  • Surface: Emit randomly from the surface (faces) of the shape.
  • Volume: Emit randomly inside the shape.
• Position Offset (vector): Emission center position, in local emitter space.
• Random Offset (vector): Extent of random emission location box, in local emitter space.
• Pos Random Offset: Additional radius to add to random emission location.

Angles

• Focus Angle , Focus Azimuth: Controls deviation from the focus direction of the emitter, which is by default the emitter's Y axis. Focus Angle is the amount to rotate, in degrees, from this axis, Focus Azimuth is the amount to rotate the new axis about the Y axis.
• Focus Gravity Dir: (flag) Forces focus direction to world negative gravity direction (usually world Z).
• Emit Angle: Maximum angle of particle emission away from focus axis (emitter local Y). Random Var sub-parameter determines minimum angle. Particles are emitted at random angles around this axis.
  • To emit in a single direction, set to 0.
  • To emit in a plane around the focus axis, set to 90, Random Var = 0%.
  • To emit equally in all directions, set to 180, Random Var = 100%.

Appearance

Particles can be either 2D (texture-based sprites) or 3D (geometry).

• Facing: (choice) Applies only to 2D particles, and determines how the sprite is oriented in space. Texture orientation is further modified by rotation parameters.
  • Camera: Sprite faces viewer, texture X&Y aligned with screen X&Y.
  • Free: Sprite rotates freely in 3D.
  • Velocity: Sprite faces direction of movement, texture X&Y aligned with screen X&Y.
  • Horizonal: Sprite faces upward, texture X&Y aligned with world X&Y.
  • Water: Sprite moved and aligned to nearest water plane.
  • Terrain: Sprite moved and aligned to terrain below position.
  • Decal: A decal is created on the nearest surface, instead of a particle. The decal has the texture, initial size, and lifetime of the particle. But not all particle features are currently implemented for decals, including movement, dynamic sizing, and dynamic color and alpha.
    Hint: A good way to use Decal particles: Create a parent effect for travelling particles, and enable collision on them. Create a child 2nd-generation effect, spawned on parent collision, and set the child effect Facing = Decal.
• Orient to Velocity: (flag) Texture X axis aligned to direction of movement (rotation parameters can rotate it further).
• Blend Type (choice): Applies only to 2D particles.
  • Alpha Based: Final Color = Particle Color * Particle Alpha + Background Color * (1 - Particle Alpha).
  • Additive: Final Color = Particle Color + Background Color
  • None: Final Color = Particle Color
• Texture, Material, Geometry (asset): You should only set one of these parameters, to the appropriate asset that is to be used for the particle. If Texture or Material is set, the particle is 2D. If Geometry is set, each particle is 3D.
• Texture Tiling: A subcategory controlling multiple usage of multiple images (tiles) per texture, for variation or animation.
  • Tiles X, Tiles Y: How many images the texture is tiled into, in X and Y.
  • First Tile: The first of the range of tiles used by this particle (numbered from 0).
  • Variant Count: How many consecutive tiles in the texture the particle will randomly select from.
  • Anim Frames Count: How many tiles make up an animation sequence. Variant Count and Anim Frames Count can be used together. For example, if Variant Count = 2 and Anim Frames Count = 8, then the particle will randomly choose between using tiles 0 thru 7, or 8 thru 15, as an animated sequence.
  • Anim Framerate: Frames per second for the animation. Special value: if 0, then the animation runs through one sequence in the particle lifetime.
  • Anim Cycle: (choice)
    • Once: Anim plays once, and holds on the last frame.
    • Loop: Anim loops continuously.
    • Mirror: Anim runs from start to end, then in reverse to start, and repeats.
  • Anim Blend: (flag) (Slightly expensive) Blends gradually between frames, drawing 2 textures.
• Octagonal Shape: (flag) Render sprite as an octagon rather than a quad, reducing pixel costs. Use only for textures whose non-transparent content fits within the octagon.
• Geometry in Pieces: (flag) If true, and the Geometry asset contains multiple sub-objects, then the geometry will be emitted in split-up pieces, one set per particle Count, originating at each piece's location in the asset. If false, each particle will use the entire geometry (all sub-objects together).
• Alpha , Color: Standard rendering values.
• Alpha Test Sets the lower alpha threshold for rendering. Pixels below this value will not be rendered.
• Soft Particle: (flag) (Expensive) Uses a rendering technique that softens the intersection between sprites and nearby objects, to prevent unnatural seams.

Lighting

• Diffuse Lighting: Multiplier to particle color for dynamic (diffuse) lighting.
• Diffuse Backlighting: Fraction of diffuse lighting that is applied to particle normals in all directions. 0 is standard diffuse lighting, where the normals facing the light are lit the most. 1 is omnidirectional diffuse lighting, where lights affects all normals equally.
• Emissive Lighting: Multiplier to particle color for constant emissive lighting.
• Emissive HDR Dynamic: Power to apply to engine HDR multiplier, for emissive lighting in HDR.
• Receive Shadows: (flag) (Expensive) Shadows will be cast on these particles (only if e_ParticlesShadows > 0).
• Cast Shadows: (flag) (Expensive) Particles will cast shadows.
• Not Affected By Fog: (flag) Particles ignore fog.
• Global Illumination: (flag) Apply engine global illumination to particles (only if cvar e_ParticlesGI > 0).
• Diffuse Cubemap: (flag) Create dynamic environment map to light particles (only if cvar e_ParticlesDiffCM > 0).
• Heat Scale: Enables visibility in thermal vision mode.

A summary of how lighting and blend parameters determine particle color:

• Alpha Based:
  • Particle Color = Texture Color * Color * Particle Light
  • Particle Alpha = Texture Alpha * Alpha
• Non-Alpha Based:
  • Particle Color = Texture Color * Color * Alpha * Particle Light
  • Particle Light = Diffuse Lighting * Dynamic Lighting + Emissive Lighting
  • Dynamic Lighting = Lighting Color * (Lighting Surface Incidence * (1 - Diffuse Backlighting) + Diffuse Backlighting)

Light Source (can be expensive for many particles)

• Radius: Radius of the particle fill light.
• Intensity: Intensity for a dynamic light created at particle position.
• HDR Dynamic: Power to apply to engine HDR multiplier, for particle light source in HDR.

If both Light Source Intensity and Radius are non-zero, then a dynamic light is generated for each particle.

This behavior is also affected by the console variable e_ParticlesLights :

Allows to have light source attached to every particle
0 = Off
1 = Deferred lights

Sound

• Sound: Name of sound event to play when emitter starts.
• Sound FX Param: Modulating value to apply to the sound. Its effect depends on how the individual sound's "particlefx" parameter is defined. Depending on the sound, this value might affect volume, pitch, or other attributes.
• Sound Control Time: Selects the time period which controls the Emitter Strength curve of Sound FX Param.
  • Emitter Life Time: The life of the emitter, controlled by Emitter Life Time param.
  • Emitter Extended Life Time: The life of the emitter's particles, Emitter Life Time + Particle Life Time.
  • Pulse Period: The period between emissions, controlled by Pulse Period.

Size

• Size: For 2D particles, the world sprite radius. For 3D particles, the scale applied to the geometry.
• Stretch: Amount to stretch particle in direction of travel in seconds (based on current velocity). Stretches in both directions.
  • Offset Ratio: Relative amount to move particle in direction of stretch. To reposition the particle to the front end of its stretch, set to 1. To reposition it to the back end, set to -1.
• Tail Length: Length of particle's tail in seconds. Particle texture will be stretched out through tail.
  • Tail Steps: Number of segments for tail. A higher number will produce smoother tail curves for non-linear-moving particles.
• Min Pixels: Add this many pixels to particles true size when rendering. Useful for important fx that should always be visible even at distance.

• Connection: (flag) Render all particles in emitter as a single polygon, connected in emission order. Emission sequences separated by a Pulse Period produce separate polygons. And for 2nd-generation particles, each child emitter produces a separate polygon.
  • Connect To Origin: (flag) Additionally connect the newest particle to the emitter origin, as if it had a permanent virtual particle of age 0.
  • Fluid Texture: (flag) Controls how texture coords are assigned to the connected particles. If false, textures are repeated once per particle, alternating direction. and move with the particles. If true, the texture spans the entire connected sequence, and is constant with particle age.
  • Texture Frequency: (default = 1) Multiplies the rate at which texture coords change per particle, determined by the flag above.

Movement

• Speed: Initial emission speed of particles.
• Inherit Velocity: Fraction of parent object's velocity imparted to particles on emission. The parent object is either a parent particle (if Second Generation), or the entity the emitter is attached to.
• Air Resistance: If non zero, particles are slowed down by air, and move toward wind speed. Units
  are 1/seconds. The higher the number, the faster particles will reach wind speed (or rest if no wind).
• Rotational Drag Scale: Fraction of Air Resistance applied to particle rotation.
• Gravity Scale: Multiple of world gravity to apply to particles. Most physical particles should set this to 1 (use Air Resistance to provide drag). Set to a negative value for buoyant particles such as smoke.
• Acceleration (vector): Constant acceleration applied to particles, in world space.
• Turbulence 3D Speed: Average speed of 3D random turbulent movement.
• Turbulence Size: Radius of horizontal spiral motion.
• Turbulence Speed: Angular speed, in degrees/second, of horizontal spiral motion.
• Move Rel Emitter: (flag) Particle motion is in emitter space; particles will move with emitter.
• Bind Emitter To Camera: (flag) Emitter attached to camera.
• Space Loop: (flag) Particles loop within a region around the camera, defined by Camera Min/Max Distance .

Target Attraction

Specifies how particles behave if the Emitter is attached externally to a #Target. By default, all particles are attracted to any target the emitter is linked to. These parameters customize that behavior.

• Ignore: Particles ignore target attraction completely.
• Extend Speed: Particles speed up to reach the target in their lifetime. Otherwise, they move at natural speed toward the target, and may not reach it.
• Orbit: Particles orbit around target when reached. Otherwise, they disappear into the target.
• Orbit Distance: The orbit radius is equal to the target's physical radius, plus this Orbit Distance amount.

Rotation

• Init Angles (vector): Initial rotation applied to particles, as rotations about each axis, in degrees. For sprite particles, only the Z axis is used, and it refers to rotation in screen space. For 3D particles, all 3 axes are used, and refer to emitter local space.
• Random Angles: (vector) Random variation (bidirectional) to Init Angles , in degrees.
• Rotation Rate (vector): Constant particle rotation, in degrees/second. The axes are the same as for Init Angles .
• Random Rotation Rate (vector): Random variation (bidirectional) to Rotation Rate , in degrees/second.

Collision

• Physics Type (choice): How the particle interacts physically.
  • None: No collisions or other physics.
  • Simple Collision: Particle collides with selected environment using simple physics simulation.
  • Simple Physics: Particle created as physical entity in the physics system, and collides using a spherical particle model.
  • Rigid Body: Particle created as physical entity in the physics system, and collides using full geometry. A Geometry asset must be set for this particle.
• Collide Terrain: (flag) Includes terrain in particle collisions.
• Collide Static Objects: (flag) (expensive) Includes non-movable objects in particle collisions.
• Collide Dynamic Objects: (flag) (very expensive) Includes dynamic, animating, and living objects in particle collisions.
• Surface Type (choice): Surface material type for collision behavior. If set, overrides Bounciness and Dynamic Friction below.
• Bounciness: ( Simple Collision only): Elasticity for collision response. Overridden by Surface Type if set. Special value: if -1, particle dies on first collision.
• Dynamic Friction: ( Simple Collision only): Drag value when sliding, in units of 1/seconds. Overridden by Surface Type if set.
• Thickness: ( Simple Physics only) The fraction of the particle's visible radius to use for the physical radius.
• Density: ( Simple Physics or Rigid Body only) Density of particle, in kg/m^3. Water = 1000.
• Max Collision Events: Limits the number of collisions the particle can have in its lifetime. After the limit is reached, the particle ignores all objects.

Visibility

• Camera Min/Max Distance: Sets the camera range that particles render in. Defaults are 0, specifying unlimited range.
• View Distance Adjust: Multiplier to distance of automatic fade-out.
• Draw Last: Modifies draw order of sub-effects. Sub-effects are rendered by lowest Draw Last value first, or in list order if equal.
• Draw Near: (flag) Particles rendered in the special "Near" rendering pass (usually for 1st-person weapons).
• Visible Indoors: Trinary value: If False hides particles when indoors, If True hides particles when outdoors, Both
• Visible Underwater: Trinary value: If False hides particles when under water, If True hides particles when above water.

Advanced

• Force Generation: (choice) Additional force generated by the emitter.
  • None: Nothing.
  • Wind: Creates a physical wind force, approximately having the velocity, direction, volume, and timing of the emitter's particles. (But the particle Count does not effect the wind, and can even be 0.) This wind force affects all particles and objects in its region, except particles in the emitter group. The following parameters affect the wind:
    • Timing: Continuous, SpawnDelay, Emitter Lifetime, Pulse Period, Particle Lifetime.
    • Direction: Focus Gravity Dir, Focus Angle, Focus Azimuth control the main focus direction of the wind. Emit Angle controls the angle: if near 0, it creates a linear wind; if > 45 degrees, a more radial wind; if 180 degrees, a perfectly spherical wind.
    • Strength: {{Speed }}directly controls the speed of the wind. It can be < 0, which creates a vacuum if used with radial winds.
    • Volume: Position Offset, Random Offset, Pos Random Offest control the volume of maximum strength. Size controls the falloff area. In addition, Speed, Particle Lifetime, Air Resistance, etc extend the volume of the effect, because they extend the distance virtual particles would travel.
  • Gravity: Creates a physical gravity force, similar to Wind , but creating a gravitational acceleration instead of a wind velocity.

• • Target: Sets the sub-emitter as an target, which attracts all particles from child sub-emitters of this sub-emitter.
• Fill Rate Cost: Multiplier to particle size which determines max screen fill allowed per emitter.
• No Offset: (flag) (physicalised geometry only) Use geometry's origin as particle position. Default is to use geometry bounding box's center.
• Allow Merging: (flag) The Renderer can merge multiple containers into one draw call, potentially yielding performance gains. However, it can also sometimes create inconsistent sorting. (Config var _r_UseParticlesMerging_ must also be true.)
• Streamable: (flag) The texture or geometry asset can be loaded dynamically, rather than at startup.

Configuration

These settings limit an effect to only be enabled on certain platform configurations. This allows you to create variant effects for different configurations.

• Config Min: The minimum system configuration an effect is enabled for (Low, Medium, High, VeryHigh).
• Config Max: The maximum system configuration an effect is enabled for.
• DX11: A trinary value. If True enables the effect only on DX10, If False enables it only on pre-DX10.

Parameter Variation Editing

Most numeric parameters have variation sub-fields, that allow for random variation, and evolution over particle and/or emitter lifetime. A variable parameter can have the following components:

• Base value: This is also the maximum value the parameter can be (any variations only reduce this value).
• Random Var: This is the proportional range of randomly subtracted values from the Base, applied at particle (or emitter) creation time. So the range of random values is from Base * (1 - Random Var) to Base. For positive-valued parameters, {{Random Var }}can range from 0 to 1. For bidirectional parameters, it can range from 0 to 2, allowing values in both positive and negative directions.
  • Examples:
    • {{Random Var = 0: }}No variation, value always = Base value.
    • {{Random Var = 0.2: }}Vary between 0.8 * Base and Base.
    • {{Random Var = 1: }}Vary between 0 and Base.
    • {{Random Var = 1.3: }}Vary between -0.3 * Base and +Base. Can be used for both positive and negative Base values.
    • {{Random Var = 2: }}Vary between -Base and +Base.
• Var Emitter Life: A spline curve that modifies the Base value of a particle or emitter param over the Emitter's life time. (This only works for emitter's with finite (non-zero) lifetime.)
• Var Particle Life: A spline curve that modifies the Base value of a particle param over the Particle's life time.

In the Particles editor, variation params are initially unexpanded, and show just the base value. Click on the expand (+) widget next to the value to open up the variation params. When closed, this widget is colored if any variation values are non-default.

Spline curves default to unity, with 2 endpoints both set to 1.

To edit a spline curve:

• Adding a point: Double-click anywhere in the graph, off of the spline.
• Moving a point: Left-click on a point and drag it around.
• Changing a point's tangents: Single-click on the spline near the point. This toggles the tangent on that side of the point between continuous (smooth) and non-continuous (linear). You should try it out to see exactly what that looks like.
• Deleting a point: Double-click an existing point, or select it and press Delete.

The Color parameter works a little differently.

• Random Var is a percentage value that varies the base color from Base*(1-Random Var) to Base, separately in each component.
• The Life curves are color curves that multiply the base color. Thus, they don't show the resultant color directly (unless the base color is white). They are edited with a color gradient control.
• Adding a point: Double-click in bottom of the control.
• Editing a point's color: Double-click the existing point.
• Moving a point in time: Left-click and drag the point.
• Changing a point's tangents: Right-click on the point to toggle the tangents between continuous and non-continuous.
• Deleting a point: Select the point and press Delete.

Child Effects

An effect can have any number of child effects, created and shown in the Sandbox as nested sub-effects. They can be nested to any level. There are 2 kinds of child effects:

• Regular child effects behave just like separate effects, except they are spawned with and attached to their parent effect. Each child effect has its own independent lifetime etc. This allows you to create an overall effect that consists of several parts.
• Second-Generation child effects are effects that are attached to the individual particles of the parent effect. That is, a separate emitter is spawned for each particle of the parent effect, and those emitters move with their parent particles. This allows you to create much more complex effects. You can nest second-generation effects multiple times, creating 3rd-or-more generation effects. Be careful, however, since the number of particles created is equal to the product of the child effect Count and the parent effect Count.

The type of child effect is determined by the Second Generation flag in the child effect parameters.

Advanced Topics

Attaching Particles to Geometry

Here is a description of the various ways you can attach particle emitters to other geometry, with particular emphasis on breakable geometry.

Basic Attachment

• Second Generation Effects: As described above, these allow you to attach emitters to parent particles, as part of the parent particle effect. If the parent effect has Geometry, then the Second Generation effect can optionally emit particles from that geometry, based on its Emit Geometry params.
• Attachment to Entities: There are code methods to spawn an emitter and attach it to a game entity that has geometry. The effect's Emit Geometry params will determine how particles are emitted from that geometry.

Breakable Objects

There are several ways to create breakable geometry in the engine. All are based on a CGF authored with multiple parts. All optionally allow secondary particle effects to be spawned on the broken pieces. I'll summarise these methods here, even though they aren't always particle-based:

• Pure particle effect: You can create a particle effect that instantly creates an "exploding" object. To do this:
• Set the effect's Geometry to a multi-part CGF.
• Set Geometry in Pieces {{ true, and Count }} 1 (for 1 exploding object).
• Set appropriate values for Speed, Focus, Rotation Rate etc to create a nice exploding effect.
• Optionally set Real Physics and Rigid Body Physics for physicalized pieces.
• Optionally create Second-Generation child effects, with appropriate Emit Geometry params, to create secondary particle effects on the pieces. These effects will spawn at the location of each piece, and if set Continuous, will stay attached to the piece during its lifetime (useful for fire, etc).
• DestroyableObjects: This is a special entity that can be "exploded" via an event. All its pieces break off at once. Particle emitters will be optionally attached to each piece based on its Surface Properties (see below).
• Physically breakable object: This is a Basic Entity, set to use a multi-part CGF, with physics params specifying how pieces break off. The physics engine will break pieces of this geometry off individually based on external forces. Particle emitters will be optionally attached to each piece based on its Surface Properties (see below).

Generating Particles from Surface Properties

Surface properties specify events that occur when something happens to an object with a particular physical material (surface) type. Surface types are identified by names (such as "wood" or "metal"). They can be specified on a render Material, and also on individual pieces or surfaces of a CGF. The properties for each surface type are specified in LUA scripts, stored in the Game/Scripts/Materials directory.

Many of these properties specify particle effects which are spawned based on events such as "bullet" hit or "walk". The effect spawned when a geometry piece breaks off of an entity is specified on the breakage/particle_effect section of the script.

This section has the following parameters:

• name: Particle effect name. This effect can, of course, have multiple child effects. Any effects which are Continuous will remain attached to the geometry piece throughout the piece's and/or effects lifetime.
• scale: Additional scale to multiply particle size quantities.
• count_scale: Additional scale to multiply particle counts.
• count_per_unit: True if particle count should be scaled by the extent of the attached geometry (length for edges, area for surface, etc). This causes particles to be emitted at the same density, regardless of the size of the attached object. You need to experiment to find a good value for count_scale in this case.

Directing Particles to a Target

Particles can be set to move toward a target in several ways. The exact way in which particles move toward the target can be customized with the particle params in the TargetAttraction group.

• External Target, from Editor: To specify an entity in the Editor as the target for an emitter entity, create an Entity Link between the emitter entity and the desired target entity. Set the name of this link to "Target".
• External Target, from Code: From code, the function IParticleEmitter.SetTarget sets a target entity for the emitter.
• Internal Target, from Particle Params: To cause a sub-emitter within an effect to become a target, to which all child sub-emitter particles are attracted, set the parameter Force Generation = Target.

Particle Performance

Profiling Tools

Performance Tips

The total number of particles in a scene is actually not very critical. Much more important are total fill-rate, physics, and (to some extent) spawn rate. So, in a framerate-challenged scene, try to avoid these things:

• Many emitters with few particles. Per-emitter overhead is more expensive than per-particle overhead. So it's more efficient to have fewer emitters, each with many particles, than the opposite.
• Large overdraw. For example, using several large particles (Count > 1 or 2, Size > 1m), additively blended to achieve dense, chaotic glows, refractions, etc. Instead of multiple overlaid sprites to provide chaotic variation and overall density, try the following techniques:
  • Use an Alpha texture with high average opacity instead of Additive.
  • Use just 2 particles at a time, and carefully tune the lifetime, rotation rate, and set curves for Alpha, Color, Size, so that they combine in chaotic ways.

• Soft Particles, and expensive shaders, such as refractive materials. These are quite expensive when used with several large particles.
  • Use Soft Particles only on sub-emitters that are near the ground, and have only small particles. Create similar sub-emitters higher up, that emit particles that never intersect the ground, and don't need soft particles.
  • For fire, use a horizontal glow texture. Combine that with some glow billboard sprites emitted higher up that don't intersect the ground. None of them need Soft Particles.

• High-resolution source textures. Use lower-res textures (if sharp details are not required), and texture compression.
• High-count second-generation effects. Each 2nd-gen effect causes an emitter to be created for each particle in the parent effect. This can be quite nice, but somewhat expensive, so use sparingly.
• Real Physics. Physicalised particles should be used quite sparingly, as they are expensive.
  • If simple terrain collision is enough, set Bounciness > 0, and Real Physics false.
  • Consider splitting an effect into sub-effects, so that only a few particles (perhaps large ones) have Real Physics for appearance, and the rest just go through the ground or fade out quickly.