shrike/weapons.py

Part of SHRIKE.

"""Hardpoints, the ten-weapon roster, and everything they put in the air.

The roster splits down the game's two economies and the split is structural
rather than cosmetic. :class:`EnergyWeapon` spends the capacitor through the
``PowerSystem`` service and never looks at a magazine; :class:`BallisticWeapon`
spends rounds from a per-weapon magazine fed by ammo boxes and never touches
the capacitor; :class:`GravHook` spends neither, because it deals no damage and
exists to move things.

Firing model
============

Every weapon reads three data sources and nothing else:

* ``balance.WEAPONS[weapon_id]`` for family, sustained DPS and, where the
  design has fixed it, the energy cost.
* :data:`FIRE_PROFILES` for the cadence, reach and shot shape, which are feel
  numbers rather than balance numbers.
* the live services, ``Services.POWER`` for energy and ``Services.DAMAGE`` for
  every damage number that leaves this module.

Per-projectile damage is always derived, never typed: a weapon that fires
``pellets`` shots at ``rate`` per second deals ``spec.dps / (rate * pellets)``
per pellet, so sustained fire into a single target delivers exactly the
roster's DPS. Beams deal ``spec.dps * dt`` per tick for the same reason.

Hit resolution happens in flight-plane geometry: a projectile sweeps the
segment it covers this step against the hostile groups, so a fast round cannot
step over a target between frames. Projectiles are still real
:class:`~simvx.core.Area3D` sensors on ``Layers.PLAYER_FIRE`` carrying the
collision contract, which is how terrain stops them and how anything watching
for player fire sees them. Damage itself is never applied here: it is handed to
``DamageRouter.deal``, which owns shield coverage, the ballistic premium and
elite modifiers.

The fit
=======

A mounted weapon is geometry on the hull, not only a transform: every one
builds a breech and a barrel sized by its family, so swapping a pulse blaster
for a rail lance changes the ship the player is looking at. :func:`weapon_summary`
is the one mechanical line a shop or a fit panel prints for a weapon, derived
from ``balance.WEAPONS`` and :data:`FIRE_PROFILES`; :meth:`WeaponRack.swap_in`
is how a fit is changed, returning the id it displaced so the caller that owns
the stowage can bank it.
"""

import math
from dataclasses import dataclass

from simvx.core import (
    Area3D,
    Input,
    Material,
    Mesh,
    MeshInstance3D,
    Node,
    Node3D,
    Quat,
    Signal,
    SphereShape3D,
    Vec3,
)

from . import balance
from .runtime import PLANE_Y, Groups, Layers, Services

try:  # The contact sparks come from the effect pool when the art layer is in.
    from . import vfx
except ImportError:  # pragma: no cover - the art layer is optional here
    vfx = None

# ============================================================================
# Numbers this module owns
#
# Everything here is a cadence, a reach or a shot shape: feel numbers that
# balance.py does not fix. The DPS, the energy costs and the magazine sizes all
# come from balance.py and are never restated.
# ============================================================================

#: Group the weapon rack joins so other systems reach it without walking the
#: tree by node name.
WEAPON_RACK_GROUP = "weapon_rack"

#: Plane offsets of the four hardpoints from the hull centre, ``(x, z)``.
#: The outboard pair is fitted first, the forward pair as the hull grows.
HARDPOINT_OFFSETS = ((-0.85, 0.15), (0.85, 0.15), (-1.45, -0.55), (1.45, -0.55))

#: Radius assumed for a target that publishes no hitbox radius.
DEFAULT_TARGET_RADIUS = 1.0
#: Radius one member of a swarm occupies, for shoals that publish array rows
#: rather than a body per member.
SWARM_MEMBER_RADIUS = 0.6
#: Radius of a projectile's own body, added to the target radius when sweeping.
PROJECTILE_RADIUS = 0.35
#: Seconds a magazine swap locks a ballistic weapon out for.
RELOAD_S = 1.2
#: Per-shot energy for the two energy weapons balance.py leaves unset, plus the
#: grav hook. A weapon whose ``WeaponSpec`` carries a cost uses that instead.
PROVISIONAL_ENERGY_PER_SHOT = {"scatter_coil": 4.0, "nova_mortar": 12.0, "grav_hook": 6.0}

#: Speed and duration of a grav hook yank.
GRAV_HOOK_PULL_SPEED = 26.0
GRAV_HOOK_PULL_S = 0.8

#: Player fire is warm gold and white; enemy fire is cold magenta. The palette
#: is the readability contract, so projectile materials live at one site.
PROJECTILE_COLOUR = (1.0, 0.82, 0.42, 1.0)
BEAM_COLOUR = (1.0, 0.93, 0.72, 1.0)
BEAM_RADIUS = 0.09
#: How long a hitscan shot leaves its tracer line on screen.
HITSCAN_TRACER_S = 0.06

# -- A beam that says whether it is working ----------------------------------
#
# The mining laser used to draw the same full-length bar of light whether it
# was cutting a vein or crossing empty space, so the only way to find out
# whether the beam was on anything was to watch a scrap counter that ticks
# twice a second. A blind pilot swept the beam across a whole sector without
# ever learning what it was for. The beam now ends where it bites, marks the
# bite, and thins out when it bites nothing.

#: Beam colour while it is cutting nothing: the same hue drained of saturation
#: and heat, so a miss reads as a spent aiming line rather than as work.
BEAM_MISS_COLOUR = (0.62, 0.62, 0.62, 1.0)
#: Emissive strength of the beam core, on a surface and in vacuum.
BEAM_EMISSIVE_HIT = 4.0
BEAM_EMISSIVE_MISS = 0.9
#: Cross-section of a beam that is cutting nothing, as a fraction of full bore.
BEAM_MISS_WIDTH = 0.4
#: Reach of a beam with nothing in front of it, as a fraction of the profile's
#: own reach. A miss stops short of the range ring as well as thinning: the
#: pilot sees the beam fail to arrive at what they were pointing at.
BEAM_MISS_REACH_FRACTION = 0.7
#: The bead of light burning on whatever the beam has found, as a multiple of
#: the beam's own radius: the highlight that says which of two veins in line
#: with the muzzle is the one being cut.
BEAM_SPOT_RADIUS_MULT = 3.4
#: Seconds between the chip bursts a working beam throws off its contact point.
BEAM_SPARK_INTERVAL_S = 0.12
#: How far past a mineable surface's own radius the beam still counts as being
#: on it. Aiming is done with a mouse at a rock the camera draws small, and a
#: beam that has to pass through the exact centre of a vein is a beam that
#: usually pays nothing. Combat reach is deliberately not padded this way.
BEAM_CONTACT_PADDING = 1.0

