shrike/modules.py

Part of SHRIKE.

"""Hull sockets, the thirty-module catalogue, and the modules that act.

Building a ship in SHRIKE is arranging it. Sockets carry positions, so the same
auto-turret is a different purchase in the bow and in the stern: a docked
turret only covers the arc its socket faces, and every unit of mass bolted on is
felt in the handling model. Three things live here:

* :class:`Socket` and :class:`SocketRack`, the positional fitting system. One
  rack per hull, one layout per hull, and every socket carries a size, so a
  reactor cannot be crammed into a bow mount meant for a sensor.
* :data:`MODULE_CATALOGUE`, all thirty launch modules with family, tier, price,
  socket size, Broker gating and pool sibling, beside :class:`ModulePool`, the
  world pool that permanently widens as the player buys rare modules.
* The modules with behaviour of their own: :class:`Refinery`, the conversion
  bet; :class:`AutoTurret`, the four deployable turret types; and
  :class:`Fabricator`, which prints ammunition from scrap. Everything else is a
  :class:`PassiveModule` publishing an effect bag the rest of the run reads.
  Power modules keep their behaviour in ``power.py`` and are fitted from here
  like anything else.
* :func:`effect_summary`, which turns any of the above into the one mechanical
  line a shop or a fit panel prints. It is derived from the effect bag and the
  behaviour tables rather than written out, so the shelf can never quote a
  number the run does not apply.

The conversion bet
==================

The Refinery is the only way to bank Cores away from a trading post, and it
prices its 30 percent premium in exactly the currencies the game is about: a
socket, a bite out of the capacitor, and noise. A batch is a
``balance.REFINERY_BATCH_CHANNEL_S`` channel drinking
``balance.ENERGY_REFINERY_PER_S`` and paying ``balance.CONVERT_RATE_REFINERY``,
started by the third rung of the interact hold. The signature burst is not
charged here: the signature meter and the notoriety tally both consume
``REFINERY_BATCH_COMPLETED``, so the batch is announced once and priced by the
systems that own those numbers.

Turrets
=======

A turret in a socket is a hull mount and covers only the arc its socket faces.
:meth:`AutoTurret.deploy` drops it in space instead, where it covers every
bearing and keeps firing after the ship has moved on. Both states draw
``balance.ENERGY_AUTO_TURRET_PER_S``, and both announce every shot as a visible
tracer, because a turret the player cannot read is a turret they cannot plan
around. A normal warp retrieves everything deployed; an emergency warp leaves
it behind, which is the price of the panic button.
"""

import math
from collections.abc import Callable, Iterable
from dataclasses import dataclass

from simvx.core import Input, Material, Mesh, MeshInstance3D, Node, Node3D, Quat, Signal, Vec2, Vec3

from . import balance
from .power import RTG, Generator, PowerSource, SignalWiring, SolarWings
from .runtime import PLANE_Y, Groups, Services, SignalNames
from .weapons import WEAPON_RACK_GROUP

# ============================================================================
# Numbers this module owns
#
# balance.py fixes the prices' tier bands, the energy draws, the batch length
# and the conversion rates. What it does not fix, and what therefore lives
# here, is the geometry of a hull's sockets, how heavy each module is, how hard
# each turret hits, and the strength of the passive effects the design names
# without numbering.
# ============================================================================

#: Socket sizes, smallest first. A socket accepts any module of its own size or
#: smaller, so a large mount is never wasted, only expensive.
SOCKET_SIZES = ("small", "medium", "large")

#: Seconds of held interact that start a Refinery batch; the first rung of the
#: same hold patches a breach and belongs to ``ship.py``.
REFINERY_INTERACT_HOLD_S = 3.0

#: Scrap consumed by one Refinery batch. A batch is deliberately smaller than a
#: sector's haul so refining a full hold is several bursts of noise rather than
#: one, and the player can stop between them.
REFINERY_BATCH_SCRAP = 40.0

#: How long a turret's tracer stays on screen. Long enough to read the intent,
#: short enough that four turrets do not become a light show.
TURRET_TRACER_S = 0.07
#: Player fire is warm gold and white, turrets included.
TRACER_COLOUR = (1.0, 0.86, 0.55, 1.0)
TRACER_RADIUS = 0.06

#: Reference mass of a bare starter hull, the denominator of the handling
#: penalty, and the floor that penalty is clamped to.
HULL_REFERENCE_MASS = 12.0
MIN_HANDLING_MULTIPLIER = 0.6


def _wrap_angle(radians: float) -> float:
    """Fold an angle into ``[-pi, pi)``."""
    return (radians + math.pi) % (2.0 * math.pi) - math.pi


# ============================================================================
# Sockets
# ============================================================================


@dataclass(frozen=True, eq=False)
class Socket:
    """One external mounting point on the hull.

    ``offset`` is the plane offset from the hull centre in the ship's own
    frame, where the nose runs along local -Z and starboard along local +X, the
    same convention the weapon hardpoints use. :attr:`bearing` turns that
    offset into the direction the socket faces relative to the nose, which is
    what makes a bow turret and a stern turret different purchases.
    """

    index: int
    offset: Vec2
    size: str
    label: str = ""

    @property
    def bearing(self) -> float:
        """Direction the socket faces, radians anticlockwise from the nose."""
        return _wrap_angle(math.atan2(-float(self.offset.y), float(self.offset.x)) - math.pi * 0.5)

    def accepts(self, size: str) -> bool:
        """Whether a module of *size* fits this mount."""
        return SOCKET_SIZES.index(size) <= SOCKET_SIZES.index(self.size)

    def local_position(self) -> Vec3:
        """The socket's position in the hull's local frame, on the flight plane."""
        return Vec3(float(self.offset.x), PLANE_Y, float(self.offset.y))


def _layout(*entries: tuple[float, float, str, str]) -> tuple[Socket, ...]:
    """Build a hull's socket tuple from ``(x, z, size, label)`` rows."""
    return tuple(Socket(i, Vec2(x, z), size, label) for i, (x, z, size, label) in enumerate(entries))


