Arcade-style space shooter built with Phaser 3 + TypeScript.
Fight asteroid waves, collect power-ups, and clear levels by defeating a mandatory boss UFO at the end of each level.

• Phaser 3 game loop with Arcade Physics and responsive viewport scaling.
• Startup bundle optimization:
  • runtime gameplay scenes are lazy-loaded from BootScene on first start,
  • Phaser is bundled with the Arcade-focused build (phaser-arcade-physics.min.js) to trim engine payload.
• Boot scene UI is width-aware on smartphones:
  • pulsing start button text and install/uninstall guidance are fitted/wrapped to stay inside the viewport.
• Difficulty presets: EASY, NORMAL, HARD (affects enemies, drops, UFO pressure, and level curve).
• Level gate: each level requires at least ~60s survival time before the boss phase can trigger.
• Two UFO variants:
  • Scout: light pressure, occasional aimed shots, single-hit destroy.
  • Boss: procedural animated silhouette with tentacles, 3-phase escalation (attack patterns intensify as health drops), dodge AI that reads incoming bullet trajectories, multi-hit energy bar with segmented display and numeric hit label. Boss modifiers from level 3+: shielded (HP regen), summoner (spawns mini-swarms), berserk (speed scales with HP loss), armored (50% damage reduction).
• Rescue event: destroying a scout UFO ejects 2-3 stranded astronauts that glide downward; touching them rescues each astronaut for bonus points.
• Rescue streak: chained astronaut rescues within a short timer build a separate rescue multiplier for higher payout.
• Top-entry invaders (SkyRaider): two AI enemy variants intermittently dive in from above, attack the player, then retreat off-screen if not destroyed. Spawn pressure scales by difficulty and level.
• Dynamic mini-events: timed battlefield modifiers (SOLAR STORM, LOW GRAVITY, SWARM RUSH) periodically alter pressure and movement flow mid-run.
• Level progression with transition overlay between levels (LEVEL N, 3, 2, 1, GO!).
• Mandatory boss phase at level end before level can advance.
• Level-end bonus celebration now runs before perk cards:
  • asteroid kills: +10 each,
  • UFO/invader kills: +100 each,
  • animated score payout with coin ticks + fireworks.
• Rogue-lite perk system: pick 1 of 3 perks after each boss defeat (fire rate, extra life, score multiplier, shield-on-level, mine stock, and more).
• Score milestone feedback: camera flash + shake + ascending arpeggio at 5K/10K/25K/50K/100K.
• Asteroid swarms: V-formation groups of 5-8 small asteroids from level 2+, bonus for full swarm wipe.
• Daily challenge mode: seeded runs with separate leaderboard, accessible from attract screen.
• Combo system with kill-streak multiplier and score popups.
• Tutorial hints on first-ever play (arrows to move, space to fire, collect power-ups).
• Persistent lifetime stats and 5 unlockable ship skins.
• Dynamic bullet-pressure controls:
  • adaptive bullet cap,
  • collision-hit coalescing for mass scenes.
• Enhanced ship visuals and power-up readability (thruster + effect overlays).
• Mine-layer tactical ability: each run starts with 2 charges; collect more and deploy 5 proximity mines (M or double-click/double-tap).
• Attract mode now includes occasional UFO live-fire for a more dynamic demo screen.
• Optional compact server sync API (public/api/stats.php) for:
  • shared highscore leaderboard (normal + daily),
  • consumed coin counter,
  • total user counter (all-time unique users). Client fetch is lazy/non-blocking in Attract/Game Over; local fallback remains active if API is unreachable.
• Attract rotation now includes a dedicated LIVE STATS block (total users + consumed coins from server snapshot).

• Attract / Game Over / Menu scenes use the existing loop track (song.mp3).
• Main gameplay uses a dedicated low-volume loop track (gameloop.mp3) so SFX remain in the foreground.
• Gameplay loop pauses/resumes with gameplay scene pause/resume and stops when leaving the gameplay scene.

