diff --git a/CHANGELOG.md b/CHANGELOG.md index b61b045..a7ad4a4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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. diff --git a/README.md b/README.md index f7373f9..3301d54 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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 diff --git a/docs/architecture-guidelines.md b/docs/architecture-guidelines.md index 08e3b18..9e9a0ce 100644 --- a/docs/architecture-guidelines.md +++ b/docs/architecture-guidelines.md @@ -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. diff --git a/docs/level-design.md b/docs/level-design.md index b2fd01b..0a855f5 100644 --- a/docs/level-design.md +++ b/docs/level-design.md @@ -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. diff --git a/src/scenes/PlanetIntermissionScene.ts b/src/scenes/PlanetIntermissionScene.ts index d816096..fba9fca 100644 --- a/src/scenes/PlanetIntermissionScene.ts +++ b/src/scenes/PlanetIntermissionScene.ts @@ -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'; @@ -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'; @@ -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; @@ -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(); + }); } /** @@ -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); @@ -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 ? [] @@ -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(); }; @@ -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); @@ -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(); diff --git a/src/scenes/gameScene/gameplayFrameBehavior.ts b/src/scenes/gameScene/gameplayFrameBehavior.ts index 55ca787..ca6941f 100644 --- a/src/scenes/gameScene/gameplayFrameBehavior.ts +++ b/src/scenes/gameScene/gameplayFrameBehavior.ts @@ -52,6 +52,7 @@ interface GameSceneGameplayFrameDelegate { getGunCharge(): number; trySwapGun(): GunSwapOutcome; updateGunCharge(deltaMs: number): boolean; + isSwapHintPending(): boolean; update(): void; }; /** @@ -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; @@ -91,6 +94,7 @@ interface GameSceneGameplayFrameDelegate { showBossBar(name: string): void; hideBossBar(): void; updateBossHp(hp: number, maxHp: number): void; + setSwapHint(visible: boolean): void; }; bulletPool: Pick; /** The nearest live enemy to a point, for seeking shots. */ @@ -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 => { diff --git a/src/scenes/planetIntermission/specialGunIntro.ts b/src/scenes/planetIntermission/specialGunIntro.ts new file mode 100644 index 0000000..540ef1d --- /dev/null +++ b/src/scenes/planetIntermission/specialGunIntro.ts @@ -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() }; +} diff --git a/src/systems/HUD.ts b/src/systems/HUD.ts index 7f26be8..bf3fed8 100644 --- a/src/systems/HUD.ts +++ b/src/systems/HUD.ts @@ -45,6 +45,7 @@ export class HUD { private currentBossMaxHp: number | null = null; private currentGun: MainGunId | null = null; private currentGunCharge: number | null = null; + private swapHint = false; create(scene: Phaser.Scene, levelConfig?: LevelConfig): void { this.scene = scene; @@ -61,6 +62,7 @@ export class HUD { this.currentBossMaxHp = null; this.currentGun = null; this.currentGunCharge = null; + this.swapHint = false; this.bossVisible = false; const levelAccent = levelConfig?.accentColor ?? DEFAULT_ACCENT; @@ -230,6 +232,13 @@ export class HUD { this.renderGunCharge(layout); } + /** The keyboard hint beside the gun row; it only shows while the row does. */ + setSwapHint(visible: boolean): void { + if (visible === this.swapHint) return; + this.swapHint = visible; + this.widgets.gunHint.setVisible(visible && this.currentGun !== null); + } + showBossWarning(): void { this.announcementTweens.showBossWarning(); } @@ -262,6 +271,7 @@ export class HUD { const { gunName, gunChargeTrack, gunChargeFill } = this.widgets; const gun = this.currentGun; for (const widget of [gunName, gunChargeTrack, gunChargeFill]) widget.setVisible(gun !== null); + this.widgets.gunHint.setVisible(this.swapHint && gun !== null); if (gun === null) return; const draining = gun !== 'lance'; gunName.setText(getMainGunProfile(gun).name).setColor(draining ? NEON_TEXT.gold : NEON_TEXT.cyan); diff --git a/src/systems/MobileControls.ts b/src/systems/MobileControls.ts index 22ee50c..210102d 100644 --- a/src/systems/MobileControls.ts +++ b/src/systems/MobileControls.ts @@ -1,5 +1,6 @@ import Phaser from 'phaser'; -import { isTouchMobileDevice } from '../utils/device'; +import { isTouchMobileDevice, prefersReducedMotion } from '../utils/device'; +import { isHardwareKeyboardDetected } from './hardwareKeyboardDetection'; import { getViewportBounds } from '../utils/layout'; import { drawAngledRectPath, NEON } from '../scenes/shared/neonUiTheme'; import { scaleUiGlowAlpha } from '../utils/renderingCompat'; @@ -14,6 +15,9 @@ const PAUSE_BUTTON_RIGHT_INSET = 22; const SWAP_BUTTON_GAP = 14; /** The charge bar redraws in steps, not every frame. */ const SWAP_CHARGE_STEPS = 20; +/** The hint ring sits this far outside the swap key and breathes over one period. */ +const SWAP_HINT_RING_OUTSET = 6; +const SWAP_HINT_PULSE_MS = 700; /** Keeps the dragged ship clear of the very edge so it stays fully visible. */ const DRAG_EDGE_MARGIN = 18; @@ -48,6 +52,10 @@ export class MobileControls { /** Special-gun charge, in `SWAP_CHARGE_STEPS` (the full count = full). */ private swapChargeStep: number = SWAP_CHARGE_STEPS; private swapPressPending: boolean = false; + /** A ring pulses around the swap key until the player first uses it (sector 3). */ + private swapHint: boolean = false; + private swapHintRing: Phaser.GameObjects.Graphics | null = null; + private swapHintPulse: Phaser.Tweens.Tween | null = null; private dragPointerId: number | null = null; private dragState: DragState | null = null; private dragFingerX: number = 0; @@ -115,6 +123,7 @@ export class MobileControls { this.pauseKey.hitArea.on('pointerdown', this.handlePauseButtonDown, this); this.swapKey = createControlKey(scene); this.swapKey.hitArea.on('pointerdown', this.handleSwapButtonDown, this); + this.swapHintRing = scene.add.graphics().setDepth(CONTROLS_DEPTH).setScrollFactor(0); scene.input.on('pointerdown', this.handlePointerDown); scene.input.on('pointermove', this.handlePointerMove); @@ -141,6 +150,8 @@ export class MobileControls { key?.icon.destroy(); key?.hitArea.destroy(); } + this.swapHintPulse?.remove(); + this.swapHintRing?.destroy(); this.scene = null; this.pauseKey = null; @@ -153,6 +164,9 @@ export class MobileControls { this.swapDraining = false; this.swapChargeStep = SWAP_CHARGE_STEPS; this.swapPressPending = false; + this.swapHint = false; + this.swapHintRing = null; + this.swapHintPulse = null; } relayout(): void { @@ -213,11 +227,22 @@ export class MobileControls { this.pauseButtonHandler = handler; } + /** True on a touch device with no hardware keyboard in use: hints then point at the touch keys. */ + showsTouchHints(): boolean { + return this.enabledForTouchDevice && !isHardwareKeyboardDetected(); + } + /** * Shows the swap button only while there is a gun to swap (sector 3 on), with the special-gun charge - * along its foot: amber and draining while a special gun is out, cyan and refilling on Lance. + * along its foot: amber and draining while a special gun is out, cyan and refilling on Lance. `hint` + * pulses a ring around it to point it out. */ - setGunChargeState(gun: MainGunId | null, charge: number): void { + setGunChargeState(gun: MainGunId | null, charge: number, hint: boolean): void { + if (hint !== this.swapHint) { + this.swapHint = hint; + this.syncSwapHintPulse(); + this.refreshVisibility(); + } const available = gun !== null; const draining = available && gun !== 'lance'; const steps = Math.max(0, Math.min(1, charge)) * SWAP_CHARGE_STEPS; @@ -300,6 +325,25 @@ export class MobileControls { const swapVisible = pauseVisible && this.swapAvailable && !this.blocked; setControlKeyVisible(this.pauseKey, pauseVisible, pauseVisible && !this.blocked); setControlKeyVisible(this.swapKey, swapVisible, swapVisible); + this.swapHintRing?.setVisible(swapVisible && this.swapHint); + } + + /** The hint ring breathes while shown; with reduced motion it holds still. */ + private syncSwapHintPulse(): void { + const ring = this.swapHintRing; + if (!ring || !this.scene) return; + this.swapHintPulse?.remove(); + this.swapHintPulse = null; + ring.setAlpha(1); + if (!this.swapHint || prefersReducedMotion()) return; + this.swapHintPulse = this.scene.tweens.add({ + targets: ring, + alpha: { from: 1, to: 0.3 }, + duration: SWAP_HINT_PULSE_MS, + ease: 'Sine.easeInOut', + yoyo: true, + repeat: -1, + }); } private releaseActiveTouches(): void { @@ -346,6 +390,7 @@ export class MobileControls { private updateKeyVisuals(): void { this.updatePauseButtonVisual(); this.updateSwapButtonVisual(); + this.drawSwapHintRing(); } private updatePauseButtonVisual(): void { @@ -393,6 +438,22 @@ export class MobileControls { key.icon.fillTriangle(x - 3, y - 1, x - 3, y + 10, x - 10, y + 4.5); key.hitArea.setPosition(x, y); } + + /** A lit outline just outside the swap key; only its position ever changes. */ + private drawSwapHintRing(): void { + const ring = this.swapHintRing; + if (!ring) return; + const size = PAUSE_BUTTON_SIZE + SWAP_HINT_RING_OUTSET * 2; + const left = this.pauseButtonX - size / 2; + const top = this.swapButtonY - size / 2; + ring.clear(); + drawAngledRectPath(ring, left, top, size, size, 14); + ring.lineStyle(6, NEON.cyan, scaleUiGlowAlpha(0.3)); + ring.strokePath(); + drawAngledRectPath(ring, left, top, size, size, 14); + ring.lineStyle(2, NEON.cyanBright, 0.95); + ring.strokePath(); + } } function createControlKey(scene: Phaser.Scene): ControlKey { diff --git a/src/systems/ShipSystemsRuntime.ts b/src/systems/ShipSystemsRuntime.ts index 9346c7f..b1eb33b 100644 --- a/src/systems/ShipSystemsRuntime.ts +++ b/src/systems/ShipSystemsRuntime.ts @@ -39,6 +39,8 @@ export class ShipSystemsRuntime { /** Null flies the standard gun: sectors before `SPECIAL_GUN_CHARGE.fromLevel`. */ private gun: MainGunId | null; private gunCharge = 1; + /** The first sector with special guns points at the swap key until the player's first swap there. */ + private swapHintPending: boolean; constructor( private readonly scene: Pick & { registry: PlayerStateRegistry }, @@ -49,6 +51,7 @@ export class ShipSystemsRuntime { ) { this.systems = systems; this.gun = level >= SPECIAL_GUN_CHARGE.fromLevel ? 'lance' : null; + this.swapHintPending = level === SPECIAL_GUN_CHARGE.fromLevel; this.syncDrone(); } @@ -65,11 +68,17 @@ export class ShipSystemsRuntime { return this.gunCharge; } + /** True until the first successful swap of the first sector with special guns; false everywhere else. */ + isSwapHintPending(): boolean { + return this.swapHintPending; + } + /** Steps Lance -> Scatter -> Seekers -> Lance. Leaving Lance needs `minToLeaveLance` charge. */ trySwapGun(): GunSwapOutcome { if (this.gun === null) return 'unavailable'; if (this.gun === 'lance' && this.gunCharge < SPECIAL_GUN_CHARGE.minToLeaveLance) return 'low-charge'; this.gun = getNextMainGun(this.gun); + this.swapHintPending = false; return 'swapped'; } diff --git a/src/systems/hud/bootstrapRelayout.ts b/src/systems/hud/bootstrapRelayout.ts index ca8edb1..d972d13 100644 --- a/src/systems/hud/bootstrapRelayout.ts +++ b/src/systems/hud/bootstrapRelayout.ts @@ -4,6 +4,8 @@ import { getVisualQualityProfile } from '../../config/visualQuality'; import { renderGunChargeTrack, renderProgressTrack, renderSurgeTrack } from './meterRenderers'; import type { HudLayoutMetrics } from './statusBarLayout'; +const SWAP_HINT_TEXT = 'Q SPECIAL GUN'; + interface CreateHudWidgetsParams { scene: Phaser.Scene; labelColor: string; @@ -24,6 +26,8 @@ export interface HudWidgets { gunName: Phaser.GameObjects.Text; gunChargeTrack: Phaser.GameObjects.Graphics; gunChargeFill: Phaser.GameObjects.Graphics; + /** `Q SPECIAL GUN` beside the charge bar, until the first swap of sector 3 (keyboard only). */ + gunHint: Phaser.GameObjects.Text; scoreLabel: Phaser.GameObjects.Text; scoreText: Phaser.GameObjects.Text; sectorText: Phaser.GameObjects.Text; @@ -62,6 +66,7 @@ export function createHudWidgets({ scene, labelColor, sectorColor }: CreateHudWi const gunName = label('', neonLabelStyle(11, NEON_TEXT.cyan)).setVisible(false); const gunChargeTrack = graphics(100).setVisible(false); const gunChargeFill = graphics(101).setVisible(false); + const gunHint = label(SWAP_HINT_TEXT, neonLabelStyle(11, NEON_TEXT.gold)).setVisible(false); const scoreLabel = label('SCORE', neonLabelStyle(11, NEON_TEXT.gold)).setOrigin(1, 0); const scoreText = label('0', neonReadoutStyle(24)).setOrigin(1, 0); @@ -129,6 +134,7 @@ export function createHudWidgets({ scene, labelColor, sectorColor }: CreateHudWi gunName, gunChargeTrack, gunChargeFill, + gunHint, scoreLabel, scoreText, sectorText, @@ -196,6 +202,7 @@ export function relayoutHudWidgets(widgets: HudWidgets, layout: HudLayoutMetrics renderSurgeTrack(widgets.surgeTrack, layout); widgets.gunName.setPosition(layout.hullX, layout.gunY - 3); renderGunChargeTrack(widgets.gunChargeTrack, layout); + widgets.gunHint.setPosition(layout.gunHintX, layout.gunY - 3); widgets.scoreLabel.setPosition(layout.scoreRight, layout.scoreLabelY).setVisible(!layout.compact); widgets.scoreText.setFontSize(layout.compact ? 22 : 24).setPosition(layout.scoreRight, layout.scoreY); diff --git a/src/systems/hud/statusBarLayout.ts b/src/systems/hud/statusBarLayout.ts index 1a9d010..ac0ba95 100644 --- a/src/systems/hud/statusBarLayout.ts +++ b/src/systems/hud/statusBarLayout.ts @@ -12,6 +12,8 @@ export const BOSS_BAR_HEIGHT = 12; export const GUN_CHARGE_BAR_HEIGHT = 4; /** Room the gun name takes before the charge bar starts; fits `SEEKERS`. */ const GUN_NAME_WIDTH = 64; +/** Clears the left cluster's plate, which reaches 9px past the hull meter. */ +const GUN_HINT_GAP = 16; /** * Where every HUD instrument sits. Two floating clusters hold the top corners (hull, surge, shields, @@ -40,6 +42,8 @@ export interface HudLayoutMetrics { gunY: number; gunBarX: number; gunBarWidth: number; + /** The first-swap hint, just outside the left cluster on the gun row. */ + gunHintX: number; /** Bottom of the left cluster: under the gun row when it shows, else under the reserve ships. */ hullClusterBottom: number; scoreRight: number; @@ -98,6 +102,7 @@ export function getLayoutMetrics(scene: Phaser.Scene, gunRow: boolean): HudLayou gunY, gunBarX: hullX + GUN_NAME_WIDTH, gunBarWidth: hullWidth - GUN_NAME_WIDTH - 4, + gunHintX: hullX + hullWidth + GUN_HINT_GAP, hullClusterBottom, scoreRight, scoreLabelY: clusterTop, diff --git a/src/ui/ui.css b/src/ui/ui.css index a955e1a..67abef4 100644 --- a/src/ui/ui.css +++ b/src/ui/ui.css @@ -2405,3 +2405,34 @@ font: 12px / 1 var(--f-mono); letter-spacing: 1.5px; } + +/* ---------- special gun intro ---------- */ +/* Higher specificity than the sheet's container profiles, which widen settings to 720px. */ +.menu-sheet.gun-intro { + width: min(100%, 440px); +} + +.gun-intro .ui-caption { + flex: none; +} + +.gun-intro .ui-heading { + --heading-size: 22px; + margin-bottom: 16px; +} + +.gun-intro__lines { + display: flex; + flex-direction: column; + gap: 10px; + overflow-y: auto; + font-size: 15px; + line-height: 1.35; + letter-spacing: 0.3px; + text-transform: none; + color: var(--t-secondary); +} + +.gun-intro .menu-sheet__done.ui-btn { + --done-gap: 22px; +} diff --git a/tests/MobileControlsDrag.test.ts b/tests/MobileControlsDrag.test.ts index f77e1c9..cae830a 100644 --- a/tests/MobileControlsDrag.test.ts +++ b/tests/MobileControlsDrag.test.ts @@ -2,7 +2,7 @@ import { describe, expect, mock, test } from 'bun:test'; import { mockPhaserModule } from './helpers/phaserMock'; mockPhaserModule(); -mock.module('../src/utils/device', () => ({ isTouchMobileDevice: () => true })); +mock.module('../src/utils/device', () => ({ isTouchMobileDevice: () => true, prefersReducedMotion: () => false })); const { MobileControls } = await import('../src/systems/MobileControls'); @@ -18,6 +18,8 @@ function createScene(viewport = { x: 0, y: 0, width: 390, height: 844 }) { const handlers = new Map void>>(); /** Each control key's `pointerdown` handler, in creation order: pause, then swap. */ const keyTaps: Array<(pointer: unknown) => void> = []; + /** Tweens still running: the swap-hint pulse is the only one. */ + const tweens = new Set(); const zone = (): Record => { const target: Record = {}; target.on = (_event: string, handler: (pointer: unknown) => void, context: unknown) => { @@ -43,6 +45,13 @@ function createScene(viewport = { x: 0, y: 0, width: 390, height: 844 }) { }, }, scale: { getViewPort: () => viewport }, + tweens: { + add: () => { + const tween = { remove: () => tweens.delete(tween) }; + tweens.add(tween); + return tween; + }, + }, }; const emit = (event: string, pointer: { id: number; x: number; y: number; wasTouch?: boolean }) => { for (const handler of handlers.get(event) ?? []) handler({ wasTouch: true, ...pointer }); @@ -51,7 +60,7 @@ function createScene(viewport = { x: 0, y: 0, width: 390, height: 844 }) { emit('pointerdown', pointer); keyTaps[index]({ wasTouch: true, ...pointer }); }; - return { scene, emit, tapKey, viewport }; + return { scene, emit, tapKey, viewport, tweens }; } function createControls(viewport?: { x: number; y: number; width: number; height: number }) { @@ -161,7 +170,7 @@ describe('MobileControls gun-swap key', () => { tapKey(SWAP_KEY, { id: 4, ...SWAP }); expect(controls.consumeGunSwapPress()).toBe(false); - controls.setGunChargeState('lance', 1); + controls.setGunChargeState('lance', 1, false); tapKey(SWAP_KEY, { id: 4, ...SWAP }); expect(controls.consumeGunSwapPress()).toBe(true); expect(controls.consumeGunSwapPress()).toBe(false); @@ -170,21 +179,36 @@ describe('MobileControls gun-swap key', () => { test('the swap key never starts a drag, and its spot steers again when there is no key', () => { const { controls, emit } = createControls(); - controls.setGunChargeState('scatter', 0.5); + controls.setGunChargeState('scatter', 0.5, false); emit('pointerdown', { id: 4, ...SWAP }); expect(controls.getDragDesiredVelocity(195, 760, 0, 480)).toBeNull(); emit('pointerup', { id: 4, ...SWAP }); - controls.setGunChargeState(null, 0); + controls.setGunChargeState(null, 0, false); emit('pointerdown', { id: 5, ...SWAP }); expect(controls.getDragDesiredVelocity(195, 760, 0, 480)).toEqual({ vx: 0, vy: 0 }); }); test('pausing drops a tap that has not been handled yet', () => { const { controls, tapKey } = createControls(); - controls.setGunChargeState('lance', 1); + controls.setGunChargeState('lance', 1, false); tapKey(SWAP_KEY, { id: 4, ...SWAP }); controls.setBlocked(true); expect(controls.consumeGunSwapPress()).toBe(false); }); + + test('the swap hint pulses only while asked for, and stops with the controls', () => { + const { controls, tweens } = createControls(); + expect(controls.showsTouchHints()).toBe(true); + controls.setGunChargeState('lance', 1, true); + expect(tweens.size).toBe(1); + controls.setGunChargeState('lance', 1, true); + expect(tweens.size).toBe(1); + controls.setGunChargeState('scatter', 0.9, false); + expect(tweens.size).toBe(0); + + controls.setGunChargeState('lance', 1, true); + controls.destroy(); + expect(tweens.size).toBe(0); + }); }); diff --git a/tests/chainOverdrive.test.ts b/tests/chainOverdrive.test.ts index 8aa03b4..0880c0a 100644 --- a/tests/chainOverdrive.test.ts +++ b/tests/chainOverdrive.test.ts @@ -104,6 +104,7 @@ function createFiringHarness(chainMultiplier: number) { getGunCharge: () => 0, trySwapGun: () => 'unavailable', updateGunCharge: () => false, + isSwapHintPending: () => false, update: () => {}, }, gunSwapFeedback: { swapped: () => {}, denied: () => {} }, @@ -129,6 +130,7 @@ function createFiringHarness(chainMultiplier: number) { showBossBar: () => undefined, hideBossBar: () => undefined, updateBossHp: () => {}, + setSwapHint: () => {}, }, findBulletTarget: () => null, bulletPool: { diff --git a/tests/e2e/shipSystems.spec.ts b/tests/e2e/shipSystems.spec.ts index d67eea4..9525be4 100644 --- a/tests/e2e/shipSystems.spec.ts +++ b/tests/e2e/shipSystems.spec.ts @@ -42,32 +42,80 @@ async function openPause(page: Page, isMobile: boolean): Promise { if (!isMobile) await page.keyboard.up('Escape'); } +/** The keyboard's first-swap hint beside the HUD charge bar in sector 3. */ +const SWAP_HINT = 'Q SPECIAL GUN'; + async function gunState(page: Page) { return (await snapshot(page)).gun; } -test('no main-gun pick after sectors 1 and 2: the refit bay goes straight to the upgrades', async ({ +test('clearing sector 2 explains the special guns once, with nothing to pick; sector 3 points at the swap until it is used', async ({ page, + isMobile, assertNoBrowserErrors, }) => { test.setTimeout(120_000); await pinQualityTier(page, 'low'); await openMenu(page); await startNewRun(page); + const continueButton = page.getByRole('button', { name: /Continue to/ }); + const card = page.getByRole('dialog', { name: 'SPECIAL GUNS ONLINE' }); - for (const level of [1, 2]) { - await page.evaluate((cleared) => window.__SPACE_EXPLORER_BROWSER_HARNESS__!.showPlanetIntermission(cleared), level); - await waitForScene(page, 'PlanetIntermission'); - await expect(page.getByRole('button', { name: /Continue to/ })).toBeVisible(); - await expect(page.getByRole('dialog')).toHaveCount(0); - await expect(page.getByRole('group', { name: 'Ship systems' })).toHaveCount(0); - } + // Sector 1's refit bay goes straight to the upgrades. + await page.evaluate(() => window.__SPACE_EXPLORER_BROWSER_HARNESS__!.showPlanetIntermission(1)); + await waitForScene(page, 'PlanetIntermission'); + await expect(continueButton).toBeVisible(); + await expect(page.getByRole('dialog')).toHaveCount(0); + + // Sector 2's opens on the card: one CONTINUE, no options, the bay out of reach behind it. + await page.evaluate(() => window.__SPACE_EXPLORER_BROWSER_HARNESS__!.showPlanetIntermission(2)); + await expect(card).toBeVisible(); + await expect(card.getByRole('button')).toHaveCount(1); + const done = card.getByRole('button', { name: 'CONTINUE' }); + await expect(done).toBeFocused(); + await expect(card).toContainText('LANCE'); + await expect(card).toContainText(isMobile ? 'Tap the swap key' : 'Press Q'); + await expect(card).not.toContainText(isMobile ? 'Press Q' : 'Tap the swap key'); + expect(await page.locator('.refit').evaluate((element) => (element.closest('.ui-layer') as HTMLElement).inert)).toBe( + true + ); + await expect(page.getByRole('group', { name: 'Ship systems' })).toHaveCount(0); + await page.screenshot({ path: test.info().outputPath('special-gun-intro.png') }); + + if (isMobile) await done.tap(); + else await page.keyboard.press('Enter'); + await expect(card).toHaveCount(0); + await expect(continueButton).toBeVisible(); + await expect(continueButton).toBeInViewport(); + // Closing the card did not carry on to the next sector. + expect((await snapshot(page)).activeScenes).toContain('PlanetIntermission'); await page.screenshot({ path: test.info().outputPath('refit-after-sector-2.png') }); - // Sector 3 flies Lance with a full charge. - await page.getByRole('button', { name: /Continue to/ }).click(); + // Sector 3 flies Lance with a full charge, and the swap is pointed out until the first one. + await continueButton.click(); await waitForScene(page, 'Game'); await expect.poll(() => gunState(page)).toEqual({ id: 'lance', charge: 1 }); + await expect.poll(() => shownTexts(page)).toContain('LANCE'); + // The keyboard gets a label by the charge bar; touch gets a pulse on the swap key instead. + if (isMobile) expect(await shownTexts(page)).not.toContain(SWAP_HINT); + else await expect.poll(() => shownTexts(page)).toContain(SWAP_HINT); + await page.screenshot({ path: test.info().outputPath('sector-3-swap-hint.png') }); + + if (isMobile) await page.touchscreen.tap(TOUCH_KEY_X, TOUCH_SWAP_Y); + else await page.keyboard.press('KeyQ'); + await expect.poll(async () => (await gunState(page))?.id).toBe('scatter'); + await expect.poll(() => shownTexts(page)).not.toContain(SWAP_HINT); + await page.screenshot({ path: test.info().outputPath('sector-3-after-swap.png') }); + + // A later run that clears sector 2 again sees the card again; no other refit bay shows it. + await page.evaluate(() => window.__SPACE_EXPLORER_BROWSER_HARNESS__!.showPlanetIntermission(2)); + await expect(card).toBeVisible(); + await card.getByRole('button', { name: 'CONTINUE' }).click(); + await expect(card).toHaveCount(0); + await page.evaluate(() => window.__SPACE_EXPLORER_BROWSER_HARNESS__!.showPlanetIntermission(3)); + await waitForScene(page, 'PlanetIntermission'); + await expect(page.getByRole('button', { name: /Continue to/ })).toBeVisible(); + await expect(page.getByRole('dialog')).toHaveCount(0); assertNoBrowserErrors(); }); diff --git a/tests/gameplayFrameBehaviorPerformance.test.ts b/tests/gameplayFrameBehaviorPerformance.test.ts index 4ff6aca..73c3f5b 100644 --- a/tests/gameplayFrameBehaviorPerformance.test.ts +++ b/tests/gameplayFrameBehaviorPerformance.test.ts @@ -79,6 +79,7 @@ function createHarness(level = 1): { getGunCharge: () => 0, trySwapGun: () => 'unavailable', updateGunCharge: () => false, + isSwapHintPending: () => false, update: () => {}, }, gunSwapFeedback: { swapped: () => {}, denied: () => {} }, @@ -106,6 +107,7 @@ function createHarness(level = 1): { showBossBar: () => undefined, hideBossBar: () => undefined, updateBossHp: () => {}, + setSwapHint: () => {}, }, findBulletTarget: () => null, bulletPool: { fire: () => {} }, diff --git a/tests/rivalDuel.test.ts b/tests/rivalDuel.test.ts index b1868de..2af769b 100644 --- a/tests/rivalDuel.test.ts +++ b/tests/rivalDuel.test.ts @@ -132,7 +132,7 @@ describe('rival duel hold', () => { let duel: { hp: number; maxHp: number } | null = { hp: 30, maxHp: 30 }; const waveUpdate = mock(); const levelUpdate = mock(); - const hud = { showBossBar: mock(), hideBossBar: mock(), updateBossHp: mock() }; + const hud = { showBossBar: mock(), hideBossBar: mock(), updateBossHp: mock(), setSwapHint: mock() }; const emit = mock(); const noop = (): void => {}; const behavior = createGameSceneGameplayFrameBehavior({ @@ -147,7 +147,13 @@ describe('rival duel hold', () => { getLastLifeHelperWing: () => null, getPicketTurrets: () => null, grazeSurge: { update: noop }, - shipSystems: { update: noop, getSystems: () => ({}), getGun: () => null, updateGunCharge: () => false }, + shipSystems: { + update: noop, + getSystems: () => ({}), + getGun: () => null, + updateGunCharge: () => false, + isSwapHintPending: () => false, + }, mobileControls: null, waveManager: { update: waveUpdate, updateBossAdds: noop, getDuelHull: () => duel }, levelManager: { diff --git a/tests/specialGunCharge.test.ts b/tests/specialGunCharge.test.ts index 6e40558..00c80da 100644 --- a/tests/specialGunCharge.test.ts +++ b/tests/specialGunCharge.test.ts @@ -204,12 +204,13 @@ describe('live ship-system changes', () => { }); }); -function createFrameHarness(level: number) { +function createFrameHarness(level: number, touch = false) { const { runtime } = createRuntime(level); const clock = new GameplayClock(); const shots: number[] = []; const feedback: string[] = []; const buttonStates: Array<[string | null, number]> = []; + const hints = { hud: false, key: false }; let swapPressed = false; let paused = false; let realTime = 0; @@ -246,7 +247,13 @@ function createFrameHarness(level: number) { swapped: (gun) => feedback.push(gun), denied: () => feedback.push('denied'), }, - mobileControls: { setGunChargeState: (gun, charge) => buttonStates.push([gun, charge]) }, + mobileControls: { + showsTouchHints: () => touch, + setGunChargeState: (gun, charge, hint) => { + buttonStates.push([gun, charge]); + hints.key = hint; + }, + }, grazeSurge: { update: () => {} }, waveManager: { update: () => {}, updateBossAdds: () => {}, getDuelHull: () => null }, levelManager: { @@ -259,7 +266,14 @@ function createFrameHarness(level: number) { }, scoreManager: { getChainState: () => ({ chain: 0, multiplier: 1 }) }, events: { emit: () => {} }, - hud: { showBossBar: () => {}, hideBossBar: () => {}, updateBossHp: () => {} }, + hud: { + showBossBar: () => {}, + hideBossBar: () => {}, + updateBossHp: () => {}, + setSwapHint: (visible) => { + hints.hud = visible; + }, + }, bulletPool: { fire: () => shots.push(clock.now) }, findBulletTarget: () => null, effectsManager: { createMuzzleFlash: () => {}, updateLighting: () => {} }, @@ -284,6 +298,7 @@ function createFrameHarness(level: number) { shots, feedback, buttonStates, + hints, run, pressSwap: () => { swapPressed = true; @@ -354,3 +369,51 @@ describe('special guns during play', () => { expect(harness.shots.length).toBeGreaterThan(0); }); }); + +describe('first-swap hint', () => { + test('only the first sector with special guns starts with it pending', () => { + expect(createRuntime(GUN_SECTOR - 1).runtime.isSwapHintPending()).toBe(false); + expect(createRuntime(GUN_SECTOR).runtime.isSwapHintPending()).toBe(true); + expect(createRuntime(GUN_SECTOR + 1).runtime.isSwapHintPending()).toBe(false); + }); + + test('the meter and a respawn leave it pending; a swap clears it', () => { + const { runtime } = createRuntime(GUN_SECTOR); + runtime.trySwapGun(); + expect(runtime.isSwapHintPending()).toBe(false); + + const other = createRuntime(GUN_SECTOR).runtime; + other.updateGunCharge(SPECIAL_GUN_CHARGE.refillMs); + other.resetGunCharge(); + expect(other.isSwapHintPending()).toBe(true); + }); + + test('with a keyboard the HUD shows the hint until the first swap, then never again', () => { + const harness = createFrameHarness(GUN_SECTOR); + harness.run(32); + expect(harness.hints).toEqual({ hud: true, key: false }); + harness.pressSwap(); + harness.run(16); + expect(harness.hints).toEqual({ hud: false, key: false }); + harness.run(SPECIAL_GUN_CHARGE.drainMs + 32); + expect(harness.runtime.getGun()).toBe('lance'); + expect(harness.hints).toEqual({ hud: false, key: false }); + }); + + test('on touch the swap key pulses instead, until the first swap', () => { + const harness = createFrameHarness(GUN_SECTOR, true); + harness.run(32); + expect(harness.hints).toEqual({ hud: false, key: true }); + harness.pressSwap(); + harness.run(16); + expect(harness.hints).toEqual({ hud: false, key: false }); + }); + + test('sectors without special guns never show it', () => { + for (const level of [GUN_SECTOR - 1, GUN_SECTOR + 1]) { + const harness = createFrameHarness(level); + harness.run(32); + expect(harness.hints).toEqual({ hud: false, key: false }); + } + }); +}); diff --git a/tests/specialGunIntro.test.ts b/tests/specialGunIntro.test.ts new file mode 100644 index 0000000..043baa8 --- /dev/null +++ b/tests/specialGunIntro.test.ts @@ -0,0 +1,23 @@ +import { describe, expect, test } from 'bun:test'; + +const { SPECIAL_GUN_CHARGE } = await import('../src/config/shipSystems'); +const { describeSpecialGunIntro, isSpecialGunIntroDue } = + await import('../src/scenes/planetIntermission/specialGunIntro'); + +describe('special gun intro card', () => { + test('is due only at the refit bay right before the first sector with special guns', () => { + const due = Array.from({ length: 10 }, (_, index) => index + 1).filter(isSpecialGunIntroDue); + expect(due).toEqual([SPECIAL_GUN_CHARGE.fromLevel - 1]); + expect(due).toEqual([2]); + }); + + test('names Q on a keyboard and the swap key on touch, and nothing else changes', () => { + const keyboard = describeSpecialGunIntro(false); + const touch = describeSpecialGunIntro(true); + expect(keyboard[1]).toBe('Press Q to switch to SCATTER or SEEKERS.'); + expect(touch[1]).toBe('Tap the swap key to switch to SCATTER or SEEKERS.'); + expect(touch.filter((line, index) => line !== keyboard[index])).toEqual([touch[1]]); + expect(keyboard[0]).toContain('LANCE'); + expect(keyboard[2]).toContain('charge'); + }); +});