Particle systems

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

A particle system is the thing that owns particles. It creates them, ages them, moves them, replaces them and takes them off the map, and none of that happens to a particle except on the turn its holding system takes. Which of those things a given system does is settled by one setting, and each of the seven values that setting accepts drives a different routine reading a different handful of the settings written beside it.

That is why a section carrying fifteen assignments can produce an effect answering to four of them. The two tables below are the whole of the division: each names every setting its behavior consults, and a setting missing from its row is read into the type, kept there, and never looked at again.

Particle system types and particles in brief

Two type definitions are involved, and they are easy to confuse, because both carry a key named BehavesLike and both accept the same seven names for it.

A ParticleSystemType describes an emitter: how often it puts particles out, how many, in what direction, and when it gives up. A ParticleType describes one puff, spark, flame or cloud: what it looks like, how long it lives, how it moves, and what it does to whatever it touches. HoldsWhat is the link between them, naming the one particle type a system makes for itself. 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 settings are independent. The system’s decides how particles are emitted and aimed; the particle’s decides what each one does once it exists. Nothing requires them to agree, and a smoke system holding a spark particle is a legal pairing that behaves as the pairing implies rather than as either name alone suggests.

At runtime the system is an object standing on the map, and the particles it holds are objects too. Only the system takes a logic turn.

What each system behavior reads

Each row is one value of the setting and names what a running system of that type consults. Every other setting in the section is parsed, stored, and passed over.

Four settings are read whatever the value says, the last two rows included, and are left out of the table to keep it short: Lifetime, which counts down for every system alike, and OneFrameLight with LightSize and ParticleCap, which together draw the glow a system of any behavior may cast.

BehavesLike	Used keys
Smoke	HoldsWhat, SpawnFrames, Slowdown, SpawnCutoff, SpawnTranslucencyCutoff, SpawnRadius
Fire	HoldsWhat, SpawnFrames
Spark	HoldsWhat, SparkSpawnFrames, SpawnSparkPercentage, SpawnDirection, and ParticleCap, LightSize and OneFrameLight a second way
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

Spawns appears in no row, under any behavior.

Three things the table cannot show go with it.

A gas, weak gas or web system makes no particle under its own power, but whatever built the system usually asks it for one on the spot, and that request does read HoldsWhat. A warhead’s Particle, an exploding BarrelParticle overlay, and each cell of a web blast all work that way. Everything such a system holds afterwards arrives through a successor.

Successors are the system’s business rather than the particle’s, and the settings they read 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, thrown to either side by the expiring particle’s Radius and ignoring the offset; fire, spark and railgun systems make none, which leaves all three of those settings inert on any type they hold.

Only two behaviors move the system itself. A smoke system rides along with the object it was attached to, where it has one and that object is not a structure, and stops emitting altogether while that object is inside a subterranean tube. A fire system re-anchors to the firer’s muzzle and re-aims along its body facing, but only on frames where the firer is both holding a target and still turning. A spark, railgun, gas, weak gas or web system stays exactly where it was created, however far the object it belongs to travels.

The turn

Particle systems take their turns at a fixed point in the logic frame, after vehicles and before terrain, walking the list of systems from the end toward the start. Every behavior ages each particle it holds and then removes the ones that flagged themselves as finished. Four of them also create particles, and where that falls differs: a spark or railgun system creates before the aging pass, a smoke or fire system after it.

Particles have no turn of their own, and that carries a consequence worth stating plainly: a particle ages and moves only where the routine holding it reaches for it. A fire system runs the movement step on every particle it holds, including the ones expiring that frame; gas, weak gas, smoke and web systems run it on all but those. Spark and railgun systems never run it at all, so a particle held by one of those two moves only in whatever way its own aging step moves it, whatever its own behavior would otherwise do about drifting.

Ending a system

Asking a system to go does not remove it. The request only marks the system, which stops a smoke, fire or railgun system emitting and leaves a spark system throwing bursts until its own SparkSpawnFrames run out; either way it stays on the map until the last particle it is holding has died, and only then does it leave. This is why a weapon whose shot is a particle effect is barred from firing again until that effect has burned out, and why a repaired vehicle can go on smoking for a while after the damage that started the plume was undone.

A system is marked under any of:

• its own behavior’s condition is met — a smoke system’s spawn interval passing SpawnCutoff, a spark system’s SparkSpawnFrames running out, a railgun system finishing the single pass that lays its trace, or a fire system finding it has no live firer left to follow;
• a positive Lifetime counts down to zero;
• the object the system was attached to is taken off the map;
• something outside asks it to go — a repair, a cloak, an order to move, a new target out of range, or the Remove particle anim at… action, which matches systems by the cell they are standing in at that moment.

Gas, WeakGas and Web have no condition of their own, so a system of one of those three, or of no behavior at all, goes only by one of the last three routes.

The five holds an object keeps

A vehicle, aircraft, infantry or structure keeps five holds, each one a place for a single running system. A hold that is already full is why a second system of the same kind is not started.

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
Natural	a structure’s NaturalParticleSystem
Damage	the smoke a damaged object gives off
Railgun	the trace an IsRailgun=yes weapon lays

