Skip to content

About

A retro arcade space exploration shooter

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Space Explorer

A retro arcade space shooter built with Phaser 4, TypeScript, and Vite. Pilot a responsive ship through a 10-level campaign, survive escalating hazards, defeat themed bosses, collect power-ups, and upgrade your ship between missions.

Playable here: Space Explorer

Latest release Quality Gates TypeScript Phaser Vite Bun License

Screenshots

Main menu A sector 3 fight with Scatter out on the charge
The card that introduces the special guns The refit bay between sectors
A sector 4 fight with the Lance, the main gun The first boss, Pyre Herald

Quick start

Use Node.js 26.x and Bun 1.3.5. CI and the Vercel project use Node 26 as well.

bun install
bun run dev

Open http://localhost:5173 in your browser.

Controls

Input Action
Arrow keys / WASD Move ship
Space / Click Fire weapons
Q / Swap button From sector 3: switch to a special gun while its charge lasts (Lance → Scatter → Seekers → Lance)
Esc / Pause button 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). From sector 3, a swap button under the pause button switches guns and shows the special-gun charge. Both buttons also accept mouse clicks on desktop and hybrid devices; gun switching appears only when it unlocks.

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, and a pulsing ring around the swap button on every device.

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 can be turned off in the same place; it starts off when the system asks for reduced motion. Phones and tablets play in both portrait and landscape; on phones, portrait gives the longest vertical read on incoming threats.

Game overview

Core loop

Menu → Game → Planet Intermission → Game → ... → Victory
  • Fight through enemy waves, hazards, and bosses
  • Lose HP on hits, but continue the run while you still have remaining lives
  • Respawn after death if lives remain
  • Spend score as credits between levels to upgrade your ship
  • Reach the end of the campaign to trigger the Victory flow

Campaign roster

Level Name Highlights Boss
1 Aurora Threshold gentle lane-reading opener with clean diver telegraphs No
2 Tideglass Shallows slow, telegraphed wormhole arrivals and dodger debut No
3 Ember Monsoon drifting minefields and ember-storm lane commitments Pyre Herald
4 Clockwork Causeway beat-timed waves and telegraphed lancer duels Marshal Vectra
5 Shatter Reef splitter target-priority exam and reef pressure Reef Stalker
6 Debris Gauntlet solar-flare and laser-lattice set-piece gauntlet Bastion Bulwark
7 Hollow Choir elite lancer/gunship remix with wormhole telegraphs Choir Regent
8 Eclipse Narrows bomber and gunship pincers through tight corridors Umbral Ark
9 Swarmfront peak-density swarm survival and returning splitters Hive Maelstrom
10 Eventide Engine six-section final exam reprising the campaign's systems Omega Null

Enemy roster

  • Scout — fast, low-HP contact threat
  • Fighter — mobile ranged pressure tuned to two base-weapon hits
  • Bomber — slower bomb carrier tuned to four base-weapon hits
  • Swarm — fragile group attackers
  • Gunship — spread-fire anchor tuned to five base-weapon hits
  • Bosses — named encounters with distinct styles such as barrage, pursuit, carrier, bulwark, and maelstrom patterns

Gameplay systems

  • Scripted level sections — pacing, hazard cadence, and encounter focus can shift inside a level
  • Hazard scripting — asteroid bursts, ring crossfire, nebula ambushes, gravity wells, and canyon-wall rock corridors
  • Adaptive section pacing — tension-arc shaping and fairness throttles smooth extreme overlap spikes
  • Authored boss fights — every boss runs its own set order of attacks across two to four phases, with a par time: beat it for a fast-kill bonus, outstay it and the boss fires faster (the first boss never does). Boss hull is fixed, so upgrades make fights shorter
  • Per-level procedural music — each level and boss has its own Web Audio-driven music identity
  • Power-up drops — temporary pickups such as health, shield, and rapid-fire boosts
  • AEGIS Picket turrets — a two-tier screen-edge support upgrade available for Level 5 onward
  • Marked Aces — sparse gilded priority targets in Levels 5–10 with stronger rewards
  • Max-chain Overdrive — maintaining the x5 chain briefly accelerates the main gun
  • Lives + respawn flow — the run continues after death if lives remain
  • Upgrade progression — intermission upgrades unlock over time and obey progression caps

Upgrades

Bought during the planet intermission screen using score as currency:

  • Hull Armor — adds 1 max HP per tier, up to 10 HP
  • Weapons — increases damage
  • 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 8 seconds, then the gun returns to Lance. On Lance the meter refills over 40 seconds 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

Some upgrades unlock later in the campaign and use progression caps so the run scales in a controlled way.

Tech stack

  • Phaser 4.2.1 — ESM game engine with WebGL rendering
  • TypeScript — strict typing across gameplay and config
  • Vite 8.1.5 — dev server and production build
  • Bun 1.3.5 — package manager and script runner

TypeScript 7 (@typescript/native) type-checks the app and tests. The typescript package stays on TypeScript 6 only because ESLint still needs it. The scripts use explicit package paths so Bun cannot resolve the wrong compiler when both packages expose a tsc binary.

