shrike/balance.py

Part of SHRIKE.

"""Every tuning number in SHRIKE, as named constants and small specs.

This module is the single source of truth for balance. Gameplay modules import
from here and never hard-code a rate, price, HP value or timer of their own.
It is data only: no engine imports, no behaviour beyond tiny pure helpers.

Units, unless stated otherwise: seconds for time, hull points for damage,
scrap for prices, world units for distance on the flight plane. Conversion
rates share one unit, Cores per 10 scrap.
"""

from dataclasses import dataclass, field

# ============================================================================
# Run structure and acts
# ============================================================================

RUN_SECTOR_VISITS_MIN = 7
RUN_SECTOR_VISITS_MAX = 9
CHART_NODES_MIN = 14
CHART_NODES_MAX = 18
CHART_ACTS = 3

#: First sector index (1-based) of each act. Act 1 covers sectors 1 to 2,
#: Act 2 covers 3 to 6, Act 3 covers 7 and beyond.
ACT_2_FIRST_SECTOR = 3
ACT_3_FIRST_SECTOR = 7

#: Destination choices offered per chart node.
CHART_DESTINATIONS_MIN = 2
CHART_DESTINATIONS_MAX = 4

#: The Wake front consumes one chart column per this many jumps.
WAKE_COLUMNS_PER_JUMP = 1 / 2
#: Above this notoriety the Wake accelerates to one column per 1.5 jumps.
WAKE_ACCEL_NOTORIETY = 60
WAKE_ACCEL_COLUMNS_PER_JUMP = 1 / 1.5
#: The chart screen always shows the front's next advances this far ahead.
WAKE_PREVIEW_ADVANCES = 2

#: Drift depots appear on roughly half the chart's between-node edges.
DEPOT_EDGE_FRACTION = 0.5

#: Every dealt chart guarantees an oxygen refill (Ice or Vent Field) reachable
#: inside this many columns of the start, so a seed can never starve the run of
#: air before the first detour decision exists.
CHART_O2_GUARANTEE_COLUMNS = 3


def act_for_sector(sector_index: int) -> int:
    """The act (1 to 3) a 1-based sector index belongs to."""
    if sector_index >= ACT_3_FIRST_SECTOR:
        return 3
    if sector_index >= ACT_2_FIRST_SECTOR:
        return 2
    return 1


# ============================================================================
# Fuel (strategic; tank 100, start full)
# ============================================================================

FUEL_MAX = 100.0
WARP_FUEL_BASE = 15.0
WARP_FUEL_PER_COLUMN_SKIPPED = 5.0
EMERGENCY_WARP_FUEL_MULT = 1.5
DEEP_GATE_TOLL = 60.0
GENERATOR_FUEL_PER_S = 0.1

FUEL_COMET_MIN = 10.0
FUEL_COMET_MAX = 15.0
WRECK_TANK_FUEL = 5.0
DEPOT_FUEL_PRICE_SCRAP = 25
DEPOT_FUEL_AMOUNT = 20.0

# ============================================================================
# Life support (strategic; 100 O2)
# ============================================================================

O2_MAX = 100.0
O2_DRAIN_PER_S = 0.25
O2_DRAIN_PER_BREACH_PER_S = 0.15
#: A breach opens each time hull crosses another 25 percent threshold.
BREACH_HULL_FRACTION_STEP = 0.25
BREACH_PATCH_SCRAP = 5
BREACH_PATCH_CHANNEL_S = 4.0
ICE_CHUNK_O2 = 10.0
DEPOT_O2_CANISTER_AMOUNT = 40.0
DEPOT_O2_CANISTER_PRICE_SCRAP = 25
DEPOT_O2_CANISTERS_PER_VISIT = 1
#: Below this many seconds of remaining O2 the mix low-passes and breathing enters.
O2_LOW_WARNING_SECONDS = 60.0

# ============================================================================
# Energy (tactical; capacitor)
# ============================================================================

CAPACITOR_MAX = 100.0
CAPACITOR_MAX_UPGRADED = 160.0

#: The ship's bus keeps this trickle flowing into the capacitor even with the
#: wings folded and the generator cold, so a dark ship is dim, never bricked.
POWER_EMERGENCY_TRICKLE_PER_S = 2.0
#: Weapons fire down to this floor, spending whatever charge is left; only
#: below it does the trigger go dead. Non-weapon consumers stay all-or-nothing.
WEAPONS_ENERGY_FLOOR = 5.0

