shrike/roost.py

Part of SHRIKE.

"""The endgame campaign: Lure fragments, Fletching pity, and the Roost duel.

Three pieces, matching design section 7's Predation ending:

:class:`LureCampaign`
    The across-runs campaign state, carried on the meta profile dictionary that
    ``save.py`` persists. Log-fragment caches from three biome types build the
    Lure blueprint; assembly costs ``balance.LURE_ASSEMBLY_SCRAP``; the
    assembled Lure puts the Roost node on the chart beside the Deep Gate and
    counts as a provocation by itself. The campaign also owns the quill gate:
    ``balance.QUILLS_TO_OPEN_ROOST`` quills are spent once to open the Roost,
    and while defeated phases persist each retry costs
    ``balance.ROOST_RETRY_QUILL_COST``.

:class:`FletchingLedger`
    The catch-up mechanism. Heralds roll a Fletching drop whose chance rises
    ``balance.FLETCHING_RATE_RISE_PER_RUN`` per run since the last quill, and
    ``balance.FLETCHINGS_PER_QUILL`` Fletchings forge a quill at any depot, so
    even a flee-only player converges on the Roost.

:class:`RoostScene`
    The three-phase duel. It opens with the exact arrival ladder every run has
    taught, and for the first time standing still is correct; there is no
    warp-out. Phase 1 is the known lantern kit at full aggression. Phase 2 eats
    the lights and hunts the player's emissions: firing, the generator and the
    afterburner all reveal the ship, silent running fades it. Phase 3 cracks
    the hull open into a telegraphed barrage while the exposed core is cut;
    the mirror-lantern blinds it for ``balance.MIRROR_LANTERN_BLIND_S`` punish
    windows in which the core takes full damage. Defeated phases persist on
    the profile across attempts. Victory rolls credits, mutates the main-menu
    nebula permanently, pays ``balance.ROOST_KILL_CORES`` and unlocks Hunt
    Rank 1.
"""

from __future__ import annotations

import math
import random
from collections.abc import Callable

from simvx.core import Node, Signal, Vec3

from . import balance
from .power import SignalWiring
from .runtime import Groups, SignalNames

# ============================================================================
# Numbers the design fixes by feel rather than by table, so balance.py has no
# name for them yet. Flagged for the balance pass.
# ============================================================================

#: The three biome types whose log-fragment caches build the Lure blueprint.
#: balance.LURE_FRAGMENT_BIOME_TYPES fixes the count at three; the design
#: leaves the biomes themselves unnamed, so these are the working picks.
LURE_FRAGMENT_BIOMES = ("nebula", "wreck_graveyard", "vent_field")
#: Fragment caches needed from each biome type before the blueprint is whole.
LURE_FRAGMENTS_PER_BIOME = 3

#: Base chance a killed herald drops a Fletching, before the per-run rise.
FLETCHING_BASE_DROP_CHANCE = 0.25

#: The quill-tech blueprint id the mirror-lantern punish windows require.
MIRROR_LANTERN_BLUEPRINT = "mirror_lantern"

#: Per-phase HP pools for the duel, phases 1 to 3.
ROOST_PHASE_HP = (750.0, 600.0, 500.0)
#: An aimed attack misses when the ship has moved this far from the point it
#: was locked at when the telegraph began.
ROOST_ATTACK_DODGE_RADIUS = 6.0
#: Phase 1: seconds of tracking between lantern burns, full aggression.
ROOST_LANTERN_COOLDOWN_S = 2.5
#: Phase 2: strike cadence and cost once the emissions give the ship away.
ROOST_STRIKE_COOLDOWN_S = 2.0
ROOST_STRIKE_WINDUP_S = 1.0
ROOST_STRIKE_DAMAGE = 25.0
#: Phase 3: barrage cadence, telegraph and per-pulse damage.
ROOST_BARRAGE_INTERVAL_S = 4.0
ROOST_BARRAGE_TELEGRAPH_S = 0.8
ROOST_BARRAGE_DAMAGE = 12.0
#: Seconds between mirror-lantern activations.
ROOST_MIRROR_COOLDOWN_S = 12.0

#: Phase 2 emission model: firing spikes the meter, running loud fills it
#: slowly, silence drains it. The Roost only hunts above the threshold.
EMISSION_MAX = 100.0
EMISSION_PER_SHOT = 8.0
EMISSION_GENERATOR_PER_S = 6.0
EMISSION_AFTERBURNER_PER_S = 10.0
EMISSION_DECAY_PER_S = 4.0
EMISSION_SILENT_DECAY_MULT = 3.0
EMISSION_HUNT_THRESHOLD = 40.0


