shrike/sector.py

Part of SHRIKE.

"""What a warp-in drops you into: one sector's harvestable content.

A sector is built from one seed and one biome, and every feature it places is
priced in noise, because loudness is the price of wealth:

* **Mineral veins are back-loaded.** The surface 70 percent of a vein cracks
  fast; the last 30 percent is a core that only yields under a sustained beam
  and pays double per unit of ore. Nearly half a vein's value therefore sits
  behind the point at which a sensible pilot would already have left.
* **Wrecks mirror that shape** at the sector's scale: an outer bay of quick
  scrap anybody can grab, and a sealed vault behind a 20-second hack channel
  worth +15 signature and a sector's worth of scrap.
* **Fuel comets, ice chunks and vents** are the strategic refills the biome
  table inverts. An Ice Field is poor in scrap and thick with breathable ice, a
  Vent Field pays fuel and oxygen, a Nebula pays scrap and blinds the warning.
* **Scrap motes** are what everything else releases. Nothing credits the ledger
  on the spot: ore becomes glowing confetti you have to fly back through.
  :meth:`Sector.credit` is where a scooped mote becomes income, and for oxygen
  and fuel that means the run's tanks directly, not only a signal.

A sector is also a bounded place, and it says so three ways rather than letting
a straight line end in a silent void: the dust thins and desaturates past
:data:`SECTOR_CONTENT_RADIUS`, crossing :data:`SECTOR_BOUNDARY_RADIUS` raises
:data:`BOUNDARY_NOTICE` until the pilot turns back, and
:meth:`Sector.compass_targets` keeps naming the nearest vein, wreck and depot
for the HUD's screen-edge markers.

When the Shrike tears in it cracks the sector open. :meth:`Sector.crack_open`
shears every sealed vault and splits every core so it pays at surface speed
with no channel, which is why the safest loot in the sector appears right next
to the thing that wants you dead.

Every one of those verbs announces itself. :meth:`Sector.affordance` resolves
the nearest thing the ship can act on into one short line naming the key and
the verb, which the HUD draws above the reticle, and each feature carries its
own state on its skin: a vein dims as its surface goes, its core lights up when
it is the only thing left, a spent body goes dark, a looted wreck's bay light
goes out, and a sealed vault glows until it is open. A pilot should never have
to guess whether a rock still has anything in it.

Generation is deterministic in the seed: the same seed, biome and sector index
always produce the same layout, so a node's danger and its payout are both
learnable. Charted lanes run both ways, so the run can walk back into a place
it has already stripped; ``revisited=True`` deals that place again from the
same seed with its harvest gone (:data:`REVISIT_HARVEST_MULT`). Backtracking
buys the air and the fuel you flew past, never a fresh field of ore.
"""

import math
import random
from dataclasses import dataclass

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

from . import balance, events
from .power import SignalWiring
from .runtime import PLANE_Y, Groups, Services, to_plane

try:  # Geometry and the dust field come from the kitbash module when installed.
    from . import artkit, vfx
except ImportError:  # pragma: no cover - the art layer is optional here
    artkit = None
    vfx = None

# ============================================================================
# Module-local tuning
#
# These are the numbers the design fixes in prose but balance.py does not yet
# carry: the sector's physical size, the shape of the mining curve, and the
# per-biome feature counts behind the biome table's resource inversions.
# ============================================================================

#: Radius of the playable disc, in world units on the flight plane. Sized so a
#: sector reads as a place rather than as a void: at cruise its far edge is
#: about four seconds away, and the whole disc is a handful of screens.
SECTOR_RADIUS = 60.0
#: Nothing is placed inside this radius of the warp-in point.
SECTOR_SPAWN_CLEARANCE = 18.0
#: The first :data:`SECTOR_NEAR_FEATURES` placements are forced inside this
#: radius of the warp-in point. Scattering the whole sector by area alone is
#: what left a player warping into an empty screen with the nearest thing to
#: do a long dead flight away; something must be in view on arrival.
SECTOR_NEAR_RADIUS = 35.0
SECTOR_NEAR_FEATURES = 3
#: Where the sector's content stops: no feature is ever placed outside it.
SECTOR_CONTENT_RADIUS = SECTOR_RADIUS
#: Crossing this raises the leaving-sector cue and keeps it up until the pilot
#: turns back. The gap between it and the content radius is the shoulder a
#: pilot chasing a mote to the rim is allowed without being nagged.
SECTOR_BOUNDARY_RADIUS = SECTOR_RADIUS + 15.0
#: Where the dust has thinned as far as it goes. Flying a straight line used to
#: end in a field of grain identical to the one over the veins, which reads as
#: more sector; past here the grain is nearly gone and the picture says empty.
SECTOR_VOID_RADIUS = SECTOR_RADIUS + 90.0
#: What the dust keeps of its density and of its colour out in the void.
VOID_DUST_ALPHA_FLOOR = 0.15
VOID_DUST_SATURATION_FLOOR = 0.10
#: The cue itself. It names what is out there and the key that shows where to
#: go instead, because "you are leaving" on its own is only half an answer.
#: Run one has no chart, so its variant offers the drive instead: naming M to
#: a pilot whose M answers "the chart is offline" is a door painted on a wall.
BOUNDARY_NOTICE = "LEAVING SECTOR: nothing out here (M: chart)"
BOUNDARY_NOTICE_OFFLINE = "LEAVING SECTOR: nothing out here (R: warp on)"

#: Kinds the sector offers the HUD's screen-edge compass, nearest first. The
#: depot is not among them: it carries the HUD's own persistent beacon, and a
#: thing with two markers on it is a thing the pilot counts twice.
COMPASS_DEPOSIT = "deposit"
COMPASS_WRECK = "wreck"

#: Refill floats merge for this long after the last credit, so a vent pays one
#: label when the pilot leaves it rather than one per frame while they sit.
CREDIT_FLOAT_MERGE_S = 0.35
#: What each credited resource is called on its float label. Scrap is absent on
#: purpose: the run scene already floats its own merged "+N SCRAP" off the same
#: signal, and two labels for one mote is worse than none.
CREDIT_FLOAT_LABELS: dict[str, str] = {"o2": "O2", "fuel": "FUEL"}

#: Minimum separation between two placed features.
SECTOR_MIN_SEPARATION = 14.0
#: Rejection-sampling attempts per feature before the separation rule is relaxed.
SECTOR_PLACEMENT_ATTEMPTS = 40

#: The sector every run opens in. Its depot is guaranteed, whatever the chart's
#: edges rolled: see :data:`FIRST_SECTOR_DEPOT_RADIUS`.
FIRST_SECTOR_INDEX = 1
#: Where the opening sector's guaranteed depot is planted, as a radius from the
#: warp-in point. Inside the near band, so the beacon it carries points at
#: something a pilot can reach in the first minute rather than at the far rim.
#:
#: The guarantee exists because six recorded boots reached neither a depot, a
#: shop nor a refit in twenty-five minutes of play. Nothing was wrong with the
#: chart: a drift depot rides an edge, and the node a run starts on is the one
#: node nobody arrives at along an edge, so the opening sector could never have
#: one. A pilot therefore mined, banked nothing, and learned that scrap is a
#: number that goes up. The first sector is where the economy has to be taught,
#: so the first sector always has somewhere to spend.
FIRST_SECTOR_DEPOT_RADIUS = 26.0

#: Radius of the ring drawn on the ground around the dock, in world units.
#: Pinned by test to ``trading.DOCK_RADIUS``, which is the radius the bay
#: actually docks at: a ring that is not the bay is a lie drawn on the floor.
#: Stated here rather than imported so that the sector, which places the
#: anchor, does not have to depend on the module that sells things at it.
#:
#: A blind pilot crossed a depot's bay three times without docking. The bay was
#: a number in a sensor and nothing in the world; the ring is that number drawn,
#: and it lights when the hull is inside it (:class:`~shrike.vfx.DockRing`).
DOCK_RING_RADIUS = 14.0

#: What a vein says when the last of it comes out. The thinning beam already
#: reads as a vein running down, and the rock goes dark when it is spent, but
#: neither says the word: a blind playtest kept the beam on a dead rock because
#: nothing had told it the rock was finished.
TAPPED_OUT_LABEL = "TAPPED OUT"

#: How big a vein is drawn, and therefore how big it is: a base body plus this
#: much per point of ore, so a rich vein is visibly the fatter target.
DEPOSIT_BASE_RADIUS = 1.4
DEPOSIT_RADIUS_PER_SCRAP = 0.02
#: A hulk's own extent, and the seal on it. Both are what a beam has to reach.
WRECK_HIT_RADIUS = 2.6
VAULT_HIT_RADIUS = 1.6


def deposit_radius(value: float) -> float:
    """How wide a vein worth *value* is drawn, in world units."""
    return DEPOSIT_BASE_RADIUS + DEPOSIT_RADIUS_PER_SCRAP * max(0.0, float(value))