#: One layout per hull in ``balance.HULL_SOCKETS``. The counts are balance's;
#: the positions and sizes are this module's, and they are what gives each hull
#: its character: the Vagrant is symmetrical, the Barge carries two extra large
#: waist mounts, the Dart is bow-heavy and small, the Hive is built around two
#: large bays amidships.
HULL_SOCKET_LAYOUTS: dict[str, tuple[Socket, ...]] = {
    "vagrant": _layout(
        (0.0, -1.7, "large", "bow"),
        (-0.9, -0.9, "small", "port bow"),
        (0.9, -0.9, "small", "starboard bow"),
        (-1.1, 0.7, "medium", "port quarter"),
        (1.1, 0.7, "medium", "starboard quarter"),
        (0.0, 1.6, "large", "stern"),
    ),
    "barge": _layout(
        (0.0, -1.9, "large", "bow"),
        (-1.0, -1.0, "small", "port bow"),
        (1.0, -1.0, "small", "starboard bow"),
        (-1.5, -0.1, "large", "port waist"),
        (1.5, -0.1, "large", "starboard waist"),
        (-1.2, 0.9, "medium", "port quarter"),
        (1.2, 0.9, "medium", "starboard quarter"),
        (0.0, 1.8, "large", "stern"),
    ),
    "dart": _layout(
        (0.0, -1.5, "medium", "bow"),
        (-0.7, -0.6, "small", "port bow"),
        (0.7, -0.6, "small", "starboard bow"),
        (0.0, 1.3, "medium", "stern"),
    ),
    "hive": _layout(
        (0.0, -1.6, "medium", "bow"),
        (-1.3, -0.2, "large", "port bay"),
        (1.3, -0.2, "large", "starboard bay"),
        (-1.0, 0.8, "small", "port quarter"),
        (1.0, 0.8, "small", "starboard quarter"),
        (0.0, 1.7, "large", "stern"),
    ),
}


def sockets_for_hull(hull_id: str) -> tuple[Socket, ...]:
    """The socket layout of a hull, by the ids in ``balance.HULL_SOCKETS``."""
    try:
        return HULL_SOCKET_LAYOUTS[hull_id]
    except KeyError:
        raise ValueError(f"unknown hull {hull_id!r}; expected one of {sorted(HULL_SOCKET_LAYOUTS)}") from None


# ============================================================================
# The catalogue
# ============================================================================

#: Price band per tier, the design's module price curve.
PRICE_BANDS: dict[int, tuple[int, int]] = {
    1: (balance.MODULE_PRICE_TIER1_MIN, balance.MODULE_PRICE_TIER1_MAX),
    2: (balance.MODULE_PRICE_TIER2_MIN, balance.MODULE_PRICE_TIER2_MAX),
    3: (balance.MODULE_PRICE_TIER3_MIN, balance.MODULE_PRICE_TIER3_MAX),
}


def price_band(tier: int) -> tuple[int, int]:
    """The scrap price band a tier's modules are priced inside."""
    return PRICE_BANDS[tier]


def _module(
    family: str,
    tier: int,
    price: int,
    socket_size: str,
    mass: float,
    *,
    broker: bool = False,
    pool_sibling: str = "",
    locked: bool = False,
    effects: dict[str, float] | None = None,
    note: str = "",
) -> dict:
    """One catalogue row.

    ``pool_sibling`` names the module this one's first purchase adds to the
    world pool, empty when it adds nothing; ``locked`` marks a module that
    starts outside that pool and can only arrive through its sibling.
    ``effects`` is the bag passive modules publish to the rest of the run.
    """
    return {
        "family": family,
        "tier": tier,
        "price": price,
        "price_band": PRICE_BANDS[tier],
        "socket_size": socket_size,
        "mass": mass,
        "broker_exclusive": broker,
        "pool_sibling": pool_sibling,
        "locked": locked,
        "effects": dict(effects or {}),
        "note": note,
    }


