shrike/hunter.py

Part of SHRIKE.

"""The Shrike: the segmented hunter the whole economy is priced against.

Two nodes share the work. :class:`HunterDirector` sits in the run scene for the
whole run: it consumes ``SIGNATURE_LOCKED``, counts arrivals, compresses the
warning per arrival and per biome, and spawns a :class:`Hunter` per visit. The
:class:`Hunter` is the animal itself: it runs the strict telegraph ladder,
tears in, scrambles the warp drive for the ten-second lockout, sweeps its
lantern, ramps its damage the longer it is tolerated, breaks off to devour
jettisoned scrap, cracks the sector open fifteen seconds in, and leaves when
the player does.

The ladder never skips a stage and never depends on hearing: every stage is a
signal (``HUNTER_TELEGRAPH`` with ``"t60"``, ``"t30"``, ``"t0"``) that the
audio director voices and the HUD subtitles. Escalation compresses the warning
only; the lockout choreography, the quill window and the fight itself are the
same on the tenth arrival as on the first.
"""

import math
import random

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

from . import balance
from .artkit import build_shrike_segment, palette
from .hud import COLOUR_WARNING
from .power import SignalWiring
from .runtime import PLANE_Y, Groups, Layers, Services, SignalNames, heading_to_direction
from .sector import SECTOR_RADIUS
from .ship import AFTERBURNER_SPEED_MULT, CRUISE_SPEED, SHIP_LENGTH_UNITS, wrap_angle
from .vfx import LANTERN_OUTER_CONE_DEGREES, LANTERN_RANGE, VISIBLE_REACH_UNITS, LanternCone, Vfx

# ============================================================================
# Numbers the design fixes by feel rather than by table; balance.py carries no
# name for them yet, so they live here and are flagged for the balance pass.
# ============================================================================

#: Cruise speed: 115 percent of the player's afterburner ceiling, per design.
SHRIKE_SPEED = balance.SHRIKE_CRUISE_SPEED_MULT * CRUISE_SPEED * AFTERBURNER_SPEED_MULT
#: The wide turn arc, radians per second. Escape is angular, never linear.
SHRIKE_TURN_RATE_RADIANS_PER_S = 0.9
#: Body segments including the lantern head; total length is the design's
#: eight player-ship lengths, so spacing falls out of the count.
SHRIKE_SEGMENT_COUNT = 8
SEGMENT_SPACING = balance.SHRIKE_LENGTH_MULT * SHIP_LENGTH_UNITS / (SHRIKE_SEGMENT_COUNT - 1)
#: Which body segments carry a shearable fin (and therefore a Quill).
FIN_SEGMENT_INDICES = (2, 3, 4, 5)
FIN_HIT_RADIUS = 1.6
HEAD_HIT_RADIUS = 2.2
#: Inside this range the eel banks into an orbit instead of ramming.
ORBIT_STANDOFF_UNITS = 22.0
#: How long the lantern burns after the one-second dim, and the gap between
#: sweeps while it re-tracks the ship.
LANTERN_BURN_S = 0.75
LANTERN_COOLDOWN_S = 1.75
#: Delay before the first sweep of an arrival, so the tear-in reads first.
LANTERN_FIRST_TRACK_S = 0.5
#: How fast the doused cone re-tracks the ship between sweeps, radians per
#: second. The pre-burn dim locks the aim, which is what makes it dodgeable.
LANTERN_TRACK_RATE_RADIANS_PER_S = 1.8
#: One tap of jettison dumps this much carried scrap to the devourer.
JETTISON_CHUNK_SCRAP = 40.0

#: Where the tear-in lands, as a fraction of :data:`~shrike.vfx.VISIBLE_REACH_UNITS`,
#: the radius of what the pilot can see: just inside the edge of it.
#:
#: This used to be a flat 55 units and it was the single worst defect in the
#: game. The visible field is a little under 25 units across from the hull, so
#: the beast tore in two screens away, closed to within its 46-unit lantern
#: reach while still off screen, and burned the ship to death from somewhere
#: the player could not look. A blind playtest died to it having never once
#: seen the thing that killed it. The Shrike is eight ship-lengths of animal
#: and the arrival is meant to be the wave: it arrives on screen.
ARRIVAL_SCREEN_FRACTION = 0.88
ARRIVAL_DISTANCE_UNITS = VISIBLE_REACH_UNITS * ARRIVAL_SCREEN_FRACTION
#: Close enough to a scrap dump to stop and devour.
FEED_REACH_UNITS = 6.0
#: Seconds a departing hunter keeps swimming before the node is freed. The
#: grace is the beast leaving somewhere the pilot can still watch it leave, so
#: it only means anything inside the sector where it was seen; see
#: :meth:`Hunter.depart`.
DEPART_FREE_S = 3.0
#: Visual bob amplitude of the trailing segments, world units off the plane.
SEGMENT_BOB_UNITS = 0.35

