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
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,11 @@ All notable changes to this project will be documented in this file.

## [Unreleased]

### Added

- The refit bay after sector 2 now opens with a short SPECIAL GUNS ONLINE card: Lance is your main gun from now on, Q (or the swap button on touch screens) switches to Scatter or Seekers, and special guns run on a charge that Lance refills. There is nothing to choose; CONTINUE (or Enter, Space or Escape) takes you to the upgrades. It shows every time a run reaches that refit bay, and at no other.
- In sector 3 the HUD points at the swap until you first use it: `Q SPECIAL GUN` beside the charge bar on a keyboard, a pulsing ring around the swap button on touch screens. It goes away after your first swap and stays away for the rest of the sector.

### 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.
Expand Down
7 changes: 6 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,11 @@ fires automatically. Pressing a key on a hardware keyboard hands steering and fi
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.

The refit bay after sector 2 opens with a short SPECIAL GUNS ONLINE card that explains Lance, the
swap key and the charge. In sector 3 the swap is pointed out until you first use it: a
`Q SPECIAL GUN` label beside the HUD charge bar on a keyboard, a pulsing ring around the swap
button on touch.

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
the gun fires without holding Space (it fires exactly as fast as holding Space would). Screen shake
Expand Down Expand Up @@ -114,7 +119,7 @@ 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
- **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
- **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 or checkpoint load. A short card at the refit bay after sector 2 explains all this
- **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

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 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.
- During a sector, `ShipSystemsRuntime` is the one owner of the run's current ship systems, the current main gun, the special-gun charge and sector 3's first-swap hint. 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
2 changes: 1 addition & 1 deletion docs/level-design.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ 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.
- **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.
- **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. The guns are taught, never picked: the refit bay after sector 2 opens on a one-button SPECIAL GUNS ONLINE card (`planetIntermission/specialGunIntro.ts`, shown on every visit to that bay and no other), and sector 3 only points at the swap until the first one there (`ShipSystemsRuntime.isSwapHintPending`): a `Q SPECIAL GUN` label beside the charge bar on a keyboard, a pulsing ring around the touch swap key.
- **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.
Expand Down
49 changes: 39 additions & 10 deletions src/scenes/PlanetIntermissionScene.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,8 @@ import {
setShipSystem,
type ShipSystemSlotDef,
} from '../config/shipSystems';
import { createSystemPickDialog, type SystemPickDialog } from './planetIntermission/systemPickDialog';
import { createSystemPickDialog } from './planetIntermission/systemPickDialog';
import { createSpecialGunIntroCard, isSpecialGunIntroDue } from './planetIntermission/specialGunIntro';
import Phaser from 'phaser';

