shrike/juice.py

Part of SHRIKE.

"""The feel layer: hit-stop, trauma-budgeted shake, punches and the scoop magnet.

Everything here is reaction. :class:`JuiceDirector` owns no gameplay state and
decides nothing: it listens to the signals the rest of the game already emits
and spends them on the player's hands and eyes. Kills buy hit-stop scaled by
how big the thing was, hits buy trauma, heavy shots buy recoil, and scrap
confetti leans toward the scoop so that income is a physical sensation rather
than a number ticking up in a corner.

Two rules shape the whole module.

**The clamp is load-bearing.** Shake is a trauma budget with a hard ceiling, a
squared response and an accessibility slider, and the ceiling drops further
while the Shrike's telegraph ladder is running. A mite shoal dying in a corner
must never blur the one warning the player's life depends on.

**A punch gives every unit back.** The engine's ``punch_position`` and
``punch_rotation`` coroutines drive a plain carrier, and the director mirrors
the carrier onto the node as a frame-to-frame delta. The node's own movement
code stays authoritative, and when the impulse ends the node is exactly where
its own logic put it.
"""

import math

from simvx.core import Node, Node3D, Quat, Signal, Vec2, Vec3, punch_position, punch_rotation

from . import balance
from .power import SignalWiring
from .runtime import (
    CAMERA_DISTANCE,
    CAMERA_FOV_DEGREES,
    PLANE_Y,
    WINDOW_HEIGHT,
    CameraRig,
    Groups,
    SignalNames,
    heading_to_direction,
    to_plane,
)
from .vfx import Vfx

# ============================================================================
# Numbers the design fixes by feel rather than by table, so balance.py has no
# name for them yet. Anything with a derivation is derived; the rest is flagged
# for the balance pass.
# ============================================================================

#: World units per screen pixel on the flight plane, from the camera rig's own
#: geometry. Section 10 quotes recoil and shake in pixels, and the game is 3D.
WORLD_UNITS_PER_PIXEL = (2.0 * CAMERA_DISTANCE * math.tan(math.radians(CAMERA_FOV_DEGREES) * 0.5)) / WINDOW_HEIGHT

#: Time constant of the ship's drift, seconds: ``INERTIAL_DAMPENING`` is applied
#: as ``d ** (dt * 60)``, so velocity decays as ``exp(-t / DRIFT_TIME_S)``.
DRIFT_TIME_S = 1.0 / (60.0 * math.log(1.0 / balance.INERTIAL_DAMPENING))

#: Rail lance recoil as a velocity impulse, sized so the shove coasts exactly
#: ``balance.RAILGUN_RECOIL_PX`` before the dampening eats it: a free dodge for
#: a player who fires across their own line of travel.
RAILGUN_RECOIL_UNITS = balance.RAILGUN_RECOIL_PX * WORLD_UNITS_PER_PIXEL
RAILGUN_RECOIL_IMPULSE = RAILGUN_RECOIL_UNITS / DRIFT_TIME_S

#: Scene time scale during a hit-stop. Not zero: the director counts its own
#: freeze in unscaled time, and a live scale keeps coroutines and audio sane.
HIT_STOP_TIME_SCALE = 0.05

#: Screen shake, in the pixels section 10 speaks and the units the camera uses.
SHAKE_MAX_OFFSET_PX = 26.0
SHAKE_MAX_OFFSET_UNITS = SHAKE_MAX_OFFSET_PX * WORLD_UNITS_PER_PIXEL
#: Trauma decays to nothing in about two thirds of a second.
TRAUMA_DECAY_PER_S = 1.6
#: The hard clamp. Trauma saturates here however much arrives in one frame.
TRAUMA_CEILING = 1.0
#: The clamp while a Shrike telegraph is running. The ladder must stay legible.
TELEGRAPH_TRAUMA_CEILING = 0.30
#: Wobble rates: the bearing sweeps at one rate and the swing beats at another,
#: deliberately incommensurate. Keeping them polar rather than per-axis is what
#: makes the clamp a real bound on the offset's length rather than on each axis.
SHAKE_BEARING_RATE_HZ = 21.0
SHAKE_SWING_RATE_HZ = 28.7

