shrike/runtime.py

Part of SHRIKE.

"""The shared runtime spine of SHRIKE.

Everything that more than one gameplay module must agree on lives here: the
flight-plane convention, the signal-name registry, node groups, collision
layers, the camera rig, and the input map. Gameplay modules import these
names; none of them redefines a group string, a layer bit or a signal name of
its own.

Flight-plane convention
=======================

Gameplay happens on a single plane in 3D space:

* **Y is up.** The flight plane is the XZ plane at ``y = PLANE_Y`` (0.0).
* Ship, enemies, salvage and projectiles keep ``position.y == PLANE_Y`` at all
  times; anything visual may float above or below, gameplay logic never does.
* 2D quantities on the plane map as ``Vec2(x, z)``; :func:`to_plane` and
  :func:`from_plane` convert. Headings are radians anticlockwise from +X when
  viewed from above (from +Y looking down).
* The camera looks down at the plane from a pitch of about 60 degrees from the
  horizontal, offset toward +Z, so on screen +X is right and -Z is up.
"""

import math

from simvx.core import (
    Camera3D,
    Input,
    InputBinding,
    InputMap,
    JoyAxis,
    JoyButton,
    Key,
    MouseButton,
    Node3D,
    Vec2,
    Vec3,
)

from . import balance

# ============================================================================
# Flight plane
# ============================================================================

PLANE_Y = 0.0

#: Window size for the interactive app; tests use SceneRunner's own size.
WINDOW_WIDTH = 1280
WINDOW_HEIGHT = 720


def to_plane(v: Vec3) -> Vec2:
    """Project a world position onto the flight plane as ``Vec2(x, z)``."""
    return Vec2(float(v.x), float(v.z))


def from_plane(p: Vec2, y: float = PLANE_Y) -> Vec3:
    """Lift a flight-plane position back into world space."""
    return Vec3(float(p.x), y, float(p.y))


def heading_to_direction(heading: float) -> Vec3:
    """Unit world vector on the plane for a heading in radians (0 is +X)."""
    return Vec3(math.cos(heading), 0.0, -math.sin(heading))


# ============================================================================
# Node groups
# ============================================================================


class Groups:
    """Scene-tree group names. Query with ``self.tree.group(Groups.X)``."""

    SHIP = "ship"
    ENEMIES = "enemies"
    HUNTER = "hunter"
    TURRETS = "turrets"
    SALVAGE = "salvage"
    DEPOSITS = "deposits"
    WRECKS = "wrecks"
    VAULTS = "vaults"
    DEPOTS = "depots"
    PLAYER_PROJECTILES = "player_projectiles"
    ENEMY_PROJECTILES = "enemy_projectiles"
    HAZARDS = "hazards"


class Services:
    """Singleton names for the run-scoped system nodes.

    Registered with ``tree.add_singleton(name, node)`` by the run scene and
    looked up with ``tree.singletons[name]``. One name per system module.
    """

    POWER = "power_system"
    SIGNATURE = "signature_meter"
    ECONOMY = "economy"
    NOTORIETY = "notoriety"
    WAVES = "wave_composer"
    DAMAGE = "damage_router"
    JUICE = "juice_director"
    AUDIO = "audio_director"
    SAVE = "save_system"
    META = "meta_profile"
    HUD = "hud"


# ============================================================================
# Collision layers
# ============================================================================


class Layers:
    """Collision layer bits, shared by every body and area in the game.

    A body's ``collision_layer`` says what it IS; its ``collision_mask`` says
    what it SEES. The canonical masks below are the default matrix; combat.py
    owns any exception and documents it where it applies.
    """

    SHIP = 1 << 0
    ENEMY = 1 << 1
    PLAYER_FIRE = 1 << 2
    ENEMY_FIRE = 1 << 3
    SALVAGE = 1 << 4
    TERRAIN = 1 << 5
    HUNTER = 1 << 6
    INTERACT = 1 << 7  # depots, vaults, deposits, event triggers (sensor-only)

    MASK_SHIP = ENEMY | ENEMY_FIRE | TERRAIN | HUNTER
    MASK_ENEMY = SHIP | PLAYER_FIRE | TERRAIN
    MASK_PLAYER_FIRE = ENEMY | TERRAIN | HUNTER
    MASK_ENEMY_FIRE = SHIP | TERRAIN
    MASK_SCOOP = SALVAGE
    MASK_INTERACT_SENSOR = SHIP


