shrike/onboarding.py

Part of SHRIKE.

"""The staged first three runs: the HUD subtraction schedule and the safe arrival.

Onboarding works by subtraction rather than tuition.
The HUD is complete from the first frame of run 3 and is *narrowed* before
that, so nothing the player learns has to be unlearned and no tutorial box ever
covers the screen:

* **Run 1** shows the gauges, the resource strip and the signature border, plus
  the diegetic and accessibility elements the HUD never subtracts (the spool
  ring, the interact fill, the damage edge, subtitles and stamps). No ammo, no
  chart, no notoriety.
* **Run 2** adds the ammunition counter, which is the one readout run one has
  nothing to put in. Ballistic weapons start appearing in depot stock the same
  run.
* **Run 3** adds silent running, the Refinery and trading-post conversion, and
  the notoriety trail. After run 3 nothing is added, and after run 2 nothing
  tactical is.

Subtraction has one hard floor: **a resource the run can charge or credit is
never subtracted.** Run one quotes five scrap for a hull patch and fifteen fuel
for a jump, and drains air the whole time; hiding those three numbers would
leave every price in the game quoted in a currency with no readout anywhere on
the screen.

Teaching happens on the HUD's control-card channel, never on the caption
queue. A card names the keys of the lesson in hand and stays up until the
player does that thing, at which point the next card replaces it. Combat
captions keep the bottom subtitle line to themselves, so a control the player
has not found yet cannot be scrolled away by a kill chime. A card whose verb
the sector never offers (nothing to mine, no breach to patch) gives up after
:data:`CARD_TIMEOUT_S` rather than stalling the script.

Neither channel is the HUD's affordance line or its controls bar. Those are
permanent fixtures the run scene drives, on for every run and every profile,
and they are what a pilot past run three still has: the script stops teaching,
so the game has to keep naming its verbs by itself.

Two kinds of teaching hang off that one channel:

* **The script** is the fixed run-one to run-three sequence above, played in
  order and paced by the clock.
* **The lessons** in :data:`LESSON_CARDS` are answers to something that has
  just happened, whatever run it happens on: a hold worth spending, a
  Refinery worth feeding, a warp key pressed with nowhere to go. A lesson is
  queued behind whatever the script is holding rather than shoving it aside,
  and is taught once per profile.

:data:`ARCHETYPE_TAGS` is the other half of the same promise. The first time a
profile sees an archetype the enemy wears its name and its job for
:data:`SIGHTING_TAG_HOLD_S`, floating beside it, so nothing that kills you was
ever anonymous. The seen set lives in the profile's ``codex["enemies"]``.

Run 1 also gets one scripted, survivable Shrike arrival: the tank is topped up
first so fleeing is always affordable, then the meter is driven straight to
lock so the klaxon, the ladder and the lockout are learned in the body rather
than read in a tooltip.

:class:`Onboarding` is the pure schedule and answers every "is this unlocked
yet" question the run scene asks. :class:`OnboardingDirector` is the node that
applies it to a live run.
"""

from __future__ import annotations

from dataclasses import dataclass

from simvx.core import Input, Node, Signal, Vec2

from . import balance
from .hud import ALL_HUD_ELEMENTS, COLOUR_ENEMY_TAG, MINIMAL_HUD_ELEMENTS, Hud, HudElements
from .power import iter_tree_nodes
from .runtime import Groups, Services, controller_aim_input

# ============================================================================
# The schedule
# ============================================================================

#: Runs the schedule covers. From this run on the game is shown whole.
STAGED_RUNS = 3

#: What run 2 adds: the one readout run one has no use for.
#:
#: The air, the fuel and the hold are shown from run one. Run one charges five
#: scrap for a patch, fifteen fuel for a jump and drains air the whole time;
#: subtracting those three readouts would leave a pilot quoted prices in
#: currencies with no number anywhere on the screen. The rule the schedule
#: obeys: **a resource the run can charge or credit is never subtracted.**
#: Ammunition survives here because run one is flown on
#: energy weapons and never sees a round.
RUN_2_ADDITIONS: frozenset[str] = frozenset({HudElements.AMMO})

#: What run 3 adds: the posture, the conversion bet and the reputation.
RUN_3_ADDITIONS: frozenset[str] = frozenset({HudElements.SILENT_RUNNING, HudElements.NOTORIETY})

#: Seconds into run 1 before the scripted arrival is provoked. Long enough to
#: have flown, mined and worked through the control cards, short enough that
#: the tutorial's climax lands while the pilot is still alive to learn from it.
SCRIPTED_ARRIVAL_AT_S = 70.0