#: Trauma each event buys, before the ceiling and the slider.
TRAUMA_PER_KILL = 0.32
#: Trauma a hit costing the whole hull would buy, before the ceiling.
#:
#: Well over the ceiling on purpose. Shake amplitude is trauma *squared*, so the
#: old linear one-for-one meant the Shrike's 35-hull lantern burn, the single
#: heaviest blow in the game, bought 0.35 trauma and therefore twelve percent of
#: the shake budget: three pixels. The owner reported the burn as having no
#: feedback at all while cue after cue was added to it, and this is why.
#: At 2.6 a burn lands at 0.91, near the top of the budget, a mite's chip still
#: barely registers, and anything that takes half the hull saturates.
TRAUMA_PLAYER_HIT_FULL_HULL = 2.6
TRAUMA_SHIELD_FULL_ABSORB = 0.35
TRAUMA_RAILGUN_SHOT = 0.22
TRAUMA_ARRIVAL = 0.8

#: Fraction of maximum hull a single hit has to cost before it also stops the
#: clock. Chip damage must not stutter the game; a blow worth a third of the
#: hull has to land like one.
HIT_STOP_PLAYER_HIT_THRESHOLD = 0.15
#: Milliseconds of hit-stop such a blow buys, at the threshold and at a hit that
#: would take the whole hull. Both sit inside the kill band, so a wound never
#: freezes the game for longer than killing something does.
#:
#: The floor is the middle of that band rather than its bottom. The threshold
#: above has already thrown out every graze, so anything reaching this line is
#: a blow; starting it at the same 30 ms the smallest kill in the game buys
#: meant the Shrike's lantern, which takes a third of the hull in one frame,
#: stopped the clock for 37 ms. That is two frames, and it is the same weight
#: as swatting a mite.
HIT_STOP_PLAYER_HIT_MIN_MS = (balance.HIT_STOP_MIN_MS + balance.HIT_STOP_MAX_MS) * 0.5
HIT_STOP_PLAYER_HIT_MAX_MS = balance.HIT_STOP_MAX_MS
#: Shape of the ramp between them. Below 1 it rises fastest just past the
#: threshold, so the difference between a heavy blow and a lethal one is felt
#: rather than reserved for hits that would end the run outright.
HIT_STOP_PLAYER_HIT_CURVE = 0.5

#: Punch impulses, in world units of peak displacement, and their duration.
PUNCH_DURATION_S = 0.18
PUNCH_PLAYER_HIT_UNITS = 0.55
PUNCH_SHIELD_UNITS = 0.30
PUNCH_RECOIL_UNITS = 0.22
PUNCH_RAILGUN_UNITS = 0.60
PUNCH_DOCK_UNITS = 0.25
PUNCH_WARP_UNITS = 0.70
#: Rotational punches, radians of peak yaw on the camera rig.
TWIST_DURATION_S = 0.35
TWIST_DOCK_RADIANS = math.radians(1.4)
TWIST_WARP_RADIANS = math.radians(4.0)

#: The scoop magnet. Confetti inside this radius leans toward the ship; the
#: sector still owns the collection, this only makes the income visible.
SCOOP_ATTRACT_RADIUS = 12.0
SCOOP_PULL_MIN_PER_S = 3.0
SCOOP_PULL_MAX_PER_S = 16.0

#: Hit-stop for a kill scales with the archetype's threat cost against the
#: dearest ordinary archetype; a set-piece with no threat price is full size.
KILL_SIZE_REFERENCE_THREAT = max(spec.threat for spec in balance.ENEMIES.values())
#: An elite of any archetype reads one size larger than its base.
ELITE_KILL_SIZE_BONUS = 0.25

#: Safety net on the telegraph clamp, so a hunter that never arrives cannot
#: leave the shake permanently muted.
TELEGRAPH_GUARD_S = balance.SHRIKE_TELEGRAPH_FIRST_S


def kill_size(archetype: str, elite: bool = False) -> float:
    """How big a kill of *archetype* reads, from 0 to 1.

    Drives both the hit-stop length and the trauma a kill buys, so a mite pops
    and a Bombardier lands.
    """
    spec = balance.ENEMIES.get(archetype)
    size = 1.0 if spec is None or spec.threat <= 0 else spec.threat / KILL_SIZE_REFERENCE_THREAT
    if elite:
        size += ELITE_KILL_SIZE_BONUS
    return min(1.0, max(0.0, size))


def hit_stop_ms_for_kill(archetype: str, elite: bool = False) -> float:
    """Milliseconds of hit-stop a kill of *archetype* is worth."""
    span = balance.HIT_STOP_MAX_MS - balance.HIT_STOP_MIN_MS
    return balance.HIT_STOP_MIN_MS + span * kill_size(archetype, elite)