#: All thirty launch modules. Eight are Broker exclusives, gated on notoriety
#: rather than on the pool; eight more start outside the pool entirely and are
#: added to it for good the first time their sibling is bought.
MODULE_CATALOGUE: dict[str, dict] = {
    # -- auto-turrets (4) ---------------------------------------------------
    "sentry_turret": _module(
        "turret", 1, 45, "small", 0.6, pool_sibling="flak_turret", note="steady kinetic tracer, the first turret"
    ),
    "flak_turret": _module("turret", 2, 95, "small", 0.8, locked=True, note="bursts, eats shoals"),
    "lance_turret": _module(
        "turret", 2, 130, "medium", 1.1, pool_sibling="arc_turret", note="long reach, narrow arc, one heavy shot"
    ),
    "arc_turret": _module("turret", 3, 190, "medium", 1.0, locked=True, note="close-range energy lash, widest arc"),
    # -- shield emitters (3) ------------------------------------------------
    "emitter_vane": _module(
        "shield", 1, 50, "small", 0.5, pool_sibling="emitter_bank", effects={"shield_arc_bonus_degrees": 30.0}
    ),
    "emitter_bank": _module(
        "shield",
        2,
        110,
        "medium",
        0.9,
        pool_sibling="bubble_emitter",
        locked=True,
        effects={"shield_absorb_bonus": 30.0},
    ),
    "bubble_emitter": _module(
        "shield",
        3,
        230,
        "large",
        1.6,
        locked=True,
        effects={"shield_arc_bonus_degrees": 240.0, "shield_energy_mult": balance.SHIELD_BUBBLE_ENERGY_MULT},
        note="the arc closes toward a bubble at triple energy cost",
    ),
    # -- power (3); behaviour lives in power.py -----------------------------
    "solar_wings": _module("power", 1, 55, "large", 1.2, note="silent, fragile, geography-dependent"),
    "generator": _module("power", 1, 60, "large", 1.8, note="strong anywhere, burns fuel, hums"),
    "rtg": _module("power", 1, balance.RTG_PRICE_SCRAP, "medium", 1.0, note="a trickle that survives silent running"),
    # -- manufacturing ------------------------------------------------------
    "refinery": _module(
        "refinery", 2, 120, "large", 2.0, pool_sibling="fabricator", note="the conversion bet, 1.3 Cores per 10 scrap"
    ),
    "fabricator": _module(
        "fabricator",
        2,
        100,
        "medium",
        1.2,
        pool_sibling="drone_bay",
        locked=True,
        note="scrap to ammunition",
    ),
    "drone_bay": _module("drone", 3, 210, "large", 1.7, locked=True, effects={"drones": 2.0}, note="two escorts"),
    # -- salvage and handling ----------------------------------------------
    "cargo_scoop": _module("scoop", 1, 40, "small", 0.4, effects={"scoop_range_mult": 1.5}),
    "ram_scoop": _module(
        "scoop",
        2,
        115,
        "medium",
        1.0,
        locked=True,
        effects={"scoop_range_mult": 1.5, "ram_collect": 1.0},
        note="afterburning through wreckage collects it",
    ),
    "grav_anchor": _module("handling", 2, 90, "medium", 1.4, effects={"knockback_taken_mult": 0.5}),
    "afterburner_injectors": _module(
        "handling",
        1,
        50,
        "medium",
        0.7,
        pool_sibling="ram_scoop",
        effects={"afterburner_speed_mult": 1.15, "afterburner_energy_mult": 0.85},
    ),
    # -- damage control -----------------------------------------------------
    "breach_foam": _module(
        "repair", 1, 35, "small", 0.3, effects={"patch_channel_mult": 0.5}, note="halves the rooted patch"
    ),
    # -- signature and sensors ----------------------------------------------
    "signature_dampener": _module(
        "signature", 1, 55, "small", 0.5, pool_sibling="wake_damper", effects={"signature_mult": 0.92}
    ),
    "wake_damper": _module(
        "signature",
        2,
        105,
        "medium",
        0.9,
        locked=True,
        effects={
            "signature_mult": balance.WAKE_DAMPER_SIGNATURE_MULT,
            "mining_speed_mult": balance.WAKE_DAMPER_MINING_SPEED_MULT,
        },
    ),
    "sensor_mast": _module(
        "sensor", 1, 45, "medium", 0.4, effects={"chart_tag_jumps": float(balance.SENSOR_MAST_CHART_TAG_JUMPS)}
    ),
    # -- quill-tech ---------------------------------------------------------
    "mirror_lantern": _module(
        "quill_tech",
        3,
        260,
        "large",
        1.5,
        effects={"lantern_blind_s": balance.MIRROR_LANTERN_BLIND_S},
        note="built from spare quills; blinds the Shrike for a punish window",
    ),
    # -- Broker exclusives (8, all tier 3) ----------------------------------
    "null_shroud": _module("signature", 3, 245, "medium", 1.1, broker=True, effects={"signature_mult": 0.70}),
    "singularity_hook": _module("scoop", 3, 215, "medium", 1.3, broker=True, effects={"scoop_range_mult": 3.0}),
    "overcharge_cell": _module(
        "power", 3, 235, "large", 1.9, broker=True, effects={"capacitor_max": balance.CAPACITOR_MAX_UPGRADED}
    ),
    "quill_rail_feed": _module(
        "quill_tech", 3, 250, "medium", 1.2, broker=True, effects={"ballistic_damage_mult": 1.25}
    ),
    "phase_plating": _module("armour", 3, 230, "large", 2.4, broker=True, effects={"damage_taken_mult": 0.85}),
    "swarm_lattice": _module("drone", 3, 260, "large", 2.0, broker=True, effects={"drones": 4.0}),
    "deep_lens": _module("sensor", 3, 185, "small", 0.5, broker=True, effects={"chart_tag_jumps": 4.0}),
    "lantern_baffle": _module("armour", 3, 205, "medium", 1.4, broker=True, effects={"lantern_damage_mult": 0.5}),
}


def module_spec(module_id: str) -> dict:
    """One catalogue row, or a ``ValueError`` naming the unknown module."""
    try:
        return MODULE_CATALOGUE[module_id]
    except KeyError:
        raise ValueError(f"unknown module id {module_id!r}") from None


def pool_sibling_pairs() -> list[tuple[str, str]]:
    """Every ``(purchase, unlocked sibling)`` pair, in catalogue order."""
    return [(mid, spec["pool_sibling"]) for mid, spec in MODULE_CATALOGUE.items() if spec["pool_sibling"]]


# ============================================================================
# Saying what a module does
#
# A shelf that prices a module owes the pilot the number it is charging for.
# "keeps the meter quieter for longer" is a mood; "signature fill -8 percent"
# is a purchase decision, and it is the same number the meter actually applies.
# Every phrase below is derived from the effect bag or from this module's own
# behaviour tables, so a rebalance moves the shelf text with it.
# ============================================================================


def _percent_less(value: float) -> str:
    """A multiplier below 1 as the reduction it is: 0.92 to "-8 percent"."""
    return f"-{(1.0 - float(value)) * 100.0:.0f} percent"


def _percent_more(value: float) -> str:
    """A multiplier above 1 as the gain it is: 1.15 to "+15 percent"."""
    return f"+{(float(value) - 1.0) * 100.0:.0f} percent"


def _times(value: float) -> str:
    """A multiplier written as a multiplier, for the ones that are not deltas."""
    text = f"{float(value):.2f}".rstrip("0").rstrip(".")
    return f"x{text}"


#: One phrase per effect key. The key is the same string the systems query off
#: :meth:`SocketRack.effect_multiplier`, so an effect that gains a phrase here
#: and no consumer, or a consumer and no phrase, is visible as a gap.
EFFECT_PHRASINGS: dict[str, Callable[[float], str]] = {
    "signature_mult": lambda v: f"signature fill {_percent_less(v)}",
    "shield_arc_bonus_degrees": lambda v: f"shield arc +{v:.0f} degrees",
    "shield_absorb_bonus": lambda v: f"shield soaks +{v:.0f} damage",
    "shield_energy_mult": lambda v: f"shield energy {_times(v)}",
    "scoop_range_mult": lambda v: f"scoop reach {_percent_more(v)}",
    "ram_collect": lambda v: "afterburning through wreckage collects it",
    "knockback_taken_mult": lambda v: f"knockback taken {_percent_less(v)}",
    "afterburner_speed_mult": lambda v: f"afterburner speed {_percent_more(v)}",
    "afterburner_energy_mult": lambda v: f"afterburner energy {_percent_less(v)}",
    "patch_channel_mult": lambda v: f"breach patch {_percent_less(v)} time",
    "mining_speed_mult": lambda v: f"mining speed {_percent_less(v)}",
    "chart_tag_jumps": lambda v: f"chart tags {v:.0f} jumps ahead",
    "lantern_blind_s": lambda v: f"blinds the lantern for {v:.0f} s",
    "capacitor_max": lambda v: f"capacitor max {v:.0f}",
    "ballistic_damage_mult": lambda v: f"ballistic damage {_percent_more(v)}",
    "damage_taken_mult": lambda v: f"damage taken {_percent_less(v)}",
    "lantern_damage_mult": lambda v: f"lantern damage {_percent_less(v)}",
    "drones": lambda v: f"{v:.0f} escort drones",
}


def _turret_effect(module_id: str) -> str:
    """A turret's numbers: what it hits for, how far, and how wide it covers."""
    profile = TURRET_PROFILES[module_id]
    return (
        f"{profile.dps:.0f} DPS auto, {profile.reach:.0f} reach, "
        f"{profile.arc_degrees:.0f} deg arc, {balance.ENERGY_AUTO_TURRET_PER_S:.1f} energy/s"
    )


#: Modules whose behaviour is code rather than an effect bag. Each says what it
#: pays out and what it costs, in the units the run's own meters use.
BEHAVIOUR_EFFECTS: dict[str, Callable[[], str]] = {
    "solar_wings": lambda: f"+{balance.SOLAR_OUTPUT_PER_S:.0f} energy/s in the open, none in nebula, silent",
    "generator": lambda: (
        f"+{balance.GENERATOR_OUTPUT_PER_S:.0f} energy/s, burns fuel, "
        f"+{balance.GENERATOR_SIGNATURE_PER_S:.1f} signature/s"
    ),
    "rtg": lambda: f"+{balance.RTG_OUTPUT_PER_S:.0f} energy/s, survives silent running",
    "refinery": lambda: (
        f"{REFINERY_BATCH_SCRAP:.0f} scrap to Cores at {balance.CONVERT_RATE_REFINERY:.1f} per 10, "
        f"{balance.REFINERY_BATCH_CHANNEL_S:.0f} s, +{balance.SIGNATURE_REFINERY_BATCH:.0f} signature"
    ),
    "fabricator": lambda: f"{balance.FABRICATOR_SCRAP_PER_BOX:.0f} scrap prints one ammo box",
}


def effect_summary(module_id: str) -> str:
    """What *module_id* does, in numbers, on one line.

    The effect bag is read first because it is what the run actually applies;
    a module whose behaviour is code answers from :data:`BEHAVIOUR_EFFECTS`.
    The catalogue note is a fallback and nothing more: where numbers exist they
    say the same thing in fewer words, and a row that printed both would be
    half prose on a screen with a fixed width.
    """
    spec = module_spec(module_id)
    if module_id in TURRET_PROFILES:
        parts = [_turret_effect(module_id)]
    elif module_id in BEHAVIOUR_EFFECTS:
        parts = [BEHAVIOUR_EFFECTS[module_id]()]
    else:
        parts = [EFFECT_PHRASINGS[key](value) for key, value in spec["effects"].items() if key in EFFECT_PHRASINGS]
    parts = [part for part in parts if part]
    return ", ".join(parts) if parts else str(spec["note"])


def socket_label(module_id: str) -> str:
    """The mount a module needs, for a shelf row that has no live hull to ask."""
    return f"{module_spec(module_id)['socket_size']} socket"


class ModulePool:
    """The set of modules the world may offer, and how it permanently widens.

    Buying a module that names a ``pool_sibling`` adds that sibling to the pool
    for good, so shops get more interesting exactly as the player gets better.
    Expansions persist in the meta profile; Broker exclusives are not part of
    this system, being gated on notoriety instead.
    """

    #: Profile key the expansions are stored under.
    PROFILE_KEY = "module_pool_expansions"

    def __init__(self, expansions: Iterable[str] = ()):
        self.expansions: set[str] = {mid for mid in expansions if mid in MODULE_CATALOGUE}

    def unlocked(self, module_id: str) -> bool:
        """Whether *module_id* may appear in stock at all."""
        spec = module_spec(module_id)
        return not spec["locked"] or module_id in self.expansions

    def available(self, *, notoriety: int = 0) -> list[str]:
        """Every module a depot may stock right now, in catalogue order.

        Broker exclusives join the list once the ship is notorious enough for
        the barge to show itself; the depots themselves filter further.
        """
        broker_open = notoriety >= balance.BROKER_NOTORIETY_THRESHOLD
        return [
            mid
            for mid, spec in MODULE_CATALOGUE.items()
            if self.unlocked(mid) and (broker_open or not spec["broker_exclusive"])
        ]

    def record_purchase(self, module_id: str) -> str | None:
        """Bank a purchase; returns the sibling it just added to the pool, if any."""
        sibling = module_spec(module_id)["pool_sibling"]
        if not sibling or sibling in self.expansions:
            return None
        self.expansions.add(sibling)
        return sibling

    def to_profile(self) -> list[str]:
        """The expansions, sorted, ready to be written into the profile."""
        return sorted(self.expansions)

    @classmethod
    def from_profile(cls, profile: dict) -> ModulePool:
        """Rebuild the pool from a saved profile, tolerating an absent key."""
        return cls(profile.get(cls.PROFILE_KEY, ()))


# ============================================================================
# Module nodes
# ============================================================================

#: Family colours, so a glance at the hull says what is bolted to it.
FAMILY_COLOURS: dict[str, tuple[float, float, float, float]] = {
    "turret": (0.82, 0.74, 0.55, 1.0),
    "shield": (0.45, 0.70, 0.95, 1.0),
    "power": (0.95, 0.80, 0.35, 1.0),
    "refinery": (0.95, 0.55, 0.30, 1.0),
    "fabricator": (0.70, 0.72, 0.78, 1.0),
    "drone": (0.60, 0.85, 0.70, 1.0),
    "scoop": (0.65, 0.70, 0.75, 1.0),
    "handling": (0.72, 0.66, 0.60, 1.0),
    "repair": (0.85, 0.85, 0.80, 1.0),
    "signature": (0.35, 0.40, 0.50, 1.0),
    "sensor": (0.55, 0.80, 0.85, 1.0),
    "quill_tech": (0.85, 0.60, 0.90, 1.0),
    "armour": (0.60, 0.62, 0.66, 1.0),
}

#: Mesh size a module of each socket size is drawn at.
MODULE_VISUAL_SIZE = {"small": 0.32, "medium": 0.45, "large": 0.62}

#: Group the socket rack joins, so a depot can ask a live hull what it is
#: carrying without walking the tree by node name. The weapon rack publishes
#: itself the same way through ``weapons.WEAPON_RACK_GROUP``.
SOCKET_RACK_GROUP = "socket_rack"


