shrike/enemies/steering.py

Part of SHRIKE.

"""Flow-field steering and the shared enemy base.

Every hostile in SHRIKE moves the same way. A :class:`FlowField` turns the
flight plane into a grid of unit vectors that all point down the cheapest path
to one target, so a shoal of twenty mites costs one field rebuild rather than
twenty pathfinding queries, and a wreck field bends the whole swarm around it
instead of pinning individuals against its hull. :class:`Enemy` is the base
every archetype derives from: it owns hull points, the elite tag, the group and
collision-layer registration, and the universal telegraph.

The telegraph convention
========================

**No enemy in the game attacks without flashing white first.** The base class
owns that promise: :meth:`Enemy.begin_attack` flashes the body white for
:attr:`Enemy.telegraph_duration` seconds (``balance.ENEMY_FIRE_TELEGRAPH_S``
for everything except the Lancer's longer dash wind-up) and only then calls
:meth:`Enemy.perform_attack`. Archetypes override ``perform_attack``; they do
not schedule attacks of their own. The flash is the readability contract from
the art direction: player fire is warm gold, enemy fire is cold magenta, and
white belongs to telegraphs alone.

Every wound shows
=================

A hull that takes nine seconds of fire and gives nothing back reads as
invulnerable, whatever the number underneath it is doing, so the feel budget
cannot all belong to kills. :meth:`Enemy.take_damage` now answers every hit.
The struck body pulses white for :data:`HIT_FLASH_S` on its emissive channel
(the telegraph keeps the albedo, so the two never fight), a spark goes off
where the round came apart, and a hull big enough to be worth the question
(:data:`HP_PIP_MIN_HP` and up) grows a :class:`~shrike.vfx.HealthPip` on its
first wound that fades away again at full or at zero.

Contact has weight
==================

An enemy that touches the hull calls :meth:`Enemy.contact_damage`, never
:meth:`Enemy.deal_damage_to`. Contact resolves through the damage router's
contact path: the attacker's drive dies for ``balance.CONTACT_STALL_S`` and
both hulls take a radial impulse apart. The stall and the recoil are honoured
by :meth:`Enemy.move`, so an archetype gets the collision for free by steering
the way every archetype already steers, and nothing glides through the ship.

Staggered cadences
==================

Every archetype that attacks on a timer seeds that timer from
:meth:`Enemy.stagger_cadence`, so two Lancers that arrive on the same frame do
not wind up, dash and recover in lockstep for the rest of the fight. The offset
is drawn from a stream of its own rather than from :attr:`Enemy.rng`, because a
seeded spawn has to stay reproducible whatever the cadence does.
"""

from __future__ import annotations

import math
import random

import numpy as np

from simvx.core import Area3D, Material, Node3D, Quat, Signal, SphereShape3D, Vec2, Vec3

from .. import balance
from ..combat import separate_on_contact
from ..runtime import PLANE_Y, Groups, Layers, Services, from_plane, to_plane
from ..vfx import HealthPip, Vfx

# ============================================================================
# Steering constants
#
# These are movement-feel numbers rather than balance numbers: they describe
# how the grid is discretised and how strongly geometry repels a swarm, not how
# hard anything hits. balance.py carries no equivalents.
# ============================================================================

#: Side length of one flow-field cell, in world units.
FLOW_CELL_SIZE = 8.0
#: Default playfield the field covers when a caller does not supply bounds:
#: the 60-unit sector (``sector.SECTOR_RADIUS``) with a margin for spawns that
#: approach from off the edge.
DEFAULT_FIELD_BOUNDS = (-120.0, -120.0, 120.0, 120.0)
#: Extra traversal cost charged to a cell covered by an obstacle. High enough
#: that a swarm flows around a wreck, finite so nothing is ever unreachable.
OBSTACLE_CELL_COST = 24.0
#: Radius around an obstacle point whose cells carry the extra cost.
OBSTACLE_RADIUS = 10.0
#: How often the scene-wide field is re-integrated toward the player ship.
FLOW_REBUILD_INTERVAL_S = 0.25
#: Group holding the scene's shared :class:`FlowFieldDirector`, if one exists.
FLOW_FIELD_GROUP = "flow_field"

#: Telegraph colour. White is reserved for telegraphs across the whole game.
TELEGRAPH_COLOUR = (1.0, 1.0, 1.0, 1.0)