# ============================================================================
# Signal-name registry
# ============================================================================


class SignalNames:
    """Canonical names for every cross-module signal.

    A module that owns one of these defines a ``Signal`` attribute with
    exactly this name on the emitting node; consumers connect by attribute.
    Payloads are documented beside each name below. Signals used only within
    one module need not be registered here.
    """

    # ship.py
    HULL_CHANGED = "hull_changed"  # (current: float, maximum: float)
    BREACH_OPENED = "breach_opened"  # (open_breaches: int)
    BREACH_PATCHED = "breach_patched"  # (open_breaches: int)
    SHIP_DESTROYED = "ship_destroyed"  # ()
    AFTERBURNER_CHANGED = "afterburner_changed"  # (active: bool)

    # power.py
    CAPACITOR_CHANGED = "capacitor_changed"  # (current: float, maximum: float)
    ENERGY_DENIED = "energy_denied"  # (consumer: str)
    SOLAR_STATE_CHANGED = "solar_state_changed"  # (state: str)
    WING_DESTROYED = "wing_destroyed"  # (wing_index: int)
    GENERATOR_CHANGED = "generator_changed"  # (running: bool)
    SILENT_RUNNING_CHANGED = "silent_running_changed"  # (active: bool)
    O2_CHANGED = "o2_changed"  # (current: float, maximum: float)
    FUEL_CHANGED = "fuel_changed"  # (current: float, maximum: float)

    # signature.py
    SIGNATURE_CHANGED = "signature_changed"  # (value: float)
    SIGNATURE_LOCKED = "signature_locked"  # ()

    # weapons.py
    WEAPON_FIRED = "weapon_fired"  # (weapon_id: str)
    AMMO_CHANGED = "ammo_changed"  # (weapon_id: str, rounds: int)
    WEAPON_EQUIPPED = "weapon_equipped"  # (weapon_id: str, hardpoint: int)

    # combat.py
    DAMAGE_DEALT = "damage_dealt"  # (target: Node, amount: float, kind: str)
    ENEMY_KILLED = "enemy_killed"  # (archetype: str, position: Vec3, elite: bool)
    PLAYER_DAMAGED = "player_damaged"  # (amount: float, direction: Vec3)
    SHIELD_ABSORBED = "shield_absorbed"  # (amount: float)
    SHIELD_BROKEN = "shield_broken"  # ()

    # enemies
    SCREAMER_SCREAMED = "screamer_screamed"  # ()
    UMBILICAL_BROKEN = "umbilical_broken"  # ()
    SHELL_LAUNCHED = "shell_launched"  # (origin: Vec3, flight_seconds: float)

    # waves.py
    WAVE_COMPOSED = "wave_composed"  # (recipe_id: str, threat_spent: float)
    WAVE_SPAWNED = "wave_spawned"  # (count: int)

    # hunter.py
    HUNTER_TELEGRAPH = "hunter_telegraph"  # (stage: str: "t60" | "t30" | "t0")
    HUNTER_ARRIVED = "hunter_arrived"  # (arrival_index: int)
    HUNTER_LOCKOUT_ENDED = "hunter_lockout_ended"  # ()
    HUNTER_FED = "hunter_fed"  # (scrap: float, seconds_bought: float)
    HUNTER_DEPARTED = "hunter_departed"  # ()
    QUILL_SHEARED = "quill_sheared"  # (quills_this_run: int)
    SECTOR_CRACKED = "sector_cracked"  # ()

    # sector.py / events.py
    SECTOR_ENTERED = "sector_entered"  # (sector_index: int, biome_id: str)
    RESOURCE_COLLECTED = "resource_collected"  # (kind: str, amount: float)
    RICH_NODE_TAPPED = "rich_node_tapped"  # ()
    VAULT_HACKED = "vault_hacked"  # (scrap: float)
    SIGNAL_EVENT = "signal_event"  # (event_id: str)

    # trading.py / economy
    SCRAP_CHANGED = "scrap_changed"  # (total: float)
    CORES_BANKED = "cores_banked"  # (cores: float, rate: float)
    DOCKED = "docked"  # (depot_id: str)
    UNDOCKED = "undocked"  # ()
    REFINERY_BATCH_STARTED = "refinery_batch_started"  # ()
    REFINERY_BATCH_COMPLETED = "refinery_batch_completed"  # (cores: float)

    # audio.py
    AUDIO_CUE = "audio_cue"  # (cue_id: str, caption: str): every played cue; the HUD's caption track

    # bounty.py
    NOTORIETY_CHANGED = "notoriety_changed"  # (value: int, reason: str)

    # chart.py
    CHART_OPENED = "chart_opened"  # ()
    JUMP_STARTED = "jump_started"  # (node_id: str, fuel_cost: float)
    JUMP_COMPLETED = "jump_completed"  # (node_id: str)
    WAKE_ADVANCED = "wake_advanced"  # (columns_consumed: int)

    # warp (ship.py owns the spool; flow.py consumes the outcome)
    WARP_SPOOL_STARTED = "warp_spool_started"  # (emergency: bool)
    WARP_SPOOL_INTERRUPTED = "warp_spool_interrupted"  # (added_seconds: float)
    WARP_SPOOL_CANCELLED = "warp_spool_cancelled"  # ()
    WARP_COMPLETED = "warp_completed"  # (emergency: bool)

    # flow.py
    RUN_STARTED = "run_started"  # (config: dict)
    RUN_ENDED = "run_ended"  # (outcome: str, ledger: dict)
    LAST_STAND_TRIGGERED = "last_stand_triggered"  # ()
    EXTRACTION_COMPLETED = "extraction_completed"  # (ledger: dict)

    # save.py / meta.py
    PROFILE_LOADED = "profile_loaded"  # (profile: dict)
    PROFILE_SAVED = "profile_saved"  # ()
    DOCTRINE_CHANGED = "doctrine_changed"  # (node_id: str, owned: bool)