#: What the death ledger calls a hull the lantern finished, and what it calls
#: one the Shrike took by anything else. A death with the beast in the sector
#: is its death either way; which of the two is on the headline is the
#: difference between "it got me" and "the beam got me, and I could have moved".
LANTERN_BLOW_ID = "shrike_lantern"
HUNTER_BLOW_ID = "hunter"
#: The label a burn floats off the hull, so the price is read once rather than
#: inferred from a gauge that dropped while the pilot was looking elsewhere.
LANTERN_BURN_LABEL = "LANTERN BURN"
#: How long the burn's label stays up. Much longer than an ordinary float,
#: because this one has to outlive the flare that delivered it: the cone is
#: white for :data:`LANTERN_BURN_S` and a label the same length as the flash is
#: a label nobody ever read a whole line of.
LANTERN_BURN_LABEL_HOLD_S = 3.0
#: Where the label is planted, as a sideways step off the burning cone's axis.
#: The label used to hang on the ship, which is the cone's target and the
#: brightest patch on the screen for the whole of its life; stepping along the
#: axis is no better, because the cone widens as it goes. So the step is
#: across: past the cone's own radius at the ship's range, plus clearance, and
#: bounded so the label stays inside the pilot's foveal zone at any range.
LANTERN_BURN_LABEL_CLEARANCE_UNITS = 2.5
LANTERN_BURN_LABEL_MIN_UNITS = 4.0
LANTERN_BURN_LABEL_MAX_UNITS = 9.0
#: The cue a landed burn sounds. It borrowed the klaxon for a while, which is
#: the hull's own alarm and says nothing about what did the burning: the caption
#: track read "KLAXON" and then "HULL BREACHED" and never once named the animal.
#: :data:`audio.CUES` now carries a burn of its own, captioned LANTERN BURN, so
#: the heaviest single blow in the game is a sound a muted mix can still read.
LANTERN_BURN_CUE = "lantern_burn"
#: How long a burn stays the blow worth naming. A hull that dies half a minute
#: after the last burn died of something else, and saying otherwise is how a
#: ledger stops being read.
LANTERN_BLOW_WINDOW_S = 3.0


class FinSegment(Node3D):
    """One shearable fin: 250 HP behind plating, and a Quill when it goes.

    Fins are the only part of the Shrike that yields to damage; the body is
    armour. Plating (``balance.SHRIKE_FIN_DAMAGE_TAKEN_MULT``) belongs to the
    damage router, which trims every hunter-side number before forwarding it,
    so what arrives here is already plated and lands on the pool untouched.
    Applying the multiplier a second time here would put a fin nine times
    behind its 250-point pool and blow the 15-second shear band.
    """

    HITBOX_RADIUS = FIN_HIT_RADIUS

    def __init__(self, hunter: Hunter, segment_index: int, **kwargs):
        super().__init__(**kwargs)
        self._hunter = hunter
        self.segment_index = int(segment_index)
        self.hp: float = balance.SHRIKE_FIN_HP
        self.sheared = False

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

    def on_ready(self):
        accent = palette("hunter").accent
        self.add_child(
            MeshInstance3D(
                name="FinBlade",
                mesh=Mesh.cone(radius=0.5, height=2.2, segments=6),
                material=Material(colour=(*accent[:3], 1.0), emissive_colour=accent[:3], emissive_strength=1.6),
                rotation=Quat.from_euler(0.0, 0.0, math.radians(90.0)),
            )
        )
        self.add_child(
            Area3D(
                name="FinHitbox",
                shape=SphereShape3D(radius=FIN_HIT_RADIUS),
                collision_layer=Layers.HUNTER,
                collision_mask=Layers.SHIP | Layers.TERRAIN,
            )
        )

    def take_damage(self, amount: float, kind: str = "impact") -> None:
        """Take a hit the router has already trimmed through the fin's plating."""
        if self.sheared:
            return
        self.hp -= float(amount)
        if self.hp <= 0.0:
            self.hp = 0.0
            self.sheared = True
            self._hunter._on_fin_sheared(self)
            self.destroy()