#: Beam damage a vein absorbs per point of scrap it is worth. With the mining
#: laser at ``balance.MINING_LASER_DEPOSIT_MULT`` times its DPS, a 50-scrap
#: vein is a little under eight seconds of surface and a similar core.
DEPOSIT_WORK_PER_SCRAP = 8.0
#: The core is denser than the surface: this much more work per unit of ore.
DEPOSIT_CORE_HARDNESS = 1.6
#: Seconds of unbroken beam on an exposed core before it yields at full rate.
DEPOSIT_CORE_SUSTAIN_S = 4.0
#: Yield multiplier on a core the beam has only just touched.
DEPOSIT_CORE_COLD_RATE = 0.25
#: Losing the beam for longer than this cools the core back down.
DEPOSIT_BEAM_GRACE_S = 0.35

#: Value spread across a sector's veins, as a multiplier on the even share.
DEPOSIT_VALUE_SPREAD = (0.7, 1.3)
#: A wreck's outer bay is worth this much of a vein's share of the budget.
WRECK_BAY_BUDGET_WEIGHT = 0.6
#: The design table calls the Wreck Graveyard "huge scrap"; ``BiomeSpec`` has
#: no field for it yet, so the multiplier lives here until balance.py grows one.
WRECK_GRAVEYARD_SCRAP_MULT = 1.5

#: What a sector still holds the second time the run walks into it. Charted
#: lanes run both ways, so a node can be revisited, and a node that rebuilt
#: itself whole would make a 15-fuel round trip the cheapest ore in the game.
#: The harvest is the thing already taken: the veins come back thin and few,
#: the sealed vault does not come back at all, and the strategic refills come
#: back halved, because ice and fuel are the honest reason to fly back and
#: an empty return trip is no reason to have the lanes at all.
REVISIT_HARVEST_MULT = 0.2
REVISIT_FEATURE_CAP = 1
REVISIT_REFILL_MULT = 0.5

#: Losing the hack channel for longer than this stalls it and it starts to slip.
VAULT_HACK_GRACE_S = 0.5
#: Hack progress lost per second while the channel is not being sustained.
VAULT_HACK_DECAY_PER_S = 0.02
#: How close the ship must stay for the hack channel to keep running. The
#: channel is a place you have to remain, not a beam you have to hold: holding
#: the mining laser on a seal for twenty seconds while a wave lands is not a
#: decision, it is a punishment, and the beam's own caller could only ever
#: announce the channel once per trigger anyway.
VAULT_HACK_RADIUS = 16.0

#: Motes are collected by flying through them.
PICKUP_SCOOP_RADIUS = 4.5
#: A tap of ``interact`` grabs the nearest loose prize inside this radius.
PICKUP_GRAB_RADIUS = 14.0
#: Motes drift out of a broken vein at up to this speed, and slow to a stop.
PICKUP_DRIFT_SPEED = 4.0
PICKUP_DRIFT_DAMPING = 1.6
#: A single burst never spawns more than this many motes; the rest lump together.
PICKUP_BURST_MAX = 12

#: How many distinct silhouettes artkit is asked for per feature type. Small on
#: purpose: artkit caches meshes by seed, so variety is bought once per sector.
VISUAL_SEED_POOL = 4

#: Emissive strength of a vein's ore accent at full surface, once the core is
#: the only thing left, and once the body is spent. The middle value is a flare,
#: not a fade: an exposed core is the one moment a rock is worth more than it
#: looks, so it is the one moment it looks like more.
DEPOSIT_ACCENT_FULL = 1.0
DEPOSIT_ACCENT_CORE = 2.6
DEPOSIT_ACCENT_SPENT = 0.0
#: How dark a spent body's rock goes, as a multiplier on its colour.
DEPOSIT_SPENT_DIM = 0.45
#: Floor on the surface accent, so a nearly-stripped vein is still visible as a
#: thing in space rather than fading into the background before it is empty.
DEPOSIT_ACCENT_FLOOR = 0.25

#: The wreck's bay light: on while the outer bay still holds anything, out the
#: moment it is emptied. It is the whole of "the wreck visibly empties".
WRECK_BAY_LIGHT_RADIUS = 0.55
WRECK_BAY_LIGHT_OFFSET = 2.2
WRECK_BAY_LIGHT_COLOUR = (0.95, 0.78, 0.35, 1.0)
WRECK_BAY_LIGHT_STRENGTH = 2.2

#: A sealed vault glows; an opened one is a hole. These are the two states.
VAULT_SEALED_STRENGTH = 2.0
VAULT_OPEN_STRENGTH = 0.0
VAULT_OPEN_DIM = 0.35

#: How far away the core prompt starts offering the beam. Set to the mining
#: laser's own reach in ``weapons.FIRE_PROFILES``, so the line appears exactly
#: where the beam would land: a prompt that promises a verb out of range is the
#: same defect as no prompt at all, one step further on.
AFFORDANCE_BEAM_RADIUS = 26.0

#: The affordance lines themselves. Every one names its key and its verb, and
#: the vault's names its price, because twenty loud seconds is a decision.
PROMPT_GRAB = "F: GRAB"
PROMPT_LOOT_BAY = "F: GRAB SALVAGE"
PROMPT_HACK_VAULT = "F: HACK VAULT, 20 s, loud"
PROMPT_HACKING_VAULT = "HACKING VAULT: stay close, {seconds:.0f} s"
PROMPT_CRACK_CORE = "HOLD RMB: CRACK THE CORE"

#: Value bands for one mote of each resource kind.
MOTE_VALUE_BANDS: dict[str, tuple[float, float]] = {
    "scrap": (float(balance.SCRAP_ORE_CHUNK_MIN), float(balance.SCRAP_ORE_CHUNK_MAX)),
    "fuel": (2.5, 5.0),
    "o2": (balance.ICE_CHUNK_O2 * 0.5, balance.ICE_CHUNK_O2),
    "ammo": (float(balance.AMMO_BOX_ROUNDS), float(balance.AMMO_BOX_ROUNDS)),
}

#: A vent's reach, and how fast it gives up its charge while you sit in it.
VENT_RADIUS = 9.0
VENT_FUEL_PER_S = 2.0
VENT_O2_PER_S = 4.0
VENT_FUEL_CHARGE = balance.FUEL_COMET_MIN
VENT_O2_CHARGE = balance.ICE_CHUNK_O2 * 2.0


@dataclass(frozen=True)
class BiomeContent:
    """How many of each feature a biome places, as inclusive count ranges.

    This is the biome table's resource inversion expressed as geography: an Ice
    Field is not poor in scrap because a multiplier says so, it is poor because
    it grew fewer veins and more ice.
    """

    deposits: tuple[int, int]
    wrecks: tuple[int, int]
    fuel_comets: tuple[int, int]
    ice_chunks: tuple[int, int]
    vents: tuple[int, int]
    hazards: tuple[int, int] = (0, 0)
    extra_vaults: int = 0
    ammo_box_chance: float = 0.2


BIOME_CONTENT: dict[str, BiomeContent] = {
    "debris_field": BiomeContent(
        deposits=(3, 4), wrecks=(2, 3), fuel_comets=(0, 1), ice_chunks=(0, 1), vents=(0, 0), ammo_box_chance=0.6
    ),
    "solar_shallows": BiomeContent(
        deposits=(3, 5), wrecks=(1, 2), fuel_comets=(1, 2), ice_chunks=(0, 0), vents=(0, 0), ammo_box_chance=0.2
    ),
    "ice_field": BiomeContent(
        deposits=(2, 3), wrecks=(1, 2), fuel_comets=(0, 1), ice_chunks=(5, 8), vents=(0, 1), ammo_box_chance=0.1
    ),
    "nebula": BiomeContent(
        deposits=(4, 6), wrecks=(2, 3), fuel_comets=(0, 1), ice_chunks=(0, 1), vents=(0, 0), ammo_box_chance=0.2
    ),
    "wreck_graveyard": BiomeContent(
        deposits=(2, 3),
        wrecks=(5, 7),
        fuel_comets=(1, 2),
        ice_chunks=(0, 1),
        vents=(0, 0),
        hazards=(1, 2),
        extra_vaults=1,
        ammo_box_chance=0.5,
    ),
    "vent_field": BiomeContent(
        deposits=(2, 3),
        wrecks=(1, 2),
        fuel_comets=(2, 3),
        ice_chunks=(2, 3),
        vents=(3, 5),
        hazards=(3, 5),
        ammo_box_chance=0.1,
    ),
    "broker_claim": BiomeContent(
        deposits=(2, 3),
        wrecks=(2, 3),
        fuel_comets=(1, 1),
        ice_chunks=(0, 1),
        vents=(0, 1),
        extra_vaults=1,
        ammo_box_chance=0.3,
    ),
    "roost": BiomeContent(deposits=(0, 0), wrecks=(0, 0), fuel_comets=(0, 0), ice_chunks=(0, 0), vents=(0, 0)),
}

