+
+
+
+
+ glitch-state v1 launched=no weapon=unseen shield=unseen boss=unseen completed=no mode=demo
+Progress can't be saved; reload the page.
+ + + + + diff --git a/challenges/glitch-invaders/game/src/app/app.mjs b/challenges/glitch-invaders/game/src/app/app.mjs new file mode 100644 index 0000000..a519cc6 --- /dev/null +++ b/challenges/glitch-invaders/game/src/app/app.mjs @@ -0,0 +1,437 @@ +import { createProgress } from '../../../shared/progress.mjs'; + +import { loadBossResources } from '../boss/boss-loader.mjs'; +import { BUG_DEFINITIONS } from '../bugs/bug-definitions.mjs'; +import { tryRepair } from '../bugs/code-state.mjs'; +import { IncidentTracker } from '../bugs/incident-tracker.mjs'; +import { SimulatedEvidenceProvider } from '../diagnostics/simulated-evidence.mjs'; +import { GameEngine } from '../engine/game-engine.mjs'; +import { createRandom } from '../engine/random.mjs'; +import { CanvasRenderer } from '../render/canvas-renderer.mjs'; +import { publishState } from '../session/monitor-state.mjs'; + +import { BossLoadingView } from '../ui/boss-loading.mjs'; +import { onClick, setText } from '../ui/dom.mjs'; +import { Hud } from '../ui/hud.mjs'; +import { IncidentConsole } from '../ui/incident-console.mjs'; +import { InputController } from '../ui/input.mjs'; +import { completionCard, introCard, OverlayHost, pauseCard } from '../ui/overlays.mjs'; +import { GameLoop } from './game-loop.mjs'; +import { canonicalEncounter, codeForProgress, firstOpenBug, waveForBug } from './resume.mjs'; + +/** How long the banner after a success or patch stays up. */ +const BANNER_MS = 6_000; + +/** The pause after the last repair, so the participant sees the result before the recap. */ +const COMPLETION_DELAY_MS = 1_800; + +/** The seed that makes enemy fire reproducible unless the page asks for another. */ +export const DEFAULT_SEED = 20_260_514; + +/** Find a required element by id. */ +function requireElement(id) { + const element = document.getElementById(id); + if (element === null) { + throw new Error(`the page has no #${id} element`); + } + + return element; +} + +/** The game page. */ +export class GameApp { + options; + now; + stage = requireElement('stage'); + banner = requireElement('banner'); + announcer = requireElement('announcer'); + hud = new Hud(); + overlays = new OverlayHost(requireElement('overlay-root')); + bossView = new BossLoadingView(requireElement('boss-loading')); + engine; + evidence = new SimulatedEvidenceProvider(); + incidentConsole; + input; + loop; + evidenceByBug = new Map(); + tracker; + progress; + code; + lastShieldHit = null; + bannerTimer = null; + pauseOpen = false; + pendingStart = null; + + constructor(options, saved) { + this.options = options; + this.now = options.now ?? (() => performance.now()); + this.progress = saved ?? createProgress(options.config.attemptId); + this.tracker = new IncidentTracker(this.progress); + this.code = codeForProgress(this.progress); + + this.engine = new GameEngine({ + random: createRandom(options.seed ?? DEFAULT_SEED), + code: this.code, + spawnBossResources: (strategy, onTask) => this.spawnBoss(strategy, onTask), + now: this.now, + particleScale: options.reducedMotion ? 0.25 : 1, + }); + this.incidentConsole = new IncidentConsole({ + progressOf: (bug) => this.progress.bugs[bug], + markEvidenceViewed: (bug) => this.tracker.markEvidenceViewed(bug), + useHint: (bug) => this.tracker.useHint(bug), + diagnose: (bug, optionId) => this.tracker.answerDiagnosis(bug, optionId), + applyPatch: (bug, patchId) => this.applyPatch(bug, patchId), + }); + + const canvas = requireElement('arena'); + const renderer = new CanvasRenderer(canvas, { reducedMotion: options.reducedMotion }); + this.input = new InputController({ + onPauseKey: () => this.togglePause(), + isGameActive: () => !this.overlays.isOpen && this.engine.world.phase !== 'ready', + }); + this.loop = new GameLoop((elapsedMs, nowMs) => { + this.engine.update(elapsedMs, this.input.current()); + renderer.draw(this.engine.world, nowMs); + this.bossView.update(this.engine.world, this.now()); + this.hud.update(this.progress, this.engine.world); + }); + } + + /** Wire the page, show the briefing or the saved run, and start drawing. */ + begin() { + this.tracker.subscribe((progress) => this.onProgress(progress)); + this.engine.on((event) => this.onEvent(event)); + publishState(document, this.progress); + + this.input.attach(document, { + left: requireElement('pad-left'), + right: requireElement('pad-right'), + fire: requireElement('pad-fire'), + }); + document.addEventListener('keydown', (event) => this.onPauseCardKey(event)); + onClick(requireElement('skip-ahead'), () => { + this.engine.fastForward(); + this.stage.focus(); + }); + for (const id of ['reset-run', 'reset-controls']) { + const button = document.getElementById(id); + if (button !== null) { + onClick(button, () => this.resetRun()); + } + } + this.showOpening(); + this.loop.start(); + } + + /** Load the boss's resources under the strategy the current code uses. */ + spawnBoss(strategy, onTask) { + return loadBossResources({ + strategy, + sleep: (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)), + now: this.now, + ...(onTask === undefined ? {} : { onTask }), + }); + } + + /** Show the briefing for a new run, or the welcome-back card for a saved one. */ + showOpening() { + if (!this.progress.launched) { + this.overlays.show( + introCard({ returning: false, onStart: () => this.startRun() }), + ); + + return; + } + + if (this.progress.completed) { + this.engine.start(1); + this.engine.finish(); + this.overlays.show( + completionCard( + this.progress, + () => this.continuePlaying(), + () => this.resetRun(), + ), + ); + + return; + } + + const bug = firstOpenBug(this.progress); + if (bug === null) { + return; + } + const stage = this.progress.bugs[bug].stage; + this.pendingStart = () => { + if (stage === 'unseen') { + this.engine.start(waveForBug(bug)); + + return; + } + this.engine.restoreIncident(bug); + this.openRestoredIncident(bug); + }; + this.overlays.show( + introCard({ returning: true, onStart: () => this.resumeRun() }), + ); + } + + /** The participant pressed Start. */ + startRun() { + this.tracker.launch(); + this.closeCard(); + this.engine.start(1); + this.announce('Run started. Move with the arrow keys, fire with Space.'); + } + + /** The participant pressed Resume on the welcome-back card. */ + resumeRun() { + this.closeCard(); + this.pendingStart?.(); + this.pendingStart = null; + this.announce('Welcome back. Your run was restored.'); + } + + /** Close the card on screen and put focus back on the arena. */ + closeCard() { + this.pauseOpen = false; + this.overlays.hide(this.stage); + } + + /** Pause or resume from the keyboard. */ + togglePause() { + if (this.overlays.isOpen || this.engine.world.phase !== 'playing') { + return; + } + this.engine.pause(); + this.input.releaseAll(); + this.pauseOpen = true; + this.overlays.show(pauseCard(() => this.resumeFromPause())); + } + + /** Close the pause card and continue. */ + resumeFromPause() { + this.engine.resume(); + this.closeCard(); + } + + /** Let P or Escape close the pause card. */ + onPauseCardKey(event) { + if ( + !event.defaultPrevented && + this.pauseOpen && + (event.code === 'KeyP' || event.code === 'Escape') + ) { + event.preventDefault(); + this.resumeFromPause(); + } + } + + /** React to what the engine reports. */ + onEvent(event) { + switch (event.type) { + case 'weapon-jammed': + this.openIncident({ + bug: 'weapon', + jam: { + weaponId: event.error.weaponId, + availableWeapons: event.availableWeapons, + error: event.error, + }, + }); + break; + case 'shield-hit': + this.lastShieldHit = event; + break; + case 'ship-down': + if (event.cause === 'shield-failure' && this.lastShieldHit !== null) { + this.openIncident({ + bug: 'shield', + failure: { + incomingDamage: this.lastShieldHit.incomingDamage, + actualDamage: this.lastShieldHit.outcome.actualDamage, + hullBefore: this.lastShieldHit.hullBefore, + hullAfter: this.lastShieldHit.hullAfter, + }, + }); + } + break; + case 'boss-online': + if (event.stalled) { + this.openIncident({ + bug: 'boss', + stall: { + totalMs: event.result.totalMs, + spans: event.result.spans.map((span) => ({ + name: span.name, + operation: span.op, + startMs: span.startMs, + durationMs: span.durationMs, + })), + }, + }); + } + break; + case 'verification-passed': + this.onVerified(event.bug); + break; + case 'pickup-collected': + this.announce(event.kind === 'fanout' ? 'Fan-out upgrade equipped.' : 'Shield equipped.'); + break; + case 'wave-started': + case 'enemy-destroyed': + case 'pickup-spawned': + case 'volley-fired': + case 'ship-restored': + case 'boss-loading': + break; + case 'run-finished': + if (this.freeplayActive) { + this.freeplayActive = false; + const bossDefeated = this.engine.world.boss === null; + this.showBanner( + bossDefeated + ? '★ Monolith destroyed! All threats eliminated.' + : 'Hull breached by The Monolith. Final score recorded.', + bossDefeated ? 'success' : 'info', + ); + setTimeout(() => this.complete(), 1_400); + } + break; + } + } + + /** A failure just happened in play: record it and open the console on its evidence. */ + openIncident(encounter) { + const bug = encounter.bug; + this.tracker.encounter(bug); + this.input.releaseAll(); + this.incidentConsole.open(bug); + this.overlays.show(this.incidentConsole.element); + const definition = BUG_DEFINITIONS[bug]; + this.announce( + `${definition.incidentLabel}: ${definition.title}. The Incident Console is open.`, + ); + + void this.evidence.evidenceFor(encounter).then((evidence) => this.deliverEvidence(evidence)); + } + + /** A failure was restored from a saved run: reopen the console on its evidence. */ + openRestoredIncident(bug) { + this.input.releaseAll(); + this.incidentConsole.open(bug); + this.overlays.show(this.incidentConsole.element); + const cached = this.evidenceByBug.get(bug); + if (cached !== undefined) { + this.incidentConsole.showEvidence(cached); + + return; + } + void this.evidence + .evidenceFor(canonicalEncounter(bug)) + .then((evidence) => this.deliverEvidence(evidence)); + } + + /** Remember the evidence and show it if its console is still open. */ + deliverEvidence(evidence) { + this.evidenceByBug.set(evidence.bug, evidence); + this.incidentConsole.showEvidence(evidence); + } + + /** Try a patch from the console. A good one is kept, closes the console, and starts the replay. */ + applyPatch(bug, patchId) { + const trial = tryRepair(bug, patchId, this.code); + this.tracker.recordRepairAttempt(bug, trial.check.ok); + if (!trial.check.ok) { + this.announce(`Patch reverted. ${trial.check.observation}`); + + return trial.check; + } + + this.code = trial.state; + this.engine.setCode(this.code); + this.closeCard(); + this.engine.beginVerification(bug); + this.showBanner(`Patch applied. ${BUG_DEFINITIONS[bug].verifyPrompt}`, 'info'); + this.announce(`Patch applied. ${BUG_DEFINITIONS[bug].verifyPrompt}`); + + return trial.check; + } + + /** The repaired behavior was seen in the arena. */ + onVerified(bug) { + this.tracker.markRepaired(bug); + const definition = BUG_DEFINITIONS[bug]; + this.showBanner(`✓ ${definition.incidentLabel} fixed. ${definition.fixExplanation}`, 'success'); + this.announce(`${definition.title} repaired.`); + + if (this.tracker.allRepaired()) { + setTimeout(() => this.complete(), COMPLETION_DELAY_MS); + } + } + + /** All three incidents are closed: freeze the arena and show the recap. */ + complete() { + this.freeplayActive = false; + this.engine.finish(); + this.input.releaseAll(); + this.hideBanner(); + this.overlays.show( + completionCard( + this.progress, + () => this.continuePlaying(), + () => this.resetRun(), + ), + ); + this.announce('All incidents closed.'); + } + + freeplayActive = false; + + /** Dismiss the completion recap and keep playing in the arena. */ + continuePlaying() { + this.freeplayActive = true; + this.closeCard(); + this.engine.continuePlaying(); + this.showBanner('Boss Showdown: Destroy The Monolith before your hull fails!', 'info'); + this.announce('Continuing play in the arena.'); + } + + /** Clear saved progress and reload the page for a fresh run. */ + resetRun() { + void this.options.store.clear().then(() => this.options.reload()); + } + + /** Save and publish every progress change. */ + onProgress(progress) { + this.progress = progress; + void this.options.store.save(progress); + publishState(document, progress); + } + + /** Show a banner over the arena, replacing any earlier one. */ + showBanner(text, kind) { + this.banner.dataset.kind = kind; + setText(this.banner, text); + this.banner.hidden = false; + if (this.bannerTimer !== null) { + clearTimeout(this.bannerTimer); + } + this.bannerTimer = setTimeout(() => this.hideBanner(), BANNER_MS); + } + + /** Hide the banner. */ + hideBanner() { + this.banner.hidden = true; + if (this.bannerTimer !== null) { + clearTimeout(this.bannerTimer); + this.bannerTimer = null; + } + } + + /** Say something to screen readers. */ + announce(message) { + setText(this.announcer, message); + } +} diff --git a/challenges/glitch-invaders/game/src/app/game-loop.mjs b/challenges/glitch-invaders/game/src/app/game-loop.mjs new file mode 100644 index 0000000..fa1eb0c --- /dev/null +++ b/challenges/glitch-invaders/game/src/app/game-loop.mjs @@ -0,0 +1,38 @@ +/** The animation frame loop: one `step` per frame, with the elapsed time since the last one. */ + +/** Runs a {@link FrameStep} on every animation frame until stopped. */ +export class GameLoop { + step; + handle = null; + previousMs = 0; + + constructor(step) { + this.step = step; + } + + /** Begin looping. Starting twice does nothing. */ + start() { + if (this.handle !== null) { + return; + } + + this.previousMs = performance.now(); + this.handle = requestAnimationFrame((nowMs) => this.frame(nowMs)); + } + + /** Stop looping. */ + stop() { + if (this.handle !== null) { + cancelAnimationFrame(this.handle); + this.handle = null; + } + } + + /** Run one frame and ask for the next. */ + frame(nowMs) { + const elapsedMs = Math.max(0, nowMs - this.previousMs); + this.previousMs = nowMs; + this.step(elapsedMs, nowMs); + this.handle = requestAnimationFrame((next) => this.frame(next)); + } +} diff --git a/challenges/glitch-invaders/game/src/app/resume.mjs b/challenges/glitch-invaders/game/src/app/resume.mjs new file mode 100644 index 0000000..ab4c82a --- /dev/null +++ b/challenges/glitch-invaders/game/src/app/resume.mjs @@ -0,0 +1,56 @@ +/** + * Rebuilding a saved run after a refresh: the code the repaired bugs left behind, and the evidence + * for a failure that was still open. + */ +import { BUG_IDS } from '../../../shared/progress.mjs'; +import { CORRECT_PATCH_IDS, createBrokenCodeState, tryRepair } from '../bugs/code-state.mjs'; + +import { SEQUENTIAL_BOSS_SPANS } from '../diagnostics/evidence-builders.mjs'; +import { WeaponConfigError } from '../weapons/weapons.mjs'; + +/** The code with every already repaired bug fixed. */ +export function codeForProgress(progress) { + let code = createBrokenCodeState(); + for (const bug of BUG_IDS) { + if (progress.bugs[bug].stage === 'repaired') { + code = tryRepair(bug, CORRECT_PATCH_IDS[bug], code).state; + } + } + + return code; +} + +/** The first failure that is not repaired, or `null` when all are. */ +export function firstOpenBug(progress) { + return BUG_IDS.find((bug) => progress.bugs[bug].stage !== 'repaired') ?? null; +} + +/** The wave a run starts at to reach `bug`: the weapon in wave 1, the shield in 2, the boss in 3. */ +export function waveForBug(bug) { + return bug === 'weapon' ? 1 : bug === 'shield' ? 2 : 3; +} + +/** What `bug` looked like when it happened, for evidence rebuilt after a refresh. */ +export function canonicalEncounter(bug) { + switch (bug) { + case 'weapon': + return { + bug, + jam: { + weaponId: 'fanout', + availableWeapons: ['single'], + error: new WeaponConfigError('fanout'), + }, + }; + case 'shield': + return { + bug, + failure: { incomingDamage: 1, actualDamage: 3, hullBefore: 3, hullAfter: 0 }, + }; + case 'boss': + return { + bug, + stall: { totalMs: 4_500, spans: [...SEQUENTIAL_BOSS_SPANS] }, + }; + } +} diff --git a/challenges/glitch-invaders/game/src/boss/boss-loader.mjs b/challenges/glitch-invaders/game/src/boss/boss-loader.mjs new file mode 100644 index 0000000..98c4ff1 --- /dev/null +++ b/challenges/glitch-invaders/game/src/boss/boss-loader.mjs @@ -0,0 +1,77 @@ +/** + * Boss resource loading, with the inefficiencies that are the third intentional failure: the work + * runs one task at a time, and one task repeats work already done at game start. + */ +import { + INIT_AI_MS, + LOAD_ANIMATIONS_MS, + LOAD_SOUNDS_MS, + LOAD_TEXTURES_MS, +} from '../engine/constants.mjs'; + +/** The span operation name every boss load reports under. */ +export const LOAD_SPAN_OP = 'game.resource.load'; + +/** Every load a spawn can run, in the order the shipped code runs them. */ +export const ALL_LOAD_TASKS = [ + { name: 'loadTextures', durationMs: LOAD_TEXTURES_MS }, + { name: 'loadSounds', durationMs: LOAD_SOUNDS_MS }, + { name: 'loadAnimations', durationMs: LOAD_ANIMATIONS_MS }, + { name: 'initializeAI', durationMs: INIT_AI_MS }, +]; + +/** The loads `strategy` performs. Only `parallel-deduplicated` drops the redundant animation load. */ +export function tasksFor(strategy) { + if (strategy === 'parallel-deduplicated') { + return ALL_LOAD_TASKS.filter((task) => task.name !== 'loadAnimations'); + } + + return ALL_LOAD_TASKS; +} + +/** Whether `strategy` starts its loads together. */ +export function runsInParallel(strategy) { + return strategy === 'parallel-all' || strategy === 'parallel-deduplicated'; +} + +/** + * How long a first spawn takes under `strategy`. A cache cannot help on a first spawn, so + * `cached-sequential` costs the same as `sequential`. + */ +export function plannedLoadMs(strategy) { + const durations = tasksFor(strategy).map((task) => task.durationMs); + if (runsInParallel(strategy)) { + return Math.max(...durations); + } + + return durations.reduce((total, duration) => total + duration, 0); +} + +/** Run one load, timing it against `startedAt`. */ +async function runTask(task, options, startedAt, spans) { + const startMs = options.now() - startedAt; + options.onTask?.({ name: task.name, phase: 'start', atMs: startMs }); + + await options.sleep(task.durationMs); + + const endMs = options.now() - startedAt; + spans.push({ name: task.name, op: LOAD_SPAN_OP, startMs, durationMs: endMs - startMs }); + options.onTask?.({ name: task.name, phase: 'end', atMs: endMs }); +} + +/** Load the boss's resources as `options.strategy` dictates and report what actually ran. */ +export async function loadBossResources(options) { + const startedAt = options.now(); + const spans = []; + const tasks = tasksFor(options.strategy); + + if (runsInParallel(options.strategy)) { + await Promise.all(tasks.map((task) => runTask(task, options, startedAt, spans))); + } else { + for (const task of tasks) { + await runTask(task, options, startedAt, spans); + } + } + + return { strategy: options.strategy, totalMs: options.now() - startedAt, spans }; +} diff --git a/challenges/glitch-invaders/game/src/bugs/bug-definitions.mjs b/challenges/glitch-invaders/game/src/bugs/bug-definitions.mjs new file mode 100644 index 0000000..62f05f8 --- /dev/null +++ b/challenges/glitch-invaders/game/src/bugs/bug-definitions.mjs @@ -0,0 +1,120 @@ +/** The three failures, in play order. */ +export const BUG_DEFINITIONS = { + weapon: { + id: 'weapon', + incidentLabel: 'INC-1', + title: 'Jammed weapon', + lens: 'Stack traces', + symptom: 'You grabbed the fan-out upgrade and your cannon stopped firing.', + requiredSections: ['exception', 'stacktrace', 'context'], + question: 'Why did the cannon jam?', + options: [ + { + id: 'no-ammo', + text: 'The cannon ran out of ammo.', + correct: false, + feedback: 'Nothing in the evidence mentions ammo. Re-read the exception message.', + }, + { + id: 'missing-config', + text: 'fire() looked up the fanout weapon and found no configuration for it.', + correct: true, + feedback: '', + }, + { + id: 'slow-cooldown', + text: 'The single weapon has a cooldown that is far too long.', + correct: false, + feedback: + 'The single weapon fired fine before the upgrade. Compare what was requested with what exists.', + }, + ], + hints: [ + 'Read the exception message first. It names exactly one thing.', + 'Compare attemptedWeapon with availableWeapons in the weapon_state context.', + 'fanout was requested, but only single exists. The configuration is missing.', + ], + fixExplanation: + 'Registering fanout gives fire() the entry it looks up: three projectiles, a 24° fan, and a 300 ms cooldown.', + verifyPrompt: 'Collect the upgrade again and fire. Three bolts should leave the ship.', + }, + shield: { + id: 'shield', + incidentLabel: 'INC-2', + title: 'Friendly fire', + lens: 'Breadcrumbs', + symptom: 'The shield was up, one hit landed, and your ship was destroyed.', + requiredSections: ['breadcrumbs', 'context'], + question: 'What was the shield doing when the hit landed?', + options: [ + { + id: 'expired', + text: 'It had already expired, so the hit did full damage.', + correct: false, + feedback: 'Check the breadcrumb that reports whether the shield was active.', + }, + { + id: 'amplified', + text: 'It was active, but it multiplied the damage instead of absorbing it.', + correct: true, + feedback: '', + }, + { + id: 'never-equipped', + text: 'The shield was never equipped.', + correct: false, + feedback: 'The first breadcrumbs show the pickup and the shield switching on.', + }, + ], + hints: [ + 'Follow the breadcrumbs from the pickup to the destroyed ship.', + 'Compare "Actual damage applied" with the expected value in shield_state.', + 'The shield was active, yet damage was 3 where 0 was expected.', + ], + fixExplanation: + 'An active shield now sets the damage to 0 and is consumed, so a hit costs the ship nothing.', + verifyPrompt: 'Collect the shield and let a shot hit you. The ship should survive untouched.', + }, + boss: { + id: 'boss', + incidentLabel: 'INC-3', + title: 'Boss buffering', + lens: 'Performance tracing', + symptom: 'The Monolith took far too long to appear. The game just sat there loading.', + requiredSections: ['waterfall', 'context'], + question: 'In the boss-spawn trace waterfall, which operation takes the longest?', + options: [ + { + id: 'load-textures', + text: 'loadTextures', + correct: false, + feedback: + 'loadTextures takes 1.20 s. Look at the waterfall for an even longer bar (1.80 s).', + }, + { + id: 'load-animations', + text: 'loadAnimations', + correct: true, + feedback: '', + }, + { + id: 'initialize-ai', + text: 'initializeAI', + correct: false, + feedback: + 'initializeAI is the shortest bar at 500 ms. Look for the longest bar in the waterfall.', + }, + ], + hints: [ + 'In the waterfall, the four loads run one after another. Which bar is longest?', + 'Compare the durations in the waterfall: loadTextures (1.20 s), loadSounds (1.00 s), loadAnimations (1.80 s), and initializeAI (500 ms).', + 'loadAnimations takes 1.80 s — the longest span in the trace.', + ], + fixExplanation: + 'Running core loads in parallel with Promise.all and streaming loadAnimations non-blocking cuts the spawn from 4.5 s to 1.2 s.', + verifyPrompt: 'Watch the Monolith spawn again. It should arrive in about a second.', + }, +}; + +/** The failures in play order. */ +export const BUG_ORDER = ['weapon', 'shield', 'boss']; diff --git a/challenges/glitch-invaders/game/src/bugs/code-state.mjs b/challenges/glitch-invaders/game/src/bugs/code-state.mjs new file mode 100644 index 0000000..0a8e8d4 --- /dev/null +++ b/challenges/glitch-invaders/game/src/bugs/code-state.mjs @@ -0,0 +1,225 @@ +/** + * The mutable "code" of the game: the three things a patch can change. The shipped state is + * deliberately broken, and the Incident Console's patches transform it. + */ + +import { plannedLoadMs, tasksFor } from '../boss/boss-loader.mjs'; +import { BOSS_SPAWN_BUDGET_MS } from '../engine/constants.mjs'; +import { resolveShieldHit } from '../shield/shield.mjs'; +import { + createBrokenWeaponTable, + FANOUT_VOLLEY, + fireWeapon, + SINGLE_SHOT, + WeaponConfigError, +} from '../weapons/weapons.mjs'; + +/** The state as shipped, with all three intentional bugs present. */ +export function createBrokenCodeState() { + return { + weapons: createBrokenWeaponTable(), + shield: 'amplify', + bossLoad: 'sequential', + }; +} + +/** The shortest cooldown the weapon loop can tolerate without flooding. */ +const MIN_SAFE_COOLDOWN_MS = 100; + +/** Install `config` as the `fanout` weapon. */ +function withFanout(state, config) { + return { ...state, weapons: { ...state.weapons, fanout: config } }; +} + +/** + * The patches for each failure, in the order the console lists them. Exactly one per failure is + * correct and it is never first, so position gives nothing away; the rest fail their check. + */ +export const REPAIR_PATCHES = { + weapon: [ + { + id: 'add-fanout-zero-cooldown', + title: 'Add fanout with no cooldown', + description: 'Three projectiles and no delay between volleys. Maximum firepower.', + snippet: + 'weapons.fanout = {\n projectileCount: 3,\n spreadDegrees: 24,\n cooldownMs: 0,\n damage: 1,\n};', + apply: (state) => withFanout(state, { ...FANOUT_VOLLEY, cooldownMs: 0 }), + }, + { + id: 'add-fanout-config', + title: 'Add the missing fanout config', + description: + 'Register the complete fan-out volley: 3 projectiles, a 24° fan, 300 ms cooldown.', + snippet: + 'weapons.fanout = {\n projectileCount: 3,\n spreadDegrees: 24,\n cooldownMs: 300,\n damage: 1,\n};', + apply: (state) => withFanout(state, FANOUT_VOLLEY), + }, + { + id: 'add-single-projectile-fanout', + title: 'Register fanout as a basic shot', + description: 'Add a fanout entry that copies the single weapon. Simple, so safe?', + snippet: 'weapons.fanout = { ...weapons.single };', + apply: (state) => withFanout(state, SINGLE_SHOT), + }, + ], + shield: [ + { + id: 'remove-multiplier', + title: 'Remove the ×3 multiplier', + description: 'Let damage pass through normally and keep the shield up.', + snippet: 'if (shieldActive) {\n actualDamage = incomingDamage;\n}', + apply: (state) => ({ ...state, shield: 'pass-through' }), + }, + { + id: 'drop-shield-on-hit', + title: 'Switch the shield off on impact', + description: 'Turn the shield off when it is hit, but still apply the damage.', + snippet: 'if (shieldActive) {\n shieldActive = false;\n actualDamage = incomingDamage;\n}', + apply: (state) => ({ ...state, shield: 'drop-then-pass' }), + }, + { + id: 'shield-absorbs-hit', + title: 'Absorb the hit completely', + description: 'While the shield is active, apply 0 damage and consume the shield.', + snippet: 'if (shieldActive) {\n actualDamage = 0;\n shieldConsumed = true;\n}', + apply: (state) => ({ ...state, shield: 'absorb' }), + }, + ], + boss: [ + { + id: 'parallelize-everything', + title: 'Await all four loads in parallel', + description: + 'Start every load at once with Promise.all, but still wait for the heavy 1.8 s loadAnimations() call before spawning.', + snippet: + 'await Promise.all([\n loadTextures(),\n loadSounds(),\n loadAnimations(), // still blocks for 1.8 s\n initializeAI(),\n]);', + apply: (state) => ({ ...state, bossLoad: 'parallel-all' }), + }, + { + id: 'parallel-without-redundant-load', + title: 'Parallelize core loads, stream animations', + description: + 'Run loadTextures, loadSounds, and initializeAI in parallel, and stream loadAnimations() without blocking spawn.', + snippet: + 'await Promise.all([\n loadTextures(),\n loadSounds(),\n initializeAI(),\n]);\nvoid loadAnimations(); // non-blocking', + apply: (state) => ({ ...state, bossLoad: 'parallel-deduplicated' }), + }, + { + id: 'add-cache-checks', + title: 'Check a cache before each load', + description: + 'Skip a load if its result is cached. On first spawn, all four loads still run one after another.', + snippet: + "if (!cache.has('textures')) await loadTextures();\nif (!cache.has('sounds')) await loadSounds();\nif (!cache.has('anims')) await loadAnimations();\nif (!cache.has('ai')) await initializeAI();", + apply: (state) => ({ ...state, bossLoad: 'cached-sequential' }), + }, + ], +}; + +/** Format milliseconds as seconds with one decimal, such as `1.8 s`. */ +function seconds(milliseconds) { + return `${(milliseconds / 1_000).toFixed(1)} s`; +} + +/** Try firing the upgrade and report whether the result is the intended three-way fan. */ +function checkWeapon(state) { + try { + const { shots, config } = fireWeapon(state.weapons, 'fanout'); + if (shots.length !== 3) { + return { + ok: false, + observation: `The upgrade fired ${shots.length} projectile${shots.length === 1 ? '' : 's'}. A fan-out should fire 3.`, + }; + } + if (config.cooldownMs < MIN_SAFE_COOLDOWN_MS) { + return { + ok: false, + observation: `A ${config.cooldownMs} ms cooldown lets the weapon fire every frame and floods the game loop.`, + }; + } + + return { ok: true, observation: 'The upgrade fired a 3-way fan with a 300 ms cooldown.' }; + } catch (error) { + if (error instanceof WeaponConfigError) { + return { ok: false, observation: error.message }; + } + throw error; + } +} + +/** Hit an active shield and report whether it protected the ship. */ +function checkShield(state) { + const outcome = resolveShieldHit(state.shield, true, 1); + if (outcome.actualDamage > 0) { + return { + ok: false, + observation: outcome.shieldConsumed + ? `The shield switched off, but the hit still landed for ${outcome.actualDamage}. A shield must absorb it.` + : `The shield let ${outcome.actualDamage} damage through and stayed up. A shield must absorb the hit.`, + }; + } + + return { ok: true, observation: 'The shield absorbed the hit: 0 damage, shield consumed.' }; +} + +/** Spawn the boss on a cold start and report whether it stays within the budget. */ +function checkBoss(state) { + const totalMs = plannedLoadMs(state.bossLoad); + const blocksOnAnimations = tasksFor(state.bossLoad).some( + (task) => task.name === 'loadAnimations', + ); + if (totalMs > BOSS_SPAWN_BUDGET_MS) { + return { + ok: false, + observation: `The boss still took ${seconds(totalMs)} to spawn on a cold start. The budget is ${seconds(BOSS_SPAWN_BUDGET_MS)}.`, + }; + } + if (blocksOnAnimations) { + return { + ok: false, + observation: `The boss spawned in ${seconds(totalMs)}, which still blocks on the 1.8 s loadAnimations() call.`, + }; + } + + return { + ok: true, + observation: `The boss spawned in ${seconds(totalMs)} by running core loads in parallel without blocking on loadAnimations.`, + }; +} + +/** Run the behavior check for `bug` against `state`. */ +export function checkRepair(bug, state) { + switch (bug) { + case 'weapon': + return checkWeapon(state); + case 'shield': + return checkShield(state); + case 'boss': + return checkBoss(state); + } +} + +/** + * Try patch `patchId` for `bug` on `state`. A patch that fails its check is reverted, so a wrong + * choice never leaves the game in a half-fixed state. + * + * @throws {Error} when `patchId` is not a patch for `bug`. + */ +export function tryRepair(bug, patchId, state) { + const patch = REPAIR_PATCHES[bug].find((candidate) => candidate.id === patchId); + if (patch === undefined) { + throw new Error(`unknown patch for ${bug}: ${patchId}`); + } + + const patched = patch.apply(state); + const check = checkRepair(bug, patched); + + return { patchId, state: check.ok ? patched : state, check }; +} + +/** The one patch per failure that passes its behavior check, for restoring a saved run. */ +export const CORRECT_PATCH_IDS = { + weapon: 'add-fanout-config', + shield: 'shield-absorbs-hit', + boss: 'parallel-without-redundant-load', +}; diff --git a/challenges/glitch-invaders/game/src/bugs/incident-tracker.mjs b/challenges/glitch-invaders/game/src/bugs/incident-tracker.mjs new file mode 100644 index 0000000..29f00a6 --- /dev/null +++ b/challenges/glitch-invaders/game/src/bugs/incident-tracker.mjs @@ -0,0 +1,207 @@ +/** + * Progress through the three failures. Each failure moves `unseen → encountered → investigated → + * repaired`, one step at a time, and every move is recorded as a milestone the guide can forward. + */ +import { BUG_IDS } from '../../../shared/progress.mjs'; +import { + SCORE_BUG_FOUND, + SCORE_DIAGNOSIS_BASE, + SCORE_DIAGNOSIS_FLOOR, + SCORE_HINT_COST, + SCORE_REPAIR_FIRST_TRY, + SCORE_REPAIR_RETRY, + SCORE_VERIFIED, +} from '../engine/constants.mjs'; +import { BUG_DEFINITIONS } from './bug-definitions.mjs'; + +/** Thrown when an action does not fit the failure's current stage, such as diagnosing before seeing it. */ +export class IllegalBugTransitionError extends Error { + constructor(bug, action, stage) { + super(`cannot ${action} for ${bug} while it is ${stage}`); + this.name = 'IllegalBugTransitionError'; + } +} + +/** The state machine behind the three failures. */ +export class IncidentTracker { + progress; + listeners = new Set(); + + constructor(initial) { + this.progress = structuredClone(initial); + } + + /** A copy of the current progress. */ + snapshot() { + return structuredClone(this.progress); + } + + /** Listen for changes; returns the function that stops listening. */ + subscribe(listener) { + this.listeners.add(listener); + + return () => { + this.listeners.delete(listener); + }; + } + + /** The stage of `bug`. */ + stageOf(bug) { + return this.progress.bugs[bug].stage; + } + + /** Whether every failure is repaired. */ + allRepaired() { + return BUG_IDS.every((bug) => this.progress.bugs[bug].stage === 'repaired'); + } + + /** The participant pressed Start. Safe to call again. */ + launch() { + if (this.progress.launched) { + return; + } + + this.progress.launched = true; + this.record('run-started'); + } + + /** The failure became observable in play. Safe to call again. */ + encounter(bug) { + const entry = this.progress.bugs[bug]; + if (entry.stage !== 'unseen') { + return; + } + + entry.stage = 'encountered'; + this.progress.score += SCORE_BUG_FOUND; + this.record('bug-encountered', bug); + } + + /** The participant opened the console's evidence for `bug`. */ + markEvidenceViewed(bug) { + const entry = this.progress.bugs[bug]; + if (entry.stage === 'unseen') { + throw new IllegalBugTransitionError(bug, 'view evidence', entry.stage); + } + if (entry.evidenceViewed) { + return; + } + + entry.evidenceViewed = true; + this.record('evidence-viewed', bug); + } + + /** + * Reveal the next hint and charge for it. + * + * @returns the index of the newly revealed hint, or `null` when all three are already shown. + */ + useHint(bug) { + const entry = this.progress.bugs[bug]; + if (entry.hintsUsed >= BUG_DEFINITIONS[bug].hints.length) { + return null; + } + + entry.hintsUsed += 1; + this.notify(null); + + return entry.hintsUsed - 1; + } + + /** + * Check a diagnosis. A right answer, given after viewing the evidence, makes the failure + * `investigated`. + * + * @throws {IllegalBugTransitionError} when the evidence has not been viewed yet. + */ + answerDiagnosis(bug, optionId) { + const entry = this.progress.bugs[bug]; + if (entry.stage !== 'encountered' || !entry.evidenceViewed) { + throw new IllegalBugTransitionError(bug, 'diagnose', entry.stage); + } + + const option = BUG_DEFINITIONS[bug].options.find((candidate) => candidate.id === optionId); + if (option === undefined) { + throw new Error(`unknown diagnosis option for ${bug}: ${optionId}`); + } + + entry.diagnosisAttempts += 1; + if (!option.correct) { + this.notify(null); + + return { correct: false, feedback: option.feedback }; + } + + entry.stage = 'investigated'; + this.progress.score += Math.max( + SCORE_DIAGNOSIS_FLOOR, + SCORE_DIAGNOSIS_BASE - SCORE_HINT_COST * entry.hintsUsed, + ); + this.notify(null); + + return { correct: true, feedback: '' }; + } + + /** + * Record that the participant applied a patch. + * + * @throws {IllegalBugTransitionError} when the failure has not been diagnosed. + */ + recordRepairAttempt(bug, correct) { + const entry = this.progress.bugs[bug]; + if (entry.stage !== 'investigated') { + throw new IllegalBugTransitionError(bug, 'attempt a repair', entry.stage); + } + + entry.repairAttempts += 1; + if (correct) { + this.progress.score += + entry.repairAttempts === 1 ? SCORE_REPAIR_FIRST_TRY : SCORE_REPAIR_RETRY; + } + this.record('repair-attempted', bug, correct); + } + + /** + * The repaired behavior was seen working in the game. Completes the run once all three are done. + * + * @throws {IllegalBugTransitionError} when the failure has not been diagnosed. + */ + markRepaired(bug) { + const entry = this.progress.bugs[bug]; + if (entry.stage === 'repaired') { + return; + } + if (entry.stage !== 'investigated') { + throw new IllegalBugTransitionError(bug, 'mark repaired', entry.stage); + } + + entry.stage = 'repaired'; + this.progress.score += SCORE_VERIFIED; + this.record('repair-succeeded', bug); + + if (this.allRepaired() && !this.progress.completed) { + this.progress.completed = true; + this.record('challenge-completed'); + } + } + + /** Append a milestone and tell listeners. */ + record(name, bug, correct) { + const seq = this.progress.milestones.length + 1; + this.progress.milestones.push({ + seq, + name, + ...(bug === undefined ? {} : { bug }), + ...(correct === undefined ? {} : { correct }), + }); + this.notify(name); + } + + /** Tell every listener about the current progress. */ + notify(change) { + const snapshot = this.snapshot(); + for (const listener of this.listeners) { + listener(snapshot, change); + } + } +} diff --git a/challenges/glitch-invaders/game/src/diagnostics/evidence-builders.mjs b/challenges/glitch-invaders/game/src/diagnostics/evidence-builders.mjs new file mode 100644 index 0000000..b60612d --- /dev/null +++ b/challenges/glitch-invaders/game/src/diagnostics/evidence-builders.mjs @@ -0,0 +1,182 @@ +import { BOSS_SPAWN_BUDGET_MS } from '../engine/constants.mjs'; + +/** Format milliseconds as seconds, such as `1.8 s`. */ +function seconds(milliseconds) { + return `${(milliseconds / 1_000).toFixed(1)} s`; +} + +/** + * Where the weapon failure's stack frames point. A unit test checks each line still holds the call + * it names, so these cannot drift from the source unnoticed. + */ +export const WEAPON_STACK_FRAMES = [ + { functionName: 'fireWeapon', file: 'game/src/weapons/weapons.mjs', line: 46, inApp: true }, + { + functionName: 'GameEngine.tryFire', + file: 'game/src/engine/game-engine.mjs', + line: 320, + inApp: true, + }, + { + functionName: 'GameEngine.updatePlayer', + file: 'game/src/engine/game-engine.mjs', + line: 294, + inApp: true, + }, + { + functionName: 'GameEngine.update', + file: 'game/src/engine/game-engine.mjs', + line: 160, + inApp: true, + }, + { functionName: 'GameLoop.frame', file: 'game/src/app/app.mjs', line: 94, inApp: true }, + { functionName: 'requestAnimationFrame', file: '