#: Weapons that answer the utility trigger (``mining_beam``) rather than
#: ``fire_primary``.
TRIGGER_MINING = frozenset({"mining_laser", "grav_hook"})

PRIMARY_ACTION = "fire_primary"
MINING_ACTION = "mining_beam"

#: What the utility trigger is called on a shelf row. A pilot who buys a mining
#: laser and holds the fire button gets nothing, so the row has to name the key.
#: The primary trigger is unremarked, being what every other weapon answers.
TRIGGER_LABELS = {MINING_ACTION: "utility trigger"}

#: The mount a weapon puts on the hull, so a hardpoint reads as fitted.
#: Barrel dimensions are metres along the hull's local -Z, which is the nose.
MOUNT_BARREL_LENGTH = {"energy": 0.62, "ballistic": 0.95, "utility": 0.42}
MOUNT_BARREL_RADIUS = {"energy": 0.075, "ballistic": 0.11, "utility": 0.14}
#: The receiver block behind the barrel, shared by every family.
MOUNT_BREECH_SIZE = 0.22
#: Gunmetal for the barrel; the muzzle carries the family's own warm accent so
#: two different guns on two hardpoints are told apart at a glance.
MOUNT_METAL_COLOUR = (0.30, 0.31, 0.34, 1.0)
MOUNT_ACCENT_COLOURS = {
    "energy": (0.55, 0.85, 1.0, 1.0),
    "ballistic": (1.0, 0.72, 0.34, 1.0),
    "utility": (0.72, 0.55, 0.95, 1.0),
}
#: Below the bloom threshold: a muzzle marks the gun, it does not light the sky.
MOUNT_ACCENT_STRENGTH = 0.9


@dataclass(frozen=True)
class FireProfile:
    """How one weapon puts its damage into the world.

    ``rate`` is trigger pulls per second and is ignored by beams, which are
    continuous. ``speed`` of zero means hitscan. ``pellets`` shots leave the
    muzzle per pull, fanned evenly across ``spread`` radians either side of the
    aim line, and each carries an equal share of the weapon's DPS.
    """

    rate: float
    reach: float
    speed: float = 0.0
    pellets: int = 1
    spread: float = 0.0
    pierce: int = 0
    blast: float = 0.0
    homing_rate: float = 0.0
    beam: bool = False
    mines: bool = False
    rounds_per_shot: int = 1


#: One profile per roster entry; the keys match ``balance.WEAPONS`` exactly.
FIRE_PROFILES: dict[str, FireProfile] = {
    "pulse_blaster": FireProfile(rate=5.0, reach=60.0, speed=90.0),
    "scatter_coil": FireProfile(rate=2.0, reach=22.0, speed=70.0, pellets=8, spread=0.30),
    "arc_beam": FireProfile(rate=0.0, reach=40.0, beam=True),
    "mining_laser": FireProfile(rate=0.0, reach=26.0, beam=True, mines=True),
    "nova_mortar": FireProfile(rate=0.8, reach=55.0, speed=40.0, blast=9.0),
    "rail_lance": FireProfile(rate=1.5, reach=90.0, pierce=3),
    "flak_cannon": FireProfile(rate=2.5, reach=34.0, speed=65.0, pellets=6, spread=0.26, blast=2.6),
    "autocannon": FireProfile(rate=8.0, reach=55.0, speed=110.0),
    "missile_rack": FireProfile(
        rate=1.0, reach=70.0, speed=55.0, pellets=2, spread=0.05, blast=5.0, homing_rate=3.0, rounds_per_shot=2
    ),
    "grav_hook": FireProfile(rate=0.5, reach=45.0),
}


# ============================================================================
# Saying what a weapon does
#
# A shelf row that says "40 DPS ballistic" has priced a word. What a pilot has
# to decide is whether the gun feeds off the capacitor they are already
# spending on the shield or off boxes they have to keep buying, and which
# trigger it answers. Those are the three facts below, and they come off
# balance.py and this module's own profiles rather than off prose.
# ============================================================================


def trigger_action_for(weapon_id: str) -> str:
    """The input action *weapon_id* answers, without mounting one to ask."""
    return MINING_ACTION if weapon_id in TRIGGER_MINING else PRIMARY_ACTION


def feed_line(weapon_id: str) -> str:
    """What the weapon costs to fire, in the units the pilot's meters use.

    Ballistic weapons quote the box because a box is the thing that runs out;
    energy weapons quote the capacitor draw, per shot or per second as the
    weapon spends it.
    """
    spec = balance.WEAPONS[weapon_id]
    profile = FIRE_PROFILES[weapon_id]
    if spec.family == "ballistic":
        rounds = int(spec.rounds_per_box or 0)
        per_shot = f", {profile.rounds_per_shot} a shot" if profile.rounds_per_shot > 1 else ""
        return f"uses ammo, {rounds} a box{per_shot}"
    per_second = spec.energy_per_s if spec.energy_per_s is not None else None
    if per_second is not None:
        return f"drains {per_second:.0f} energy/s"
    per_shot_cost = spec.energy_per_shot
    if per_shot_cost is None:
        per_shot_cost = PROVISIONAL_ENERGY_PER_SHOT.get(weapon_id, 0.0)
    if per_shot_cost <= 0.0:
        return "costs nothing to fire"
    return f"{per_shot_cost:.0f} energy a shot"


def weapon_summary(weapon_id: str) -> str:
    """DPS, feed and trigger on one line, for a shelf row or a fit panel."""
    spec = balance.WEAPONS[weapon_id]
    head = f"{spec.dps:.0f} DPS" if spec.dps > 0.0 else "no damage"
    parts = [head, feed_line(weapon_id), TRIGGER_LABELS.get(trigger_action_for(weapon_id), "")]
    if spec.note:
        parts.append(spec.note)
    return ", ".join(part for part in parts if part)


# ============================================================================
# Flight-plane geometry
# ============================================================================


def _plane_of(node: Node3D) -> tuple[float, float]:
    """A node's world position as flight-plane ``(x, z)`` floats."""
    p = node.world_position
    return float(p[0]), float(p[2])


def _normalise(x: float, z: float) -> tuple[float, float]:
    """Unit vector on the plane; a zero vector becomes +X."""
    length = math.hypot(x, z)
    if length < 1e-9:
        return 1.0, 0.0
    return x / length, z / length