#: Readability palette for the placeholder geometry: harvest is warm, refills
#: are cold, sealed prizes glow.
_FEATURE_COLOURS: dict[str, tuple[float, float, float, float]] = {
    "vein": (0.42, 0.35, 0.28, 1.0),
    "rich_vein": (0.62, 0.48, 0.24, 1.0),
    "comet": (0.30, 0.45, 0.55, 1.0),
    "ice": (0.55, 0.75, 0.85, 1.0),
    "wreck": (0.28, 0.30, 0.34, 1.0),
    "vault": (0.75, 0.62, 0.25, 1.0),
    "vent": (0.35, 0.28, 0.30, 1.0),
    "mote": (0.95, 0.78, 0.35, 1.0),
}


def _plane_distance(a: Vec2, b: Vec2) -> float:
    """Distance between two flight-plane points."""
    return math.hypot(float(a.x) - float(b.x), float(a.y) - float(b.y))


def _placeholder(kind: str, radius: float) -> MeshInstance3D:
    """A primitive stand-in so a sector is never invisible without artkit."""
    colour = _FEATURE_COLOURS.get(kind, (0.5, 0.5, 0.5, 1.0))
    emissive = kind in ("mote", "vault", "vent", "ice")
    material = Material(
        colour=colour,
        metallic=0.1 if emissive else 0.6,
        roughness=0.8,
        emissive_colour=colour[:3] if emissive else None,
    )
    return MeshInstance3D(name="Visual", mesh=Mesh.sphere(radius=radius, rings=8, segments=10), material=material)


#: The name artkit gives an emissive accent mesh. Looked up rather than imported
#: so a sector still skins its features when the art layer is not installed.
ART_ACCENT_NAME = getattr(artkit, "ROLE_ACCENT", "Accent")


def _mesh_instances(node: Node3D) -> list[MeshInstance3D]:
    """Every mesh under *node*, whichever layer built the geometry."""
    found: list[MeshInstance3D] = []
    stack = [node]
    while stack:
        current = stack.pop()
        if isinstance(current, MeshInstance3D):
            found.append(current)
        stack.extend(current.children)
    return found


def _set_emissive(mesh: MeshInstance3D | None, colour, strength: float) -> None:
    """Drive one mesh's emissive to *strength*, keeping *colour*'s hue."""
    material = getattr(mesh, "material", None)
    if material is None:
        return
    material.emissive_colour = (float(colour[0]), float(colour[1]), float(colour[2]), float(strength))


def _dim_albedo(mesh: MeshInstance3D | None, factor: float) -> None:
    """Scale one mesh's albedo toward black, keeping its alpha."""
    material = getattr(mesh, "material", None)
    if material is None:
        return
    colour = tuple(float(channel) for channel in material.colour)
    rgb = tuple(channel * float(factor) for channel in colour[:3])
    material.colour = (*rgb, colour[3] if len(colour) > 3 else 1.0)


@dataclass(frozen=True)
class Affordance:
    """One thing in reach, and the line that names the key that takes it.

    *kind* is the verb id (``"grab"``, ``"bay"``, ``"vault"``, ``"hacking"``,
    ``"core"``), *target* the feature it belongs to, and *distance* how far the
    ship is from it. The HUD only ever draws :attr:`prompt`; the rest is for the
    interact handler, which must act on exactly what the prompt promised.
    """

    prompt: str
    kind: str
    target: object
    distance: float


# ============================================================================
# Placed features
# ============================================================================


class SectorFeature(Node3D):
    """Base for everything a sector places, with a cached owning sector."""

    def __init__(self, *, visual_seed: int = 0, **kwargs):
        super().__init__(**kwargs)
        self.visual_seed = int(visual_seed)
        self._sector: Sector | None = None

    @property
    def sector(self) -> Sector | None:
        """The :class:`Sector` this feature belongs to, or None once detached."""
        if self._sector is None:
            node = self.parent
            while node is not None:
                if isinstance(node, Sector):
                    self._sector = node
                    break
                node = node.parent
        return self._sector

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

        World rather than local, because a vault is a child of the wreck it is
        welded into and its local position is the keel, not the sector.
        """
        return to_plane(self.world_position)


class Deposit(SectorFeature):
    """A back-loaded ore body: a fast surface and a core that pays double.

    Mining is work against two pools. The surface holds
    ``1 - balance.DEPOSIT_CORE_FRACTION`` of the ore and gives it up at the
    beam's face value. The core holds the rest, costs
    :data:`DEPOSIT_CORE_HARDNESS` times as much work per unit of ore, pays
    ``balance.DEPOSIT_CORE_PAYOUT_MULT`` times as much for it, and only reaches
    full yield after :data:`DEPOSIT_CORE_SUSTAIN_S` seconds of unbroken beam on
    the exposed core. Let the beam drop and the core cools back down, so a
    pilot who taps between dodges never banks the back half of a vein.

    ``remaining_surface`` and ``remaining_core`` are beam-damage remaining, not
    scrap; :attr:`value_remaining` is the payout still in the rock.

    All three of those states are on the rock's skin. The ore accent dims as
    the surface goes, flares to :data:`DEPOSIT_ACCENT_CORE` the moment the core
    is the only thing left (which is also when the crack-the-core prompt
    appears), and goes out entirely when the body is spent, with the rock
    itself darkened behind it. A pilot should be able to tell a stripped vein
    from a fresh one at a glance, from across the sector.
    """

    def __init__(
        self,
        *,
        value: float = 50.0,
        rich: bool = False,
        resource: str = "scrap",
        core_fraction: float = balance.DEPOSIT_CORE_FRACTION,
        **kwargs,
    ):
        super().__init__(**kwargs)
        self.resource = resource
        self.rich = bool(rich)
        self.value = max(0.0, float(value))
        self.tapped = False
        self.split = False
        #: Radius a beam has to reach to be cutting this vein. It is the body's
        #: own drawn radius, because anything smaller means a beam laid across
        #: the middle of a rock passes through it and pays nothing, which is
        #: what a blind pilot read as "mining does not work".
        self.hit_radius = deposit_radius(self.value)

        core_fraction = min(max(float(core_fraction), 0.0), 1.0)
        surface_fraction = 1.0 - core_fraction
        work = DEPOSIT_WORK_PER_SCRAP * self.value
        self.remaining_surface = work * surface_fraction
        self.remaining_core = work * core_fraction * DEPOSIT_CORE_HARDNESS

        # Payout per unit of ore, set so surface plus core equals the vein's value
        # with the core paying its multiple.
        ore_units = surface_fraction + core_fraction * balance.DEPOSIT_CORE_PAYOUT_MULT
        per_ore = self.value / ore_units if ore_units > 0 else 0.0
        self._surface_pay = (per_ore * surface_fraction) / self.remaining_surface if self.remaining_surface > 0 else 0.0
        core_pay_total = per_ore * core_fraction * balance.DEPOSIT_CORE_PAYOUT_MULT
        self._core_pay = core_pay_total / self.remaining_core if self.remaining_core > 0 else 0.0

        self._core_beam = 0.0
        self._idle = DEPOSIT_BEAM_GRACE_S
        self._bank = 0.0

        self._surface_full = self.remaining_surface
        self._body: MeshInstance3D | None = None
        self._accent: MeshInstance3D | None = None
        self._accent_colour = (1.0, 0.82, 0.36)
        self._spent_shown = False

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

    def on_ready(self):
        radius = self.hit_radius
        if artkit is not None and self.resource == "scrap":
            art = self.add_child(artkit.build_deposit(self.rich, self.visual_seed))
        else:
            kind = "comet" if self.resource == "fuel" else ("rich_vein" if self.rich else "vein")
            art = self.add_child(_placeholder(kind, radius))
        self._bind_skin(art)
        self.refresh_visual()

    def _bind_skin(self, art: Node3D) -> None:
        """Find the two meshes this deposit shows its state on.

        The kitbash deposit carries a separate ore accent; the placeholder is
        one sphere, which then plays both parts. Either way the accent's
        emissive is the state channel and the body's albedo is the "spent" one.
        """
        meshes = _mesh_instances(art)
        if not meshes:
            return
        accents = [mesh for mesh in meshes if mesh.name == ART_ACCENT_NAME]
        bodies = [mesh for mesh in meshes if mesh.name != ART_ACCENT_NAME]
        self._accent = accents[0] if accents else meshes[0]
        self._body = bodies[0] if bodies else meshes[0]
        material = getattr(self._accent, "material", None)
        emissive = getattr(material, "emissive_colour", None)
        if emissive is not None:
            self._accent_colour = tuple(float(channel) for channel in emissive[:3])
        elif material is not None:
            self._accent_colour = tuple(float(channel) for channel in tuple(material.colour)[:3])

    def accent_strength(self) -> float:
        """Emissive strength the ore accent should currently be showing."""
        if self.depleted:
            return DEPOSIT_ACCENT_SPENT
        if self.core_exposed:
            return DEPOSIT_ACCENT_CORE
        if self._surface_full <= 0.0:
            return DEPOSIT_ACCENT_FULL
        left = max(0.0, self.remaining_surface) / self._surface_full
        return DEPOSIT_ACCENT_FLOOR + (DEPOSIT_ACCENT_FULL - DEPOSIT_ACCENT_FLOOR) * left

    def refresh_visual(self) -> None:
        """Put the current state on the rock. Cheap enough to call per tick.

        The frame the last ore comes out is also where the rock says so in
        words: the beam thinning and the body going dark are both true and both
        gradual, and a pilot who has been holding the trigger reads neither as
        "this one is finished". One label, once, where the vein is.
        """
        _set_emissive(self._accent, self._accent_colour, self.accent_strength())
        if not self.depleted or self._spent_shown:
            return
        self._spent_shown = True
        self._announce_spent()
        _dim_albedo(self._body, DEPOSIT_SPENT_DIM)
        if self._accent is not self._body:
            _dim_albedo(self._accent, DEPOSIT_SPENT_DIM)
        # A spent body is no longer a deposit as far as the beam is concerned.
        # Leaving it in the group left it clamping the mining laser's reach for
        # nothing, so a stripped vein went on blocking the one behind it.
        self.remove_from_group(Groups.DEPOSITS)

    def _announce_spent(self) -> None:
        """Float one :data:`TAPPED_OUT_LABEL` over the vein that just ran out.

        Only for a vein that was actually worked: a body the Shrike sheared or
        a deposit that was born empty has nothing to tell the pilot about their
        own beam. Credits nothing, so the label stays where the rock is instead
        of flying at a counter.

        Planted at the rock's position rather than pinned to the rock. A spent
        vein does not move, so following it buys nothing, and the HUD steps a
        planted label around the ship's own readings while a pinned one has to
        stay on the thing it names: pinned, this one rose through ``SIGNATURE``
        on a rendered frame.
        """
        if not self.tapped:
            return
        sector = self.sector
        hud = sector._service(Services.HUD) if sector is not None else None
        if hud is None:
            return
        hud.float_text(TAPPED_OUT_LABEL, position=Vec3(self.world_position), toward="")

    @property
    def depleted(self) -> bool:
        """True once neither pool has ore left."""
        return self.remaining_surface <= 0.0 and self.remaining_core <= 0.0

    @property
    def core_exposed(self) -> bool:
        """True once the surface is gone and the core is the only thing left."""
        return self.remaining_surface <= 0.0 and self.remaining_core > 0.0

    @property
    def value_remaining(self) -> float:
        """Payout still locked in the rock, in this deposit's resource."""
        return self.remaining_surface * self._surface_pay + self.remaining_core * self._core_pay

    def core_yield_rate(self) -> float:
        """Current fraction of the core's full yield rate, from 0 to 1."""
        if self.split:
            return 1.0
        ramp = min(self._core_beam / DEPOSIT_CORE_SUSTAIN_S, 1.0) if DEPOSIT_CORE_SUSTAIN_S > 0 else 1.0
        return DEPOSIT_CORE_COLD_RATE + (1.0 - DEPOSIT_CORE_COLD_RATE) * ramp

    def mine(self, dps: float, dt: float) -> float:
        """Apply *dps* of beam for *dt* seconds; returns the resource released.

        Call once per frame while the beam holds. Released resource leaves as
        motes rather than crediting anything directly, so the return value is
        for feedback (the HUD's scrap ticker, the vfx spray), not for the
        ledger.
        """
        if self.depleted or dps <= 0.0 or dt <= 0.0:
            return 0.0
        self._idle = 0.0
        released = 0.0
        work = dps * dt

        if self.remaining_surface > 0.0:
            used = min(work, self.remaining_surface)
            self.remaining_surface -= used
            work -= used
            released += used * self._surface_pay

        if self.remaining_core > 0.0:
            if self.remaining_surface <= 0.0:
                self._core_beam += dt
            if work > 0.0:
                used = min(work * self.core_yield_rate(), self.remaining_core)
                self.remaining_core -= used
                released += used * self._core_pay

        if released > 0.0 and not self.tapped:
            self.tapped = True
            sector = self.sector
            if sector is not None and self.rich:
                sector.report_rich_tap()
        self._bank_release(released)
        self.refresh_visual()
        return released

    def split_core(self) -> None:
        """Shear the core open so it yields at surface speed with no sustain."""
        self.split = True
        self._core_beam = DEPOSIT_CORE_SUSTAIN_S
        self.refresh_visual()

    def on_update(self, dt: float):
        self._idle += dt
        if self._idle > DEPOSIT_BEAM_GRACE_S and not self.split:
            self._core_beam = 0.0

    def _bank_release(self, amount: float) -> None:
        """Hold released ore back until it is worth a mote, then spawn one."""
        if amount <= 0.0:
            return
        self._bank += amount
        sector = self.sector
        if sector is None:
            return
        threshold = MOTE_VALUE_BANDS.get(self.resource, (1.0, 1.0))[0]
        if self._bank >= threshold or (self.depleted and self._bank > 0.0):
            sector.release(self.resource, self._bank, self.plane_position)
            self._bank = 0.0


