Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,20 @@

All notable changes to this project will be documented in this file.

## [Unreleased]

### Changed

- Lance is now your main gun from sector 3 on, and Scatter and Seekers are special guns you use on a charge. Press Q (or the swap button on touch screens) to go Lance → Scatter → Seekers → Lance. A special gun runs down a charge meter: a full meter lasts 10 seconds, and when it empties you go back to Lance on your own, with the gun's name flashing over your ship. The meter only refills on Lance, over 30 seconds, and every enemy you destroy tops it up a little. You need a fifth of the meter to leave Lance; below that Q just clicks. Switching between the special guns, or back to Lance, always works.
- The meter starts full at the start of every sector and after you respawn or load a checkpoint. Pausing and hit-stops never run it down.
- The HUD shows the current gun and its charge under your reserve ships from sector 3: amber while a special gun drains it, cyan while Lance refills it. The touch swap button shows the same charge along its foot. Sectors 1 and 2 are unchanged: standard gun, no meter, and Q does nothing.
- `bun run balance:bosses` measures every boss with Lance only; its `--guns` option is gone.

### Removed

- The CHOOSE YOUR MAIN GUN pick after sector 2, the main gun at the refit bay and in the pause panel's SYSTEMS tab, and the gun's name in save slots. Saves from earlier versions still load; the gun they stored is ignored.
- The 2-second wait between gun swaps and the half second of silence after a swap. The charge is the cost now.

## [1.34.0] - 2026-11-13

### Added
Expand Down
9 changes: 5 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,15 +36,15 @@ Open `http://localhost:5173` in your browser.
|-------|--------|
| Arrow keys / WASD | Move ship |
| Space / Click | Fire weapons |
| Q | Swap main gun (once the run has picked one) |
| Q | From sector 3: switch to a special gun while its charge lasts (Lance → Scatter → Seekers → Lance) |
| Esc | Pause (closes the settings sheet on the menu) |

The ship flies with inertia: it builds speed over about a second and slides after you let go.

On touch devices, drag anywhere to fly: the ship follows your finger's movement and the main gun
fires automatically. Pressing a key on a hardware keyboard hands steering and firing to the
keyboard, and the next touch hands them back (tap-to-pause stays available). Once the run has a main
gun, a swap button sits under the pause button.
keyboard, and the next touch hands them back (tap-to-pause stays available). From sector 3, a swap
button under the pause button switches guns and shows the special-gun charge.

Autofire is set in SETTINGS (menu or pause panel). Touch flight autofires by default; turn it off
to fire only while your finger is on the screen. Keyboard and mouse play can turn autofire on, so
Expand Down Expand Up @@ -114,7 +114,8 @@ Bought during the planet intermission screen using score as currency:
- **Fire Rate** — improves firing speed
- **Shield** — increases hit absorption
- **AEGIS Picket** — installs and overclocks automatic flank-defense turrets
- **Ship systems** — free picks after sectors 2, 5 and 8 that change how the ship plays: a main gun (Lance, Scatter, Seekers), a support system (Magnet, Surge Core, Wingman) and a doctrine (Overdrive, Bulwark, Salvager). Picks can be changed freely at any later refit bay, and mid-run: the main gun on Q or the touch swap button, the others from the pause panel
- **Lance and special guns** — from sector 3 the ship flies Lance, a piercing gun. Q (or the touch swap button) switches to Scatter or Seekers for as long as a charge meter lasts: a full meter gives 10 seconds, then the gun returns to Lance. On Lance the meter refills over time and a little with every kill, and you need a fifth of it to switch again. The meter starts full every sector and after every respawn
- **Ship systems** — free picks after sectors 5 and 8 that change how the ship plays: a support system (Magnet, Surge Core, Wingman) and a doctrine (Overdrive, Bulwark, Salvager). Picks can be changed freely at any later refit bay, and mid-run from the pause panel
- **A different run every time** — each run has its own sky and may fly sectors mirrored; RETRY replays the same run, NEW RUN starts a fresh one

Some upgrades unlock later in the campaign and use progression caps so the run scales in a controlled way.
Expand Down
2 changes: 1 addition & 1 deletion docs/architecture-guidelines.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ This document describes the scene boundaries, system contracts, and coding rules

