typescript-game-boss-dormancy-gating

Answer

Root cause (RR-GAP-015): the boss is spawned at level entry — state.boss exists, phase: 'BOSS_INTRO' is set, and the arena rect is captured from the spawned level state — but the render/update/HUD paths in main.ts only checked for the boss's existence, so the fight ran (controller ticked), the boss was drawn, and the HUD bar appeared during level traversal instead of waiting for arena entry.

Fix strategy: leave the spawn exactly where it is. Introduce a dedicated module of pure gate helpers keyed on the existing bossEncounterArmed flag (true = pending/dormant, flipped to false at arena entry), and apply them at the 3 wiring points in main.ts. Nothing else in the game knows about dormancy.

1. New module src/game/logic/bossGates.ts — the pure gates:

import type { BossState } from '../state';

export interface BossHudSnapshot {
  id: string;
  name: string;
  hp: number;
  maxHp: number;
}

/** Wiring point 1 — should the boss controller tick this frame? */
export function bossFightRuns(encounterArmed: boolean, boss: BossState | null): boolean {
  return !encounterArmed && boss !== null;
}

/** Wiring point 2 — should the boss be drawn this frame? */
export function bossRenderable(encounterArmed: boolean, boss: BossState | null): boolean {
  return !encounterArmed && boss !== null;
}

/** Wiring point 3 — HUD snapshot; null while dormant so no bar is drawn. */
export function bossHudSnapshot(
  encounterArmed: boolean,
  boss: BossState | null,
): BossHudSnapshot | null {
  if (encounterArmed || boss === null) return null;
  return { id: boss.id, name: boss.name, hp: boss.hp, maxHp: boss.maxHp }; // immutable copy
}

2. The 3 wiring points in main.ts (update / render / HUD pass):

// Wiring 1 — update loop: controller.update only runs once the fight is live
if (bossFightRuns(state.bossEncounterArmed, state.boss)) {
  updateBossController(state.boss, input, dt); // intro timer only advances here
}

// Wiring 2 — render pass: boss is never drawn while dormant
if (bossRenderable(state.bossEncounterArmed, state.boss)) {
  renderBoss(ctx, state.boss);
}

// Wiring 3 — HUD pass: no boss bar while dormant
const hud = bossHudSnapshot(state.bossEncounterArmed, state.boss);
if (hud !== null) {
  drawBossHud(ctx, hud);
}

3. Spawn stays at level entry — arena rect read from spawned state; the only existing arena-entry handler gains the flag flip:

// main.ts — spawn (unchanged position, level entry)
function spawnBossAtLevelEntry(state: GameState) {
  const arenaRect = findArenaRect(state.level);          // read from spawned level state
  state.boss = {
    id: 'nexus-warden', name: 'Nexus Warden',
    hp: 120, maxHp: 120,
    x: arenaRect.x + arenaRect.w / 2, y: arenaRect.y + arenaRect.h / 2,
    phase: 'BOSS_INTRO', arenaRect,                       // captured once, never re-derived
    updateCount: 0,
  };
  state.bossEncounterArmed = true;                        // dormant until arena entry
}

// main.ts — existing arena-entry trigger, one added flip
function onArenaEntry(state: GameState) {
  state.arenaEntered = true;
  if (state.bossEncounterArmed) state.bossEncounterArmed = false; // gates open
}

4. Capture path keeps immediate visibility (used by Playwright/screenshot capture) — bypasses dormancy by flipping the same flag, so the gates need no special-case branch:

export function spawnBossForCapture(state: GameState) {
  spawnBossAtLevelEntry(state);
  state.bossEncounterArmed = false; // visible on the very first frame
}

5. Machine-readable probe for the hard PASS gate, exposed as window.__rrGap015.read() in the served build; it reuses the same gates so it cannot drift from real behaviour:

export function readProbe(state: GameState): RrGap015Probe {
  return {
    bossSpawned: state.boss !== null,
    bossEncounterArmed: state.bossEncounterArmed,
    bossFightRuns:  bossFightRuns(state.bossEncounterArmed, state.boss),
    bossRendered:   bossRenderable(state.bossEncounterArmed, state.boss),
    bossHudVisible: bossHudSnapshot(state.bossEncounterArmed, state.boss) !== null,
    bossPhase:      state.boss?.phase ?? null,
    bossUpdateCount: state.boss?.updateCount ?? 0,
  };
}