shrike/enemies/advanced.py

Part of SHRIKE.

"""The advanced half of the enemy roster: support, siege, alarm, emplacement and herald.

Where ``basic.py`` holds the archetypes that come at you, this module holds the
five that change the shape of a fight rather than adding hulls to shoot:

* :class:`Welder` keeps other enemies alive down a visible repair umbilical you
  cut by flying through it, which turns a wave into a kill-order problem.
* :class:`Bombardier` never closes. It paints landing reticles on where you are
  about to be, so parking on a deposit is what costs hull.
* :class:`Screamer` never shoots. Leave it alive
  ``balance.SCREAMER_AGGRO_TIMER_S`` after it notices you and it pays for itself
  in signature, which is the next wave's budget.
* :class:`HuskTurret` is terrain that shoots: a dead hull sweeping a tracking
  beam across a corridor, damaging in ticks rather than continuously.
* :class:`Herald` pours in during the hunter's arrival window and carries the
  Fletchings the Roost campaign is built from.

Every one of them attacks through :meth:`Enemy.begin_attack`, so the white
telegraph promise from ``steering.py`` holds here too.

The three elite modifiers are composable wrappers rather than subclasses.
:func:`apply_elite` wraps an enemy's bound ``take_damage`` and hooks its ``died``
signal, so Armoured, Splitting and EMP-laced apply equally to everything in
``basic.py`` and everything here, and two of them nest cleanly on one hull.

Balance numbers come from ``shrike.balance``, speeds and engagement ranges
included: the module-level names below are bindings to that table. What is
named here for its own sake is cadence, geometry and the elite coefficients.

Each of these archetypes staggers its own attack timer at spawn through
``Enemy.stagger_cadence``, so a battery of Bombardiers walks its fire and a
flight of Heralds lances in ones rather than in a single volley.
"""

from __future__ import annotations

import math
import random
from dataclasses import dataclass, field

import numpy as np

from simvx.core import (
    Material,
    Mesh,
    MeshInstance3D,
    MultiMesh,
    MultiMeshInstance3D,
    Node3D,
    Property,
    Quat,
    Signal,
    Vec2,
    Vec3,
)

from .. import artkit, balance
from ..runtime import PLANE_Y, Groups, Services, from_plane, to_plane
from ..vfx import Vfx
from .steering import Enemy, seek

# ============================================================================
# Module-local anchors
#
# Speeds and engagement ranges live in balance.py, quoted as multiples of the
# player's cruise speed and against what the camera actually shows; the bindings
# below give the behaviour code readable names for them and nothing more. What
# is genuinely local is cadence, geometry and the elite coefficients: how often
# an archetype may try, how wide its sweep is, and what a modifier costs.
# ============================================================================

# Welder
WELDER_SPEED = balance.WELDER_SPEED
#: Longest umbilical the welder projects, and the range it looks for patients in.
WELDER_UMBILICAL_RANGE = balance.WELDER_UMBILICAL_RANGE
#: Distance it tries to hold from its patient while the link is live.
WELDER_TETHER_DISTANCE = balance.WELDER_TETHER_DISTANCE
WELDER_REPAIR_PER_S = 6.0
#: How near the umbilical the ship must pass to shear it.
WELDER_UMBILICAL_BREAK_RADIUS = balance.WELDER_UMBILICAL_BREAK_RADIUS
#: Dead time before a sheared welder finds another patient.
WELDER_RELINK_DELAY_S = 2.5
#: Where an unlinked welder loiters relative to the ship.
WELDER_LOITER_DISTANCE = balance.WELDER_LOITER_DISTANCE
#: Drawn radius of the umbilical. Thinner than a weapon beam: it is a link to
#: read and fly through, not a thing that hurts.
WELDER_UMBILICAL_RADIUS = 0.09

# Bombardier
BOMBARDIER_SPEED = balance.BOMBARDIER_SPEED
BOMBARDIER_STANDOFF_DISTANCE = balance.BOMBARDIER_STANDOFF_DISTANCE
#: Dead band around the stand-off distance, inside which it strafes rather than closes.
BOMBARDIER_STANDOFF_BAND = balance.BOMBARDIER_STANDOFF_BAND
#: Beyond this the ship is out of the tube's reach.
BOMBARDIER_MAX_RANGE = balance.BOMBARDIER_MAX_RANGE
BOMBARDIER_SALVO_INTERVAL_S = 4.5
BOMBARDIER_SALVO_SHELLS = 3
#: Seconds a reticle is painted on the plane before its shell lands. Two full
#: seconds is the design's warning, and it is a floor rather than a taste: it
#: has to cover reading the paint, deciding, and flying out of a blast radius
#: from a standing start.
BOMBARDIER_SHELL_FLIGHT_S = 2.0
#: Extra flight time per shell, so a salvo walks across the target rather than stacking.
BOMBARDIER_SHELL_STAGGER_S = 0.35
BOMBARDIER_BLAST_RADIUS = balance.BOMBARDIER_BLAST_RADIUS
#: How far ahead of the ship's current velocity the first shell is aimed.
BOMBARDIER_LEAD_S = 0.9
#: Random scatter applied to each shell after the lead, in plane units.
BOMBARDIER_SCATTER = balance.BOMBARDIER_SCATTER

# Screamer
SCREAMER_SPEED = balance.SCREAMER_SPEED
SCREAMER_AGGRO_RANGE = balance.SCREAMER_AGGRO_RANGE
#: Once aggroed it runs, and keeps running until it is this far from the ship.
SCREAMER_FLEE_DISTANCE = balance.SCREAMER_FLEE_DISTANCE

# Husk turret
HUSK_TURRET_BEAM_RANGE = balance.HUSK_TURRET_BEAM_RANGE
#: Idle sweep: the beam oscillates across this arc, centred on its rest heading.
HUSK_TURRET_SWEEP_ARC = math.radians(120.0)
HUSK_TURRET_SWEEP_RATE = math.radians(45.0)
#: How fast the beam pulls onto a target once the ship is in range.
HUSK_TURRET_TRACK_RATE = math.radians(70.0)
#: Angular tolerance for the beam counting as on target.
HUSK_TURRET_BEAM_HALF_ANGLE = math.radians(4.0)
#: The beam damages in ticks, not continuously.
HUSK_TURRET_TICK_S = 0.5
#: Height of the barrel's trunnion above the wreck, world units: the drum the
#: art kit sits on the base is 1.7 deep and the barrel rides its shoulder.
HUSK_TURRET_BARREL_HEIGHT = 0.75

# Herald
HERALD_SPEED = balance.HERALD_SPEED
#: Radius of the strafing orbit a herald holds around the ship.
HERALD_ORBIT_RADIUS = balance.HERALD_ORBIT_RADIUS
HERALD_ORBIT_RATE = 1.1
HERALD_FIRE_INTERVAL_S = 2.2
HERALD_LANCE_RANGE = balance.HERALD_LANCE_RANGE
#: The telegraph stage the flight arrives on.
HERALD_ARRIVAL_STAGE = "t30"
HERALD_FLIGHT_MIN = 3
HERALD_FLIGHT_MAX = 5
#: Heralds tear in on a ring this far from the ship.
HERALD_SPAWN_RADIUS = balance.HERALD_SPAWN_RADIUS
#: Heralds are the hunter's language spoken by an enemy hull, so they carry the
#: enemy palette like everything else the player shoots; what marks them out is
#: the silhouette, a shard of the Shrike itself.
HERALD_COLOUR = artkit.palette("enemy").hull_colour