def hit_stop_ms_for_wound(hull_fraction: float) -> float:
    """Milliseconds of hit-stop a hit costing *hull_fraction* of the hull buys.

    Zero below :data:`HIT_STOP_PLAYER_HIT_THRESHOLD`, because a game that
    stutters every time a mite grazes the hull is a game with a frame-rate
    problem, not a game with weight.
    """
    hull_fraction = _clamp01(hull_fraction)
    if hull_fraction < HIT_STOP_PLAYER_HIT_THRESHOLD:
        return 0.0
    over = (hull_fraction - HIT_STOP_PLAYER_HIT_THRESHOLD) / max(1.0 - HIT_STOP_PLAYER_HIT_THRESHOLD, 1e-6)
    ramp = _clamp01(over) ** HIT_STOP_PLAYER_HIT_CURVE
    return HIT_STOP_PLAYER_HIT_MIN_MS + (HIT_STOP_PLAYER_HIT_MAX_MS - HIT_STOP_PLAYER_HIT_MIN_MS) * ramp


def _clamp01(value: float) -> float:
    return min(1.0, max(0.0, float(value)))


def _plane_direction(direction: Vec3) -> Vec2:
    """*direction* flattened onto the plane and scaled to unit length."""
    x, z = float(direction.x), float(direction.z)
    length = math.hypot(x, z)
    if length < 1e-9:
        return Vec2(0.0, 0.0)
    return Vec2(x / length, z / length)


class _PunchCarrier:
    """A plain target for the engine's punch coroutines.

    ``punch_position`` writes a ``Vec2`` and ``punch_rotation`` writes a float;
    a ``Node3D`` carries a ``Vec3`` and a ``Quat``. The coroutines drive this
    instead, and the director mirrors the result onto the node.
    """

    def __init__(self):
        self.position = Vec2(0.0, 0.0)
        self.rotation = 0.0


class _PlaneOffset:
    """Mirrors a carrier's plane offset onto a node as a per-frame delta."""

    def __init__(self, node: Node3D, carrier: _PunchCarrier):
        self._node = node
        self._carrier = carrier
        self._applied = Vec2(0.0, 0.0)

    def apply(self) -> None:
        node = self._node
        if node.destroying or node.tree is None:
            return
        current = Vec2(self._carrier.position)
        dx = float(current.x) - float(self._applied.x)
        dz = float(current.y) - float(self._applied.y)
        self._applied = current
        node.position = Vec3(float(node.position.x) + dx, float(node.position.y), float(node.position.z) + dz)


class _Twist:
    """Mirrors a carrier's angle onto a node as a yaw about the captured pose."""

    def __init__(self, node: Node3D, carrier: _PunchCarrier):
        self._node = node
        self._carrier = carrier
        self._base = node.rotation

    def apply(self) -> None:
        node = self._node
        if node.destroying or node.tree is None:
            return
        node.rotation = Quat.from_axis_angle(Vec3(0.0, 1.0, 0.0), float(self._carrier.rotation)) * self._base


def _drive(punch, mirror) -> object:
    """Step an engine punch coroutine and mirror each step onto its node.

    The engine coroutine restores the carrier to its base in its own ``finally``
    clause, so the trailing mirror is what hands the node its offset back.
    """
    step = None
    while True:
        try:
            punch.send(step)
        except StopIteration:
            break
        mirror.apply()
        step = yield
    mirror.apply()