ENERGY_PULSE_BLASTER_PER_SHOT = 2.0
ENERGY_ARC_BEAM_PER_S = 8.0
ENERGY_MINING_BEAM_PER_S = 3.0
ENERGY_SHIELD_REGEN_PER_S = 4.0
ENERGY_AFTERBURNER_PER_S = 10.0
ENERGY_TRACTOR_SCOOP_PER_S = 3.0
ENERGY_AUTO_TURRET_PER_S = 1.5
ENERGY_REFINERY_PER_S = 5.0

# Solar wings
SOLAR_OUTPUT_PER_S = 6.0
SOLAR_OUTPUT_SOLAR_SHALLOWS_PER_S = 12.0
SOLAR_OUTPUT_NEBULA_PER_S = 0.0
SOLAR_WING_HP = 30.0
SOLAR_HITBOX_WIDEN_FRACTION = 0.25
SOLAR_DEPLOY_S = 2.0
SOLAR_RETRACT_S = 2.0

# Generator
GENERATOR_OUTPUT_PER_S = 14.0
GENERATOR_SIGNATURE_PER_S = 0.5

# RTG (meta unlock, then a depot module). Kept strictly above
# POWER_EMERGENCY_TRICKLE_PER_S: the module a player paid for must out-pay the
# bus every bare hull already carries, or fitting it reads as nothing changing.
RTG_OUTPUT_PER_S = 3.0
RTG_PRICE_SCRAP = 60

# Silent running
SILENT_SIGNATURE_GAIN_MULT = 0.25
SILENT_SIGNATURE_DECAY_PER_S = 1.5

# ============================================================================
# Ammo (tactical; per-weapon magazines)
# ============================================================================

AMMO_BOX_ROUNDS = 60
MISSILES_PER_RACK = 8
AMMO_BOX_PRICE_SCRAP = 20
FABRICATOR_SCRAP_PER_BOX = 10
#: Ballistic weapons hit this much harder per shot than energy weapons.
BALLISTIC_DAMAGE_PREMIUM_MIN = 0.40
BALLISTIC_DAMAGE_PREMIUM_MAX = 0.60

# ============================================================================
# Signature (per-sector, 0 to 100)
# ============================================================================

SIGNATURE_MAX = 100.0
SIGNATURE_BASELINE_PER_S = {1: 0.1, 2: 0.4, 3: 0.8}
#: Silent-running decay never drops the meter below the act floor.
SIGNATURE_FLOOR = {1: 0.0, 2: 20.0, 3: 40.0}

SIGNATURE_RICH_NODE_TAP = 2.0
SIGNATURE_PER_KILL = 1.0
SIGNATURE_REFINERY_BATCH = 12.0
SIGNATURE_VAULT_HACK = 15.0
SIGNATURE_SCREAMER_SURVIVED = 10.0

# ============================================================================
# The conversion bet (all rates in Cores per 10 scrap)
# ============================================================================

CONVERT_SCRAP_UNIT = 10.0
CONVERT_RATE_REFINERY = 1.3
CONVERT_RATE_TRADING_POST = 1.0
CONVERT_RATE_EXTRACTION = 1.0
CONVERT_RATE_DEATH = 0.4
#: A cheap early doctrine node raises the death rate to this.
CONVERT_RATE_DEATH_UPGRADED = 0.6

REFINERY_BATCH_CHANNEL_S = 6.0

# Last Stand (the collapse rule)
LAST_STAND_CONVERT_RATE = 1.0
LAST_STAND_CORES_CAP = 40
LAST_STAND_SHRIKE_ARRIVES_WITHIN_S = 60.0


def cores_from_scrap(scrap: float, rate: float) -> float:
    """Cores produced by converting *scrap* at *rate* Cores per 10 scrap."""
    return scrap / CONVERT_SCRAP_UNIT * rate


# ============================================================================
# Weapons (10, split down the two economies)
# ============================================================================


@dataclass(frozen=True)
class WeaponSpec:
    """One weapon's anchor numbers. ``family`` is "energy", "ballistic" or "utility".

    ``energy_per_shot`` / ``energy_per_s`` are None where the design leaves the
    cost unset; the owner sets those during balance, implementers must not
    invent values here.
    """

    id: str
    family: str
    dps: float
    energy_per_shot: float | None = None
    energy_per_s: float | None = None
    rounds_per_box: int | None = None
    note: str = ""