• TRI (Triple Shot): 3-way spread.
• SLO (Slow Motion): slows world pacing.
• SHD (Shield): absorbs one hit.
• EMP (EMP Wave): heavy crowd-clear utility.
• GST (Ghost Phase): temporary intangibility.
• DRN (Wingman Drones): support fire.
• CLG (Cannon Cooling): no heat build-up; thruster flame shifts to icy white.
• BLK (Black Hole): gravity-like control effect.
• BNK (Shield Bunker): deploys temporary indestructible bunkers that block ships, bullets, and asteroids.
  • Base duration: ~18s (difficulty-scaled).
  • Compact/mobile layouts spawn 2 bunkers instead of 3.
  • Bunkers blink 4x shortly before deactivation.
• MNE (Mine Layer): grants +1 mine-field charge (run starts with 2); each activation deploys 5 proximity mines that arm, pulse, and destroy enemies on contact.
• MINE STOCK (Perk Card): permanent +1 mine-field charge per stack when selected after boss fights.

• Scout UFO: light target, usually single-hit; destroying it ejects 2-3 rescue astronauts.
• Boss UFO: level-end mandatory target with multi-hit energy, escalating phases, and modifiers (shielded, summoner, berserk, armored).
• SkyRaider Stalker: tracking raider with aimed fire, medium threat profile.
• SkyRaider Lancer: faster strike variant with stronger pressure and higher score reward.
• Elite Drone: rare bonus/salvage target; rescue or destroy it to gain a permanent run perk.

• Move: Arrow Keys or pointer/touch drag.
• Fire: hold Space or pointer.
• Pause: UI button PAUSE (P) / P or Esc.
• Help: UI button HELP (H) / H.
• Deploy mine field (requires MNE charge): M or double-click (mouse) / double-tap (touch).
• Debug overlay (off by default): D.
• Test spawn (debug): B activates shield bunkers.

• Boot: SOUND (S), START (ENTER/SPACE) (desktop tries fullscreen on start).
• Pause scene: RESUME (P), EXIT (X), SOUND (S), volume sliders (MASTER/SFX/BGM).
• Help scene: BACK (ESC/H).
• Help scene readability: darkened backdrop + opaque content panel for higher text contrast.
• Game Over: HELP (H), SETTINGS (O), 1 PLAYER (1), 2 PLAYER (2), INSERT COIN (I).

• Insert coin: I.
• Start game: 1, 2, Enter, Space.
• Help: H.
• Open settings: O.
• Settings overlay controls:
  • Sound: S
  • Volume sliders: MASTER, SFX, BGM (pointer/touch)
  • Fullscreen: F (desktop)
  • Difficulty: A/D or Left/Right
  • Scan/CRT toggle: C (only when supported)
  • Back: Esc, B, or O
• Daily challenge: C.

npm install
npm run dev

• The game UI is intentionally English-first (lang="en").
• To reduce Microsoft Edge/Chromium translation popups on restart, index.html includes:
  • translate="no" on <html> and <body>,
  • meta name="google" content="notranslate".
• Content-Language is declared as en,de for mixed deployment context metadata without changing in-game UI language.
• PWA manifest also declares "lang": "en".

To enable shared highscores/coins/users on your web server:

