shrike/combat.py

Part of SHRIKE.

"""The damage router and the collision-layer contract.

Two things live here, and they are the same job seen from two sides.

**The layer contract.** ``runtime.Layers`` holds the bits; this module holds
the matrix, as :data:`LAYER_CONTRACT`, one ``(layer, mask)`` pair per role a
body or sensor can play. :func:`bind_layers` is the only supported way to set
those two numbers, :func:`layer_of` answers "what is this node" for a gameplay
node whose collision shape is a child, and :func:`may_damage` answers "is this
pair allowed to hurt each other" from the masks rather than from the caller's
good intentions. The one documented exception is the Welder's umbilical, a
sensor that watches the ship alone: see :data:`Roles.UMBILICAL`.

**The router.** :class:`DamageRouter` is the only code in the game that applies
a damage number. Weapons, enemies and the hunter all call :meth:`deal`, which
resolves the ballistic premium, hull plating and the direction convention, then
forwards to the target's own damage entry point. Kills come back through
:meth:`report_kill`, which drops the scrap and emits ``ENEMY_KILLED``; the
signature meter, the notoriety tally, the HUD and the juice layer all hang off
that one signal rather than off the enemy that died.

Contact
=======

Hull-to-hull damage goes through :meth:`DamageRouter.resolve_contact` rather
than through :meth:`deal`, because contact is the one damage source with
nothing flying between the two bodies and so the one that has to read as a
collision. Resolving it stalls the attacker for ``balance.CONTACT_STALL_S`` and
puts a radial separation impulse on both hulls, so a Lancer that connects stops
dead and bounces off instead of gliding through the ship trailing a damage
number.

Direction convention
====================

Every caller passes ``direction`` as the direction the damage **travelled**,
source to target: a projectile's flight vector, an enemy's charge vector. The
ship, the HUD and the shield arc all speak the opposite convention, the bearing
from the ship **toward** its attacker, because that is the bearing a player
defends. The router is the single place that flips it, so no caller has to
remember which way round it is.
"""

import math
import random

from simvx.core import Node, Node3D, Signal, Vec2, Vec3

from . import balance
from .power import iter_tree_nodes
from .runtime import PLANE_Y, Groups, Layers, to_plane

# ============================================================================
# Numbers the design fixes in prose rather than in a table, derived from the
# constants balance.py does carry. Flagged for the balance pass.
# ============================================================================

#: Ballistic weapons hit harder per shot than energy weapons and pay for it in
#: the scrap economy. Balance carries the band, not the working figure, so the
#: router uses the middle of it.
BALLISTIC_PREMIUM = (balance.BALLISTIC_DAMAGE_PREMIUM_MIN + balance.BALLISTIC_DAMAGE_PREMIUM_MAX) * 0.5


class Roles:
    """Every part a body or sensor can play in the collision matrix."""

    SHIP = "ship"
    ENEMY = "enemy"
    PLAYER_FIRE = "player_fire"
    ENEMY_FIRE = "enemy_fire"
    SALVAGE = "salvage"
    SCOOP = "scoop"
    TERRAIN = "terrain"
    HUNTER = "hunter"
    INTERACT = "interact"
    #: The Welder's repair umbilical: it is enemy-side geometry, but the only
    #: thing it must notice is the ship flying through it to snap the beam, so
    #: it watches ``SHIP`` alone instead of taking ``MASK_ENEMY``.
    UMBILICAL = "umbilical"


#: ``role -> (collision_layer, collision_mask)``. The whole matrix, in one place.
LAYER_CONTRACT: dict[str, tuple[int, int]] = {
    Roles.SHIP: (Layers.SHIP, Layers.MASK_SHIP),
    Roles.ENEMY: (Layers.ENEMY, Layers.MASK_ENEMY),
    Roles.PLAYER_FIRE: (Layers.PLAYER_FIRE, Layers.MASK_PLAYER_FIRE),
    Roles.ENEMY_FIRE: (Layers.ENEMY_FIRE, Layers.MASK_ENEMY_FIRE),
    Roles.SALVAGE: (Layers.SALVAGE, 0),
    Roles.SCOOP: (Layers.SHIP, Layers.MASK_SCOOP),
    Roles.TERRAIN: (Layers.TERRAIN, 0),
    Roles.HUNTER: (Layers.HUNTER, Layers.SHIP | Layers.TERRAIN),
    Roles.INTERACT: (Layers.INTERACT, Layers.MASK_INTERACT_SENSOR),
    Roles.UMBILICAL: (Layers.ENEMY, Layers.SHIP),
}