class ShipModule(Node3D):
    """Base for anything bolted into a socket.

    A module knows its catalogue row and the socket it sits in, and reaches the
    run's systems through the service singletons rather than through its
    parents, so it behaves the same on a hull, on a test harness, or dropped in
    space.
    """

    def __init__(self, module_id: str, **kwargs):
        spec = module_spec(module_id)
        kwargs.setdefault("name", module_id)
        super().__init__(**kwargs)
        self.module_id = module_id
        self.spec = spec
        self.socket: Socket | None = None
        self.rack: SocketRack | None = None

    # -- description ------------------------------------------------------

    @property
    def family(self) -> str:
        return self.spec["family"]

    @property
    def mass(self) -> float:
        return float(self.spec["mass"])

    @property
    def effects(self) -> dict[str, float]:
        """The passive effect bag other systems read off the rack."""
        return self.spec["effects"]

    # -- lifecycle --------------------------------------------------------

    def on_ready(self):
        self.add_child(self._build_visual())

    def _build_visual(self) -> Node3D:
        colour = FAMILY_COLOURS.get(self.family, (0.7, 0.7, 0.7, 1.0))
        size = MODULE_VISUAL_SIZE[self.spec["socket_size"]]
        return MeshInstance3D(
            name="Casing",
            mesh=Mesh.cube(size=size),
            material=Material(colour=colour, metallic=0.7, roughness=0.4),
        )

    def on_removed(self) -> None:
        """Undo anything the module did to the run. Called before it is freed."""

    # -- services ---------------------------------------------------------

    def power(self):
        """The run's power system, or None before one is registered."""
        tree = self.tree
        return None if tree is None else tree.singletons.get(Services.POWER)

    def economy(self):
        """The run's scrap and Cores ledger, or None outside a run."""
        tree = self.tree
        return None if tree is None else tree.singletons.get(Services.ECONOMY)

    def ship(self) -> Node3D | None:
        """The hull this module belongs to, or None while it is not fitted."""
        return None if self.rack is None else self.rack.ship()


class PassiveModule(ShipModule):
    """A module whose whole behaviour is the effect bag it publishes.

    Most of the catalogue is passive: plating, scoops, injectors, sensors. The
    rack aggregates their effects and the systems that care read them from
    there. The one effect a passive module applies itself is the signature
    multiplier, because the meter owns a register for exactly this and applying
    it anywhere else would double-count it.
    """

    def __init__(self, module_id: str, **kwargs):
        super().__init__(module_id, **kwargs)
        self._signature_applied = False

    @property
    def signature_source(self) -> str:
        """The meter register this module writes to.

        Keyed by socket as well as by module, so a second dampener in a second
        socket stacks with the first instead of overwriting it.
        """
        socket = 0 if self.socket is None else self.socket.index
        return f"module:{self.module_id}:{socket}"

    def on_update(self, dt: float):
        if not self._signature_applied and "signature_mult" in self.effects:
            meter = self._meter()
            if meter is not None:
                meter.set_gain_multiplier(self.signature_source, float(self.effects["signature_mult"]))
                self._signature_applied = True

    def on_removed(self) -> None:
        if not self._signature_applied:
            return
        meter = self._meter()
        if meter is not None:
            meter.set_gain_multiplier(self.signature_source, 1.0)
        self._signature_applied = False

    def _meter(self):
        tree = self.tree
        return None if tree is None else tree.singletons.get(Services.SIGNATURE)


# ============================================================================
# The Refinery
# ============================================================================


class Refinery(ShipModule):
    """The conversion bet, socketed: scrap into Cores anywhere, loudly.

    A batch is a channel, not an instant: :meth:`begin_batch` reserves up to
    :data:`REFINERY_BATCH_SCRAP` and runs for ``balance.REFINERY_BATCH_CHANNEL_S``
    while paying ``balance.ENERGY_REFINERY_PER_S``. A capacitor that cannot keep
    up aborts the batch with the scrap untouched, which is the whole point: the
    flak cannon and the smelter draw from the same hundred points.

    The player starts a batch by holding the interact action for
    :data:`REFINERY_INTERACT_HOLD_S`, the last rung of the interact ladder;
    ``ship.py`` owns the patch rung earlier in the same hold and neither blocks
    the other.
    """

    #: Registered as ``SignalNames.REFINERY_BATCH_STARTED`` / ``_COMPLETED``.
    refinery_batch_started = Signal()
    refinery_batch_completed = Signal(float)

    def __init__(self, module_id: str = "refinery", **kwargs):
        super().__init__(module_id, **kwargs)
        self._remaining = 0.0
        self._batch_scrap = 0.0
        self._hold = 0.0
        self._hold_consumed = False

    # -- reading ----------------------------------------------------------

    @property
    def running(self) -> bool:
        """Whether a batch is in the smelter right now."""
        return self._remaining > 0.0

    @property
    def batch_scrap(self) -> float:
        """Scrap the running batch will convert, zero when idle."""
        return self._batch_scrap

    def batch_fraction(self) -> float:
        """Progress of the running batch, 0 to 1, for the HUD's radial fill."""
        if not self.running:
            return 0.0
        return 1.0 - self._remaining / balance.REFINERY_BATCH_CHANNEL_S

    def hold_fraction(self) -> float:
        """Progress of the interact hold toward starting a batch, 0 to 1."""
        return min(1.0, self._hold / REFINERY_INTERACT_HOLD_S)

    # -- driving ----------------------------------------------------------

    def begin_batch(self) -> bool:
        """Load the smelter and start the channel. False if it cannot start."""
        if self.running:
            return False
        economy = self.economy()
        if economy is None or self.power() is None:
            return False
        loaded = min(REFINERY_BATCH_SCRAP, float(getattr(economy, "scrap", 0.0)))
        if loaded <= 0.0:
            return False
        self._batch_scrap = loaded
        self._remaining = balance.REFINERY_BATCH_CHANNEL_S
        self.refinery_batch_started()
        return True

    def cancel_batch(self) -> None:
        """Abandon the running batch. The scrap was never spent, so it stays."""
        self._remaining = 0.0
        self._batch_scrap = 0.0

    def on_update(self, dt: float):
        self._tick_hold(dt)
        if self.running:
            self._tick_batch(dt)

    # -- internals --------------------------------------------------------

    def _tick_hold(self, dt: float) -> None:
        if not Input.is_action_pressed("interact"):
            self._hold = 0.0
            self._hold_consumed = False
            return
        self._hold += dt
        if self._hold_consumed or self._hold < REFINERY_INTERACT_HOLD_S:
            return
        if self.begin_batch():
            self._hold_consumed = True

    def _tick_batch(self, dt: float) -> None:
        power = self.power()
        if power is None or not power.drain(balance.ENERGY_REFINERY_PER_S, dt, "refinery"):
            self.cancel_batch()
            return
        self._remaining -= dt
        if self._remaining > 0.0:
            return
        self._complete()

    def _complete(self) -> None:
        economy = self.economy()
        converted = self._batch_scrap
        self._remaining = 0.0
        self._batch_scrap = 0.0
        if economy is None:
            return
        converted = min(converted, float(getattr(economy, "scrap", 0.0)))
        if converted <= 0.0:
            return
        cores = economy.convert(converted, balance.CONVERT_RATE_REFINERY)
        if cores is None:
            cores = balance.cores_from_scrap(converted, balance.CONVERT_RATE_REFINERY)
        # The signature burst and the notoriety are charged by the meter and the
        # bounty tally off this signal; announcing it twice would price it twice.
        self.refinery_batch_completed(float(cores))