• Deploy public/api/stats.php.
• Ensure public/api/data/ is writable by PHP (API writes stats.runtime.json there).
• Optional client override: set VITE_STATS_API to your endpoint.
• Default client endpoint is relative (api/stats.php), so under https://meuse24.info/apps/kineticScan/index.html it resolves to https://meuse24.info/apps/kineticScan/api/stats.php.
• Vite copies public/ into dist/ automatically, including public/api/*. Uploading the entire dist/ folder contents is sufficient.

Behavior:

• New highscores are sent to server immediately after initials are confirmed in Game Over.
• Consumed credits are posted when a run starts.
• Attract and Game Over refresh highscores lazily in the background so gameplay flow is not blocked.
• API keeps only the last 30 recently seen users in users, while totalUsersEver is tracked separately.
• If API calls fail (offline/network errors), events are buffered in localStorage and retried automatically.

Build/lint:

npm run lint
npm run build

Tests:

npm run test
npm run test:coverage

Playwright smoke flow (requires running dev server on http://localhost:5173):

npm run test:smoke

Preview production build:

npm run preview

• Build currently emits a dedicated phaser chunk plus separate runtime scene chunks.
• Typical split after optimization:
  • phaser ~1.09 MB minified (~296 kB gzip),
  • MainScene ~96 kB,
  • index runtime chunk ~91 kB,
  • menu/overlay scenes each in small separate chunks.

For headless capture stability, renderer can be forced to canvas:

• ?renderer=canvas
• ?capture=1

Automation helpers are exposed on window:

• render_game_to_text()
• advanceTime(ms)

• src/main.ts: entry + automation hooks.
• src/gameConfig.ts: renderer/scaling configuration.
• src/MainScene.ts: core gameplay loop (player, enemies, level/boss flow, overlays, mine-layer ability).
• src/UFO.ts: scout/boss UFO logic, procedural visuals (animated tentacles, hull, energy bar), projectile volleys.
• src/systems/MainWorldEvents.ts: wormhole/elite/swarm world events and scout-UFO astronaut burst spawning + astronaut movement/rescue state.
• src/Player.ts: player movement/fire/heat + visual indicators.
• src/EnemyManager.ts: asteroid spawning/splitting/difficulty scaling.
• src/PowerUpDirector.ts: drop logic and support triggers.
• src/GameOverScene.ts, src/AttractScene.ts, src/HelpScene.ts: meta flow.
• src/ComboManager.ts: combo kill-streak tracking with multiplier tiers.
• src/PerkSystem.ts + src/PerkSelectScene.ts: rogue-lite perk selection after boss defeats.
• src/StatsManager.ts: persistent lifetime stats and ship skin unlocks.

• Attract -> Start -> Gameplay -> Pause/Help -> Game Over.
• Attract and Game Over both expose settings overlay (O) with sound/fullscreen/difficulty/CRT controls.
• Difficulty switch persists and affects pacing.
• Level transition overlay appears (3, 2, 1, GO!).
• Player ship is inactive during level-transition overlay (no firing while countdown is shown).
• Boss appears at level end and requires multiple hits.
• Boss energy bar is shown directly on the boss UFO and decreases on hits (segmented bar + numeric label).
• Boss hit-flash and damage-drain animation visible on each hit.
• Boss modifiers visible from level 3+ (shielded/summoner/berserk/armored).
• Scout/Boss destruction uses full explosion and cleanup without freeze states.
• Destroyed scout UFOs eject 2-3 astronauts; astronauts glide down slowly, can be rescued individually, and disappear correctly when collected or expired.
• Rescue streak HUD appears when chaining astronaut rescues and expires correctly when timer runs out.
• Combo HUD text stays on a dedicated row and does not overlap lives/mines/pause/help on compact/mobile layouts.
• Dynamic mini-events (SOLAR STORM, LOW GRAVITY, SWARM RUSH) activate periodically and expire cleanly.
• Attract-mode UFO occasionally fires demo shots.
• In-game background loop (gameloop.mp3) is audible but quieter than gameplay SFX.
• Perk selection overlay appears after boss defeat (pick 1 of 3 upgrades).
• Level bonus fireworks + score payout appears before perk selection.
• Score milestones trigger camera effects and ascending arpeggio.
• Top-entry invaders (stalker/lancer) appear from above, shoot, and retreat if left alive.
• Asteroid swarm formations spawn from level 2+ with bonus for full wipe.
• Start each run with 2 mine charges; Mine Layer pickup or Mine Stock perk increases HUD mine count. Deployment (M or double-click/double-tap) launches 5 pulsing mines that destroy asteroids/UFOs/invaders on contact.
• Daily challenge mode with seeded runs and separate leaderboard.
• Tutorial hints shown on first play.
• Volume sliders (master/SFX/BGM) available in pause menu.
• Volume sliders (master/SFX/BGM) available in attract/game-over settings overlays.
• Pause menu exit path returns to attract screen (EXIT (X) / X).