WEAPONS: dict[str, WeaponSpec] = {
    "pulse_blaster": WeaponSpec("pulse_blaster", "energy", 20.0, energy_per_shot=ENERGY_PULSE_BLASTER_PER_SHOT),
    "scatter_coil": WeaponSpec("scatter_coil", "energy", 35.0, note="DPS at point blank"),
    "arc_beam": WeaponSpec("arc_beam", "energy", 30.0, energy_per_s=ENERGY_ARC_BEAM_PER_S, note="sustained"),
    "mining_laser": WeaponSpec(
        "mining_laser", "energy", 12.0, energy_per_s=ENERGY_MINING_BEAM_PER_S, note="triple DPS against deposits"
    ),
    "nova_mortar": WeaponSpec("nova_mortar", "energy", 70.0, note="area"),
    "rail_lance": WeaponSpec("rail_lance", "ballistic", 45.0, rounds_per_box=AMMO_BOX_ROUNDS),
    "flak_cannon": WeaponSpec("flak_cannon", "ballistic", 55.0, rounds_per_box=AMMO_BOX_ROUNDS, note="against shoals"),
    "autocannon": WeaponSpec("autocannon", "ballistic", 40.0, rounds_per_box=AMMO_BOX_ROUNDS),
    "missile_rack": WeaponSpec("missile_rack", "ballistic", 60.0, rounds_per_box=MISSILES_PER_RACK, note="burst"),
    "grav_hook": WeaponSpec("grav_hook", "utility", 0.0, note="yanks enemies and salvage"),
}

MINING_LASER_DEPOSIT_MULT = 3.0

# ============================================================================
# Player defence and hull
# ============================================================================

HULL_MAX_STARTER = 100.0

SHIELD_ARC_DEGREES = 120.0
SHIELD_ABSORB_MAX = 60.0
SHIELD_BREAK_LOCKOUT_S = 3.0
#: Stacking emitters widens the arc toward a bubble at this energy multiplier.
SHIELD_BUBBLE_ENERGY_MULT = 3.0
#: Gamepad shield nudge step, degrees per bumper tap.
SHIELD_PAD_NUDGE_DEGREES = 60.0

AUTO_TURRETS_MAX = 4
TURRET_PRICE_SCRAP_MIN = 40
TURRET_PRICE_SCRAP_MAX = 80

HARDPOINTS_STARTER = 2
HARDPOINTS_MAX = 4

# ============================================================================
# Flight feel (drift model and juice anchors)
# ============================================================================

INERTIAL_DAMPENING = 0.90
#: Camera leads the aim by this fraction of screen width.
CAMERA_AIM_LEAD_FRACTION = 0.12
AFTERBURNER_IGNITION_RAMP_S = 0.2
#: Releasing all keys drifts the ship this many ship lengths before stopping.
RELEASE_DRIFT_SHIP_LENGTHS = 1.5
#: The hull's length in world units; the unit RELEASE_DRIFT_SHIP_LENGTHS is
#: quoted in, and the mesh height ``ship.py`` builds the cone at.
SHIP_LENGTH_UNITS = 1.8
RAILGUN_RECOIL_PX = 40.0
HIT_STOP_MIN_MS = 30.0
HIT_STOP_MAX_MS = 60.0
KILL_COMBO_WINDOW_S = 2.0
#: Gamepad aim-assist magnetism cone, degrees.
AIM_ASSIST_CONE_DEGREES = 12.0

# ============================================================================
# Enemies (9 archetypes plus elites and set-pieces)
# ============================================================================


@dataclass(frozen=True)
class EnemySpec:
    """One archetype's anchors: threat-budget cost, HP, damage per hit."""

    id: str
    threat: int
    hp: float
    damage: float
    note: str = ""


ENEMIES: dict[str, EnemySpec] = {
    # A mite's hp sits exactly on one pulse-blaster round (dps 20 / rate 5), so
    # the starter kit pops a splinter per hit; at the design's first-pass 5.0
    # every round left a sliver and the whole shoal read as spongy.
    "mite": EnemySpec("mite", 1, 4.0, 2.0, note="shoals of 8 to 20 on one flow field"),
    "skimmer": EnemySpec("skimmer", 2, 25.0, 0.0, note="steals floating salvage, never shoots"),
    "lancer": EnemySpec("lancer", 3, 60.0, 12.0, note="dash telegraph line drawn 0.5 s early"),
    "mag_mine": EnemySpec("mag_mine", 2, 10.0, 20.0, note="lunges once the ship is inside 8 units"),
    "welder": EnemySpec("welder", 4, 80.0, 0.0, note="repair umbilical, broken by flying through it"),
    "bombardier": EnemySpec("bombardier", 5, 90.0, 18.0, note="stand-off mortars, painted reticles"),
    "screamer": EnemySpec("screamer", 2, 20.0, 0.0, note="+10 signature if alive 8 s after aggro"),
    "husk_turret": EnemySpec("husk_turret", 3, 150.0, 8.0, note="damage is per beam tick"),
    "herald": EnemySpec("herald", 4, 70.0, 10.0, note="pours in at T-30, drops Fletchings"),
}