class FuelComet(Deposit):
    """A frozen fuel body. All surface, no core, and mining one is loud."""

    def __init__(self, *, value: float = balance.FUEL_COMET_MIN, **kwargs):
        super().__init__(value=value, rich=True, resource="fuel", core_fraction=0.0, **kwargs)


class Vault(SectorFeature):
    """A sealed prize behind a hack channel that announces you while it runs.

    The channel is started by a tap of ``interact`` inside
    :data:`VAULT_HACK_RADIUS` (or by the mining beam touching the seal, which
    calls :meth:`begin_hack` the same way), and it then runs for
    ``balance.VAULT_HACK_CHANNEL_S`` for as long as the ship stays inside that
    radius. Fly away and it stalls and slips back; see it through and the vault
    pays ``balance.SCRAP_VAULT_MIN`` to ``MAX`` scrap and
    ``balance.SIGNATURE_VAULT_HACK`` signature.

    Proximity rather than a held beam is what makes the twenty seconds a
    decision. It is also the only contract a caller can honour: a beam knows it
    has touched a seal, but it announces that once per trigger pull, so a
    channel that demanded a call every frame simply never completed, and the
    vault sat there eating beam ticks and paying nothing.

    The Shrike does not respect seals. :meth:`shear` opens a vault outright
    when the sector cracks, with no channel and no signature bill.
    """

    def __init__(self, *, scrap: float = balance.SCRAP_VAULT_MIN, **kwargs):
        super().__init__(**kwargs)
        self.scrap = float(scrap)
        self.sealed = True
        self.hacking = False
        #: What a beam has to reach to be standing on the seal.
        self.hit_radius = VAULT_HIT_RADIUS
        self.hack_progress = 0.0
        self._since_beam = VAULT_HACK_GRACE_S * 2.0
        self._visual: MeshInstance3D | None = None

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

    def on_ready(self):
        self._visual = self.add_child(_placeholder("vault", VAULT_HIT_RADIUS))
        self._refresh_visual()

    @property
    def hack_remaining_s(self) -> float:
        """Seconds of channel still owed, zero once the vault is open."""
        if not self.sealed:
            return 0.0
        return max(0.0, (1.0 - self.hack_progress) * balance.VAULT_HACK_CHANNEL_S)

    def begin_hack(self) -> bool:
        """Start the hack channel. False when the vault is already open.

        Idempotent: starting a running channel simply re-arms it, which is what
        the mining beam's one call per trigger pull amounts to.
        """
        if not self.sealed:
            return False
        self._since_beam = 0.0
        self.hacking = True
        return True

    def in_hack_range(self, here: Vec2) -> bool:
        """Whether a ship at *here* is close enough to run the channel."""
        return _plane_distance(here, self.plane_position) <= VAULT_HACK_RADIUS

    def _sustained(self) -> bool:
        """Whether the channel has a reason to keep running this frame."""
        if self._since_beam <= VAULT_HACK_GRACE_S:
            return True
        tree = self.tree
        ship = tree.get_first_in_group(Groups.SHIP) if tree is not None else None
        return ship is not None and self.in_hack_range(to_plane(ship.world_position))

    def on_update(self, dt: float):
        if not self.sealed or not self.hacking:
            return
        self._since_beam += dt
        if self._sustained():
            self.hack_progress += dt / balance.VAULT_HACK_CHANNEL_S
            if self.hack_progress >= 1.0:
                self._complete()
        else:
            self.hack_progress = max(0.0, self.hack_progress - VAULT_HACK_DECAY_PER_S * dt)
            if self.hack_progress <= 0.0:
                self.hacking = False

    def shear(self) -> None:
        """Open the vault the way the Shrike does: no channel, no signature."""
        if not self.sealed:
            return
        self.sealed = False
        self.hacking = False
        self.hack_progress = 1.0
        self._pay_out()
        self._refresh_visual()

    def _complete(self) -> None:
        self.sealed = False
        self.hacking = False
        self.hack_progress = 1.0
        sector = self.sector
        if sector is not None:
            sector.report_vault_hacked(self.scrap)
        self._pay_out()
        self._refresh_visual()

    def _refresh_visual(self) -> None:
        """A sealed vault glows; an opened one is a dark hole in the keel."""
        colour = _FEATURE_COLOURS["vault"]
        if self.sealed:
            _set_emissive(self._visual, colour, VAULT_SEALED_STRENGTH)
            return
        _set_emissive(self._visual, colour, VAULT_OPEN_STRENGTH)
        _dim_albedo(self._visual, VAULT_OPEN_DIM)

    def _pay_out(self) -> None:
        sector = self.sector
        if sector is not None and self.scrap > 0.0:
            sector.release("scrap", self.scrap, self.plane_position)
        self.scrap = 0.0
        # An opened vault is no longer a vault to the beam that opened it: it
        # leaves the group so it stops clamping the mining laser's reach on
        # every later pass over a wreck the pilot has already worked.
        self.remove_from_group(Groups.VAULTS)