#: The sector run 1 usually meets the scripted arrival in. Advisory only: the
#: clock is the gate, and the arrival lands in whatever sector the run occupies
#: when it expires. Tying it to this sector would let a pilot who warped out
#: before the deadline lose the arrival entirely, and with it run one's whole
#: wave schedule.
SCRIPTED_ARRIVAL_SECTOR = 1


@dataclass(frozen=True)
class ScriptedArrival:
    """Run one's staged Shrike arrival.

    *guaranteed_fuel* is topped into the tank the moment the ladder starts, so
    the lesson is "the klaxon means leave" and never "the klaxon means die".
    """

    sector_index: int = SCRIPTED_ARRIVAL_SECTOR
    at_elapsed_s: float = SCRIPTED_ARRIVAL_AT_S
    guaranteed_fuel: float = balance.FUEL_MAX


# ============================================================================
# The control cards
# ============================================================================


class Verbs:
    """The things a card can wait for the player to do."""

    THRUST = "thrust"
    AIM = "aim"
    FIRE = "fire"
    MINE = "mine"
    GRAB = "grab"
    SOLAR_WINGS = "solar_wings"
    GENERATOR = "generator"
    PATCH = "patch"
    WARP = "warp"
    CHART = "chart"


#: Which actions satisfy each verb. Actions only, never raw keys, so a
#: remapped key teaches itself without the script knowing about it.
VERB_ACTIONS: dict[str, tuple[str, ...]] = {
    Verbs.THRUST: ("thrust_up", "thrust_down", "thrust_left", "thrust_right"),
    Verbs.AIM: ("aim_up", "aim_down", "aim_left", "aim_right"),
    Verbs.FIRE: ("fire_primary",),
    Verbs.MINE: ("mining_beam",),
    # The grab and the patch are the same key at two hold lengths, so the grab
    # card is satisfied by a tap and the patch card only by the one-second hold
    # in VERB_HOLD_S. Teaching the tap first is deliberate: it is the verb the
    # sector offers constantly, and it is the one that introduces the prompt.
    Verbs.GRAB: ("interact",),
    Verbs.SOLAR_WINGS: ("solar_wings",),
    Verbs.GENERATOR: ("generator",),
    Verbs.PATCH: ("interact",),
    Verbs.WARP: ("warp_spool",),
    Verbs.CHART: ("star_chart",),
}

#: Seconds a verb must be held before it counts as done. A tap proves you found
#: the key; a hold proves you found what the key is for, which is the lesson for
#: the beam and the patch channel.
VERB_HOLD_S: dict[str, float] = {
    Verbs.THRUST: 0.4,
    Verbs.MINE: 1.0,
    Verbs.PATCH: 1.0,
}

#: The verbs a card counts by what the run gained rather than by the key.
#: Both of these are ways of getting paid, so both are satisfied by the pay:
#: a beam held at empty space and an interact tapped at nothing have taught
#: nobody anything, and a card that counted the key would advance on both.
OUTCOME_VERBS: frozenset[str] = frozenset({Verbs.MINE, Verbs.GRAB})

#: Mouse travel, in pixels, that counts as having aimed. Keyboard pilots have no
#: ``aim_*`` binding at all: the pointer is the aim, exactly as the ship reads it.
AIM_MOUSE_TRAVEL_PX = 90.0
#: Right-stick deflection that counts as aiming on a pad.
AIM_STICK_DEFLECTION = 0.4

#: How long a card with no verb stays up before the script moves on.
CARD_HOLD_S = 7.0
#: How long a card waits for a verb the sector may never offer (no vein in
#: range, no breach to patch) before giving up. A lesson is not a gate.
CARD_TIMEOUT_S = 45.0


class Gates:
    """Conditions a card waits for before it is worth showing at all.

    A card that names a verb the hull cannot perform is worse than no card: a
    pilot who reads "PATCH A BREACH: hold F" on an undamaged hull holds F at
    nothing and comes away believing the key is broken.
    """

    #: The hull has at least one open breach.
    BREACH = "breach"


#: Seconds a gated card waits before it steps aside for the rest of the script.
#: It keeps its place in the queue; it simply stops holding the door.
GATE_RETRY_S = 6.0

#: How finely the card's progress bar is quantised before it is redrawn. The
#: HUD draws the bar itself; this only bounds how often a moving hold re-shows
#: the card. A tap of the beam must show as a tap rather than as nothing at all.
PROGRESS_TICKS = 8