The types themselves are named elsewhere: a weapon’s by AttachedParticleSystem, a damaged object’s by DamageParticleSystems, which is one list split by each entry’s behavior into the sparks that fill the spark hold and the smoke that fills the damage hold.

Damage sparks and a spark weapon share one hold

Nothing separates them. A damaged object that has picked up a spark system from its DamageParticleSystems cannot fire a UseSparkParticles=yes weapon until that system has cleared, because the test that bars the shot asks only whether the spark hold is occupied. It runs the other way too: while a spark weapon’s spray is alive, the object grows no damage sparks. The fire, natural, damage and railgun holds each answer to one claimant and are unaffected.

Deleting a structure’s plume outright strands half of its particles

Every other system on this page is marked and left to run itself out. A cloaking structure’s plume is the exception: it is removed outright the moment the structure turns fully transparent, while it may still be holding particles. The removal frees the first particle in its list, drops the second from that list without freeing it, and repeats down the list — so roughly half the puffs the plume was carrying are left behind with no system keeping them. Nothing ages, moves or removes them afterwards, and they go on being drawn where they stood for the rest of the scenario, a fresh patch of them for every cloak. NaturalParticleLocation covers the rebuild on the way back out, which is guarded by the offset rather than by the system.

What each particle behavior reads

The same division applies one level down, on the ParticleType. MaxEC is read whatever the value says and is left out of the table. So are NextParticle, NextParticleOffset and Radius: all three answer to the holding system’s row above rather than to any row here.

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	XVelocity, YVelocity, MinZVelocity, ZVelocityRange, 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

StartFrame and NumLoopFrames appear in no row, under any behavior.

Two entries above are worth reading twice. Normalized recomputes the interval between animation states as the particle is created, but only a Fire particle reads the recomputed figure — on every other behavior the setting is stored and the authored StateAIAdvance is what runs. And a Web particle does read its warhead, but always applies it at zero damage, so its own Damage figure changes nothing.

Two things outside the section reach only part of the set. WindDirection picks one fixed offset for the whole map, and Gas, WeakGas and Smoke particles are the only ones that take it, with WindEffect scaling how often or how far. The vertical pull of Gravity reaches Gas, WeakGas and Spark particles alone.

Systems that no attachment holds

Four sites build a system that belongs to nothing at all: a warhead’s Particle at each impact, a Webby=yes warhead in every cell it covers, an exploding barrel’s BarrelParticle on one blast in four, and the Particle anim at… action on the ground at a waypoint. None of those has a source object, so nothing removes it when anything is destroyed and nothing moves it once it is placed, whatever its behavior.

Two more sites build a system with a source but no hold: a piece of debris carries its AttachedSystem, and a vehicle or aircraft killed by the firestorm warhead throws seven to nine copies of DefaultFirestormExplosionSystem. Both are marked when the object that made them goes.

Two systems are named by the engine rather than by any assignment, so a mod can only reach either through the section carrying that exact name. GasCloudSys is the scenario’s shared gas cloud: one system, built once as the scenario starts rather than once per blast, into which every gas-behavior warhead particle is released instead of into a system of its own. That single system’s turn is therefore what ages and drifts every such particle in the match, and its own HoldsWhat is what they are made of, whatever the warhead named. GasPuffSys is the puff a levitating vehicle leaves behind as it accelerates.

Retiring the shared gas cloud crashes the next gas detonation

Nothing rebuilds it. The one build happens as the scenario is set up, and the blast that releases a gas particle takes the shared cloud and puts a particle into it without first checking that it is still there. Two things can take it away mid-match: a positive Lifetime on the GasCloudSys section, which is the one retirement route a gas system has, and a Remove particle anim at… action whose waypoint lands on the cell the cloud stands in, which is fixed at 10,10. Either way the cloud leaves once the last particle in it has died, and the next detonation carrying a gas-behavior Particle stops the game. Leave Lifetime off that section.

Of the ten Default…System names the rules carry, DefaultFirestormExplosionSystem is the only one that reaches a system that is ever built; the DefaultSparkSystem page covers the other nine as a group. HalfDamageSmokeLocation1 and its two companions stand on the same footing beside 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 named behavior that decides which fixed routines drive a particle or a particle system.	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 delivers through its own warhead.	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 unit 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, hover cushions and 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	Punches a damaging line through the world 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.	colour (R,G,B)	0,0,0
LifetimeParticleSystemType	How many frames a particle system runs before it is retired.	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 speed a spark is thrown at.	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 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 creates its particles a step more faded.	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 no gameplay path reads.	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.	colour (R,G,B)	0,0,0
StartColor2ParticleType	The other end of the color range a spark or railgun particle is created at.	colour (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 far a railgun particle's speed may run above its own type's velocity.	floating point	0.0
WarheadAnimType, ParticleType, VoxelAnimType, WeaponType	The WarheadType a weapon's shot carries, 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 59fae722af8c