# Elite modifiers
ELITE_ARMOURED_HP_MULT = 1.8
#: Plating trims most incoming damage, but ballistics were built for plating.
ELITE_ARMOURED_REDUCTION = 0.45
ELITE_ARMOURED_BALLISTIC_REDUCTION = 0.20
ELITE_SPLIT_COUNT = 2
ELITE_SPLIT_HP_FRACTION = 0.35
#: How far the halves are thrown apart when the parent comes open.
ELITE_SPLIT_SCATTER = 4.0
ELITE_EMP_CAPACITOR_DRAIN = 25.0
ELITE_EMP_RADIUS = 14.0


# ============================================================================
# Ordnance presentation
#
# An attack the player cannot see is not a difficulty setting, it is a bug: a
# mortar reticle that is only a dataclass, a turret beam that is only a heading
# and a lance that is only a damage number all read to the player as dying for
# no reason. Everything an enemy puts in the air is built from the constants
# below, so the readability contract (enemy fire is cold magenta, and emissive
# so it survives two hundred particles) is enforced at one site rather than
# remembered five times.
# ============================================================================

#: Cold magenta, from the enemy palette. Every hostile muzzle, shell, beam and
#: reticle in the game is this colour.
ENEMY_FIRE_COLOUR = artkit.palette("enemy").accent
ENEMY_FIRE_ENERGY = artkit.palette("enemy").accent_strength
#: How much larger than the radius its damage resolves against a piece of
#: ordnance is drawn. Fire that is drawn at its true size is a pixel at this
#: camera distance, so it is drawn at the size it needs to be read at, and the
#: hit stays honest by resolving against the smaller number.
ENEMY_ORDNANCE_VISUAL_GAIN = 2.0

#: Radius the mortar shell's own body would occupy. Nothing collides with it in
#: flight (its reticle owns the landing), so this exists to size the tracer.
MORTAR_SHELL_BODY_RADIUS = 0.26
#: The drawn tracer, at the visual gain.
MORTAR_SHELL_DRAWN_RADIUS = MORTAR_SHELL_BODY_RADIUS * ENEMY_ORDNANCE_VISUAL_GAIN
#: How high above the plane the shell arcs at the top of its flight. Gameplay
#: never leaves the plane; the picture is allowed to.
MORTAR_SHELL_ARC_HEIGHT = 7.0
#: The audio cue a launched shell asks for. See :attr:`Bombardier.shell_launched`.
MORTAR_WHISTLE_CUE = "mortar_whistle"

#: The landing reticle: a dim rim at the blast radius that says where, and a
#: bright ring closing inside it that says when. Both are rings of dashes on
#: one multimesh, so a full salvo of three costs six draws.
RETICLE_RING_DASHES = 24
RETICLE_DASH_LENGTH = 0.22
RETICLE_DASH_WIDTH = 0.05
RETICLE_DASH_THICKNESS = 0.02
RETICLE_RIM_ALPHA = 0.45
RETICLE_CLOSER_ALPHA = 1.0
#: The closing ring never quite reaches zero: a ring with no radius is a dot,
#: and the last tenth of a second is when the player most needs to see one.
RETICLE_CLOSER_MIN_FRACTION = 0.12
#: Reticles sit a hair above the plane so they never z-fight the deck.
RETICLE_HEIGHT = 0.04

#: Beams: the husk turret's sustained sweep and the herald's lance.
ENEMY_BEAM_RADIUS = 0.16
#: How long a lance stays drawn after it has landed. Long enough to be seen and
#: located, short enough that a flight of five does not paint the screen.
LANCE_TRACER_S = 0.18


def enemy_fire_material(*, alpha: float = 1.0, energy: float = ENEMY_FIRE_ENERGY) -> Material:
    """One piece of hostile ordnance's material: unlit magenta that blooms."""
    return Material(
        colour=(*ENEMY_FIRE_COLOUR, alpha),
        blend="alpha",
        unlit=True,
        emissive_colour=ENEMY_FIRE_COLOUR,
        emissive_strength=energy,
    )


def _ring_multimesh(dashes: int = RETICLE_RING_DASHES) -> MultiMesh:
    """A unit-radius ring of tangential dashes, as one instanced draw.

    Scaling the node that carries it scales the ring, which is what lets the
    closing ring shrink every frame without touching a transform buffer.
    """
    transforms = np.zeros((dashes, 4, 4), dtype=np.float32)
    transforms[:, 3, 3] = 1.0
    angles = np.arange(dashes, dtype=np.float32) * (2.0 * math.pi / dashes)
    # Yaw each dash so its long axis lies along the tangent at its angle.
    yaw = -(angles + math.pi * 0.5)
    cos, sin = np.cos(yaw), np.sin(yaw)
    transforms[:, 0, 0] = cos * RETICLE_DASH_LENGTH
    transforms[:, 2, 0] = -sin * RETICLE_DASH_LENGTH
    transforms[:, 1, 1] = RETICLE_DASH_THICKNESS
    transforms[:, 0, 2] = sin * RETICLE_DASH_WIDTH
    transforms[:, 2, 2] = cos * RETICLE_DASH_WIDTH
    transforms[:, 0, 3] = np.cos(angles)
    transforms[:, 2, 3] = np.sin(angles)
    mesh = MultiMesh(mesh=Mesh.cube(size=1.0), instance_count=dashes)
    mesh.set_all_transforms(transforms)
    return mesh


class PlaneBeam(Node3D):
    """A magenta bolt drawn between two points on the flight plane.

    The husk turret holds one lit for as long as its beam is on target; a
    herald strikes one for :data:`LANCE_TRACER_S` and lets it fade. Either way
    the player sees the line the damage came down, which is the whole point:
    the geometry is the only difference between an attack and an unexplained
    hull loss.
    """

    visible = Property(
        False,
        coerce=bool,
        hint="Whether this node and its subtree are drawn",
        on_change="_on_visible_changed",
    )

    def __init__(self, *, radius: float = ENEMY_BEAM_RADIUS, **kwargs):
        kwargs.setdefault("name", "Beam")
        super().__init__(**kwargs)
        self.radius = float(radius)
        self._core: MeshInstance3D | None = None
        self._hold = 0.0

    @property
    def lit(self) -> bool:
        """Whether the beam is currently drawn."""
        return self.visible

    def on_ready(self):
        self._core = self.add_child(
            MeshInstance3D(
                name="Core",
                mesh=Mesh.cylinder(radius=self.radius, height=1.0, segments=8),
                material=enemy_fire_material(),
                rotation=Quat.from_euler(math.radians(90.0), 0.0, 0.0),
            )
        )

    def draw_between(self, start: Vec2, end: Vec2, *, hold_s: float = 0.0) -> None:
        """Light the beam from *start* to *end*, holding it for *hold_s*.

        A zero hold means the caller re-draws it every frame while it burns; a
        positive one is a strike that fades itself out.
        """
        dx = float(end.x) - float(start.x)
        dz = float(end.y) - float(start.y)
        length = math.hypot(dx, dz)
        if length < 1e-6 or self._core is None:
            return
        self.position = Vec3(float(start.x), PLANE_Y, float(start.y))
        self.face_along(Vec3(dx / length, 0.0, dz / length))
        self._core.position = Vec3(0.0, 0.0, -length * 0.5)
        self._core.scale = Vec3(1.0, length, 1.0)
        self._hold = float(hold_s)
        self.visible = True

    def douse(self) -> None:
        """Put the beam out now."""
        self._hold = 0.0
        self.visible = False

    def on_update(self, dt: float):
        if self._hold <= 0.0:
            return
        self._hold -= dt
        if self._hold <= 0.0:
            self.douse()


