drum-rhythm-game/CLAUDE.md

# 🥁 Drum Rhythm Game — Claude Handoff Document

This file tells Claude exactly what this project is, what has been built, what needs to be built next, and how everything works. Read this entire file before making any changes.

---

## What This Is

A browser-based drum rhythm game built as a single HTML file. It works like Rock Band — notes scroll down the screen and the player hits the matching drum pad in time. It runs entirely in the browser with no server, no dependencies, no npm. Just open `index.html`.

The game was originally built to work with a **Wii Rock Band drum kit connected via USB** on Windows, Mac, and Linux. It also works with keyboard keys.

---

## Current File Structure

Right now everything is in one file: `index.html`. As this project grows, split it as follows:

```
drum-rhythm-game/
├── index.html          ← main shell, links all JS/CSS
├── css/
│   └── style.css       ← extract all <style> here
├── js/
│   ├── audio.js        ← AudioContext, drum sounds, synthesizer
│   ├── rhythms.js      ← all genre drum patterns
│   ├── classical.js    ← classical pieces, note sequences, synth orchestra
│   ├── game.js         ← game loop, scoring, hit detection, players
│   ├── canvas.js       ← all canvas drawing
│   ├── input.js        ← keyboard + gamepad input
│   └── menu.js         ← UI screens, genre tabs, pad toggles
└── CLAUDE.md           ← this file
```

---

## Hardware Setup

- **Drum kit**: Wii Rock Band drums connected via USB dongle
- **Pads**: Red, Yellow, Blue, Green (4 pads) + Kick pedal
- **OS**: Must work on Windows 11, Linux, and Mac
- **Browser**: Chrome or Edge recommended for gamepad API support

### Gamepad Button Mapping (Wii Rock Band via USB)
```
Button 0 → Blue  (lane 2)
Button 1 → Green (lane 3)
Button 2 → Red   (lane 0)
Button 3 → Yellow(lane 1)
Button 4 → Kick  (lane 4)
Button 8 → Kick  (lane 4) — alternate
```

### Lane Definitions
```
Lane 0 = Red    — Tom high  — keyboard: F
Lane 1 = Yellow — Snare     — keyboard: G
Lane 2 = Blue   — Hi-hat    — keyboard: H
Lane 3 = Green  — Tom low   — keyboard: J
Lane 4 = Kick   — Bass drum — keyboard: Space
```

---

## What Has Been Built

### Screens
1. **Menu screen** — mode select, rhythm picker, pad toggles, players, leaderboard
2. **Game screen** — canvas highway, HUD (score/streak/acc/player), countdown
3. **Leaderboard screen** — all saved scores sorted by score

### Modes
1. **Rhythm Mode** — select a genre + rhythm, notes scroll, drum pattern plays as audio background, score your hits
2. **MP3 Jam Mode** — load your own MP3, it plays in background, drum freely (no chart, no scoring)

### Genres & Rhythms (8 genres × 15 patterns = 120 rhythms)
- Rock, Metal, Jazz, Hip Hop, Funk, Latin, Electronic, Country
- Each rhythm has: name, BPM, bars, pattern array
- Pattern format: `{t: beat_offset, l: lane}` where t is within a 4-beat bar

### Rhythm Pattern System
```javascript
// Example pattern entry
{n:"Basic Rock", bpm:90, bars:8, p:[
  {t:0, l:4},   // kick on beat 1
  {t:0, l:2},   // hihat on beat 1
  {t:1, l:1},   // snare on beat 2
  // etc.
]}
```
- `bars` controls how many times the 4-beat pattern repeats
- Notes are built by looping the pattern for the full bar count
- Only notes on **active pads** appear on screen (user can toggle pads)

### Pad Toggle System
- Menu has colored buttons for each pad/kick
- Toggle off = pad makes sound when hit but shows no notes and doesn't score
- Designed for beginners — start with kick+snare, add more pads as you improve

### Scoring
- Hit within 0.17 seconds of note time = counts as hit
- Within 0.05s = "PERFECT" (green), otherwise "GOOD" (yellow)
- Miss = streak resets
- Score = 100 × min(streak, 10) per hit
- Scores saved to localStorage key `"drgame5"`

### Multiplayer (Take Turns)
- Add players in menu (up to N players)
- Each player takes a turn on the same rhythm
- After all turns, results shown sorted by score
- All scores saved to leaderboard