# ----------------------------------------------------------------------------
# Damage feedback
#
# A hit that produces no picture is a hit the player does not believe in. Three
# things say "that landed", and between them they cover every scale of hull:
# a white pulse on the body, a spark where the round came apart, and, for the
# hulls big enough that the honest question is "how much further", a pip.
# ----------------------------------------------------------------------------

#: Length of the white emissive pulse a hit puts on a struck hull, seconds.
#: Short on purpose: long enough to register at 60 fps, too short to wash the
#: hull's own colour out under sustained fire.
HIT_FLASH_S = 0.08
#: Emissive strength the pulse drives the struck materials to.
HIT_FLASH_STRENGTH = 6.0
#: The pulse's colour. White, like every other "pay attention" signal.
HIT_FLASH_EMISSIVE = (1.0, 1.0, 1.0)
#: Shortest gap between two impact sparks on one hull. A beam lands a hit every
#: frame, and sixty sparks a second is both an empty effect pool and a solid
#: block of light where a stream of them should be.
HIT_SPARK_INTERVAL_S = 0.06
#: Smallest hull pool worth a health pip: the set the design names outright
#: (bombardiers, husk turrets, wardens, magistrates) and anything an Armoured
#: elite has plated up past them. Below it a hull dies inside a burst, and a
#: read-out on it would be chrome the player never has time to read.
HP_PIP_MIN_HP = 90.0
#: How far above the flight plane the pip rides, world units.
HP_PIP_HEIGHT = 1.9
#: How far toward the top of the screen (-Z) the pip is offset from the hull.
HP_PIP_OFFSET_Z = -1.6

_LARGE_COST = np.float32(1e9)
_SQRT2 = math.sqrt(2.0)

#: Neighbour offsets as ``(row delta, column delta)``, rows being +Z and
#: columns +X, in the order the relaxation stacks them.
_NEIGHBOURS = ((-1, 0), (1, 0), (0, -1), (0, 1), (-1, -1), (-1, 1), (1, -1), (1, 1))