#: What the script says when a key is pressed that a later card teaches. The
#: run honours the key regardless: this answers it rather than refusing it, so
#: no bound key on the tutorial is ever silent.
OUT_OF_ORDER_ANSWER = "FIRST: {text}"
#: Seconds between two of those answers, so a held key is one sentence.
OUT_OF_ORDER_COOLDOWN_S = 2.5


@dataclass(frozen=True)
class ControlCard:
    """One lesson on the HUD's control channel.

    *text* names the keys, *hint* is the smaller line under it, and *verb* is
    what the card waits for: one of :class:`Verbs`, or empty for a card that
    simply holds for *hold_s*. *at_s* is the earliest point in the run the card
    may be shown, which is how a line lands on the beat it belongs to. *gate*
    is a :class:`Gates` condition the run must satisfy before the card is worth
    putting up at all.
    """

    text: str
    verb: str = ""
    hint: str = ""
    at_s: float = 0.0
    hold_s: float = CARD_HOLD_S
    gate: str = ""


#: Run one's script: fly, shoot, harvest, keep the lights on, then obey the
#: klaxon. Every line names its key, because a key nobody names is a key nobody
#: presses.
RUN_1_CARDS: tuple[ControlCard, ...] = (
    ControlCard("FLY: W A S D", verb=Verbs.THRUST, hint="you drift; the engines only ever push"),
    ControlCard("AIM: the mouse", verb=Verbs.AIM, hint="the nose follows the pointer wherever you thrust"),
    ControlCard("FIRE: left mouse button", verb=Verbs.FIRE, hint="the guns spend the capacitor"),
    ControlCard(
        "MINE: hold right mouse button on an orange-flecked rock",
        verb=Verbs.MINE,
        hint="the beam pays in scrap: the surface pays fast, the core pays double",
    ),
    ControlCard(
        "GRAB: F beside the drifting motes or a wreck's open bay",
        verb=Verbs.GRAB,
        hint="the line above your ship always names the key and the verb in reach",
    ),
    ControlCard(
        "SOLAR WINGS: X",
        verb=Verbs.SOLAR_WINGS,
        hint="deployed wings refill the capacitor from starlight, and they can be shot off",
    ),
    ControlCard(
        "GENERATOR: Z",
        verb=Verbs.GENERATOR,
        hint="it refills the capacitor from fuel, and it is the loudest thing you own",
    ),
    ControlCard(
        "CAPACITOR: the blue arc under the ship",
        hint="the guns and the burner (SHIFT) spend it; X and Z put it back",
    ),
    ControlCard(
        "PATCH A BREACH: hold F",
        verb=Verbs.PATCH,
        hint="a breach bleeds your air until it is patched",
        gate=Gates.BREACH,
    ),
    ControlCard(
        "THE KLAXON MEANS LEAVE: R spools the drive",
        at_s=SCRIPTED_ARRIVAL_AT_S + 1.0,
        hint="the tank is full; nothing out here is worth staying for",
        hold_s=12.0,
    ),
)

#: Run two's script: the chart is open now, and fuel is the leash on it.
RUN_2_CARDS: tuple[ControlCard, ...] = (
    ControlCard(
        "STAR CHART: M",
        verb=Verbs.CHART,
        at_s=3.0,
        hint="every route is priced in fuel, and the prices are honest",
    ),
    ControlCard(
        # R first, M second: every arrival arms a lane for itself, so the
        # chip already names somewhere to go and the chart is the override
        # rather than the prerequisite. Taught the other way round, the lesson
        # would send a pilot to a screen to confirm a choice the drive has made.
        "WARP OUT: R flies the route named under the ship; M picks another",
        verb=Verbs.WARP,
        at_s=12.0,
        hint="the drive spools for five seconds and the jump costs that route's fuel price; tap R again to abort",
    ),
    ControlCard("OXYGEN: the green arc", at_s=32.0, hint="breaches bleed it; hold F to patch one"),
)

#: Run three's script: the conversion bet, and the noise it costs.
RUN_3_CARDS: tuple[ControlCard, ...] = (
    ControlCard("CONVERT AT A DEPOT: hold F", at_s=3.0, hint="scrap only becomes Cores where you convert it"),
    ControlCard("GO DARK: C", at_s=20.0, hint="it cools the meter, and the guns go dark with it"),
)


# ============================================================================
# Lessons: the cards a moment asks for rather than the clock
# ============================================================================


class Lessons:
    """Ids for the cards that answer something that just happened."""

    #: The hold is worth something, and nothing in the sector has said so.
    SCRAP = "scrap_sinks"
    #: The smelter is aboard and the hold is big enough to feed it.
    REFINE = "refine"
    #: The drive was spooled with nowhere to spool to.
    WARP = "warp"