class Wreck(SectorFeature):
    """A dead hull: a quick outer bay, and often a vault welded into the keel.

    The bay is a tap of ``interact``, the fastest scrap in the sector and the
    reason a wreck is worth approaching at all. What makes it worth staying for
    is :attr:`vault`, and the vault is the loud half.

    A wreck that still holds something burns a bay light. Emptying it puts the
    light out, so a graveyard the pilot has already worked reads as worked from
    a distance instead of being seven identical silhouettes.
    """

    def __init__(
        self,
        *,
        bay_scrap: float = balance.SCRAP_WRECK_MIN,
        fuel: float = balance.WRECK_TANK_FUEL,
        ammo_boxes: int = 0,
        module_tier: int = 1,
        **kwargs,
    ):
        super().__init__(**kwargs)
        self.bay_scrap = float(bay_scrap)
        self.fuel = float(fuel)
        self.ammo_boxes = int(ammo_boxes)
        self.module_tier = int(module_tier)
        self.looted = False
        self.vault: Vault | None = None
        #: What a beam has to reach to be standing on this hulk.
        self.hit_radius = WRECK_HIT_RADIUS
        self._bay_light: MeshInstance3D | None = None

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

    def on_ready(self):
        if artkit is not None:
            self.add_child(artkit.build_wreck(self.visual_seed))
        else:
            self.add_child(_placeholder("wreck", WRECK_HIT_RADIUS))
        light = _placeholder("mote", WRECK_BAY_LIGHT_RADIUS)
        light.name = "BayLight"
        light.position = Vec3(0.0, PLANE_Y, WRECK_BAY_LIGHT_OFFSET)
        _set_emissive(light, WRECK_BAY_LIGHT_COLOUR, WRECK_BAY_LIGHT_STRENGTH)
        self._bay_light = self.add_child(light)
        self._refresh_visual()

    @property
    def has_bay(self) -> bool:
        """Whether the outer bay still holds anything worth a grab."""
        return not self.looted and (self.bay_scrap > 0.0 or self.fuel > 0.0 or self.ammo_boxes > 0)

    def _refresh_visual(self) -> None:
        if self._bay_light is not None:
            self._bay_light.visible = self.has_bay

    def loot_bay(self) -> float:
        """Empty the outer bay. Returns the scrap released, 0 if already looted."""
        if self.looted:
            return 0.0
        self.looted = True
        sector = self.sector
        released = self.bay_scrap
        if sector is not None:
            at = self.plane_position
            if self.bay_scrap > 0.0:
                sector.release("scrap", self.bay_scrap, at)
            if self.fuel > 0.0:
                sector.release("fuel", self.fuel, at)
            for _ in range(self.ammo_boxes):
                sector.release("ammo", float(balance.AMMO_BOX_ROUNDS), at)
        self.bay_scrap = 0.0
        self.fuel = 0.0
        self.ammo_boxes = 0
        self._refresh_visual()
        return released


class Pickup(SectorFeature):
    """A loose prize: scrap confetti, an ice chunk, a spilled tank, an ammo box.

    Collected by flying through it (:data:`PICKUP_SCOOP_RADIUS`) or by a tap of
    ``interact`` from a little further out. Collection is the only thing in the
    sector that credits a resource, which is what makes income a physical act.
    """

    def __init__(self, *, kind: str = "scrap", amount: float = 1.0, drift: Vec2 | None = None, **kwargs):
        super().__init__(**kwargs)
        self.kind = kind
        self.amount = float(amount)
        self.collected = False
        self._drift = drift if drift is not None else Vec2(0.0, 0.0)

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

    def on_ready(self):
        self.add_child(_placeholder("ice" if self.kind == "o2" else "mote", 0.5))

    def on_update(self, dt: float):
        speed = math.hypot(float(self._drift.x), float(self._drift.y))
        if speed <= 0.01:
            return
        self.position = Vec3(
            float(self.position.x) + float(self._drift.x) * dt,
            PLANE_Y,
            float(self.position.z) + float(self._drift.y) * dt,
        )
        decay = max(0.0, 1.0 - PICKUP_DRIFT_DAMPING * dt)
        self._drift = Vec2(float(self._drift.x) * decay, float(self._drift.y) * decay)

    def collect(self) -> float:
        """Credit this pickup and remove it. Returns the amount credited."""
        if self.collected:
            return 0.0
        self.collected = True
        sector = self.sector
        if sector is not None:
            sector.credit(self.kind, self.amount)
        self.destroy()
        return self.amount


class Vent(SectorFeature):
    """A thermal vent: park in it and it refills fuel and oxygen until it dies.

    The Vent Field's whole inversion, made physical. A vent is generous and
    stationary, which means taking it costs the one thing a sector charges for:
    time spent not leaving.
    """

    def __init__(
        self,
        *,
        fuel: float = VENT_FUEL_CHARGE,
        o2: float = VENT_O2_CHARGE,
        radius: float = VENT_RADIUS,
        **kwargs,
    ):
        super().__init__(**kwargs)
        self.fuel = float(fuel)
        self.o2 = float(o2)
        self.radius = float(radius)

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

    def on_ready(self):
        self.add_child(_placeholder("vent", 2.0))

    @property
    def spent(self) -> bool:
        """True once the vent has nothing left to give."""
        return self.fuel <= 0.0 and self.o2 <= 0.0

    def draw_from(self, dt: float) -> None:
        """Bleed one frame's worth of refill into the ship's tanks."""
        sector = self.sector
        if sector is None or dt <= 0.0:
            return
        if self.fuel > 0.0:
            amount = min(self.fuel, VENT_FUEL_PER_S * dt)
            self.fuel -= amount
            sector.credit("fuel", amount)
        if self.o2 > 0.0:
            amount = min(self.o2, VENT_O2_PER_S * dt)
            self.o2 -= amount
            sector.credit("o2", amount)


# ============================================================================
# The sector
# ============================================================================