#: The mask a bare layer bit implies, for a node that never carried a shape of
#: its own. Roles that share a layer (the scoop is ship-layered) are resolved by
#: the node itself when it carries a real ``collision_mask``.
_MASK_FOR_LAYER: dict[int, int] = {
    Layers.SHIP: Layers.MASK_SHIP,
    Layers.ENEMY: Layers.MASK_ENEMY,
    Layers.PLAYER_FIRE: Layers.MASK_PLAYER_FIRE,
    Layers.ENEMY_FIRE: Layers.MASK_ENEMY_FIRE,
    Layers.SALVAGE: 0,
    Layers.TERRAIN: 0,
    Layers.HUNTER: Layers.SHIP | Layers.TERRAIN,
    Layers.INTERACT: Layers.MASK_INTERACT_SENSOR,
}

#: Group membership implies a layer for gameplay nodes whose collision shape is
#: a child: an ``Enemy`` is a plain ``Node3D`` with a hitbox underneath it.
_LAYER_FOR_GROUP: tuple[tuple[str, int], ...] = (
    (Groups.SHIP, Layers.SHIP),
    (Groups.HUNTER, Layers.HUNTER),
    (Groups.ENEMIES, Layers.ENEMY),
    (Groups.PLAYER_PROJECTILES, Layers.PLAYER_FIRE),
    (Groups.ENEMY_PROJECTILES, Layers.ENEMY_FIRE),
    (Groups.SALVAGE, Layers.SALVAGE),
    (Groups.DEPOSITS, Layers.TERRAIN),
    (Groups.WRECKS, Layers.TERRAIN),
    (Groups.VAULTS, Layers.INTERACT),
    (Groups.DEPOTS, Layers.INTERACT),
)


def bind_layers(node: Node, role: str) -> None:
    """Stamp the contract's ``(layer, mask)`` for *role* onto *node*.

    Raises ``KeyError`` for an unknown role: a body with the wrong bits is a
    silent gameplay bug, so a typo has to fail loudly at the seam instead.
    """
    try:
        layer, mask = LAYER_CONTRACT[role]
    except KeyError:
        known = ", ".join(sorted(LAYER_CONTRACT))
        raise KeyError(f"unknown collision role {role!r}; expected one of {known}") from None
    node.collision_layer = layer
    node.collision_mask = mask


def layer_of(node: Node) -> int:
    """What *node* is, as a layer bit, or 0 when nothing claims it.

    Reads the node's own ``collision_layer`` first, then falls back to group
    membership so a gameplay node that keeps its shape in a child still answers
    the question.
    """
    layer = int(getattr(node, "collision_layer", 0) or 0)
    if layer:
        return layer
    for group, bit in _LAYER_FOR_GROUP:
        if node.is_in_group(group):
            return bit
    return 0


def mask_of(node: Node) -> int:
    """What *node* can see, as a mask, falling back to its layer's default."""
    mask = int(getattr(node, "collision_mask", 0) or 0)
    if mask:
        return mask
    return _MASK_FOR_LAYER.get(layer_of(node), 0)


def may_damage(source: Node, target: Node) -> bool:
    """True when the matrix lets *source* hurt *target*.

    The mask is the authority in one direction only: what the attacker sees.
    Player fire cannot see the ship and enemy fire cannot see enemies, so this
    is what keeps friendly fire out of the game without a per-caller check.
    """
    return bool(mask_of(source) & layer_of(target))


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


def damage_multiplier_for(target: Node) -> float:
    """How much of an incoming number *target* actually takes.

    A target may declare its own ``damage_taken_mult`` (the Shrike's fins carry
    plating, a Warden's shielded face does not). Anything hunter-side that has
    not declared one is plated: that is what makes shearing a fin a 15-second
    commitment rather than a burst.
    """
    declared = getattr(target, "damage_taken_mult", None)
    if declared is not None:
        return max(0.0, float(declared))
    if target.is_in_group(Groups.HUNTER):
        return balance.SHRIKE_FIN_DAMAGE_TAKEN_MULT
    return 1.0


# ============================================================================
# Contact resolution
# ============================================================================


def contact_axis(attacker: Node3D, target: Node3D) -> Vec3:
    """The unit plane vector a contact hit travelled along, attacker to target.

    Two hulls resting exactly on top of each other fall back to a fixed axis, so
    a collision at zero distance still separates instead of dividing by zero.
    """
    dx = float(target.position.x) - float(attacker.position.x)
    dz = float(target.position.z) - float(attacker.position.z)
    length = math.hypot(dx, dz)
    if length < 1e-6:
        return Vec3(1.0, 0.0, 0.0)
    return Vec3(dx / length, 0.0, dz / length)