# ============================================================================
# Auto-turrets
# ============================================================================


@dataclass(frozen=True)
class TurretProfile:
    """How one turret type shoots. Cadence, reach and arc are feel numbers."""

    dps: float
    reach: float
    rate: float
    arc_degrees: float
    kind: str = "ballistic"
    note: str = ""


#: The four turret types. Every one draws ``balance.ENERGY_AUTO_TURRET_PER_S``;
#: what they buy with it is reach, cadence and coverage.
TURRET_PROFILES: dict[str, TurretProfile] = {
    "sentry_turret": TurretProfile(14.0, 22.0, 3.0, 180.0, note="the dependable one"),
    "flak_turret": TurretProfile(26.0, 16.0, 5.0, 200.0, note="short bursts into shoals"),
    "lance_turret": TurretProfile(22.0, 34.0, 1.0, 140.0, note="reaches across the arena, hates being flanked"),
    "arc_turret": TurretProfile(30.0, 14.0, 6.0, 260.0, kind="energy", note="close lash, nearly all-round"),
}


class AutoTurret(ShipModule):
    """A socketed turret that finds its own targets, docked or deployed.

    Docked, it is a hull mount: it covers only the arc its socket faces, so
    where it is bought matters as much as which one. :meth:`deploy` drops it in
    space, where it covers every bearing and holds the ground the ship has left.
    Either way it pays ``balance.ENERGY_AUTO_TURRET_PER_S`` and draws a tracer
    for every shot, so the player can read what it is doing without watching it.
    """

    #: ``(module_id)`` on every shot. Local to this module; the HUD and the
    #: audio director read it off the turret they are watching.
    turret_fired = Signal(str)

    def __init__(self, module_id: str, **kwargs):
        super().__init__(module_id, **kwargs)
        self.profile = TURRET_PROFILES[module_id]
        self.deployed = False
        self._cooldown = 0.0
        self._tracer: Node3D | None = None
        self._tracer_mesh: MeshInstance3D | None = None
        self._tracer_left = 0.0

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

    # -- deployment -------------------------------------------------------

    def deploy(self) -> bool:
        """Drop the turret where the ship is standing. False if already out."""
        if self.deployed or self.rack is None:
            return False
        anchor = self.world_position
        host = self.rack.deployment_host()
        if host is None:
            return False
        self.reparent(host)
        self.world_position = Vec3(float(anchor[0]), PLANE_Y, float(anchor[2]))
        self.deployed = True
        return True

    def retrieve(self) -> bool:
        """Take the turret back into its socket. False if it was never out."""
        if not self.deployed or self.rack is None or self.socket is None:
            return False
        self.reparent(self.rack)
        self.position = self.socket.local_position()
        self.deployed = False
        return True

    def on_removed(self) -> None:
        self.deployed = False

    # -- coverage ---------------------------------------------------------

    @property
    def coverage_degrees(self) -> float:
        """Width of the arc the turret can shoot into."""
        return 360.0 if self.deployed else self.profile.arc_degrees

    def coverage_centre(self) -> float:
        """World heading the arc is centred on, radians anticlockwise from +X."""
        if self.deployed or self.socket is None:
            return 0.0
        ship = self.ship()
        heading = float(getattr(ship, "heading", 0.0)) if ship is not None else 0.0
        return _wrap_angle(heading + self.socket.bearing)

    def covers(self, world_point) -> bool:
        """Whether the turret can bring its guns to bear on a plane point."""
        if self.deployed:
            return True
        origin = self.world_position
        dx = float(world_point[0]) - float(origin[0])
        dz = float(world_point[2]) - float(origin[2])
        if math.hypot(dx, dz) < 1e-6:
            return True
        offset = abs(_wrap_angle(math.atan2(-dz, dx) - self.coverage_centre()))
        return offset <= math.radians(self.coverage_degrees) * 0.5

    # -- firing -----------------------------------------------------------

    @property
    def damage_per_shot(self) -> float:
        """DPS spread evenly across a second of cadence."""
        return self.profile.dps / self.profile.rate

    def on_update(self, dt: float):
        self._tick_tracer(dt)
        self._cooldown = max(0.0, self._cooldown - dt)
        power = self.power()
        if power is None or not power.drain(balance.ENERGY_AUTO_TURRET_PER_S, dt, "auto_turret"):
            return
        if self._cooldown > 0.0:
            return
        target = self.acquire()
        if target is None:
            return
        self._cooldown = 1.0 / self.profile.rate
        self._fire(target)

    def acquire(self) -> Node3D | None:
        """The nearest hostile in reach and inside the arc, or None."""
        tree = self.tree
        if tree is None:
            return None
        origin = self.world_position
        best: Node3D | None = None
        best_distance = self.profile.reach
        for group in (Groups.ENEMIES, Groups.HUNTER):
            for node in tree.group(group):
                if not isinstance(node, Node3D) or node.destroying:
                    continue
                position = node.world_position
                distance = math.hypot(float(position[0]) - float(origin[0]), float(position[2]) - float(origin[2]))
                if distance > best_distance or not self.covers(position):
                    continue
                best, best_distance = node, distance
        return best

    def _fire(self, target: Node3D) -> None:
        origin, position = self.world_position, target.world_position
        dx = float(position[0]) - float(origin[0])
        dz = float(position[2]) - float(origin[2])
        length = math.hypot(dx, dz)
        direction = Vec3(dx / length, 0.0, dz / length) if length > 1e-6 else Vec3(1.0, 0.0, 0.0)
        self._show_tracer(direction, length)
        self.turret_fired(self.module_id)
        tree = self.tree
        router = tree.singletons.get(Services.DAMAGE) if tree is not None else None
        if router is not None:
            router.deal(target, self.damage_per_shot, kind=self.profile.kind, direction=direction)

    def _show_tracer(self, direction: Vec3, length: float) -> None:
        if self._tracer is None:
            self._tracer = self.add_child(Node3D(name="Tracer"))
            self._tracer_mesh = self._tracer.add_child(
                MeshInstance3D(
                    name="Line",
                    mesh=Mesh.cylinder(radius=TRACER_RADIUS, height=1.0, segments=6),
                    material=Material(colour=TRACER_COLOUR, emissive_colour=TRACER_COLOUR[:3], emissive_strength=4.0),
                    rotation=Quat.from_euler(math.radians(90.0), 0.0, 0.0),
                )
            )
        self._tracer.visible = True
        self._tracer.face_along(direction)
        self._tracer_mesh.position = Vec3(0.0, 0.0, -length * 0.5)
        self._tracer_mesh.scale = Vec3(1.0, max(length, 1e-3), 1.0)
        self._tracer_left = TURRET_TRACER_S

    def _tick_tracer(self, dt: float) -> None:
        if self._tracer_left <= 0.0:
            return
        self._tracer_left -= dt
        if self._tracer_left <= 0.0 and self._tracer is not None:
            self._tracer.visible = False