WARDEN = EnemySpec("warden", 15, 1600.0, 15.0, note="stationary mini-boss with a rotating shield arc")
MAGISTRATE = EnemySpec("magistrate", 0, 900.0, 14.0, note="named bounty hunter, jumps in at notoriety 40+")
MAGISTRATE_COUNT = 3
MAGISTRATE_NOTORIETY_THRESHOLD = 40
MAGISTRATE_SCRAP_DROP_MIN = 60
MAGISTRATE_SCRAP_DROP_MAX = 120

MITE_SHOAL_MIN = 8
MITE_SHOAL_MAX = 20
SCREAMER_AGGRO_TIMER_S = 8.0
LANCER_TELEGRAPH_S = 0.5
ENEMY_FIRE_TELEGRAPH_S = 0.3
SPAWN_EDGE_CHEVRON_S = 1.0

#: Hard cap on concurrent enemies (multimesh-instanced).
ENEMY_HARD_CAP = 120

# ============================================================================
# Enemy speeds and engagement ranges
#
# Two rules govern this table, and both were bought with a playtest.
#
# **Speed.** Every hostile speed is quoted as a multiple of the player's cruise
# speed, because that is the only frame in which "can I disengage?" has an
# answer. The Shrike alone is allowed past the afterburner ceiling; a hostile
# that outruns the burner has taken the decision away from the player, and the
# first five minutes stop being a game. The one licensed exception is a burst:
# a Lancer's dash beats the burner for the two thirds of a second it lasts,
# which is a dodge rather than a chase.
#
# **Range.** Every engagement range is quoted against what the camera actually
# shows. A telegraph fired from off-screen is not a telegraph, so a trigger
# range wider than the visible field is a bug however good the wind-up looks.
# ============================================================================

#: The player's cruise top speed, world units per second (16.2): the speed at
#: which the dampened drift model coasts RELEASE_DRIFT_SHIP_LENGTHS hull
#: lengths after release at the 60 Hz fixed step. ``ship.CRUISE_SPEED`` binds
#: to this, so the table below and the flight model cannot drift apart.
PLAYER_CRUISE_SPEED = RELEASE_DRIFT_SHIP_LENGTHS * SHIP_LENGTH_UNITS * 60.0 * (1.0 - INERTIAL_DAMPENING)
#: The afterburner lifts both the acceleration and the ceiling by this much;
#: ``ship.AFTERBURNER_SPEED_MULT`` binds to it.
PLAYER_AFTERBURNER_SPEED_MULT = 1.8
#: The ceiling no hostile but the Shrike may hold, world units per second.
PLAYER_AFTERBURNER_SPEED = PLAYER_CRUISE_SPEED * PLAYER_AFTERBURNER_SPEED_MULT

#: What the camera shows of the flight plane at the design's pitch and distance,
#: world units. Engagement ranges are quoted against these two numbers.
VISIBLE_FIELD_WIDTH = 77.0
VISIBLE_FIELD_HEIGHT = 39.5


def enemy_speed(cruise_multiple: float) -> float:
    """A hostile speed, quoted as a multiple of the player's cruise speed."""
    return PLAYER_CRUISE_SPEED * cruise_multiple


# Mites: slower than a cruising ship, so a shoal is a thing you leave rather
# than a thing you outrun, and the telegraphed surge is the only time it gains.
MITE_SPEED = enemy_speed(0.70)
MITE_SURGE_SPEED = enemy_speed(1.10)
MITE_SURGE_RANGE = 24.0

# Skimmers: exactly as fast as the ship while hunting, and faster while running
# for the edge with your salvage, but never faster than the burner. Chasing one
# down is a fuel decision, not an impossibility.
SKIMMER_SPEED = enemy_speed(1.00)
SKIMMER_FLEE_SPEED = enemy_speed(1.50)
SKIMMER_IDLE_SPEED = enemy_speed(0.35)
SKIMMER_GRAB_RADIUS = 3.0
#: How far a loaded Skimmer runs before it is gone with the mote.
SKIMMER_ESCAPE_DISTANCE = 60.0

# Lancers: they close slightly slower than you cruise, hold at a distance that
# fits on screen, and buy their damage with a dash the burner cannot match for
# the two thirds of a second it lasts.
LANCER_APPROACH_SPEED = enemy_speed(0.95)
LANCER_DASH_SPEED = enemy_speed(2.20)
LANCER_STANDOFF = 15.0
LANCER_DASH_RANGE = 25.0
LANCER_DASH_DISTANCE = 22.0