def apply_separation(node: Node3D, direction: Vec3, speed: float) -> None:
    """Shove *node* along *direction* at *speed*, whatever kind of body it is.

    A hostile owns a recoil channel that survives its own steering pass
    (``Enemy.apply_contact_impulse``); anything else carrying a plane
    ``velocity``, the ship included, takes the impulse straight onto it and
    bleeds it off through its own dampening. A body with neither is not
    something a collision can move, and is left where it is.
    """
    if node is None or speed <= 0.0:
        return
    impulse = getattr(node, "apply_contact_impulse", None)
    if callable(impulse):
        impulse(direction, speed)
        return
    velocity = getattr(node, "velocity", None)
    if velocity is None:
        return
    node.velocity = Vec2(
        float(velocity.x) + float(direction.x) * speed,
        float(velocity.y) + float(direction.z) * speed,
    )


def separate_on_contact(attacker: Node3D, target: Node3D) -> Vec3:
    """Stall *attacker* and push both hulls apart; returns the travel axis.

    The attacker takes the whole impulse and the target the fraction
    ``balance.CONTACT_TARGET_IMPULSE_FRACTION`` of it, because the ship is the
    heavier of the two and a collision that flung the player around would cost
    more control than the hit costs hull.
    """
    travel = contact_axis(attacker, target)
    stall = getattr(attacker, "stall", None)
    if callable(stall):
        stall(balance.CONTACT_STALL_S)
    away = Vec3(-float(travel.x), 0.0, -float(travel.z))
    apply_separation(attacker, away, balance.CONTACT_SEPARATION_IMPULSE)
    apply_separation(target, travel, balance.CONTACT_SEPARATION_IMPULSE * balance.CONTACT_TARGET_IMPULSE_FRACTION)
    return travel