# ============================================================================
# Plane geometry
# ============================================================================


def wrap_angle(radians: float) -> float:
    """Fold an angle into ``[-pi, pi]``."""
    return (float(radians) + math.pi) % (2.0 * math.pi) - math.pi


def point_to_segment_distance(point: Vec2, start: Vec2, end: Vec2) -> float:
    """Shortest distance from *point* to the segment ``start -> end`` on the plane."""
    sx, sy = float(start.x), float(start.y)
    dx, dy = float(end.x) - sx, float(end.y) - sy
    length_sq = dx * dx + dy * dy
    if length_sq <= 1e-9:
        return math.hypot(float(point.x) - sx, float(point.y) - sy)
    t = ((float(point.x) - sx) * dx + (float(point.y) - sy) * dy) / length_sq
    t = min(1.0, max(0.0, t))
    return math.hypot(float(point.x) - (sx + dx * t), float(point.y) - (sy + dy * t))


def bearing(origin: Vec2, target: Vec2) -> float:
    """Heading in radians from *origin* to *target*, anticlockwise from +X seen from above."""
    return math.atan2(-(float(target.y) - float(origin.y)), float(target.x) - float(origin.x))


def heading_vector(heading: float) -> Vec2:
    """Unit plane vector for a heading, matching ``runtime.heading_to_direction``."""
    return Vec2(math.cos(heading), -math.sin(heading))


def full_hp(enemy) -> float:
    """Full hull points for *enemy*, honouring an Armoured elite's inflated pool.

    An archetype that tracks its own ceiling (everything in this module, and
    anything an elite has been attached to) reports it through ``max_hp``.
    Otherwise the archetype's balance entry is the ceiling, which is right for a
    single hull and only approximate for an aggregate one such as a mite shoal,
    so callers that heal clamp against the current value as well.
    """
    return float(getattr(enemy, "max_hp", enemy.spec.hp))


# ============================================================================
# Shared scaffolding
# ============================================================================


class AdvancedEnemy(Enemy):
    """Station-keeping, seeding and elite bookkeeping shared by the advanced five.

    The base in ``steering.py`` already owns hull points, the telegraph and the
    damage route. What the advanced archetypes add is a reason to sit still at a
    chosen distance, per-node randomness the wave composer can seed for a
    learnable spawn, and the ``max_hp`` ceiling a Welder heals toward and an
    Armoured elite raises.
    """

    #: Cruising speed on the flight plane in units per second; 0 when stationary.
    SPEED: float = 0.0

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.max_hp = float(self.spec.hp)
        self.elite_modifiers: list[EliteModifier] = []
        self._ordnance: list[Node3D] = []

    # -- Ordnance ownership -------------------------------------------------

    def mount_beam(self, name: str = "Beam", **kwargs) -> PlaneBeam:
        """Mount a :class:`PlaneBeam` this enemy owns but does not carry.

        Ordnance is parented beside the hull rather than under it, because a
        beam is drawn between two points on the flight plane and a hull that
        turns to face its target would otherwise swing its own beam twice. The
        enemy still owns the node: :meth:`on_exit_tree` takes it away.
        """
        parent = self.parent if self.parent is not None else self
        beam = parent.add_child(PlaneBeam(name=f"{self.name}{name}", **kwargs))
        self._ordnance.append(beam)
        return beam

    def release_ordnance(self) -> None:
        """Destroy everything this enemy put on the plane. Idempotent."""
        for node in self._ordnance:
            if node is not None and not node.destroying:
                node.destroy()
        self._ordnance = []

    def on_exit_tree(self):
        super().on_exit_tree()
        self.release_ordnance()

    def place(self, plane_point: Vec2) -> None:
        """Move to *plane_point*, holding the flight plane exactly."""
        self.position = from_plane(Vec2(float(plane_point.x), float(plane_point.y)))

    def hold_standoff(self, target: Vec2, dt: float, distance: float, band: float) -> None:
        """Keep *distance* from *target*, strafing sideways once inside the *band*.

        This is what makes a stand-off archetype read as deliberate: it closes
        when it is too far, backs off when you charge it, and circles when it is
        happy, rather than oscillating across the ideal range.
        """
        offset = self.plane_position - Vec2(float(target.x), float(target.y))
        current = math.hypot(float(offset.x), float(offset.y))
        if current <= 1e-6:
            self.move(dt, Vec2(1.0, 0.0), self.SPEED)
            return
        outward = Vec2(float(offset.x) / current, float(offset.y) / current)
        if current > distance + band:
            direction = Vec2(-float(outward.x), -float(outward.y))
        elif current < distance - band:
            direction = outward
        else:
            direction = Vec2(-float(outward.y), float(outward.x))
        self.move(dt, direction, self.SPEED)
        self.face(direction)

    def deal_damage_from(self, origin: Vec2, target, amount: float, kind: str) -> None:
        """Hurt *target* as though the blow came from *origin* rather than this hull.

        A mortar shell landing beside the ship must desaturate the screen edge it
        actually fell on, not the edge the tube is parked behind, so the blast
        direction comes from the shell.

        A shell that lands squarely on the hull has no bearing of its own, and a
        zero direction is the one value every consumer of ``PLAYER_DAMAGED``
        silently drops: no edge desaturation, no punch, no directional cue at
        all, on the hit that most deserves one. In that case the bearing falls
        back to the tube's, which is where the player has to look anyway.
        """
        here = Vec2(float(origin.x), float(origin.y))
        there = to_plane(target.position)
        bearing_from = seek(here, there)
        if not float(bearing_from.x) and not float(bearing_from.y):
            bearing_from = seek(self.plane_position, there)
        direction = from_plane(bearing_from)
        router = self.damage_router()
        if router is not None:
            router.deal(target, amount, kind=kind, direction=direction, source=self)
        elif hasattr(target, "apply_damage"):
            target.apply_damage(amount, direction, kind)


# ============================================================================
# Welder
# ============================================================================