#: Scrap in the hold that earns the sinks lesson: enough to be worth a plan.
SCRAP_LESSON_SCRAP = 50.0
#: Scrap in the hold that earns the refine lesson, once a Refinery is fitted.
REFINE_LESSON_SCRAP = 100.0
#: The catalogue id of the smelter, as ``modules.MODULE_CATALOGUE`` spells it.
REFINERY_MODULE_ID = "refinery"
#: Seconds between the director's sweeps for a lesson or a first sighting.
LESSON_POLL_S = 0.5

#: The lesson cards themselves. Every one names its key, like the script does.
LESSON_CARDS: dict[str, ControlCard] = {
    Lessons.SCRAP: ControlCard(
        "SCRAP BUYS FUEL, AMMO AND MODULES",
        hint="spend it at a trading post, or sell it there for Cores; carrying it home pays far less",
    ),
    Lessons.REFINE: ControlCard(
        "REFINE THE HOLD: hold F",
        hint="the smelter turns scrap into Cores wherever you float, and it is heard for sectors",
    ),
    Lessons.WARP: ControlCard(
        "WARP NEEDS A DESTINATION: M picks it, R spools the drive",
        hint="the chart quotes every route in fuel; tap R again to abort a spool",
    ),
}


# ============================================================================
# First sightings
# ============================================================================

#: ``archetype -> the three words that say what it does to you``. balance.py
#: carries each archetype's note, which is written for tuning rather than
#: for a pilot reading it mid-dodge, so the pilot's version lives
#: here. A new archetype without a line is tagged with its name alone.
ARCHETYPE_TAGS: dict[str, str] = {
    "mite": "swarms and chews",
    "skimmer": "steals your salvage",
    "lancer": "dashes and rams",
    "mag_mine": "lunges when close",
    "welder": "repairs its friends",
    "bombardier": "shells from afar",
    "screamer": "screams for attention",
    "husk_turret": "burns fixed lanes",
    "herald": "heralds the Shrike",
    "warden": "guards its vault",
    "magistrate": "hunts your bounty",
}

#: How long a first-sighting tag floats beside the thing it names.
SIGHTING_TAG_HOLD_S = 4.0
#: The profile's codex bucket the seen archetypes are kept in.
CODEX_ENEMIES = "enemies"


def sighting_tag(archetype: str) -> str:
    """The label a first sighting of *archetype* wears."""
    name = str(archetype).replace("_", " ").upper()
    role = ARCHETYPE_TAGS.get(str(archetype), "")
    return f"{name}: {role}" if role else name


class Onboarding:
    """The staged-run schedule: what is on screen and what is unlocked.

    Pure data and predicates. Every method takes the run number so one instance
    can answer for any run, and defaults to the run it was built for.
    """

    def __init__(self, run_number: int = 1):
        self.run_number = max(1, int(run_number))

    def __repr__(self) -> str:
        return f"Onboarding(run_number={self.run_number})"

    # -- state -------------------------------------------------------------

    @property
    def active(self) -> bool:
        """Whether this run is still inside the staged schedule."""
        return self.run_number < STAGED_RUNS

    def _run(self, run_number: int | None) -> int:
        return self.run_number if run_number is None else max(1, int(run_number))

    # -- the HUD -----------------------------------------------------------

    def visible_hud_elements(self, run_number: int | None = None) -> set[str]:
        """The HUD element ids drawn on *run_number*.

        Run 1 is ``hud.MINIMAL_HUD_ELEMENTS``, run 2 adds :data:`RUN_2_ADDITIONS`,
        and run 3 onward is the whole display.
        """
        run = self._run(run_number)
        if run >= STAGED_RUNS:
            return set(ALL_HUD_ELEMENTS)
        elements = set(MINIMAL_HUD_ELEMENTS)
        if run >= 2:
            elements |= RUN_2_ADDITIONS
        return elements

    def hidden_hud_elements(self, run_number: int | None = None) -> set[str]:
        """The complement of :meth:`visible_hud_elements`, for the tutorial copy."""
        return set(ALL_HUD_ELEMENTS) - self.visible_hud_elements(run_number)

    # -- feature gates -----------------------------------------------------

    def chart_open(self, run_number: int | None = None) -> bool:
        """Whether the player picks the route. Run 1 flies a fixed gentle one."""
        return self._run(run_number) >= 2

    def ballistics_offered(self, run_number: int | None = None) -> bool:
        """Whether depots stock ammo-fed weapons yet."""
        return self._run(run_number) >= 2

    def silent_running_available(self, run_number: int | None = None) -> bool:
        return self._run(run_number) >= STAGED_RUNS

    def conversion_available(self, run_number: int | None = None) -> bool:
        """The Refinery and the trading posts' scrap desk."""
        return self._run(run_number) >= STAGED_RUNS

    def notoriety_tracked(self, run_number: int | None = None) -> bool:
        return self._run(run_number) >= STAGED_RUNS

    # -- the staged arrival ------------------------------------------------

    def scripted_arrival(self, run_number: int | None = None) -> ScriptedArrival | None:
        """Run one's staged arrival, or None once the Shrike comes on its own."""
        return ScriptedArrival() if self._run(run_number) == 1 else None

    def control_cards(self, run_number: int | None = None) -> tuple[ControlCard, ...]:
        """The control-card script for *run_number*, in the order it is taught."""
        return {1: RUN_1_CARDS, 2: RUN_2_CARDS, STAGED_RUNS: RUN_3_CARDS}.get(self._run(run_number), ())


