shrike/events.py

Part of SHRIKE.

"""The signal-event deck: twelve cards a sector can deal you on arrival.

Every sector warp-in resolves one card from a run-scoped deck. The deck is
weighted toward cards this profile has never seen, so early runs spend most of
their draws teaching new content and later runs still shuffle the familiar
ones. Cards are pure data: the sector reads the resource fields and seeds the
matching content, and everyone else keys off the emitted event id and looks the
card up here.

A card never spawns enemies itself. ``hostile`` is the declaration that
something will shoot at you because of it; the wave composer and the hunter
read it off the ``signal_event`` payload and decide what arrives.
"""

import random
from dataclasses import dataclass

from . import balance

#: Relative draw weight of a card the profile has never resolved.
UNSEEN_DRAW_WEIGHT = 4.0
#: Relative draw weight of a card the profile has already resolved.
SEEN_DRAW_WEIGHT = 1.0


@dataclass(frozen=True)
class SignalEventCard:
    """One card in the deck.

    ``kind`` groups the card for presentation: "boon" pays out, "bait" pays out
    but wakes something, "hazard" only costs, "trade" opens a purchase. The
    resource fields are budgets the sector spends on extra content, in the same
    units as the rest of the economy: scrap, fuel, O2. ``vaults`` seeds extra
    sealed prizes behind a hack channel. ``signature_mult`` is a sector-scoped
    multiplier on signature gain that the meter applies while this card is live.
    """

    id: str
    title: str
    kind: str
    hostile: bool = False
    scrap: float = 0.0
    fuel: float = 0.0
    o2: float = 0.0
    vaults: int = 0
    signature_mult: float = 1.0
    note: str = ""


SIGNAL_EVENTS: dict[str, SignalEventCard] = {
    "lifeboat_distress": SignalEventCard(
        "lifeboat_distress",
        "Lifeboat Distress",
        "boon",
        scrap=35.0,
        note="A crewed lifeboat answers and pays for the escort in salvage.",
    ),
    "bait_beacon": SignalEventCard(
        "bait_beacon",
        "Repeating Beacon",
        "bait",
        hostile=True,
        scrap=15.0,
        note="The distress loop repeats too cleanly. Something set it.",
    ),
    "derelict_cache": SignalEventCard(
        "derelict_cache",
        "Derelict Cache",
        "boon",
        scrap=60.0,
        note="A supply cache drifts unclaimed with its seals still green.",
    ),
    "herald_nest": SignalEventCard(
        "herald_nest",
        "Dormant Herald Nest",
        "bait",
        hostile=True,
        vaults=1,
        note="A nest sleeps in the hulk. Rob it and it wakes.",
    ),
    "black_box": SignalEventCard(
        "black_box",
        "Black Box",
        "boon",
        scrap=15.0,
        note="A flight recorder still transmitting; its log fragment is worth reading.",
    ),
    "fuel_barge": SignalEventCard(
        "fuel_barge",
        "Ruptured Barge",
        "boon",
        fuel=balance.FUEL_COMET_MAX * 2.0,
        note="A tanker broke up here and its cargo froze into comets.",
    ),
    "ice_calving": SignalEventCard(
        "ice_calving",
        "Ice Calving",
        "boon",
        o2=balance.ICE_CHUNK_O2 * 4.0,
        note="A shelf sheds; breathable ice tumbles across the lane.",
    ),
    "mine_drift": SignalEventCard(
        "mine_drift",
        "Mine Drift",
        "hazard",
        hostile=True,
        note="Somebody else's minefield has drifted across the approach.",
    ),
    "broker_courier": SignalEventCard(
        "broker_courier",
        "Broker Courier",
        "trade",
        note="A courier drone offers one module below list price and asks no questions.",
    ),
    "scavenger_pack": SignalEventCard(
        "scavenger_pack",
        "Scavenger Pack",
        "hazard",
        hostile=True,
        note="Skimmers are already here, and they strip floating salvage.",
    ),
    "sensor_shadow": SignalEventCard(
        "sensor_shadow",
        "Sensor Shadow",
        "boon",
        signature_mult=0.75,
        note="Charged dust swallows your emissions. Be loud while it lasts.",
    ),
    "wake_surge": SignalEventCard(
        "wake_surge",
        "Wake Surge",
        "hazard",
        signature_mult=1.25,
        note="The Wake laps the sector's edge and everything you do reads louder.",
    ),
}


class SignalEventDeck:
    """A run-scoped deck of signal-event cards, weighted toward unseen ones.

    ``seen`` is the profile's set of card ids and is mutated in place as cards
    are drawn, so persisting it persists the weighting. Within one deck a card
    is never dealt twice until every card has been dealt, at which point the
    deck reshuffles.
    """

    def __init__(self, seed: int, seen: set[str] | None = None):
        self._rng = random.Random(seed)
        self.seen: set[str] = seen if seen is not None else set()
        self._drawn: list[str] = []
        #: Cards dealt over the deck's whole life, reshuffles included. A deck
        #: built with the same seed and initial ``seen`` reproduces its state
        #: exactly by drawing this many times, which is how a suspended run
        #: gets the same card back on resume.
        self.draws = 0

    @property
    def drawn(self) -> list[str]:
        """Cards dealt since the deck last reshuffled, oldest first."""
        return list(self._drawn)

    def weights(self) -> dict[str, float]:
        """Current draw weight per candidate card, for the chart and for tests."""
        candidates = [card_id for card_id in SIGNAL_EVENTS if card_id not in self._drawn]
        if not candidates:
            candidates = list(SIGNAL_EVENTS)
        return {card_id: (SEEN_DRAW_WEIGHT if card_id in self.seen else UNSEEN_DRAW_WEIGHT) for card_id in candidates}

    def draw(self) -> str:
        """Deal one card, mark it seen, and return its id."""
        if len(self._drawn) >= len(SIGNAL_EVENTS):
            self._drawn.clear()
        weights = self.weights()
        card_ids = list(weights)
        card_id = self._rng.choices(card_ids, weights=[weights[c] for c in card_ids], k=1)[0]
        self._drawn.append(card_id)
        self.seen.add(card_id)
        self.draws += 1
        return card_id


def card(event_id: str) -> SignalEventCard:
    """The card behind an emitted ``signal_event`` id."""
    return SIGNAL_EVENTS[event_id]