# ============================================================================
# Input map
# ============================================================================

#: Every gameplay action, bound for keyboard and mouse AND gamepad. The run
#: root declares ``input_actions = INPUT_ACTIONS`` so the scene tree registers
#: the map at mount and re-registers it on every ``change_scene``.
INPUT_ACTIONS: dict[str, list] = {
    # Thrust vector (left stick on pad; the nose aims independently)
    "thrust_up": [Key.W, InputBinding(joy_axis=JoyAxis.LEFT_Y, joy_axis_positive=False)],
    "thrust_down": [Key.S, InputBinding(joy_axis=JoyAxis.LEFT_Y, joy_axis_positive=True)],
    "thrust_left": [Key.A, InputBinding(joy_axis=JoyAxis.LEFT_X, joy_axis_positive=False)],
    "thrust_right": [Key.D, InputBinding(joy_axis=JoyAxis.LEFT_X, joy_axis_positive=True)],
    # Aim nose (mouse position on keyboard; right stick on pad, read as an axis pair)
    "aim_up": [InputBinding(joy_axis=JoyAxis.RIGHT_Y, joy_axis_positive=False)],
    "aim_down": [InputBinding(joy_axis=JoyAxis.RIGHT_Y, joy_axis_positive=True)],
    "aim_left": [InputBinding(joy_axis=JoyAxis.RIGHT_X, joy_axis_positive=False)],
    "aim_right": [InputBinding(joy_axis=JoyAxis.RIGHT_X, joy_axis_positive=True)],
    # Weapons
    "fire_primary": [MouseButton.LEFT, InputBinding(joy_axis=JoyAxis.RIGHT_TRIGGER, joy_axis_positive=True)],
    "mining_beam": [MouseButton.RIGHT, InputBinding(joy_axis=JoyAxis.LEFT_TRIGGER, joy_axis_positive=True)],
    # Shield arc: Q/E rotate on keyboard; on pad the arc mirrors the aim vector
    # and the bumpers nudge it 60 degrees; tapping both re-centres it.
    "shield_left": [Key.Q, JoyButton.LEFT_BUMPER],
    "shield_right": [Key.E, JoyButton.RIGHT_BUMPER],
    # Movement and posture
    "afterburner": [Key.LEFT_SHIFT, JoyButton.A],
    "silent_running": [Key.C, JoyButton.Y],
    "solar_wings": [Key.X, JoyButton.DPAD_UP],
    "generator": [Key.Z, JoyButton.DPAD_DOWN],
    # Interaction: tap docks or grabs, hold 1 s patches the nearest breach,
    # hold 3 s starts a Refinery batch (or sells scrap while docked).
    "interact": [Key.F, JoyButton.X],
    "jettison_scrap": [Key.G, JoyButton.B],
    "warp_spool": [Key.R, JoyButton.LEFT_THUMB],
    "tractor_scoop": [Key.TAB, JoyButton.RIGHT_THUMB],
    # Screens. Escape is deliberately not on the chart: backing out of things
    # is what Escape means everywhere else, so it raises the pause overlay and
    # the map lives on its own key.
    "star_chart": [Key.M, JoyButton.BACK],
    "pause_menu": [Key.ESCAPE, JoyButton.START],
    # Display: hides and shows the HUD's persistent controls bar. A display
    # control rather than a gameplay verb, but it lives on the declarative map
    # like everything else so it remaps and reaches the pad.
    "toggle_controls": [Key.H, JoyButton.DPAD_LEFT],
    # Menu navigation. No gameplay code reads these; every screen's cursor
    # answers the arrows and Enter alongside the thrust keys and interact.
    # They share pad buttons with gameplay verbs and the controls-bar toggle
    # (D-pad, A) safely because the two vocabularies are never live at the same
    # time. All four arrows are declared because the screens advertise ARROWS as
    # one block, and half a block that answers is worse than none.
    "menu_up": [Key.UP, JoyButton.DPAD_UP],
    "menu_down": [Key.DOWN, JoyButton.DPAD_DOWN],
    "menu_left": [Key.LEFT, JoyButton.DPAD_LEFT],
    "menu_right": [Key.RIGHT, JoyButton.DPAD_RIGHT],
    "menu_confirm": [Key.ENTER, Key.KP_ENTER, JoyButton.A],
    # Developer readout: wall-clock frame time and, where the driver has
    # timestamp pools, the per-pass GPU times. Keyboard only and deliberately
    # unbound on the pad, because it is a measurement tool rather than a verb
    # and nothing in the game reads it. "It feels hotter than last build" is
    # not a number until somebody on real hardware presses this.
    "debug_frame_stats": [Key.F3],
}