Phaser is consumed through its package ESM export and the game requires WebGL. Browsers without WebGL receive an explicit unsupported-device message instead of a partial Canvas fallback.

Project structure

The internal architecture rules live in docs/architecture-guidelines.md.

src/
├── config/
│   ├── LevelsConfig.ts          # public level-config entrypoint
│   ├── UpgradesConfig.ts        # upgrade definitions and progression rules
│   ├── playerConfig.ts          # player stat scaling
│   └── levels/
│       ├── types.ts             # level config types
│       ├── selectors.ts         # getLevelConfig / campaign selectors
│       ├── registry.ts          # ordered campaign registry
│       ├── definitions/         # one file per level
│       └── music/               # level music configuration and patterns
├── entities/
│   ├── Player.ts
│   ├── PowerUp.ts
│   ├── Asteroid.ts
│   ├── BomberBomb.ts
│   ├── Bullet.ts
│   ├── EnemyBullet.ts
│   └── enemies/
│       └── boss/
├── scenes/
│   ├── gameScene/               # runtime lifecycle + flow helpers
│   ├── planetIntermission/      # upgrade-screen interaction/presentation
│   ├── menuScene/
│   ├── shared/
│   ├── BootScene.ts
│   ├── PreloadScene.ts
│   ├── MenuScene.ts
│   ├── GameScene.ts
│   ├── PlanetIntermissionScene.ts
│   ├── GameOverScene.ts
│   └── VictoryScene.ts
├── systems/
│   ├── audio/
│   │   └── procedural/          # procedural music internals
│   ├── parallax/                # layered background lifecycle helpers
│   ├── balance/
│   ├── effects/
│   ├── hud/
│   ├── wave/
│   ├── AudioManager.ts          # procedural audio and music orchestration
│   ├── CollisionManager.ts
│   ├── EnemyPool.ts
│   ├── HUD.ts
│   ├── LevelManager.ts
│   ├── PlayerState.ts
│   └── WaveManager.ts           # config-driven enemy + hazard spawning
└── utils/
    ├── spriteFactory/
    ├── constants.ts
    └── layout.ts

Design notes

  • Config-driven campaign — levels, music, hazard sections, and bosses are authored through config
  • Procedural presentation — visuals and audio avoid external asset-heavy pipelines where possible
  • Object pooling — bullets, enemies, bombs, asteroids, and bullets are pooled for performance
  • Arcade readability first — later levels add complexity through authored pacing and hazards, not only stat inflation

Development

bun run dev      # start local dev server
bun run typecheck # type-check source, scripts, config, and tests
bun run test     # run unit/regression tests with per-file isolation
bun run test:e2e # run the desktop and touch-portrait browser smoke suite
bun run build    # type-check and production build
bun run preview  # preview production build
bun run lint     # eslint
bun run knip     # unused-code analysis
bun run bundle:report   # report dist asset sizes after a build
bun run bundle:check    # enforce bundle size limits and keep dev diagnostics out of releases
bun run perf:profile -- --level 9   # play a sector hands-free and report frame pacing and draw calls

CI runs the static gates and six parallel browser shards (desktop and touch, three each). The Quality gates passed check sums them up; main is protected and only accepts pull requests whose checks pass. Merges to main deploy to production.

CI runs typecheck, lint, format, unit tests (including level-authoring validation), knip, a dependency audit, the build with its bundle check, and the browser smoke suite on desktop and phone viewports.

Visual quality offers Auto and Low. Auto is the full presentation (normal-mapped lighting and bloom; phones start on a lighter lighting budget) and adapts nonessential effects only after sustained frame-delivery pressure, restoring them gradually once stable delivery returns. Low is the baked look with no dynamic lights or bloom. Saved Standard or High choices from earlier versions load as Auto. Gameplay timing, physics, damage, and encounter pacing are never changed.

Production bundle checks separately guard the Phaser engine chunk and application JavaScript. Development-only browser diagnostics are tree-shaken from releases.

Playtest shortcut (dev server only, stripped from production builds): open http://localhost:5173/?startLevel=9 to skip the menu into any level with that level's progression-legal max loadout. Append &upgrades=3,3,3,2 (hp,damage,fireRate,shield) for an explicit loadout, or &upgrades=0 for a stock ship.

The level shortcut runs once per page load. Returning to the main menu stays in the menu; reloading the browser starts the requested preview level again.

All ten campaign levels use evolving procedural atmosphere and generated landmarks, with a distinct composition for each world. Their expensive shader work runs in a bounded texture; Low and reduced-motion settings retain a stable composition. Cinematic hulls remain separate from the background renderer. See the background contract.

For development comparisons, append &atmosphere=live to compare live noise calculation against cached-field sampling. Reload between comparisons.

Docs

Release notes

Acknowledgements

This project was largely autonomously built using Flow for OpenCode, a planning-and-execution workflow plugin that turns goals into tracked, reviewer-gated feature sessions.

License

MIT License. See LICENSE.

About

A retro arcade space exploration shooter

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages