Fire pipeline
What it is
The fire pipeline is the per-frame, per-weapon sequence that converts a ready weapon into a resolved hit on an enemy. It begins with the cooldown tick that decides whether the weapon is eligible to fire this frame and ends with damage applied to enemies via the shared on-hit path. Every player weapon — auto-aim or manual, projectile or beam, aura or mortar — runs the same pipeline; the differences live in which stage forks at which gate.
The pipeline
The eight stages run in this order, once per weapon, once per frame:
| # | Stage | What happens |
|---|---|---|
| 1 | Cooldown tick | Each weapon’s fire timer decrements by the frame delta toward zero. A weapon is eligible to fire only when its timer reaches zero and is not already mid-warmup |
| 2 | Target acquisition | The auto-aim resolver scans live enemies inside the weapon’s effective range, scores them by the weapon’s target mode (closest / furthest / flanking / high-HP / low-HP), and returns an aim angle to the best candidate — or no target |
| 3 | Pre-fire gate | If the resolver returned no target, the gate checks the behavior carveout list and the always-forward flag (see “Branch points” below). If neither applies, the fire is aborted and the timer holds at zero for the next frame |
| 4 | Warmup | If the weapon has a non-trivial warmup window, the gate begins a warmup state that accumulates over the warmup duration. The aim angle is cached so it survives the target dying mid-warmup. Below the warmup threshold, this stage is a single-frame skip |
| 5 | Fire dispatch | On the frame warmup completes (or immediately, if there was no warmup), the dispatch reads the weapon’s behavior and collision mode and routes to one of the family fire functions: tesla line, shield arc, arc/plasma mortar, orbit (swords), flame stream, cone beam DOT, burst fire, flame drop, orbit ring, beam decay, artillery rain, phoenix aura, carpet bomber, quad-burst, beam trace, chain arc, or the default projectile spawner |
| 6 | Cost & cooldown commit | The dispatch sets the next cooldown to 1 / final fire rate, applies per-shot jitter to the cooldown for weapons that have it, resets the fire timer to the new cooldown, raises the HUD fire-flash marker, and commits damage/range/area numbers computed from the weapon’s level, scaling curve, early-level nerfs, horizontal damage modifiers, and active multipliers |
| 7 | Projectile spawn | The family fire function spawns its hit entities — bullets into the player-bullet array (recycled from the bullet bin), beam traces with an instant line check, hitscan damage applied directly with no entity, arc-mortar barrels that follow a parabolic path, or area zones placed at the ship’s position. Each spawned entity carries the resolved damage, the weapon ID, and the behavior tag chain that controls update, on-hit, and on-death callbacks |
| 8 | On-hit resolution | When a spawned entity overlaps an enemy, the shared collision resolver routes through any behavior on-hit callbacks (chain, redirect, bounce, pierce, ricochet), then applies damage through the shared damage path, records the weapon hit in telemetry, and either consumes the entity or leaves it alive for further hits according to its pierce/lifetime rules |
A subsequent cooldown tick happens the same frame for unfired weapons and the following frame for fired ones, restarting the cycle.
Branch points
The pipeline forks in three places where a weapon might fire without a normal target-found result, and in one place where the fire is aborted entirely.
Behavior carveouts
Inside the shared fire entry point, two gates check the firing weapon’s behavior name and let one specific behavior pass through with no acquired target. The carveout consumer is the orbit-ring legendary cast, which is direction-less and centered on the ship — neither a resolver result nor a ship-facing fallback would be meaningful. Every other weapon stays gated. See concept-behavior-carveouts.
Always-forward fallback
When the resolver returns no target, the bridge applies the no-target fallback before calling the fire entry point. If the weapon’s spec sets the always-forward flag, the aim angle is set to the ship’s current facing and the pipeline proceeds normally. If the flag is unset, the aim angle stays undefined and the pre-fire gate aborts the fire. See concept-always-forward-firing.
Manual-mode override
If the player has switched a weapon slot to manual fire mode, the resolver is skipped entirely. The fire entry point is called only when the player triggers the slot, and the aim angle is computed from ship facing plus the weapon’s spec-defined default offset (zero for a forward-firing weapon, 180° for a rear-firing mine, and so on). Manual-mode triggers do not buffer — if the cooldown is not ready the trigger is silently discarded.
No-target stand-down
Outside of the three exceptions above, a weapon with no acquired target stays dormant. Its cooldown timer holds at zero, no warmup begins, no projectile spawns, no fire event records to telemetry, and no HUD fire flash raises. The weapon will fire on the first frame a valid target appears.
Per-stage references
| Stage | Relevant concept pages |
|---|---|
| Cooldown tick | concept-fire-rate-jitter, concept-horizontal-modifiers |
| Target acquisition | concept-target-modes |
| Pre-fire gate | concept-behavior-carveouts, concept-always-forward-firing |
| Warmup | concept-warmup |
| Fire dispatch | concept-collision-modes, concept-area-modes |
| Cost & cooldown commit | concept-damage-multiplier-curve, concept-scaling-curves, concept-early-level-damage-buff, concept-horizontal-modifiers |
| Projectile spawn | concept-more-projectiles-fan, concept-spread, concept-double-shot, concept-travel-range |
| On-hit resolution | concept-damage-tags, concept-chain-weapons, concept-per-target-contact-cooldown, concept-destructibles-flag |
EXTRACT-CANDIDATES:
- concept-target-modes — already exists; this page now anchors stage 2, so the target-modes page can cross-link back here as the canonical sequence diagram.
- concept-warmup — already exists; the warmup page documents the within-stage behavior, this page documents how warmup nests inside the larger sequence. Add a one-line back-reference here from the warmup page.
- concept-behavior-carveouts — already exists; carveouts are now described as a branch point on this page. The carveouts page’s existing “Pre-warmup gate” / “Pre-spawn gate” table is the granular version of stage 3 here.
- concept-always-forward-firing — already exists; this page formalizes the fallback chain inside stage 3. The always-forward page’s existing fallback table is the granular version.
- concept-manual-fire-mode — possible new page covering the manual-trigger override, default-angle offsets, trigger-discard behavior, and per-slot settings persistence. Currently the manual-mode logic lives only in the bridge integration code and is not documented on any concept page; this fire-pipeline page mentions it as a branch point but cannot fully replace a dedicated page.
- concept-cooldown-commit — possible new page consolidating the final-fire-rate computation (base × horizontal × early-level nerf × jitter) and the cooldown-set-after-fire ordering. Currently those rules are split across the damage-multiplier-curve, horizontal-modifiers, fire-rate-jitter, and warmup pages with no single point that says “the timer is reset on the fire frame, not the start-of-warmup frame”.
- concept-on-hit-resolution — possible new page describing the shared collision-resolver path, the behavior on-hit registry (chain, redirect, bounce, ricochet, pierce), and the telemetry-recording contract. The damage-tags page covers the damage classification but not the resolution sequence.