class Welder(AdvancedEnemy):
    """Support crab that keeps other enemies alive down a visible repair umbilical.

    It never shoots. It picks the most wounded enemy in range, holds station near
    it and pours :data:`WELDER_REPAIR_PER_S` back into its hull. The link is a
    line on the flight plane, and flying the ship through that line shears it:
    the welder emits :attr:`umbilical_broken` and cannot relink for
    :data:`WELDER_RELINK_DELAY_S`. That is the whole answer to the archetype, and
    it costs positioning rather than damage.
    """

    ARCHETYPE = "welder"
    SPEED = WELDER_SPEED
    HITBOX_RADIUS = 1.5

    #: ``runtime.SignalNames.UMBILICAL_BROKEN``. Emitted when the ship cuts the link.
    umbilical_broken = Signal()

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.patient: Node3D | None = None
        self.umbilical: PlaneBeam | None = None
        self._relink_delay = 0.0

    def build_body(self):
        self.add_child(artkit.build_enemy("welder"))
        # The link is the archetype's whole answer, so it has to be a line the
        # player can see and fly through, not a pair of coordinates.
        self.umbilical = self.mount_beam("Umbilical", radius=WELDER_UMBILICAL_RADIUS)

    @property
    def linked(self) -> bool:
        """Whether an umbilical is currently projected."""
        return self.patient is not None

    def umbilical_endpoints(self) -> tuple[Vec2, Vec2] | None:
        """The two plane points the umbilical runs between, or ``None`` when unlinked."""
        if self.patient is None:
            return None
        return self.plane_position, to_plane(self.patient.position)

    def on_update(self, dt: float):
        super().on_update(dt)
        if self._relink_delay > 0.0:
            self._relink_delay -= dt
        self._drop_invalid_patient()
        if self.patient is None and self._relink_delay <= 0.0:
            self.patient = self._choose_patient()
        if self.patient is None:
            if self.umbilical is not None:
                self.umbilical.douse()
            return
        if self._ship_cuts_umbilical():
            self._shear()
            return
        if self.umbilical is not None:
            self.umbilical.draw_between(self.plane_position, to_plane(self.patient.position))
        # Never below where the patient already is: a welder repairs, and an
        # aggregate hull such as a shoal reports a pool bigger than its spec.
        ceiling = max(full_hp(self.patient), float(self.patient.hp))
        self.patient.hp = min(ceiling, float(self.patient.hp) + WELDER_REPAIR_PER_S * dt)

    def on_fixed_update(self, dt: float):
        if self.patient is not None:
            self.hold_standoff(to_plane(self.patient.position), dt, WELDER_TETHER_DISTANCE, 2.0)
            return
        ship = self.player_ship()
        if ship is not None:
            self.hold_standoff(to_plane(ship.position), dt, WELDER_LOITER_DISTANCE, 4.0)

    # -- internals ----------------------------------------------------------

    def _drop_invalid_patient(self) -> None:
        patient = self.patient
        if patient is None:
            return
        if patient.destroying or patient.tree is None or float(patient.hp) <= 0.0:
            self.patient = None
            return
        if self.distance_to(patient) > WELDER_UMBILICAL_RANGE:
            self.patient = None

    def _choose_patient(self) -> Node3D | None:
        """The most wounded enemy in range, nearest first among equals."""
        tree = self.tree
        if tree is None:
            return None
        best: Node3D | None = None
        best_key = (2.0, float("inf"))
        for node in tree.group(Groups.ENEMIES):
            if node is self or node.destroying or isinstance(node, Welder):
                continue
            if not hasattr(node, "hp") or not hasattr(node, "spec"):
                continue
            distance = self.distance_to(node)
            if distance > WELDER_UMBILICAL_RANGE:
                continue
            key = (float(node.hp) / max(full_hp(node), 1e-6), distance)
            if key < best_key:
                best, best_key = node, key
        return best

    def _ship_cuts_umbilical(self) -> bool:
        ship = self.player_ship()
        if ship is None or self.patient is None:
            return False
        gap = point_to_segment_distance(to_plane(ship.position), self.plane_position, to_plane(self.patient.position))
        return gap <= WELDER_UMBILICAL_BREAK_RADIUS

    def _shear(self) -> None:
        self.patient = None
        self._relink_delay = WELDER_RELINK_DELAY_S
        if self.umbilical is not None:
            self.umbilical.douse()
        self.umbilical_broken()


# ============================================================================
# Bombardier
# ============================================================================


class ReticleMarker(Node3D):
    """The painted landing circle, drawn: a rim, and a ring closing inside it.

    The rim says *where*, at the blast radius, and never moves. The closer says
    *when*: it starts on the rim and shrinks toward the impact point as the
    shell falls, so a glance costs no reading at all. Both are magenta, because
    everything that can hurt the player is.
    """

    def __init__(self, *, radius: float, **kwargs):
        kwargs.setdefault("name", "Reticle")
        super().__init__(**kwargs)
        self.radius = float(radius)
        self._rim: MultiMeshInstance3D | None = None
        self._closer: MultiMeshInstance3D | None = None
        self._fraction = 0.0

    @property
    def closer_radius(self) -> float:
        """Current radius of the closing ring, in world units."""
        span = 1.0 - RETICLE_CLOSER_MIN_FRACTION
        return self.radius * (1.0 - span * self._fraction)

    def on_ready(self):
        ring = _ring_multimesh()
        self._rim = self.add_child(
            MultiMeshInstance3D(
                name="Rim",
                multi_mesh=ring,
                material=enemy_fire_material(alpha=RETICLE_RIM_ALPHA, energy=ENEMY_FIRE_ENERGY * 0.4),
                scale=Vec3(self.radius, 1.0, self.radius),
            )
        )
        self._closer = self.add_child(
            MultiMeshInstance3D(
                name="Closer",
                multi_mesh=ring,
                material=enemy_fire_material(alpha=RETICLE_CLOSER_ALPHA),
                scale=Vec3(self.radius, 1.0, self.radius),
            )
        )

    def set_fraction(self, fraction: float) -> None:
        """Close the ring to *fraction* of the way through the shell's flight."""
        self._fraction = min(1.0, max(0.0, float(fraction)))
        if self._closer is not None:
            radius = self.closer_radius
            self._closer.scale = Vec3(radius, 1.0, radius)


class MortarShell(Node3D):
    """The round itself: a glowing magenta tracer arcing onto its reticle.

    It carries no collision body and resolves no damage; the reticle it was
    launched at owns the landing. What it owns is the answer to "what hit me":
    a shell in the air, on a visible arc, from a visible direction.
    """

    def __init__(self, *, origin: Vec2, target: Vec2, flight: float, **kwargs):
        kwargs.setdefault("name", "Shell")
        super().__init__(**kwargs)
        self.origin = Vec2(float(origin.x), float(origin.y))
        self.target = Vec2(float(target.x), float(target.y))
        self.flight = max(float(flight), 1e-6)
        self.elapsed = 0.0
        self.position = Vec3(float(origin.x), PLANE_Y, float(origin.y))

    @property
    def fraction(self) -> float:
        """How far along its arc the shell is, 0 at the tube and 1 on impact."""
        return min(1.0, max(0.0, self.elapsed / self.flight))

    def on_ready(self):
        self.add_child(
            MeshInstance3D(
                name="Tracer",
                mesh=Mesh.sphere(radius=MORTAR_SHELL_DRAWN_RADIUS, rings=6, segments=8),
                material=enemy_fire_material(),
            )
        )

    def advance(self, dt: float) -> None:
        """Fly one step of the arc. The bombardier drives this with its reticle."""
        self.elapsed += dt
        t = self.fraction
        self.position = Vec3(
            float(self.origin.x) + (float(self.target.x) - float(self.origin.x)) * t,
            PLANE_Y + MORTAR_SHELL_ARC_HEIGHT * 4.0 * t * (1.0 - t),
            float(self.origin.y) + (float(self.target.y) - float(self.origin.y)) * t,
        )


@dataclass
class MortarReticle:
    """One painted landing circle: where a shell falls, and how long until it does.

    ``marker`` and ``shell`` are the geometry the player actually reads. They
    are optional so a reticle can still be reasoned about in a scene with no
    tree to mount them in, but in a live run every reticle has both.
    """

    centre: Vec2
    radius: float
    remaining: float
    flight: float
    marker: ReticleMarker | None = field(default=None, compare=False)
    shell: MortarShell | None = field(default=None, compare=False)

    @property
    def fraction(self) -> float:
        """How far the paint has filled: 0 when painted, 1 at the moment of impact."""
        if self.flight <= 0.0:
            return 1.0
        return min(1.0, max(0.0, 1.0 - self.remaining / self.flight))