class Sector(Node3D):
    """One generated sector: its biome, its content, and its signal event.

    Construct with a ``seed`` to generate on mount, or call :meth:`generate`
    later to build (or rebuild) the layout. Generation draws one card from the
    run's :class:`~shrike.events.SignalEventDeck`, sizes the harvest against
    the act's drop table and the biome's inversions, scatters the features, and
    emits ``sector_entered`` followed by ``signal_event``.
    """

    #: Where a jump drops the hull, in the sector's own space. Every layout is
    #: built around it: nothing is placed inside :data:`SECTOR_SPAWN_CLEARANCE`
    #: of it and the first :data:`SECTOR_NEAR_FEATURES` placements are forced
    #: inside :data:`SECTOR_NEAR_RADIUS`, so a pilot who arrives on it has
    #: something worth flying at already in view. Arriving anywhere else throws
    #: that guarantee away, which is why ``flow.enter_sector`` places the hull
    #: here on every jump.
    warp_anchor = Vec3(0.0, PLANE_Y, 0.0)

    #: (sector_index: int, biome_id: str)
    sector_entered = Signal(int, str)
    #: (kind: str, amount: float) for "scrap", "fuel", "o2" and "ammo"
    resource_collected = Signal(str, float)
    #: A rich node gave up its first ore; the signature meter charges for it.
    rich_node_tapped = Signal()
    #: (scrap: float) a vault channel completed under its own power
    vault_hacked = Signal(float)
    #: (event_id: str) the card this sector dealt
    signal_event = Signal(str)
    #: The Shrike's arrival tore the sector open.
    sector_cracked = Signal()

    def __init__(
        self,
        *,
        sector_index: int = 1,
        biome_id: str = "debris_field",
        seed: int | None = None,
        deck: events.SignalEventDeck | None = None,
        has_depot: bool = False,
        chart_offline: bool = False,
        revisited: bool = False,
        **kwargs,
    ):
        super().__init__(**kwargs)
        self.sector_index = int(sector_index)
        self.biome = balance.BIOMES[biome_id]
        self.deck = deck
        #: Whether a drift depot rides this sector. The caller says so from the
        #: chart edge it came in along; the opening sector says so itself,
        #: because no edge leads into it and the run has to be able to spend
        #: what its first sector pays. See :data:`FIRST_SECTOR_DEPOT_RADIUS`.
        self.has_depot = bool(has_depot) or self.sector_index == FIRST_SECTOR_INDEX
        #: True on a run flown before the chart calibrates: the boundary cue
        #: then offers the drive key rather than a chart that will not open.
        self.chart_offline = bool(chart_offline)
        #: True when the run has stood here before. The place is the same
        #: place, dealt from the same seed; what it is not is a fresh harvest.
        #: See :data:`REVISIT_HARVEST_MULT`.
        self.revisited = bool(revisited)

        self.event_id: str | None = None
        self.event: events.SignalEventCard | None = None
        self.harvest_budget = 0.0
        self.depot_anchor: Vec2 | None = None
        self.hazard_anchors: list[Vec2] = []
        self.cracked = False
        #: The sector's motion reference, mounted on entry and never cleared.
        self.dust: Node3D | None = None
        #: The ring drawn on the ground around the dock, when this sector has
        #: one. Mounted by the layout beside the anchor it marks and armed from
        #: the same tick that resolves the affordances.
        self.dock_ring: Node3D | None = None
        #: True while the ship is outside :data:`SECTOR_BOUNDARY_RADIUS`.
        self.beyond_boundary = False

        self._dust_fade = 1.0
        self._credit_bank: dict[str, float] = {}
        self._credit_wait = 0.0

        self._seed = seed
        self._rng = random.Random(seed if seed is not None else 0)
        self._generated = False
        self._deposits: list[Deposit] = []
        self._wrecks: list[Wreck] = []
        self._vaults: list[Vault] = []
        self._vents: list[Vent] = []
        self._pickups: list[Pickup] = []
        self._crack_countdown: float | None = None
        self._hunter_connected = False

    # -- read-only views ---------------------------------------------------

    @property
    def deposits(self) -> list[Deposit]:
        """Every ore body in the sector, veins and comets alike."""
        return list(self._deposits)

    @property
    def wrecks(self) -> list[Wreck]:
        return list(self._wrecks)

    @property
    def vaults(self) -> list[Vault]:
        return list(self._vaults)

    @property
    def vents(self) -> list[Vent]:
        return list(self._vents)

    @property
    def pickups(self) -> list[Pickup]:
        """Loose prizes currently floating, oldest first."""
        return [p for p in self._pickups if not p.collected]

    @property
    def signature_mult(self) -> float:
        """The card's sector-scoped multiplier on signature gain."""
        return self.event.signature_mult if self.event is not None else 1.0

    @property
    def hostile_event(self) -> bool:
        """Whether this sector's card promises that something will shoot."""
        return bool(self.event.hostile) if self.event is not None else False

    def harvestable_scrap(self) -> float:
        """Scrap still in the ground, in bays, in sealed vaults and in motes."""
        total = sum(d.value_remaining for d in self._deposits if d.resource == "scrap")
        total += sum(w.bay_scrap for w in self._wrecks)
        total += sum(v.scrap for v in self._vaults)
        total += sum(p.amount for p in self.pickups if p.kind == "scrap")
        return total

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

    def on_ready(self):
        self._mount_dust()
        if self._seed is not None and not self._generated:
            self.generate(self._seed)

    def _mount_dust(self) -> None:
        """Give the sector its motion reference.

        Every sector gets one, including an empty one: the dust is what tells
        the player the ship is moving at all, so it is not content and it is
        not optional. It is a child of the sector rather than of the run scene
        so that leaving takes it with the rest of the place.
        """
        if self.dust is not None or vfx is None:
            return
        self.dust = self.add_child(vfx.DustField(name="Dust", seed=self._seed if self._seed is not None else 0))

    def on_update(self, dt: float):
        self._connect_hunter_if_present()
        if self._crack_countdown is not None:
            self._crack_countdown -= dt
            if self._crack_countdown <= 0.0:
                self._crack_countdown = None
                self.crack_open()

        self._pickups = [p for p in self._pickups if not p.collected and not p.destroying]
        self._tick_credit_floats(dt)
        ship = self.tree.get_first_in_group(Groups.SHIP) if self.tree is not None else None
        if ship is None:
            return
        here = to_plane(ship.position)

        for pickup in list(self._pickups):
            if _plane_distance(here, pickup.plane_position) <= PICKUP_SCOOP_RADIUS:
                pickup.collect()

        for vent in self._vents:
            if not vent.spent and _plane_distance(here, vent.plane_position) <= vent.radius:
                vent.draw_from(dt)

        if Input.is_action_just_pressed("interact"):
            self.perform_interact(here)

        self._tick_dock_ring(here)
        self._tick_boundary(here)

    def _tick_dock_ring(self, here: Vec2) -> None:
        """Light the bay's ring while the hull is standing in it."""
        ring = self.dock_ring
        anchor = self.depot_anchor
        if ring is None or anchor is None:
            return
        ring.set_armed(_plane_distance(here, anchor) <= DOCK_RING_RADIUS)

    # -- the edge of the place ---------------------------------------------

    def _tick_boundary(self, here: Vec2) -> None:
        """Say where the sector stops, in the dust and on the HUD.

        Three channels, because one was never enough: the grain thins and
        drains of colour as the content is left behind, the HUD carries a
        standing line naming what is out there and the key back to the chart,
        and the screen-edge compass keeps pointing at the things worth flying
        to. A straight line out should look, read and steer like a mistake.
        """
        radius = math.hypot(float(here.x), float(here.y))
        self._apply_dust_fade(self.dust_fade_for(radius))
        self.beyond_boundary = radius > SECTOR_BOUNDARY_RADIUS
        hud = self._service(Services.HUD)
        if hud is None:
            return
        if self.beyond_boundary:
            hud.set_boundary_notice(BOUNDARY_NOTICE_OFFLINE if self.chart_offline else BOUNDARY_NOTICE)
        hud.set_compass_targets(self.compass_targets(here))

    @staticmethod
    def dust_fade_for(radius: float) -> float:
        """Density the dust should carry *radius* out, 1 inside, 0 in the void."""
        if radius <= SECTOR_CONTENT_RADIUS:
            return 1.0
        span = max(SECTOR_VOID_RADIUS - SECTOR_CONTENT_RADIUS, 1e-6)
        return max(0.0, 1.0 - (radius - SECTOR_CONTENT_RADIUS) / span)

    @property
    def dust_fade(self) -> float:
        """The density fraction the dust is currently drawn at."""
        return self._dust_fade

    def compass_targets(self, here: Vec2 | None = None) -> list[tuple[Vec3, str]]:
        """The nearest thing of each kind worth flying to, as ``(where, kind)``.

        One deposit and one wreck: the answers to "there is nothing here" that
        are in this sector. Kinds are the ``COMPASS_*`` ids, and the HUD decides
        whether they are needed, since only it knows what is on screen.

        Every offered target is inside :data:`SECTOR_CONTENT_RADIUS`, checked
        rather than assumed. A marker is a promise that flying at it arrives
        somewhere, and a playtester who chased one to the sector boundary and
        out the other side had that promise broken by the HUD rather than by
        the pilot. The depot is deliberately absent: it has its own persistent
        beacon, and offering it here as well drew it twice.
        """
        if here is None:
            ship = self.tree.get_first_in_group(Groups.SHIP) if self.tree is not None else None
            if ship is None:
                return []
            here = to_plane(ship.world_position)

        out: list[tuple[Vec3, str]] = []
        nearest = self._nearest([d for d in self._deposits if not d.depleted], here)
        if nearest is not None:
            out.append((nearest.world_position, COMPASS_DEPOSIT))
        worth_a_look = [w for w in self._wrecks if w.has_bay or (w.vault is not None and w.vault.sealed)]
        nearest = self._nearest(worth_a_look, here)
        if nearest is not None:
            out.append((nearest.world_position, COMPASS_WRECK))
        return [(where, kind) for where, kind in out if self.in_sector(to_plane(where))]

    @staticmethod
    def in_sector(where: Vec2) -> bool:
        """Whether *where* is inside the sector's content disc."""
        return math.hypot(float(where.x), float(where.y)) <= SECTOR_CONTENT_RADIUS

    @staticmethod
    def _nearest(features: list, here: Vec2):
        """The feature of *features* closest to *here*, or None when empty."""
        if not features:
            return None
        return min(features, key=lambda feature: _plane_distance(here, feature.plane_position))

    def _apply_dust_fade(self, fade: float) -> None:
        """Thin and desaturate the dust to *fade*, 1 being the field as built.

        Driven through :meth:`~shrike.vfx.DustField.set_fade`, which owns the
        materials and keeps the fade across the act re-tints the field does for
        itself; the floors here are this sector's say over what the void keeps.
        """
        if self.dust is None or abs(fade - self._dust_fade) < 1e-3:
            return
        self._dust_fade = fade
        self.dust.set_fade(
            density=VOID_DUST_ALPHA_FLOOR + (1.0 - VOID_DUST_ALPHA_FLOOR) * fade,
            saturation=VOID_DUST_SATURATION_FLOOR + (1.0 - VOID_DUST_SATURATION_FLOOR) * fade,
            glow=fade,
        )

    # -- affordances -------------------------------------------------------

    def affordance(self, here: Vec2 | None = None) -> Affordance | None:
        """The nearest verb the ship at *here* can perform, or None.

        Each candidate is gated by the radius its own verb actually uses, so
        the line the HUD draws and the thing the key does turn on and off
        together. Ranking is by plain distance: an exposed core under the nose
        beats a mote across the sector, and vice versa.
        """
        if here is None:
            ship = self.tree.get_first_in_group(Groups.SHIP) if self.tree is not None else None
            if ship is None:
                return None
            here = to_plane(ship.world_position)

        running = next((v for v in self._vaults if v.sealed and v.hacking and v.in_hack_range(here)), None)
        if running is not None:
            return Affordance(
                PROMPT_HACKING_VAULT.format(seconds=running.hack_remaining_s),
                "hacking",
                running,
                _plane_distance(here, running.plane_position),
            )

        best: Affordance | None = None

        def offer(prompt: str, kind: str, target, distance: float, reach: float) -> None:
            nonlocal best
            if distance > reach:
                return
            if best is None or distance < best.distance:
                best = Affordance(prompt, kind, target, distance)

        for pickup in self.pickups:
            offer(PROMPT_GRAB, "grab", pickup, _plane_distance(here, pickup.plane_position), PICKUP_GRAB_RADIUS)
        for wreck in self._wrecks:
            if wreck.has_bay:
                offer(PROMPT_LOOT_BAY, "bay", wreck, _plane_distance(here, wreck.plane_position), PICKUP_GRAB_RADIUS)
        for vault in self._vaults:
            if vault.sealed:
                offer(PROMPT_HACK_VAULT, "vault", vault, _plane_distance(here, vault.plane_position), VAULT_HACK_RADIUS)
        for deposit in self._deposits:
            if deposit.core_exposed:
                offer(
                    PROMPT_CRACK_CORE,
                    "core",
                    deposit,
                    _plane_distance(here, deposit.plane_position),
                    AFFORDANCE_BEAM_RADIUS,
                )
        return best

    def perform_interact(self, here: Vec2 | None = None) -> str:
        """Take whatever the affordance is currently offering ``interact``.

        Returns the verb id taken, or an empty string when nothing was in
        reach. The core is not on this key: cracking it is a held beam, and the
        prompt says so.
        """
        found = self.affordance(here)
        if found is None:
            return ""
        if found.kind == "grab":
            found.target.collect()
        elif found.kind == "bay":
            found.target.loot_bay()
        elif found.kind == "vault":
            found.target.begin_hack()
        else:
            return ""
        return found.kind

    # -- generation --------------------------------------------------------

    def generate(self, seed: int) -> None:
        """Build the sector's content from *seed*, replacing anything already placed."""
        self._seed = seed
        rng = random.Random(seed)
        # A second stream, so runtime scatter (motes) never perturbs the layout.
        self._rng = random.Random(seed + 1)
        self._clear()

        deck = self.deck if self.deck is not None else events.SignalEventDeck(seed)
        self.deck = deck
        self.event_id = deck.draw()
        self.event = events.card(self.event_id)

        content = BIOME_CONTENT[self.biome.id]
        drops = balance.ACT_DROPS[balance.act_for_sector(self.sector_index)]

        budget = rng.uniform(*drops.scrap_per_sector) * self.biome.scrap_mult
        if self.biome.id == "wreck_graveyard":
            budget *= WRECK_GRAVEYARD_SCRAP_MULT
        n_deposits = rng.randint(*content.deposits)
        n_wrecks = rng.randint(*content.wrecks)
        if self.revisited:
            budget *= REVISIT_HARVEST_MULT
            n_deposits = min(n_deposits, REVISIT_FEATURE_CAP)
            n_wrecks = min(n_wrecks, REVISIT_FEATURE_CAP)
        self.harvest_budget = budget

        share = budget / max(n_deposits + n_wrecks * WRECK_BAY_BUDGET_WEIGHT, 1e-6)

        taken: list[Vec2] = []
        self._place_deposits(rng, n_deposits, share, taken)
        self._place_wrecks(rng, n_wrecks, share * WRECK_BAY_BUDGET_WEIGHT, drops, content, taken)
        self._place_vaults(rng, drops, content, taken)
        self._place_refills(rng, content, taken)
        self._place_event_content(rng, taken)
        self._place_anchors(rng, content, taken)

        self._generated = True
        # Both signals below fire once, from this node's own on_ready, which no
        # interval sweep can have seen yet: the wirings must be told first, or
        # every deferred consumer misses the only sector_entered it will get.
        SignalWiring.sweep_all()
        self.sector_entered(self.sector_index, self.biome.id)
        self.signal_event(self.event_id)

    def _place_deposits(self, rng: random.Random, count: int, share: float, taken: list[Vec2]) -> None:
        values = [share * rng.uniform(*DEPOSIT_VALUE_SPREAD) for _ in range(count)]
        for index, value in enumerate(values):
            deposit = Deposit(
                name=f"Vein{index}",
                position=self._scatter(rng, taken),
                value=value,
                rich=value >= share,
                visual_seed=rng.randrange(VISUAL_SEED_POOL),
            )
            self._deposits.append(self.add_child(deposit))

    def _place_wrecks(
        self,
        rng: random.Random,
        count: int,
        bay_value: float,
        drops: balance.ActDrops,
        content: BiomeContent,
        taken: list[Vec2],
    ) -> None:
        for index in range(count):
            wreck = Wreck(
                name=f"Wreck{index}",
                position=self._scatter(rng, taken),
                bay_scrap=bay_value * rng.uniform(*DEPOSIT_VALUE_SPREAD),
                fuel=balance.WRECK_TANK_FUEL,
                ammo_boxes=1 if rng.random() < content.ammo_box_chance else 0,
                module_tier=rng.randint(*drops.module_tiers_in_wrecks),
                visual_seed=rng.randrange(VISUAL_SEED_POOL),
            )
            self._wrecks.append(self.add_child(wreck))

    def _place_vaults(
        self, rng: random.Random, drops: balance.ActDrops, content: BiomeContent, taken: list[Vec2]
    ) -> None:
        card = self.event
        extra = content.extra_vaults + (card.vaults if card is not None else 0)
        count = rng.randint(*drops.vaults_per_sector) + extra
        if self.revisited:
            # The sealed prize is the one thing a sector holds exactly once.
            count = 0
        free_wrecks = [w for w in self._wrecks if w.vault is None]
        rng.shuffle(free_wrecks)
        for index in range(count):
            scrap = rng.uniform(balance.SCRAP_VAULT_MIN, balance.SCRAP_VAULT_MAX) * self.biome.scrap_mult
            if free_wrecks:
                host = free_wrecks.pop()
                vault = Vault(name="Vault", position=Vec3(0.0, PLANE_Y, 0.0), scrap=scrap)
                host.vault = host.add_child(vault)
            else:
                vault = Vault(name=f"Vault{index}", position=self._scatter(rng, taken), scrap=scrap)
                self.add_child(vault)
            self._vaults.append(vault)

    def _place_refills(self, rng: random.Random, content: BiomeContent, taken: list[Vec2]) -> None:
        for index in range(self._refill_count(rng, content.fuel_comets)):
            comet = FuelComet(
                name=f"Comet{index}",
                position=self._scatter(rng, taken),
                value=rng.uniform(balance.FUEL_COMET_MIN, balance.FUEL_COMET_MAX),
            )
            self._deposits.append(self.add_child(comet))
        for index in range(self._refill_count(rng, content.ice_chunks)):
            self._add_pickup(
                Pickup(name=f"Ice{index}", position=self._scatter(rng, taken), kind="o2", amount=balance.ICE_CHUNK_O2)
            )
        for index in range(self._refill_count(rng, content.vents)):
            vent = Vent(name=f"Vent{index}", position=self._scatter(rng, taken))
            self._vents.append(self.add_child(vent))

    def _refill_count(self, rng: random.Random, band: tuple[int, int]) -> int:
        """How many of a strategic refill this visit places.

        The roll happens whatever the visit, so a revisited layout is the same
        layout thinned rather than a different one, and only the count that
        comes out of it is halved.
        """
        count = rng.randint(*band)
        return int(count * REVISIT_REFILL_MULT) if self.revisited else count

    def _place_event_content(self, rng: random.Random, taken: list[Vec2]) -> None:
        card = self.event
        if card is None:
            return
        if card.scrap > 0.0:
            self._add_pickup(Pickup(name="Cache", position=self._scatter(rng, taken), kind="scrap", amount=card.scrap))
        if card.fuel > 0.0:
            comet = FuelComet(name="EventComet", position=self._scatter(rng, taken), value=card.fuel)
            self._deposits.append(self.add_child(comet))
        if card.o2 > 0.0:
            chunks = max(1, int(round(card.o2 / balance.ICE_CHUNK_O2)))
            for index in range(chunks):
                self._add_pickup(
                    Pickup(
                        name=f"EventIce{index}",
                        position=self._scatter(rng, taken),
                        kind="o2",
                        amount=card.o2 / chunks,
                    )
                )

    def _place_anchors(self, rng: random.Random, content: BiomeContent, taken: list[Vec2]) -> None:
        self.hazard_anchors = [to_plane(self._scatter(rng, taken)) for _ in range(rng.randint(*content.hazards))]
        self.depot_anchor = self._place_depot(rng, taken) if self.has_depot else None
        self._mount_dock_ring()

    def _mount_dock_ring(self) -> None:
        """Draw the bay on the ground, if this sector has one.

        The sector places the anchor, so the sector owns the mark on it: the
        dock itself is built by the run, and a ring that only appears once a
        shop node exists is a ring the layout cannot promise. Nothing here
        depends on the dock, only on where it will be.
        """
        if self.dock_ring is not None:
            parent = self.dock_ring.parent
            if parent is not None:
                parent.remove_child(self.dock_ring)
            self.dock_ring.destroy()
            self.dock_ring = None
        if self.depot_anchor is None or vfx is None:
            return
        anchor = self.depot_anchor
        self.dock_ring = self.add_child(
            vfx.DockRing(
                name="DockRing",
                radius=DOCK_RING_RADIUS,
                position=Vec3(float(anchor.x), PLANE_Y, float(anchor.y)),
            )
        )

    def _place_depot(self, rng: random.Random, taken: list[Vec2]) -> Vec2:
        """Where the dock sits, near the warp-in point in the opening sector.

        A depot anywhere on a sixty-unit disc is a long flight to a shop a pilot
        does not yet know exists. The opening sector is the one that has to teach
        the sink, so its dock is planted on a ring the ship can be at within the
        first minute, on a bearing the rest of the layout has left free. Later
        sectors keep the ordinary scatter: by then the beacon means something.
        """
        if self.sector_index != FIRST_SECTOR_INDEX:
            return to_plane(self._scatter(rng, taken))
        best = Vec2(FIRST_SECTOR_DEPOT_RADIUS, 0.0)
        best_clearance = -1.0
        for _ in range(SECTOR_PLACEMENT_ATTEMPTS):
            angle = rng.uniform(0.0, math.tau)
            spot = Vec2(
                FIRST_SECTOR_DEPOT_RADIUS * math.cos(angle),
                FIRST_SECTOR_DEPOT_RADIUS * math.sin(angle),
            )
            clearance = min((_plane_distance(spot, other) for other in taken), default=SECTOR_RADIUS)
            if clearance > best_clearance:
                best, best_clearance = spot, clearance
            if clearance >= SECTOR_MIN_SEPARATION:
                break
        taken.append(best)
        return best

    def _scatter(self, rng: random.Random, taken: list[Vec2]) -> Vec3:
        """A free spot on the plane, clear of the warp-in point and its neighbours.

        The first :data:`SECTOR_NEAR_FEATURES` spots of a layout are drawn from
        the near band only, so a pilot who has just warped in can see something
        worth flying at without turning the ship around first. Everything after
        them is scattered evenly by area across the whole disc.
        """
        outer = SECTOR_NEAR_RADIUS if len(taken) < SECTOR_NEAR_FEATURES else SECTOR_RADIUS
        span = outer - SECTOR_SPAWN_CLEARANCE
        best = Vec2(0.0, 0.0)
        for _ in range(SECTOR_PLACEMENT_ATTEMPTS):
            radius = SECTOR_SPAWN_CLEARANCE + span * math.sqrt(rng.random())
            angle = rng.uniform(0.0, math.tau)
            best = Vec2(radius * math.cos(angle), radius * math.sin(angle))
            if all(_plane_distance(best, other) >= SECTOR_MIN_SEPARATION for other in taken):
                break
        taken.append(best)
        return Vec3(float(best.x), PLANE_Y, float(best.y))

    def _clear(self) -> None:
        for feature in (*self._deposits, *self._wrecks, *self._vaults, *self._vents, *self._pickups):
            parent = feature.parent
            if parent is not None:
                parent.remove_child(feature)
            feature.destroy()
        self._deposits.clear()
        self._wrecks.clear()
        self._vaults.clear()
        self._vents.clear()
        self._pickups.clear()
        self.hazard_anchors = []
        self.depot_anchor = None
        self.cracked = False
        self._mount_dock_ring()

    # -- the harvest ledger ------------------------------------------------

    def release(self, kind: str, amount: float, at: Vec2) -> list[Pickup]:
        """Scatter *amount* of *kind* as motes around *at*. Returns the motes."""
        if amount <= 0.0:
            return []
        low, high = MOTE_VALUE_BANDS.get(kind, (amount, amount))
        rng = self._rng
        motes: list[Pickup] = []
        left = amount
        while left > 0.0 and len(motes) < PICKUP_BURST_MAX:
            value = min(left, rng.uniform(low, high))
            if left - value < low * 0.5:
                value = left
            left -= value
            angle = rng.uniform(0.0, math.tau)
            speed = rng.uniform(0.3, 1.0) * PICKUP_DRIFT_SPEED
            offset = rng.uniform(0.5, 2.0)
            mote = Pickup(
                name="Mote",
                position=Vec3(float(at.x) + math.cos(angle) * offset, PLANE_Y, float(at.y) + math.sin(angle) * offset),
                kind=kind,
                amount=value,
                drift=Vec2(math.cos(angle) * speed, math.sin(angle) * speed),
            )
            motes.append(self._add_pickup(mote))
        if left > 0.0 and motes:
            motes[-1].amount += left
        return motes

    def credit(self, kind: str, amount: float) -> None:
        """Put *amount* of *kind* aboard the ship, and announce it.

        The announcement is not the income. ``resource_collected`` is a
        notification several modules listen to for their own reasons, and the
        run's tanks are not among them: life support and the fuel tank are
        filled here, through the power system's own ``add_o2`` / ``add_fuel``,
        the way a depot canister fills them. Without this an ice field was
        scenery, a fuel comet was a rock, and a vent was a light.
        """
        if amount <= 0.0:
            return
        power = self._service(Services.POWER)
        if power is not None:
            if kind == "o2":
                power.add_o2(amount)
            elif kind == "fuel":
                power.add_fuel(amount)
        if kind in CREDIT_FLOAT_LABELS:
            self._credit_bank[kind] = self._credit_bank.get(kind, 0.0) + float(amount)
            self._credit_wait = CREDIT_FLOAT_MERGE_S
        self.resource_collected(kind, amount)

    def _tick_credit_floats(self, dt: float) -> None:
        """Float one label per refill once the credits stop arriving.

        A vent pays every frame it is sat in, so a label per credit would be a
        column of "+0 O2". The bank flushes once the stream dries up, which
        makes one label per act of collection however long the act took, and the
        HUD carries whatever is left over into the next one: a refill worth two
        thirds of a unit is not a "+0", it is two thirds of the next label.
        """
        if not self._credit_bank:
            return
        self._credit_wait -= dt
        if self._credit_wait > 0.0:
            return
        banked, self._credit_bank = self._credit_bank, {}
        hud = self._service(Services.HUD)
        ship = self.tree.get_first_in_group(Groups.SHIP) if self.tree is not None else None
        if hud is None or ship is None:
            return
        for kind, amount in banked.items():
            # O2 and fuel are gauges on the ring around the hull, so their
            # labels stay where they landed rather than flying anywhere.
            hud.credit_float(kind, amount, CREDIT_FLOAT_LABELS[kind], node=ship, toward="")

    def _service(self, name: str):
        """The run singleton registered under *name*, or None outside a run."""
        tree = self.tree
        return tree.singletons.get(name) if tree is not None else None

    def report_rich_tap(self) -> None:
        """A rich node gave up its first ore. The meter charges for it."""
        self.rich_node_tapped()

    def report_vault_hacked(self, scrap: float) -> None:
        """A vault channel completed. Worth signature, notoriety and scrap."""
        self.vault_hacked(scrap)

    def _add_pickup(self, pickup: Pickup) -> Pickup:
        self.add_child(pickup)
        self._pickups.append(pickup)
        return pickup

    # -- the Shrike cracks it open -----------------------------------------

    def connect_hunter(self, hunter) -> None:
        """Listen to *hunter* for the arrival that cracks this sector open."""
        signal = getattr(hunter, "hunter_arrived", None)
        if signal is None or self._hunter_connected:
            return
        signal.connect(self.on_hunter_arrived)
        self._hunter_connected = True

    def on_hunter_arrived(self, arrival_index: int = 0) -> None:
        """Schedule the crack for ``balance.SHRIKE_CRACK_OPEN_S`` from now."""
        if not self.cracked and self._crack_countdown is None:
            self._crack_countdown = balance.SHRIKE_CRACK_OPEN_S

    def crack_open(self) -> None:
        """Shear every sealed vault and split every core. Idempotent."""
        if self.cracked:
            return
        self.cracked = True
        for vault in self._vaults:
            vault.shear()
        for deposit in self._deposits:
            deposit.split_core()
        self.sector_cracked()

    def _connect_hunter_if_present(self) -> None:
        if self._hunter_connected or self.tree is None:
            return
        hunter = self.tree.get_first_in_group(Groups.HUNTER)
        if hunter is not None:
            self.connect_hunter(hunter)