def _rotate(x: float, z: float, angle: float) -> tuple[float, float]:
    """Rotate a plane vector by *angle* radians."""
    c, s = math.cos(angle), math.sin(angle)
    return x * c - z * s, x * s + z * c


def _is_swarm(node: Node3D) -> bool:
    """Whether *node* is a swarm whose members are array rows, not bodies.

    A shoal publishes ``live_positions`` and takes damage through
    ``damage_at`` at a world point, because no individual member has a hitbox
    of its own to sweep against.
    """
    return getattr(node, "HITBOX_RADIUS", DEFAULT_TARGET_RADIUS) is None and hasattr(node, "damage_at")


def _target_radius(node: Node3D) -> float:
    """Collision radius a shot must reach to count as a hit on *node*."""
    hitbox = getattr(node, "HITBOX_RADIUS", None)
    if hitbox is not None:
        return float(hitbox)
    if _is_swarm(node):
        return SWARM_MEMBER_RADIUS
    return float(getattr(node, "hit_radius", DEFAULT_TARGET_RADIUS))


def _swarm_members(node: Node3D) -> list[tuple[float, float]]:
    """Plane positions of a swarm's live members."""
    rows = getattr(node, "live_positions", None)
    if rows is None:
        return []
    return [(float(row[0]), float(row[2])) for row in rows]


def _segment_circle_distance(
    origin: tuple[float, float],
    direction: tuple[float, float],
    length: float,
    centre: tuple[float, float],
    radius: float,
) -> float | None:
    """Distance along a unit-direction segment at which it first enters a circle.

    Returns ``None`` when the segment misses. A segment starting inside the
    circle reports 0.0, so a shot spawned on top of a target still connects.
    """
    fx, fz = origin[0] - centre[0], origin[1] - centre[1]
    b = fx * direction[0] + fz * direction[1]
    c = fx * fx + fz * fz - radius * radius
    if c <= 0.0:
        return 0.0
    discriminant = b * b - c
    if discriminant < 0.0:
        return None
    entry = -b - math.sqrt(discriminant)
    if 0.0 <= entry <= length:
        return entry
    return None


def _group_nodes(tree, *groups: str) -> list[Node3D]:
    """Live ``Node3D`` members of the given groups, skipping anything expiring."""
    out: list[Node3D] = []
    if tree is None:
        return out
    for group in groups:
        for node in tree.group(group):
            if isinstance(node, Node3D) and not node.destroying:
                out.append(node)
    return out


def _sweep(
    tree,
    origin: tuple[float, float],
    direction: tuple[float, float],
    length: float,
    padding: float,
    *groups: str,
) -> list[tuple[float, Node3D, tuple[float, float]]]:
    """Every group member the segment crosses, nearest first.

    Each hit is ``(distance, node, centre)``. *centre* is the plane centre of
    the body that was actually struck, which for a swarm is the member's own
    position rather than the shoal node's: a shoal is tested against each of
    its live members, so it reports the distance at which the segment reaches
    its nearest mite, and the damage that follows has to land on that mite
    rather than on the shoal's centre of mass.
    """
    hits: list[tuple[float, Node3D, tuple[float, float]]] = []
    for node in _group_nodes(tree, *groups):
        radius = _target_radius(node) + padding
        if _is_swarm(node):
            reached = [
                (distance, member)
                for distance, member in (
                    (_segment_circle_distance(origin, direction, length, member, radius), member)
                    for member in _swarm_members(node)
                )
                if distance is not None
            ]
            if not reached:
                continue
            distance, centre = min(reached, key=lambda pair: pair[0])
        else:
            centre = _plane_of(node)
            distance = _segment_circle_distance(origin, direction, length, centre, radius)
            if distance is None:
                continue
        hits.append((distance, node, centre))
    hits.sort(key=lambda hit: hit[0])
    return hits


def _hostiles(tree) -> list[Node3D]:
    """Everything player fire is allowed to damage."""
    return _group_nodes(tree, Groups.ENEMIES, Groups.HUNTER)


def _deal(
    tree,
    target: Node3D,
    amount: float,
    kind: str,
    direction: tuple[float, float],
    at: tuple[float, float] | None = None,
    splash: float = 0.0,
) -> None:
    """Hand a damage number to the router, the only code that applies one.

    A swarm is the one exception, and it is an interface gap rather than a
    choice: ``DamageRouter.deal`` takes a node, and a shoal's members are array
    rows at their own positions, so damage that landed at a point is applied
    through the shoal's own ``damage_at`` instead. *at* is therefore the struck
    member's own centre, not the point on its surface the round touched: the
    sweep pads a target's radius by the projectile's, and a burst centred on
    that padded surface would fall entirely outside the member it just hit.
    """
    if at is not None and _is_swarm(target):
        target.damage_at(Vec3(at[0], PLANE_Y, at[1]), max(splash, _target_radius(target)), amount, kind)
        return
    router = tree.singletons.get(Services.DAMAGE) if tree is not None else None
    if router is None:
        return
    router.deal(target, amount, kind=kind, direction=Vec3(direction[0], 0.0, direction[1]))


# ============================================================================
# Projectiles
# ============================================================================