class Bombardier(AdvancedEnemy):
    """Stand-off mortar that shells where you are about to be, never where it is.

    It holds :data:`BOMBARDIER_STANDOFF_DISTANCE` and lobs a salvo of
    :data:`BOMBARDIER_SALVO_SHELLS`, each painting a reticle on the plane
    :data:`BOMBARDIER_SHELL_FLIGHT_S` before it lands. The reticles lead the
    ship's current velocity and walk outward, which is what makes camping a rich
    deposit expensive: reading the paint and moving costs nothing, ignoring it
    costs ``spec.damage`` a shell.
    """

    ARCHETYPE = "bombardier"
    SPEED = BOMBARDIER_SPEED
    HITBOX_RADIUS = 1.8

    #: ``(origin, flight_seconds)`` as each shell leaves the tube. Registered as
    #: ``SignalNames.SHELL_LAUNCHED``; ``audio.py`` plays ``MORTAR_WHISTLE_CUE``
    #: off it, panned to the origin, so the salvo is audible as well as visible.
    shell_launched = Signal(Vec3, float)

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.reticles: list[MortarReticle] = []
        self._salvo_cooldown = BOMBARDIER_SALVO_INTERVAL_S
        self.stagger_cadence()

    def stagger_cadence(self) -> None:
        """Start somewhere inside the salvo interval, so a battery walks its fire."""
        self._salvo_cooldown = self.cadence_offset(BOMBARDIER_SALVO_INTERVAL_S)

    def build_body(self):
        self.add_child(artkit.build_enemy("bombardier"))

    def on_update(self, dt: float):
        self._resolve_reticles(dt)
        super().on_update(dt)
        if self.telegraphing:
            return
        self._salvo_cooldown -= dt
        if self._salvo_cooldown > 0.0:
            return
        ship = self.player_ship()
        if ship is None or self.distance_to(ship) > BOMBARDIER_MAX_RANGE:
            return
        if self.begin_attack():
            self._salvo_cooldown = BOMBARDIER_SALVO_INTERVAL_S

    def on_fixed_update(self, dt: float):
        ship = self.player_ship()
        if ship is None:
            return
        self.hold_standoff(to_plane(ship.position), dt, BOMBARDIER_STANDOFF_DISTANCE, BOMBARDIER_STANDOFF_BAND)

    def perform_attack(self) -> None:
        """Paint the salvo's landing circles, leading the ship's current course."""
        ship = self.player_ship()
        if ship is None:
            return
        origin = to_plane(ship.position)
        velocity = getattr(ship, "velocity", None)
        lead = Vec2(0.0, 0.0)
        if velocity is not None:
            lead = Vec2(float(velocity.x) * BOMBARDIER_LEAD_S, float(velocity.y) * BOMBARDIER_LEAD_S)
        for index in range(BOMBARDIER_SALVO_SHELLS):
            walk = 1.0 + index * 0.5
            centre = Vec2(
                float(origin.x) + float(lead.x) * walk + self.rng.uniform(-BOMBARDIER_SCATTER, BOMBARDIER_SCATTER),
                float(origin.y) + float(lead.y) * walk + self.rng.uniform(-BOMBARDIER_SCATTER, BOMBARDIER_SCATTER),
            )
            flight = BOMBARDIER_SHELL_FLIGHT_S + index * BOMBARDIER_SHELL_STAGGER_S
            reticle = MortarReticle(centre=centre, radius=BOMBARDIER_BLAST_RADIUS, remaining=flight, flight=flight)
            self._launch(reticle)
            self.reticles.append(reticle)

    # -- internals ----------------------------------------------------------

    def _launch(self, reticle: MortarReticle) -> None:
        """Paint *reticle* on the plane and put a shell in the air toward it."""
        parent = self.parent if self.parent is not None else self
        reticle.marker = parent.add_child(
            ReticleMarker(
                radius=reticle.radius,
                position=Vec3(float(reticle.centre.x), PLANE_Y + RETICLE_HEIGHT, float(reticle.centre.y)),
            )
        )
        muzzle = self.plane_position
        reticle.shell = parent.add_child(MortarShell(origin=muzzle, target=reticle.centre, flight=reticle.flight))
        self.shell_launched(from_plane(muzzle), reticle.flight)

    def _resolve_reticles(self, dt: float) -> None:
        if not self.reticles:
            return
        landed: list[MortarReticle] = []
        live: list[MortarReticle] = []
        for reticle in self.reticles:
            reticle.remaining -= dt
            if reticle.remaining > 0.0:
                self._drive_ordnance(reticle, dt)
                live.append(reticle)
            else:
                landed.append(reticle)
        self.reticles = live
        for reticle in landed:
            self._impact(reticle)
        if not landed:
            return
        ship = self.player_ship()
        if ship is None:
            return
        here = to_plane(ship.position)
        for reticle in landed:
            gap = math.hypot(float(here.x) - float(reticle.centre.x), float(here.y) - float(reticle.centre.y))
            if gap <= reticle.radius:
                self.deal_damage_from(reticle.centre, ship, self.spec.damage, "explosive")

    def _drive_ordnance(self, reticle: MortarReticle, dt: float) -> None:
        """Close the ring and fly the shell one step along its arc."""
        if reticle.marker is not None and not reticle.marker.destroying:
            reticle.marker.set_fraction(reticle.fraction)
        if reticle.shell is not None and not reticle.shell.destroying:
            reticle.shell.advance(dt)

    def _impact(self, reticle: MortarReticle) -> None:
        """Retire a landed shell's geometry and detonate it where it fell."""
        for node in (reticle.marker, reticle.shell):
            if node is not None and not node.destroying:
                node.destroy()
        reticle.marker = None
        reticle.shell = None
        tree = self.tree
        if tree is None or tree.root is None:
            return
        Vfx.spawn(
            tree,
            "explosion",
            Vec3(float(reticle.centre.x), PLANE_Y, float(reticle.centre.y)),
            faction="enemy",
            scale=reticle.radius / BOMBARDIER_BLAST_RADIUS,
        )

    def on_exit_tree(self):
        """Take any ordnance still in the air with the tube that fired it."""
        super().on_exit_tree()
        for reticle in self.reticles:
            for node in (reticle.marker, reticle.shell):
                if node is not None and not node.destroying:
                    node.destroy()
        self.reticles = []


# ============================================================================
# Screamer
# ============================================================================


