Firing geometry and beam weapons

Where a shot and its firing effects appear, the order in which one shot produces them, and which effects stop the weapon firing until they end.

One shot can produce a projectile, a laser beam or sonic wave, weapon particle effects, a firing animation, a sound, recoil, a spent round and a reload delay. These parts do not all appear at the same point on the firer, and some take their settings from a different weapon slot than the one that fired. As a result, a beam and the shell fired with it can leave from opposite sides of the same gun.

Projectile flight and impact covers the projectile after launch. This page covers the moment of firing.

Weapon slots in brief

An object type has three weapon slots. Primary= fills the first, Secondary= the second, and Elite= the third. The third slot is never fired directly; it only replaces the first slot on an elite object.

Each slot also holds a firing offset, a barrel length and a barrel thickness. These come from the type’s image section in art.ini, not from rules.ini. The first slot uses PrimaryFireFLH, PBarrelLength and PBarrelThickness. The second slot uses SecondaryFireFLH, SBarrelLength and SBarrelThickness. The third slot uses the first slot’s three values.

Two substitutions can replace a whole slot, including its offsets. Both are checked each time the slot is used, so a promotion or a new upgrade applies from the next shot.

An object at elite rank uses the third slot in place of the first. Because the third slot takes the first slot’s offsets, the elite weapon fires from the same point on the artwork. If the type sets no Elite= weapon, the first slot’s weapon stays in use.
A structure with upgrades plugged in takes each slot from the first upgrade type that has a weapon in that slot. It also takes that upgrade type’s offsets for the slot. This replacement is checked before rank, so an upgrade’s first-slot weapon also replaces the elite weapon.

On this page, the firing slot means the slot the shot was ordered from, after these substitutions. The first slot means slot one after these substitutions, so on an elite object it holds the elite weapon.

This abridged example shows where the settings go. The weapons are named in rules.ini, and their offsets are set in art.ini under the type’s image, which is the type’s ID unless Image= names another:

[GunTower]
Primary=GunTowerGun    ; the weapon the first slot fires
Secondary=GunTowerBeam ; the weapon the second slot fires

[GunTowerGun]
Burst=2                ; alternates the shot between the two sides of the gun

[GunTower]
PrimaryFireFLH=120,20,80   ; forward, lateral and height of the first slot's mounting
PBarrelLength=40           ; how far that slot's muzzle runs past the mounting
PBarrelThickness=6         ; how far that muzzle sits above it
SecondaryFireFLH=140,0,60  ; the second slot's mounting, in the same three parts
SBarrelLength=40
SBarrelThickness=6

The shot, step by step

One shot runs the steps below in order. A step that ends the shot skips every later step, so no round is spent and no reload delay is set.

The firing slot must hold a weapon. An empty slot fires nothing.
If the weapon’s warhead has a LimpetFactor above 0 and the target is a vehicle, infantry, aircraft or structure, no projectile is fired. If the firer’s house has not yet marked that target, the target is marked, the weapon’s Report sound plays, and the firer is taken off the map. If that house has already marked the target, the shot ends and the firer stays.
The shot ends if this weapon’s effect from an earlier shot is still alive. Effects that hold the weapon shut lists these effects.
The barrel starts turning to the elevation chosen for this target.
The projectile’s damage is set. An IsSonic=yes or UseFireParticles=yes weapon gives its projectile no damage. For any other weapon, a positive Damage is multiplied by the house’s firepower bias and the object’s firepower bias, and raised further by the veteran firepower ability. A zero or negative Damage is used unchanged.
The projectile is created and launched from the mounting. A laser, railgun or sonic weapon also creates its projectile here. The shot ends if the projectile cannot be created, if no ballistic arc reaches the target, or if the projectile cannot be placed at the mounting.
A turreted object recoils.
If the firing slot’s barrel length is above 0, the projectile takes two flight turns at once, so it starts two turns further along its path. A projectile with a ROT above 0 launches at a speed of 1, so these turns move it only a short way. IsLaser=yes weapons and Inviso=yes projectiles skip these turns. They are ordinary flight turns, so a projectile that would detonate during them does.
A UseFireParticles=yes, UseSparkParticles=yes or IsRailgun=yes weapon starts its effect at the muzzle. The railgun beam deals its damage now, before any later step; IsRailgun covers what it hits.
The burst counter advances, the reload delay is set from the advanced counter, and the counter returns to 0 after the last round of the burst.
The weapon’s Report sound plays at the mounting. When the projectile is Dropping=yes, it plays at the firer’s center.
The firing animation from the weapon’s Anim list appears at the muzzle. It is attached to a firing vehicle, infantry or aircraft and moves with it. On a structure it stays where it appeared and is drawn with a depth adjustment.
An IsSonic=yes weapon creates its sonic wave, from the muzzle to the target.
An IsLaser=yes weapon draws its beam, from the muzzle to the target. On a structure, the beam also resets the turret’s charge animation to its first frame. The structure then discharges its turret unless it has more than one round of Ammo left, so every structure with the default unlimited Ammo discharges. Charges covers what that means for a charging weapon.
A round of ammunition is spent.
If the target is an object a human player owns, the firer reveals the area within two cells of itself to that player when it stands in that player’s shroud or fog, or when it belongs to another house and that player has not yet discovered it. That player’s own aircraft are exempt from the shroud and fog test. A shot at the ground reveals nothing. In a campaign, any player-controlled house counts as a human player here, and the tests use the player’s own shroud, fog and discoveries.