class FlowField:
    """A grid of unit vectors over the flight plane, all pointing at one target.

    Rebuilding integrates a cost-to-go field outward from the target cell with
    an eight-connected relaxation, charging obstacles extra to enter, then
    stores the descent direction per cell. Sampling is bilinear, so a body
    crossing a cell boundary turns smoothly rather than snapping.

    Positions and directions are plane coordinates, ``Vec2(x, z)``. Bounds are
    ``(min_x, min_z, max_x, max_z)``; a sample from outside the bounds falls
    back to a straight line toward the target, which walks a stray body back
    into the field rather than stalling it at the edge.
    """

    def __init__(self, bounds: tuple[float, float, float, float], cell: float = FLOW_CELL_SIZE):
        min_x, min_z, max_x, max_z = (float(b) for b in bounds)
        if max_x <= min_x or max_z <= min_z:
            raise ValueError(f"FlowField bounds must be (min_x, min_z, max_x, max_z) with positive extent: {bounds}")
        if cell <= 0.0:
            raise ValueError(f"FlowField cell size must be positive, got {cell}")
        self.bounds = (min_x, min_z, max_x, max_z)
        self.cell = float(cell)
        self.columns = max(1, int(math.ceil((max_x - min_x) / self.cell)))
        self.rows = max(1, int(math.ceil((max_z - min_z) / self.cell)))
        self.target = Vec2(0.0, 0.0)
        self._flow = np.zeros((self.rows, self.columns, 2), dtype=np.float32)
        self._cost_to_go = np.zeros((self.rows, self.columns), dtype=np.float32)
        self._built = False
        columns_x = min_x + (np.arange(self.columns, dtype=np.float32) + 0.5) * self.cell
        rows_z = min_z + (np.arange(self.rows, dtype=np.float32) + 0.5) * self.cell
        self._centre_x = np.tile(columns_x, (self.rows, 1))
        self._centre_z = np.repeat(rows_z[:, None], self.columns, axis=1)

    # -- Queries ------------------------------------------------------------

    @property
    def built(self) -> bool:
        """Whether :meth:`rebuild` has run at least once."""
        return self._built

    @property
    def cost_to_go(self) -> np.ndarray:
        """The integrated cost field, ``(rows, columns)``, in world units."""
        return self._cost_to_go

    def contains(self, position: Vec2) -> bool:
        """Whether a plane position lies inside the field's bounds."""
        min_x, min_z, max_x, max_z = self.bounds
        return min_x <= float(position.x) <= max_x and min_z <= float(position.y) <= max_z

    def targets(self, point: Vec2, tolerance: float | None = None) -> bool:
        """Whether the field is currently integrated toward *point*.

        Enemies use this to decide whether the shared field answers the
        question they are asking: one that chases something other than the
        field's target steers directly instead.
        """
        if not self._built:
            return False
        limit = self.cell if tolerance is None else float(tolerance)
        return math.hypot(float(point.x) - float(self.target.x), float(point.y) - float(self.target.y)) <= limit

    # -- Rebuild ------------------------------------------------------------

    def rebuild(self, target: Vec2, obstacles: list[Vec2]) -> None:
        """Re-integrate the field toward *target*, charging *obstacles* extra.

        Obstacles are plane points; every cell within :data:`OBSTACLE_RADIUS`
        of one costs :data:`OBSTACLE_CELL_COST` more to enter. The cost stays
        finite, so a body walled in by geometry still finds a way out instead
        of freezing on an unreachable cell.
        """
        self.target = Vec2(float(target.x), float(target.y))
        enter_cost = np.ones((self.rows, self.columns), dtype=np.float32)
        radius_sq = OBSTACLE_RADIUS * OBSTACLE_RADIUS
        for obstacle in obstacles:
            dx = self._centre_x - float(obstacle.x)
            dz = self._centre_z - float(obstacle.y)
            enter_cost += np.where(dx * dx + dz * dz < radius_sq, np.float32(OBSTACLE_CELL_COST), np.float32(0.0))

        row = self._row_of(float(target.y))
        column = self._column_of(float(target.x))
        costs = np.full((self.rows, self.columns), _LARGE_COST, dtype=np.float32)
        costs[row, column] = 0.0
        step = np.array([self.cell * (_SQRT2 if dr and dc else 1.0) for dr, dc in _NEIGHBOURS], dtype=np.float32)

        for _ in range(self.rows + self.columns + 2):
            candidates = self._neighbour_stack(costs) + step[:, None, None] * enter_cost[None, :, :]
            relaxed = np.minimum(costs, candidates.min(axis=0))
            if np.array_equal(relaxed, costs):
                break
            costs = relaxed

        self._cost_to_go = costs
        self._flow = self._descent_directions(costs)
        self._built = True

    def _neighbour_stack(self, costs: np.ndarray) -> np.ndarray:
        """The eight shifted copies of *costs*, padded with an unreachable cost."""
        padded = np.pad(costs, 1, mode="constant", constant_values=_LARGE_COST)
        rows, columns = costs.shape
        return np.stack(
            [padded[1 + dr : 1 + dr + rows, 1 + dc : 1 + dc + columns] for dr, dc in _NEIGHBOURS],
            axis=0,
        )

    def _descent_directions(self, costs: np.ndarray) -> np.ndarray:
        """Per-cell unit vector toward the cheapest neighbour."""
        stack = self._neighbour_stack(costs)
        best = np.argmin(stack, axis=0)
        offsets = np.array([(dc, dr) for dr, dc in _NEIGHBOURS], dtype=np.float32)
        lengths = np.hypot(offsets[:, 0], offsets[:, 1])
        unit = offsets / lengths[:, None]
        flow = unit[best]
        reachable = stack.min(axis=0) < _LARGE_COST * 0.5
        flow[~reachable] = 0.0
        flow[costs <= 0.0] = 0.0
        return flow.astype(np.float32)

    # -- Sampling -----------------------------------------------------------

    def sample(self, position: Vec2) -> Vec2:
        """The unit steering direction at a plane position."""
        result = self.sample_many(np.asarray([[float(position.x), float(position.y)]], dtype=np.float32))
        return Vec2(float(result[0, 0]), float(result[0, 1]))

    def sample_many(self, positions: np.ndarray) -> np.ndarray:
        """Sample an ``(N, 2)`` array of plane positions in one pass.

        Returns an ``(N, 2)`` array of unit directions (zero where a body is
        already on the target). This is the path the mite shoal takes: one
        vectorised gather for the whole swarm.

        The field resolves navigation at cell granularity, so it can only ever
        aim a body at the target's cell rather than at the target itself. Inside
        the last cell the sample steers straight at the target instead, which is
        what lets a shoal close the final few units onto a ship rather than
        settling into a ring around the cell centre.
        """
        points = np.asarray(positions, dtype=np.float32).reshape(-1, 2)
        direct = self._direct_to_target(points)
        if not self._built:
            return direct

        min_x, min_z, max_x, max_z = self.bounds
        inside = (points[:, 0] >= min_x) & (points[:, 0] <= max_x) & (points[:, 1] >= min_z) & (points[:, 1] <= max_z)
        offset = np.asarray([float(self.target.x), float(self.target.y)], dtype=np.float32) - points
        inside &= np.hypot(offset[:, 0], offset[:, 1]) > self.cell
        u = (points[:, 0] - min_x) / self.cell - 0.5
        v = (points[:, 1] - min_z) / self.cell - 0.5
        column0 = np.floor(u).astype(np.int32)
        row0 = np.floor(v).astype(np.int32)
        fu = (u - column0)[:, None]
        fv = (v - row0)[:, None]
        c0 = np.clip(column0, 0, self.columns - 1)
        c1 = np.clip(column0 + 1, 0, self.columns - 1)
        r0 = np.clip(row0, 0, self.rows - 1)
        r1 = np.clip(row0 + 1, 0, self.rows - 1)
        top = self._flow[r0, c0] * (1.0 - fu) + self._flow[r0, c1] * fu
        bottom = self._flow[r1, c0] * (1.0 - fu) + self._flow[r1, c1] * fu
        blended = top * (1.0 - fv) + bottom * fv

        lengths = np.hypot(blended[:, 0], blended[:, 1])
        usable = inside & (lengths > 1e-6)
        out = direct.copy()
        out[usable] = blended[usable] / lengths[usable, None]
        return out.astype(np.float32)

    def _direct_to_target(self, points: np.ndarray) -> np.ndarray:
        offset = np.asarray([float(self.target.x), float(self.target.y)], dtype=np.float32) - points
        lengths = np.hypot(offset[:, 0], offset[:, 1])
        out = np.zeros_like(offset)
        moving = lengths > 1e-6
        out[moving] = offset[moving] / lengths[moving, None]
        return out

    def _row_of(self, z: float) -> int:
        min_z = self.bounds[1]
        return int(min(max(int((z - min_z) / self.cell), 0), self.rows - 1))

    def _column_of(self, x: float) -> int:
        min_x = self.bounds[0]
        return int(min(max(int((x - min_x) / self.cell), 0), self.columns - 1))