class Projectile(Area3D):
    """One round in flight on the plane.

    The sensor body carries the ``Layers.PLAYER_FIRE`` contract so terrain and
    anything else watching player fire sees the round; damage is resolved by
    sweeping the segment travelled this step, which is what stops a fast round
    from stepping over a small target between frames.
    """

    def __init__(
        self,
        *,
        weapon_id: str,
        kind: str,
        damage: float,
        direction: tuple[float, float],
        speed: float,
        reach: float,
        pierce: int = 0,
        blast: float = 0.0,
        homing_rate: float = 0.0,
        **kwargs,
    ):
        kwargs.setdefault("shape", SphereShape3D(radius=PROJECTILE_RADIUS))
        super().__init__(**kwargs)
        self.collision_layer = Layers.PLAYER_FIRE
        self.collision_mask = Layers.MASK_PLAYER_FIRE
        self.weapon_id = weapon_id
        self.kind = kind
        self.damage = float(damage)
        self.speed = float(speed)
        self.reach = float(reach)
        self.pierce = int(pierce)
        self.blast = float(blast)
        self.homing_rate = float(homing_rate)
        self._direction = _normalise(direction[0], direction[1])
        self._travelled = 0.0
        self._struck: set[int] = set()

    def on_enter_tree(self):
        super().on_enter_tree()
        self.add_to_group(Groups.PLAYER_PROJECTILES)

    def on_ready(self):
        tracer = Material(colour=PROJECTILE_COLOUR, emissive_colour=PROJECTILE_COLOUR[:3], emissive_strength=3.0)
        self.add_child(
            MeshInstance3D(
                name="Tracer",
                mesh=Mesh.sphere(radius=PROJECTILE_RADIUS, rings=6, segments=8),
                material=tracer,
            )
        )
        self.body_entered.connect(self._on_body_entered)

    def on_fixed_update(self, dt: float):
        if self.destroying:
            return
        if self.homing_rate > 0.0:
            self._steer(dt)
        step = min(self.speed * dt, self.reach - self._travelled)
        if step <= 0.0:
            self._expire(detonate=False)
            return
        origin = _plane_of(self)
        if self._resolve(origin, step):
            return
        self.position = Vec3(
            origin[0] + self._direction[0] * step,
            PLANE_Y,
            origin[1] + self._direction[1] * step,
        )
        self._travelled += step

    def _steer(self, dt: float):
        """Turn toward the nearest hostile, limited by the homing rate."""
        here = _plane_of(self)
        nearest = None
        best = float("inf")
        for node in _hostiles(self.tree):
            tx, tz = _plane_of(node)
            distance = math.hypot(tx - here[0], tz - here[1])
            if distance < best:
                best, nearest = distance, node
        if nearest is None:
            return
        tx, tz = _plane_of(nearest)
        wanted = _normalise(tx - here[0], tz - here[1])
        cross = self._direction[0] * wanted[1] - self._direction[1] * wanted[0]
        dot = max(-1.0, min(1.0, self._direction[0] * wanted[0] + self._direction[1] * wanted[1]))
        turn = max(-self.homing_rate * dt, min(self.homing_rate * dt, math.acos(dot) * (1.0 if cross >= 0.0 else -1.0)))
        self._direction = _normalise(*_rotate(self._direction[0], self._direction[1], turn))

    def _resolve(self, origin: tuple[float, float], step: float) -> bool:
        """Damage everything the step crosses. True when the round is spent."""
        for distance, target, centre in _sweep(
            self.tree, origin, self._direction, step, PROJECTILE_RADIUS, Groups.ENEMIES, Groups.HUNTER
        ):
            if id(target) in self._struck:
                continue
            self._struck.add(id(target))
            _deal(self.tree, target, self.damage, self.kind, self._direction, at=centre, splash=self.blast)
            if self.pierce <= 0:
                self.position = Vec3(
                    origin[0] + self._direction[0] * distance,
                    PLANE_Y,
                    origin[1] + self._direction[1] * distance,
                )
                self._expire(detonate=True)
                return True
            self.pierce -= 1
        return False

    def _on_body_entered(self, other):
        """Terrain stops a round where it hits, blast and all."""
        if int(getattr(other, "collision_layer", 0)) & Layers.TERRAIN:
            self._expire(detonate=True)

    def _expire(self, *, detonate: bool):
        if self.destroying:
            return
        if detonate and self.blast > 0.0:
            self._detonate()
        self.remove_from_group(Groups.PLAYER_PROJECTILES)
        self.destroy()

    def _detonate(self):
        """Splash damage on everything in the blast that the round did not hit.

        A shoal caught by the blast takes it across the whole radius in one
        call, which is the burst clearing several rows at once.
        """
        centre = _plane_of(self)
        for target in _hostiles(self.tree):
            if id(target) in self._struck:
                continue
            if _is_swarm(target):
                _deal(self.tree, target, self.damage, self.kind, self._direction, at=centre, splash=self.blast)
                continue
            tx, tz = _plane_of(target)
            if math.hypot(tx - centre[0], tz - centre[1]) <= self.blast + _target_radius(target):
                _deal(self.tree, target, self.damage, self.kind, self._direction)


# ============================================================================
# Weapons
# ============================================================================


