shrike/vfx.py

Part of SHRIKE.

"""SHRIKE's effects library: pooled bursts, the two live emitters and the dust.

Everything here is tinted from :mod:`shrike.artkit`'s palettes, so ownership
survives a screen with two hundred grains on it: player warm gold and white,
enemy cold magenta, telegraphs white, the hunter's lantern a bruised violet.

Five shapes of effect live here.

* **One-shots** go through :meth:`Vfx.spawn`, which draws from a fixed pool
  parented under the run scene. Nothing allocates per hit, and the pool never
  grows past :data:`VFX_POOL_SIZE`: under a barrage the oldest burst is
  recycled rather than the frame budget.
* **The thrust plume**, :class:`EngineRibbon`, is geometry rather than grains.
  A drive under power is one continuous jet, and a trail of separate warm puffs
  behind a hull is the visual grammar of something detonating: the flare is a
  tapered cone anchored on the nozzle, stretched down the thrust vector, with a
  tight mote stream inside it for texture.
* **The lantern**, :class:`LanternCone`, is the Shrike's head: a drawn beam
  with a shadow-casting spot inside it and its own dust, sweeping bright,
  dimming for the one second that warns of a burn, and flaring on the burn. Its
  shell is capped at :data:`LANTERN_CONE_EMISSIVE_MAX`, because the same beam
  that has to be unmissable also crosses the HUD band, and a bloomed white plane
  over HULL and SIGNATURE explains nothing about the blow it just landed.
* **The dock ring**, :class:`DockRing`, is a bay drawn on the ground: dashed and
  cool outside, lit and breathing once the hull is inside it. A radius in a
  sensor is not a place, and a pilot crossed one three times looking for the
  shop that was in it.
* **The dust field**, :class:`DustField`, is the one thing here that is not a
  flourish. Space with nothing in it has no motion cue at all, and a ship at
  cruise on an empty screen reads as a ship sitting still. The field tiles two
  parallax bands of motes around the camera focus so speed is always visible.
  The motes are soft, dim and tinted with the act, because grain that is bright
  and white is not dust: it is confetti in front of the fight.

The engine ribbon is also where notoriety becomes visible: it consumes
``NOTORIETY_CHANGED`` and brightens with the player's reputation, which is the
one tell a hunting Magistrate reads before the player does.
"""

from __future__ import annotations

import math
from dataclasses import dataclass, field

import numpy as np

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

from . import balance
from .artkit import ACT_GRADES, PLUME_CORE, PLUME_FLARE, act_grade, build_engine_plume, palette
from .runtime import CameraRig, Groups, Services, SignalNames, camera_plane_extents, to_plane

# ============================================================================
# Module-local constants
#
# Presentation numbers, deliberately not in balance.py: none of them changes
# what the game does, only what it looks like while doing it.
# ============================================================================

#: Concurrent one-shot bursts. Past this the oldest is recycled.
VFX_POOL_SIZE = 48

#: Extra seconds a burst is held before it returns to the pool, so the last
#: grains of a long-lived emitter are not cut off mid-fade.
VFX_RETIRE_MARGIN_S = 0.15

#: Engine-trail emissive multiplier at zero and at maximum notoriety.
TRAIL_BRIGHTNESS_QUIET = 1.0
TRAIL_BRIGHTNESS_NOTORIOUS = 2.6

#: The plume's mouth radius at full throttle, and the fraction of it a plume
#: keeps at the lightest touch on the thrust, so a nudge is still a jet.
PLUME_RADIUS_UNITS = 0.44
PLUME_IDLE_FRACTION = 0.55
#: How far the flare reaches behind the nozzle at the extremes of the throttle.
#: The ship is 2.6 units long, so a full burn trails a plume longer than the
#: hull: that length difference is the tell that the burner is lit.
PLUME_LENGTH_MIN_UNITS = 1.2
PLUME_LENGTH_MAX_UNITS = 3.6
#: Opacity of the outer flare and the inner core at full throttle.
PLUME_FLARE_ALPHA = 0.55
PLUME_CORE_ALPHA = 0.7
#: The core burns toward white: the hottest part of a flame is the least
#: saturated part, and it is what makes the plume read as heat.
PLUME_CORE_COLOUR = (1.0, 0.96, 0.88)
PLUME_CORE_ENERGY = 1.0

# -- The afterburner, as something to look at --------------------------------
#
# The throttle alone carries the burn from 0.65 to 1.0, which moves the plume
# by a third of its length and a quarter of its brightness: a difference a
# pilot can measure but not notice. Shift is a resource decision and it has to
# read as a state change, so the burn is a multiplier laid over the throttle
# rather than the top of the throttle's own range. At full burn the jet is
# longer than the hull twice over and its core has gone from candle-white to
# the blue-white of a torch.

#: What a full burn does to the flare's length, its bore and its heat.
PLUME_BURN_LENGTH_MULT = 1.9
PLUME_BURN_RADIUS_MULT = 1.35
PLUME_BURN_GLOW_MULT = 2.1
#: The burning core's colour: hotter than the cruise core, and colder in hue,
#: which is what "hotter" looks like.
PLUME_BURN_CORE_COLOUR = (0.78, 0.90, 1.0)

#: Dust motes are neutral and cold on purpose: the readability contract gives
#: warm gold to player fire and magenta to enemy fire, and the one thing that
#: is on screen at all times must claim neither.
DUST_NEAR_COLOUR = (0.60, 0.68, 0.84)
DUST_FAR_COLOUR = (0.34, 0.40, 0.54)
#: Movement of the camera focus, in world units, below which the dust field
#: leaves its transforms alone.
DUST_REFRESH_EPSILON = 0.01
#: How far a mote's colour is carried toward the act's own hue. Grain that is
#: white in every sector is confetti; grain that is the colour of the place is
#: the place, so the tint moves with the act while the neutral base keeps the
#: motes from competing with either faction's fire.
DUST_ACT_TINT = 0.55
#: A mote's opacity. Solid grain reads as debris in the foreground: these are
#: meant to be barely there, and it is their motion that carries the cue.
DUST_ALPHA = 0.55
#: Size attenuation across a band's tile: a mote at the tile edge, which is the
#: furthest the camera can see it, is drawn at this fraction of its own size.
#: Without it every mote is the same size wherever it is, which flattens the
#: field into a screen-door pattern rather than a volume of dust.
DUST_FAR_SIZE_FRACTION = 0.35
#: Rings and segments of the mote sphere. Motes are two or three pixels across,
#: so this is as much sphere as the screen can resolve.
DUST_MOTE_RINGS = 4
DUST_MOTE_SEGMENTS = 6

#: The health pip: a thin flat bar for the hulls big enough to be worth a
#: read-out. Deliberately small and dim next to everything else on the plane,
#: because it is chrome on a screen whose readability contract belongs to fire.
PIP_WIDTH_UNITS = 2.4
PIP_THICKNESS_UNITS = 0.05
PIP_DEPTH_UNITS = 0.22
#: The fill is drawn slightly narrower than its track, so the track reads as a
#: frame around it rather than as a second bar.
PIP_FILL_INSET = 0.72
PIP_TRACK_COLOUR = (0.06, 0.05, 0.08)
PIP_TRACK_ALPHA = 0.75
#: Enemy-side chrome carries the enemy's own hue, not the player's warm gold.
PIP_FILL_COLOUR = palette("enemy").accent
PIP_FILL_ENERGY = 1.6
#: Seconds the pip takes to fade all the way in or out.
PIP_FADE_S = 0.35