# ============================================================================
# The director
# ============================================================================


class OnboardingDirector(Node):
    """Applies the schedule to a live run.

    A child of the run scene. On mount it narrows the HUD; every frame it runs
    the control-card script, watching the action map for the verb the card in
    hand is waiting for, and on run 1 it tops the tank up and provokes the one
    arrival the player is meant to survive.

    It also sweeps the live run every :data:`LESSON_POLL_S` for the two things
    a schedule cannot know in advance: a hold worth teaching a sink for, and an
    archetype this profile has never seen. Both need the profile to remember
    what has been taught, so a run built without one teaches everything once
    per run and persists nothing.
    """

    #: Emitted once, when the staged arrival has been provoked.
    arrival_provoked = Signal()
    #: ``(verb, card_index)`` every time a card is satisfied and put away.
    card_completed = Signal(str, int)
    #: ``(archetype)`` the first time this profile lays eyes on one.
    archetype_sighted = Signal(str)

    def __init__(
        self,
        *,
        run_number: int = 1,
        onboarding: Onboarding | None = None,
        profile: dict | None = None,
        **kwargs,
    ):
        super().__init__(**kwargs)
        self.onboarding = onboarding if onboarding is not None else Onboarding(run_number)
        #: The live meta profile, or None in a harness without one.
        self.profile = profile
        self.elapsed = 0.0
        self.sector_index = SCRIPTED_ARRIVAL_SECTOR
        self.provoked = False
        self._cards = list(self.onboarding.control_cards())
        self._card_index = 0
        self._card_shown = False
        self._card_elapsed = 0.0
        self._verb_held = 0.0
        self._mouse_travel = 0.0
        self._last_mouse: Vec2 | None = None
        self._taught: set[str] = set()
        self._poll_in = 0.0
        #: Scrap earned when the card in hand went up, which is what the two
        #: outcome verbs are measured against.
        self._scrap_mark = 0.0
        self._verb_seen = False
        self._gate_waited: dict[str, float] = {}
        self._progress_shown: int | None = None
        self._answer_cooldown = 0.0
        self._answered: set[str] = set()

    # -- lifecycle ---------------------------------------------------------

    def on_ready(self):
        self.apply_to_hud()

    def on_update(self, dt: float):
        self.elapsed += dt
        self._run_card_script(dt)
        self._poll_in -= dt
        if self._poll_in <= 0.0:
            self._poll_in = LESSON_POLL_S
            self.poll_lessons()
            self.poll_sightings()
        arrival = self.onboarding.scripted_arrival()
        if arrival is None or self.provoked:
            return
        if self.elapsed < arrival.at_elapsed_s:
            return
        self.provoke_arrival()

    # -- the control-card script -------------------------------------------

    @property
    def card(self) -> ControlCard | None:
        """The card the script is on, or None once the script is finished."""
        return self._cards[self._card_index] if self._card_index < len(self._cards) else None

    @property
    def cards_completed(self) -> int:
        """How many cards the script has put away."""
        return self._card_index

    @property
    def pending_cards(self) -> tuple[ControlCard, ...]:
        """The card in hand and everything queued behind it, in order."""
        return tuple(self._cards[self._card_index :])

    def report_verb(self, verb: str) -> bool:
        """Tell the director the player just did *verb*.

        The director watches the action map itself, so this is for the cases
        the action map cannot see: a system confirming the thing really
        happened. Returns whether it satisfied the card in hand.
        """
        card = self.card
        if card is None or not self._card_shown or card.verb != verb:
            return False
        self._advance_card()
        return True

    def _run_card_script(self, dt: float) -> None:
        card = self.card
        self._answer_cooldown = max(0.0, self._answer_cooldown - dt)
        if card is None:
            return
        if not self._card_shown:
            if self.elapsed < card.at_s:
                return
            if not self._gate_met(card):
                self._wait_for_gate(card, dt)
                return
            hud = self.hud()
            if hud is None:
                return
            self._card_shown = True
            self._card_elapsed = 0.0
            self._verb_held = 0.0
            self._verb_seen = False
            self._mouse_travel = 0.0
            self._last_mouse = None
            self._scrap_mark = self._scrap_earned()
            self._progress_shown = None
            self._answered.clear()
            self._show_card(card)
            return
        self._card_elapsed += dt
        if not card.verb:
            if self._card_elapsed >= card.hold_s:
                self._advance_card()
            return
        if self._verb_performed(card.verb, dt):
            self._advance_card()
            return
        if self._card_elapsed >= CARD_TIMEOUT_S:
            # The sector never offered the verb. Teaching is not a gate, so the
            # script moves on rather than holding the panel up all run.
            self._advance_card()
            return
        self._show_progress(card)
        self._answer_out_of_order(card)

    def restore_card(self) -> bool:
        """Put the card in hand back on the glass, and say whether there was one.

        The HUD's transient layer is swept whole on a jump, because everything
        in it belongs to the sector that raised it. The card in hand does not:
        it teaches a key, and a pilot who jumped mid-lesson has not learned it
        yet. The progress mark is dropped with it so the bar is redrawn from
        whatever the hold has reached rather than from the tick it last showed.
        """
        card = self.card
        if card is None or not self._card_shown:
            return False
        self._progress_shown = None
        self._show_card(card)
        return True

    def _advance_card(self) -> None:
        card = self.card
        self._card_index += 1
        self._card_shown = False
        self._progress_shown = None
        hud = self.hud()
        if hud is not None:
            hud.clear_control_card()
        if card is not None:
            self.card_completed.emit(card.verb, self._card_index - 1)

    # -- gates -------------------------------------------------------------

    def _gate_met(self, card: ControlCard) -> bool:
        """Whether the run currently satisfies *card*'s gate."""
        if card.gate != Gates.BREACH:
            return True
        tree = self.tree
        if tree is None:
            return False
        return any(int(getattr(ship, "open_breaches", 0)) > 0 for ship in tree.group(Groups.SHIP))

    def _wait_for_gate(self, card: ControlCard, dt: float) -> None:
        """Hold a gated card back, and stop it holding the script back.

        After :data:`GATE_RETRY_S` the card goes to the end of the queue so the
        lines behind it are taught, and after :data:`CARD_TIMEOUT_S` of waiting
        it is dropped: nothing in this script is allowed to stall a run.
        """
        waited = self._gate_waited.get(card.text, 0.0) + dt
        self._gate_waited[card.text] = waited
        if waited >= CARD_TIMEOUT_S:
            self._cards.pop(self._card_index)
            return
        if waited >= GATE_RETRY_S and len(self._cards) - self._card_index > 1:
            self._cards.append(self._cards.pop(self._card_index))

    # -- the card on screen -------------------------------------------------

    def _show_card(self, card: ControlCard, progress: float | None = None) -> None:
        hud = self.hud()
        if hud is None:
            return
        hud.show_control_card(card.text, verb=card.verb, hint=card.hint, progress=progress)

    def _show_progress(self, card: ControlCard) -> None:
        """Report how far along the card is, when it has anything to show.

        A card that waits for a one-second hold and shows nothing for the first
        nine tenths of it reads as a card that is not listening, which is what
        a tap of the mining beam looked like. The HUD draws the bar; this only
        re-shows the card when the reading has moved a visible amount.
        """
        fraction = self.card_progress
        ticks = int(round(min(1.0, fraction) * PROGRESS_TICKS)) if fraction > 0.0 else None
        if ticks == self._progress_shown:
            return
        self._progress_shown = ticks
        self._show_card(card, fraction if ticks is not None else None)

    @property
    def card_progress(self) -> float:
        """How far the card in hand has got, from 0 to 1."""
        card = self.card
        if card is None or not self._card_shown or not card.verb:
            return 0.0
        hold = VERB_HOLD_S.get(card.verb, 0.0)
        if card.verb in OUTCOME_VERBS:
            done = self._scrap_earned() > self._scrap_mark
            held = min(1.0, self._verb_held / hold) if hold > 0.0 else float(self._verb_seen)
            return 1.0 if done else 0.5 * held
        if hold <= 0.0:
            return 0.0
        return min(1.0, self._verb_held / hold)

    def _answer_out_of_order(self, card: ControlCard) -> None:
        """Answer a key a later card teaches with what the script wants first.

        The run honours every one of these keys; this is not a refusal. It is
        the answer a pilot needs: a press that changes nothing visible on a
        tutorial screen reads as a broken key.

        Once per key per card, and never twice in the same breath. A pilot who
        keeps firing while learning to fly is not asking the same question over
        and over, and the toast line is needed for answers they have not had.

        It goes on the answer line as a *note* rather than as the line itself,
        because the run answers the same press in the same frame and has more to
        say about it: pressing the generator key with no generator fitted is
        both "the script wants you to fly first" and "there is no generator".
        If whichever spoke last were the whole answer, a pilot would read
        ``FIRST: FLY: W A S D`` and file Z as a dead key. See
        :meth:`shrike.hud.Hud.set_toast_note`.
        """
        if self._answer_cooldown > 0.0:
            return
        later = self._cards[self._card_index + 1 :]
        actions = {action for entry in later for action in VERB_ACTIONS.get(entry.verb, ())}
        actions -= set(VERB_ACTIONS.get(card.verb, ())) | self._answered
        pressed = next((action for action in sorted(actions) if Input.just_pressed(action)), "")
        if not pressed:
            return
        self._answered.add(pressed)
        hud = self.hud()
        if hud is not None:
            hud.set_toast_note(OUT_OF_ORDER_ANSWER.format(text=card.text.upper()))
        self._answer_cooldown = OUT_OF_ORDER_COOLDOWN_S

    def _scrap_earned(self) -> float:
        """Scrap this run has banked, which only ever goes up."""
        economy = self._service(Services.ECONOMY)
        return float(getattr(economy, "scrap_earned_this_run", 0.0)) if economy is not None else 0.0

    def _verb_performed(self, verb: str, dt: float) -> bool:
        """Whether the player has now done *verb*, holds and outcomes included.

        A hold has to be continuous: letting go puts the card back to zero, so
        the beam lesson is learned as a beam rather than as a click. The two
        harvest verbs want the outcome rather than the key: a beam held at
        empty space and an interact tapped at nothing have taught nobody
        anything, and a card that counted the key would tick over on both.
        """
        if verb == Verbs.AIM and self._aimed(dt):
            return True
        pressed = any(Input.pressed(action) for action in VERB_ACTIONS.get(verb, ()))
        self._verb_held = self._verb_held + dt if pressed else 0.0
        self._verb_seen = self._verb_seen or pressed
        held_enough = pressed and self._verb_held >= VERB_HOLD_S.get(verb, 0.0)
        if verb in OUTCOME_VERBS:
            return self._verb_seen and self._scrap_earned() > self._scrap_mark
        return held_enough

    def _aimed(self, dt: float) -> bool:
        """Whether the pointer has been moved, or the pad's aim stick pushed."""
        del dt
        stick = controller_aim_input()
        if abs(float(stick.x)) >= AIM_STICK_DEFLECTION or abs(float(stick.y)) >= AIM_STICK_DEFLECTION:
            return True
        mouse = Vec2(Input.mouse_position)
        if self._last_mouse is not None:
            self._mouse_travel += abs(float(mouse.x) - float(self._last_mouse.x))
            self._mouse_travel += abs(float(mouse.y) - float(self._last_mouse.y))
        self._last_mouse = mouse
        return self._mouse_travel >= AIM_MOUSE_TRAVEL_PX

    def set_sector(self, sector_index: int) -> None:
        """Follow the run's sector. A record, not a gate: the arrival is timed."""
        self.sector_index = int(sector_index)

    # -- lessons -----------------------------------------------------------

    def taught(self, lesson: str) -> bool:
        """Whether *lesson* has already been given to this profile."""
        if lesson in self._taught:
            return True
        return bool(lesson in self._profile_lessons())

    def teach(self, lesson: str) -> bool:
        """Queue *lesson* behind the script. False when it is already taught.

        The card joins the end of the script rather than replacing whatever is
        on screen: a lesson that shoves the card the player is still working
        through aside teaches neither.
        """
        card = LESSON_CARDS.get(lesson)
        if card is None or self.taught(lesson):
            return False
        self._taught.add(lesson)
        self._profile_lessons()[lesson] = True
        self._cards.append(card)
        return True

    def poll_lessons(self) -> None:
        """Teach whatever the run's own state now asks for."""
        economy = self._service(Services.ECONOMY)
        scrap = float(getattr(economy, "scrap", 0.0)) if economy is not None else 0.0
        if scrap >= SCRAP_LESSON_SCRAP:
            self.teach(Lessons.SCRAP)
        if scrap >= REFINE_LESSON_SCRAP and self.refinery_fitted():
            self.teach(Lessons.REFINE)

    def refinery_fitted(self) -> bool:
        """Whether the hull is carrying a Refinery right now."""
        tree = self.tree
        if tree is None:
            return False
        for ship in tree.group(Groups.SHIP):
            for node in ship.walk():
                installed = getattr(node, "installed_ids", None)
                if callable(installed) and REFINERY_MODULE_ID in installed():
                    return True
        return False

    # -- first sightings ---------------------------------------------------

    def poll_sightings(self) -> None:
        """Tag every archetype in the sector this profile has not met before."""
        tree = self.tree
        if tree is None:
            return
        for enemy in tree.group(Groups.ENEMIES):
            self.note_sighting(self.archetype_of(enemy), enemy)

    def note_sighting(self, archetype: str, enemy=None, *, position=None) -> bool:
        """Record a first sighting and float its tag. False when it is known.

        The tag rides *enemy* so it keeps up with something that is already
        closing; pass a *position* instead for a sighting whose node has gone.
        """
        archetype = str(archetype)
        if not archetype or archetype in self.seen_archetypes():
            return False
        self.seen_archetypes().append(archetype)
        hud = self.hud()
        if hud is not None and (enemy is not None or position is not None):
            hud.float_text(
                sighting_tag(archetype),
                node=enemy,
                position=position,
                hold_s=SIGHTING_TAG_HOLD_S,
                colour=COLOUR_ENEMY_TAG,
            )
        self.archetype_sighted.emit(archetype)
        return True

    @staticmethod
    def archetype_of(enemy) -> str:
        """The archetype id of *enemy*, the way ``combat.py`` reports its kills."""
        spec = getattr(enemy, "spec", None)
        archetype = getattr(spec, "id", None)
        return str(archetype) if archetype else type(enemy).__name__.lower()

    def seen_archetypes(self) -> list:
        """The profile's codex of met archetypes, or a run-local stand-in."""
        codex = self._profile_section("codex")
        seen = codex.get(CODEX_ENEMIES)
        if not isinstance(seen, list):
            seen = []
            codex[CODEX_ENEMIES] = seen
        return seen

    def _profile_lessons(self) -> dict:
        return self._profile_section("lessons")

    def _profile_section(self, key: str) -> dict:
        """One mutable section of the profile, created on first use.

        A director mounted without a profile keeps its sections on itself, so
        a harness (and the smoke gate) teaches each lesson once per run and
        writes nothing to disk.
        """
        if self.profile is None:
            self.profile = {}
        section = self.profile.get(key)
        if not isinstance(section, dict):
            section = {}
            self.profile[key] = section
        return section

    # -- effects -----------------------------------------------------------

    def apply_to_hud(self) -> bool:
        """Narrow the HUD to this run's element set. False when there is no HUD."""
        hud = self.hud()
        if hud is None:
            return False
        hud.set_visible_elements(self.onboarding.visible_hud_elements())
        return True

    def provoke_arrival(self) -> bool:
        """Top the tank up and drive the meter to lock. False when it cannot.

        Fuel first, always: the scripted arrival exists to teach the escape, so
        the escape has to be affordable before the klaxon sounds.
        """
        meter = self._service(Services.SIGNATURE)
        if meter is None:
            return False
        power = self._service(Services.POWER)
        arrival = self.onboarding.scripted_arrival() or ScriptedArrival()
        if power is not None and float(power.fuel) < arrival.guaranteed_fuel:
            power.add_fuel(arrival.guaranteed_fuel - float(power.fuel))
        self.provoked = True
        meter.add(balance.SIGNATURE_MAX, "onboarding", raw=True)
        self.arrival_provoked.emit()
        return True

    # -- lookups -----------------------------------------------------------

    def hud(self) -> Hud | None:
        """The run's HUD: the service entry if there is one, else the scene's."""
        tree = self.tree
        if tree is None:
            return None
        service = tree.singletons.get(Services.HUD)
        if isinstance(service, Hud):
            return service
        for node in iter_tree_nodes(tree):
            if isinstance(node, Hud):
                return node
        return None

    def _service(self, name: str):
        tree = self.tree
        return tree.singletons.get(name) if tree is not None else None