class Weapon(Node3D):
    """One mounted weapon: cadence, cost and the shape of what it fires.

    A weapon is inert until something drives it. :meth:`set_trigger` holds the
    trigger down (the rack does this from the input actions every frame) and
    :meth:`try_fire` demands a shot right now, returning whether one left the
    muzzle. Beams report whether they are currently burning.
    """

    def __init__(self, weapon_id: str, **kwargs):
        if weapon_id not in balance.WEAPONS:
            raise ValueError(f"unknown weapon id {weapon_id!r}")
        kwargs.setdefault("name", weapon_id)
        super().__init__(**kwargs)
        self.weapon_id = weapon_id
        self.spec = balance.WEAPONS[weapon_id]
        self.profile = FIRE_PROFILES[weapon_id]
        self.rack: WeaponRack | None = None
        self._trigger = False
        self._cooldown = 0.0
        self._aim_point = Vec3(0.0, PLANE_Y, 0.0)
        self._beam_active = False
        self._beam: Node3D | None = None
        self._beam_mesh: MeshInstance3D | None = None
        self._beam_spot: MeshInstance3D | None = None
        self._beam_hit = False
        self._beam_length = 0.0
        self._spark_wait = 0.0
        self._tracer_left = 0.0
        self._hacking: set[int] = set()

    # -- the mount --------------------------------------------------------

    def on_ready(self):
        self.add_child(self._build_mount())

    def _build_mount(self) -> Node3D:
        """The gun as it sits on the hull: a breech block and a barrel.

        Without this a hardpoint is an empty transform, so buying a weapon
        changes the ship's fire and nothing about the ship, and a pilot has no
        way to see which hardpoint carries what. The barrel runs along local
        -Z, which is the hull's nose, and its length and bore come off the
        family, so a rail lance and a pulse blaster are told apart in
        silhouette. Geometry from engine primitives, as the beam and the tracer
        already are; ``artkit`` would be the tidier home for it once it grows a
        player-weapon builder.
        """
        family = self.spec.family
        length = MOUNT_BARREL_LENGTH[family]
        radius = MOUNT_BARREL_RADIUS[family]
        mount = Node3D(name="Mount")
        mount.add_child(
            MeshInstance3D(
                name="Breech",
                mesh=Mesh.cube(size=MOUNT_BREECH_SIZE),
                material=Material(colour=MOUNT_METAL_COLOUR, metallic=0.8, roughness=0.45),
            )
        )
        mount.add_child(
            MeshInstance3D(
                name="Barrel",
                mesh=Mesh.cylinder(radius=radius, height=length, segments=10),
                material=Material(colour=MOUNT_METAL_COLOUR, metallic=0.85, roughness=0.35),
                rotation=Quat.from_euler(math.radians(90.0), 0.0, 0.0),
                position=Vec3(0.0, 0.0, -length * 0.5),
            )
        )
        accent = MOUNT_ACCENT_COLOURS[family]
        mount.add_child(
            MeshInstance3D(
                name="Muzzle",
                mesh=Mesh.sphere(radius=radius * 1.25, rings=6, segments=8),
                material=Material(colour=accent, emissive_colour=accent[:3], emissive_strength=MOUNT_ACCENT_STRENGTH),
                position=Vec3(0.0, 0.0, -length),
            )
        )
        return mount

    # -- description ------------------------------------------------------

    @property
    def trigger_action(self) -> str:
        """The input action this weapon answers."""
        return MINING_ACTION if self.weapon_id in TRIGGER_MINING else PRIMARY_ACTION

    @property
    def damage_per_projectile(self) -> float:
        """DPS divided evenly across a second's worth of pellets."""
        shots_per_second = self.profile.rate * self.profile.pellets
        if self.profile.beam or shots_per_second <= 0.0:
            return 0.0
        return self.spec.dps / shots_per_second

    @property
    def beam_active(self) -> bool:
        """Whether a beam weapon is burning right now."""
        return self._beam_active

    # -- driving ----------------------------------------------------------

    def set_trigger(self, held: bool) -> None:
        """Hold or release the trigger; beams and automatics keep going."""
        self._trigger = bool(held)

    def set_aim(self, world_point: Vec3) -> None:
        """The flight-plane point every shot converges on."""
        self._aim_point = Vec3(world_point)

    def try_fire(self, aim_point: Vec3) -> bool:
        """Fire one shot at *aim_point* if the weapon is ready and can pay.

        Beams engage instead of firing a shot and report whether they burn.
        """
        self.set_aim(aim_point)
        if self.profile.beam:
            self._trigger = True
            return self._beam_active
        if self._cooldown > 0.0 or not self._pay_for_shot():
            return False
        self._cooldown = 1.0 / self.profile.rate
        self._discharge()
        self._announce_fired()
        return True

    def on_update(self, dt: float):
        self._cooldown = max(0.0, self._cooldown - dt)
        if self.profile.beam:
            self._tick_beam(dt)
            return
        if self._trigger:
            self.try_fire(self._aim_point)
        if self._tracer_left > 0.0:
            self._tracer_left -= dt
            if self._tracer_left <= 0.0 and self._beam is not None:
                self._beam.visible = False
                self._beam_hit = False

    # -- payment (overridden by the two economies) ------------------------

    def _pay_for_shot(self) -> bool:
        return True

    def _pay_for_beam(self, dt: float) -> bool:
        return True

    def _power(self):
        return self.tree.singletons.get(Services.POWER) if self.tree is not None else None

    def _free_fire(self) -> bool:
        return bool(self.rack is not None and self.rack.free_fire)

    # -- discharge --------------------------------------------------------

    def _aim_direction(self) -> tuple[float, float]:
        muzzle = _plane_of(self)
        aim = self._aim_point
        return _normalise(float(aim[0]) - muzzle[0], float(aim[2]) - muzzle[1])

    def _discharge(self) -> None:
        """Put one trigger pull's worth of shots into the world."""
        base = self._aim_direction()
        pellets = self.profile.pellets
        for index in range(pellets):
            offset = 0.0
            if pellets > 1 and self.profile.spread > 0.0:
                offset = self.profile.spread * (2.0 * index / (pellets - 1) - 1.0)
            direction = _rotate(base[0], base[1], offset)
            if self.profile.speed <= 0.0:
                self._hitscan(direction)
            else:
                self._spawn_projectile(direction)

    def _hitscan(self, direction: tuple[float, float]) -> None:
        """Resolve an instant shot and leave a tracer along the line it took."""
        origin = _plane_of(self)
        allowed = self.profile.pierce + 1
        reach = self.profile.reach
        hit = False
        for distance, target, centre in _sweep(
            self.tree, origin, direction, self.profile.reach, 0.0, Groups.ENEMIES, Groups.HUNTER
        ):
            _deal(self.tree, target, self.damage_per_projectile, self.spec.family, direction, at=centre)
            reach, hit = distance, True
            allowed -= 1
            if allowed <= 0:
                break
        self._show_beam(direction, reach, hit=hit, full_bore=True)
        self._tracer_left = HITSCAN_TRACER_S

    def _spawn_projectile(self, direction: tuple[float, float]) -> None:
        if self.tree is None or self.tree.root is None:
            return
        muzzle = _plane_of(self)
        self.tree.root.add_child(
            Projectile(
                name=f"{self.weapon_id}_round",
                weapon_id=self.weapon_id,
                kind=self.spec.family,
                damage=self.damage_per_projectile,
                direction=direction,
                speed=self.profile.speed,
                reach=self.profile.reach,
                pierce=self.profile.pierce,
                blast=self.profile.blast,
                homing_rate=self.profile.homing_rate,
                position=Vec3(muzzle[0], PLANE_Y, muzzle[1]),
            )
        )

    # -- beams ------------------------------------------------------------

    def _tick_beam(self, dt: float) -> None:
        if not self._trigger or not self._pay_for_beam(dt):
            self._end_beam()
            return
        if not self._beam_active:
            self._beam_active = True
            self._announce_fired()
        self._beam_damage(dt)

    def _beam_damage(self, dt: float) -> None:
        origin = _plane_of(self)
        direction = self._aim_direction()
        reach = self.profile.reach
        hit = False
        struck = _sweep(self.tree, origin, direction, reach, 0.0, Groups.ENEMIES, Groups.HUNTER)
        if struck:
            distance, target, centre = struck[0]
            reach, hit = min(reach, distance), True
            _deal(self.tree, target, self.spec.dps * dt, self.spec.family, direction, at=centre)
        if self.profile.mines:
            mined = self._mine(origin, direction, dt)
            hit = hit or mined < self.profile.reach
            reach = min(reach, mined)
        if not hit:
            reach = self.profile.reach * BEAM_MISS_REACH_FRACTION
        self._show_beam(direction, reach, hit=hit)
        self._tick_sparks(dt, origin, direction, reach, hit)

    def _mine(self, origin: tuple[float, float], direction: tuple[float, float], dt: float) -> float:
        """Work the beam against the surfaces it can reach; returns the reach used.

        Deposits take the mining multiplier rather than the raw beam DPS, and a
        vault held in the beam starts its hack channel once. A wreck's hull is
        neither, but it is solid: the beam stops on it rather than passing
        through, because a beam that draws straight through a hulk is telling
        the pilot the hulk is not there.
        """
        reach = self.profile.reach
        padding = BEAM_CONTACT_PADDING
        deposits = _sweep(self.tree, origin, direction, reach, padding, Groups.DEPOSITS)
        if deposits:
            distance, deposit, _centre = deposits[0]
            reach = min(reach, distance)
            deposit.mine(self.spec.dps * balance.MINING_LASER_DEPOSIT_MULT, dt)
        vaults = _sweep(self.tree, origin, direction, reach, padding, Groups.VAULTS)
        if vaults:
            distance, vault, _centre = vaults[0]
            reach = min(reach, distance)
            if id(vault) not in self._hacking:
                self._hacking.add(id(vault))
                vault.begin_hack()
        wrecks = _sweep(self.tree, origin, direction, reach, padding, Groups.WRECKS)
        if wrecks:
            reach = min(reach, wrecks[0][0])
        return reach

    @property
    def beam_on_target(self) -> bool:
        """Whether the beam currently drawn is standing on a surface."""
        return self._beam_hit

    @property
    def beam_reach(self) -> float:
        """How far the beam currently drawn actually travels, world units."""
        return self._beam_length

    def _tick_sparks(
        self,
        dt: float,
        origin: tuple[float, float],
        direction: tuple[float, float],
        reach: float,
        hit: bool,
    ) -> None:
        """Throw chips off the contact point while the beam is biting something.

        A beam in vacuum throws none, so the sparks and their absence are the
        same message read twice: the pilot who cannot tell a thinner beam from a
        fatter one can still tell a shower from an empty line.
        """
        if not hit or vfx is None or self.tree is None:
            self._spark_wait = 0.0
            return
        self._spark_wait -= dt
        if self._spark_wait > 0.0:
            return
        self._spark_wait = BEAM_SPARK_INTERVAL_S
        contact = Vec3(origin[0] + direction[0] * reach, PLANE_Y, origin[1] + direction[1] * reach)
        vfx.Vfx.spawn(self.tree, "beam_spark", contact, direction=Vec3(-direction[0], 0.0, -direction[1]))

    def _show_beam(
        self,
        direction: tuple[float, float],
        length: float,
        *,
        hit: bool = True,
        full_bore: bool | None = None,
    ) -> None:
        """Draw the beam out to *length*, saying whether it found anything.

        A held beam that ends on a surface is at full bore, warm, and capped
        with a bead of light on the thing it is cutting; one that ends in vacuum
        is thin and grey. The two must not be told apart by the scrap counter
        alone.

        *full_bore* separates the two questions for the tracer a hitscan round
        leaves behind, which is a slug's own trace rather than a beam standing
        on something: it is drawn hot whether or not the slug connected, and
        only the bead answers to *hit*.
        """
        if self._beam is None:
            self._build_beam()
        hot = hit if full_bore is None else bool(full_bore)
        self._beam.visible = True
        self._beam.face_along(Vec3(direction[0], 0.0, direction[1]))
        width = 1.0 if hot else BEAM_MISS_WIDTH
        self._beam_mesh.position = Vec3(0.0, 0.0, -length * 0.5)
        self._beam_mesh.scale = Vec3(width, max(length, 1e-3), width)
        material = self._beam_mesh.material
        colour = BEAM_COLOUR if hot else BEAM_MISS_COLOUR
        material.colour = colour
        material.emissive_colour = colour[:3]
        material.emissive_strength = BEAM_EMISSIVE_HIT if hot else BEAM_EMISSIVE_MISS
        self._beam_spot.position = Vec3(0.0, 0.0, -length)
        self._beam_spot.visible = hit
        self._beam_hit = hit
        self._beam_length = float(length)

    def _build_beam(self) -> None:
        self._beam = self.add_child(Node3D(name="Beam"))
        self._beam_mesh = self._beam.add_child(
            MeshInstance3D(
                name="Core",
                mesh=Mesh.cylinder(radius=BEAM_RADIUS, height=1.0, segments=8),
                material=Material(
                    colour=BEAM_COLOUR,
                    emissive_colour=BEAM_COLOUR[:3],
                    emissive_strength=BEAM_EMISSIVE_HIT,
                ),
                rotation=Quat.from_euler(math.radians(90.0), 0.0, 0.0),
            )
        )
        self._beam_spot = self._beam.add_child(
            MeshInstance3D(
                name="Contact",
                mesh=Mesh.sphere(radius=BEAM_RADIUS * BEAM_SPOT_RADIUS_MULT, rings=6, segments=10),
                material=Material(
                    colour=BEAM_COLOUR,
                    emissive_colour=BEAM_COLOUR[:3],
                    emissive_strength=BEAM_EMISSIVE_HIT,
                ),
            )
        )
        self._beam_spot.visible = False

    def _end_beam(self) -> None:
        self._beam_active = False
        self._beam_hit = False
        self._spark_wait = 0.0
        self._hacking.clear()
        if self._beam is not None:
            self._beam.visible = False
        if self._beam_spot is not None:
            self._beam_spot.visible = False

    # -- signals ----------------------------------------------------------

    def _announce_fired(self) -> None:
        if self.rack is not None:
            self.rack.weapon_fired(self.weapon_id)