#: How far the pilot can see across the flight plane in any direction, from the
#: camera's own geometry rather than guessed. The rig biases its focus so the
#: warning above and below the hull is equal, which makes the visible field a
#: disc of this radius centred on the ship. Anything that decides how far away
#: a threat may act from measures itself against this: what the player cannot
#: see must not be allowed to hurt them.
VISIBLE_REACH_UNITS = sum(camera_plane_extents()) * 0.5

#: The lantern's cone half-angles, degrees, and its reach in world units.
#:
#: The reach is that visible field, not a number chosen for feel: the cone that
#: burns you is the cone you can see coming, and at the old 46 units the beast
#: could stand two screens off and burn from a place the player had no way to
#: look at. Deriving it from the camera keeps the light, the burn and the
#: window agreeing whatever shape the window is.
LANTERN_INNER_CONE_DEGREES = 9.0
LANTERN_OUTER_CONE_DEGREES = 17.0
LANTERN_RANGE = VISIBLE_REACH_UNITS
LANTERN_INTENSITY = 7.0
#: Fraction of full intensity during the pre-burn dim that warns of a sweep.
LANTERN_PREBURN_DIM = 0.22
#: What the lantern does on the burn frame: the sweep, hard over. The burn is
#: the only frame in the cycle that costs hull, so it is the only one that
#: flares, and the flare is what the pilot can point at afterwards.
LANTERN_BURN_FLARE = 2.4

#: The cone's own geometry, per phase, as the alpha of a bruised-violet shell.
#:
#: A ``SpotLight3D`` and nothing else is invisible here. The arena is empty
#: space: the beam crosses no floor and no wall, so there is no surface for it
#: to fall on, and a sweep held at zero intensity on top of that landed on
#: nothing twice over. A pilot could watch the beast in full view for a whole
#: arrival and never see it attack, because the attack was a light with nothing
#: to light. The shaft is therefore drawn as translucent emissive geometry, and
#: the light is what it casts rather than what it is.
LANTERN_CONE_ALPHA_SWEEP = 0.20
LANTERN_CONE_ALPHA_PREBURN = 0.09
LANTERN_CONE_ALPHA_BURN = 0.44
#: Emissive strength of the shell per phase, so the flare reads as heat and not
#: only as opacity. Multiplies the hunter palette's own accent strength.
LANTERN_CONE_GLOW_SWEEP = 1.0
LANTERN_CONE_GLOW_PREBURN = 0.45
LANTERN_CONE_GLOW_BURN = 2.6
#: Ceiling on the shell's own emissive strength, whatever the phase asks for.
#:
#: The hunter accent is authored at 6.5, which is right for a slim trim line on
#: a hull seen across the arena and several stops too hot for a shaft that fills
#: a third of the frame. Multiplied by the burn's glow it put the cone far over
#: white, bloomed, and a blind playtest photographed the burn frame with the
#: hull arc, the HULL number and the SIGNATURE reading all inside it and none of
#: them readable. The cap keeps the shell a bruised violet flare that is still
#: the brightest thing on the screen without being a white plate over the one
#: set of readings the burn exists to explain. The HUD plates its readings as
#: well (``hud.COLOUR_READING_PLATE``); neither fix is sufficient alone, because
#: the arcs are not text and the plates are not the beam.
LANTERN_CONE_EMISSIVE_MAX = 3.4
#: How the flare decays: seconds held hard over, then seconds easing back to
#: the sweep look for the rest of the burn window.
#:
#: The hull is spent on the first frame the ship is in the cone, so everything
#: after that frame is punctuation. Held hard over for the whole window, the
#: punctuation was the problem: nine per cent of the frame went over luminance
#: 200, the label naming the blow was written into the middle of it, and the
#: burn's own art was the only thing stopping the burn from being read. It
#: still opens as the brightest thing on the screen; it just gets out of the
#: way of the readouts it is supposed to be explaining.
LANTERN_BURN_FLASH_S = 0.14
LANTERN_BURN_FALLOFF_S = 0.26
#: Segments around the shell's base. A cone this wide on screen needs enough
#: of them that its edge reads as a beam rather than as a faceted prism.
LANTERN_CONE_SEGMENTS = 24


@dataclass(frozen=True)
class EffectSpec:
    """One one-shot effect's emitter shape.

    ``faction`` names the :mod:`shrike.artkit` palette the grains are tinted
    from, which is what keeps the readability contract true in the particle
    layer as well as on the hulls.
    """

    id: str
    faction: str
    amount: int
    lifetime: float
    speed: float
    speed_variance: float = 0.0
    spread: float = 0.6
    spread_pattern: str = "gaussian"
    damping: float = 0.0
    start_scale: float = 0.3
    end_scale: float = 0.0
    explosiveness: float = 1.0
    streak: float = 0.0
    emission_radius: float = 0.0
    #: Multiplies the palette accent to make a grain hotter than its hull.
    energy: float = 1.0
    gravity: tuple[float, float, float] = field(default=(0.0, 0.0, 0.0))


#: Every effect id :meth:`Vfx.spawn` accepts.
EFFECTS: dict[str, EffectSpec] = {
    "muzzle": EffectSpec(
        "muzzle",
        "player",
        amount=24,
        lifetime=0.14,
        speed=22.0,
        speed_variance=6.0,
        spread=0.28,
        start_scale=0.22,
        streak=0.03,
        energy=1.6,
    ),
    "impact": EffectSpec(
        "impact",
        "player",
        amount=40,
        lifetime=0.32,
        speed=13.0,
        speed_variance=5.0,
        spread=1.1,
        spread_pattern="ring",
        damping=3.0,
        start_scale=0.2,
        energy=1.4,
    ),
    # A wound, not a kill. Small, brief and warm: it is the player's own round
    # coming apart on a hull, and it has to read at a glance without competing
    # with the explosion that ends the same hull a second later.
    "enemy_hit": EffectSpec(
        "enemy_hit",
        "player",
        amount=16,
        lifetime=0.18,
        speed=15.0,
        speed_variance=6.0,
        spread=1.3,
        spread_pattern="ring",
        damping=4.0,
        start_scale=0.14,
        end_scale=0.02,
        streak=0.04,
        energy=2.0,
    ),
    # Where a held beam is actually biting. Cheap and continuous rather than
    # loud and one-off: it is re-emitted several times a second for as long as
    # the beam is on a surface, so it has to read as a shower of chips coming
    # off rock and never as an explosion. A beam crossing empty space emits
    # none, which is the whole point of it.
    "beam_spark": EffectSpec(
        "beam_spark",
        "player",
        amount=10,
        lifetime=0.22,
        speed=9.0,
        speed_variance=4.0,
        spread=1.5,
        spread_pattern="ring",
        damping=5.0,
        start_scale=0.11,
        end_scale=0.01,
        streak=0.03,
        energy=1.7,
    ),
    "shield_spark": EffectSpec(
        "shield_spark",
        "player",
        amount=64,
        lifetime=0.45,
        speed=17.0,
        speed_variance=7.0,
        spread=0.9,
        spread_pattern="disc",
        damping=2.2,
        start_scale=0.16,
        streak=0.05,
        energy=1.8,
    ),
    "explosion": EffectSpec(
        "explosion",
        "enemy",
        amount=180,
        lifetime=0.85,
        speed=19.0,
        speed_variance=9.0,
        spread=1.6,
        spread_pattern="star",
        damping=1.6,
        start_scale=0.55,
        end_scale=0.05,
        emission_radius=0.4,
        energy=2.2,
    ),
    "scrap_confetti": EffectSpec(
        "scrap_confetti",
        "environment",
        amount=48,
        lifetime=1.4,
        speed=7.0,
        speed_variance=3.5,
        spread=1.4,
        spread_pattern="ring",
        damping=1.1,
        start_scale=0.18,
        end_scale=0.08,
        energy=1.2,
    ),
    "salvage_motes": EffectSpec(
        "salvage_motes",
        "environment",
        amount=64,
        lifetime=1.0,
        speed=9.0,
        speed_variance=2.0,
        spread=0.5,
        spread_pattern="disc",
        start_scale=0.12,
        end_scale=0.02,
        explosiveness=0.2,
        emission_radius=1.6,
        energy=1.6,
    ),
    # A negative launch speed on a ring of grains born at the spool radius is
    # what makes the implosion collapse inwards rather than blow outwards.
    "warp_implosion": EffectSpec(
        "warp_implosion",
        "player",
        amount=220,
        lifetime=0.7,
        speed=-26.0,
        speed_variance=4.0,
        spread=1.2,
        spread_pattern="ring",
        start_scale=0.1,
        end_scale=0.5,
        emission_radius=7.0,
        energy=2.4,
    ),
    # The mote stream inside the plume. Everything about it is chosen to read
    # as one continuous jet: no explosiveness, so grains leave the nozzle at an
    # even rate rather than in puffs; a spread of a couple of degrees, so the
    # stream stays a line; a short life at high speed, so a grain is a streak
    # and never a floating blob.
    "engine_ribbon": EffectSpec(
        "engine_ribbon",
        "player",
        amount=34,
        lifetime=0.11,
        speed=22.0,
        speed_variance=1.5,
        spread=0.02,
        spread_pattern="disc",
        damping=0.0,
        start_scale=0.035,
        end_scale=0.006,
        streak=0.02,
        explosiveness=0.0,
        energy=1.0,
    ),
    "lantern_cone": EffectSpec(
        "lantern_cone",
        "hunter",
        amount=96,
        lifetime=0.9,
        speed=14.0,
        speed_variance=3.0,
        spread=0.3,
        damping=1.0,
        start_scale=0.5,
        end_scale=0.1,
        explosiveness=0.3,
        energy=2.0,
    ),
}