# ============================================================================
# Profile helpers shared by the campaign, the scene and flow.py
# ============================================================================


def quills_to_open(profile: dict) -> int:
    """Quills the first attempt of a Roost campaign costs.

    Hunt Rank 7 raises the toll per ``balance.HUNT_RANK7_QUILLS_TO_OPEN_ROOST``.
    """
    if int(profile.get("hunt_rank", 0)) >= 7:
        return int(balance.HUNT_RANK7_QUILLS_TO_OPEN_ROOST)
    return int(balance.QUILLS_TO_OPEN_ROOST)


def quills_after_death(quills: int, *, roost_attempt: bool) -> int:
    """What the one-kept-on-death rule leaves of *quills*.

    The rule applies only to ordinary runs; quills carried into a Roost
    attempt are exempt, so a summit expedition never pays the ordinary tax on
    top of its entry fee. flow.py calls this from the death ledger.
    """
    if roost_attempt:
        return int(quills)
    return min(int(quills), int(balance.QUILLS_KEPT_ON_DEATH))


def can_wake_roost(profile: dict, fuel: float, notoriety: int = 0) -> bool:
    """Whether the Roost can be woken: spare fuel plus a provocation.

    Notoriety ``balance.ROOST_PROVOCATION_NOTORIETY`` qualifies, and so does
    the assembled Lure by itself: it is sixty notoriety worth of noise in a
    single object, which keeps the quietest playstyle inside the true ending.
    """
    if float(fuel) < balance.ROOST_FUEL_REQUIRED:
        return False
    assembled = bool(profile.get("lure", {}).get("assembled", False))
    return assembled or int(notoriety) >= balance.ROOST_PROVOCATION_NOTORIETY


def reveal_roost_node(graph, profile: dict) -> str | None:
    """Put the Roost on *graph* beside the Deep Gate when the Lure is aboard.

    *graph* is a ``chart.ChartGraph``; its ``reveal_roost`` places the node
    adjacent to the gate so extraction and predation are one fork taken with
    the same fuel. Returns the node id, or ``None`` while the Lure is not yet
    assembled. Calling this every jump is harmless.
    """
    if not profile.get("lure", {}).get("assembled", False):
        return None
    return graph.reveal_roost()


def menu_nebula_mutated(profile: dict) -> bool:
    """Whether the main-menu nebula shows the permanent post-kill mutation."""
    return int(profile.get("hunt_rank", 0)) >= 1


def apply_victory(profile: dict) -> dict:
    """Bank a Roost kill on *profile* and return the rewards summary.

    Pays ``balance.ROOST_KILL_CORES``, raises the Hunt Rank one tier (the
    first kill unlocks Rank 1), and resets the campaign so the next rank's
    Roost is a fresh summit. The caller rolls credits and saves the profile.
    """
    profile["cores"] = int(profile.get("cores", 0)) + int(balance.ROOST_KILL_CORES)
    profile["hunt_rank"] = min(int(profile.get("hunt_rank", 0)) + 1, int(balance.HUNT_RANKS_TOTAL))
    profile["roost"] = {"phases_defeated": 0, "attempts": 0}
    return {
        "cores": int(balance.ROOST_KILL_CORES),
        "hunt_rank": int(profile["hunt_rank"]),
        "credits_rolled": True,
        "menu_nebula_mutated": True,
    }


def _roost_state(profile: dict) -> dict:
    state = profile.setdefault("roost", {})
    state.setdefault("phases_defeated", 0)
    state.setdefault("attempts", 0)
    return state


# ============================================================================
# The Lure campaign
# ============================================================================