class EnergyWeapon(Weapon):
    """Pulse blaster, scatter coil, arc beam, mining laser and nova mortar.

    Fed entirely by the capacitor through ``PowerSystem``; no magazine, no
    ammo box, no scrap. Last Stand waives the cost without waiving the shot.
    """

    def _energy_per_shot(self) -> float:
        if self.spec.energy_per_shot is not None:
            return float(self.spec.energy_per_shot)
        return PROVISIONAL_ENERGY_PER_SHOT.get(self.weapon_id, 0.0)

    def _energy_per_second(self) -> float:
        if self.spec.energy_per_s is not None:
            return float(self.spec.energy_per_s)
        return 0.0

    def _pay_for_shot(self) -> bool:
        cost = self._energy_per_shot()
        power = self._power()
        if cost <= 0.0 or power is None or self._free_fire():
            return True
        return bool(power.request(cost, self.weapon_id))

    def _pay_for_beam(self, dt: float) -> bool:
        cost = self._energy_per_second()
        power = self._power()
        if cost <= 0.0 or power is None or self._free_fire():
            return True
        return bool(power.drain(cost, dt, self.weapon_id))


class BallisticWeapon(Weapon):
    """Rail lance, flak cannon, autocannon and missile rack.

    Fed by a magazine that ammo boxes refill and by nothing else: a ballistic
    weapon costs zero capacitor, which is what lets a scrap-fed build leave the
    power economy altogether. An empty magazine swaps a box in automatically
    when the rack holds one, at the price of a reload lockout.
    """

    def __init__(self, weapon_id: str, **kwargs):
        super().__init__(weapon_id, **kwargs)
        self.magazine_size = int(self.spec.rounds_per_box or 0)
        self.rounds = self.magazine_size

    def reload_from_box(self) -> bool:
        """Consume one of the rack's boxes to refill the magazine."""
        if self.rounds >= self.magazine_size or self.rack is None:
            return False
        if not self.rack.take_ammo_box(self.weapon_id):
            return False
        self.rounds = self.magazine_size
        self._announce_ammo()
        return True

    def _pay_for_shot(self) -> bool:
        needed = self.profile.rounds_per_shot
        if self.rounds < needed:
            if self.reload_from_box():
                self._cooldown = RELOAD_S
            return False
        self.rounds -= needed
        self._announce_ammo()
        return True

    def _announce_ammo(self) -> None:
        if self.rack is not None:
            self.rack.ammo_changed(self.weapon_id, self.rounds)