def effect_spec(effect: str) -> EffectSpec:
    """The spec for *effect*, raising on an unknown id."""
    try:
        return EFFECTS[effect]
    except KeyError:
        raise ValueError(f"Unknown effect {effect!r}; expected one of {', '.join(EFFECTS)}") from None


def effect_colours(
    effect: str, faction: str | None = None
) -> tuple[tuple[float, float, float, float], tuple[float, float, float, float]]:
    """The ``(start, end)`` grain colours for *effect* under *faction*.

    The start colour is the palette accent driven past 1.0 by the effect's
    energy so bloom catches it; the end colour is the same hue at zero alpha,
    so a burst fades out rather than turning grey.
    """
    spec = effect_spec(effect)
    accent = palette(faction or spec.faction).accent
    start = tuple(min(channel * spec.energy, 4.0) for channel in accent)
    return (*start, 1.0), (*start, 0.0)


class Vfx(Node3D):
    """One pooled one-shot burst: a particle emitter that returns itself.

    Callers do not construct these. :meth:`spawn` is the whole interface; a Vfx
    is idle and invisible until the pool hands it out, and retires itself once
    its grains have lived out their lifetime.
    """

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

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.particles: GPUParticles3D | None = None
        self._age = 0.0
        self._retire_at = 0.0
        self._live = False

    @staticmethod
    def spawn(tree, effect: str, position: Vec3, **params) -> None:
        """Play a pooled one-shot *effect* at *position*.

        Keyword parameters: ``faction`` overrides the effect's default palette
        (an elite's magenta explosion versus a player-ship debris burst),
        ``direction`` aims a directional effect such as ``"muzzle"``, ``scale``
        sizes the whole burst, and ``colour`` overrides the grain colour
        outright for the rare case that is not a faction (the white telegraph
        flash is ``faction="telegraph"``, not a colour override).

        ``"engine_ribbon"`` and ``"lantern_cone"`` are available here as single
        puffs; their persistent forms are :class:`EngineRibbon` and
        :class:`LanternCone`, which a caller parents and keeps.
        """
        VfxPool.for_tree(tree).emit(effect, position, **params)

    @property
    def live(self) -> bool:
        """Whether this burst is currently playing."""
        return self._live

    def on_ready(self):
        self.particles = self.add_child(GPUParticles3D(name="Particles", emitting=False, one_shot=True))

    def play(
        self,
        effect: str,
        position: Vec3,
        *,
        faction: str | None = None,
        direction: Vec3 | None = None,
        scale: float = 1.0,
        colour: tuple[float, float, float, float] | None = None,
    ) -> None:
        """Configure and start this burst. Called by :class:`VfxPool` only."""
        spec = effect_spec(effect)
        emitter = self.particles
        if emitter is None:
            raise RuntimeError("Vfx.play before the node is ready")
        self.position = position
        start, end = effect_colours(effect, faction)
        if colour is not None:
            start = tuple(colour)
            end = (*tuple(colour)[:3], 0.0)

        emitter.amount = spec.amount
        emitter.lifetime = spec.lifetime
        emitter.speed = spec.speed * scale
        emitter.speed_variance = spec.speed_variance * scale
        emitter.spread = spec.spread
        emitter.spread_pattern = spec.spread_pattern
        emitter.damping = spec.damping
        emitter.start_scale = spec.start_scale * scale
        emitter.end_scale = spec.end_scale * scale
        emitter.explosiveness = spec.explosiveness
        emitter.streak = spec.streak
        emitter.emission_shape = "sphere" if spec.emission_radius > 0.0 else "point"
        emitter.emission_radius = spec.emission_radius * scale
        # Space, not a battlefield: nothing here falls.
        emitter.gravity = spec.gravity
        emitter.direction = tuple(direction) if direction is not None else (1.0, 0.0, 0.0)
        emitter.start_colour = start
        emitter.end_colour = end
        emitter.one_shot = True
        emitter.restart()

        self._age = 0.0
        self._retire_at = spec.lifetime + VFX_RETIRE_MARGIN_S
        self._live = True
        self.visible = True

    def retire(self) -> None:
        """Stop and hide this burst; idempotent."""
        if self.particles is not None:
            self.particles.emitting = False
        self._live = False
        self.visible = False

    def on_update(self, dt: float):
        if not self._live:
            return
        self._age += dt
        if self._age >= self._retire_at:
            self.retire()
            pool = self.parent
            if isinstance(pool, VfxPool):
                pool.release(self)


class VfxPool(Node3D):
    """A fixed pool of :class:`Vfx` bursts, parented under the run scene.

    One per scene, created on demand by :meth:`Vfx.spawn`. It lives in the
    scene rather than as a tree singleton so a scene change takes its bursts
    with it instead of leaving them hanging in the next sector.
    """

    def __init__(self, size: int = VFX_POOL_SIZE, **kwargs):
        super().__init__(**kwargs)
        if size < 1:
            raise ValueError(f"Vfx pool size must be at least 1, got {size}")
        self.size = size
        self._free: list[Vfx] = []
        self._busy: list[Vfx] = []

    @classmethod
    def for_tree(cls, tree) -> VfxPool:
        """The scene's pool, creating it under the root the first time."""
        root = getattr(tree, "root", None)
        if root is None:
            raise RuntimeError("Vfx needs a loaded scene: the tree has no root")
        pool = root.find(cls)
        if pool is None:
            pool = root.add_child(cls(name="VfxPool"))
        return pool

    def on_ready(self):
        for index in range(self.size):
            self._free.append(self.add_child(Vfx(name=f"Vfx{index}")))

    @property
    def busy_count(self) -> int:
        """How many bursts are playing right now."""
        return len(self._busy)

    def acquire(self) -> Vfx:
        """A free burst, recycling the oldest busy one when the pool is dry."""
        if self._free:
            return self._free.pop()
        oldest = self._busy.pop(0)
        oldest.retire()
        return oldest

    def release(self, node: Vfx) -> None:
        """Return a burst to the pool. Safe to call more than once."""
        if node in self._busy:
            self._busy.remove(node)
        if node not in self._free:
            self._free.append(node)

    def emit(self, effect: str, position: Vec3, **params) -> Vfx:
        """Play *effect* at *position* and return the burst that plays it."""
        node = self.acquire()
        node.play(effect, position, **params)
        self._busy.append(node)
        return node