#: Actions that are instruments rather than verbs. They are exempt from the
#: keyboard-and-pad rule every other action keeps: a pad button spent on a
#: developer readout is a pad button a pilot cannot use, and nothing in the game
#: reads these. Declared here rather than spelled out in the test, so the
#: exemption is the module's statement about itself.
DEBUG_ACTIONS: frozenset[str] = frozenset({"debug_frame_stats"})


def register_input_actions() -> None:
    """Register the full action map with the active :class:`InputMap`.

    The canonical path is declarative (``input_actions`` on the run root);
    this helper exists for tests and tools that drive input without mounting
    the real root scene.
    """
    for name, bindings in INPUT_ACTIONS.items():
        InputMap.add_action(name, list(bindings), _quiet=True)


def move_input() -> Vec2:
    """The thrust vector from the action map, on the flight plane, unnormalised.

    Returns ``Vec2(x, z)`` in plane coordinates: +x is screen right, +y (that
    is, world +Z) is screen down. Magnitude is clamped to 1.
    """
    x = Input.get_axis("thrust_left", "thrust_right")
    z = Input.get_axis("thrust_up", "thrust_down")
    v = Vec2(x, z)
    length = math.hypot(float(v.x), float(v.y))
    if length > 1.0:
        return Vec2(float(v.x) / length, float(v.y) / length)
    return v


def gamepad_aim_input() -> Vec2:
    """The right-stick aim vector in plane coordinates, zero when centred."""
    return Vec2(Input.get_axis("aim_left", "aim_right"), Input.get_axis("aim_up", "aim_down"))


# ============================================================================
# Camera rig
# ============================================================================

