Starship Survivors Wiki

boss-gauntlet-types

3 min read

boss-gauntlet-types

PURPOSE

Type contract + tuning constants for the Boss Gauntlet runner. Defines the per-frame telemetry sample shape, per-boss report shape, run-wide report shape, live progress callback shape, and per-mode config table consumed by the BossGauntletTab in the Ship Playground. No runtime logic — pure shapes + frozen constant tables.

OWNS

  • BossGauntletMode — union of 'smoke' | 'balance' | 'survival' | 'stress'.
  • BossGauntletStatus — union of 'queued' | 'running' | 'passed' | 'failed' | 'skipped' | 'error'.
  • BossTelemetryFrame — per-sample shape (timestamp, boss bar hp, enemy/projectile counts, player hp, frame ms, per-pass VFX/ability ms, layer count).
  • BossGauntletReport — final per-boss outcome including pass flag, durations, kill flag, damage taken, peak projectile/frame/VFX/ability metrics, spawn-correctness flags, error/failReason strings, full telemetry array.
  • BossGauntletRunReport — gauntlet-wide roll-up across all bosses with counts per status + array of per-boss reports.
  • BossGauntletProgress — live callback shape (currentIndex, total, mode, currentBossId, elapsedSec, reports-so-far).
  • BossGauntletModeConfig — per-mode tuning shape (godMode, playerDpsToBoss, timeoutSec, playerLevel, enemyDamageMult, label, description).
  • BOSS_GAUNTLET_MODE_CONFIGS — Record<BossGauntletMode, BossGauntletModeConfig> table with one entry per mode.
  • BOSS_GAUNTLET_ORDER — ordered string[] of boss ids the runner cycles through.
  • TELEMETRY_SAMPLE_EVERY_N_FRAMES — sample-stride constant.
  • PROJECTILE_PERF_GATE — bullet-count perf gate; exceeding it fails the run.

READS FROM

Nothing. Pure type/constant module with no imports.

PUSHES TO

Nothing directly. Consumers:

  • Boss Gauntlet runner (drives playground tests, populates BossGauntletReport + emits BossGauntletProgress).
  • BossGauntletTab UI in the Ship Playground (reads BOSS_GAUNTLET_MODE_CONFIGS for the test-mode picker, renders reports + live progress).

DOES NOT

  • Does not run any tests, simulate any frames, or mutate any state.
  • Does not import boss definitions — only references boss ids as opaque strings in BOSS_GAUNTLET_ORDER.
  • Does not define pass/fail logic — only the shape that holds the verdict.
  • Does not handle rendering, scheduling, or game-loop integration.
  • Does not validate that BOSS_GAUNTLET_ORDER ids exist in data/bosses — that’s the runner’s job.

Signals

None emitted. None consumed. This file is read-only at compile time and runtime.

Entry points

  • Import any of the exported types or constants. No initialization required.
  • Consumers usually destructure BOSS_GAUNTLET_MODE_CONFIGS[mode] to read mode tuning, and iterate BOSS_GAUNTLET_ORDER to schedule per-boss runs.

Pattern notes

  • Per-mode config table is centralised here (not on the runner) so the UI mode-picker and the runner share the same numbers and stay in sync.
  • BossGauntletReport.telemetry is self-contained — once collected a report can be viewed without re-running the gauntlet.
  • Peak metrics in BossGauntletReport exist alongside the full telemetry array — they’re cheap reductions for quick scan, telemetry is kept for charts.
  • Telemetry sample stride (TELEMETRY_SAMPLE_EVERY_N_FRAMES) bounds memory: 60Hz / 10 → 6 samples/sec → ~360 entries per 60s run.
  • Boss-bar HP fields (barHp, barHpMax) are sums across all entities tagged sharesHealthWithBoss or isBoss — the runner is responsible for that aggregation, this file just specifies the contract.
  • VFX/ability per-pass ms fields and bossVfxLayerCount are annotated v5.147.1+ — added later for VFX-perf gating; older consumers tolerate them as required-numeric.
  • status and pass are redundant by design — pass === (status === 'passed') — kept distinct so consumers can scan booleans without re-checking the union.
  • BOSS_GAUNTLET_ORDER hard-codes the 8 boss ids in deliberate run order; changing order or count requires editing this file.

EXTRACT-CANDIDATE

  • BossTelemetryFrame shares the per-pass VFX/ability/layer-count timing fields with the engine’s frame-perf telemetry. If a unified FramePerfSample type emerges elsewhere (rendering perf overlay, prod telemetry), these fields should be lifted into a shared PerfFrameTimings mixin and embedded here.
  • The peak-reduction pattern in BossGauntletReport (peakProjectiles, peakFrameTimeMs, peakBossVfx*Ms, peakTickAllAbilitiesMs, peakBossVfxLayerCount) is duplicated logic across any telemetry-aggregating report. A generic PeakOf<Frame> helper or reducePeaks(samples, keys) utility would unify this if a second runner (e.g. wave gauntlet, mission gauntlet) appears.

Graph View