# Mag-mines: they drift, and the lunge triggers close enough that the white
# flash and the lunge both happen well inside the frame.
MAG_MINE_DRIFT_SPEED = enemy_speed(0.20)
MAG_MINE_LUNGE_SPEED = enemy_speed(1.60)
MAG_MINE_LUNGE_RANGE = 8.0

# Welders: slow support that has to be caught, and an umbilical short enough to
# see both ends of.
WELDER_SPEED = enemy_speed(0.70)
WELDER_UMBILICAL_RANGE = 24.0
WELDER_TETHER_DISTANCE = 12.0
WELDER_LOITER_DISTANCE = 30.0
#: How near the umbilical the ship must pass to shear it.
WELDER_UMBILICAL_BREAK_RADIUS = 1.8

# Bombardiers: the slowest hull in the roster, holding a stand-off that stays
# inside the frame so the tube and its reticles are on screen together.
BOMBARDIER_SPEED = enemy_speed(0.55)
BOMBARDIER_STANDOFF_DISTANCE = 26.0
BOMBARDIER_STANDOFF_BAND = 5.0
BOMBARDIER_MAX_RANGE = 34.0
BOMBARDIER_BLAST_RADIUS = 6.0
#: Random scatter applied to each shell after the lead, in plane units.
BOMBARDIER_SCATTER = 5.0

# Screamers: they run, and slower than you, so the tax is always payable.
SCREAMER_SPEED = enemy_speed(0.90)
SCREAMER_AGGRO_RANGE = 22.0
SCREAMER_FLEE_DISTANCE = 28.0

# Husk turrets: terrain that shoots, with a beam that reaches most of the frame.
HUSK_TURRET_SPEED = 0.0
HUSK_TURRET_BEAM_RANGE = 26.0

# Heralds: the hunter's language at a survivable scale, orbiting inside the
# frame and never able to run the ship down.
HERALD_SPEED = enemy_speed(0.90)
HERALD_ORBIT_RADIUS = 18.0
HERALD_LANCE_RANGE = 22.0
#: Heralds tear in on a ring this far from the ship.
HERALD_SPAWN_RADIUS = 30.0

# ============================================================================
# Contact
#
# Hull-to-hull damage is the only damage in the game with nothing flying
# between the two bodies, so it is the only damage that has to read as a
# collision. An attacker that lands one loses its drive briefly and both hulls
# take a radial impulse apart; without that an enemy slides through the ship
# and the hit registers as a number rather than as a crash.
# ============================================================================

#: How long a hostile's drive is dead after it lands a contact hit.
CONTACT_STALL_S = 0.3
#: Separation velocity the collision puts on the attacker, world units per second.
CONTACT_SEPARATION_IMPULSE = 18.0
#: The share of that impulse the body being hit takes. The ship is the heavier
#: of the two, so it is shoved less than the thing that ran into it.
CONTACT_TARGET_IMPULSE_FRACTION = 0.5
#: How fast a separation impulse bleeds off, as an exponential rate per second.
CONTACT_RECOIL_DAMPING = 6.0

#: Elite modifiers appear past this threat budget.
ELITE_THREAT_THRESHOLD = 25
ELITE_MODIFIERS = ("armoured", "splitting", "emp_laced")

#: Target time-to-kill bands, the tuning contract.
TTK_BANDS_S = {"mite": 0.5, "lancer": 2.0, "warden": 45.0, "shrike_fin": 15.0}

# ============================================================================
# Waves
# ============================================================================

WAVE_BUDGET_BASE = 10
WAVE_BUDGET_PER_SECTOR = 3
WAVE_BUDGET_NOTORIETY_DIVISOR = 10
WAVE_INTERVAL_MIN_S = 35.0
WAVE_INTERVAL_MAX_S = 55.0
WAVE_RECIPES_TARGET = 40


def wave_threat_budget(sector_index: int, notoriety: float) -> float:
    """T = 10 + 3 x sector index + notoriety / 10."""
    return WAVE_BUDGET_BASE + WAVE_BUDGET_PER_SECTOR * sector_index + notoriety / WAVE_BUDGET_NOTORIETY_DIVISOR


# ============================================================================
# The Shrike
# ============================================================================

# Telegraph ladder (seconds before arrival)
SHRIKE_TELEGRAPH_FIRST_S = 60.0
SHRIKE_TELEGRAPH_KLAXON_S = 30.0
#: Per-arrival compression: second arrival warns at T-45, third and later at T-30.
SHRIKE_TELEGRAPH_SECOND_ARRIVAL_S = 45.0
SHRIKE_TELEGRAPH_LATER_ARRIVALS_S = 30.0
#: In the Nebula the T-60 stage is muffled to this.
SHRIKE_TELEGRAPH_NEBULA_S = 20.0