class LureCampaign:
    """The across-runs half of Predation, carried on the meta profile.

    Plain state logic over the profile dictionary: fragments, assembly and the
    quill gate all mutate the same dictionary ``save.SaveSystem`` writes, so
    persistence is wherever the profile already goes. Scrap payment goes
    through the *spend_scrap* callable (``Economy.spend_scrap`` in a run);
    without one, assembly has nothing to pay with and refuses.
    """

    def __init__(self, profile: dict, *, spend_scrap: Callable[[float], bool] | None = None):
        self.profile = profile
        self._spend_scrap = spend_scrap

    # -- fragments and assembly -------------------------------------------

    def fragments(self) -> dict[str, int]:
        """Caches held per fragment biome type, zero-filled for the missing."""
        stored = self.profile.get("lure", {}).get("fragments", {})
        return {biome: int(stored.get(biome, 0)) for biome in LURE_FRAGMENT_BIOMES}

    def collect_fragment(self, biome_id: str) -> bool:
        """Bank one log-fragment cache found in *biome_id*.

        Only the three fragment biome types count, and a biome that has
        already yielded its share yields no more: the campaign has a shape,
        not a lottery. Returns whether the cache counted.
        """
        if biome_id not in LURE_FRAGMENT_BIOMES:
            return False
        lure = self.profile.setdefault("lure", {"fragments": {}, "assembled": False})
        held = int(lure.setdefault("fragments", {}).get(biome_id, 0))
        if held >= LURE_FRAGMENTS_PER_BIOME:
            return False
        lure["fragments"][biome_id] = held + 1
        return True

    def blueprint_complete(self) -> bool:
        """Whether every fragment biome has yielded its full share."""
        return all(count >= LURE_FRAGMENTS_PER_BIOME for count in self.fragments().values())

    def assembled(self) -> bool:
        """Whether the Lure is aboard, which is what reveals the Roost node."""
        return bool(self.profile.get("lure", {}).get("assembled", False))

    def can_assemble(self) -> bool:
        """Blueprint complete and the Lure not yet built; scrap is checked at assembly."""
        return self.blueprint_complete() and not self.assembled()

    def assemble(self) -> bool:
        """Build the Lure for ``balance.LURE_ASSEMBLY_SCRAP``. Returns success."""
        if not self.can_assemble():
            return False
        if self._spend_scrap is None or not self._spend_scrap(float(balance.LURE_ASSEMBLY_SCRAP)):
            return False
        self.profile.setdefault("lure", {})["assembled"] = True
        return True

    # -- the quill gate ---------------------------------------------------

    def quills(self) -> int:
        """Quills banked on the profile."""
        return int(self.profile.get("quills", 0))

    def add_quill(self, count: int = 1) -> None:
        """Bank sheared or forged quills and reset the pity counter."""
        self.profile["quills"] = self.quills() + int(count)
        self.profile["runs_since_last_quill"] = 0

    def campaign_open(self) -> bool:
        """Whether the five-quill toll has already been paid this campaign."""
        return int(_roost_state(self.profile).get("attempts", 0)) > 0

    def attempt_cost(self) -> int:
        """Quills the next attempt costs: the opening toll once, then retries."""
        if self.campaign_open():
            return int(balance.ROOST_RETRY_QUILL_COST)
        return quills_to_open(self.profile)

    def can_begin_attempt(self, fuel: float, notoriety: int = 0) -> bool:
        """Whether an attempt can start: Lure aboard, Roost woken, toll payable."""
        return (
            self.assembled() and can_wake_roost(self.profile, fuel, notoriety) and self.quills() >= self.attempt_cost()
        )

    def begin_attempt(self) -> bool:
        """Spend the quill toll and count the attempt. Returns success.

        Defeated phases stay defeated on the profile, so a paid retry resumes
        at the first phase still standing.
        """
        cost = self.attempt_cost()
        if self.quills() < cost:
            return False
        self.profile["quills"] = self.quills() - cost
        _roost_state(self.profile)["attempts"] += 1
        return True


# ============================================================================
# The Fletching ledger
# ============================================================================


