Particle systems

Features & systems·Combat & weapons·Weapons, warheads & projectiles

A particle system creates, ages, moves and removes the particles it holds. Particles take no turn of their own, so nothing happens to a particle except during its system’s turn. The system’s BehavesLike value selects which of those steps run and which settings in the system’s section are read.

Most settings apply to only some behaviors. A setting the behavior does not read is loaded and then ignored, so a section with fifteen assignments can produce an effect controlled by four of them. The two tables below list every setting each behavior reads.

Particle system types and particles in brief

Two kinds of type definition work together. Both have a BehavesLike key, and both accept the same seven names, so they are easy to confuse.

A ParticleSystemType describes an emitter: how often it creates particles, how many, in which direction, and when it stops. A ParticleType describes one puff, spark, flame or cloud: how it looks, how long it lives, how it moves, and what it does to objects it touches. The system’s HoldsWhat names the one particle type it creates. Rules registration lists covers how the [ParticleSystems] and [Particles] lists are read and what an unknown name does.

rules.ini

[ParticleSystems]
0=MYSMOKESYS

[Particles]
0=MYSMOKEPUFF

[MYSMOKESYS] ; the emitter
BehavesLike=Smoke
HoldsWhat=MYSMOKEPUFF
SpawnFrames=10
Slowdown=.0025
SpawnCutoff=15.0

[MYSMOKEPUFF] ; the thing emitted
Image=SGRYSMK1
BehavesLike=Smoke
MaxEC=80
Velocity=6
Deacc=.02
EndStateAI=20

The two BehavesLike values are independent. The system’s value decides how particles are emitted and aimed. The particle’s value decides what each particle does once it exists. They do not have to match. A smoke system can hold spark particles: the system decides when particles appear and whether they get successors, and each spark particle still ages and moves as a spark.

What each system behavior reads

Each row lists the settings that a running system with that BehavesLike value reads on its turn. The system ignores every other setting in its section.

Four settings apply to every system, including those in the last two rows. Lifetime counts down for every system. OneFrameLight, LightSize and ParticleCap control the glow that a system of any behavior can cast. The table names these four only where a behavior also uses them in another way.

BehavesLike	Used keys
Smoke	HoldsWhat, SpawnFrames, Slowdown, SpawnCutoff, SpawnTranslucencyCutoff, SpawnRadius
Fire	HoldsWhat, SpawnFrames
Spark	HoldsWhat, SparkSpawnFrames, SpawnSparkPercentage, SpawnDirection, plus ParticleCap for the size of each burst and LightSize for a flash on the first frame, which appears only when OneFrameLight is off
Railgun	HoldsWhat, ParticlesPerCoord, SpiralRadius, SpiralDeltaPerCoord, PositionPerturbationCoefficient, MovementPerturbationCoefficient, VelocityPerturbationCoefficient, Laser, LaserColor
Gas, WeakGas, Web	nothing, HoldsWhat included
A name outside the seven, or no name at all	nothing, HoldsWhat included

No behavior reads Spawns.

Some places that build a system ask it for one particle at once, whatever its behavior. That particle comes from HoldsWhat. A warhead’s Particle, an exploding barrel’s BarrelParticle and each cell of a web blast work this way. For a gas, weak gas or web system, this first particle is the only one HoldsWhat ever supplies; every later particle is a successor. The Particle anim at… action asks for no particle, so a gas, weak gas or web system it places stays empty.

The system decides whether an expiring particle gets a successor, but the settings involved sit on the particle type:

• A gas, weak gas or web system replaces each expiring particle with one NextParticle successor, displaced by NextParticleOffset.
• A smoke system replaces it with two successors, thrown to either side by the expiring particle’s Radius. It ignores NextParticleOffset.
• Fire, spark and railgun systems create no successors, so all three settings have no effect on the types they hold.

Only smoke and fire systems move:

• A smoke system follows the object it is attached to, unless that object is a structure. It creates no particles while that object is traveling through a map tunnel.
• A fire system moves to the muzzle of its firer’s first weapon slot and re-aims along the firer’s body facing. It does so only on frames when the firer has a target and is still turning.

Spark, railgun, gas, weak gas and web systems stay where they were created, however far the object they belong to travels.