SHRIKE_LOCKOUT_S = 10.0
WARP_SPOOL_S = 5.0
WARP_SPOOL_PENALTY_PER_HIT_S = 0.5
#: Hits a single spool channel absorbs before it breaks outright. The design
#: prices each hit but names no cap; without one the ring never resolves under
#: sustained fire, so the channel fails loudly past this many interruptions.
WARP_SPOOL_MAX_INTERRUPTIONS = 6

#: Jettisoned scrap buys about this much escape time, seconds per scrap dumped.
SHRIKE_FEED_SECONDS_PER_SCRAP = 8.0 / 40.0

SHRIKE_FIN_HP = 250.0
#: Fin plating trims incoming DPS to roughly a third.
SHRIKE_FIN_DAMAGE_TAKEN_MULT = 1 / 3
#: Damage output ramps this much every ramp interval while present.
SHRIKE_RAMP_FRACTION = 0.20
SHRIKE_RAMP_INTERVAL_S = 10.0
#: Third and later arrivals start the ramp already at +20 percent.
SHRIKE_RAMP_START_LATER_ARRIVALS = 0.20

SHRIKE_CRUISE_SPEED_MULT = 1.15
SHRIKE_LANTERN_HULL_DAMAGE = 35.0
SHRIKE_LANTERN_CAPACITOR_BLACKOUT_S = 1.0
SHRIKE_LANTERN_PREBURN_WARNING_S = 1.0
#: The ship is this many times the player ship's length.
SHRIKE_LENGTH_MULT = 8.0

#: Seconds after arrival when every vault is shorn open and every core split.
SHRIKE_CRACK_OPEN_S = 15.0

# ============================================================================
# Quills, Fletchings and the Roost
# ============================================================================

QUILLS_TO_OPEN_ROOST = 5
QUILLS_KEPT_ON_DEATH = 1
FLETCHINGS_PER_QUILL = 10
#: Herald drop rates rise this much per run since your last quill.
FLETCHING_RATE_RISE_PER_RUN = 0.05
ROOST_RETRY_QUILL_COST = 1
ROOST_KILL_CORES = 150
ROOST_FUEL_REQUIRED = 40.0
ROOST_PROVOCATION_NOTORIETY = 60
#: The assembled Lure counts as this much notoriety worth of noise by itself.
LURE_NOTORIETY_EQUIVALENT = 60
LURE_ASSEMBLY_SCRAP = 200
LURE_FRAGMENT_BIOME_TYPES = 3
MIRROR_LANTERN_BLIND_S = 3.0

# ============================================================================
# Notoriety (run-level, 0 to 100)
# ============================================================================

NOTORIETY_MAX = 100
NOTORIETY_VAULT_CRACKED = 5
NOTORIETY_REFINERY_BATCH = 4
NOTORIETY_ELITE_KILL = 3
NOTORIETY_ARRIVAL_SURVIVED = 8
NOTORIETY_QUIET_SECTOR_DECAY = 5

BROKER_NOTORIETY_THRESHOLD = 50
BOUNTY_DOUBLE_NOTORIETY_THRESHOLD = 60

# ============================================================================
# Scrap economy
# ============================================================================

SCRAP_ORE_CHUNK_MIN = 3
SCRAP_ORE_CHUNK_MAX = 8
SCRAP_WRECK_MIN = 15
SCRAP_WRECK_MAX = 40
SCRAP_VAULT_MIN = 60
SCRAP_VAULT_MAX = 150
SCRAP_KILL_MIN = 1
SCRAP_KILL_MAX = 4
SCRAP_BOUNTY_MIN = 60
SCRAP_BOUNTY_MAX = 120

VAULT_HACK_CHANNEL_S = 20.0
#: Deposits are back-loaded: the surface fraction cracks fast, the core pays double.
DEPOSIT_SURFACE_FRACTION = 0.70
DEPOSIT_CORE_FRACTION = 0.30
DEPOSIT_CORE_PAYOUT_MULT = 2.0

TYPICAL_RUN_SCRAP_TIMID = 450
TYPICAL_RUN_SCRAP_GREEDY = 900
TYPICAL_RUN_CORES_MIN = 40
TYPICAL_RUN_CORES_MAX = 110