# ============================================================================
# Steering helpers
# ============================================================================


def seek(position: Vec2, target: Vec2) -> Vec2:
    """Unit vector from *position* toward *target*, zero when they coincide."""
    dx = float(target.x) - float(position.x)
    dz = float(target.y) - float(position.y)
    length = math.hypot(dx, dz)
    if length < 1e-6:
        return Vec2(0.0, 0.0)
    return Vec2(dx / length, dz / length)


def limit(vector: Vec2, maximum: float) -> Vec2:
    """Clamp a plane vector's magnitude to *maximum*."""
    length = math.hypot(float(vector.x), float(vector.y))
    if length <= maximum or length < 1e-9:
        return Vec2(float(vector.x), float(vector.y))
    scale = maximum / length
    return Vec2(float(vector.x) * scale, float(vector.y) * scale)


def separation(positions: np.ndarray, radius: float) -> np.ndarray:
    """Per-body push-apart vectors for a swarm of ``(N, 2)`` plane positions.

    Each body is pushed away from every neighbour inside *radius*, weighted by
    how deeply the pair overlaps. The result is unnormalised so a body with one
    distant neighbour barely deviates while one buried in the shoal squirts
    out, which is what makes a shoal read as liquid rather than as a grid.
    """
    points = np.asarray(positions, dtype=np.float32).reshape(-1, 2)
    count = points.shape[0]
    if count < 2 or radius <= 0.0:
        return np.zeros_like(points)
    delta = points[:, None, :] - points[None, :, :]
    distance = np.hypot(delta[:, :, 0], delta[:, :, 1])
    np.fill_diagonal(distance, np.float32(np.inf))
    weight = np.clip(1.0 - distance / radius, 0.0, 1.0)
    safe = np.where(distance > 1e-6, distance, np.float32(1.0))
    push = delta / safe[:, :, None] * weight[:, :, None]
    return push.sum(axis=1).astype(np.float32)