class DamageRouter(Node):
    """The single owner of every damage number in the run.

    Registered as ``Services.DAMAGE``. Callers never touch a target's hull:
    they hand :meth:`deal` an amount, a kind and the direction the damage
    travelled, and the router resolves the premium, the plating and the
    direction convention before forwarding. Player hits go to
    ``PlayerShip.apply_damage``, which owns the shield arc, so the router never
    resolves shield coverage a second time and never re-emits the shield's own
    signals.

    Deaths come back through :meth:`report_kill` rather than through the enemy
    node, so scrap, signature, notoriety, audio and juice all read one event.
    """

    #: (target: Node, amount: float, kind: str) after every resolution step.
    damage_dealt = Signal(Node, float, str)
    #: (archetype: str, position: Vec3, elite: bool)
    enemy_killed = Signal(str, Vec3, bool)
    #: (amount: float, direction: Vec3) with the bearing toward the attacker,
    #: and only for damage that actually reached the hull.
    player_damaged = Signal(float, Vec3)

    def __init__(self, *, seed: int = 0, **kwargs):
        super().__init__(**kwargs)
        #: Total damage the router has put on hulls this run.
        self.damage_applied = 0.0
        #: Kills reported this run, including each mite of a shoal.
        self.kills = 0
        #: Scrap released by kills this run, before any scoop pass.
        self.kill_scrap = 0.0
        #: Archetype of whatever last put a hit on the ship, "" for an
        #: unsourced hit. Recorded before the hull resolves the hit, because
        #: ``SHIP_DESTROYED`` fires from inside that resolution: this is what
        #: lets the death ledger name the killer instead of guessing it.
        self.last_ship_hit_by = ""
        self._rng = random.Random(seed)
        self._sector_cache = None

    # ------------------------------------------------------------------ damage

    def deal(self, target: Node, amount: float, *, kind: str, direction: Vec3, source: Node | None = None) -> float:
        """Apply *amount* to *target* and return what actually landed.

        *direction* is the direction the damage travelled, source to target.
        *kind* is the weapon family ("energy", "ballistic") or the contact kind
        ("impact", "beam"). Passing *source* opts the call into the collision
        matrix (a shot its mask cannot see is dropped rather than applied) and,
        for a hit on the ship, is what lets the death ledger name the killer.
        """
        amount = float(amount)
        if target is None or amount <= 0.0 or target.destroying:
            return 0.0
        if source is not None and not may_damage(source, target):
            return 0.0

        travel = _normalised(Vec3(direction))
        if layer_of(target) == Layers.SHIP:
            return self._damage_ship(target, amount, kind, travel, source)
        return self._damage_hostile(target, amount, kind, travel)

    def resolve_contact(self, attacker: Node3D, target: Node3D, amount: float, *, kind: str = "impact") -> float:
        """Land a hull-to-hull hit and make it read as a collision.

        The damage goes through :meth:`deal` like any other, so the shield arc,
        the plating and the matrix all still apply. What contact adds is weight:
        the attacker's drive dies for ``balance.CONTACT_STALL_S`` and both hulls
        take a radial impulse apart, whether or not the hit got past the shield.
        The collision happened either way.
        """
        if attacker is None or target is None or target.destroying:
            return 0.0
        travel = contact_axis(attacker, target)
        landed = self.deal(target, amount, kind=kind, direction=travel, source=attacker)
        separate_on_contact(attacker, target)
        return landed

    def _damage_ship(self, ship: Node, amount: float, kind: str, travel: Vec3, source: Node | None = None) -> float:
        """Hand a hit to the ship and report only what got past the shield.

        The attacker is recorded *before* the hull resolves the hit: a fatal
        hit emits ``SHIP_DESTROYED`` from inside ``apply_damage``, and the
        run's death handler reads :meth:`last_ship_attacker` synchronously
        from within that emission.
        """
        self.last_ship_hit_by = self._archetype_of(source) if source is not None else ""
        toward_attacker = Vec3(-float(travel.x), 0.0, -float(travel.z))
        before = float(getattr(ship, "hull", 0.0))
        ship.apply_damage(amount, toward_attacker, kind)
        leaked = max(0.0, before - float(getattr(ship, "hull", 0.0)))
        if leaked <= 0.0:
            return 0.0
        self.damage_applied += leaked
        self.damage_dealt(ship, leaked, kind)
        self.player_damaged(leaked, toward_attacker)
        return leaked

    def _damage_hostile(self, target: Node, amount: float, kind: str, travel: Vec3) -> float:
        """Resolve the premium and the plating, then hurt the target."""
        if kind == "ballistic":
            amount *= 1.0 + BALLISTIC_PREMIUM
        amount *= damage_multiplier_for(target)
        if amount <= 0.0:
            return 0.0

        take_damage = getattr(target, "take_damage", None)
        if take_damage is not None:
            take_damage(amount, kind)
        elif hasattr(target, "apply_damage"):
            target.apply_damage(amount, travel, kind)
        else:
            return 0.0

        self.damage_applied += amount
        self.damage_dealt(target, amount, kind)
        return amount

    def last_ship_attacker(self) -> str:
        """Archetype of whatever last hit the ship, or "" when nothing sourced has.

        Valid mid-death: the ship's destruction is emitted from inside the hit
        that caused it, so during that emission this names the killer.
        """
        return self.last_ship_hit_by

    # ------------------------------------------------------------------- kills

    def report_kill(self, enemy: Node3D) -> None:
        """Bank one kill: drop its scrap, then announce it.

        A shoal reports once per mite, from the shoal's own node, so this must
        stay cheap and must never assume the reporter is leaving the tree.
        """
        archetype = self._archetype_of(enemy)
        elite = bool(getattr(enemy, "elite", None))
        position = Vec3(enemy.position.x, PLANE_Y, enemy.position.z)

        self.kills += 1
        self._drop_scrap(position)
        self.enemy_killed(archetype, position, elite)

    def _archetype_of(self, enemy: Node) -> str:
        spec = getattr(enemy, "spec", None)
        archetype = getattr(spec, "id", None)
        return str(archetype) if archetype else type(enemy).__name__.lower()

    def _drop_scrap(self, position: Vec3) -> None:
        """Scatter a kill's scrap as motes the ship has to fly through."""
        amount = float(self._rng.randint(balance.SCRAP_KILL_MIN, balance.SCRAP_KILL_MAX))
        if amount <= 0.0:
            return
        self.kill_scrap += amount
        sector = self._sector()
        if sector is not None:
            sector.release("scrap", amount, to_plane(position))

    def _sector(self):
        """The live sector, or None in a scene assembled without one.

        Cached, and re-resolved whenever the cached one has left: a mite shoal
        reports a kill per mite, and the walk is the expensive half.
        """
        cached = self._sector_cache
        if cached is not None and not cached.destroying and cached.tree is not None:
            return cached
        self._sector_cache = None
        tree = self.tree
        if tree is None:
            return None
        from . import sector as sector_module

        for node in iter_tree_nodes(tree):
            if isinstance(node, sector_module.Sector):
                self._sector_cache = node
                return node
        return None


__all__ = [
    "BALLISTIC_PREMIUM",
    "LAYER_CONTRACT",
    "DamageRouter",
    "Roles",
    "apply_separation",
    "bind_layers",
    "contact_axis",
    "damage_multiplier_for",
    "layer_of",
    "mask_of",
    "may_damage",
    "separate_on_contact",
]