- `src/systems/PlayerState.ts` is the only place that should define registry keys and helper functions for persistent run data.
- Use `getPlayerState`, `setPlayerState`, `saveScoreToState`, `saveCurrentHp`, `advanceToNextLevel`, `getRunSummary`, and `setRunSummary` instead of writing raw registry keys in scenes.
- During a sector, `ShipSystemsRuntime` is the one owner of the run's current ship systems. The gun, the surge, doctrine effects and the pause panel read them from it, and every mid-run change goes through it so the live effects (Wingman's drone, Magnet, the gun-swap cost) and `saveShipSystems` stay in step. Do not copy the systems onto other objects.
- During a sector, `ShipSystemsRuntime` is the one owner of the run's current ship systems, the current main gun and the special-gun charge. The gun, the surge, doctrine effects, the HUD, the touch swap key and the pause panel read them from it, and every mid-run change goes through it so the live effects (Wingman's drone, Magnet, the charge draining and refilling) and `saveShipSystems` stay in step. The gun and its charge are per sector and never saved. Do not copy them onto other objects.
- `PlayerStateData` is the long-lived run state used between scenes.
- `RunSummaryData` is the terminal summary contract used by `GameOverScene` and `VictoryScene`.
- When adding new terminal UI data, extend `RunSummaryData` and update the setter/getter helpers first so every scene reads the same contract.
Expand Down
5 changes: 3 additions & 2 deletions docs/level-design.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,8 @@ shields recharge on every respawn.
Levels 5–10 add payoff without adding player inputs:

- **AEGIS Picket** becomes purchasable after Level 4. Its fixed flank turrets trim chaff with flat-damage bolts while the main gun remains the dominant damage source. Pickets never target bosses.
- **Ship systems** are free one-of-three picks at the refit bay after sectors 2, 5 and 8 (`config/shipSystems.ts`). They change how the ship plays rather than how hard it hits, and are balanced by measurement: each main gun trades single-target damage for one strength and scored inside the standard gun's run-to-run spread in sector 5. Nothing is offered in sectors 1–2, which stay a gentle introduction. A system works without input; the only new input is changing one. Once a slot has a pick the player may change it to another option of that slot: freely at every later refit bay (the picks sit beside the upgrade cards and reopen the pick dialog, which Escape dismisses), the main gun mid-flight on Q or the touch swap key, and support and doctrine from the pause panel's SYSTEMS tab. A gun change in flight costs `GUN_SWAP` (0.5 s of silence, 2 s before the next change, both on the gameplay clock), so swapping mid-fight is a decision and never a free best-of-all-guns; between sectors, at the refit bay, a change is free and has no cooldown. In flight, feedback is a brief name flash over the ship and a short swap sound, and each gun's shots have their own look (the profile's `look`), so the active gun reads from the fire itself; there is no persistent panel. The current pick is saved with the run.
- **Main guns** (`config/shipSystems.ts`): sectors 1–2 fly the standard bolt and have no gun input, so the opening stays a gentle introduction. From sector 3 the home gun is Lance; Scatter and Seekers are special guns borrowed on a charge, not picks. Each gun trades single-target damage for one strength and scored inside the standard gun's run-to-run spread in sector 5. Q or the touch swap key steps Lance → Scatter → Seekers → Lance. One meter, `SPECIAL_GUN_CHARGE`, counted on the gameplay clock, pays for the specials: it drains while one is selected (a full meter lasts 10 s) and returns the gun to Lance at empty; on Lance it refills over 30 s plus a bonus per enemy destroyed; leaving Lance needs at least 0.2 of it, while moving between specials or back to Lance is always allowed. It starts full every sector and after every respawn or checkpoint load, and is never saved. Feedback is a name flash over the ship and a short swap sound on every change (including the automatic return), the quiet click when leaving Lance is refused, each gun's own shot look (the profile's `look`), and the HUD's gun row under the reserve ships: the gun's name and a charge bar that burns amber while a special drains and refills cyan on Lance, with a tick at the threshold. The touch swap key mirrors the bar along its foot.
- **Ship systems** are free one-of-three picks at the refit bay after sectors 5 and 8. They change how the ship plays rather than how hard it hits. A system works without input; the only input is changing one. Once a slot has a pick the player may change it to another option of that slot: freely at every later refit bay (the picks sit beside the upgrade cards and reopen the pick dialog, which Escape dismisses) and mid-run from the pause panel's SYSTEMS tab. The current pick is saved with the run.
- **Run variation** comes from one seed per run (`systems/runVariation.ts`, `systems/gameplayRandom.ts`). It decides the wave choices, whether each sector is mirrored left to right, and the sky. Two rules keep scores comparable: the sky is looks only, and the only layout change is the mirror, which is as hard by symmetry. Never vary wave order, enemy counts or timing by seed. RETRY keeps the seed; NEW RUN draws a new one. Enemies, asteroids and wormholes each draw from their own seeded stream, so one cannot shift another's choices; how far a run gets through a stream still depends on play. Enemy jitter and pickup drops stay unseeded because they depend on how the fight goes.
- **Marked Aces** are sparse authored variants of existing enemies. Their gilded treatment signals 2× durability, 4× score, and exactly one guaranteed power-up.
- **Boss volleys are telegraphed.** For the last 400 ms before every volley the boss's core swells and its hardpoints flash white. Bosses have no stun or bonus-damage window; fights are paced by the wind-up and each attack's cooldown.
Expand Down Expand Up @@ -169,7 +170,7 @@ Difficulty shorthand: G = gentle, R = ramp, H = hard.

### L3: Ember Monsoon (G->R) - planet Cinderreach - motif: ember storm
- Sower + minefield debut; energy-storm returns as the weather.
- First boss: Pyre Herald (barrage), taught by a mid-boss elite wave at 60%. Two gentle phases of two attacks each; it never escalates and needs no gun pick.
- First boss: Pyre Herald (barrage), taught by a mid-boss elite wave at 60%. Two gentle phases of two attacks each; it never escalates and needs no special gun.
- distance 14500, spawnRate 1.35; enemies: fighter 30, sower 18, swarm 27, diver 25.
- Drops: health at the heat front, shield pre-boss.

Expand Down
32 changes: 12 additions & 20 deletions scripts/balance/bossFights.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,13 @@
* Fights every boss with a scripted bot and reports how long each fight took and what it cost.
*
* bun run balance:bosses
* bun run balance:bosses --sectors 6 --guns standard,lance --port 4302
* bun run balance:bosses --sectors 6 --port 4302
* bun run balance:bosses --invulnerable # time to kill even where the bot would die
*
* Starts its own dev server (the browser harness is dev-only), jumps straight to each boss with the
* sector's representative ship, and lets `startBossFight` in the browser harness fly a fixed bot: it
* holds a low line under the boss and steps away from shots that will cross it. Fights run in real
* holds a low line under the boss and steps away from shots that will cross it. Every boss sector flies
* Lance; the bot never spends the special-gun charge. Fights run in real
* time on the gameplay clock (no speed-up), several at once in separate pages; `seconds` is gameplay
* time from the boss alarm to the kill, so pauses and hit-stops do not count.
*/
Expand All @@ -18,13 +19,10 @@ import { createServer } from 'vite';
import type { BossFightReport } from '../../src/browserHarness';
import { getUpgradeByKey, getUpgradeProgressionLimit, type UpgradeKey } from '../../src/config/UpgradesConfig';

const GUNS = ['standard', 'lance', 'scatter', 'seekers'] as const;
type Gun = (typeof GUNS)[number];
const BOSS_SECTORS = [3, 4, 5, 6, 7, 8, 9, 10];

interface Options {
sectors: number[];
guns: Gun[];
parallel: number;
limitSeconds: number;
invulnerable: boolean;
Expand All @@ -41,11 +39,8 @@ function parseOptions(argv: readonly string[]): Options {
flag(name)
?.split(',')
.map((part) => part.trim());
const guns = (list('--guns') ?? [...GUNS]) as Gun[];
if (guns.some((gun) => !GUNS.includes(gun))) throw new Error(`--guns takes ${GUNS.join(',')}`);
return {
sectors: list('--sectors')?.map(Number) ?? BOSS_SECTORS,
guns,
parallel: Number(flag('--parallel') ?? 4),
limitSeconds: Number(flag('--limit') ?? 240),
invulnerable: argv.includes('--invulnerable'),
Expand All @@ -67,12 +62,11 @@ function representativeUpgrades(sector: number): string {

interface FightResult extends BossFightReport {
sector: number;
gun: Gun;
/** Frames per second the page held; the bot needs a real frame rate to dodge like a player. */
fps: number;
}

async function fight(browser: Browser, baseUrl: string, sector: number, gun: Gun, options: Options) {
async function fight(browser: Browser, baseUrl: string, sector: number, options: Options) {
const context = await browser.newContext({ viewport: { width: 1280, height: 720 } });
const page = await context.newPage();
try {
Expand All @@ -81,9 +75,8 @@ async function fight(browser: Browser, baseUrl: string, sector: number, gun: Gun
// Low effects keep several pages at full frame rate; quality never changes the simulation.
window.localStorage.setItem('space-explorer.visualQuality.v1', 'low');
});
const systems = gun === 'standard' ? '' : `&systems=${gun}`;
const upgrades = representativeUpgrades(sector);
await page.goto(`${baseUrl}/?browserHarness=1&startLevel=${sector}&upgrades=${upgrades}${systems}&seed=1`);
await page.goto(`${baseUrl}/?browserHarness=1&startLevel=${sector}&upgrades=${upgrades}&seed=1`);
await page.waitForFunction(
() => window.__SPACE_EXPLORER_BROWSER_HARNESS__?.snapshot().activeScenes.includes('Game') ?? false,
undefined,
Expand All @@ -108,10 +101,10 @@ async function fight(browser: Browser, baseUrl: string, sector: number, gun: Gun
.catch(() => false);
if (!report || report.killed || gameOver || report.seconds > options.limitSeconds) break;
}
if (!report) throw new Error(`Sector ${sector} ${gun}: no fight report`);
if (!report) throw new Error(`Sector ${sector}: no fight report`);
const frames = await page.evaluate(() => window.__SPACE_EXPLORER_BROWSER_HARNESS__!.renderStats.read().frames);
const fps = frames / ((Date.now() - startedAt) / 1000);
return { ...report, sector, gun, fps } satisfies FightResult;
return { ...report, sector, fps } satisfies FightResult;
} finally {
await context.close();
}
Expand All @@ -128,7 +121,7 @@ async function main(): Promise<void> {
if (!address || typeof address === 'string') throw new Error('Dev server did not report a port');
const baseUrl = `http://127.0.0.1:${address.port}`;

const queue = options.sectors.flatMap((sector) => options.guns.map((gun) => ({ sector, gun })));
const queue = [...options.sectors];
const results: FightResult[] = [];
// Without the GPU, headless Chromium renders the game at about 10 fps and the bot reacts too late.
const browser = await chromium.launch({
Expand All @@ -137,9 +130,9 @@ async function main(): Promise<void> {
});
try {
const workers = Array.from({ length: Math.max(1, options.parallel) }, async () => {
for (let job = queue.shift(); job; job = queue.shift()) {
const result = await fight(browser, baseUrl, job.sector, job.gun, options);
console.error(`sector ${result.sector} ${result.gun}: ${result.seconds.toFixed(1)} s`);
for (let sector = queue.shift(); sector !== undefined; sector = queue.shift()) {
const result = await fight(browser, baseUrl, sector, options);
console.error(`sector ${result.sector}: ${result.seconds.toFixed(1)} s`);
results.push(result);
}
});
Expand All @@ -149,12 +142,11 @@ async function main(): Promise<void> {
await server.close();
}

results.sort((a, b) => a.sector - b.sector || GUNS.indexOf(a.gun) - GUNS.indexOf(b.gun));
results.sort((a, b) => a.sector - b.sector);
console.log(`Boss fights${options.invulnerable ? ' (invulnerable bot)' : ''}`);
console.table(
results.map((result) => ({
sector: result.sector,
gun: result.gun,
upgrades: representativeUpgrades(result.sector),
'kill s': result.killed ? Number(result.seconds.toFixed(1)) : `- (${Math.round(result.seconds)})`,
'boss hp': result.killed ? 0 : `${Math.round(result.bossHp)}/${result.bossMaxHp}`,
Expand Down
10 changes: 9 additions & 1 deletion src/browserHarness/snapshot.ts
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,8 @@ export interface BrowserHarnessSnapshot {
audioPauseReasons: readonly AudioPauseReason[];
audioContextState: AudioContextState | null;
levelProgress: number | null;
/** The Game scene's main gun and special-gun charge (0..1); null before sector 3 or outside a sector. */
gun: Readonly<{ id: string; charge: number }> | null;
preload: Readonly<{ status: number; progress: number; texts: readonly string[] }> | null;
texts: readonly Readonly<{ text: string; x: number; y: number; width: number; height: number; shown: boolean }>[];
objects: readonly Readonly<{
Expand Down Expand Up @@ -121,7 +123,12 @@ export function createBrowserHarnessSnapshot(game: Phaser.Game): BrowserHarnessS

const physicsWorld = primaryScene?.physics?.world;
const gameScene = activeScenes.find((scene) => scene.scene.key === 'Game') as
(Phaser.Scene & { levelManager?: { progress: number } }) | undefined;
| (Phaser.Scene & {
levelManager?: { progress: number };
shipSystems?: { getGun(): string | null; getGunCharge(): number };
})
| undefined;
const gunId = gameScene?.shipSystems?.getGun() ?? null;
const preloadScene = game.scene.getScene('Preload');
const preloadTexts = preloadScene.children.list
.filter((child): child is Phaser.GameObjects.Text => child instanceof Phaser.GameObjects.Text)
Expand Down Expand Up @@ -149,6 +156,7 @@ export function createBrowserHarnessSnapshot(game: Phaser.Game): BrowserHarnessS
audioPauseReasons: Object.freeze([...audioManager.getPauseReasons()]),
audioContextState: audioManager.getContextState(),
levelProgress: gameScene?.levelManager?.progress ?? null,
gun: gunId === null ? null : Object.freeze({ id: gunId, charge: gameScene!.shipSystems!.getGunCharge() }),
preload: Object.freeze({
status: preloadScene.sys.settings.status,
progress: preloadScene.load.progress,
Expand Down
Loading
Loading