The Anim list is indexed by the direction the object is firing. A list of 8, 16, 32 or 64 entries uses the entry for that direction, rounded to the list’s number of directions. The first entry is for north-west, and the list continues clockwise, so on an eight-entry list the second entry is north and the third north-east. A list of any other length always uses its first entry.

Step 10 sets the reload delay after step 9 has started the weapon’s effects. This lets the delay depend on whether an effect is alive; The reload delay gives the result.

The mounting and the muzzle

Every shot uses two points on the firer, and they move differently as the gun aims.

The mounting is where the projectile is created and the point its aim is calculated from. It is the firing slot’s offset turned to the gun heading, with TurretOffset added to the forward distance. It ignores the barrel, so it stays in place while the gun elevates.

The muzzle is where the firing animation, the laser beam, the sonic wave and the weapon particle effects appear. It starts from the same offset, rises by the slot’s barrel thickness, then extends by the barrel length along the elevated barrel.

The gun heading, and whether the points tilt with the body, depend on the kind of firer:

Firer	Gun heading	Mounting	Muzzle
Vehicle with a turret	The turret facing	Tilts with the body on slopes	Stays upright
Vehicle without a turret	The body facing	Tilts with the body on slopes	Stays upright
Aircraft	The turret facing, whether or not it has a turret	Tilts with the body	Stays upright
Infantry	The body facing	The same point as the muzzle, so barrel length and thickness move the projectile too	Stays upright
Structure with a turret	The turret facing	Stays upright	Stays upright
Structure without a turret	The direction from its center to its target	Stays upright	Stays upright

A structure can replace both points. The engine tests these cases in order and uses the first that applies:

A structure with a PrimaryFirePixelOffset other than 65535,65535 uses that screen offset, projected onto the ground, for both points and for every slot.
A BarrelAnimIsVoxel=yes structure places both points at the end of its voxel barrel, from VoxelBarrelOffsetToBarrelEnd. Both points rise as the barrel elevates.
Any other structure uses the points described above. When its turret is a voxel, the turret animation’s screen offset is added to both.

The barrel’s elevation is chosen from the first slot, whichever slot fires:

A structure whose first-slot weapon has IsLaser=yes points its barrel straight at the aim point.
An EMPulseCannon=yes structure solves a ballistic arc. If no arc reaches the target, it tries again with a launch speed a quarter higher.
Every other object solves a ballistic arc for its first-slot weapon. The barrel takes the high arc when that weapon is Lobber=yes, or when the target stands higher above the firer than it is away horizontally. Lobber on the second slot does not raise the barrel. The projectile itself still follows its own weapon’s Lobber.

How a burst alternates muzzles

The burst counter runs from 0 up to one less than the weapon’s Burst. When the counter is odd, the lateral part of the firing offset is reversed. A burst weapon therefore fires alternately from two points on either side of the centerline. A structure with a voxel barrel alternates the lateral part of its barrel offset instead. The first shot of a burst uses one side and the second the other. The third and later shots come from the center.

Step 10 advances the burst counter partway through the shot, so the parts of one shot are placed with two different counter values:

This shot’s counter: the projectile, the report sound, and the fire, spark and railgun effects.
The next shot’s counter: the firing animation, the sonic wave and the laser beam.

The two groups appear on opposite sides of the gun when one counter value is odd and the other even. With an even Burst that is every shot. With an odd Burst it is every shot except the last of each burst.

A structure with a voxel barrel works the other way, because its muzzle uses the previous counter value, which cancels the advance. There the firing animation, sonic wave and laser beam appear at the projectile’s barrel, while the fire, spark and railgun effects appear at the previous shot’s barrel.