# ============================================================================
# The shared enemy base
# ============================================================================


class Enemy(Node3D):
    """Base for every hostile: hull points, the elite tag, and the telegraph.

    Subclasses set :attr:`ARCHETYPE` to a key of ``balance.ENEMIES``, build
    their body in :meth:`build_body`, drive movement from
    ``on_fixed_update`` and implement :meth:`perform_attack`. They never call
    ``perform_attack`` directly: :meth:`begin_attack` runs the white telegraph
    flash first and fires the attack when it ends.
    """

    #: Key into ``balance.ENEMIES``; subclasses must set it.
    ARCHETYPE: str = ""
    #: Radius of the sensor hitbox other systems collide against. None builds
    #: no hitbox, for an archetype whose hulls are numpy rows rather than nodes.
    HITBOX_RADIUS: float | None = 1.5
    #: Body colour before any telegraph flash.
    BODY_COLOUR: tuple[float, float, float, float] = (0.55, 0.20, 0.42, 1.0)
    #: Length of this archetype's telegraph flash, seconds.
    telegraph_duration: float = balance.ENEMY_FIRE_TELEGRAPH_S

    #: Fires when the white flash starts, with this enemy's archetype id.
    telegraph_started = Signal(str)
    #: Fires once when hull points run out, before the node leaves the tree.
    died = Signal()

    def __init__(self, *, elite: str | None = None, seed: int | None = None, **kwargs):
        super().__init__(**kwargs)
        if elite is not None and elite not in balance.ELITE_MODIFIERS:
            raise ValueError(f"unknown elite modifier {elite!r}; expected one of {balance.ELITE_MODIFIERS}")
        self.spec: balance.EnemySpec = balance.ENEMIES[self.ARCHETYPE]
        self.hp: float = float(self.spec.hp)
        self.elite: str | None = elite
        self.velocity = Vec2(0.0, 0.0)
        self.flow_field: FlowField | None = None
        self.telegraph_remaining: float = 0.0
        self.stall_remaining: float = 0.0
        self.rng = random.Random(seed)
        self._phase_rng = random.Random(None if seed is None else f"{seed}:cadence")
        self._recoil = Vec2(0.0, 0.0)
        self._attack_pending = False
        self._materials: list[Material] = []
        self._base_colours: list[tuple[float, ...]] = []
        self._base_emissive: list[tuple[float, ...] | None] = []
        self.hit_flash_remaining: float = 0.0
        self.spark_cooldown: float = 0.0
        self.pip: HealthPip | None = None

    def set_seed(self, seed: int) -> None:
        """Reseed this enemy's randomness so a spawn is reproducible per node.

        Re-rolls the attack phase as well: the wave composer seeds a node after
        it has been added, and a stagger drawn before that would make the fight
        depend on construction order rather than on the seed.
        """
        self.rng = random.Random(seed)
        self._phase_rng = random.Random(f"{seed}:cadence")
        self.stagger_cadence()

    def stagger_cadence(self) -> None:
        """Offset this archetype's attack timer by a random slice of its cadence.

        Overridden by every archetype that attacks on a timer, and called both
        at construction and on :meth:`set_seed`. Without it a wave that spawns
        three Lancers together gets one Lancer three times over: the same
        wind-up, the same dash and the same recovery frame, which reads as a
        scripted volley rather than as three ships.
        """

    def cadence_offset(self, interval: float) -> float:
        """A random point inside *interval*, for seeding one cadence timer."""
        return float(interval) * self._phase_rng.random()

    # -- Lifecycle ----------------------------------------------------------

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

    def on_ready(self):
        self.position = Vec3(float(self.position.x), PLANE_Y, float(self.position.z))
        self.build_body()
        self._collect_materials()
        if self.HITBOX_RADIUS is not None:
            hitbox = self.add_child(Area3D(name="Hitbox", shape=SphereShape3D(radius=self.HITBOX_RADIUS)))
            hitbox.collision_layer = Layers.ENEMY
            hitbox.collision_mask = Layers.MASK_ENEMY
        self.flow_field = shared_flow_field(self)

    def build_body(self):
        """Add the archetype's visible geometry. Override in subclasses."""

    def _collect_materials(self) -> None:
        """Cache every body material and the look the telegraph and the flash restore."""
        self._materials = []
        self._base_colours = []
        self._base_emissive = []
        for node in self.walk():
            material = getattr(node, "material", None)
            if isinstance(material, Material):
                self._materials.append(material)
                self._base_colours.append(tuple(float(c) for c in material.colour))
                emissive = material.emissive_colour
                self._base_emissive.append(None if emissive is None else tuple(float(c) for c in emissive))

    # -- Movement -----------------------------------------------------------

    @property
    def plane_position(self) -> Vec2:
        """This enemy's position on the flight plane."""
        return to_plane(self.position)

    def steer_toward(self, target: Vec2) -> Vec2:
        """Unit steering direction toward *target*.

        Uses the shared flow field when it is integrated toward the same place,
        so a whole wave bends around the same wreck; otherwise steers directly,
        which is what a Skimmer chasing salvage needs.
        """
        field = self.flow_field
        position = self.plane_position
        if field is not None and field.targets(target):
            direction = field.sample(position)
            if float(direction.x) or float(direction.y):
                return direction
        return seek(position, target)

    def move(self, dt: float, direction: Vec2, speed: float) -> None:
        """Integrate one step along *direction*, staying exactly on the plane.

        The drive is whatever the archetype asked for, unless a contact hit has
        stalled it, in which case there is no drive at all for the rest of
        ``balance.CONTACT_STALL_S``. On top of that sits the separation recoil
        from the last collision, bleeding off at
        ``balance.CONTACT_RECOIL_DAMPING``: that is what carries a hostile back
        off the hull it just hit rather than through it.
        """
        drive_x = 0.0 if self.stalled else float(direction.x) * speed
        drive_z = 0.0 if self.stalled else float(direction.y) * speed
        vx = drive_x + float(self._recoil.x)
        vz = drive_z + float(self._recoil.y)
        self.velocity = Vec2(vx, vz)
        self.position = Vec3(
            float(self.position.x) + vx * dt,
            PLANE_Y,
            float(self.position.z) + vz * dt,
        )
        self.decay_recoil(dt)

    # -- Contact ------------------------------------------------------------

    @property
    def stalled(self) -> bool:
        """Whether a contact hit has this enemy's drive shut down."""
        return self.stall_remaining > 0.0

    def stall(self, seconds: float) -> None:
        """Kill this enemy's drive for *seconds*. Never shortens a live stall."""
        self.stall_remaining = max(self.stall_remaining, float(seconds))

    def apply_contact_impulse(self, direction: Vec3, speed: float) -> None:
        """Add a separation velocity along a world *direction* at *speed*.

        Kept apart from :attr:`velocity` because an archetype rewrites its
        velocity from scratch every step; the recoil has to survive that pass or
        the collision would last exactly one frame.
        """
        self._recoil = Vec2(
            float(self._recoil.x) + float(direction.x) * float(speed),
            float(self._recoil.y) + float(direction.z) * float(speed),
        )

    def decay_recoil(self, dt: float) -> None:
        """Bleed the separation recoil off exponentially."""
        if not float(self._recoil.x) and not float(self._recoil.y):
            return
        keep = math.exp(-balance.CONTACT_RECOIL_DAMPING * dt)
        self._recoil = Vec2(float(self._recoil.x) * keep, float(self._recoil.y) * keep)

    def contact_damage(self, target, amount: float, kind: str = "impact") -> None:
        """Hurt *target* by touching it, and take the collision on the chin.

        The router owns contact when there is one, so the shield arc, the
        matrix and the run's damage ledger all still apply. Without a router the
        damage falls back to the target's own entry point and the separation is
        applied here, so an enemy in a bare scene is still a body rather than a
        ghost.
        """
        router = self.damage_router()
        resolve = getattr(router, "resolve_contact", None)
        if callable(resolve):
            resolve(self, target, amount, kind=kind)
            return
        self.deal_damage_to(target, amount, kind)
        separate_on_contact(self, target)

    def face(self, direction: Vec2) -> None:
        """Point the hull's nose along a plane direction."""
        if abs(float(direction.x)) < 1e-6 and abs(float(direction.y)) < 1e-6:
            return
        self.rotation = Quat.from_euler(0.0, math.atan2(-float(direction.y), float(direction.x)), 0.0)

    def distance_to(self, node) -> float:
        """Plane distance from this enemy to another node."""
        return math.hypot(
            float(node.position.x) - float(self.position.x),
            float(node.position.z) - float(self.position.z),
        )

    # -- The telegraph ------------------------------------------------------

    @property
    def telegraphing(self) -> bool:
        """Whether the white pre-attack flash is running."""
        return self.telegraph_remaining > 0.0

    def begin_attack(self) -> bool:
        """Telegraph now and attack when the flash ends.

        Returns False when a telegraph or attack is already in flight, so an
        archetype can call this every frame while a condition holds.
        """
        if self.telegraphing or self._attack_pending:
            return False
        self._attack_pending = True
        self.on_telegraph()
        return True

    def on_telegraph(self) -> None:
        """Flash the body white for :attr:`telegraph_duration` seconds."""
        self.telegraph_remaining = float(self.telegraph_duration)
        self.apply_telegraph_colour(True)
        self.telegraph_started(self.ARCHETYPE)

    def apply_telegraph_colour(self, active: bool) -> None:
        """Switch the body between its own colour and the telegraph white."""
        for material, base in zip(self._materials, self._base_colours, strict=True):
            material.colour = TELEGRAPH_COLOUR if active else base

    def perform_attack(self) -> None:
        """Land the attack the telegraph announced. Override in subclasses."""

    def on_update(self, dt: float):
        if self.stall_remaining > 0.0:
            self.stall_remaining = max(0.0, self.stall_remaining - dt)
        self._tick_hit_flash(dt)
        if self.telegraph_remaining <= 0.0:
            return
        self.telegraph_remaining -= dt
        if self.telegraph_remaining > 0.0:
            return
        self.telegraph_remaining = 0.0
        self.apply_telegraph_colour(False)
        if self._attack_pending:
            self._attack_pending = False
            self.perform_attack()

    # -- Damage -------------------------------------------------------------

    def take_damage(self, amount: float, kind: str) -> None:
        """Subtract hull points, show the hit, and die at zero."""
        if self.destroying or amount <= 0.0:
            return
        self.hp -= float(amount)
        self.show_hit()
        if self.hp <= 0.0:
            self.hp = 0.0
            self.kill()
            return
        self.refresh_pip()

    # -- Damage feedback ----------------------------------------------------

    @property
    def flashing_hit(self) -> bool:
        """Whether the white hit pulse is currently on the hull."""
        return self.hit_flash_remaining > 0.0

    def hull_ceiling(self) -> float:
        """This hull's full pool, honouring an elite that inflated it."""
        return max(float(getattr(self, "max_hp", self.spec.hp)), float(self.hp), 1e-6)

    def carries_pip(self) -> bool:
        """Whether this hull is big enough to be worth a health read-out."""
        return self.hull_ceiling() >= HP_PIP_MIN_HP

    def show_hit(self, at: Vec3 | None = None) -> None:
        """React to a hit that landed: pulse white and throw a spark.

        *at* is where the round came apart; without one the hull's own position
        stands in, which is accurate to within its own radius and is what a
        caller that only knows "this node was hit" can honestly supply.
        """
        self.flash_hit()
        self.spark_at(Vec3(self.position) if at is None else at)

    def flash_hit(self) -> None:
        """Drive the body's emissive to white for :data:`HIT_FLASH_S`."""
        self.hit_flash_remaining = HIT_FLASH_S
        self.apply_hit_flash(True)

    def apply_hit_flash(self, active: bool) -> None:
        """Switch the body's emissive between the pulse and its own value."""
        for material, base in zip(self._materials, self._base_emissive, strict=True):
            if active:
                material.emissive_colour = (*HIT_FLASH_EMISSIVE, HIT_FLASH_STRENGTH)
            else:
                material.emissive_colour = base

    def spark_at(self, at: Vec3) -> None:
        """Throw a one-shot impact spark at a world point.

        Rate-limited to :data:`HIT_SPARK_INTERVAL_S`, because a beam lands a hit
        every frame and an unthrottled spark would both drain the effect pool
        and turn a stream of impacts into one solid patch of light.
        """
        tree = self.tree
        if tree is None or tree.root is None or self.spark_cooldown > 0.0:
            return
        self.spark_cooldown = HIT_SPARK_INTERVAL_S
        Vfx.spawn(tree, "enemy_hit", Vec3(float(at.x), PLANE_Y, float(at.z)))

    def refresh_pip(self) -> None:
        """Show, update or retire this hull's health pip.

        Mounted on the first hit rather than at spawn: an untouched field
        carries no read-outs at all, which is what keeps the pips meaningful
        when a fight does start.
        """
        if not self.carries_pip() or self.destroying:
            return
        if self.pip is None:
            self.pip = self.add_child(HealthPip(position=Vec3(0.0, HP_PIP_HEIGHT, HP_PIP_OFFSET_Z)))
        self.pip.set_fraction(float(self.hp) / self.hull_ceiling())

    def _tick_hit_flash(self, dt: float) -> None:
        if self.spark_cooldown > 0.0:
            self.spark_cooldown = max(0.0, self.spark_cooldown - dt)
        if self.hit_flash_remaining <= 0.0:
            return
        self.hit_flash_remaining -= dt
        if self.hit_flash_remaining <= 0.0:
            self.hit_flash_remaining = 0.0
            self.apply_hit_flash(False)

    def kill(self) -> None:
        """Report the kill and leave the tree.

        The damage router owns the consequences (scrap drop, signature, the
        ``ENEMY_KILLED`` signal); this only reports and stands down.
        """
        if self.destroying:
            return
        if self.pip is not None:
            self.pip.dismiss()
        self.died()
        router = self.damage_router()
        if router is not None:
            router.report_kill(self)
        self.destroy()

    def damage_router(self):
        """The run's damage router, or None before one is registered."""
        tree = self.tree
        return None if tree is None else tree.singletons.get(Services.DAMAGE)

    def deal_damage_to(self, target, amount: float, kind: str = "impact") -> None:
        """Hurt *target* through the damage router, or directly as a fallback.

        The router is the only code allowed to apply damage numbers once it
        exists; the direct call keeps an enemy dangerous in a scene assembled
        without one.
        """
        direction = from_plane(seek(self.plane_position, to_plane(target.position)))
        router = self.damage_router()
        if router is not None:
            router.deal(target, amount, kind=kind, direction=direction, source=self)
        elif hasattr(target, "apply_damage"):
            target.apply_damage(amount, direction, kind)

    # -- Lookups ------------------------------------------------------------

    def player_ship(self):
        """The player's ship node, or None when it is gone."""
        tree = self.tree
        if tree is None:
            return None
        for ship in tree.group(Groups.SHIP):
            if not ship.destroying:
                return ship
        return None