class FletchingLedger:
    """Herald Fletching drops and the pity forge, over the meta profile.

    The drop chance starts at :data:`FLETCHING_BASE_DROP_CHANCE` and rises
    ``balance.FLETCHING_RATE_RISE_PER_RUN`` for every run finished since the
    last quill, so the funnel converges instead of stalling.
    """

    def __init__(self, profile: dict, *, rng: random.Random | None = None):
        self.profile = profile
        self._rng = rng if rng is not None else random.Random()

    def fletchings(self) -> int:
        """Fletchings banked on the profile."""
        return int(self.profile.get("fletchings", 0))

    def drop_chance(self) -> float:
        """The current herald drop chance, clamped to certainty."""
        runs = int(self.profile.get("runs_since_last_quill", 0))
        return min(1.0, FLETCHING_BASE_DROP_CHANCE + balance.FLETCHING_RATE_RISE_PER_RUN * runs)

    def on_herald_killed(self) -> bool:
        """Roll the drop for one dead herald; banks a Fletching on success."""
        if self._rng.random() >= self.drop_chance():
            return False
        self.profile["fletchings"] = self.fletchings() + 1
        return True

    def can_forge(self) -> bool:
        """Whether a quill's worth of Fletchings is banked."""
        return self.fletchings() >= int(balance.FLETCHINGS_PER_QUILL)

    def forge_quill(self) -> bool:
        """Trade ``balance.FLETCHINGS_PER_QUILL`` Fletchings for a quill.

        Depot-side code offers this while docked; the ledger itself only
        enforces the price. Forging counts as gaining a quill, so the pity
        counter resets.
        """
        if not self.can_forge():
            return False
        self.profile["fletchings"] = self.fletchings() - int(balance.FLETCHINGS_PER_QUILL)
        self.profile["quills"] = int(self.profile.get("quills", 0)) + 1
        self.profile["runs_since_last_quill"] = 0
        return True

    def record_run(self, *, quill_gained: bool) -> None:
        """Advance the pity counter at run end; a quill run resets it."""
        if quill_gained:
            self.profile["runs_since_last_quill"] = 0
        else:
            self.profile["runs_since_last_quill"] = int(self.profile.get("runs_since_last_quill", 0)) + 1


# ============================================================================
# The Roost duel
# ============================================================================

#: Per-phase aimed-attack cadence: seconds between attacks, telegraph length,
#: damage on a clean hit, and the damage kind the ship's ledger sees.
_PHASE_COOLDOWN_S = {1: ROOST_LANTERN_COOLDOWN_S, 2: ROOST_STRIKE_COOLDOWN_S, 3: ROOST_BARRAGE_INTERVAL_S}
_PHASE_WINDUP_S = {1: balance.SHRIKE_LANTERN_PREBURN_WARNING_S, 2: ROOST_STRIKE_WINDUP_S, 3: ROOST_BARRAGE_TELEGRAPH_S}
_PHASE_DAMAGE = {1: balance.SHRIKE_LANTERN_HULL_DAMAGE, 2: ROOST_STRIKE_DAMAGE, 3: ROOST_BARRAGE_DAMAGE}
_PHASE_KIND = {1: "lantern", 2: "strike", 3: "barrage"}

PHASE_COUNT = len(ROOST_PHASE_HP)