class EngineRibbon(Node3D):
    """The ship's thrust plume: a stretched flare with a mote stream inside it.

    Parent one per engine nacelle, call :meth:`set_throttle` from the ship's
    movement code and :meth:`set_direction` with the world-space direction the
    exhaust should stream in. The ribbon also consumes ``NOTORIETY_CHANGED``
    and brightens with it, so a notorious player is literally easier to see.

    The plume is geometry first and particles second, and that ordering is the
    whole readability of the thing. A drive under power is one continuous jet:
    a tapered flare anchored on the nozzle, stretching further and burning
    brighter the harder the ship is pushed. Grains alone cannot say that. They
    detach from the ship the instant they are born, and a trail of separate
    warm puffs behind a hull is the visual grammar of something exploding, not
    of something accelerating. The mote stream survives as texture on the jet:
    tight, fast and short-lived, so it streaks rather than floats.
    """

    def __init__(self, faction: str = "player", **kwargs):
        super().__init__(**kwargs)
        self.faction = faction
        self.particles: GPUParticles3D | None = None
        #: The plume geometry's mount; :meth:`set_direction` aims this node.
        self.plume: Node3D | None = None
        self._flare: MeshInstance3D | None = None
        self._core: MeshInstance3D | None = None
        self._throttle = 0.0
        self._burn = 0.0
        self._brightness = TRAIL_BRIGHTNESS_QUIET

    @property
    def throttle(self) -> float:
        """Current throttle fraction, 0 to 1."""
        return self._throttle

    @property
    def burn(self) -> float:
        """How far into the afterburner this plume is, 0 (cold) to 1 (lit)."""
        return self._burn

    @property
    def brightness(self) -> float:
        """Notoriety-driven emissive multiplier on the ribbon."""
        return self._brightness

    @property
    def plume_length(self) -> float:
        """How far the flare currently reaches behind the nozzle, world units.

        Zero with the drive cold: an unlit plume reaches nowhere, whatever
        scale the hidden geometry was last left at.
        """
        if self._flare is None or self._throttle <= 0.0:
            return 0.0
        return float(self._flare.scale.z)

    def on_ready(self):
        spec = effect_spec("engine_ribbon")
        self.plume = self.add_child(build_engine_plume(self.faction))
        self._flare = self.plume.node_at(PLUME_FLARE)
        self._core = self.plume.node_at(PLUME_CORE)
        self.particles = self.add_child(
            GPUParticles3D(
                name="Ribbon",
                amount=spec.amount,
                lifetime=spec.lifetime,
                speed=spec.speed,
                speed_variance=spec.speed_variance,
                spread=spec.spread,
                spread_pattern=spec.spread_pattern,
                damping=spec.damping,
                start_scale=spec.start_scale,
                end_scale=spec.end_scale,
                streak=spec.streak,
                explosiveness=spec.explosiveness,
                gravity=(0.0, 0.0, 0.0),
                # A GPU emitter launches its grains along a world-space vector,
                # not along the node's own axes, so the owner aims the ribbon
                # every frame through set_direction. This is only the value it
                # streams in until the first aim arrives.
                direction=(-1.0, 0.0, 0.0),
                emitting=False,
            )
        )
        self._connect_notoriety()
        self._refresh()

    def _connect_notoriety(self) -> None:
        notoriety = self.tree.singletons.get(Services.NOTORIETY) if self.tree is not None else None
        signal = getattr(notoriety, SignalNames.NOTORIETY_CHANGED, None) if notoriety is not None else None
        if signal is not None:
            signal.connect(self._on_notoriety_changed)
            self._on_notoriety_changed(getattr(notoriety, "value", 0), "initial")

    def _on_notoriety_changed(self, value: int, reason: str = "") -> None:
        fraction = max(0.0, min(float(value) / float(balance.NOTORIETY_MAX), 1.0))
        self._brightness = TRAIL_BRIGHTNESS_QUIET + (TRAIL_BRIGHTNESS_NOTORIOUS - TRAIL_BRIGHTNESS_QUIET) * fraction
        self._refresh()

    def set_throttle(self, fraction: float) -> None:
        """Set the ribbon's intensity from the throttle, 0 (idle) to 1 (full).

        Callers push per frame, so the unchanged case is the common one and it
        must not cost a rebuild: :meth:`_refresh` restates every emitter
        parameter on the ribbon and its plumes.
        """
        value = max(0.0, min(float(fraction), 1.0))
        if value == self._throttle:
            return
        self._throttle = value
        self._refresh()

    def set_burn(self, fraction: float) -> None:
        """Say how far into the afterburner the drive is, 0 to 1.

        Separate from the throttle because it answers a separate question. The
        throttle says how hard the pilot is pushing; the burn says which of the
        two drives is doing the pushing, and the pilot is spending a capacitor
        on the answer. See :data:`PLUME_BURN_LENGTH_MULT`.

        Gated on a change for the same reason as :meth:`set_throttle`. The gate
        lives here rather than in each caller because the hunter drives the
        lantern cone through this setter on every frame of a burn, and anything
        written next gets the same protection without knowing to ask for it.
        """
        value = max(0.0, min(float(fraction), 1.0))
        if value == self._burn:
            return
        self._burn = value
        self._refresh()

    def set_direction(self, direction: Vec3) -> None:
        """Stream the exhaust along *direction*, a world-space vector.

        A zero-length vector leaves the current aim alone, so a ship coasting
        with no thrust keeps the last plume rather than firing along +X.
        """
        dx, dy, dz = float(direction[0]), float(direction[1]), float(direction[2])
        length = math.sqrt(dx * dx + dy * dy + dz * dz)
        if length < 1e-6:
            return
        unit = (dx / length, dy / length, dz / length)
        if self.particles is not None:
            self.particles.direction = unit
        if self.plume is not None:
            # The plume tapers down its own local -Z, which is the axis
            # face_along aims, so aiming the mount is aiming the jet.
            self.plume.face_along(unit)

    def _refresh(self) -> None:
        self._refresh_plume()
        emitter = self.particles
        if emitter is None:
            return
        spec = effect_spec("engine_ribbon")
        accent = palette(self.faction).accent
        energy = spec.energy * self._brightness * (0.35 + 0.65 * self._throttle)
        start = tuple(min(channel * energy, 4.0) for channel in accent)
        emitter.start_colour = (*start, 1.0)
        emitter.end_colour = (*start, 0.0)
        emitter.speed = spec.speed * (0.55 + 0.45 * self._throttle)
        emitter.start_scale = spec.start_scale * (0.6 + 0.4 * self._throttle)
        emitter.emitting = self._throttle > 0.0

    def _refresh_plume(self) -> None:
        """Stretch, fatten and light the flare for the throttle and the burn."""
        if self.plume is None or self._flare is None or self._core is None:
            return
        lit = self._throttle > 0.0
        self.plume.visible = lit
        if not lit:
            return
        burn = self._burn
        stretch = 1.0 + (PLUME_BURN_LENGTH_MULT - 1.0) * burn
        fatten = 1.0 + (PLUME_BURN_RADIUS_MULT - 1.0) * burn
        radius = PLUME_RADIUS_UNITS * (PLUME_IDLE_FRACTION + (1.0 - PLUME_IDLE_FRACTION) * self._throttle) * fatten
        length = (PLUME_LENGTH_MIN_UNITS + (PLUME_LENGTH_MAX_UNITS - PLUME_LENGTH_MIN_UNITS) * self._throttle) * stretch
        self._flare.scale = Vec3(radius, radius, length)
        self._core.scale = Vec3(radius, radius, length)

        accent = palette(self.faction).accent
        glow = 1.0 + (PLUME_BURN_GLOW_MULT - 1.0) * burn
        strength = palette(self.faction).accent_strength * self._brightness * glow
        flare = self._flare.material
        flare.colour = (*accent, PLUME_FLARE_ALPHA * (0.5 + 0.5 * self._throttle))
        flare.emissive_colour = (*accent, strength * (0.45 + 0.55 * self._throttle))
        core = self._core.material
        core_hue = tuple(
            cool + (hot - cool) * burn for cool, hot in zip(PLUME_CORE_COLOUR, PLUME_BURN_CORE_COLOUR, strict=True)
        )
        core.colour = (1.0, 1.0, 1.0, PLUME_CORE_ALPHA * (0.4 + 0.6 * self._throttle))
        core.emissive_colour = (*core_hue, strength * PLUME_CORE_ENERGY * (0.35 + 0.65 * self._throttle))