# ============================================================================
# The Fabricator
# ============================================================================


class Fabricator(ShipModule):
    """Prints ammunition from scrap, joining the two economies at a price.

    ``balance.FABRICATOR_SCRAP_PER_BOX`` of scrap becomes one box on the weapon
    rack, half what a depot charges, which is what lets a ballistic build stay
    fed between posts without ever docking.
    """

    def weapon_rack(self):
        """The ship's weapon rack, or None if nothing is fitted yet."""
        tree = self.tree
        if tree is None:
            return None
        racks = tree.group(WEAPON_RACK_GROUP)
        return racks[0] if racks else None

    def craftable(self) -> list[str]:
        """Weapon ids this module can print boxes for."""
        return [wid for wid, spec in balance.WEAPONS.items() if spec.family == "ballistic"]

    def craft(self, weapon_id: str) -> bool:
        """Buy one ammo box for *weapon_id*. False if the scrap or rack is missing."""
        if weapon_id not in self.craftable():
            raise ValueError(f"{weapon_id!r} is not a ballistic weapon; nothing to print")
        rack = self.weapon_rack()
        economy = self.economy()
        if rack is None or economy is None:
            return False
        if not economy.spend_scrap(balance.FABRICATOR_SCRAP_PER_BOX):
            return False
        rack.add_ammo_box(weapon_id)
        return True


# ============================================================================
# Building modules
# ============================================================================

#: Power modules keep their behaviour in ``power.py``; the catalogue fits them.
POWER_CLASSES: dict[str, type[PowerSource]] = {
    "solar_wings": SolarWings,
    "generator": Generator,
    "rtg": RTG,
}

#: Modules with behaviour of their own, by id. Everything else is passive.
SPECIAL_CLASSES: dict[str, type[ShipModule]] = {
    "refinery": Refinery,
    "fabricator": Fabricator,
}


def make_module(module_id: str, **kwargs) -> Node3D:
    """Build the node for a catalogue id, picking the class by family."""
    spec = module_spec(module_id)
    power_class = POWER_CLASSES.get(module_id)
    if power_class is not None:
        kwargs.setdefault("name", module_id)
        node = power_class(**kwargs)
        node.module_id = module_id
        return node
    if spec["family"] == "turret":
        return AutoTurret(module_id, **kwargs)
    special = SPECIAL_CLASSES.get(module_id)
    if special is not None:
        return special(module_id, **kwargs)
    return PassiveModule(module_id, **kwargs)


# ============================================================================
# The rack
# ============================================================================