class JuiceDirector(Node):
    """The run's feel layer, registered as ``Services.JUICE``.

    Consumes ``ENEMY_KILLED`` (hit-stop and trauma scaled by kill size, plus
    the combo rung the audio ladder pitches on), ``PLAYER_DAMAGED`` and
    ``SHIELD_ABSORBED`` (directional sparks and a punch), ``WEAPON_FIRED``
    (recoil, and the rail lance's shove), ``DOCKED`` and the warp signals
    (punch and twist), and ``HUNTER_TELEGRAPH`` (which tightens the shake clamp
    until the thing actually arrives).

    Accessibility: :attr:`shake_scale` and :attr:`hit_stop_scale` are the two
    sliders section 10 promises, both 0 to 1, and both able to switch their
    effect off entirely without changing anything else.
    """

    #: (rung: int) the kill-combo rung, inside ``balance.KILL_COMBO_WINDOW_S``.
    kill_ladder = Signal(int)

    def __init__(self, *, shake_scale: float = 1.0, hit_stop_scale: float = 1.0, **kwargs):
        super().__init__(**kwargs)
        #: Live trauma, 0 to 1. Shake is its square.
        self.trauma = 0.0
        #: Seconds of hit-stop still to run, counted in unscaled time.
        self.hit_stop_remaining = 0.0
        #: The scene time scale the director is asking for.
        self.time_scale = 1.0
        #: Kills inside the current combo window.
        self.kill_combo = 0

        self._shake_scale = _clamp01(shake_scale)
        self._hit_stop_scale = _clamp01(hit_stop_scale)
        self._applied_scale = 1.0
        self._scaled_app = None
        self._combo_remaining = 0.0
        self._telegraph_guard = 0.0
        self._shake_time = 0.0
        self._shake_offset = Vec2(0.0, 0.0)
        self._shake_applied = Vec2(0.0, 0.0)
        self._rig: CameraRig | None = None
        self._wiring = SignalWiring(self)

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

    def on_ready(self):
        for signal_name, handler in (
            (SignalNames.ENEMY_KILLED, self._on_enemy_killed),
            (SignalNames.PLAYER_DAMAGED, self._on_player_damaged),
            (SignalNames.SHIELD_ABSORBED, self._on_shield_absorbed),
            (SignalNames.WEAPON_FIRED, self._on_weapon_fired),
            (SignalNames.DOCKED, self._on_docked),
            (SignalNames.WARP_SPOOL_STARTED, self._on_warp_spool_started),
            (SignalNames.WARP_COMPLETED, self._on_warp_completed),
            (SignalNames.HUNTER_TELEGRAPH, self._on_hunter_telegraph),
            (SignalNames.HUNTER_ARRIVED, self._on_hunter_arrived),
        ):
            self._wiring.want(signal_name, handler)
        # No sweep here on purpose: the director is a singleton, so its
        # on_ready runs while the run scene is still assembling itself. The
        # first poll of on_update sweeps a fully mounted tree instead.

    def on_exit_tree(self):
        """Hand the scene clock back however the director was holding it."""
        if self._applied_scale != 1.0:
            self._set_time_scale(1.0)
        self.hit_stop_remaining = 0.0

    # --------------------------------------------------------------- settings

    @property
    def shake_scale(self) -> float:
        """Screen-shake slider, 0 (off) to 1 (full)."""
        return self._shake_scale

    @shake_scale.setter
    def shake_scale(self, value: float) -> None:
        self._shake_scale = _clamp01(value)

    @property
    def hit_stop_scale(self) -> float:
        """Hit-stop slider, 0 (off) to 1 (full)."""
        return self._hit_stop_scale

    @hit_stop_scale.setter
    def hit_stop_scale(self, value: float) -> None:
        self._hit_stop_scale = _clamp01(value)

    @property
    def trauma_ceiling(self) -> float:
        """The live hard clamp: tighter while a telegraph is on screen."""
        return TELEGRAPH_TRAUMA_CEILING if self._telegraph_guard > 0.0 else TRAUMA_CEILING

    @property
    def shake_offset(self) -> Vec2:
        """The plane offset the camera rig is currently carrying."""
        return Vec2(self._shake_offset)

    # ---------------------------------------------------------- public surface

    def hit_stop(self, ms: float) -> None:
        """Freeze the scene clock for *ms* milliseconds of unscaled time.

        Overlapping calls take the longer freeze rather than stacking, so a
        shoal wiping out in one flak burst reads as one beat, not eight.
        """
        ms = min(max(float(ms), 0.0), balance.HIT_STOP_MAX_MS) * self._hit_stop_scale
        if ms <= 0.0:
            return
        self.hit_stop_remaining = max(self.hit_stop_remaining, ms / 1000.0)
        self._set_time_scale(HIT_STOP_TIME_SCALE)

    def shake(self, trauma: float) -> None:
        """Add *trauma* to the budget, saturating at the live ceiling.

        The slider scales what the camera does with the budget, not the budget
        itself, so it reads as a linear "how much shake" control; at zero the
        trauma is not even banked.
        """
        trauma = max(0.0, float(trauma))
        if trauma <= 0.0 or self._shake_scale <= 0.0:
            return
        self.trauma = min(self.trauma_ceiling, self.trauma + trauma)

    def punch(self, node: Node3D, direction: Vec3, strength: float) -> None:
        """Kick *node* along *direction* by *strength* world units, and back.

        The impulse is a damped sine on the node's plane position; it is purely
        additive, so the node's own movement keeps running underneath it and the
        offset is returned in full when the impulse ends.
        """
        if node is None or node.destroying or strength <= 0.0:
            return
        aim = _plane_direction(Vec3(direction))
        if float(aim.x) == 0.0 and float(aim.y) == 0.0:
            return
        carrier = _PunchCarrier()
        amplitude = Vec2(float(aim.x) * float(strength), float(aim.y) * float(strength))
        coroutine = punch_position(carrier, amplitude, PUNCH_DURATION_S)
        self.start_coroutine(_drive(coroutine, _PlaneOffset(node, carrier)))

    def punch_twist(self, node: Node3D, radians: float) -> None:
        """Yaw *node* about its current pose and settle it back.

        For nodes that do not drive their own rotation: the camera rig, a dock
        ring. The ship's nose is written every frame by its own aim code, so it
        takes :meth:`punch` instead.
        """
        if node is None or node.destroying or radians == 0.0:
            return
        carrier = _PunchCarrier()
        coroutine = punch_rotation(carrier, float(radians), TWIST_DURATION_S)
        self.start_coroutine(_drive(coroutine, _Twist(node, carrier)))

    def kill_juice(self, archetype: str, position: Vec3, elite: bool = False) -> None:
        """The full kill reaction: stop, shake, debris, and the ladder rung."""
        size = kill_size(archetype, elite)
        self.hit_stop(hit_stop_ms_for_kill(archetype, elite))
        self.shake(TRAUMA_PER_KILL * size)
        self._advance_combo()
        tree = self.tree
        if tree is not None and tree.root is not None:
            Vfx.spawn(tree, "explosion", position, scale=0.6 + size)
            Vfx.spawn(tree, "scrap_confetti", position, scale=0.6 + size)

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

    def on_update(self, dt: float):
        unscaled = dt / self._applied_scale if self._applied_scale > 0.0 else dt
        self._wiring.poll(unscaled)
        self._tick_hit_stop(unscaled)
        self._tick_combo(unscaled)
        self._tick_telegraph_guard(unscaled)
        self._tick_shake(unscaled)
        self._tick_scoop_magnet(dt)

    def _tick_hit_stop(self, dt: float) -> None:
        if self.hit_stop_remaining <= 0.0:
            return
        self.hit_stop_remaining -= dt
        if self.hit_stop_remaining <= 0.0:
            self.hit_stop_remaining = 0.0
            self._set_time_scale(1.0)

    def _tick_combo(self, dt: float) -> None:
        if self._combo_remaining <= 0.0:
            return
        self._combo_remaining -= dt
        if self._combo_remaining <= 0.0:
            self._combo_remaining = 0.0
            self.kill_combo = 0

    def _tick_telegraph_guard(self, dt: float) -> None:
        if self._telegraph_guard > 0.0:
            self._telegraph_guard = max(0.0, self._telegraph_guard - dt)
            self.trauma = min(self.trauma, self.trauma_ceiling)

    def _tick_shake(self, dt: float) -> None:
        self._shake_time += dt
        if self.trauma > 0.0:
            self.trauma = max(0.0, self.trauma - TRAUMA_DECAY_PER_S * dt)
        amplitude = SHAKE_MAX_OFFSET_UNITS * self.trauma * self.trauma * self._shake_scale
        if amplitude <= 0.0:
            self._shake_offset = Vec2(0.0, 0.0)
        else:
            bearing = self._shake_time * math.tau * SHAKE_BEARING_RATE_HZ
            swing = amplitude * math.sin(self._shake_time * math.tau * SHAKE_SWING_RATE_HZ + 1.7)
            self._shake_offset = Vec2(swing * math.cos(bearing), swing * math.sin(bearing))
        self._apply_shake()

    def _apply_shake(self) -> None:
        """Carry the shake on the rig itself, leaving its follow code alone."""
        rig = self._camera_rig()
        if rig is None:
            self._shake_applied = Vec2(0.0, 0.0)
            return
        dx = float(self._shake_offset.x) - float(self._shake_applied.x)
        dz = float(self._shake_offset.y) - float(self._shake_applied.y)
        self._shake_applied = Vec2(self._shake_offset)
        if dx == 0.0 and dz == 0.0:
            return
        rig.position = Vec3(float(rig.position.x) + dx, float(rig.position.y), float(rig.position.z) + dz)

    def _tick_scoop_magnet(self, dt: float) -> None:
        """Lean loose salvage toward the ship so income is a physical thing.

        Only the lean lives here. The sector still owns collection, so a mote
        the magnet drags in is credited exactly once, by the code that always
        credited it.
        """
        tree = self.tree
        if tree is None or dt <= 0.0:
            return
        ship = tree.get_first_in_group(Groups.SHIP)
        if ship is None or ship.destroying:
            return
        here = to_plane(ship.position)
        for mote in tree.group(Groups.SALVAGE):
            if mote.destroying or getattr(mote, "collected", False):
                continue
            there = to_plane(mote.position)
            dx = float(here.x) - float(there.x)
            dz = float(here.y) - float(there.y)
            distance = math.hypot(dx, dz)
            if distance <= 1e-6 or distance > SCOOP_ATTRACT_RADIUS:
                continue
            closeness = 1.0 - distance / SCOOP_ATTRACT_RADIUS
            speed = SCOOP_PULL_MIN_PER_S + (SCOOP_PULL_MAX_PER_S - SCOOP_PULL_MIN_PER_S) * closeness
            step = min(distance, speed * dt)
            mote.position = Vec3(
                float(mote.position.x) + dx / distance * step,
                PLANE_Y,
                float(mote.position.z) + dz / distance * step,
            )

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

    def _on_enemy_killed(self, archetype: str, position: Vec3, elite: bool) -> None:
        self.kill_juice(str(archetype), Vec3(position), bool(elite))

    def _on_player_damaged(self, amount: float, direction: Vec3) -> None:
        hull_max = max(float(balance.HULL_MAX_STARTER), 1e-6)
        cost = _clamp01(float(amount) / hull_max)
        self.shake(TRAUMA_PLAYER_HIT_FULL_HULL * cost)
        self.hit_stop(hit_stop_ms_for_wound(cost))
        toward_attacker = Vec3(direction)
        away = Vec3(-float(toward_attacker.x), 0.0, -float(toward_attacker.z))
        ship = self._ship()
        if ship is not None:
            self.punch(ship, away, PUNCH_PLAYER_HIT_UNITS)
            self._spawn(ship, "impact", toward_attacker)
        rig = self._camera_rig()
        if rig is not None:
            self.punch(rig, away, PUNCH_PLAYER_HIT_UNITS)

    def _on_shield_absorbed(self, amount: float) -> None:
        """Sparks fly off the facing that took the hit, not off the hull."""
        self.shake(TRAUMA_SHIELD_FULL_ABSORB * _clamp01(float(amount) / balance.SHIELD_ABSORB_MAX))
        ship = self._ship()
        if ship is None:
            return
        facing = self._shield_facing(ship)
        self.punch(ship, -facing, PUNCH_SHIELD_UNITS)
        self._spawn(ship, "shield_spark", facing)

    def _on_weapon_fired(self, weapon_id: str) -> None:
        """Recoil, and for the rail lance a shove worth steering with."""
        ship = self._ship()
        if ship is None:
            return
        back = -self._nose_direction(ship)
        if str(weapon_id) == "rail_lance":
            self.punch(ship, back, PUNCH_RAILGUN_UNITS)
            self.shake(TRAUMA_RAILGUN_SHOT)
            self._shove(ship, back, RAILGUN_RECOIL_IMPULSE)
            return
        self.punch(ship, back, PUNCH_RECOIL_UNITS)

    def _on_docked(self, depot_id: str) -> None:
        del depot_id
        rig = self._camera_rig()
        ship = self._ship()
        if ship is not None:
            self.punch(ship, self._nose_direction(ship), PUNCH_DOCK_UNITS)
        if rig is not None:
            self.punch_twist(rig, TWIST_DOCK_RADIANS)

    def _on_warp_spool_started(self, emergency: bool) -> None:
        del emergency
        rig = self._camera_rig()
        if rig is not None:
            self.punch_twist(rig, -TWIST_DOCK_RADIANS)

    def _on_warp_completed(self, emergency: bool) -> None:
        del emergency
        # The jump's own punch is the only feel that crosses it. Trauma and
        # hit stop are answers to blows landed in the sector being left, and a
        # camera still swinging, or a clock still stopped, from a fight several
        # light-years back reads as the new sector doing it to you.
        self.trauma = 0.0
        self._shake_offset = Vec2(0.0, 0.0)
        self._apply_shake()
        if self.hit_stop_remaining > 0.0:
            self.hit_stop_remaining = 0.0
            self._set_time_scale(1.0)
        ship = self._ship()
        rig = self._camera_rig()
        if ship is not None:
            self.punch(ship, self._nose_direction(ship), PUNCH_WARP_UNITS)
            self._spawn(ship, "warp_implosion", self._nose_direction(ship))
        if rig is not None:
            self.punch_twist(rig, TWIST_WARP_RADIANS)

    def _on_hunter_telegraph(self, stage: str) -> None:
        del stage
        self._telegraph_guard = TELEGRAPH_GUARD_S
        self.trauma = min(self.trauma, self.trauma_ceiling)

    def _on_hunter_arrived(self, arrival_index: int = 0) -> None:
        del arrival_index
        self._telegraph_guard = 0.0
        self.shake(TRAUMA_ARRIVAL)

    # ---------------------------------------------------------------- helpers

    def _advance_combo(self) -> None:
        self.kill_combo = self.kill_combo + 1 if self._combo_remaining > 0.0 else 1
        self._combo_remaining = balance.KILL_COMBO_WINDOW_S
        self.kill_ladder(self.kill_combo)

    def _set_time_scale(self, scale: float) -> None:
        """Ask the app for *scale*, and remember what it actually granted.

        The app scales the dt the director itself is ticked with, so the granted
        factor is what turns that dt back into the unscaled seconds a hit-stop
        is counted in. Headless there is no app, nothing is scaled, and the
        director's own clock is already unscaled.
        """
        self.time_scale = float(scale)
        app = self.app or self._scaled_app
        if app is None or not hasattr(app, "time_scale"):
            self._applied_scale = 1.0
            return
        app.time_scale = float(scale)
        self._applied_scale = float(scale)
        self._scaled_app = app if scale != 1.0 else None

    def _ship(self) -> Node3D | None:
        tree = self.tree
        if tree is None:
            return None
        ship = tree.get_first_in_group(Groups.SHIP)
        return None if ship is None or ship.destroying else ship

    def _camera_rig(self) -> CameraRig | None:
        rig = self._rig
        if rig is not None and not rig.destroying and rig.tree is not None:
            return rig
        self._rig = None
        tree = self.tree
        if tree is None or tree.root is None:
            return None
        self._rig = tree.root if isinstance(tree.root, CameraRig) else tree.root.find(CameraRig)
        return self._rig

    def _nose_direction(self, ship: Node3D) -> Vec3:
        """Unit world vector along the ship's nose."""
        return heading_to_direction(float(getattr(ship, "heading", 0.0)))

    def _shield_facing(self, ship: Node3D) -> Vec3:
        """Unit world vector along the shield arc's centre, or the nose."""
        shield = getattr(ship, "shield", None)
        if shield is None:
            return self._nose_direction(ship)
        return heading_to_direction(float(shield.absolute_centre()))

    def _shove(self, ship: Node3D, direction: Vec3, impulse: float) -> None:
        """Add a velocity impulse to the ship, the recoil's mobility half."""
        velocity = getattr(ship, "velocity", None)
        if velocity is None:
            return
        aim = _plane_direction(Vec3(direction))
        ship.velocity = Vec2(
            float(velocity.x) + float(aim.x) * impulse,
            float(velocity.y) + float(aim.y) * impulse,
        )

    def _spawn(self, ship: Node3D, effect: str, facing: Vec3) -> None:
        """Play a one-shot on the hull's surface along *facing*."""
        tree = self.tree
        if tree is None or tree.root is None:
            return
        at = Vec3(
            float(ship.position.x) + float(facing.x),
            PLANE_Y,
            float(ship.position.z) + float(facing.z),
        )
        Vfx.spawn(tree, effect, at, direction=Vec3(facing))


__all__ = [
    "HIT_STOP_TIME_SCALE",
    "RAILGUN_RECOIL_IMPULSE",
    "RAILGUN_RECOIL_UNITS",
    "SCOOP_ATTRACT_RADIUS",
    "SHAKE_MAX_OFFSET_UNITS",
    "TELEGRAPH_TRAUMA_CEILING",
    "TRAUMA_CEILING",
    "JuiceDirector",
    "hit_stop_ms_for_kill",
    "hit_stop_ms_for_wound",
    "kill_size",
]