class GravHook(Weapon):
    """The utility hardpoint: yanks one enemy or salvage mote toward the ship.

    Deals no damage at all. What it moves, it moves on the flight plane at a
    fixed speed for a fixed time, so a mote pulled out of a Skimmer's path and
    a Lancer pulled out of its dash both read the same way.
    """

    def __init__(self, weapon_id: str = "grav_hook", **kwargs):
        super().__init__(weapon_id, **kwargs)
        self._hooked: list[tuple[Node3D, float]] = []

    def _pay_for_shot(self) -> bool:
        cost = PROVISIONAL_ENERGY_PER_SHOT.get(self.weapon_id, 0.0)
        power = self._power()
        if cost <= 0.0 or power is None or self._free_fire():
            return True
        return bool(power.request(cost, self.weapon_id))

    def _discharge(self) -> None:
        origin = _plane_of(self)
        direction = self._aim_direction()
        caught = _sweep(
            self.tree, origin, direction, self.profile.reach, 0.0, Groups.ENEMIES, Groups.SALVAGE, Groups.HUNTER
        )
        # A swarm has no single body to grab: its members are array rows that
        # do not follow the shoal node.
        for _distance, target, _centre in caught:
            if not _is_swarm(target):
                self._hooked.append((target, GRAV_HOOK_PULL_S))
                return

    def on_update(self, dt: float):
        super().on_update(dt)
        self._pull(dt)

    def _pull(self, dt: float) -> None:
        if not self._hooked:
            return
        anchor = self._anchor()
        still: list[tuple[Node3D, float]] = []
        for target, remaining in self._hooked:
            if target.destroying or remaining <= 0.0:
                continue
            tx, tz = _plane_of(target)
            towards = _normalise(anchor[0] - tx, anchor[1] - tz)
            step = GRAV_HOOK_PULL_SPEED * dt
            target.position = Vec3(
                float(target.position[0]) + towards[0] * step,
                PLANE_Y,
                float(target.position[2]) + towards[1] * step,
            )
            still.append((target, remaining - dt))
        self._hooked = still

    def _anchor(self) -> tuple[float, float]:
        """Where hooked things are dragged to: the ship, or the hook itself."""
        ships = _group_nodes(self.tree, Groups.SHIP)
        return _plane_of(ships[0]) if ships else _plane_of(self)


#: Which class mounts each roster entry.
_WEAPON_CLASSES = {"energy": EnergyWeapon, "ballistic": BallisticWeapon, "utility": GravHook}


def make_weapon(weapon_id: str, **kwargs) -> Weapon:
    """Build the weapon node for a roster id, picking the class by family."""
    if weapon_id not in balance.WEAPONS:
        raise ValueError(f"unknown weapon id {weapon_id!r}")
    return _WEAPON_CLASSES[balance.WEAPONS[weapon_id].family](weapon_id, **kwargs)


# ============================================================================
# The rack
# ============================================================================