A weapon is affected only if its Burst is above 1 and its lateral offset is not zero. PrimaryFirePixelOffset places every part at one point.

What each part of a shot reads

Several parts of a shot take their settings from the first slot, not from the slot that fired. This matters when a beam or wave weapon is in the second slot, or when the two slots have different offsets.

Part of the shot	Appears at	Settings from
The projectile, its damage, warhead and projectile range	The mounting	The firing slot
The report sound	The mounting	The firing slot
The firing animation	The muzzle	The firing slot
The fire and spark particle systems	The muzzle	The firing slot
The railgun beam, its `AmbientDamage`, warhead and `AttachedParticleSystem`	The muzzle	The firing slot
The sonic wave’s `AmbientDamage` and warhead	The firing slot’s muzzle when created, then the first slot’s muzzle	The first slot
The laser beam’s `LaserInnerColor`, `LaserOuterColor`, `LaserOuterSpread`, `LaserDuration` and `IsBigLaser`	The firing slot’s muzzle	The first slot
The barrel elevation, including the high arc from `Lobber`	Not placed	The first slot
The reload delay	Not placed	The firing slot

A sonic wave starts at the muzzle of the slot that fired it. From the next frame it is redrawn from the first slot’s muzzle. If the two slots have different offsets, a second-slot sonic wave therefore jumps one frame after it is fired. A UseFireParticles=yes stream also moves to the first slot’s muzzle, but only on frames when the firer has a target and is still turning. Particle systems covers how it follows the firer.

Effects that hold the weapon shut

Four weapon effects stop an object from firing while they are alive:

the fire stream of a UseFireParticles=yes weapon;
the spark spray of a UseSparkParticles=yes weapon;
the railgun trace of an IsRailgun=yes weapon;
the sonic wave of an IsSonic=yes weapon.

The first three each occupy one of the object’s particle holds. An object has room for one sonic wave, so it can have only one alive at a time.

The object checks these effects in three places, with a different result each time:

The other slot. If the weapon in the slot that is not firing has a live effect, the object reports that it cannot fire at this target at all.
The firing slot. If the firing slot’s weapon has a live effect, the object is treated as still reloading.
The shot itself. Step 3 of the firing sequence repeats the firing slot’s check and ends the shot.

Each check asks only whether the hold is occupied, not what occupies it. This matters only for the spark hold, which a damaged object’s sparks share with a spark weapon’s spray. Particle systems covers the result.

Vehicles have one more gate, unrelated to effects. FiringSyncFrame1 times the first round of each burst to the firing animation, and FiringSyncFrame2 times the second round. A weapon without a burst uses FiringSyncFrame1 for every round. While the firing animation is playing, the round is treated as still reloading until the animation reaches the named frame. It then fires even if the reload delay has not run out. Only first-slot shots are timed this way.

The reload delay

The delay before the next shot comes from the first row that applies:

The firer and its weapon	Frames until the next shot
A structure that had more than one round of `Ammo` when it fired	1
The weapon is `IsSonic=yes`, whether or not a wave is alive, or is a fire, spark or railgun weapon whose particle hold is occupied	Exactly `ROF`
The burst has rounds left	`BurstDelay0` after the first round, up to `BurstDelay3` after the fourth. A random 3 to 5 when that entry is `-1`, or after the fifth or a later round
Any other shot	`ROF` multiplied by the house’s rate-of-fire bias, plus a random 0 to 2, then shortened by the veteran rate-of-fire ability

The third row sets the pace of the effect weapons. It skips the house bias, the burst delays and the random extra frames, and the effect blocks firing until it ends. The next shot therefore waits until both ROF has passed and the effect has ended. A structure with more than one round left matches the first row instead, so only the effect’s lifetime paces it.

Filter keysRuntime effect

38 of 38

