vinylgauntlet/plan.md

VINYL GAUNTLET — Implementation Plan

A top-down arcade maze shooter that clones the mechanics of Gauntlet II (1986), re-skinned as record-collecting / DJ / trainspotting culture. You dig through record fairs and warehouse clubs, fight off swarming clubbers, and reach the DJ Booth to trainspot the track and clear the level.

Execute the steps IN ORDER. Each step ends with an acceptance check — do not start the next step until the check passes in the browser. Do not add features not listed here. Placeholder geometric shapes throughout; no sprite art until Step 7.

Tech stack

• Vite + vanilla JS (no TypeScript, no framework)
• Phaser 3 (npm install phaser), Arcade Physics, zero gravity, top-down
• One canvas 960x720. Tile size 32px.
• No external assets: shapes are add.rectangle/add.circle converted to physics bodies (or generated textures via make.graphics). Voice via window.speechSynthesis. The single sound effect (airhorn) via WebAudio oscillator — no audio files.

File layout (keep it this small)

index.html
src/main.js        — Phaser config + scene registration
src/GameScene.js   — the whole game (it's fine, it's an arcade game)
src/levels.js      — level maps as 2D arrays + legend
src/announcer.js   — speechSynthesis wrapper + line table

Core constants (put at top of GameScene.js, tune later)

const TILE = 32;
const VIBE_MAX = 2000;
const VIBE_DRAIN_PER_SEC = 1;          // the Gauntlet heartbeat
const ESPRESSO_VIBE = 500;
const POSER_TOUCH_DAMAGE = 30;
const NERD_TOUCH_DAMAGE = 80;
const SOUNDGUY_DRAIN = 10;             // per 250ms tick while overlapping
const GEN_HP = 3;
const GEN_SPAWN_MS = 2500;             // base; shrinks with crowd density
const PLAYER_SPEED = 180;
const POSER_SPEED = 120;
const NERD_SPEED = 70;
const SOUNDGUY_SPEED = 55;
const VINYL_SPEED = 400;
const FIRE_COOLDOWN_MS = 180;
const TRAINSPOT_MS = 3000;

---

Step 1 — Project, tilemap, movement

