Behavior carveouts
What it is
A behavior carveout is a fire-path branch keyed off a weapon’s behavior name that lets a weapon skip the standard “no target → stay dormant” gate. Carveouts live inside the shared fire entry point, not on the per-weapon spec, so they can only fire on weapons whose behavior string matches the hard-coded check. They are the rarest of the three ways a weapon can fire without an acquired enemy.
The carveout in code
The shared fire path runs two checks that both early-return when the auto-aim resolver returned no target. Each check tests the firing weapon’s behavior name and only lets a single behavior through.
| Check site | Phase | Carveout behavior | What it does when no target |
|---|---|---|---|
| Pre-warmup gate | Weapon ready, deciding whether to begin warmup | orbit ring | Falls through into warmup with no aim angle |
| Pre-spawn gate | Warmup complete, about to spawn projectiles | orbit ring | Falls through into the behavior dispatch |
Both gates are explicit equality checks: only the literal behavior string “orbit_ring” passes. Every other behavior name returns immediately when no target is present.
How the cast resolves without a target
The orbit ring fire path is the only carveout consumer. When it runs with no target, the dispatcher coerces the missing aim angle to a numeric 0, and the orbit-ring fire function ignores its aim parameter entirely. The ring formation is spawned around the ship origin, not relative to any enemy direction.
Difference from always-forward firing
Both carveouts and the always-forward flag let a weapon fire on cooldown without an acquired target, but they sit at different layers and have different effects on aim.
| Property | Behavior carveout | Always-forward firing |
|---|---|---|
| Where it lives | Hard-coded behavior-name check inside the fire path | Boolean flag on the weapon spec |
| What controls it | Source code | Data table |
| Aim angle when no target | Skipped entirely (orbit ring is player-centered) | Falls back to ship facing |
| Bullet/zone origin | Player position, no direction | Player position, ship facing direction |
| Number of consumers | 1 behavior | 2 weapons |
The always-forward flag is the documented data-driven way for a weapon to fire on timer without a target. The behavior carveout exists because the orbit ring cast is player-centered and direction-less — neither the resolver result nor a ship-facing fallback is meaningful for it.
Which weapons use the carveout
| Weapon | Behavior | Cast shape | Why a carveout instead of the always-forward flag |
|---|---|---|---|
| Star Halo | orbit ring | Ring of stars formed around the ship, rigid-body spin, then explode | The cast is direction-less; ship facing as fallback would still be a meaningless aim angle |
No other behavior currently has a carveout. The phoenix aura behavior (Phoenix legendary) reaches the behavior dispatch through the same path as every non-carveout weapon, which means it requires an auto-aim target to fire — it is not a carveout despite reading as an always-on aura.
EXTRACT-CANDIDATES:
- concept-warmup — already exists; the orbit-ring carveout falls through warmup with a deferred aim angle that the carveout overrides on completion, an edge case worth documenting on the warmup page.
- concept-fire-pipeline — possible new page that lays out the full fire-event sequence (cooldown tick → resolver call → gate → warmup → dispatch → spawn) so carveouts, always-forward, and warmup all have a shared diagram to point at.