Key	Description	Value	When omitted
`AmbientDamage`WeaponType	The damage a sonic wave or a railgun beam deals to everything along its path, as opposed to the damage the shot delivers at the target.	integer	`0`
`Anim`WeaponType	The animations played at the firing coordinate when the weapon goes off, either one fixed entry or one per facing.	list of AnimTypes	`(empty)`
`AttachedParticleSystem`WeaponType	The particle system a flame, spark or railgun weapon spawns as it fires.	string	`none`
`BarrelAnimIsVoxel`BuildingType	Draws a building's gun barrel from a voxel model over its turret animation.	boolean	`no`
`Burst`WeaponType	How many shots the weapon fires in quick succession before it waits out its full reload.	integer	`1`
`BurstDelay0`WeaponType	The gap in frames between the first and second shot of a burst.	integer	`-1`
`BurstDelay1`WeaponType	The gap in frames between the second and third shot of a burst.	integer	`-1`
`BurstDelay2`WeaponType	The gap in frames between the third and fourth shot of a burst.	integer	`-1`
`BurstDelay3`WeaponType	The gap in frames between the fourth and fifth shot of a burst.	integer	`-1`
`Charges`WeaponType	Makes a structure wind its turret animation up to full charge before the weapon will fire.	boolean	`no`
`Elite`AircraftType, BuildingType, InfantryType, UnitType	The WeaponType an elite object fires in place of its primary.	class	`none`
`FiringSyncFrame1`UnitType	The countdown value at which the first round of a burst leaves a shape-drawn vehicle.	integer	`-1`
`IsBigLaser`WeaponType	Widens the screen glow drawn along a laser beam.	boolean	`no`
`IsLaser`WeaponType	Draws a beam from the muzzle to the target as the weapon fires.	boolean	`no`
`IsRailgun`WeaponType	Fires a beam that damages objects along the line from the muzzle to the target as the weapon fires.	boolean	`no`
`IsSonic`WeaponType	Sends a visible wave rolling from the muzzle to the target, damaging everything it crosses on the way.	boolean	`no`
`LaserDuration`WeaponType	How many frames a laser beam stays drawn for.	integer	`10`
`LaserInnerColor`WeaponType	The color of the thin core line of a laser beam.	color (R,G,B)	`0,0,0`
`LaserOuterColor`WeaponType	The color of the pair of glow lines drawn alongside a laser beam's core.	color (R,G,B)	`0,0,0`
`LaserOuterSpread`WeaponType	How far each channel of a laser beam's glow color may shift at random on each frame.	color (R,G,B)	`0,0,0`
`Lobber`WeaponType	Makes the weapon always throw its shot on the high arc rather than the flat one.	boolean	`no`
`PBarrelLength`AircraftType, BuildingType, InfantryType, UnitType	How far out along the first weapon's barrel its muzzle sits.	integer	`0`
`PBarrelThickness`AircraftType, BuildingType, InfantryType, UnitType	Raises the point the first weapon's barrel pivots about.	integer	`0`
`Primary`AircraftType, BuildingType, InfantryType, UnitType	The WeaponType in the object type's first weapon slot.	class	`none`
`PrimaryFireFLH`AircraftType, BuildingType, InfantryType, UnitType	The offset from an object's center that its first weapon fires from.	point (x,y,z)	`0,0,0`
`PrimaryFirePixelOffset`BuildingType	The screen offset a building's shots leave from, in place of its firing offsets.	point (x,y)	`65535,65535`
`RailgunDamageRadius`global rules	How far an object's center may stand from a railgun beam and still be caught by it.	integer	`128`
`Report`AnimType, WeaponType	The sound effect played when the weapon fires, or when the animation starts.	sound	Varies by type
`ROF`HouseType, WeaponType, difficulty settings	A weapon's frames between shots, or the multiplier a country or a difficulty setting applies to that delay.	floating point	Varies by type
`SBarrelLength`AircraftType, BuildingType, InfantryType, UnitType	How far out along the second weapon's barrel its muzzle sits.	integer	`0`
`SBarrelThickness`AircraftType, BuildingType, InfantryType, UnitType	Raises the point the second weapon's barrel pivots about.	integer	`0`
`Secondary`AircraftType, BuildingType, InfantryType, UnitType	The WeaponType in the object type's second weapon slot.	class	`none`
`SecondaryFireFLH`AircraftType, BuildingType, InfantryType, UnitType	The offset from an object's center that its second weapon fires from.	point (x,y,z)	`0,0,0`
`SecondaryFirePixelOffset`No effectBuildingType	Parsed screen offset that the engine never uses.	point (x,y)	`65535,65535`
`TurretOffset`AircraftType, BuildingType, InfantryType, UnitType	Moves an object's turret forward from its center along the centerline.	integer	`0`
`UseFireParticles`WeaponType	Attacks with a stream of fire particles instead of the projectile's damage.	boolean	`no`
`UseSparkParticles`WeaponType	Sprays a particle system at the target alongside the shot.	boolean	`no`
`VoxelBarrelOffsetToBarrelEnd`BuildingType	Where a building with a voxel barrel creates its shots.	point (x,y,z)	`0,0,0`