CAMERA_PITCH_RADIANS = math.radians(60.0)
CAMERA_DISTANCE = 42.0
CAMERA_FOV_DEGREES = 50.0
#: The aspect the framing is authored at. A window wider than this keeps the
#: same horizontal extent and gains nothing; a narrower one keeps the vertical
#: field and simply sees less to the sides.
CAMERA_REFERENCE_ASPECT = 16.0 / 9.0
#: Exponential follow smoothing rate, higher is stiffer.
CAMERA_FOLLOW_RATE = 8.0
#: Seconds of plane velocity the focus runs ahead of the ship by. The aim lead
#: alone points the view where the guns are; this points it where the hull is
#: going, which is the half that decides whether an obstacle arrives as a
#: surprise.
CAMERA_VELOCITY_LEAD_S = 0.45
#: Ceiling on the combined aim-plus-velocity lead, world units. Set above the
#: worst case honest play can produce (a full-speed burn straight at the far
#: corner of the screen) so it only ever catches an aim point that is off the
#: screen entirely, and the hull never leaves the middle of the frame.
CAMERA_LEAD_MAX_UNITS = 14.0
#: Below this pitch above the top screen edge the ground plane is no longer in
#: front of the camera; the framing maths clamps rather than diverging.
_CAMERA_MIN_EDGE_PITCH = math.radians(2.0)


def camera_fov_degrees(aspect: float) -> float:
    """The vertical field of view to use at *aspect*, fitting by width.

    A perspective camera holds its vertical extent fixed, so on an ultrawide
    window every extra pixel of width buys the player more warning to the
    sides than the game is balanced for. Past
    :data:`CAMERA_REFERENCE_ASPECT` this narrows the vertical field just
    enough to hold the horizontal extent at its authored value; at or below
    the reference aspect it is exactly :data:`CAMERA_FOV_DEGREES`.
    """
    aspect = max(float(aspect), 1e-3)
    half_height = math.tan(math.radians(CAMERA_FOV_DEGREES) * 0.5)
    half_width = half_height * CAMERA_REFERENCE_ASPECT
    return math.degrees(2.0 * math.atan(min(half_height, half_width / aspect)))


def camera_plane_extents(aspect: float = CAMERA_REFERENCE_ASPECT) -> tuple[float, float]:
    """Flight-plane distances from the focus to the near and far screen edges.

    Returns ``(near, far)`` in world units: how far toward +Z (screen down) the
    bottom edge of the screen reaches, and how far toward -Z (screen up) the
    top edge does. A pitched camera makes those two wildly different, which is
    why :class:`CameraRig` biases its focus rather than centring the ship.
    """
    half = math.radians(camera_fov_degrees(aspect)) * 0.5
    height = CAMERA_DISTANCE * math.sin(CAMERA_PITCH_RADIANS)
    base = CAMERA_DISTANCE * math.cos(CAMERA_PITCH_RADIANS)
    near = base - height / math.tan(CAMERA_PITCH_RADIANS + half)
    top_pitch = max(CAMERA_PITCH_RADIANS - half, _CAMERA_MIN_EDGE_PITCH)
    far = height / math.tan(top_pitch) - base
    return near, far


def camera_depth_bias(aspect: float = CAMERA_REFERENCE_ASPECT) -> float:
    """How far toward +Z the focus sits so the ship is centred in *depth*.

    Pointing the focus straight at the ship puts it well below the middle of
    the visible band: the top edge of the screen reaches much further across
    the plane than the bottom edge does. Offsetting the focus by half the
    difference gives the same warning above and below the hull.
    """
    near, far = camera_plane_extents(aspect)
    return (far - near) * 0.5