The turn

Particle systems take their turns in each logic frame after animations, building lights, bullets, structures, aircraft, infantry and vehicles, and before terrain objects, voxel animations and waves.

On its turn, a system with one of the seven behaviors ages every particle it holds, then removes the particles that have finished. Smoke, fire, spark and railgun systems also create particles. Spark and railgun systems create them before aging; smoke and fire systems create them after.

A system with no recognized behavior does nothing on its turn. A particle put into it never ages, moves or expires, and the system stays on the map for as long as it holds that particle.

A particle moves only when its system runs the movement step for it:

• A fire system moves every particle it holds, including those expiring that frame.
• Gas, weak gas, smoke and web systems move every particle except those expiring that frame.
• Spark and railgun systems never run the movement step. In those systems, only Spark and Railgun particles move, because they move themselves as they age. Particles of other behaviors stay where they were created.

Ending a system

Asking a system to end only marks it. A marked smoke, fire or railgun system stops creating particles. A marked spark system keeps throwing bursts until its SparkSpawnFrames run out, unless all its particles expire between two bursts first. Either way, the system stays on the map until its last particle has expired, and only then is it removed.

This delay has visible effects. A repaired vehicle can keep smoking for a while, because its damage smoke stops producing puffs but the existing puffs and their successors live out their time. A system also keeps its object’s hold filled until it is removed.

A system is marked when any of these happens:

• Its behavior’s end condition is met. A smoke system ends when its spawn interval passes SpawnCutoff. A spark system with a positive SparkSpawnFrames ends when that count runs out. A railgun system ends after it lays its trace, which it does in a single turn. A fire system ends when it has no live firer to follow.
• A positive Lifetime counts down to zero.
• The object the system is attached to is taken off the map, changes owner, or starts to cloak.
• Damage smoke ends when its object is repaired above yellow health or goes underground.
• A fire stream ends when its firer is given a destination (a move order, or its own approach to a target) or a new target out of range.
• The Remove particle anim at… action ends every system standing in the waypoint’s cell at that moment.

Gas, WeakGas and Web have no end condition of their own, and neither does a spark system whose SparkSpawnFrames is 0. A system of that kind, or with no behavior, ends only through one of the other routes above.

The five holds an object keeps

Each vehicle, aircraft, infantry and structure has five holds, and each hold keeps one running system. While a hold is filled, no second system of that kind starts for the object.

Hold	What claims it
Fire	the stream a UseFireParticles=yes weapon throws
Spark	the spray a UseSparkParticles=yes weapon throws, and the sparks a damaged object gives off (infantry only with Cyborg=yes)
Natural	a structure’s NaturalParticleSystem
Damage	the smoke a damaged object gives off
Railgun	the trace an IsRailgun=yes weapon lays

A hold stays filled until its system is removed. An object therefore cannot fire a spark, fire or railgun weapon again until the previous effect has burned out. Firing geometry covers how a filled hold blocks each weapon slot.

The fire hold is the exception. A new destination (a move order, or the object’s own approach to a target) or a new target out of range frees it at once. The old stream burns out on its own, and the object can start a new stream before it has finished.

The types come from other settings. A weapon names its system with AttachedParticleSystem. A damaged object picks from its DamageParticleSystems list: entries with the Spark behavior fill the spark hold, and entries with the Smoke behavior fill the damage hold.

Damage sparks and a spark weapon share one hold

A damaged object that has started a spark system from its DamageParticleSystems cannot fire a UseSparkParticles=yes weapon until that system is removed. The reverse also applies: while a spark weapon’s spray is alive, the object produces no damage sparks. The fire, natural, damage and railgun holds each have a single source and are not affected.

Cloaking a structure strands part of its plume

When a structure finishes cloaking, its natural plume is deleted at once instead of being marked. About half of the puffs the plume held are left behind. They stay on screen where they were, never age, move or expire, and remain for the rest of the scenario. Each cloak leaves another set. NaturalParticleLocation covers how the plume is rebuilt when the structure uncloaks.

What each particle behavior reads

A particle’s BehavesLike likewise decides which settings in its section are read. MaxEC applies to every behavior and is left out of the table. Some particle settings are read by the holding system instead, so they depend on the system’s behavior, not the particle’s:

• NextParticle, NextParticleOffset and Radius control successors, as described under what each system behavior reads.
• XVelocity, YVelocity, MinZVelocity and ZVelocityRange are read by a Spark system, which uses them to throw each particle it creates, whatever that particle’s behavior.

BehavesLike	Used keys
Gas	MaxDC, Damage, Warhead, WindEffect, Translucency, StartStateAI, EndStateAI, StateAIAdvance, DeleteOnStateLimit
WeakGas	everything Gas reads except MaxDC, Damage and Warhead
Smoke	Velocity, Deacc, WindEffect, Translucency, StartStateAI, EndStateAI, StateAIAdvance, DeleteOnStateLimit
Fire	Velocity, Deacc, MaxDC, Damage, Warhead, FinalDamageState, Normalized, Translucency, Translucent25State, Translucent50State, StartStateAI, EndStateAI, StateAIAdvance, DeleteOnStateLimit
Spark	ColorList, ColorSpeed, StartColor1, StartColor2
Railgun	Velocity, ColorList, ColorSpeed, StartColor1, StartColor2
Web	Warhead, Translucency, StartStateAI, EndStateAI, StateAIAdvance, DeleteOnStateLimit
A name outside the seven, or no name at all	Translucency

No behavior reads StartFrame or NumLoopFrames.

Normalized recalculates the interval between animation states when a particle is created, but only Fire particles use the recalculated interval. Particles of every other behavior use StateAIAdvance as written.

A Web particle applies its warhead at zero damage, so its Damage has no effect.

Two global settings reach only some behaviors. WindDirection sets one wind direction for the whole map. Only Gas, WeakGas and Smoke particles drift with it. For Gas and WeakGas particles, WindEffect sets how often they take a wind step. For Smoke particles, it sets how far they move each frame. Gravity affects only Gas, WeakGas and Spark particles.

Systems that no attachment holds

These systems belong to no object:

• a warhead’s Particle, built at each impact, except that a Gas system joins the shared gas cloud described below;
• a Webby=yes warhead’s Particle, built in every cell the web covers;
• an exploding barrel’s BarrelParticle, built on one blast in four;
• the system the Particle anim at… action places on the ground at a waypoint.

None of these has a source object, so no object’s destruction ends them, and none moves after it is placed, whatever its behavior.

Two more are tied to an object but fill no hold. A piece of debris builds its AttachedSystem. An aircraft, or a vehicle without DeathFrames, killed by the firestorm warhead throws seven to nine copies of DefaultFirestormExplosionSystem; each of these picks a random direction for every burst and ignores SpawnDirection. Both kinds are marked when the object that made them is removed.

Two systems are named by the engine, not by any key. A mod configures them only through sections with these exact names:

• GasCloudSys is the scenario’s shared gas cloud. The game builds it once as the scenario starts, at cell 10,10, and it never moves. Every warhead whose Particle system has BehavesLike=Gas releases its particle into this cloud instead of building a system of its own. That particle comes from the cloud’s HoldsWhat, not from the system the warhead names, and the cloud’s turn ages and moves every such particle in the match. Veinhole monsters release their gas into it as well.
• GasPuffSys is the puff a levitating vehicle leaves behind as it accelerates. Each puff builds a new system.

Keep the shared gas cloud alive

The game never rebuilds GasCloudSys. Once it is removed, the next detonation of a warhead with a Gas Particle system crashes the game, and so does the next gas release from a veinhole monster. Two things can remove the cloud during a match:

• a positive Lifetime in the [GasCloudSys] section;
• a Remove particle anim at… action whose waypoint is cell 10,10.

In both cases the cloud is removed once its last particle has expired. Leave Lifetime unset in that section, and keep that action’s waypoint off cell 10,10.

Of the ten Default…System settings, only DefaultFirestormExplosionSystem names a system the game ever builds. The DefaultSparkSystem page covers the other nine.

HalfDamageSmokeLocation1, HalfDamageSmokeLocation2 and a vehicle’s HalfDamageSmokeLocation are loaded but never used. Damage smoke and sparks start at DamageSmokeOffset.

Related settings

Filter keys

69 of 69