class Screamer(AdvancedEnemy):
    """Fragile siren that costs signature rather than hull.

    It aggros when the ship comes inside :data:`SCREAMER_AGGRO_RANGE` or the
    moment it is hit, then runs. Survive that aggro by
    ``balance.SCREAMER_AGGRO_TIMER_S`` and it emits :attr:`screamer_screamed`;
    the signature meter is what turns that into
    ``balance.SIGNATURE_SCREAMER_SURVIVED``, which is the next wave's budget. It
    never fires a shot, so ignoring it only ever costs you later.
    """

    ARCHETYPE = "screamer"
    SPEED = SCREAMER_SPEED
    HITBOX_RADIUS = 1.0

    #: ``runtime.SignalNames.SCREAMER_SCREAMED``. Emitted once, if it lives long enough.
    screamer_screamed = Signal()

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.aggroed = False
        self.screamed = False
        self._aggro_elapsed = 0.0

    def build_body(self):
        self.add_child(artkit.build_enemy("screamer"))

    @property
    def seconds_to_scream(self) -> float:
        """Time left on the aggro clock: ``inf`` before aggro, 0 once it has screamed."""
        if self.screamed:
            return 0.0
        if not self.aggroed:
            return float("inf")
        return max(0.0, balance.SCREAMER_AGGRO_TIMER_S - self._aggro_elapsed)

    def aggro(self) -> None:
        """Notice the ship and start the clock. Idempotent."""
        if self.aggroed:
            return
        self.aggroed = True
        self._aggro_elapsed = 0.0

    def take_damage(self, amount: float, kind: str) -> None:
        """Being shot counts as being noticed, whatever the range."""
        self.aggro()
        super().take_damage(amount, kind)

    def on_update(self, dt: float):
        super().on_update(dt)
        if not self.aggroed:
            ship = self.player_ship()
            if ship is not None and self.distance_to(ship) <= SCREAMER_AGGRO_RANGE:
                self.aggro()
            return
        if self.screamed:
            return
        self._aggro_elapsed += dt
        if self._aggro_elapsed >= balance.SCREAMER_AGGRO_TIMER_S:
            self.screamed = True
            self.screamer_screamed()

    def on_fixed_update(self, dt: float):
        if not self.aggroed:
            return
        ship = self.player_ship()
        if ship is None:
            return
        away = self.plane_position - to_plane(ship.position)
        distance = math.hypot(float(away.x), float(away.y))
        if distance >= SCREAMER_FLEE_DISTANCE:
            self.move(dt, Vec2(0.0, 0.0), 0.0)
            return
        direction = Vec2(1.0, 0.0) if distance <= 1e-6 else Vec2(float(away.x) / distance, float(away.y) / distance)
        self.move(dt, direction, self.SPEED)
        self.face(direction)


# ============================================================================
# Husk turret
# ============================================================================


class HuskTurret(AdvancedEnemy):
    """A dead hull's gun emplacement: terrain that shoots.

    It cannot move. Idle, the beam oscillates across
    :data:`HUSK_TURRET_SWEEP_ARC` around its rest heading; with the ship inside
    :data:`HUSK_TURRET_BEAM_RANGE` it pulls onto the target at
    :data:`HUSK_TURRET_TRACK_RATE`. Coming on target runs the standard telegraph
    and only then lights the beam, which damages ``spec.damage`` per
    :data:`HUSK_TURRET_TICK_S` tick for as long as it stays on you. Breaking the
    beam's line therefore matters more than out-running it.
    """

    ARCHETYPE = "husk_turret"
    SPEED = 0.0
    HITBOX_RADIUS = 2.2

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.rest_heading = 0.0
        self.beam_heading = 0.0
        self.beam_active = False
        self.beam: PlaneBeam | None = None
        self._barrel: Node3D | None = None
        self._sweep_phase = 0.0
        self._tick_accumulator = 0.0
        self.stagger_cadence()

    def stagger_cadence(self) -> None:
        """Enter the idle sweep at a random point of its cycle.

        Two turrets covering the same corridor otherwise sweep as one gate that
        is either open or shut, instead of as two beams a player can time.
        """
        self._sweep_phase = self.cadence_offset(2.0 * math.pi)

    def build_body(self):
        self.add_child(artkit.build_enemy("husk_turret"))
        # The barrel is a build of its own because it swivels: the drum below
        # it is a dead hull and never turns.
        self._barrel = self.add_child(Node3D(name="Barrel", position=Vec3(0.0, HUSK_TURRET_BARREL_HEIGHT, 0.0)))
        self._barrel.add_child(artkit.build_turret_barrel())
        self.beam = self.mount_beam("Beam")

    @property
    def beam_endpoint(self) -> Vec2:
        """Where the beam terminates on the plane, for the vfx and hud passes."""
        unit = heading_vector(self.beam_heading)
        here = self.plane_position
        return Vec2(
            float(here.x) + float(unit.x) * HUSK_TURRET_BEAM_RANGE,
            float(here.y) + float(unit.y) * HUSK_TURRET_BEAM_RANGE,
        )

    def on_update(self, dt: float):
        super().on_update(dt)
        ship = self.player_ship()
        if ship is None or self.distance_to(ship) > HUSK_TURRET_BEAM_RANGE:
            self._sweep(dt)
            self._stand_down()
            self._aim_barrel()
            return
        error = self._track(ship, dt)
        self._aim_barrel()
        if abs(error) > HUSK_TURRET_BEAM_HALF_ANGLE:
            self._stand_down()
            return
        if not self.beam_active:
            self.begin_attack()
            return
        self._draw_beam()
        self._tick_accumulator += dt
        while self._tick_accumulator >= HUSK_TURRET_TICK_S:
            self._tick_accumulator -= HUSK_TURRET_TICK_S
            self.deal_damage_to(ship, self.spec.damage, "beam")

    def perform_attack(self) -> None:
        """Light the beam and land its first tick; later ticks run from ``on_update``.

        The telegraph runs to completion even if the ship slips off the beam, so
        the attack re-checks the alignment it was announced for rather than
        trusting a decision made a third of a second ago.
        """
        ship = self.player_ship()
        if ship is None or self.distance_to(ship) > HUSK_TURRET_BEAM_RANGE:
            return
        error = wrap_angle(bearing(self.plane_position, to_plane(ship.position)) - self.beam_heading)
        if abs(error) > HUSK_TURRET_BEAM_HALF_ANGLE:
            return
        self.beam_active = True
        self._tick_accumulator = 0.0
        self._draw_beam()
        self.deal_damage_to(ship, self.spec.damage, "beam")

    # -- internals ----------------------------------------------------------

    def _draw_beam(self) -> None:
        """Light the beam down the heading it is currently damaging along."""
        if self.beam is not None:
            self.beam.draw_between(self.plane_position, self.beam_endpoint)

    def _sweep(self, dt: float) -> None:
        self._sweep_phase += HUSK_TURRET_SWEEP_RATE * dt
        offset = math.sin(self._sweep_phase) * HUSK_TURRET_SWEEP_ARC * 0.5
        self.beam_heading = wrap_angle(self.rest_heading + offset)

    def _track(self, ship, dt: float) -> float:
        """Turn the beam toward *ship*; returns the residual angular error."""
        wanted = bearing(self.plane_position, to_plane(ship.position))
        error = wrap_angle(wanted - self.beam_heading)
        step = HUSK_TURRET_TRACK_RATE * dt
        self.beam_heading = wrap_angle(self.beam_heading + max(-step, min(step, error)))
        self.rest_heading = self.beam_heading
        self._sweep_phase = 0.0
        return wrap_angle(wanted - self.beam_heading)

    def _aim_barrel(self) -> None:
        if self._barrel is not None:
            self._barrel.rotation = Quat.from_euler(0.0, self.beam_heading, 0.0)

    def _stand_down(self) -> None:
        self.beam_active = False
        self._tick_accumulator = 0.0
        if self.beam is not None:
            self.beam.douse()


# ============================================================================
# Heralds
# ============================================================================