class RoostScene(Node):
    """The three-phase duel, resumed at the first phase still standing.

    The scene is the fight's director: it runs the opening arrival ladder,
    scrambles the warp for the whole duel (there is no warp-out), drives the
    per-phase attack cycles against the player ship, and takes the player's
    damage through the same :class:`~shrike.combat.DamageRouter` path as every
    other hostile. Defeated phases are written to the profile the moment they
    fall, so death after a phase kill loses nothing but the retry quill.

    Every attack is telegraphed: the Roost locks the ship's position when the
    windup begins and the burn lands only if the ship is still within
    :data:`ROOST_ATTACK_DODGE_RADIUS` of that point, so dodging is a piloting
    problem at full aggression, exactly as the run taught it.
    """

    hunter_telegraph = Signal(str)  # SignalNames.HUNTER_TELEGRAPH: "t60" | "t30" | "t0"
    roost_attack_telegraphed = Signal(str)  # attack kind, at windup start
    roost_phase_defeated = Signal(int)  # 1-based phase that just fell
    roost_blinded = Signal(float)  # mirror-lantern window length, seconds
    roost_victory = Signal(dict)  # rewards summary from apply_victory
    roost_failed = Signal(int)  # 1-based phase the attempt died in

    def __init__(
        self,
        profile: dict,
        *,
        telegraph_s: float = balance.SHRIKE_TELEGRAPH_FIRST_S,
        mirror_lantern: bool | None = None,
        **kwargs,
    ):
        super().__init__(**kwargs)
        self.profile = profile
        if mirror_lantern is None:
            mirror_lantern = MIRROR_LANTERN_BLUEPRINT in profile.get("quill_tech", [])
        self.mirror_lantern_available = bool(mirror_lantern)

        #: "ladder" | "fight" | "won" | "lost"
        self.state = "ladder"
        #: 1-based current phase; opens past whatever earlier attempts felled.
        self.phase = min(int(_roost_state(profile).get("phases_defeated", 0)) + 1, PHASE_COUNT)
        self.phase_hp = float(ROOST_PHASE_HP[self.phase - 1])
        #: Phase 2's giveaway meter, 0 to EMISSION_MAX.
        self.emission = 0.0

        self._telegraph_remaining = float(telegraph_s)
        self._t30_sent = False
        self._fight_s = 0.0
        self._attack_state = "cooldown"  # "cooldown" | "windup"
        self._attack_timer = _PHASE_COOLDOWN_S[self.phase]
        self._locked_point: tuple[float, float] | None = None
        self._blind_remaining = 0.0
        self._mirror_cooldown = 0.0
        self._blackout_remaining = 0.0
        self._generator_on = False
        self._afterburner_on = False
        self._silent_running = False
        self._warp_held = False
        self._wiring = SignalWiring(self)
        self._wiring.want(SignalNames.WEAPON_FIRED, self._on_weapon_fired)
        self._wiring.want(SignalNames.GENERATOR_CHANGED, self._on_generator_changed)
        self._wiring.want(SignalNames.AFTERBURNER_CHANGED, self._on_afterburner_changed)
        self._wiring.want(SignalNames.SILENT_RUNNING_CHANGED, self._on_silent_running_changed)
        self._wiring.want(SignalNames.SHIP_DESTROYED, self._on_ship_destroyed)

    # ------------------------------------------------------------- properties

    @property
    def damage_taken_mult(self) -> float:
        """What the DamageRouter scales incoming numbers by.

        Phases 1 and 2 take honest damage. Phase 3's exposed core is plated
        like a fin until the mirror-lantern blinds it, which is what makes the
        punish windows worth building the module for.
        """
        if self.phase == 3 and self._blind_remaining <= 0.0:
            return float(balance.SHRIKE_FIN_DAMAGE_TAKEN_MULT)
        return 1.0

    def blinded(self) -> bool:
        """Whether a mirror-lantern window is open."""
        return self._blind_remaining > 0.0

    def damage_multiplier(self) -> float:
        """Full aggression: the ramp starts high and climbs while present."""
        steps = math.floor(self._fight_s / balance.SHRIKE_RAMP_INTERVAL_S)
        return 1.0 + balance.SHRIKE_RAMP_START_LATER_ARRIVALS + balance.SHRIKE_RAMP_FRACTION * steps

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

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

    def on_ready(self):
        self._wiring.sweep()
        self._emit_stage("t60")
        if self._telegraph_remaining <= balance.SHRIKE_TELEGRAPH_KLAXON_S:
            self._emit_stage("t30")
            self._t30_sent = True

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

    def take_damage(self, amount: float, kind: str = "impact") -> None:
        """Damage the current phase; the router has already applied plating."""
        if self.state != "fight" or amount <= 0.0:
            return
        self.phase_hp -= float(amount)
        if self.phase_hp <= 0.0:
            self._defeat_phase()

    def activate_mirror_lantern(self) -> bool:
        """Open a ``balance.MIRROR_LANTERN_BLIND_S`` punish window.

        Only in phase 3, only with the quill-tech built, and only off
        cooldown. Blinding cancels any barrage mid-telegraph.
        """
        if self.state != "fight" or self.phase != 3 or not self.mirror_lantern_available:
            return False
        if self._mirror_cooldown > 0.0:
            return False
        self._blind_remaining = float(balance.MIRROR_LANTERN_BLIND_S)
        self._mirror_cooldown = ROOST_MIRROR_COOLDOWN_S
        self._reset_attack()
        self.roost_blinded(float(balance.MIRROR_LANTERN_BLIND_S))
        return True

    def fail(self) -> None:
        """End the attempt in defeat; felled phases stay felled on the profile."""
        if self.state in ("won", "lost"):
            return
        self.state = "lost"
        self._release_warp()
        self.roost_failed(self.phase)

    # ------------------------------------------------------------------- tick

    def on_update(self, dt: float):
        self._wiring.poll(dt)
        if self.state == "ladder":
            self._hold_warp()
            self._tick_ladder(dt)
        elif self.state == "fight":
            self._hold_warp()
            self._tick_fight(dt)

    def _tick_ladder(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.state = "fight"
            self._emit_stage("t0")

    def _tick_fight(self, dt: float) -> None:
        self._fight_s += dt
        self._tick_blackout(dt)
        if self._mirror_cooldown > 0.0:
            self._mirror_cooldown = max(0.0, self._mirror_cooldown - dt)
        if self.phase == 2:
            self._tick_emission(dt)
        if self.phase == 3 and self._blind_remaining > 0.0:
            self._blind_remaining = max(0.0, self._blind_remaining - dt)
            self._reset_attack()
            return
        self._tick_attack(dt)

    def _tick_emission(self, dt: float) -> None:
        gain = 0.0
        if self._generator_on:
            gain += EMISSION_GENERATOR_PER_S
        if self._afterburner_on:
            gain += EMISSION_AFTERBURNER_PER_S
        decay = EMISSION_DECAY_PER_S * (EMISSION_SILENT_DECAY_MULT if self._silent_running else 1.0)
        self.emission = min(EMISSION_MAX, max(0.0, self.emission + (gain - decay) * dt))

    def _tick_attack(self, dt: float) -> None:
        if self._attack_state == "cooldown":
            self._attack_timer = max(0.0, self._attack_timer - dt)
            if self._attack_timer <= 0.0 and self._may_windup():
                self._begin_windup()
        else:
            self._attack_timer -= dt
            if self._attack_timer <= 0.0:
                self._resolve_attack()

    def _may_windup(self) -> bool:
        if self._ship() is None:
            return False
        if self.phase == 2:
            return self.emission >= EMISSION_HUNT_THRESHOLD
        return True

    def _begin_windup(self) -> None:
        self._attack_state = "windup"
        self._attack_timer = _PHASE_WINDUP_S[self.phase]
        self._locked_point = self._ship_plane()
        self.roost_attack_telegraphed(_PHASE_KIND[self.phase])

    def _resolve_attack(self) -> None:
        locked = self._locked_point
        self._reset_attack()
        ship = self._ship()
        here = self._ship_plane()
        if ship is None or locked is None or here is None:
            return
        if math.hypot(here[0] - locked[0], here[1] - locked[1]) > ROOST_ATTACK_DODGE_RADIUS:
            return
        # An enveloping wash, not a bearing-aligned shot: the shield arc covers
        # no bearing for it and the only defence is not being where it looked.
        amount = _PHASE_DAMAGE[self.phase] * self.damage_multiplier()
        ship.apply_damage(amount, Vec3(0.0, 0.0, 0.0), kind=_PHASE_KIND[self.phase])
        if self.phase == 1:
            self._blackout_remaining = balance.SHRIKE_LANTERN_CAPACITOR_BLACKOUT_S

    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 _reset_attack(self) -> None:
        self._attack_state = "cooldown"
        self._attack_timer = _PHASE_COOLDOWN_S[self.phase]
        self._locked_point = None

    # ----------------------------------------------------------------- phases

    def _defeat_phase(self) -> None:
        felled = self.phase
        state = _roost_state(self.profile)
        state["phases_defeated"] = max(int(state.get("phases_defeated", 0)), felled)
        self.roost_phase_defeated(felled)
        if felled >= PHASE_COUNT:
            self.state = "won"
            self._release_warp()
            self.roost_victory(apply_victory(self.profile))
            return
        self.phase = felled + 1
        self.phase_hp = float(ROOST_PHASE_HP[self.phase - 1])
        self.emission = 0.0
        self._blind_remaining = 0.0
        self._reset_attack()

    # ------------------------------------------------------------ warp denial

    def _hold_warp(self) -> None:
        ship = self._ship()
        if ship is not None:
            ship.warp_scrambled = True
            self._warp_held = True

    def _release_warp(self) -> None:
        if not self._warp_held:
            return
        self._warp_held = False
        ship = self._ship()
        if ship is not None:
            ship.warp_scrambled = False

    # -------------------------------------------------------------- listeners

    def _on_weapon_fired(self, weapon_id: str) -> None:
        if self.state == "fight" and self.phase == 2:
            self.emission = min(EMISSION_MAX, self.emission + EMISSION_PER_SHOT)

    def _on_generator_changed(self, running: bool) -> None:
        self._generator_on = bool(running)

    def _on_afterburner_changed(self, active: bool) -> None:
        self._afterburner_on = bool(active)

    def _on_silent_running_changed(self, active: bool) -> None:
        self._silent_running = bool(active)

    def _on_ship_destroyed(self) -> None:
        if self.state in ("ladder", "fight"):
            self.fail()

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

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

    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)