• npm create vite@latest . -- --template vanilla, then npm install phaser.
• Phaser config: 960x720, arcade physics, gravity: {y: 0}, pixelArt true.
• Levels are 2D arrays of single characters in src/levels.js:

  W = wall (crate stack, brown)        . = floor (dark grey #1a1a1a)
  P = player start                     E = espresso (green square)
  K = lanyard/key (yellow square)      D = velvet rope door (red block)
  G = generator/discount bin (purple)  X = DJ booth exit (magenta, pulsing alpha tween)
  S = sound guy spawn                  A = airhorn pickup (white square)
  

  Export LEVELS = [level1, level2, level3] — author 3 maps by hand, each ~30x25 tiles, Gauntlet-style: rooms, corridors, a keyed door between player and exit, 2–4 generators. Level 1 easy (1 generator, no sound guy), level 3 nasty.
• Build the level in buildLevel(index): walls into a staticGroup, everything else into groups/objects. This function must fully tear down the previous level first (clear groups, timers, colliders) — it gets called on every level change and restart.
• Player: cyan circle, 8-way WASD movement, normalized diagonal speed, collides with walls. Camera follows player with lerp; world bounds = map size.

Check: player drives around level 1, can't pass through walls, camera follows.

Step 2 — Vibe drain, pickups, doors, HUD

• this.vibe = VIBE_MAX. A 1-second looped timer subtracts VIBE_DRAIN_PER_SEC.
• HUD (fixed to camera): VIBE 1987 LANYARDS 1 AIRHORNS 1 LEVEL 1. Vibe text turns yellow below 500, red below 200.
• Espresso overlap: +ESPRESSO_VIBE (cap at VIBE_MAX), destroy pickup.
• Lanyard overlap: lanyards++, destroy pickup.
• Velvet rope: static red blocks that collide like walls; on collide, if lanyards > 0 then lanyards-- and destroy the block.
• Vibe <= 0 → GAME_OVER state: freeze physics, "TRAINWRECK" centered, press R to restart at level 1 with fresh vibe.
• Game states as a plain string field: TITLE | PLAYING | GAME_OVER | LEVEL_CLEAR. Title screen = level shown behind a "VINYL GAUNTLET — press any key" overlay.

Check: vibe visibly ticks down, espresso refills it, a lanyard opens a rope, letting vibe hit 0 shows game over, R restarts.

Step 3 — Shooting, generators, the swarm

• Firing: arrow keys fire vinyl (small black circle with white center dot) in 8 directions (combinations of arrows), independent of movement direction — this is the Gauntlet control scheme. Rate-limit with FIRE_COOLDOWN_MS. Vinyl dies on wall impact or after 1200ms.
• Object pooling (CRITICAL): one physics.add.group for vinyl (size 30), one for enemies (size 80). Spawn with group.get(), kill with setActive(false).setVisible(false) + disable body. Never new/destroy per shot.
• Generators (Discount Bins): purple squares, GEN_HP hits. Each has its own looped spawn timer (GEN_SPAWN_MS): if it's within ~700px of the player, spawn an enemy on an adjacent floor tile. Vinyl hit → hp--, brief white flash tween; at 0, destroy generator and its timer.
• Two spawned enemy types (generator picks 70/30):
  • Poser (red triangle): fast, moveToObject toward player every 400ms.
  • Gear Nerd (orange square): slow, same homing, bigger touch damage — the "ghost" that corners you and drains you with synth talk.
• Crowd density: this.density = 1, +0.05 every 10s on the current level; effective spawn interval = GEN_SPAWN_MS / density. Resets each level.

Check: shooting feels like Gauntlet (move one way, shoot another), bins pour out enemies until destroyed, 50+ enemies on screen holds 60fps.

Step 4 — Combat, the Sound Guy, the Airhorn

• Vinyl overlaps enemy → both deactivated (back to pool).
• Enemy overlaps player → enemy deactivated, vibe -= its touch damage, 100ms red tint flash on player. (Enemy dies on contact = authentic Gauntlet grunt behavior and prevents per-frame drain stacking.)
• The Sound Guy (Gauntlet's Death): black square with a white "SND" label, one per level at the S tile (levels 2+). No wall collider — phases through everything. Homes at SOUNDGUY_SPEED. Immune to vinyl (vinyl passes through). While overlapping the player, drain SOUNDGUY_DRAIN per 250ms tick — NOT per frame. Only the airhorn removes him.
• Airhorn (smart bomb): spacebar, if airhorns > 0: white full-screen flash (200ms), camera shake, deactivate every active enemy AND the sound guy (generators survive), play a two-tone WebAudio oscillator blast (BWAA-BWAA). A pickups grant +1; player starts with 1.

Check: shooting clears swarms, sound guy walks through walls and is only stoppable by airhorn, airhorn wipes the screen.

Step 5 — Trainspotting exit + level flow

• DJ Booth (X): while the player overlaps it, a progress bar fills over TRAINSPOT_MS ("TRAINSPOTTING..."). Taking ANY damage or leaving the tile resets the bar to zero. This is the level's tension peak — enemies keep coming.
• Bar full → LEVEL_CLEAR: freeze 1.5s, "TUNE IDENTIFIED", then buildLevel(next). Vibe, lanyards, airhorns CARRY OVER (Gauntlet rule — the drain is the difficulty curve). After the last level, loop back to level 1 with density starting higher.

Check: standing at the booth under pressure fills the bar, getting hit resets it, level 2 loads with vibe carried over.

Step 6 — The Announcer

src/announcer.js: wrapper around speechSynthesis — cancel any current utterance before speaking, pick the most robotic-sounding available voice, rate 0.9, pitch 0.6. Per-line cooldowns (min 8s per line key) so it never spams. Lines:

Trigger	Line
vibe crosses below 500	"Selector needs espresso badly."
vibe crosses below 200	"Selector... is about to die."
game over	"Trainwreck. Absolute trainwreck."
shot a generator to death	"Discount bin... destroyed."
sound guy spawns	"The sound guy... is coming."
airhorn used	(no speech — the oscillator blast IS the line)
door opened	"Velvet rope... unlocked."
level clear	"Tune identified. Selector levels up."
touching booth, bar filling	"Trainspotting..." (once per attempt)

Check: lines fire at the right moments, never overlap or spam.

Step 7 — Juice pass (only after 1–6 are flawless)

Small, in this order, stop when it feels good:

1. Vibe < 200: red vignette (a camera-fixed rectangle with low alpha).
2. Enemy death: 3-particle puff (pooled).
3. Booth pulses brighter as the trainspot bar fills.
4. Only now, optionally swap shapes for sprites — the game must already be fun as rectangles.

Explicit NON-GOALS (do not build, do not scaffold for)

Multiplayer. Digging minigame. Finite ammo / vinyl-as-currency. Ranged enemies. Level editors or Tiled/JSON maps. Vibe-based movement penalties. Saving/persistence. Mobile controls. More than 3 enemy types. Any menu beyond title/game-over text. If any of these seem needed, they aren't — finish the loop first.