### Audio System
- Uses Web Audio API — no external files needed
- **Critical**: AudioContext must be unlocked on user gesture — especially important on Linux/Chrome
- Unlock happens on any click, keydown, touchstart, mousedown
- Two separate AudioContexts: `previewAc` (menu preview) and `gameAc` (in-game)
- Both must call `.resume()` aggressively

### Drum Sounds (Synthesized)
```
Kick  → sine oscillator, 180Hz → 40Hz sweep, ~0.3s
Snare → highpass noise burst + 180Hz tone body
Hi-hat→ highpass noise burst, very short ~0.05s
Tom   → sine oscillator, 160Hz → 64Hz sweep
Tom2  → sine oscillator, 120Hz → 48Hz sweep
```

### Canvas Layout
- Top 78% = 4 pad lanes side by side
- Bottom 22% = kick zone (full width, centered)
- Hit line at 76% down the pad zone
- Notes fall from top, future notes above hit line
- Note Y position: `noteY = HIT_Y - (noteTime - currentSongTime) * SPEED`
- SPEED = 260px/second
- Notes outside screen bounds are skipped (culled)
- Missed notes (past hit line by HIT_WIN) fade to 20% opacity

### Preview System
- In menu, click Preview to hear any rhythm before playing
- Auto-loops the pattern using scheduled Web Audio nodes
- Plays all drum hits as audio so user can hear the beat
- Stops cleanly when switching rhythms or starting game

---

## What Needs To Be Built Next

### 1. Classical Music Genre Tab (PRIORITY)

Add a new genre called **"Classical"** with the following pieces. Each piece needs:
- A synthesized melody/orchestral background that plays automatically
- A separate set of "hittable" notes (melody notes only) that scroll on screen
- The player hits the melody rhythm, background fills in the rest

#### Pieces to implement (all public domain compositions):

| Piece | Composer | Notes |
|-------|----------|-------|
| Beethoven's 5th (Opening) | Beethoven | DA DA DA DUM — 3 same pad + 1 different |
| Hall of the Mountain King | Grieg | Starts slow, accelerates — great difficulty curve |
| Ride of the Valkyries | Wagner | Galloping rhythm pattern |
| Mars, Bringer of War | Holst | Heavy 5/4 march |
| Toccata & Fugue in D Minor | Bach | Famous DUN DUN DUN opener |
| William Tell Overture (Gallop) | Rossini | Fast galloping rhythm |
| Bolero | Ravel | Literally a drum pattern that builds — perfect |
| Also Sprach Zarathustra | Strauss | DA DAAAA DA DUM (2001 theme) |
| Barber of Seville Overture | Rossini | Bugs Bunny classic |
| The Blue Danube | Strauss Jr. | Waltz rhythm |
| Night on Bald Mountain | Mussorgsky | Fantasia — dark and dramatic |
| Sorcerer's Apprentice | Dukas | Fantasia — Mickey Mouse |
| Swan Lake (Theme) | Tchaikovsky | Elegant waltz |
| Morning Mood | Grieg | Peer Gynt — gentle build |
| In the Hall of the Mountain King | Grieg | (same as above, confirm not duplicate) |

> **Not actually public domain — do not re-add:** O Fortuna (Orff, 1936; composer d. 1982 — still under copyright until 2032 in the US / 2052 in the EU) and Sabre Dance (Khachaturian, 1942; composer d. 1978 — still under copyright until 2048 in the EU) were removed from the repo on this basis. The rest of this table is genuinely public domain (composers who died before ~1955, or works published before 1930).

#### How Classical Mode Should Work
1. Player selects a classical piece
2. Game starts with countdown
3. **Background**: Full synthesized orchestral arrangement plays automatically (Web Audio oscillators, multiple voices, proper frequencies)
4. **Foreground**: Only the main melody notes scroll down as hittable notes
5. Player hits the melody rhythm — satisfying because they're "playing" the famous part
6. Scoring same as rhythm mode

#### Synthesizer Architecture for Classical
Use multiple oscillator types for different instruments:
```javascript
// Strings — sawtooth oscillator + lowpass filter
// Brass   — square oscillator + envelope
// Woodwind— triangle oscillator
// Bass    — sine oscillator, low frequency
// Timpani — sine sweep, like kick but lower
// Choir   — multiple detuned sine oscillators
```