class FlowFieldDirector(Node3D):
    """Owns the scene-wide flow field and re-integrates it toward the ship.

    Add one to the run scene and every enemy picks it up automatically, so a
    wave of twenty bodies costs one integration per
    :data:`FLOW_REBUILD_INTERVAL_S` rather than twenty path queries per frame.
    Wrecks, deposits and hazards are charged as obstacles, which is what bends
    a swarm around the terrain instead of through it.
    """

    OBSTACLE_GROUPS = (Groups.WRECKS, Groups.DEPOSITS, Groups.HAZARDS)

    def __init__(self, bounds: tuple[float, float, float, float] = DEFAULT_FIELD_BOUNDS, **kwargs):
        super().__init__(**kwargs)
        self.field = FlowField(bounds)
        self._until_rebuild = 0.0

    def on_enter_tree(self):
        super().on_enter_tree()
        self.add_to_group(FLOW_FIELD_GROUP)

    def on_update(self, dt: float):
        self._until_rebuild -= dt
        if self._until_rebuild > 0.0:
            return
        self._until_rebuild = FLOW_REBUILD_INTERVAL_S
        self.rebuild_now()

    def rebuild_now(self) -> None:
        """Re-integrate the field toward the ship's current position."""
        tree = self.tree
        if tree is None:
            return
        ships = [ship for ship in tree.group(Groups.SHIP) if not ship.destroying]
        if not ships:
            return
        obstacles = [
            to_plane(node.position)
            for group in self.OBSTACLE_GROUPS
            for node in tree.group(group)
            if not node.destroying
        ]
        self.field.rebuild(to_plane(ships[0].position), obstacles)


def shared_flow_field(node) -> FlowField | None:
    """The scene's shared field, or None when no director is present."""
    tree = node.tree
    if tree is None:
        return None
    for director in tree.group(FLOW_FIELD_GROUP):
        if not director.destroying:
            return director.field
    return None