class Hunter(Node3D):
    """The Shrike itself: ladder, lockout, lantern, fins, feeding and leash.

    Spawned by :class:`HunterDirector` when the sector's signature locks. The
    node's position is the lantern head; the trailing segments are children
    chained behind it, free to bob off the flight plane while every gameplay
    test stays on it.
    """

    hunter_telegraph = Signal(str)
    hunter_arrived = Signal(int)
    hunter_lockout_ended = Signal()
    hunter_fed = Signal(float, float)
    hunter_departed = Signal()
    quill_sheared = Signal(int)
    sector_cracked = Signal()
    #: (amount: float, direction: Vec3) toward the lantern that burned the ship.
    #:
    #: The same ``PLAYER_DAMAGED`` every other source of hull damage announces,
    #: and the reason it is emitted here rather than by the damage router is in
    #: :meth:`_burn_ship`: the burn's hull maths is deliberately directionless
    #: so the shield arc covers no bearing for it, and a directionless hit is
    #: the one value every consumer of the signal drops. The hull keeps its
    #: bearing-free resolution; the pilot gets a bearing to look down.
    player_damaged = Signal(float, Vec3)

    HITBOX_RADIUS = HEAD_HIT_RADIUS

    def __init__(self, *, seed: int = 0, **kwargs):
        super().__init__(**kwargs)
        self.seed = int(seed)
        self.state = "idle"  # "idle" | "approaching" | "present" | "departing"
        self.arrival_index = 0
        self.quills_this_run = 0
        #: Bearing from the ship toward where the tear-in will happen, for the
        #: compass edge glow. Set when the ladder starts.
        self.approach_bearing = 0.0
        #: Last ladder stage emitted, for the HUD's countdown framing.
        self.telegraph_stage: str | None = None
        self.telegraph_remaining = 0.0

        self.lantern: LanternCone | None = None
        self.fins: list[FinSegment] = []

        self._heading = 0.0
        self._lantern_heading = 0.0
        self._lantern_phase = "track"  # "track" | "preburn" | "burn"
        self._lantern_timer = LANTERN_FIRST_TRACK_S
        self._burn_landed = False
        self._blackout_remaining = 0.0
        self._blow_remaining = 0.0

        self._ramp_start = 0.0
        self._present_s = 0.0
        self._lockout_remaining = 0.0
        self._lockout_ended_sent = False
        self._crack_remaining = 0.0
        self._crack_sent = False
        self._t30_sent = False
        self._feed_remaining = 0.0
        self._feed_point = (0.0, 0.0)
        self._depart_remaining = 0.0
        self._orbit_sign = 1.0
        self._time = 0.0
        self._chain: list[tuple[float, float]] = []
        self._segments: list[Node3D] = []

    # ------------------------------------------------------------------ setup

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

    def on_ready(self):
        self.add_child(
            Area3D(
                name="HeadHitbox",
                shape=SphereShape3D(radius=HEAD_HIT_RADIUS),
                collision_layer=Layers.HUNTER,
                collision_mask=Layers.SHIP | Layers.TERRAIN,
            )
        )
        self.lantern = self.add_child(LanternCone(name="Lantern"))
        for index in range(SHRIKE_SEGMENT_COUNT):
            segment = self.add_child(Node3D(name=f"Segment{index}"))
            art = build_shrike_segment(index, seed=self.seed)
            # The art kit builds along +X; a quarter turn brings it onto the
            # local -Z that face_along aims.
            art.rotation = Quat.from_axis_angle(Vec3(0.0, 1.0, 0.0), math.pi * 0.5)
            segment.add_child(art)
            if index in FIN_SEGMENT_INDICES:
                side = 1.0 if (index % 2) else -1.0
                fin = segment.add_child(
                    FinSegment(self, index, name=f"Fin{index}", position=Vec3(side * 1.1, 0.0, 0.0))
                )
                self.fins.append(fin)
            self._segments.append(segment)
        self._reset_chain()

    # ------------------------------------------------------------- public API

    def begin_approach(self, arrival_index: int, telegraph_s: float) -> None:
        """Start the telegraph ladder: *telegraph_s* seconds until the tear-in.

        The first stage fires immediately; the klaxon stage fires at T-30, or
        together with the first stage when the whole warning has been
        compressed or muffled inside it. Stage identities never change, only
        their timing.
        """
        self.arrival_index = int(arrival_index)
        self._ramp_start = balance.SHRIKE_RAMP_START_LATER_ARRIVALS if self.arrival_index >= 3 else 0.0
        self.state = "approaching"
        self.telegraph_remaining = float(telegraph_s)
        self._t30_sent = False
        self._stage_ship()
        self._emit_stage("t60")
        if self.telegraph_remaining <= balance.SHRIKE_TELEGRAPH_KLAXON_S:
            self._t30_sent = True
            self._emit_stage("t30")

    def depart(self, *, immediate: bool = False) -> None:
        """Break off and leave. Emits ``HUNTER_DEPARTED`` once, immediately.

        The body then swims off for :data:`DEPART_FREE_S` before the node is
        freed, which is the beast leaving rather than the beast blinking out.
        *immediate* frees it in place instead, for the caller whose reason for
        departing is that the world underneath it has been replaced: after a
        jump the swim happens in the new sector, at the old sector's
        coordinates, trailing fins and a lit lantern cone, and whether it
        crosses the arrival screen is a matter of where the two anchors
        happened to fall.
        """
        if self.state == "departing" or self.destroying:
            return
        self.state = "departing"
        self._depart_remaining = DEPART_FREE_S
        self._set_lantern_idle()
        ship = self._ship()
        if ship is not None:
            ship.warp_scrambled = False
        self.hunter_departed()
        if immediate:
            self.destroy()

    def feed(self, scrap: float) -> None:
        """Devour *scrap* jettisoned at the ship's position; buys escape time.

        Rate is ``balance.SHRIKE_FEED_SECONDS_PER_SCRAP`` (about eight seconds
        per forty scrap). Feeding stacks: two dumps buy two windows.
        """
        scrap = float(scrap)
        if scrap <= 0.0 or self.state != "present":
            return
        seconds = scrap * balance.SHRIKE_FEED_SECONDS_PER_SCRAP
        ship = self._ship()
        if ship is not None:
            self._feed_point = (float(ship.position.x), float(ship.position.z))
        else:
            self._feed_point = (float(self.position.x), float(self.position.z))
        self._feed_remaining += seconds
        self._set_lantern_idle()
        self.hunter_fed(scrap, seconds)

    def take_damage(self, amount: float, kind: str = "impact") -> None:
        """Body shots ping off the armoured hull; only the fins yield."""

    def damage_multiplier(self) -> float:
        """The soft enrage: +20 percent per ten seconds present, no cap.

        Third and later arrivals start already ramped, so re-ringing the bell
        is what gets dearer, never standing your ground.
        """
        intervals = int(self._present_s / balance.SHRIKE_RAMP_INTERVAL_S)
        return 1.0 + self._ramp_start + balance.SHRIKE_RAMP_FRACTION * intervals

    @property
    def approach(self) -> tuple[float, float] | None:
        """``(seconds, bearing)`` while inbound, or None when it is not.

        The HUD's countdown and its approach marker read this: the telegraph
        signal carries a stage name and nothing else, and a stage name is not a
        clock. Bearing is the one the tear-in will land on, so the marker
        points at the place rather than in a general direction.
        """
        if self.state != "approaching":
            return None
        return (max(0.0, self.telegraph_remaining), self.approach_bearing)

    @property
    def last_blow(self) -> str:
        """The blow the death ledger should name if the hull dies right now.

        Valid mid-death: the burn writes it before the hull resolves the hit,
        exactly as ``DamageRouter.last_ship_hit_by`` is written before the
        router forwards one, so it is already true inside the
        ``SHIP_DESTROYED`` emitted from within that resolution. It falls back
        to the animal itself once the burn is :data:`LANTERN_BLOW_WINDOW_S`
        old, because a hull that dies long after the last beam died of
        something else.
        """
        return LANTERN_BLOW_ID if self._blow_remaining > 0.0 else HUNTER_BLOW_ID

    @property
    def lockout_active(self) -> bool:
        """True during the ten-second scramble after the tear-in."""
        return self.state == "present" and self._lockout_remaining > 0.0

    @property
    def feeding(self) -> bool:
        """True while it is breaking off to devour jettisoned scrap."""
        return self.state == "present" and self._feed_remaining > 0.0

    @property
    def fins_remaining(self) -> int:
        return sum(1 for fin in self.fins if not fin.sheared)

    # ------------------------------------------------------------------ frames

    def on_update(self, dt: float):
        self._time += dt
        if self.state == "approaching":
            self._tick_telegraph(dt)
        elif self.state == "present":
            self._tick_present(dt)
        elif self.state == "departing":
            self._depart_remaining -= dt
            if self._depart_remaining <= 0.0:
                self.destroy()

    def on_fixed_update(self, dt: float):
        if self.state == "present":
            self._swim(dt)
            self._clamp_to_leash()
        elif self.state == "departing":
            self._advance(self._heading, dt)
        else:
            return
        self._update_segments()

    # ---------------------------------------------------------------- telegraph

    def _tick_telegraph(self, dt: float) -> None:
        self.telegraph_remaining -= dt
        if not self._t30_sent and self.telegraph_remaining <= balance.SHRIKE_TELEGRAPH_KLAXON_S:
            self._t30_sent = True
            self._emit_stage("t30")
        if self.telegraph_remaining <= 0.0:
            self.telegraph_remaining = 0.0
            self._arrive()

    def _emit_stage(self, stage: str) -> None:
        self.telegraph_stage = stage
        self.hunter_telegraph(stage)

    def _stage_ship(self) -> None:
        """Pick the approach vector and hold off-sector until the tear-in."""
        rng = random.Random(self.seed * 1_000_003 + self.arrival_index)
        self.approach_bearing = rng.uniform(0.0, math.tau)
        anchor = self._ship_plane() or (0.0, 0.0)
        direction = heading_to_direction(self.approach_bearing)
        distance = SECTOR_RADIUS * 2.0
        self.position = Vec3(
            anchor[0] + float(direction.x) * distance,
            PLANE_Y,
            anchor[1] + float(direction.z) * distance,
        )
        self._heading = wrap_angle(self.approach_bearing + math.pi)
        self._reset_chain()

    def _arrive(self) -> None:
        """T-0: the lens tears, on screen, and the arrival is the wave.

        The tear-in is placed inside the pilot's own visible field
        (:data:`ARRIVAL_DISTANCE_UNITS`) so the thing that has been counted
        down to is the thing they are looking at when it lands. The sector
        clamp still applies and is applied first, because the leash is the
        arena's rule; the field clamp then runs over the top of it, so a pilot
        who has flown out past the boundary still watches the arrival happen
        rather than hearing about it.
        """
        anchor = self._ship_plane() or (0.0, 0.0)
        direction = heading_to_direction(self.approach_bearing)
        x = anchor[0] + float(direction.x) * ARRIVAL_DISTANCE_UNITS
        z = anchor[1] + float(direction.z) * ARRIVAL_DISTANCE_UNITS
        reach = math.hypot(x, z)
        if reach > SECTOR_RADIUS:
            x, z = x / reach * SECTOR_RADIUS, z / reach * SECTOR_RADIUS
        offset = math.hypot(x - anchor[0], z - anchor[1])
        if offset > ARRIVAL_DISTANCE_UNITS:
            pull = ARRIVAL_DISTANCE_UNITS / offset
            x = anchor[0] + (x - anchor[0]) * pull
            z = anchor[1] + (z - anchor[1]) * pull
        self.position = Vec3(x, PLANE_Y, z)
        self._heading = wrap_angle(self.approach_bearing + math.pi)
        self._lantern_heading = self._heading
        self._reset_chain()

        self.state = "present"
        self._present_s = 0.0
        self._lockout_remaining = balance.SHRIKE_LOCKOUT_S
        self._lockout_ended_sent = False
        self._crack_remaining = balance.SHRIKE_CRACK_OPEN_S
        self._crack_sent = False
        self._lantern_phase = "track"
        self._lantern_timer = LANTERN_FIRST_TRACK_S
        self._blow_remaining = 0.0
        self._set_lantern("sweep")

        if self.tree is not None:
            Vfx.spawn(self.tree, "warp_implosion", Vec3(x, PLANE_Y, z))
        ship = self._ship()
        if ship is not None:
            ship.cancel_warp_spool()
            ship.warp_scrambled = True

        self._emit_stage("t0")
        self.hunter_arrived(self.arrival_index)

    # ------------------------------------------------------------------ present

    def _tick_present(self, dt: float) -> None:
        self._present_s += dt

        if self._lockout_remaining > 0.0:
            self._lockout_remaining -= dt
            if self._lockout_remaining <= 0.0 and not self._lockout_ended_sent:
                self._lockout_ended_sent = True
                ship = self._ship()
                if ship is not None:
                    ship.warp_scrambled = False
                self.hunter_lockout_ended()

        if not self._crack_sent:
            self._crack_remaining -= dt
            if self._crack_remaining <= 0.0:
                self._crack_sent = True
                self.sector_cracked()

        if self._feed_remaining > 0.0:
            self._feed_remaining = max(0.0, self._feed_remaining - dt)
            if self._feed_remaining <= 0.0:
                self._set_lantern("sweep")  # done eating, and hunting again visibly
        else:
            self._tick_lantern(dt)

        self._blow_remaining = max(0.0, self._blow_remaining - dt)
        self._tick_blackout(dt)
        self._tick_jettison()

    def _tick_jettison(self) -> None:
        """A tap of jettison dumps a chunk of carried scrap as bait."""
        if not Input.is_action_just_pressed("jettison_scrap"):
            return
        tree = self.tree
        economy = tree.singletons.get(Services.ECONOMY) if tree is not None else None
        if economy is None:
            return
        amount = min(JETTISON_CHUNK_SCRAP, float(getattr(economy, "scrap", 0.0)))
        if amount > 0.0 and economy.spend_scrap(amount):
            self.feed(amount)

    # ------------------------------------------------------------------ lantern

    def _tick_lantern(self, dt: float) -> None:
        ship = self._ship()
        sweep_mult = 1.0
        if ship is not None and getattr(ship.assists, "slow_lantern", False):
            sweep_mult = balance.ASSIST_LANTERN_SWEEP_MULT

        if self._lantern_phase == "track":
            self._track_ship(dt * sweep_mult)
            self._lantern_timer -= dt * sweep_mult
            if self._lantern_timer <= 0.0:
                self._lantern_phase = "preburn"
                self._lantern_timer = balance.SHRIKE_LANTERN_PREBURN_WARNING_S
                self._set_lantern("preburn")
        elif self._lantern_phase == "preburn":
            self._lantern_timer -= dt
            if self._lantern_timer <= 0.0:
                self._lantern_phase = "burn"
                self._lantern_timer = LANTERN_BURN_S
                self._burn_landed = False
                self._set_lantern("burn")
        elif self._lantern_phase == "burn":
            if not self._burn_landed and self._ship_in_cone():
                self._burn_landed = True
                self._burn_ship()
            self._lantern_timer -= dt
            if self._lantern_timer <= 0.0:
                self._lantern_phase = "track"
                self._lantern_timer = LANTERN_COOLDOWN_S
                self._set_lantern("sweep")

    def _track_ship(self, dt: float) -> None:
        target = self._ship_plane()
        if target is None:
            return
        bearing = self._bearing_to(target)
        if bearing is None:
            return
        delta = wrap_angle(bearing - self._lantern_heading)
        step = max(-LANTERN_TRACK_RATE_RADIANS_PER_S * dt, min(LANTERN_TRACK_RATE_RADIANS_PER_S * dt, delta))
        self._lantern_heading = wrap_angle(self._lantern_heading + step)
        if self.lantern is not None:
            self.lantern.aim_at(heading_to_direction(self._lantern_heading))

    def _ship_in_cone(self) -> bool:
        """Whether the burn would land, which needs the head to be on screen.

        The cone is drawn to :data:`~shrike.vfx.LANTERN_RANGE` and burns to the
        same number, and that number is the pilot's own visible reach: nothing
        the player cannot see is allowed to hurt them. Without the second half
        of that rule the beast could sit off screen and burn.
        """
        target = self._ship_plane()
        if target is None:
            return False
        dx = target[0] - float(self.position.x)
        dz = target[1] - float(self.position.z)
        distance = math.hypot(dx, dz)
        if distance > min(LANTERN_RANGE, VISIBLE_REACH_UNITS) or distance < 1e-6:
            return False
        bearing = math.atan2(-dz, dx)
        return abs(wrap_angle(bearing - self._lantern_heading)) <= math.radians(LANTERN_OUTER_CONE_DEGREES)

    def _burn_ship(self) -> None:
        """A clean hit: 35 hull scaled by the ramp, plus the capacitor blackout.

        The burn is an enveloping wash of light, not a bearing-aligned shot, so
        it lands as a directionless hit: the shield arc covers no bearing for
        it and the only defence is not being in the cone. Spool lengthening and
        breach bookkeeping still run through the ship's one damage path.

        Everything after the hull is the hit becoming legible. The blow is
        named before the hull resolves it, because a fatal burn emits
        ``SHIP_DESTROYED`` from inside ``apply_damage`` and the ledger reads
        the name during that emission. Then the pilot is told twice:
        ``PLAYER_DAMAGED`` on the bearing of the lantern, which is what the
        screen-edge desaturation and the feel layer's trauma are spent on, and
        a label floated off the hull carrying the number. Neither existed, and
        the burn was therefore silent: 35 hull left the gauge with no cue of
        any kind, which is how a run could end to an animal in plain sight
        that appeared never to attack.
        """
        ship = self._ship()
        if ship is None:
            return
        self._blow_remaining = LANTERN_BLOW_WINDOW_S
        before = float(getattr(ship, "hull", 0.0))
        ship.apply_damage(
            balance.SHRIKE_LANTERN_HULL_DAMAGE * self.damage_multiplier(), Vec3(0.0, 0.0, 0.0), kind="lantern"
        )
        self._black_out_capacitor(ship)
        landed = max(0.0, before - float(getattr(ship, "hull", 0.0)))
        if landed <= 0.0:
            return
        self.player_damaged(landed, self._bearing_from_ship(ship))
        self._float_burn_cost(ship, landed)
        self._sound_burn(ship)

    def _black_out_capacitor(self, ship) -> None:
        """Drop the bus for the blackout second, as one state rather than a drain.

        The hold belongs to the power system: it is the only code that knows
        what the sources are putting back in, and holding the tank down from
        out here meant spending the charge one frame and watching it refill the
        next. A system without the hold keeps the old behaviour.
        """
        power = getattr(ship, "power", None)
        seconds = balance.SHRIKE_LANTERN_CAPACITOR_BLACKOUT_S
        if power is not None and hasattr(power, "begin_blackout"):
            power.begin_blackout(seconds)
            self._blackout_remaining = 0.0
            return
        self._blackout_remaining = seconds

    def _sound_burn(self, ship) -> None:
        """Put the burn on the audio track, where a pilot looking away hears it.

        The klaxon is the hull's own alarm and it captions on the HUD's plate,
        so a muted mix reads the hit too. It is deliberately the loudest thing
        the game says: quieter cues were reported as no cue at all.
        """
        tree = self.tree
        director = tree.singletons.get(Services.AUDIO) if tree is not None else None
        if director is None or not hasattr(director, "play"):
            return
        director.play(LANTERN_BURN_CUE, position=Vec3(ship.position))

    def _bearing_from_ship(self, ship) -> Vec3:
        """Unit vector from the ship toward this head, the cue's convention.

        Every consumer of ``PLAYER_DAMAGED`` reads the direction as "where the
        threat is", so the arrow, the desaturated edge and the punch all point
        at the animal rather than away from it.
        """
        dx = float(self.position.x) - float(ship.position.x)
        dz = float(self.position.z) - float(ship.position.z)
        reach = math.hypot(dx, dz)
        if reach < 1e-6:
            return heading_to_direction(self._lantern_heading)
        return Vec3(dx / reach, 0.0, dz / reach)

    def _burn_label_position(self, ship) -> Vec3:
        """Where the burn's label is planted: beside the cone, not inside it.

        Anchoring it to the ship put the one line that names the blow at the
        cone's aim point, so it spent its whole life being erased by the flare
        that had just delivered it. The label steps across the cone's axis by
        more than the cone's own radius at this range, and takes whichever of
        the two perpendiculars reads higher up the screen (-Z), so it lands on
        dark space above the hull rather than under it.
        """
        sx, sz = float(ship.position.x), float(ship.position.z)
        dx, dz = sx - float(self.position.x), sz - float(self.position.z)
        reach = math.hypot(dx, dz)
        if reach < 1e-6:
            return Vec3(sx, PLANE_Y, sz - LANTERN_BURN_LABEL_MIN_UNITS)
        radius = reach * math.tan(math.radians(LANTERN_OUTER_CONE_DEGREES))
        clear = radius + LANTERN_BURN_LABEL_CLEARANCE_UNITS
        step = min(LANTERN_BURN_LABEL_MAX_UNITS, max(LANTERN_BURN_LABEL_MIN_UNITS, clear))
        px, pz = -dz / reach, dx / reach
        if pz > 0.0:
            px, pz = -px, -pz
        return Vec3(sx + px * step, PLANE_Y, sz + pz * step)

    def _float_burn_cost(self, ship, landed: float) -> None:
        """Put the price on the hull in words, once, where the pilot is looking.

        On a plate and for :data:`LANTERN_BURN_LABEL_HOLD_S`, because this
        label is written into a flood of white light and an ordinary float is
        neither backed nor long enough to survive one. Planted in the world
        rather than pinned to the hull, so it marks where the burn landed and
        stays put while the pilot flies out of the cone.

        The caption is not raised here: every cue :meth:`_sound_burn` plays is
        announced on the audio director's ``audio_cue`` signal and the HUD
        captions that announcement itself, wherever the play came from.
        """
        tree = self.tree
        hud = tree.singletons.get(Services.HUD) if tree is not None else None
        if hud is None or not hasattr(hud, "float_text"):
            return
        hud.float_text(
            f"{LANTERN_BURN_LABEL}: {landed:.0f} HULL",
            position=self._burn_label_position(ship),
            hold_s=LANTERN_BURN_LABEL_HOLD_S,
            colour=COLOUR_WARNING,
            toward="",
            plate=True,
        )

    def _tick_blackout(self, dt: float) -> None:
        """Hold the capacitor at zero for the blackout second after a burn."""
        if self._blackout_remaining <= 0.0:
            return
        self._blackout_remaining = max(0.0, self._blackout_remaining - dt)
        ship = self._ship()
        if ship is None:
            return
        power = ship.power
        charge = float(getattr(power, "capacitor", 0.0))
        if charge > 0.0:
            power.request(charge, "lantern_blackout")

    def _set_lantern(self, phase: str) -> None:
        """Show *phase*: ``"off"``, ``"sweep"``, ``"preburn"`` or ``"burn"``.

        The sweep is lit. It used to be dark, which made the whole telegraph a
        lie: the pilot saw nothing at all, then a dim shell for one second,
        then took 35 hull. The dim only warns of a burn if there is something
        brighter for it to be dimmer than.
        """
        cone = self.lantern
        if cone is None:
            return
        cone.set_active(phase != "off")
        cone.set_preburn(phase == "preburn")
        cone.set_burn(phase == "burn")

    def _set_lantern_idle(self) -> None:
        """Douse it: feeding and departing are the two times it stops hunting."""
        self._lantern_phase = "track"
        self._lantern_timer = LANTERN_COOLDOWN_S
        self._set_lantern("off")

    # ---------------------------------------------------------------- movement

    def _swim(self, dt: float) -> None:
        if self._lantern_phase != "track" and not self.feeding:
            return  # coiled to burn: the locked cone stays where the dim promised
        if self.feeding:
            fx, fz = self._feed_point
            dx = fx - float(self.position.x)
            dz = fz - float(self.position.z)
            if math.hypot(dx, dz) <= FEED_REACH_UNITS:
                return  # devouring on the spot
            desired = math.atan2(-dz, dx)
        else:
            target = self._ship_plane()
            if target is None:
                return
            bearing = self._bearing_to(target)
            if bearing is None:
                return
            dx = target[0] - float(self.position.x)
            dz = target[1] - float(self.position.z)
            desired = bearing
            if math.hypot(dx, dz) < ORBIT_STANDOFF_UNITS:
                desired = wrap_angle(bearing + self._orbit_sign * (math.pi * 0.5 + 0.35))
        delta = wrap_angle(desired - self._heading)
        step = max(-SHRIKE_TURN_RATE_RADIANS_PER_S * dt, min(SHRIKE_TURN_RATE_RADIANS_PER_S * dt, delta))
        self._heading = wrap_angle(self._heading + step)
        self._advance(self._heading, dt)

    def _advance(self, heading: float, dt: float) -> None:
        direction = heading_to_direction(heading)
        self.position = Vec3(
            float(self.position.x) + float(direction.x) * SHRIKE_SPEED * dt,
            PLANE_Y,
            float(self.position.z) + float(direction.z) * SHRIKE_SPEED * dt,
        )

    def _clamp_to_leash(self) -> None:
        """It leashes to the sector: the arena's edge is also its cage.

        The clamp lands a hair inside the radius because ``position`` stores
        float32: rescaling to exactly SECTOR_RADIUS in float64 can round up on
        the store and leave the beast a few micro-units past its own leash.
        """
        x, z = float(self.position.x), float(self.position.z)
        reach = math.hypot(x, z)
        if reach > SECTOR_RADIUS:
            leash = SECTOR_RADIUS * (1.0 - 1e-6)
            self.position = Vec3(x / reach * leash, PLANE_Y, z / reach * leash)

    # ------------------------------------------------------------------- body

    def _reset_chain(self) -> None:
        head = (float(self.position.x), float(self.position.z))
        tail = heading_to_direction(wrap_angle(self._heading + math.pi))
        self._chain = [
            (head[0] + float(tail.x) * SEGMENT_SPACING * i, head[1] + float(tail.z) * SEGMENT_SPACING * i)
            for i in range(SHRIKE_SEGMENT_COUNT)
        ]
        self._update_segments()

    def _update_segments(self) -> None:
        """Follow-the-leader: each segment trails the one ahead at fixed spacing."""
        if not self._chain:
            return
        head = (float(self.position.x), float(self.position.z))
        self._chain[0] = head
        for i in range(1, SHRIKE_SEGMENT_COUNT):
            px, pz = self._chain[i - 1]
            cx, cz = self._chain[i]
            dx, dz = cx - px, cz - pz
            length = math.hypot(dx, dz)
            if length < 1e-6:
                dx, dz, length = SEGMENT_SPACING, 0.0, SEGMENT_SPACING
            self._chain[i] = (px + dx / length * SEGMENT_SPACING, pz + dz / length * SEGMENT_SPACING)
        for i, segment in enumerate(self._segments):
            sx, sz = self._chain[i]
            bob = 0.0 if i == 0 else math.sin(self._time * 2.0 + i * 0.9) * SEGMENT_BOB_UNITS
            segment.position = Vec3(sx - head[0], bob, sz - head[1])
            ax, az = self._chain[max(0, i - 1)]
            direction = Vec3(ax - sx, 0.0, az - sz)
            if i == 0:
                direction = heading_to_direction(self._heading)
            if math.hypot(float(direction.x), float(direction.z)) > 1e-6:
                segment.face_along(direction)

    # ------------------------------------------------------------------ lookup

    def _ship(self):
        return self.tree.get_first_in_group(Groups.SHIP) if self.tree is not None else None

    def _ship_plane(self) -> tuple[float, float] | None:
        ship = self._ship()
        if ship is None:
            return None
        return float(ship.position.x), float(ship.position.z)

    def _bearing_to(self, target: tuple[float, float]) -> float | None:
        dx = target[0] - float(self.position.x)
        dz = target[1] - float(self.position.z)
        if math.hypot(dx, dz) < 1e-6:
            return None
        return math.atan2(-dz, dx)

    # ------------------------------------------------------------------- fins

    def _on_fin_sheared(self, fin: FinSegment) -> None:
        self.quills_this_run += 1
        if self.tree is not None:
            Vfx.spawn(self.tree, "explosion", fin.world_position, faction="hunter")
        self.quill_sheared(self.quills_this_run)