# Depot stock and prices
DEPOT_STOCK_ITEMS = 6
DEPOT_STOCK_WEAPONS = 2
DEPOT_STOCK_MODULES = 3
DEPOT_STOCK_CONSUMABLES = 1
DEPOT_PITY_SLOTS = 1
DEPOT_REROLL_BASE_SCRAP = 10
DEPOT_REROLL_PRICE_MULT = 2.0
#: How many times one visit may restock the same consumable shelf entry. O2
#: canisters ignore this and honour DEPOT_O2_CANISTERS_PER_VISIT instead.
DEPOT_CONSUMABLE_RESTOCK_LIMIT = 9
#: Fuel cells one visit will sell. Air is rationed to a single canister so a
#: full purse cannot buy its way out of the life-support clock; fuel is
#: rationed far more loosely, because a tank too empty to reach the next node
#: is the one dead end the shop exists to answer. Four cells is five jumps.
DEPOT_FUEL_CELLS_PER_VISIT = 4

MODULE_PRICE_TIER1_MIN = 35
MODULE_PRICE_TIER1_MAX = 60
MODULE_PRICE_TIER2_MIN = 90
MODULE_PRICE_TIER2_MAX = 140
MODULE_PRICE_TIER3_MIN = 180
MODULE_PRICE_TIER3_MAX = 260

# ============================================================================
# Per-act drop tables
# ============================================================================


@dataclass(frozen=True)
class ActDrops:
    """Loot density anchors for one act."""

    scrap_per_sector: tuple[int, int]
    module_tiers_in_wrecks: tuple[int, int]
    fletchings_per_herald_wave: tuple[int, int]
    vaults_per_sector: tuple[int, int]


ACT_DROPS: dict[int, ActDrops] = {
    1: ActDrops((40, 60), (1, 1), (0, 0), (0, 1)),
    2: ActDrops((80, 140), (1, 2), (1, 2), (1, 1)),
    3: ActDrops((140, 220), (2, 3), (2, 4), (1, 2)),
}

NODE_SCRAP_ACT1_MIN = 40
NODE_SCRAP_ACT1_MAX = 60

# ============================================================================
# Biomes (7 plus the Roost)
# ============================================================================


@dataclass(frozen=True)
class BiomeSpec:
    """One biome's resource-pressure inversion, as multipliers on the baseline."""

    id: str
    solar_mult: float = 1.0
    scrap_mult: float = 1.0
    #: Override for the first telegraph stage, seconds; None keeps the ladder.
    telegraph_override_s: float | None = None
    note: str = ""


BIOMES: dict[str, BiomeSpec] = {
    "debris_field": BiomeSpec("debris_field", note="baseline; wrecks, ammo boxes"),
    "solar_shallows": BiomeSpec("solar_shallows", solar_mult=2.0, note="deployed panels are prime flak targets"),
    "ice_field": BiomeSpec("ice_field", scrap_mult=0.5, note="O2 chunks refill life support; slow enemies"),
    "nebula": BiomeSpec(
        "nebula",
        solar_mult=0.0,
        scrap_mult=1.5,
        telegraph_override_s=SHRIKE_TELEGRAPH_NEBULA_S,
        note="spawn directions fogged",
    ),
    "wreck_graveyard": BiomeSpec("wreck_graveyard", note="huge scrap; husk turrets; Skimmers steal salvage"),
    "vent_field": BiomeSpec("vent_field", note="fuel and O2 refills; mag-mine mazes"),
    "broker_claim": BiomeSpec("broker_claim", note="black market barge, docks at notoriety 50+; Warden guarded"),
    "roost": BiomeSpec("roost", note="unique Act 3 node, appears only with the assembled Lure aboard"),
}

#: Ice Field scrap is "poor" in the design; 0.5 is the working multiplier and
#: the owner tunes it at the balance pass.

# ============================================================================
# Modules and sockets
# ============================================================================

MODULES_AT_LAUNCH = 30
BROKER_EXCLUSIVE_MODULES = 8
POOL_EXPANSION_PAIRS = 8
SOCKETS_STARTER_HULL = 6

WAKE_DAMPER_SIGNATURE_MULT = 0.85
WAKE_DAMPER_MINING_SPEED_MULT = 0.85
SENSOR_MAST_CHART_TAG_JUMPS = 2

TYPICAL_RUN_PURCHASES_MIN = 5
TYPICAL_RUN_PURCHASES_MAX = 7

# ============================================================================
# Doctrine tree and meta progression
# ============================================================================