class HealthPip(Node3D):
    """A thin damage read-out that rides above one big hull.

    Small enemies do not get one: a mite has five hull points and a pip on it
    would be a UI element per splinter. What a pip is for is the hull the player
    has to commit to, where the honest question is "am I nearly through this, or
    am I wasting a magazine". It appears on the first hit rather than at spawn,
    so an untouched field carries no chrome at all, and it fades out again the
    moment it has nothing left to say: back to full, or dead.

    The bar lies flat on the flight plane under the near-top-down camera, which
    is the one orientation that stays the same width whatever the hull is doing.
    """

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

    def __init__(self, *, width: float = PIP_WIDTH_UNITS, **kwargs):
        kwargs.setdefault("name", "HealthPip")
        super().__init__(**kwargs)
        self.width = float(width)
        self._fraction = 1.0
        self._opacity = 0.0
        # A pip with nothing to say is already on its way out: mounted and never
        # told a fraction, it stays invisible rather than fading itself in.
        self._fading = True
        self._track: MeshInstance3D | None = None
        self._fill: MeshInstance3D | None = None

    @property
    def fraction(self) -> float:
        """Hull fraction the fill currently shows, 0 to 1."""
        return self._fraction

    @property
    def opacity(self) -> float:
        """How far the pip has faded in, 0 (gone) to 1 (fully drawn)."""
        return self._opacity

    @property
    def fading(self) -> bool:
        """Whether the pip is on its way out."""
        return self._fading

    def on_ready(self):
        bar = Mesh.cube(size=1.0)
        self._track = self.add_child(
            MeshInstance3D(
                name="Track",
                mesh=bar,
                material=Material(colour=(*PIP_TRACK_COLOUR, 0.0), blend="alpha", unlit=True),
                scale=Vec3(self.width, PIP_THICKNESS_UNITS, PIP_DEPTH_UNITS),
            )
        )
        self._fill = self.add_child(
            MeshInstance3D(
                name="Fill",
                mesh=bar,
                material=Material(
                    colour=(*PIP_FILL_COLOUR, 0.0),
                    blend="alpha",
                    unlit=True,
                    emissive_colour=PIP_FILL_COLOUR,
                    emissive_strength=PIP_FILL_ENERGY,
                ),
                # Nudged toward the camera so the fill never z-fights its track.
                position=Vec3(0.0, PIP_THICKNESS_UNITS, 0.0),
                scale=Vec3(self.width, PIP_THICKNESS_UNITS, PIP_DEPTH_UNITS * PIP_FILL_INSET),
            )
        )
        self._apply()

    def set_fraction(self, fraction: float) -> None:
        """Show *fraction* of the hull, fading in on the way and out at the ends."""
        self._fraction = min(1.0, max(0.0, float(fraction)))
        self._fading = self._fraction >= 1.0 or self._fraction <= 0.0
        if not self._fading:
            self.visible = True
        self._apply()

    def dismiss(self) -> None:
        """Fade the pip out whatever it is showing, for a hull that has died."""
        self._fading = True

    def on_update(self, dt: float):
        target = 0.0 if self._fading else 1.0
        if self._opacity == target:
            return
        rate = dt / max(PIP_FADE_S, 1e-6)
        if target > self._opacity:
            self._opacity = min(target, self._opacity + rate)
        else:
            self._opacity = max(target, self._opacity - rate)
        if self._opacity <= 0.0:
            self.visible = False
        self._apply()

    def _apply(self) -> None:
        if self._track is None or self._fill is None:
            return
        self._track.material.colour = (*PIP_TRACK_COLOUR, PIP_TRACK_ALPHA * self._opacity)
        self._fill.material.colour = (*PIP_FILL_COLOUR, self._opacity)
        filled = max(self._fraction, 0.0) * self.width
        self._fill.scale = Vec3(max(filled, 1e-4), PIP_THICKNESS_UNITS, PIP_DEPTH_UNITS * PIP_FILL_INSET)
        # The fill drains from the right-hand end, which is what makes a bar
        # read as a quantity rather than as a shrinking object.
        self._fill.position = Vec3(-(self.width - filled) * 0.5, PIP_THICKNESS_UNITS, 0.0)