class Herald(AdvancedEnemy):
    """Shrike-spawn that pours in during the arrival window, previewing the hunter.

    Heralds orbit and lance rather than charge, which is the hunter's own attack
    language at a survivable scale. Each carries a share of its wave's Fletchings
    and emits :attr:`herald_killed` with that share when it dies, so the Roost
    ledger banks it without polling.
    """

    ARCHETYPE = "herald"
    SPEED = HERALD_SPEED
    HITBOX_RADIUS = 1.4
    BODY_COLOUR = HERALD_COLOUR

    #: Emitted once on death, carrying the Fletchings this herald was holding.
    herald_killed = Signal(int)

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.fletchings = 0
        self.lance: PlaneBeam | None = None
        self._orbit_phase = 0.0
        self._fire_cooldown = HERALD_FIRE_INTERVAL_S
        self.stagger_cadence()

    def stagger_cadence(self) -> None:
        """Spread a flight's lances out, so five heralds are not one volley."""
        self._fire_cooldown = self.cadence_offset(HERALD_FIRE_INTERVAL_S)

    def build_body(self):
        self.add_child(artkit.build_enemy("herald"))
        self.lance = self.mount_beam("Lance")

    def on_ready(self):
        super().on_ready()
        self.died.connect(self._announce_drop)

    def set_orbit_phase(self, radians: float) -> None:
        """Put this herald at a given point of the strafing orbit, so a flight fans out."""
        self._orbit_phase = float(radians)

    def on_update(self, dt: float):
        super().on_update(dt)
        if self.telegraphing:
            return
        self._fire_cooldown -= dt
        if self._fire_cooldown > 0.0:
            return
        ship = self.player_ship()
        if ship is not None and self.distance_to(ship) <= HERALD_LANCE_RANGE and self.begin_attack():
            self._fire_cooldown = HERALD_FIRE_INTERVAL_S

    def on_fixed_update(self, dt: float):
        ship = self.player_ship()
        if ship is None:
            return
        self._orbit_phase += HERALD_ORBIT_RATE * dt
        centre = to_plane(ship.position)
        wanted = Vec2(
            float(centre.x) + math.cos(self._orbit_phase) * HERALD_ORBIT_RADIUS,
            float(centre.y) + math.sin(self._orbit_phase) * HERALD_ORBIT_RADIUS,
        )
        here = self.plane_position
        direction = seek(here, wanted)
        reach = math.hypot(float(wanted.x) - float(here.x), float(wanted.y) - float(here.y))
        self.move(dt, direction, min(self.SPEED, reach / max(dt, 1e-6)))
        self.face(direction)

    def perform_attack(self) -> None:
        """Lance the ship, if it is still inside the strafing run's reach.

        The bolt is drawn along the line the damage travelled and left up for
        :data:`LANCE_TRACER_S`, which is what turns a hull point loss into an
        attack the player can locate and answer.
        """
        ship = self.player_ship()
        if ship is None or self.distance_to(ship) > HERALD_LANCE_RANGE:
            return
        if self.lance is not None:
            self.lance.draw_between(self.plane_position, to_plane(ship.position), hold_s=LANCE_TRACER_S)
        self.deal_damage_to(ship, self.spec.damage, "energy")

    def _announce_drop(self) -> None:
        self.herald_killed(int(self.fletchings))


def fletching_budget(act: int, runs_since_quill: int, rng: random.Random) -> int:
    """Fletchings one herald wave is worth, rising with the drought since your last quill."""
    low, high = balance.ACT_DROPS[act].fletchings_per_herald_wave
    if high <= 0:
        return 0
    base = rng.randint(low, high)
    rise = 1.0 + balance.FLETCHING_RATE_RISE_PER_RUN * max(0, int(runs_since_quill))
    return int(round(base * rise))


