Firing geometry and beam weapons

Settles where an object's shots and firing effects appear, in what order one shot produces them, and which of them hold the weapon shut until they burn out.

One routine turns a decision to shoot into everything a shot consists of: the projectile, the beam or wave that goes with it, the muzzle flash, the report, the recoil, the round spent and the delay before the next one. It runs in a fixed order, and several of the things it produces are anchored at different points on the artwork and read from different weapon slots, which is why a beam and the shell it accompanies can leave from opposite sides of the same gun.

Projectile flight and impact owns what the shot does once it is in the air. This page owns the moment of firing.

Weapon slots in brief

An object type carries three weapon slots. Primary= and Secondary= fill the first two; Elite= fills a third that is never fired on its own. Each slot holds more than a weapon: it also holds the firing offset, barrel length and barrel thickness that weapon uses, read from the art entry rather than from the rules.

Two substitutions replace a whole slot, offsets included, and both are settled every time the slot is consulted rather than once.

An object that has reached elite rank reads the third slot in place of the first. Because the offsets travel with the slot and the third slot is filled from the first weapon’s PrimaryFireFLH, PBarrelLength and PBarrelThickness, an elite weapon fires from the same point on the artwork as the weapon it replaces.
A structure with anything plugged into an upgrade slot takes the requested slot from the first plugged-in type that supplies a weapon there — and takes that type’s firing offsets with it, not its own.

Throughout this page the firing slot means whichever slot the shot was ordered from after those substitutions, and the first slot means slot zero after them, which is the elite weapon on an elite object.

The shot, step by step

The order matters because a step that fails ends the shot, and everything below it is skipped. The numbered steps below all belong to one call.

The firing slot’s weapon and projectile are fetched. A slot with no weapon does nothing at all.
A warhead whose LimpetFactor is 1 or more diverts here whenever the target is an object rather than a cell: the mark is clamped on and the firer removes itself. A target this house has already marked ends the shot here too, leaving the firer standing. Either way no shot is created.
The shot is refused outright where the effect this weapon would produce is still alive — see below.
The barrel is given its desired elevation.
The damage the shot will carry is worked out: nothing at all for an IsSonic=yes or UseFireParticles=yes weapon, and otherwise the weapon’s Damage scaled by the house’s and the object’s firepower bias and by the veteran firepower ability.
The projectile is created and launched from the mounting. A shot that finds no ballistic solution, or that cannot be placed at the mounting, ends here and nothing below runs — no round is spent and no reload is started.
A turreted object goes into recoil.
A shot from a weapon whose slot has a barrel length above zero is given two flight turns immediately, so that it appears past the muzzle rather than inside it. An IsLaser=yes weapon and an Inviso=yes projectile are both excluded, and those two turns are ordinary ones — a shot that would detonate on them does.
The fire, spark and railgun effects are spawned at the muzzle, each only where its own hold is empty. The railgun’s beam is walked and its damage dealt at this point, before anything below.
The burst counter advances, the reload delay is set from it, and the counter wraps.
The weapon’s Report sound plays from the mounting — or from the firer’s own center when the projectile is Dropping=yes.
The firing animation from the weapon’s Anim list is created at the muzzle, attached to the firer unless the firer is a structure, in which case it is given a depth adjustment instead. A list of exactly eight entries is indexed by the gun heading rounded to one of eight, with the list rotated one place round: the first entry belongs to a gun facing north-west, the second to north, and so on. A list of any other length always uses its first entry.
The sonic wave is created, from the muzzle to the target.
The laser beam is drawn, from the muzzle to the target. On a structure this also stops the turret animation dead and, where the structure is down to its last round, discharges its turret; Charges covers what that costs a charging weapon.
A round of ammunition is spent, and a firer standing hidden in shroud or fog reveals the ground around itself to the target’s owner where that owner is under player control.

Note where the reload delay sits. It is set at step 10, so the effects at step 9 are already alive when it is worked out — which is exactly what lets the effect weapons take a different delay from everything else.

The mounting and the muzzle

Two distinct points are computed for every shot, and confusing them accounts for most of the surprises on this page.

The mounting is where the projectile is created and where the firing solution is measured from. It is built by taking a frame aligned with the gun heading, then displacing it by the firing slot’s own offset with TurretOffset added to the forward component. The barrel is deliberately not part of it, so the mounting holds still while the gun elevates.

The muzzle is where the fire animation, the laser beam, the sonic wave and the attached particle systems appear. It carries on from the same displacement by adding the slot’s barrel thickness upward, pitching by the barrel’s current elevation, and running out along the pitched barrel by its length.

The gun heading is not the same thing for every kind of object, and neither is the frame the two points are measured in.

Firer	Gun heading	Mounting	Muzzle
Vehicle with a turret	The turret facing	Measured inside the transform the body is drawn with, so ground slope and body tilt move it	Measured upright, so slope and tilt do not move it
Vehicle without a turret	The body facing	As above	As above
Aircraft	The turret facing, whether or not it carries a turret	As above	As above
Infantry	The body facing	The same point as the muzzle, so barrel length and thickness move the projectile too	Measured upright
Structure with a turret	The turret facing	Measured upright	Measured upright
Structure without a turret	The direction from its center to what it is shooting at	Measured upright	Measured upright

A structure has two further layers on top of that, tested in this order for both points alike:

A PrimaryFirePixelOffset other than 65535,65535 replaces both outright with that screen offset projected back onto the ground, whichever slot is firing. Nothing below is consulted.
A BarrelAnimIsVoxel=yes structure takes both from VoxelBarrelOffsetToBarrelEnd run through the barrel’s own placement, so the two points coincide at the end of the barrel and both rise as it elevates.
Otherwise the ordinary transform applies, with the turret animation’s own screen offset added when the turret is drawn as a voxel.

The barrel elevation itself is decided per firer as well. A structure whose first weapon is IsLaser=yes points its barrel straight at the aim point rather than solving anything; an EM pulse cannon solves a ballistic arc and retries a quarter faster when the first solve fails; every other object solves the arc for its first weapon, which is why Lobber in the second slot does not raise the barrel.

How a burst alternates muzzles

A burst counter runs from zero to one less than the weapon’s Burst and is used by the geometry as well as by the reload: the lateral component of the firing offset is negated whenever the counter is odd, which is what gives a burst weapon a pair of muzzles either side of the centerline. A structure with a voxel barrel does the same thing through its barrel offset instead, centering the third shot and any after it. Those are facts of the two settings; what belongs here is when the counter is read.

The counter advances at step 10 of the sequence above, and the parts of a shot are split either side of that. The projectile, the railgun beam and the attached particle systems are placed with the counter as it stood for this shot; the firing animation, the sonic wave and the laser beam are placed with the counter as it now stands for the next one. On a Burst=2 weapon those are always the two opposite muzzles, so the flash and the beam appear on the far side of the gun from the shell. A structure with a voxel barrel is displaced the other way, because its barrel lookup subtracts one from the counter to compensate: there the animation, wave and beam land correctly and the projectile’s own effects land on the previous shot’s barrel.

Only a weapon whose Burst is above one and whose firing offset has a non-zero lateral component is affected. Everything else places both groups at the same point.

What each part of a shot reads

Several parts of a shot are read from the first slot rather than from the slot that fired, which matters as soon as a beam or wave weapon is put in the second slot. The table gathers where each part is anchored and which slot supplies its settings.

Part of the shot	Anchored at	Read from
The projectile, its damage, warhead and projectile range	The mounting	The firing slot
The report sound and the firing animation	The mounting and the muzzle respectively	The firing slot
The fire and spark particle systems	The muzzle	The firing slot
The railgun beam, its ambient damage, warhead and particle system	The muzzle	The firing slot
The sonic wave’s ambient damage and warhead	The muzzle at creation, then re-anchored each frame to the first slot’s muzzle	The first slot
The laser beam’s colors, spread, duration and glow width	The muzzle	The first slot
The barrel elevation and whether it is lobbed	—	The first slot
The reload delay	—	The firing slot

The two re-anchoring rows are worth reading twice. A sonic wave is created from the muzzle that fired it and then follows the first slot’s muzzle for the rest of its life, so a second-slot sonic weapon on an object whose slots have different offsets sees its wave jump on the frame after it is fired. A UseFireParticles=yes stream behaves the same way; particle systems owns the re-anchoring itself.

Effects that hold the weapon shut

Four effects lock an object out of firing while they are alive: a fire particle stream, a spark particle spray, a railgun particle trace, and a sonic wave. The first three each occupy one of the object’s particle holds; the wave occupies a single slot of its own, so an object can have only one wave in flight.

The lock is applied at three separate places, and the three do not answer alike.

Before the shot is considered at all, the slot that is not firing is examined: a live effect belonging to that slot’s weapon reports the object as unable to fire at this target at all.
The firing slot’s own weapon is examined next, and a live effect there reports the object as still rearming.
The firing routine tests the same four conditions again and returns without creating anything.

The tests ask whether the hold is occupied, not whether this weapon’s own effect is the thing occupying it. That matters for one hold only: sparks from a damaged object and a spark weapon’s spray share theirs, and particle systems records what that costs.

A vehicle carries one further gate that is not about effects at all: FiringSyncFrame1 ties the first round of a burst to the firing animation and FiringSyncFrame2 the second, holding the weapon as rearming until the animation reaches the named frame and then releasing the round without the reload timer being consulted. Only the first slot is tied this way; a shot from the second slot is never held.

The reload delay

The delay before the next shot is chosen by the first of these that applies, so a row further down is reached only when every row above it has been passed over.

The firer and its weapon	Frames until the next shot
A structure with more than one round left	1
The firing slot holds no weapon	1
The weapon is `IsSonic=yes` — whether or not a wave is actually alive — or is a fire, spark or railgun weapon whose matching particle hold is occupied	Exactly `ROF`
The burst is not finished	The matching `BurstDelay0` to `BurstDelay3`, or a random 3 to 5 where that entry is `-1` or the shot is past the fourth
Anything else	`ROF` scaled by the house’s rate-of-fire bias, plus a random 0 to 2, and shortened by the veteran rate-of-fire ability

The third row is the whole reason an effect weapon fires at the pace it does. It skips the bias, the burst gaps and the random padding alike, so the firing rate is decided by ROF and the effect’s own lifetime and by nothing else — and on a structure with a stock of rounds even ROF drops out, because the first row has already answered with a single frame and only the effect’s lifetime is left to pace 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	Punches a damaging line through the world 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.	colour (R,G,B)	`0,0,0`
`LaserOuterColor`WeaponType	The color of the pair of glow lines drawn alongside a laser beam's core.	colour (R,G,B)	`0,0,0`
`LaserOuterSpread`WeaponType	How far each channel of a laser beam's glow may wander from its color, redrawn every frame.	colour (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)	Context-dependent