class CameraRig(Node3D):
    """The near top-down chase camera for the flight plane.

    Owns a :class:`Camera3D` child pitched ``CAMERA_PITCH_RADIANS`` from the
    horizontal, offset toward +Z, looking at a focus point on the plane. Three
    things decide where that focus goes:

    * the aim, by ``balance.CAMERA_AIM_LEAD_FRACTION`` of the ship-to-aim
      offset;
    * the ship's plane velocity, by :data:`CAMERA_VELOCITY_LEAD_S`, so flying
      somewhere shows you what you are flying into (the two leads together are
      clamped to :data:`CAMERA_LEAD_MAX_UNITS`);
    * :func:`camera_depth_bias`, a fixed push toward +Z that makes the warning
      above and below the hull equal.

    The vertical field of view is refreshed from :func:`camera_fov_degrees`
    every frame, so a window that is wider than 16:9 sees the same slice of
    the plane rather than a wider one.

    Usage: add as a sibling of the ship, call :meth:`set_target` once and
    :meth:`set_aim` whenever the aim point moves (the ship module does both).
    """

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self._target: Node3D | None = None
        self._aim_point: Vec3 = Vec3(0.0, PLANE_Y, 0.0)
        self._focus: Vec2 = Vec2(0.0, 0.0)
        self.camera: Camera3D | None = None

    def on_ready(self):
        self.camera = self.add_child(Camera3D(name="Camera", fov=CAMERA_FOV_DEGREES))
        self.snap()

    @property
    def focus(self) -> Vec2:
        """The flight-plane point the camera is currently looking at."""
        return self._focus

    @property
    def aspect(self) -> float:
        """The viewport's width-to-height ratio, falling back to the reference."""
        size = self.tree.screen_size if self.tree is not None else None
        if size is None:
            return CAMERA_REFERENCE_ASPECT
        width, height = float(size[0]), float(size[1])
        if width <= 0.0 or height <= 0.0:
            return CAMERA_REFERENCE_ASPECT
        return width / height

    def set_target(self, node: Node3D) -> None:
        """Follow *node*; the rig snaps to it immediately."""
        self._target = node
        self.snap()

    def snap(self) -> None:
        """Cut the camera to where the target is now, with no follow lag.

        For teleports. A warp arrival moves the hull the width of a sector in
        one frame, and a rig left to ease after it would fly the whole of that
        distance with the player watching.
        """
        self._snap()

    def set_aim(self, world_point: Vec3) -> None:
        """The world-space point the player is aiming at, on the flight plane."""
        self._aim_point = world_point

    def _lead(self, ship: Vec2) -> Vec2:
        """The combined aim and velocity lead, clamped to its ceiling."""
        aim = to_plane(self._aim_point)
        fraction = balance.CAMERA_AIM_LEAD_FRACTION
        lead_x = (float(aim.x) - float(ship.x)) * fraction
        lead_z = (float(aim.y) - float(ship.y)) * fraction
        velocity = getattr(self._target, "velocity", None)
        if velocity is not None and len(velocity) == 2:
            lead_x += float(velocity[0]) * CAMERA_VELOCITY_LEAD_S
            lead_z += float(velocity[1]) * CAMERA_VELOCITY_LEAD_S
        reach = math.hypot(lead_x, lead_z)
        if reach > CAMERA_LEAD_MAX_UNITS:
            scale = CAMERA_LEAD_MAX_UNITS / reach
            lead_x, lead_z = lead_x * scale, lead_z * scale
        return Vec2(lead_x, lead_z)

    def _desired_focus(self) -> Vec2:
        if self._target is None:
            return self._focus
        ship = to_plane(self._target.position)
        lead = self._lead(ship)
        return Vec2(
            float(ship.x) + float(lead.x),
            float(ship.y) + float(lead.y) + camera_depth_bias(self.aspect),
        )

    def _snap(self) -> None:
        self._focus = self._desired_focus()
        self._place()

    def _place(self) -> None:
        if self.camera is None:
            return
        self.camera.fov = camera_fov_degrees(self.aspect)
        fx, fz = float(self._focus.x), float(self._focus.y)
        cam_y = CAMERA_DISTANCE * math.sin(CAMERA_PITCH_RADIANS)
        cam_z = fz + CAMERA_DISTANCE * math.cos(CAMERA_PITCH_RADIANS)
        self.camera.position = Vec3(fx, cam_y, cam_z)
        self.camera.look_at(Vec3(fx, PLANE_Y, fz))

    def on_update(self, dt: float):
        desired = self._desired_focus()
        blend = 1.0 - math.exp(-CAMERA_FOLLOW_RATE * dt)
        self._focus = Vec2(
            float(self._focus.x) + (float(desired.x) - float(self._focus.x)) * blend,
            float(self._focus.y) + (float(desired.y) - float(self._focus.y)) * blend,
        )
        self._place()