class LanternCone(Node3D):
    """The Shrike's lantern: a drawn beam, a shadow-casting spot and its dust.

    Parent it to the hunter's head and aim it with :meth:`aim_at`. Three
    phases, and the pilot has to be able to tell them apart across the width of
    the arena, because which one is running is the whole of whether standing
    still costs 35 hull:

    * **Sweep** (:meth:`set_active`) is the beam hunting for the ship. Bright,
      dust streaming, and it moves.
    * **Pre-burn** (:meth:`set_preburn`) is the one second of warning the design
      promises. The beam locks where it is, stops streaming dust and drops to a
      dim shell: several times fainter than the sweep, but never gone, because
      "the light went out" and "the light is about to burn you" cannot look the
      same.
    * **Burn** (:meth:`set_burn`) is the frame that costs hull, and it flares
      well past the sweep so the pilot can name what hit them.

    The shell is geometry rather than light alone. A spot cast across an empty
    arena illuminates nothing, so the beam is drawn as an emissive translucent
    cone and the ``SpotLight3D`` is what that beam throws onto the hulls it
    crosses.
    """

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.light: SpotLight3D | None = None
        self.particles: GPUParticles3D | None = None
        #: The drawn beam. Its apex sits on this node, opening down local -Z.
        self.beam: MeshInstance3D | None = None
        self._active = False
        self._preburn = False
        self._burn = False
        #: Seconds since the burn frame opened, which is what the flare decays
        #: against. Reset every time the burn phase is entered.
        self._burn_age = 0.0

    @property
    def active(self) -> bool:
        """Whether the lantern is lit at all."""
        return self._active

    @property
    def preburn(self) -> bool:
        """Whether the lantern is in its locked pre-burn dim."""
        return self._preburn

    @property
    def burn(self) -> bool:
        """Whether the lantern is on the burning frame."""
        return self._burn

    @property
    def beam_alpha(self) -> float:
        """Opacity of the drawn shell, or zero while the lantern is doused.

        This is the number that makes the phase legible from across the arena,
        so it is readable state rather than an implementation detail.
        """
        if self.beam is None or not self._active:
            return 0.0
        return float(self.beam.material.colour[3])

    def on_ready(self):
        spec = effect_spec("lantern_cone")
        accent = palette("hunter").accent
        self.beam = self.add_child(self._build_beam(accent))
        self.light = self.add_child(
            SpotLight3D(
                name="Lantern",
                range=LANTERN_RANGE,
                inner_cone=LANTERN_INNER_CONE_DEGREES,
                outer_cone=LANTERN_OUTER_CONE_DEGREES,
                shadows=True,
            )
        )
        self.light.colour = accent
        self.particles = self.add_child(
            GPUParticles3D(
                name="LanternDust",
                amount=spec.amount,
                lifetime=spec.lifetime,
                speed=spec.speed,
                speed_variance=spec.speed_variance,
                spread=spec.spread,
                damping=spec.damping,
                start_scale=spec.start_scale,
                end_scale=spec.end_scale,
                explosiveness=spec.explosiveness,
                gravity=(0.0, 0.0, 0.0),
                direction=(0.0, 0.0, -1.0),
                start_colour=(*tuple(min(c * spec.energy, 4.0) for c in accent), 1.0),
                end_colour=(*tuple(min(c * spec.energy, 4.0) for c in accent), 0.0),
                emitting=False,
            )
        )
        self._refresh()

    @staticmethod
    def _build_beam(accent) -> MeshInstance3D:
        """The drawn shell: a cone with its apex on the head, opening down -Z.

        ``Mesh.cone`` points up +Y with its base centred on the origin, so a
        quarter turn about X lays it along the axis a ``SpotLight3D`` beams
        down, and the half-length shift puts its apex on the lantern rather
        than half a beam behind it. The radius is the outer cone angle carried
        the full range, so the drawn shell and the burn test agree by
        construction instead of by a number kept in step by hand.
        """
        radius = LANTERN_RANGE * math.tan(math.radians(LANTERN_OUTER_CONE_DEGREES))
        return MeshInstance3D(
            name="LanternBeam",
            mesh=Mesh.cone(radius=radius, height=LANTERN_RANGE, segments=LANTERN_CONE_SEGMENTS),
            material=Material(
                colour=(*accent, LANTERN_CONE_ALPHA_SWEEP),
                blend="alpha",
                metallic=0.0,
                roughness=1.0,
                double_sided=True,
                emissive_colour=accent,
                emissive_strength=palette("hunter").accent_strength,
            ),
            rotation=Quat.from_axis_angle(Vec3(1.0, 0.0, 0.0), math.pi * 0.5),
            position=Vec3(0.0, 0.0, -LANTERN_RANGE * 0.5),
        )

    def set_active(self, active: bool) -> None:
        """Light or douse the lantern. A doused lantern leaves both sub-phases."""
        self._active = bool(active)
        if not self._active:
            self._preburn = False
            self._burn = False
        self._refresh()

    def set_preburn(self, active: bool) -> None:
        """Enter or leave the ``balance.SHRIKE_LANTERN_PREBURN_WARNING_S`` dim."""
        self._preburn = bool(active)
        if self._preburn:
            self._burn = False
        self._refresh()

    def set_burn(self, active: bool) -> None:
        """Enter or leave the burning frame, the flare that costs hull."""
        was_burning = self._burn
        self._burn = bool(active)
        if self._burn:
            self._preburn = False
            if not was_burning:
                self._burn_age = 0.0
        self._refresh()

    def on_update(self, dt: float):
        """Age the flare so it falls back to the sweep look after its flash."""
        if not self._burn:
            return
        if self._burn_age >= LANTERN_BURN_FLASH_S + LANTERN_BURN_FALLOFF_S:
            return
        self._burn_age += float(dt)
        self._refresh()

    @property
    def burn_flare(self) -> float:
        """How much of the flare is still up, 1 on the burn frame and 0 after.

        Readable state rather than bookkeeping: the flare's fall is the reason
        the burn's own readouts are legible, so a test can assert on it.
        """
        if not self._burn:
            return 0.0
        over = (self._burn_age - LANTERN_BURN_FLASH_S) / max(LANTERN_BURN_FALLOFF_S, 1e-6)
        return 1.0 - min(1.0, max(0.0, over))

    def aim_at(self, direction: Vec3) -> None:
        """Aim the cone down *direction*; a zero vector leaves the aim alone.

        A ``SpotLight3D`` beams along its node's forward axis, so aiming the
        cone is aiming this node, and the drawn shell rides the same rotation.
        """
        self.face_along(direction)

    def _phase_look(self) -> tuple[float, float, float]:
        """``(light multiplier, shell alpha, shell glow)`` for the live phase."""
        if self._burn:
            flare = self.burn_flare
            return (
                1.0 + (LANTERN_BURN_FLARE - 1.0) * flare,
                LANTERN_CONE_ALPHA_SWEEP + (LANTERN_CONE_ALPHA_BURN - LANTERN_CONE_ALPHA_SWEEP) * flare,
                LANTERN_CONE_GLOW_SWEEP + (LANTERN_CONE_GLOW_BURN - LANTERN_CONE_GLOW_SWEEP) * flare,
            )
        if self._preburn:
            return LANTERN_PREBURN_DIM, LANTERN_CONE_ALPHA_PREBURN, LANTERN_CONE_GLOW_PREBURN
        return 1.0, LANTERN_CONE_ALPHA_SWEEP, LANTERN_CONE_GLOW_SWEEP

    def _refresh(self) -> None:
        if self.light is None:
            return
        multiplier, alpha, glow = self._phase_look()
        self.light.intensity = LANTERN_INTENSITY * multiplier if self._active else 0.0
        if self.beam is not None:
            hunter = palette("hunter")
            self.beam.visible = self._active
            self.beam.material.colour = (*hunter.accent, alpha)
            self.beam.material.emissive_strength = min(hunter.accent_strength * glow, LANTERN_CONE_EMISSIVE_MAX)
        if self.particles is not None:
            # Dust streams while the beam is hunting and while it burns; the
            # pre-burn second is the one that holds still, and stillness is the
            # tell the dodge is read off.
            self.particles.emitting = self._active and not self._preburn