def share_out(total: int, parts: int, rng: random.Random) -> list[int]:
    """Split *total* into *parts* whole shares, scattering the remainder."""
    if parts <= 0:
        return []
    shares = [total // parts] * parts
    for index in rng.sample(range(parts), total % parts):
        shares[index] += 1
    return shares


def spawn_herald_flight(
    parent: Node3D,
    centre: Vec2,
    *,
    count: int,
    act: int = 1,
    runs_since_quill: int = 0,
    seed: int = 0,
    radius: float = HERALD_SPAWN_RADIUS,
) -> list[Herald]:
    """Tear *count* heralds in on a ring around *centre* and share the wave's Fletchings out.

    The wave's whole budget is rolled once from ``balance.ACT_DROPS`` and then
    split across the flight, so clearing every herald pays what the design tables
    promise however many arrived.
    """
    if count <= 0:
        return []
    rng = random.Random(seed)
    shares = share_out(fletching_budget(act, runs_since_quill, rng), count, rng)
    offset = rng.uniform(0.0, 2.0 * math.pi)

    flight: list[Herald] = []
    for index in range(count):
        angle = offset + index * (2.0 * math.pi / count)
        herald = Herald(name=f"Herald{index + 1}")
        herald.position = from_plane(
            Vec2(float(centre.x) + math.cos(angle) * radius, float(centre.y) + math.sin(angle) * radius)
        )
        parent.add_child(herald)
        herald.set_seed(seed + index)
        herald.fletchings = shares[index]
        herald.set_orbit_phase(angle)
        flight.append(herald)
    return flight


class HeraldFlight(Node3D):
    """Owns the herald flight's arrival window: in at ``t30``, out with the hunter.

    Add one to the run scene and it watches the hunter's telegraph ladder. On the
    :data:`HERALD_ARRIVAL_STAGE` stage it spawns a flight around the ship and
    tallies the Fletchings the flight drops; when the hunter departs, any
    survivor leaves with it. The flight is a set-piece rather than a wave, so it
    spends none of the wave composer's threat budget.
    """

    def __init__(self, *, act: int = 1, runs_since_quill: int = 0, seed: int = 0, **kwargs):
        super().__init__(**kwargs)
        self.act = act
        self.runs_since_quill = runs_since_quill
        self.seed = seed
        self.fletchings_dropped = 0
        self.heralds: list[Herald] = []
        self._hunter = None
        self._rng = random.Random(seed)

    def on_update(self, dt: float):
        self._attach_to_hunter()
        self.heralds = [h for h in self.heralds if not h.destroying and h.tree is not None]

    def on_hunter_telegraph(self, stage: str) -> None:
        """Spawn the flight when the ladder reaches the arrival window."""
        if stage == HERALD_ARRIVAL_STAGE and not self.heralds:
            self.spawn()

    def on_hunter_departed(self) -> None:
        """The flight leaves with the thing that sent it."""
        for herald in self.heralds:
            if not herald.destroying:
                herald.destroy()
        self.heralds = []

    def spawn(self) -> list[Herald]:
        """Tear a flight in around the ship and start counting its Fletchings."""
        centre = Vec2(0.0, 0.0)
        tree = self.tree
        if tree is not None:
            for ship in tree.group(Groups.SHIP):
                centre = to_plane(ship.position)
                break
        self.heralds = spawn_herald_flight(
            self,
            centre,
            count=self._rng.randint(HERALD_FLIGHT_MIN, HERALD_FLIGHT_MAX),
            act=self.act,
            runs_since_quill=self.runs_since_quill,
            seed=self.seed,
        )
        for herald in self.heralds:
            herald.herald_killed.connect(self._on_herald_killed)
        return self.heralds

    # -- internals ----------------------------------------------------------

    def _on_herald_killed(self, fletchings: int) -> None:
        self.fletchings_dropped += int(fletchings)

    def _attach_to_hunter(self) -> None:
        tree = self.tree
        if self._hunter is not None or tree is None:
            return
        for hunter in tree.group(Groups.HUNTER):
            telegraph = getattr(hunter, "hunter_telegraph", None)
            if telegraph is None:
                continue
            telegraph.connect(self.on_hunter_telegraph)
            departed = getattr(hunter, "hunter_departed", None)
            if departed is not None:
                departed.connect(self.on_hunter_departed)
            self._hunter = hunter
            return


# ============================================================================
# Elite modifiers
# ============================================================================


class EliteModifier:
    """A composable wrapper that re-skins any enemy without subclassing it.

    Attaching replaces the enemy's bound ``take_damage`` with the modifier's own
    and subscribes to its ``died`` signal, so the modifier sees every hit and the
    death that ends the chain without the archetype knowing it exists. Modifiers
    therefore nest: attach two and the second filters first, and both still get
    their :meth:`on_killed`. That is why the same three apply to a mite shoal and
    to a herald.
    """

    #: Matches an entry in ``balance.ELITE_MODIFIERS``.
    id: str = ""

    def __init__(self):
        self.enemy = None
        self._inner = None

    def attach(self, enemy: Enemy) -> EliteModifier:
        """Wrap *enemy*, returning this modifier so callers can hold or chain it.

        Attaching normalises ``max_hp`` onto the enemy first. Elites are applied
        at spawn, so whatever the archetype is carrying then is its full pool,
        and that is the number Armoured scales and Splitting divides, whether the
        hull is a single ship or an aggregate such as a mite shoal.
        """
        enemy.max_hp = float(getattr(enemy, "max_hp", enemy.hp))
        self.enemy = enemy
        self._inner = enemy.take_damage
        enemy.take_damage = self._filtered_take_damage
        modifiers = getattr(enemy, "elite_modifiers", None)
        if modifiers is None:
            modifiers = []
            enemy.elite_modifiers = modifiers
        modifiers.append(self)
        enemy.elite = self.id
        enemy.died.connect(self._on_died)
        self.on_attach(enemy)
        return self

    def _filtered_take_damage(self, amount: float, kind: str) -> None:
        self._inner(self.filter_damage(float(amount), kind), kind)

    def _on_died(self) -> None:
        if self.enemy is not None:
            self.on_killed(self.enemy)

    # -- hooks --------------------------------------------------------------

    def on_attach(self, enemy: Enemy) -> None:
        """Apply whatever this modifier changes at spawn."""

    def filter_damage(self, amount: float, kind: str) -> float:
        """Transform an incoming hit before the enemy under this wrapper sees it."""
        return amount

    def on_killed(self, enemy: Enemy) -> None:
        """React to the wrapped enemy running out of hull points."""


class Armoured(EliteModifier):
    """Plated: a bigger hull pool, and most incoming damage trimmed.

    Ballistics were built for plating and lose far less to it than energy weapons
    do, so the modifier reads a hit's ``kind`` rather than only its size. That is
    the readable answer to an Armoured elite and one of the reasons a run carries
    both economies.
    """

    id = "armoured"

    def on_attach(self, enemy: Enemy) -> None:
        enemy.max_hp = full_hp(enemy) * ELITE_ARMOURED_HP_MULT
        enemy.hp = enemy.max_hp

    def filter_damage(self, amount: float, kind: str) -> float:
        reduction = ELITE_ARMOURED_BALLISTIC_REDUCTION if kind == "ballistic" else ELITE_ARMOURED_REDUCTION
        return amount * (1.0 - reduction)


class Splitting(EliteModifier):
    """Comes apart: dying spawns :data:`ELITE_SPLIT_COUNT` smaller copies.

    The halves are the same archetype at :data:`ELITE_SPLIT_HP_FRACTION` of the
    parent's pool and carry no modifier of their own, so a split never cascades
    and the threat budget stays honest.
    """

    id = "splitting"

    def on_killed(self, enemy: Enemy) -> None:
        parent = enemy.parent
        if parent is None or enemy.tree is None:
            return
        rng = getattr(enemy, "rng", None) or random.Random()
        pool = full_hp(enemy) * ELITE_SPLIT_HP_FRACTION
        here = to_plane(enemy.position)
        spread = rng.uniform(0.0, 2.0 * math.pi)
        for index in range(ELITE_SPLIT_COUNT):
            angle = spread + index * (2.0 * math.pi / ELITE_SPLIT_COUNT)
            half = type(enemy)(name=f"{enemy.name}Split{index + 1}")
            half.position = Vec3(
                float(here.x) + math.cos(angle) * ELITE_SPLIT_SCATTER,
                PLANE_Y,
                float(here.y) + math.sin(angle) * ELITE_SPLIT_SCATTER,
            )
            parent.add_child(half)
            half.max_hp = pool
            half.hp = pool
            half.elite = None


class EmpLaced(EliteModifier):
    """Wired to burst: dying dumps the ship's capacitor if it is standing close.

    The drain runs through :class:`PowerSystem` like any other spend, so a fat
    capacitor, a running generator and silent running all change what the burst
    actually costs.
    """

    id = "emp_laced"

    def on_killed(self, enemy: Enemy) -> None:
        tree = enemy.tree
        if tree is None:
            return
        power = tree.singletons.get(Services.POWER)
        ship = next((node for node in tree.group(Groups.SHIP) if not node.destroying), None)
        if power is None or ship is None:
            return
        here = to_plane(enemy.position)
        there = to_plane(ship.position)
        if math.hypot(float(there.x) - float(here.x), float(there.y) - float(here.y)) > ELITE_EMP_RADIUS:
            return
        drained = min(ELITE_EMP_CAPACITOR_DRAIN, float(power.capacitor))
        if drained > 0.0:
            power.request(drained, "elite_emp")


#: Every elite modifier in ``balance.ELITE_MODIFIERS``, by id.
ELITE_MODIFIER_TYPES: dict[str, type[EliteModifier]] = {
    Armoured.id: Armoured,
    Splitting.id: Splitting,
    EmpLaced.id: EmpLaced,
}


def apply_elite(enemy: Enemy, modifier_id: str) -> EliteModifier:
    """Wrap *enemy* in the named modifier and return the wrapper.

    Raises :class:`KeyError` for an id outside ``balance.ELITE_MODIFIERS``: a
    typo that silently produced a plain enemy is the kind of bug a wave composer
    hides for weeks.
    """
    modifier_type = ELITE_MODIFIER_TYPES.get(modifier_id)
    if modifier_type is None:
        known = ", ".join(sorted(ELITE_MODIFIER_TYPES))
        raise KeyError(f"unknown elite modifier {modifier_id!r}; expected one of {known}")
    return modifier_type().attach(enemy)


#: The advanced archetypes by their ``balance.ENEMIES`` id.
ARCHETYPES: dict[str, type[AdvancedEnemy]] = {
    Welder.ARCHETYPE: Welder,
    Bombardier.ARCHETYPE: Bombardier,
    Screamer.ARCHETYPE: Screamer,
    HuskTurret.ARCHETYPE: HuskTurret,
    Herald.ARCHETYPE: Herald,
}