import { getLevelConfig, getTotalLevels, isLastLevel } from '@/config/LevelsConfig';
Expand All @@ -22,6 +23,8 @@ import {
import { AUTOSAVE_SLOT_ID, createSaveSlotRecord, writeSaveSlot } from '@/systems/SaveSlotStorage';
import { WarpTransition } from '@/systems/WarpTransition';
import { measureInGame } from '@/ui/dom';
import { isTouchMobileDevice } from '@/utils/device';
import { isHardwareKeyboardDetected } from '@/systems/hardwareKeyboardDetection';
import { rebindSceneLifecycleHandlers } from '@/utils/sceneLifecycle';

import { bindProceedOnInput } from './shared/bindProceedOnInput';
Expand Down Expand Up @@ -49,7 +52,13 @@ export class PlanetIntermissionScene extends Phaser.Scene {
private state!: PlayerStateData;
private warpTransition!: WarpTransition;
private view?: RefitView;
private pickDialog?: SystemPickDialog;
/** The pick dialog or the special-gun card, whichever is open over the bay. */
private dialog?: { destroy: () => void };
/**
* Set once the special-gun card is closed, so a resize restart of this visit does not show it again;
* cleared on leaving, so the next run that reaches this bay sees it once more.
*/
private specialGunIntroClosed = false;
private isFinalMissionComplete = false;
private transitioning = false;
private pointerdownHandler?: () => void;
Expand Down Expand Up @@ -112,7 +121,23 @@ export class PlanetIntermissionScene extends Phaser.Scene {
this.warpTransition = new WarpTransition();
this.warpTransition.create(this);
this.bindContinueInputs();
this.offerShipSystemPick();
this.offerSpecialGunIntro();
}

/** Before the first sector that flies Lance, a card explains the special guns before the shop opens. */
private offerSpecialGunIntro(): void {
if (this.specialGunIntroClosed || !isSpecialGunIntroDue(this.state.level)) {
this.offerShipSystemPick();
return;
}
this.view?.setInert(true);
const touch = isTouchMobileDevice() && !isHardwareKeyboardDetected();
this.dialog = createSpecialGunIntroCard(touch, () => {
this.closeDialog();
this.specialGunIntroClosed = true;
audioManager.playUi();
this.offerShipSystemPick();
});
Comment on lines +135 to +140

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bug: Closing the dialog with Enter allows Phaser's queued Enter keydown event to trigger handleUnfocusedKey('Enter'), accidentally purchasing the first purchasable upgrade card.
Severity: MEDIUM

Suggested Fix

Call stopPropagation() or prevent the default action on the Enter key event within the dialog continue handler, or defer un-inerting the upgrade bay view until the next frame/tick so the queued Enter event is consumed safely.

Prompt for AI Agent
Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.

Location: src/scenes/PlanetIntermissionScene.ts#L135-L140

Potential issue: When closing the "SPECIAL GUNS ONLINE" dialog using the Enter key on
the CONTINUE button, the dialog closes synchronously and immediately un-inerts the
upgrade bay. Because Phaser queues native key events and processes them on a later game
step, the scene's keydown handler then receives the queued Enter event after
`this.dialog` has been reset to undefined. The handler invokes
`view.handleUnfocusedKey('Enter')`, which focuses and purchases the first available
upgrade card without player intent.

Did we get this right? 👍 / 👎 to inform future reviews.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not a bug: the Enter keydown never reaches Phaser. Every UI layer stops propagation of Enter/Space pressed on a focused button (keepNativeKeys in src/ui/dom.ts:42), so the scene's keydown handler does not see the key that closed the card. The e2e test closes the card with Enter on desktop and the bay afterwards still shows 8000 credits and Hull Armor at 0/5.

}

/**
Expand All @@ -133,9 +158,8 @@ export class PlanetIntermissionScene extends Phaser.Scene {
private openSystemPick(slot: ShipSystemSlotDef): void {
const current = this.state.systems[slot.slot];
this.view?.setInert(true);
this.pickDialog = createSystemPickDialog(slot, current, (id) => {
this.pickDialog?.destroy();
this.pickDialog = undefined;
this.dialog = createSystemPickDialog(slot, current, (id) => {
this.closeDialog();
if (id !== current) {
this.state.systems = setShipSystem(this.state.systems, slot.slot, id);
setPlayerState(this.registry, this.state);
Expand All @@ -146,6 +170,11 @@ export class PlanetIntermissionScene extends Phaser.Scene {
});
}

private closeDialog(): void {
this.dialog?.destroy();
this.dialog = undefined;
}

private evaluate(): UpgradeEvaluation[] {
return this.isFinalMissionComplete
? []
Expand All @@ -164,7 +193,7 @@ export class PlanetIntermissionScene extends Phaser.Scene {

this.pointerdownHandler = () => this.continueToNextLevel();
this.keydownHandler = (event: KeyboardEvent) => {
if (this.transitioning || this.pickDialog || event.repeat || NON_PROCEED_KEYS.has(event.code)) return;
if (this.transitioning || this.dialog || event.repeat || NON_PROCEED_KEYS.has(event.code)) return;
if (event.target instanceof Element && event.target.closest('input, select, textarea')) return;
if (!this.view?.handleUnfocusedKey(event.code)) this.continueToNextLevel();
};
Expand All @@ -173,8 +202,7 @@ export class PlanetIntermissionScene extends Phaser.Scene {
}

private handleSceneShutdown(): void {
this.pickDialog?.destroy();
this.pickDialog = undefined;
this.closeDialog();
this.view?.destroy();
this.view = undefined;
if (this.pointerdownHandler) this.input.off('pointerdown', this.pointerdownHandler);
Expand All @@ -201,8 +229,9 @@ export class PlanetIntermissionScene extends Phaser.Scene {
}

private continueToNextLevel(): void {
if (this.transitioning || this.pickDialog) return;
if (this.transitioning || this.dialog) return;
this.transitioning = true;
this.specialGunIntroClosed = false;
audioManager.playUi();
this.view?.leave();

Expand Down
12 changes: 10 additions & 2 deletions src/scenes/gameScene/gameplayFrameBehavior.ts
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,7 @@ interface GameSceneGameplayFrameDelegate {
getGunCharge(): number;
trySwapGun(): GunSwapOutcome;
updateGunCharge(deltaMs: number): boolean;
isSwapHintPending(): boolean;
update(): void;
};
/**
Expand All @@ -63,7 +64,9 @@ interface GameSceneGameplayFrameDelegate {
denied(): void;
};
mobileControls: {
setGunChargeState(gun: MainGunId | null, charge: number): void;
/** True when hints should point at the touch keys rather than the keyboard. */
showsTouchHints(): boolean;
setGunChargeState(gun: MainGunId | null, charge: number, hint: boolean): void;
} | null;
grazeSurge: {
update(): void;
Expand Down Expand Up @@ -91,6 +94,7 @@ interface GameSceneGameplayFrameDelegate {
showBossBar(name: string): void;
hideBossBar(): void;
updateBossHp(hp: number, maxHp: number): void;
setSwapHint(visible: boolean): void;
};
bulletPool: Pick<MainGunVolley, 'fire'>;
/** The nearest live enemy to a point, for seeking shots. */
Expand Down Expand Up @@ -162,7 +166,11 @@ export function createGameSceneGameplayFrameBehavior(
else if (outcome === 'low-charge') delegate.gunSwapFeedback.denied();
}
if (shipSystems.updateGunCharge(delta)) delegate.gunSwapFeedback.swapped('lance');
delegate.mobileControls?.setGunChargeState(shipSystems.getGun(), shipSystems.getGunCharge());
// Until the first swap of sector 3 the swap is pointed out: a pulse on the touch key, else a Q label.
const hint = shipSystems.isSwapHintPending();
const touchHint = hint && (delegate.mobileControls?.showsTouchHints() ?? false);
delegate.mobileControls?.setGunChargeState(shipSystems.getGun(), shipSystems.getGunCharge(), touchHint);
delegate.hud.setSwapHint(hint && !touchHint);
};

const updatePlayerFiring = (time: number): void => {
Expand Down
71 changes: 71 additions & 0 deletions src/scenes/planetIntermission/specialGunIntro.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
import { SPECIAL_GUN_CHARGE } from '../../config/shipSystems';
import { h, mountUiLayer } from '../../ui/dom';

export interface SpecialGunIntroCard {
destroy: () => void;
}

/** The card belongs to the refit bay right before the first sector that flies Lance, and to no other. */
export function isSpecialGunIntroDue(clearedLevel: number): boolean {
return clearedLevel === SPECIAL_GUN_CHARGE.fromLevel - 1;
}

/** The card's lines; touch names the on-screen swap key instead of Q. */
export function describeSpecialGunIntro(touch: boolean): readonly string[] {
return [
'Your main gun is now the LANCE: slower shots that pierce every ship in a line.',
`${touch ? 'Tap the swap key' : 'Press Q'} to switch to SCATTER or SEEKERS.`,
'Special guns run on a charge. When it is empty you drop back to the Lance, which refills it.',
];
}

/**
* A short explanation of the special guns, shown over the refit bay before the shop opens. Nothing to
* choose: CONTINUE (or Enter, Space, Escape) closes it, and focus never leaves it while it is open.
*/
export function createSpecialGunIntroCard(touch: boolean, onContinue: () => void): SpecialGunIntroCard {
const done = h('button', { type: 'button', className: 'ui-btn ui-btn--primary menu-sheet__done' }, 'CONTINUE');
done.addEventListener('click', onContinue);
const sheet = h(
'section',
{
className: 'ui-panel menu-sheet gun-intro',
role: 'dialog',
'aria-modal': 'true',
'aria-labelledby': 'gun-intro-title',
'aria-describedby': 'gun-intro-lines',
tabIndex: -1,
},
h('div', { className: 'ui-frame', 'aria-hidden': 'true' }),
h('p', { className: 'ui-caption' }, 'REFIT BAY · NEW HARDWARE'),
h('h2', { className: 'ui-heading', id: 'gun-intro-title' }, 'SPECIAL GUNS ONLINE'),
h(
'div',
{ className: 'gun-intro__lines', id: 'gun-intro-lines' },
...describeSpecialGunIntro(touch).map((line) => h('p', {}, line))
),
done
);
const modal = h('div', { className: 'ui-modal' }, sheet);
modal.addEventListener('keydown', (event) => {
if (event.code === 'Escape') {
// Handled here: the bay behind must not also read Escape as "carry on".
event.preventDefault();
event.stopPropagation();
onContinue();
} else if (event.code === 'Tab' || event.code.startsWith('Arrow')) {
// One control: Tab and the arrows keep focus on it.
event.preventDefault();
}
});
// A press on the card itself must not pull focus off CONTINUE, or Enter would stop working.
modal.addEventListener('mousedown', (event) => {
if (event.target !== done) event.preventDefault();
});

// Its own layer above the refit bay; the scene makes the bay inert meanwhile.
const layer = mountUiLayer();
layer.append(modal);
done.focus({ preventScroll: true });
return { destroy: () => layer.remove() };
}
Loading
Loading