class SocketRack(Node3D):
    """The hull's external sockets and everything bolted into them.

    The rack is the one place a module is fitted or stripped, so it is also the
    one place the consequences are applied: the power system rediscovers its
    sources, the handling model learns the new mass, and the aggregate effect
    bag other systems read is recomputed from what is actually installed.

    It also owns the turret contract across a warp. A normal warp retrieves
    every deployed turret; an emergency warp abandons them, which is what the
    1.5x fuel price on the panic button is buying you out of.
    """

    #: ``(module_id, socket_index)`` on every fitting change.
    module_installed = Signal(str, int)
    module_removed = Signal(str, int)

    def __init__(self, hull_id: str = "vagrant", **kwargs):
        kwargs.setdefault("name", "Sockets")
        super().__init__(**kwargs)
        self.hull_id = hull_id
        self.sockets: list[Socket] = list(sockets_for_hull(hull_id))
        self._fitted: list[Node3D | None] = [None] * len(self.sockets)
        self._ids: list[str | None] = [None] * len(self.sockets)
        self._wiring = SignalWiring(self)

    # -- lifecycle --------------------------------------------------------

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

    def on_ready(self):
        self._wiring.want(SignalNames.WARP_COMPLETED, self._on_warp_completed)
        self._wiring.sweep()

    def on_update(self, dt: float):
        self._wiring.poll(dt)

    # -- fitting ----------------------------------------------------------

    def install(self, module_id: str, socket_index: int) -> Node3D:
        """Bolt *module_id* into a socket and return the node it built.

        Raises ``ValueError`` for an unknown module, a socket that does not
        exist, a socket already filled, a module too large for the mount, or a
        fifth turret past ``balance.AUTO_TURRETS_MAX``.
        """
        spec = module_spec(module_id)
        socket = self._socket(socket_index)
        if self._fitted[socket_index] is not None:
            raise ValueError(f"socket {socket_index} ({socket.label}) already carries {self._ids[socket_index]!r}")
        if not socket.accepts(spec["socket_size"]):
            raise ValueError(f"{module_id!r} needs a {spec['socket_size']} socket; {socket.label} is {socket.size}")
        if spec["family"] == "turret" and len(self.turrets()) >= balance.AUTO_TURRETS_MAX:
            raise ValueError(f"a hull carries at most {balance.AUTO_TURRETS_MAX} auto-turrets")

        node = make_module(module_id, position=socket.local_position())
        node.socket = socket
        node.rack = self
        self._fitted[socket_index] = self.add_child(node)
        self._ids[socket_index] = module_id
        self._on_fitting_changed()
        self.module_installed(module_id, socket_index)
        return node

    def remove(self, socket_index: int) -> None:
        """Strip a socket back to bare mounting. A no-op on an empty socket."""
        self._socket(socket_index)
        node = self._fitted[socket_index]
        if node is None:
            return
        module_id = self._ids[socket_index]
        self._fitted[socket_index] = None
        self._ids[socket_index] = None
        removed = getattr(node, "on_removed", None)
        if callable(removed):
            removed()
        node.rack = None
        # Immediate rather than deferred: the power system rediscovers its
        # sources on the next line, and a module still in the tree at that
        # moment would keep paying out for the rest of the frame. A deployed
        # turret hangs off the scene rather than off the rack, so the unlink
        # goes through whatever is actually carrying it.
        if node.parent is not None:
            node.parent.remove_child(node)
        node.destroy()
        self._on_fitting_changed()
        self.module_removed(module_id, socket_index)

    def _socket(self, socket_index: int) -> Socket:
        if not 0 <= socket_index < len(self.sockets):
            raise ValueError(f"socket {socket_index} does not exist (hull has {len(self.sockets)})")
        return self.sockets[socket_index]

    # -- reading ----------------------------------------------------------

    def module_at(self, socket_index: int) -> Node3D | None:
        """Whatever is in a socket, or None."""
        self._socket(socket_index)
        return self._fitted[socket_index]

    def module_id_at(self, socket_index: int) -> str | None:
        """The catalogue id in a socket, or None."""
        self._socket(socket_index)
        return self._ids[socket_index]

    def installed(self) -> list[tuple[int, Node3D]]:
        """Every fitted module with the socket index it occupies."""
        return [(i, node) for i, node in enumerate(self._fitted) if node is not None]

    def installed_ids(self) -> list[str]:
        """Catalogue ids of everything currently fitted, in socket order."""
        return [mid for mid in self._ids if mid is not None]

    def free_sockets(self, size: str | None = None) -> list[Socket]:
        """Empty sockets, optionally only those a module of *size* fits."""
        return [
            socket
            for i, socket in enumerate(self.sockets)
            if self._fitted[i] is None and (size is None or socket.accepts(size))
        ]

    def socket_for(self, module_id: str) -> Socket | None:
        """Where *module_id* would go if it were bought now, or None for nowhere.

        The same choice :meth:`install` is given by the run scene, the sternmost
        mount that takes it, so a shelf can promise a socket by name before the
        scrap is spent rather than after.
        """
        free = self.free_sockets(str(module_spec(module_id)["socket_size"]))
        return free[-1] if free else None

    def fit_lines(self) -> list[str]:
        """One line per socket, for a screen that shows the current fit.

        Empty mounts are listed too. A rack that only printed what is installed
        would answer "what can I still buy?" with silence, which is the question
        a pilot standing in a shop is actually asking.
        """
        lines: list[str] = []
        for index, socket in enumerate(self.sockets):
            head = f"{socket.label} ({socket.size})"
            module_id = self._ids[index]
            if module_id is None:
                lines.append(f"{head}: empty")
                continue
            lines.append(f"{head}: {module_id.replace('_', ' ').upper()}, {effect_summary(module_id)}")
        return lines

    def turrets(self) -> list[AutoTurret]:
        """Every auto-turret on the hull, docked or deployed."""
        return [node for node in self._fitted if isinstance(node, AutoTurret)]

    def ship(self) -> Node3D | None:
        """The hull the rack is mounted on."""
        return self.parent if isinstance(self.parent, Node3D) else None

    def deployment_host(self) -> Node | None:
        """Where a deployed turret is parented: the ship's own parent, or the root.

        A turret that is out is no longer part of the hull, so it must hang off
        something that does not move with it. Anything above the ship will do,
        since a ``Node3D`` under a plain ``Node`` keeps its own world transform.
        """
        ship = self.ship()
        if ship is not None and ship.parent is not None:
            return ship.parent
        tree = self.tree
        return None if tree is None else tree.root

    # -- aggregates -------------------------------------------------------

    def total_mass(self) -> float:
        """Mass of everything fitted, in the handling model's units."""
        return sum(float(MODULE_CATALOGUE[mid]["mass"]) for mid in self.installed_ids())

    def handling_multiplier(self) -> float:
        """How much the fitted mass slows the hull, 1.0 on a bare ship.

        The ship module applies this to its acceleration and turn rate; until it
        does, the number is still the honest measure of what a build costs to
        fly, and the rack pushes it to any hull that accepts it.
        """
        loaded = 1.0 / (1.0 + self.total_mass() / HULL_REFERENCE_MASS)
        return max(MIN_HANDLING_MULTIPLIER, loaded)

    def effect_multiplier(self, name: str) -> float:
        """The product of one named multiplicative effect across the build."""
        value = 1.0
        for mid in self.installed_ids():
            effect = MODULE_CATALOGUE[mid]["effects"].get(name)
            if effect is not None:
                value *= float(effect)
        return value

    def effect_bonus(self, name: str) -> float:
        """The sum of one named additive effect across the build."""
        return sum(float(MODULE_CATALOGUE[mid]["effects"].get(name, 0.0)) for mid in self.installed_ids())

    # -- turret contract across a warp ------------------------------------

    def deploy_turrets(self) -> int:
        """Drop every docked turret where the ship stands; returns how many."""
        return sum(1 for turret in self.turrets() if turret.deploy())

    def retrieve_turrets(self) -> int:
        """Take every deployed turret back aboard; returns how many."""
        return sum(1 for turret in self.turrets() if turret.retrieve())

    def _on_warp_completed(self, emergency: bool) -> None:
        if not emergency:
            self.retrieve_turrets()
            return
        for index, node in list(self.installed()):
            if isinstance(node, AutoTurret) and node.deployed:
                self.remove(index)

    # -- consequences of a fitting change ---------------------------------

    def _on_fitting_changed(self) -> None:
        tree = self.tree
        power = None if tree is None else tree.singletons.get(Services.POWER)
        if power is not None:
            power.refresh_sources()
        ship = self.ship()
        set_mass = getattr(ship, "set_module_mass", None)
        if callable(set_mass):
            set_mass(self.total_mass())