Use a note-scheduling system:
```javascript
// Notes stored as: {time, freq, duration, instrument, volume}
// Schedule all notes at game start using AudioContext time
// This ensures perfect sync regardless of JS timing
```

#### Note Frequencies Reference
```javascript
const NOTES = {
  C3:130.81, D3:146.83, E3:164.81, F3:174.61, G3:196.00,
  A3:220.00, Bb3:233.08, B3:246.94,
  C4:261.63, D4:293.66, E4:329.63, F4:349.23, G4:392.00,
  A4:440.00, Bb4:466.16, B4:493.88,
  C5:523.25, D5:587.33, E5:659.25, F5:698.46, G5:783.99,
  A5:880.00, C6:1046.50
};
```

#### Beethoven's 5th — Starter Implementation
```
Opening motif (G minor):
- G4 (short) → G4 (short) → G4 (short) → Eb4 (long)
- F4 (short) → F4 (short) → F4 (short) → D4 (long)

Drum mapping:
- Short notes → Red pad (lane 0)
- Long notes  → Green pad (lane 3)
- Background: strings + brass arrangement
```

---

### 2. Audio Improvements
- Make drum sounds punchier with a slight distortion/clipping on kick
- Add reverb to classical orchestral sounds (ConvolverNode or simple delay feedback)
- Consider a master volume slider in the game HUD (not just menu)

### 3. Visual Improvements  
- Scrolling speed lines in lane backgrounds for motion feel
- Note "explosion" particle effect on perfect hit
- Combo multiplier display (currently capped at 10x but not shown prominently)
- BPM display during game

### 4. Gameplay Features
- **Practice mode**: slow down to 50/75% speed
- **Difficulty**: Easy (fewer notes), Medium (all notes), Hard (+ extra fills)
- **Endless mode**: rhythm loops until you quit, cumulative score
- **Song length selector**: 1 min / 2 min / full length

### 5. Quality of Life
- Remap button in-game HUD (not just standalone soundboard)
- Volume control per sound type (kick louder than hihat etc.)
- "How to play" screen
- GitHub Pages deployment so it runs at a URL without downloading

---

## Known Issues & Bugs

1. **Linux audio** — AudioContext needs aggressive `.resume()` on every user interaction. Already fixed in current code but watch for regressions.
2. **Pad toggle visual** — toggling a pad on/off used to flicker (toggle on click). Fixed to be one-directional but confirm behavior.
3. **High BPM rhythms** — at 200+ BPM notes can stack visually. May need note size scaling by BPM.
4. **MP3 Jam scoring** — currently no chart in MP3 mode, just free play. Future: beat detection to generate a chart from the MP3.

---

## Tech Constraints

- **No external libraries** — pure vanilla JS, Web Audio API, Canvas 2D
- **No build step** — must work by opening index.html directly
- **No server required** — localStorage for scores, no backend
- **Single HTML file** initially, refactor to multi-file as needed
- **Cross-platform** — Windows 11, Linux (Ubuntu/Fedora), Mac, any modern browser

---

## Style Guide

- Dark theme: background `#0a0a0f`, cards `#13131f`, borders `#222`
- Lane colors: Red `#e53e3e`, Yellow `#d69e2e`, Blue `#3182ce`, Green `#38a169`, Kick `#805ad5`
- Accent: Purple `#805ad5` for buttons/highlights
- Font: system sans-serif, no imports needed
- Minimal UI — game canvas should dominate the screen

---

## How To Test

1. Open `index.html` in Chrome or Edge
2. Click any genre tab → select a rhythm → click Preview to hear it
3. Click Start → watch countdown → notes should fall → hit F/G/H/J/Space
4. For drum kit: plug in USB, hit any pad to wake gamepad API, should show "🎮 Connected"
5. Test on Linux: click something first before hitting Preview — audio needs a gesture

---

## Questions / Decisions Needed

- [ ] Should classical pieces loop or play once through?
- [ ] Should the synthesized orchestra volume be adjustable separately from drum hit volume?
- [ ] For Bolero specifically — should difficulty increase as the piece builds (more notes appearing)?
- [ ] Should we add a GitHub Pages deploy so it runs at a public URL?