# AIsteroids 2026

A top-down space shooter built with Phaser 3, inspired by the classic Asteroids arcade game. Survive escalating waves of asteroids and alien attackers across multiple levels — no installation required.

---

## Gameplay

- **Asteroids** spawn at the start of each level. Shoot them to break them apart:
  - Large → 1–3 medium or small fragments
  - Medium → 2 small fragments
  - Small → destroyed completely
- **Alien ships** periodically warp in and hunt the player. Three variants appear as levels progress:
  - **Basic** (cyan saucer) — moves toward the player and fires single shots
  - **Spread** (orange saucer) — fires a 5-bullet fan, appears at level 3+
  - **Missile** (purple diamond) — fires homing missiles, appears at level 5+
- A level ends when all asteroids and alien ships are destroyed. The player always respawns at screen center on a new level.
- Asteroid speed increases each level (capped at 2× the base speed).

## Controls

| Input | Action |
|---|---|
| Mouse movement | Rotate ship toward cursor (360° turn takes 2 seconds) |
| Left mouse button | Thrust / accelerate |
| `A` or `Space` | Fire weapon |

The ship uses zero-gravity physics — it builds speed over ~2 seconds at full thrust and gradually decelerates when thrust is released.

---

## Tech Stack

| Tool | Purpose |
|---|---|
| [Phaser 3.60](https://phaser.io/) | HTML5 game framework (WebGL renderer) |
| JavaScript ES6 Modules | Game logic, entity classes |
| Phaser Arcade Physics | Collision detection, zero-gravity movement |
| WebGL PostFX Pipeline | Custom CRT scanline/barrel-distortion shader |
| Python 3 HTTP server | Local development server (no build step) |

There is no bundler, package manager, or build step. Modules are loaded natively by the browser over HTTP using ES6 `import`/`export`.

---

## Project Structure

```
oc-test/
├── index.html              # Entry point — loads Phaser via CDN and bootstraps main.js
├── start_web.sh            # Helper script: starts python3 -m http.server 8000
├── Software.md             # Authoritative game design specification
│
└── js/
    ├── main.js             # Phaser config, scene list, pipeline registration
    │
    ├── scenes/
    │   ├── BootScene.js    # Procedural texture generation, hands off to MenuScene
    │   ├── MenuScene.js    # Title screen with decorative entities and CRT effect
    │   └── GameScene.js    # Core game loop — owns all entities and collision logic
    │
    ├── entities/
    │   ├── Player.js       # Player ship: mouse-driven rotation, thrust, firing
    │   ├── Asteroid.js     # Asteroid: size variants, rotation, fragmentation data
    │   ├── AlienShip.js    # Alien ship: type variants, AI movement, attack patterns
    │   └── Bullet.js       # Bullets and homing missiles (player, alien, missile types)
    │
    └── pipelines/
        └── CRTPipeline.js  # WebGL PostFXPipeline: scanlines, barrel distortion, vignette
```

All game graphics are **procedurally generated** at startup in `BootScene` — no external image assets are required for the core game.

---

## Running Locally

Requires Python 3 (for the dev server) and a modern browser with WebGL support.

```bash
# Clone the repo
git clone <repo-url>
cd oc-test

# Start the development server
./start_web.sh
# or equivalently:
python3 -m http.server 8000
```

Then open [http://localhost:8000](http://localhost:8000) in your browser.

> **Note:** The game must be served over HTTP (not opened as a `file://` URL) because ES6 modules require a server context.

---

## Architecture Notes

- **Scene flow:** `BootScene` → `MenuScene` → `GameScene`
- **Entity pattern:** Each entity class holds an `alive` flag and attaches itself to its sprite via `sprite.gameEntity = this`, enabling collision callbacks to look up the owning object.
- **Collision detection:** Uses Phaser physics groups for overlap detection, backed by plain JS arrays for per-frame update loops.
- **CRT effect:** Applied as a `PostFXPipeline` in both `MenuScene` and `GameScene` (WebGL only). Features barrel distortion (strength 0.18), alternating scanlines, and a vignette.