#: The docking ring: the bay drawn on the ground so it is a place and not a
#: radius. A blind pilot crossed a depot's dock radius three times in under two
#: seconds each without noticing, because nothing in the world said where the
#: bay was or that the hull was inside it. The ring is that line, and it changes
#: state when the ship crosses it, which is the other half of the same answer.
DOCK_RING_SEGMENTS = 40
#: Fraction of each segment's slot the segment actually fills, so the ring reads
#: as a dashed approach marker rather than as a solid disc edge.
DOCK_RING_SEGMENT_FILL = 0.55
DOCK_RING_THICKNESS_UNITS = 0.06
DOCK_RING_WIDTH_UNITS = 0.55
#: How far above the flight plane the ring lies. Gameplay stays on the plane;
#: this is visual flourish and is allowed to leave it by a hair, which is what
#: keeps it from z-fighting anything else drawn flat.
DOCK_RING_LIFT_UNITS = 0.05
#: The ring outside the bay and inside it. Idle is a cool marker; armed is the
#: HUD's own affordance green, so the ring, the beacon and the verb line are one
#: colour language.
DOCK_RING_IDLE_COLOUR = (0.34, 0.62, 0.72)
DOCK_RING_ARMED_COLOUR = (0.55, 1.00, 0.80)
DOCK_RING_IDLE_ALPHA = 0.34
DOCK_RING_ARMED_ALPHA = 0.85
DOCK_RING_IDLE_ENERGY = 0.7
DOCK_RING_ARMED_ENERGY = 2.6
#: Cycles per second the armed ring breathes at, and how deep the breath goes.
DOCK_RING_PULSE_HZ = 1.1
DOCK_RING_PULSE_DEPTH = 0.28
#: Seconds the ring takes to cross between its two states, so entering the bay
#: is a transition the eye catches rather than a swap between two frames.
DOCK_RING_ARM_S = 0.22


class DockRing(Node3D):
    """The depot's bay, drawn flat on the plane, lit when the hull is inside it.

    One :class:`MultiMesh` of dashed segments and no per-frame transform work:
    arming changes the material and nothing else. Mount it at the dock's anchor
    with the bay's own radius and drive it with :meth:`set_armed` from whoever
    knows where the ship is; :attr:`armed` and :attr:`glow` are readable state,
    because "does the ring visibly change" is the assertion this exists for.
    """

    def __init__(self, *, radius: float = 14.0, **kwargs):
        kwargs.setdefault("name", "DockRing")
        super().__init__(**kwargs)
        self.radius = float(radius)
        self._armed = False
        #: How far into the armed look the ring has travelled, 0 to 1.
        self._arm = 0.0
        self._elapsed = 0.0
        self._material: Material | None = None

    @property
    def armed(self) -> bool:
        """Whether the ring has been told the hull is inside the bay."""
        return self._armed

    @property
    def glow(self) -> float:
        """The ring's live emissive strength: the number the change is visible in."""
        material = self._material
        return float(material.emissive_strength) if material is not None else 0.0

    def on_ready(self):
        segment = Mesh.cube(size=1.0)
        mesh = MultiMesh(mesh=segment, instance_count=DOCK_RING_SEGMENTS)
        mesh.set_all_transforms(self._segment_transforms())
        self._material = Material(
            colour=(*DOCK_RING_IDLE_COLOUR, DOCK_RING_IDLE_ALPHA),
            blend="alpha",
            metallic=0.0,
            roughness=1.0,
            emissive_colour=DOCK_RING_IDLE_COLOUR,
            emissive_strength=DOCK_RING_IDLE_ENERGY,
        )
        self.add_child(MultiMeshInstance3D(name="Segments", multi_mesh=mesh, material=self._material))
        self._paint()

    def _segment_transforms(self) -> np.ndarray:
        """One tangential dash per slot around the circle, laid flat on the plane."""
        angles = np.linspace(0.0, math.tau, DOCK_RING_SEGMENTS, endpoint=False)
        length = math.tau * self.radius / DOCK_RING_SEGMENTS * DOCK_RING_SEGMENT_FILL
        cos, sin = np.cos(angles), np.sin(angles)
        transforms = np.zeros((DOCK_RING_SEGMENTS, 4, 4), dtype=np.float32)
        transforms[:, 3, 3] = 1.0
        # Local X runs along the tangent, local Z out along the radius.
        transforms[:, 0, 0] = -sin * length
        transforms[:, 2, 0] = cos * length
        transforms[:, 1, 1] = DOCK_RING_THICKNESS_UNITS
        transforms[:, 0, 2] = cos * DOCK_RING_WIDTH_UNITS
        transforms[:, 2, 2] = sin * DOCK_RING_WIDTH_UNITS
        transforms[:, 0, 3] = cos * self.radius
        transforms[:, 1, 3] = DOCK_RING_LIFT_UNITS
        transforms[:, 2, 3] = sin * self.radius
        return transforms

    def set_armed(self, armed: bool) -> None:
        """Say whether the hull is inside the bay. Idempotent; cheap to push per frame."""
        self._armed = bool(armed)

    def on_update(self, dt: float):
        self._elapsed += float(dt)
        rate = float(dt) / max(DOCK_RING_ARM_S, 1e-6)
        target = 1.0 if self._armed else 0.0
        if self._arm != target:
            self._arm = min(target, self._arm + rate) if target > self._arm else max(target, self._arm - rate)
        elif not self._armed:
            return  # nothing is moving; the idle ring costs no writes at all
        self._paint()

    def _paint(self) -> None:
        """Blend the two looks and breathe the armed one."""
        material = self._material
        if material is None:
            return
        arm = min(1.0, max(0.0, self._arm))
        pulse = 1.0 - DOCK_RING_PULSE_DEPTH * (0.5 - 0.5 * math.cos(self._elapsed * DOCK_RING_PULSE_HZ * math.tau))
        colour = tuple(
            idle + (lit - idle) * arm for idle, lit in zip(DOCK_RING_IDLE_COLOUR, DOCK_RING_ARMED_COLOUR, strict=True)
        )
        alpha = DOCK_RING_IDLE_ALPHA + (DOCK_RING_ARMED_ALPHA - DOCK_RING_IDLE_ALPHA) * arm
        energy = DOCK_RING_IDLE_ENERGY + (DOCK_RING_ARMED_ENERGY - DOCK_RING_IDLE_ENERGY) * arm
        material.colour = (*colour, alpha * (pulse if arm > 0.0 else 1.0))
        material.emissive_colour = colour
        material.emissive_strength = energy * (pulse if arm > 0.0 else 1.0)


# ============================================================================
# The dust field
# ============================================================================


@dataclass(frozen=True)
class DustBand:
    """One parallax layer of the dust field.

    ``parallax`` is how much of the camera's travel the band gives back as
    apparent motion: 1.0 pins the motes in world space, so they stream past at
    exactly the ship's speed, and a value above 1.0 makes the band race the
    other way, which is what a layer between the camera and the plane does.
    """

    id: str
    count: int
    #: Side of the square tile the band is wrapped into, world units. It must
    #: comfortably exceed the visible extent or motes recycle inside the frame.
    span: float
    parallax: float
    #: Inclusive height range above the flight plane the band occupies.
    height: tuple[float, float]
    scale: tuple[float, float]
    colour: tuple[float, float, float]
    #: Emissive multiplier; the near band runs hot enough for bloom to catch.
    energy: float


#: Two bands: grit lying on the flight plane, and a looser haze just above it.
#: The haze is nearer the camera, so it is both larger and faster, and that
#: difference is the whole depth cue.
DUST_BANDS: tuple[DustBand, ...] = (
    DustBand(
        "grit",
        count=320,
        span=112.0,
        parallax=1.0,
        height=(-0.7, 0.7),
        scale=(0.075, 0.15),
        colour=DUST_NEAR_COLOUR,
        energy=1.1,
    ),
    DustBand(
        "haze",
        count=200,
        span=112.0,
        parallax=1.45,
        height=(2.6, 5.4),
        scale=(0.1, 0.2),
        colour=DUST_FAR_COLOUR,
        energy=0.55,
    ),
)