class HunterDirector(Node):
    """Owns the ladder: arrival counting, compression, muffling and spawning.

    A child of the run scene, alive for the whole run. It consumes
    ``SIGNATURE_LOCKED`` to start an arrival, ``SECTOR_ENTERED`` to know the
    biome's muffling, and ``WARP_COMPLETED`` to send the hunter home when the
    player escapes. Escalation compresses the warning, never the fight: the
    second arrival warns at T-45, the third and later at T-30, and a nebula
    muffles the whole warning down to T-20 whatever the arrival count.
    """

    arrivals_this_run: int = 0

    def __init__(self, *, seed: int = 0, **kwargs):
        super().__init__(**kwargs)
        self.seed = int(seed)
        self.arrivals_this_run = 0
        self.biome_id = "debris_field"
        self.hunter: Hunter | None = None
        self._wiring = SignalWiring(self)

    def on_ready(self):
        self._wiring.want(SignalNames.SIGNATURE_LOCKED, self.on_signature_locked)
        self._wiring.want(SignalNames.SECTOR_ENTERED, self._on_sector_entered)
        self._wiring.want(SignalNames.WARP_COMPLETED, self._on_warp_completed)
        self._wiring.sweep()

    def on_update(self, dt: float):
        self._wiring.poll(dt)

    # ------------------------------------------------------------------ ladder

    def telegraph_seconds(self, arrival_index: int) -> float:
        """Warning length for the given arrival, after compression and muffling."""
        if arrival_index <= 1:
            seconds = balance.SHRIKE_TELEGRAPH_FIRST_S
        elif arrival_index == 2:
            seconds = balance.SHRIKE_TELEGRAPH_SECOND_ARRIVAL_S
        else:
            seconds = balance.SHRIKE_TELEGRAPH_LATER_ARRIVALS_S
        override = balance.BIOMES[self.biome_id].telegraph_override_s
        if override is not None:
            seconds = min(seconds, override)
        return seconds

    def on_signature_locked(self) -> None:
        """The meter hit 100: one arrival, exactly, is now inbound."""
        if self.hunter is not None and not self.hunter.destroying:
            return
        self.arrivals_this_run += 1
        parent = self.parent if self.parent is not None else self
        hunter = parent.add_child(Hunter(name="Hunter", seed=self.seed))
        hunter.hunter_departed.connect(self._on_hunter_departed)
        self.hunter = hunter
        hunter.begin_approach(self.arrivals_this_run, self.telegraph_seconds(self.arrivals_this_run))

    def set_biome(self, biome_id: str) -> None:
        """Adopt the current sector's biome for its telegraph muffling."""
        if biome_id not in balance.BIOMES:
            raise ValueError(f"Unknown biome {biome_id!r}; expected one of {', '.join(balance.BIOMES)}")
        self.biome_id = biome_id

    # ---------------------------------------------------------------- handlers

    def _on_sector_entered(self, sector_index: int, biome_id: str) -> None:
        self.set_biome(biome_id)
        # A sector is dealt once, so a beast still alive here belongs to the
        # last one. Immediate for the same reason as the jump above, and so
        # the fix does not depend on which of the two signals lands first.
        if self.hunter is not None and not self.hunter.destroying:
            self.hunter.depart(immediate=True)

    def _on_warp_completed(self, emergency: bool) -> None:
        # The hull is somewhere else now, so there is nowhere for the beast to
        # swim away to that the pilot could watch. Freed in place instead.
        if self.hunter is not None and not self.hunter.destroying:
            self.hunter.depart(immediate=True)

    def _on_hunter_departed(self) -> None:
        self.hunter = None


def killing_blow(tree) -> str:
    """Which Shrike blow the death ledger should name, for a death in its sector.

    A run that ends with the beast on screen ended because of the beast, and
    the ledger has always said so. What it could not say was *how*, so a pilot
    burned twice by a beam they never learned to read left with "the Shrike
    took you" and no lesson in it. :data:`LANTERN_BLOW_ID` is that lesson, and
    :attr:`Hunter.last_blow` is written before the hull resolves the burn, so
    it is already true inside the ``SHIP_DESTROYED`` emission the ledger reads
    it from.

    Falls back to :data:`HUNTER_BLOW_ID` when the burn is stale or the group
    holds no live hunter (a sheared fin outlives its animal for a frame, and a
    fin is not a blow).
    """
    if tree is None:
        return HUNTER_BLOW_ID
    for node in tree.group(Groups.HUNTER):
        if isinstance(node, Hunter) and not node.destroying:
            return node.last_blow or HUNTER_BLOW_ID
    return HUNTER_BLOW_ID