Key	Description	Value	When omitted
AttachedParticleSystemWeaponType	The particle system a flame, spark or railgun weapon spawns as it fires.	string	none
AttachedSystemVoxelAnimType	The particle system created with a voxel animation and destroyed with it.	class	none
BarrelParticleglobal rules	The particle system released by an exploding overlay, on one blast in four.	class	none
BehavesLikeParticleType, ParticleSystemType	The behavior a particle or a particle system follows, such as smoke, gas or sparks.	string	none
ColorListParticleType	The colors a spark or railgun particle blends through as it ages.	rgbclass list	(empty)
ColorSpeedParticleType	How fast a spark or railgun particle slides from one of its colors to the next.	floating point	0
DamageAnimType, ParticleType, VoxelAnimType, WeaponType	A weapon's damage per shot, or the damage an animation, particle or voxel animation deals.	floating point	Varies by type
DamageParticleSystemsAircraftType, BuildingType, InfantryType, UnitType	The particle systems a damaged object gives off, sorted into sparks and smoke by their own behavior.	list of ParticleSystemTypes	(empty)
DamageSmokeOffsetAircraftType, BuildingType, InfantryType, UnitType	Where a damaged object's spark and smoke systems are anchored, relative to the object.	offset (x,y,z)	0,0,0
DeaccParticleType	The speed a particle loses each frame.	floating point	0
DefaultFirestormExplosionSystemglobal rules	The ParticleSystemType spawned in place of the usual explosion when the firestorm warhead destroys a vehicle or aircraft.	class	none
DefaultSparkSystemNo effectglobal rules	Parsed particle system name that the engine never uses.	class	none
DeleteOnStateLimitParticleType	Kills a particle the moment its animation reaches the last state.	boolean	no
EndStateAIParticleType	The animation state that ends a particle's sequence.	integer	0
FinalDamageStateParticleType	The last animation state at which a flame particle still burns what it drifts over.	integer	Inherited
Gravityglobal rules	The downward pull applied each frame to ballistic shots, hovering and levitating objects, and some particles.	integer	3
HalfDamageSmokeLocation1No effectBuildingType	Parsed offset that nothing in the engine reads.	point (x,y,z)	0,0,0
HoldsWhatParticleSystemType	The ParticleType every particle a system creates is made from.	string	(empty)
IsRailgunWeaponType	Fires a beam that damages objects along the line from the muzzle to the target as the weapon fires.	boolean	no
LaserParticleSystemType	Whether a railgun system draws a beam alongside its spiral of particles.	boolean	no
LaserColorParticleSystemType	The color of the beam a railgun system draws.	color (R,G,B)	0,0,0
LifetimeParticleSystemType	How many frames a particle system runs before it winds down.	integer	-1
LightSizeParticleSystemType	How strong a light a particle system casts.	integer	0
MaxDCParticleType	The frames between one particle's damage applications.	integer	0
MaxECParticleType	The base lifetime of a particle, in frames.	integer	1
MinZVelocityParticleType	The smallest upward part of the speed picked for each spark.	integer	0
MovementPerturbationCoefficientParticleSystemType	How far each railgun particle's course is deflected from the spiral it was laid on.	floating point	0.0
NaturalParticleLocationAircraftType, BuildingType, InfantryType, UnitType	Where a structure's continuous particle plume sits, relative to the structure.	offset (x,y,z)	0,0,0
NaturalParticleSystemAircraftType, BuildingType, InfantryType, UnitType	A particle system a structure runs continuously from the moment it appears.	class	none
NextParticleParticleType	The particle type created in place of this one when it expires.	string	none
NextParticleOffsetParticleType	How far a successor particle is placed from the one it replaces.	offset (x,y,z)	0,0,0
NormalizedNo effect in some scopes7 applicable types	Rescales an animation's frame delay against the game speed setting, or paces a particle's damage states over its flight.	boolean	no
NumLoopFramesNo effectParticleType	Parsed frame count that the engine never uses.	integer	1
OneFrameLightParticleSystemType	Whether a system's light is redrawn every frame at a brightness that follows how full of particles it is.	boolean	no
ParticleWarheadType	The particle system released where the warhead detonates.	class	none
ParticleCapParticleSystemType	The size of a spark system's burst, and the fullness a one-frame light's brightness is measured against.	integer	50
ParticlesPerCoordParticleSystemType	How many particles a railgun trace lays per lepton of beam length.	floating point	.1
PositionPerturbationCoefficientParticleSystemType	How far each railgun particle is displaced from its place on the spiral, in leptons.	floating point	0.0
RadiusParticleType	How far a smoke system throws the two successors of an expiring particle.	integer	0
SlowdownParticleSystemType	How much a smoke system's spawn interval lengthens every frame.	floating point	0.0
SparkSpawnFramesParticleSystemType	How many frames a spark system goes on throwing bursts for.	integer	0
SpawnCutoffParticleSystemType	The spawn interval a smoke system stops emitting at.	floating point	0.0
SpawnDirectionParticleSystemType	The direction a spark burst is thrown in.	vector	0,0,0
SpawnFramesParticleSystemType	The starting interval, in game frames, between a smoke or fire system's particle spawns.	integer	1
SpawnRadiusParticleSystemType	How far a smoke system scatters its new particles from its own position, in leptons.	integer	0
SpawnSparkPercentageParticleSystemType	The chance that a spark system throws a burst on any one frame.	floating point	0.0
SpawnTranslucencyCutoffParticleSystemType	The spawn interval past which a smoke system raises its new particles' fade level by one step.	floating point	0.0
SpawnsNo effect in some scopesAnimType, ParticleSystemType, VoxelAnimType	The type spawned where thrown debris lands, and on a particle system a flag with no effect.	class	Varies by type
SpiralDeltaPerCoordParticleSystemType	How far a railgun trace's corkscrew turns per lepton of beam length, in radians.	floating point	.025
SpiralRadiusParticleSystemType	The radius of the corkscrew a railgun trace winds around its beam, in leptons.	floating point	25.0
StartColor1ParticleType	One end of the color range a spark or railgun particle is created at.	color (R,G,B)	0,0,0
StartColor2ParticleType	The other end of the color range a spark or railgun particle is created at.	color (R,G,B)	0,0,0
StartFrameNo effectParticleType	Parsed frame index that the engine never uses.	integer	0
StartStateAIParticleType	The animation state a particle is created at.	integer	0
StateAIAdvanceParticleType	The frames a particle spends in each animation state.	integer	4
TranslucencyAnimType, ParticleType	How faded an animation or a particle is drawn, as a percentage, at the detail settings that honor it.	integer	0
Translucent25StateParticleType	The animation state at which a flame particle thins to a quarter faded.	integer	-1
Translucent50StateParticleType	The animation state at which a flame particle thins to half faded.	integer	-1
UseFireParticlesWeaponType	Attacks with a stream of fire particles instead of the projectile's damage.	boolean	no
UseSparkParticlesWeaponType	Sprays a particle system at the target alongside the shot.	boolean	no
VelocityParticleType	The speed a particle is created with, in leptons per frame.	floating point	0
VelocityPerturbationCoefficientParticleSystemType	How much a railgun trace randomly varies its particles' speed.	floating point	0.0
WarheadAnimType, ParticleType, VoxelAnimType, WeaponType	The WarheadType a weapon's shot uses, or the one an animation, particle or voxel animation delivers its own damage through.	class	none
WebbyWarheadType	The warhead entangles the infantry it catches instead of damaging them.	boolean	no
WindDirectionglobal rules	The facing that smoke and gas particles drift toward.	integer	-1
WindEffectParticleType	How strongly the prevailing wind carries a particle sideways.	integer	0
XVelocityParticleType	One horizontal axis of the spread of speeds a spark is thrown at.	integer	1
YVelocityParticleType	The other horizontal axis of the spread of speeds a spark is thrown at.	integer	1
ZVelocityRangeParticleType	The spread of upward speeds a spark is thrown at.	integer	1

Related resources

• Rules registration listsFormat
• Cloaking and detectionFeature or system
• Particle Anim at...Trigger action
• Remove Particle Anim at...Trigger action
• Firing geometry and beam weaponsFeature or system
• Projectile flight and impactFeature or system

Page feedback

Report an error or missing detail. The issue includes this page and revision.

Open issueSource revision 51b52aa38392