class DustField(Node3D):
    """Tiled parallax motes that make the ship's own speed visible.

    An empty sector gives the eye nothing to measure motion against: at cruise
    the hull sits dead centre of the frame with the stars fixed behind it, and
    the honest reading of that picture is a ship that is not moving. This field
    is the fix. Each band of :data:`DUST_BANDS` is a square tile of motes that
    is wrapped around the camera focus every frame, so the player always flies
    through the same density of grain no matter how far the sector runs, and
    each band gives back a different fraction of the camera's travel, so the
    screen shows depth as well as speed.

    It costs one draw call per band and one vectorised wrap per frame; nothing
    is spawned, retired or simulated. Mount one per sector and forget it.
    """

    def __init__(self, seed: int = 0, bands: tuple[DustBand, ...] = DUST_BANDS, act: int = 1, **kwargs):
        super().__init__(**kwargs)
        self.seed = int(seed)
        self.bands = tuple(bands)
        self.act = int(act)
        self._meshes: list[MultiMesh] = []
        self._transforms: list[np.ndarray] = []
        self._origins: list[np.ndarray] = []
        self._sizes: list[np.ndarray] = []
        self._materials: list[Material] = []
        self._rig: CameraRig | None = None
        self._last_focus: Vec2 | None = None
        self._fade_density = 1.0
        self._fade_saturation = 1.0
        self._fade_glow = 1.0

    @property
    def mote_count(self) -> int:
        """How many motes the whole field carries."""
        return sum(band.count for band in self.bands)

    def mote_colour(self, band: DustBand) -> tuple[float, float, float]:
        """*band*'s colour carried :data:`DUST_ACT_TINT` of the way to the act's hue."""
        tint = act_grade(self.act).nebula_bright
        peak = max(max(tint), 1e-6)
        return tuple(
            base * (1.0 - DUST_ACT_TINT) + (channel / peak) * DUST_ACT_TINT
            for base, channel in zip(band.colour, tint, strict=True)
        )

    def set_act(self, act: int) -> None:
        """Re-tint the whole field for *act*; the geometry and fade are untouched."""
        self.act = int(act)
        self._paint()

    def set_fade(self, *, density: float = 1.0, saturation: float = 1.0, glow: float | None = None) -> None:
        """Thin the field without it forgetting how it was authored.

        *density* scales every band's alpha, *saturation* carries its colour
        toward grey, and *glow* scales the emissive push, defaulting to
        *density*. All three are fractions of the field as built and all three
        survive an act change: the sector drives this as the ship leaves the
        content behind, and a jump-deep re-tint out in the void must not snap
        the grain back to full density.
        """
        self._fade_density = min(1.0, max(0.0, float(density)))
        self._fade_saturation = min(1.0, max(0.0, float(saturation)))
        self._fade_glow = self._fade_density if glow is None else min(1.0, max(0.0, float(glow)))
        self._paint()

    def _paint(self) -> None:
        """Write the act tint and the fade onto every band's material."""
        if not self._materials:
            return
        for band, material in zip(self.bands, self._materials, strict=True):
            colour = self.mote_colour(band)
            grey = sum(colour) / 3.0
            rgb = tuple(grey + (channel - grey) * self._fade_saturation for channel in colour)
            material.colour = (*rgb, DUST_ALPHA * self._fade_density)
            material.emissive_colour = (*rgb, band.energy * self._fade_glow)

    def on_ready(self):
        rng = np.random.default_rng(self.seed)
        mote = Mesh.sphere(radius=0.5, rings=DUST_MOTE_RINGS, segments=DUST_MOTE_SEGMENTS)
        for band in self.bands:
            self._origins.append(rng.random((band.count, 2)) * band.span)
            self._sizes.append(rng.uniform(band.scale[0], band.scale[1], size=band.count).astype(np.float32))
            transforms = np.zeros((band.count, 4, 4), dtype=np.float32)
            transforms[:, 3, 3] = 1.0
            transforms[:, 1, 3] = rng.uniform(band.height[0], band.height[1], size=band.count)
            self._transforms.append(transforms)

            mesh = MultiMesh(mesh=mote, instance_count=band.count)
            self._meshes.append(mesh)
            colour = self.mote_colour(band)
            material = Material(
                colour=(*colour, DUST_ALPHA),
                blend="alpha",
                metallic=0.0,
                roughness=1.0,
                emissive_colour=colour,
                emissive_strength=band.energy,
            )
            self._materials.append(material)
            self.add_child(
                MultiMeshInstance3D(name=f"Dust{band.id.title()}", multi_mesh=mesh, material=material),
            )
        self.set_act(self._sector_act())
        self._wrap(self._focus_point(), force=True)

    def on_update(self, dt: float):
        act = self._sector_act()
        if act != self.act:
            self.set_act(act)
        self._wrap(self._focus_point())

    def _sector_act(self) -> int:
        """The act the run is in, so a jump deeper re-tints the grain with the sky.

        Read from the signature meter rather than passed in, because the field
        outlives the sector it was mounted in: it is the place, and the place
        changes colour when the run does.
        """
        tree = self.tree
        meter = tree.singletons.get(Services.SIGNATURE) if tree is not None else None
        act = getattr(meter, "act", None)
        return int(act) if act in ACT_GRADES else self.act

    def _focus_point(self) -> Vec2:
        """Where the field centres itself: the camera focus, else the ship."""
        tree = self.tree
        if tree is None:
            return Vec2(0.0, 0.0)
        if self._rig is None and tree.root is not None:
            self._rig = tree.root.find(CameraRig)
        if self._rig is not None:
            return self._rig.focus
        ship = tree.get_first_in_group(Groups.SHIP)
        return to_plane(ship.position) if ship is not None else Vec2(0.0, 0.0)

    def _wrap(self, focus: Vec2, *, force: bool = False) -> None:
        """Re-tile every band around *focus*, skipping a focus that has not moved."""
        fx, fz = float(focus.x), float(focus.y)
        if not force and self._last_focus is not None:
            moved = math.hypot(fx - float(self._last_focus.x), fz - float(self._last_focus.y))
            if moved < DUST_REFRESH_EPSILON:
                return
        self._last_focus = Vec2(fx, fz)
        here = self.world_position
        layers = zip(self.bands, self._origins, self._transforms, self._sizes, self._meshes, strict=True)
        for band, origins, transforms, sizes, mesh in layers:
            half = band.span * 0.5
            drift = np.array([fx, fz], dtype=np.float64) * band.parallax
            offsets = np.mod(origins - drift + half, band.span) - half
            transforms[:, 0, 3] = fx + offsets[:, 0] - float(here.x)
            transforms[:, 2, 3] = fz + offsets[:, 1] - float(here.z)
            # Distance attenuation: a mote shrinks as it travels out toward the
            # edge of its tile, which is both the depth cue and the reason a
            # mote recycling across the tile boundary is never seen popping.
            reach = np.hypot(offsets[:, 0], offsets[:, 1]) / half
            fade = 1.0 - (1.0 - DUST_FAR_SIZE_FRACTION) * np.clip(reach, 0.0, 1.0)
            scaled = (sizes * fade).astype(np.float32)
            transforms[:, 0, 0] = scaled
            transforms[:, 1, 1] = scaled
            transforms[:, 2, 2] = scaled
            mesh.set_all_transforms(transforms)

    def sizes(self, band_index: int = 0) -> np.ndarray:
        """Current drawn diameter of each mote of one band, for tests."""
        return self._transforms[band_index][:, 0, 0].copy()

    def positions(self, band_index: int = 0) -> np.ndarray:
        """Current world-space ``(N, 3)`` mote positions of one band, for tests."""
        transforms = self._transforms[band_index]
        here = self.world_position
        world = transforms[:, :3, 3].copy()
        world[:, 0] += float(here.x)
        world[:, 1] += float(here.y)
        world[:, 2] += float(here.z)
        return world