DOCTRINE_NODES = 60
DOCTRINE_BRANCHES = 5
DOCTRINE_NODES_PER_BRANCH = 12
DOCTRINE_MINORS_PER_BRANCH = 7
DOCTRINE_NOTABLES_PER_BRANCH = 4
DOCTRINE_KEYSTONES_PER_BRANCH = 1
DOCTRINE_COST_MINOR = 15
DOCTRINE_COST_NOTABLE = 40
DOCTRINE_COST_KEYSTONE = 90
DOCTRINE_FULL_TREE_CORES = 1775
DOCTRINE_MAX_ACTIVE_KEYSTONES = 2

DOCTRINE_BRANCHES_IDS = ("gunnery", "engineering", "silent_running", "salvage", "predation")
DOCTRINE_KEYSTONES = {
    "gunnery": "dead_reckoning",
    "engineering": "overload_discharge",
    "silent_running": "cold_start",
    "salvage": "magpie_protocol",
    "predation": "quillborn",
}

COLD_START_INVISIBLE_S = 20.0
MAGPIE_SALVAGE_FRACTION = 0.50
DEEP_INSERTION_START_SECTOR = 3
DEEP_INSERTION_START_SIGNATURE = 15.0

# Milestone bounties (Cores), the first-five-runs velocity ramp.
MILESTONE_FIRST_EXTRACTION = 30
MILESTONE_FIRST_VAULT = 20
MILESTONE_FIRST_ELITE_KILL = 20
MILESTONE_FIRST_ACT3_ENTRY = 25
MILESTONE_FIRST_ARRIVAL_SURVIVED = 30

# Run score: scrap earned + Cores banked x 10 + quills x 100 + a depth bonus.
SCORE_CORES_WEIGHT = 10
SCORE_QUILLS_WEIGHT = 100

# Hulls (feat-gated trophies)
HULL_SOCKETS = {"vagrant": 6, "barge": 8, "dart": 4, "hive": 6}
#: Gun mounts per hull, between HARDPOINTS_STARTER and HARDPOINTS_MAX. The Barge
#: is the fortress and takes all four; the Hive spends its third mount on the
#: drone bays it is built around; the Dart buys its speed by staying at two.
HULL_HARDPOINTS = {
    "vagrant": HARDPOINTS_STARTER,
    "barge": HARDPOINTS_MAX,
    "dart": HARDPOINTS_STARTER,
    "hive": 3,
}
BARGE_UNLOCK_SCRAP_CARRIED = 200
DART_SIGNATURE_FILL_MULT = 0.80
HIVE_UNLOCK_HUNT_RANK = 2

# Hunt Ranks (8 ascension tiers; 1 to 4 at launch)
HUNT_RANKS_AT_LAUNCH = 4
HUNT_RANKS_TOTAL = 8
HUNT_RANK_CORE_INCOME_BONUS = 0.10
HUNT_RANK1_SIGNATURE_FILL_MULT = 1.15
HUNT_RANK2_DEPOT_STOCK_ITEMS = 5
HUNT_RANK3_BREACH_BLEED_MULT = 2.0
HUNT_RANK5_MUFFLE_STRENGTH = 0.5
HUNT_RANK6_DEEP_GATE_TOLL = 90.0
HUNT_RANK7_QUILLS_TO_OPEN_ROOST = 6

# Doctrine kits (the free first-depot pick, one of three)
KIT_ARSENAL_FLAK_ROUNDS = 120
#: What each kit delivers, by catalogue id, per design section 4. The Solar
#: Kit keeps the design's composition (solar wings + signature dampener) even
#: though every hull already boots with the first power source it can carry:
#: the grant tops up rather than stacks, so a part whose module is already
#: socketed is skipped and the kit's visible value on a wings-carrying hull is
#: the dampener. A second wing array was never priced and never intended.
KIT_CONTENTS = {
    "solar": ("solar_wings", "signature_dampener"),
    "forge": ("generator", "sentry_turret"),
    "arsenal": ("flak_cannon",),
}

# ============================================================================
# Signal events
# ============================================================================

SIGNAL_EVENT_DECK_SIZE = 12
LOG_FRAGMENTS_TOTAL = 30

# ============================================================================
# Steady Wake assist panel (accessibility; marked on the ledger, locks nothing)
# ============================================================================

ASSIST_SIGNATURE_FILL_MULT = 0.80
ASSIST_DAMAGE_TAKEN_STEPS = (1.0, 0.8, 0.6)
ASSIST_LANTERN_SWEEP_MULT = 0.75


@dataclass(frozen=True)
class AssistSettings:
    """The Steady Wake panel's live state; defaults are everything off."""

    slow_signature: bool = False
    damage_taken_mult: float = 1.0
    slow_lantern: bool = False
    spool_immunity: bool = False
    extra: dict = field(default_factory=dict)