class WeaponRack(Node3D):
    """The ship's hardpoints, what is bolted to them, and the ammo locker.

    The rack is the single place other systems connect to for fire and ammo
    events, and the single place the two fire actions are read. It drives its
    weapons every frame: aim first, then trigger state, so a held button keeps
    an automatic firing and a released one drops a beam within the frame.

    It is a ``Node3D`` rather than a bare ``Node`` because the weapons hanging
    off it are positioned hardpoints and must inherit the hull's transform.
    """

    #: ``(weapon_id)`` whenever a shot leaves a muzzle or a beam engages.
    weapon_fired = Signal(str)
    #: ``(weapon_id, rounds)`` after every round spent and every reload.
    ammo_changed = Signal(str, int)
    #: ``(weapon_id, hardpoint)`` when a hardpoint's fitting changes.
    weapon_equipped = Signal(str, int)

    def __init__(self, hardpoints: int = balance.HARDPOINTS_STARTER, **kwargs):
        kwargs.setdefault("name", "Hardpoints")
        super().__init__(**kwargs)
        self.hardpoints: list[Weapon | None] = [None] * self._validated_count(hardpoints)
        self._boxes: dict[str, int] = {}
        self._aim_point: Vec3 | None = None
        self._triggers = {PRIMARY_ACTION: False, MINING_ACTION: False}
        #: When True the rack reads the fire actions itself. Turrets and other
        #: non-player mounts set it False and drive the triggers directly.
        self.player_controlled = True
        #: Last Stand waives energy costs; ammo is still spent.
        self.free_fire = False

    @staticmethod
    def _validated_count(hardpoints: int) -> int:
        if not 1 <= int(hardpoints) <= balance.HARDPOINTS_MAX:
            raise ValueError(f"hardpoint count must be 1 to {balance.HARDPOINTS_MAX}, got {hardpoints}")
        return int(hardpoints)

    def on_enter_tree(self):
        super().on_enter_tree()
        self.add_to_group(WEAPON_RACK_GROUP)

    # -- fitting ----------------------------------------------------------

    def equip(self, weapon_id: str, hardpoint: int) -> None:
        """Bolt *weapon_id* to *hardpoint*, replacing whatever was there."""
        self._check_hardpoint(hardpoint)
        self.unequip(hardpoint)
        offset = HARDPOINT_OFFSETS[hardpoint % len(HARDPOINT_OFFSETS)]
        weapon = make_weapon(weapon_id, position=Vec3(offset[0], PLANE_Y, offset[1]))
        weapon.rack = self
        self.hardpoints[hardpoint] = self.add_child(weapon)
        self.weapon_equipped(weapon_id, hardpoint)

    def unequip(self, hardpoint: int) -> None:
        """Strip a hardpoint back to bare mounting."""
        self._check_hardpoint(hardpoint)
        fitted = self.hardpoints[hardpoint]
        if fitted is not None:
            self.hardpoints[hardpoint] = None
            fitted.rack = None
            fitted.destroy()

    def swap_in(self, weapon_id: str, hardpoint: int) -> str:
        """Fit *weapon_id* to *hardpoint* and return whatever it displaced.

        The empty string when the hardpoint was bare. The caller owns the
        locker, so a swap is one call here and one list edit there rather than
        two half-authoritative copies of what the ship is carrying; the run
        scene puts the returned id back into its stowage.
        """
        self._check_hardpoint(hardpoint)
        fitted = self.hardpoints[hardpoint]
        displaced = fitted.weapon_id if fitted is not None else ""
        self.equip(weapon_id, hardpoint)
        return displaced

    def free_hardpoint(self) -> int | None:
        """The lowest bare hardpoint, or None when every mount is taken.

        The same choice :meth:`equip` is given when a purchase lands, so a
        shelf can name the hardpoint a weapon would take before it is bought.
        """
        for index, fitted in enumerate(self.hardpoints):
            if fitted is None:
                return index
        return None

    def fit_lines(self) -> list[str]:
        """One line per hardpoint, for a screen that shows the current fit.

        Bare mounts are listed as bare, because the question a pilot asks in a
        shop is as often "where would this go?" as "what have I got?". A
        ballistic mount also carries its magazine and its spare boxes, which is
        the number that decides whether the next purchase is a gun or a box.
        """
        lines: list[str] = []
        for index, fitted in enumerate(self.hardpoints):
            head = f"hardpoint {index + 1}"
            if fitted is None:
                lines.append(f"{head}: empty")
                continue
            name = fitted.weapon_id.replace("_", " ").upper()
            line = f"{head}: {name}, {weapon_summary(fitted.weapon_id)}"
            if isinstance(fitted, BallisticWeapon):
                line += f", {fitted.rounds}/{fitted.magazine_size} loaded, {self.ammo_boxes(fitted.weapon_id)} boxes"
            lines.append(line)
        return lines

    def add_hardpoint(self) -> int:
        """Open one more hardpoint, up to the hull maximum, and return its index."""
        if len(self.hardpoints) >= balance.HARDPOINTS_MAX:
            raise ValueError(f"a hull carries at most {balance.HARDPOINTS_MAX} hardpoints")
        self.hardpoints.append(None)
        return len(self.hardpoints) - 1

    def weapons(self) -> list[Weapon]:
        """Every fitted weapon, in hardpoint order."""
        return [w for w in self.hardpoints if w is not None]

    def _check_hardpoint(self, hardpoint: int) -> None:
        if not 0 <= hardpoint < len(self.hardpoints):
            raise ValueError(f"hardpoint {hardpoint} does not exist (rack has {len(self.hardpoints)})")

    # -- ammunition -------------------------------------------------------

    def ammo_boxes(self, weapon_id: str) -> int:
        """Spare boxes held for *weapon_id*."""
        return self._boxes.get(weapon_id, 0)

    def add_ammo_box(self, weapon_id: str) -> None:
        """Stow one box; boxes are per weapon, as the magazines are."""
        self._require_ballistic(weapon_id)
        self._boxes[weapon_id] = self._boxes.get(weapon_id, 0) + 1

    def take_ammo_box(self, weapon_id: str) -> bool:
        """Consume one stowed box. False when the locker is empty."""
        held = self._boxes.get(weapon_id, 0)
        if held <= 0:
            return False
        self._boxes[weapon_id] = held - 1
        return True

    def ammo_eater(self) -> str | None:
        """The mounted ballistic weapon a bought box feeds: the hungriest one.

        None when nothing on the hull takes boxes, which is what makes a box a
        refusable purchase rather than scrap spent on a locker with no gun.
        """
        ballistic = [weapon for weapon in self.weapons() if weapon.spec.family == "ballistic"]
        if not ballistic:
            return None
        return min(ballistic, key=lambda weapon: self.ammo_boxes(weapon.weapon_id)).weapon_id

    def locker(self) -> dict[str, int]:
        """Every non-empty box count by weapon id, for the suspend save."""
        return {weapon_id: held for weapon_id, held in self._boxes.items() if held > 0}

    @staticmethod
    def _require_ballistic(weapon_id: str) -> None:
        spec = balance.WEAPONS.get(weapon_id)
        if spec is None or spec.family != "ballistic":
            raise ValueError(f"{weapon_id!r} does not take ammo boxes")

    # -- driving ----------------------------------------------------------

    def set_aim(self, world_point: Vec3) -> None:
        """The flight-plane point every fitted weapon converges on."""
        self._aim_point = Vec3(world_point)

    def set_primary_trigger(self, held: bool) -> None:
        self._triggers[PRIMARY_ACTION] = bool(held)

    def set_mining_trigger(self, held: bool) -> None:
        self._triggers[MINING_ACTION] = bool(held)

    def on_update(self, dt: float):
        if self.player_controlled:
            self.set_primary_trigger(Input.is_action_pressed(PRIMARY_ACTION))
            self.set_mining_trigger(Input.is_action_pressed(MINING_ACTION))
        aim = self._aim_point if self._aim_point is not None else self._default_aim()
        for weapon in self.weapons():
            weapon.set_aim(aim)
            weapon.set_trigger(self._triggers[weapon.trigger_action])

    def _default_aim(self) -> Vec3:
        """Straight down the hull's nose when nothing has set an aim point."""
        heading = float(getattr(self.parent, "heading", 0.0))
        here = _plane_of(self)
        return Vec3(here[0] + math.cos(heading) * 10.0, PLANE_Y, here[1] - math.sin(heading) * 10.0)


def attach_rack(ship: Node, hardpoints: int = balance.HARDPOINTS_STARTER, loadout: tuple[str, ...] = ()) -> WeaponRack:
    """Mount a rack on *ship* and fit *loadout* to its hardpoints in order."""
    rack = ship.add_child(WeaponRack(hardpoints=hardpoints))
    for index, weapon_id in enumerate(loadout[:hardpoints]):
        rack.equip(weapon_id, index)
    return rack