# 🎮 Suno Music Adventure - Complete Feature Documentation

## Table of Contents
1. [Core Game Mechanics](#core-game-mechanics)
2. [Musician System](#musician-system)
3. [Time Travel & Locations](#time-travel--locations)
4. [UI & Controls](#ui--controls)
5. [Progression Systems](#progression-systems)
6. [NPC Encounters](#npc-encounters)
7. [Store & Economy](#store--economy)
8. [Quiz System](#quiz-system)
9. [Arcade Games](#arcade-games)

---

## Core Game Mechanics

### World Exploration
- **Grid Size**: 10x10 cells per room
- **Infinite World**: Unlimited connected rooms using coordinate system
- **Procedural Generation**: Seeded random terrain ensures consistency
- **Terrain Types**:
  - Roads (passable, tan color) - 65-75% of map
  - Blocks (impassable, grey) - 25-35% of map (maze-like)
- **Room Boundaries**: Dashed borders indicate explorable edges
- **Room Persistence**: Visited rooms are saved and restored

### Movement & Controls
- **WASD / Arrow Keys**: Move character in 4 directions
- **Space Bar**: Interact with challenges and NPCs
- **Edge Navigation**: Walk to room edges to explore new rooms
- **Collision Detection**: Cannot walk through blocks
- **Center Spawn**: Start at position (5, 5) in each new room

### Terrain Complexity
- **Block Clusters**: Irregular maze-like patterns
- **25-35% Obstacle Density**: Challenging but navigable
- **Connected Pathways**: Algorithm ensures all roads connect
- **Seeded Generation**: Same coordinates = same room layout

---

## Musician System

### Musician Database
- **20+ Historical Musicians** across 15 time periods
- **Coverage**: 1720s (Bach, Vivaldi) to 2020s (modern artists)
- **Attributes**:
  - Name, era, location, genres
  - Style prompts for Suno generation
  - Historical context and descriptions
  - Difficulty levels and icon
  - Required player level

### Musician Encounters
- **Location-Based**: Musicians appear in their historical cities
- **Era-Specific**: Only encounter musicians from current time period
- **Level-Gated**: Higher-level musicians require progression
- **Challenge Format**: Battle musicians to learn their styles

### Style Learning System
- **Unlock Mechanism**: Complete challenge → learn style
- **Style Prompts**: Get Suno-compatible generation prompts
- **Persistent Progress**: Learned styles saved to player profile
- **Collection Tracking**: Track all unlocked musician styles

### Example Musicians by Era
- **1720s**: Bach (Leipzig), Vivaldi (Venice)
- **1780s**: Mozart (Vienna)
- **1800s**: Beethoven (Vienna)
- **1920s**: Louis Armstrong (New Orleans)
- **1950s**: Elvis Presley (Memphis), Chuck Berry
- **1960s**: The Beatles (Liverpool), Jimi Hendrix
- **1980s**: Michael Jackson, Prince, Madonna
- **2010s-2020s**: Modern era artists

---

## Time Travel & Locations

### Time Periods (15 Total)
1. 1720s - Baroque Era
2. 1780s - Classical Era
3. 1800s - Classical/Romantic
4. 1830s - Romantic Era
5. 1920s - Jazz Age
6. 1930s - Swing Era
7. 1940s - Bebop
8. 1950s - Rock and Roll
9. 1960s - Rock Revolution
10. 1970s - Classic Rock
11. 1980s - Pop/New Wave
12. 1990s - Alternative
13. 2000s - Electronic
14. 2010s - Modern
15. 2020s - Contemporary

### Location System
- **Historical Cities**: Each era has 2-4 associated cities
- **Auto-Assignment**: Location changes when changing time periods
- **Coordinate-Based**: Room coordinates determine specific city within era
- **Display**: Shows current city, country, and coordinates in left sidebar

### Time Travel UI
- **Left Sidebar**: Scrollable list of all 15 time periods
- **Location Display**: Shows current city and time period
- **Coordinates**: Room position shown below location
- **Click to Travel**: Select any time period to jump there
- **Challenge Refresh**: New musicians spawn when changing eras

---

## UI & Controls

### Layout Structure
- **Top Header** (110px): Title, status, resources, find challenge, message
- **Left Sidebar** (120px): Location, time periods (scrollable)
- **Right Sidebar** (120px): Action buttons (settings, store, help, etc.)
- **Bottom Bar** (60px): Music player
- **Center**: 10x10 game map

### Top Header Elements
- **Title**: "SUNO Music Adventure" (centered, large)
- **Status**: Character icon + name, Level (⭐)
- **Resources**: Fans 👥, Streams 🎧, Credits 🎵, Active Challenges 🎯
- **Message Display**: Centered game messages
- **Exit Button**: 🚪 (top-right corner)

### Right Sidebar Buttons
1. 🔍 **Find Challenge** - Spawn new musician encounters
2. ⚙️ **Settings** - Font size control (12-24px)
3. 🛒 **Store** - Cleffy's Music Store
4. 📖 **Help** - Controls and features guide
5. 🗺️ **World Map** - Explored rooms grid, fast travel
6. 🧠 **Quiz** - Suno Timeline Quiz (100 questions)
7. 🕹️ **Arcade** - Mini-game selection
8. 🚪 **Exit** - Return to main menu

### Modal System
- **All Draggable**: Click and drag modal headers
- **Glass-Morphism Design**: Translucent with backdrop blur
- **Glowing Borders**: Orange accent color (#f39c12)
- **Hover Effects**: Headers change color on hover
- **Close Buttons**: Red X with rotate animation
- **Custom Scrollbars**: Orange-themed scroll bars
- **Z-Index**: Modals appear above game map (z-index: 5000)

### Font Size System
- **Base Size**: 16px (default)
- **Range**: 12px (small) to 24px (large)
- **Slider Control**: In Settings modal
- **Relative Sizing**: All text uses `em` units for proportional scaling
- **Live Preview**: See changes immediately

---

## Progression Systems

### Level System (5 Levels)
1. **Level 1: Aspiring Artist** (0-49 fans)
2. **Level 2: Local Talent** (50-249 fans)
3. **Level 3: Rising Artist** (250-499 fans)
4. **Level 4: Regional Success** (500-999 fans)
5. **Level 5: Established Artist** (1000+ fans)

### Character Types (4 Options)
- 🎸 **Indie Artist** - +20% fans from original songs
- 🎧 **Electronic Producer** - +20% Suno Credits from remixes
- ⭐ **Pop Star** - +20% streams from all songs
- 🤘 **Rock Musician** - +20% fans from live performances

### Resources & Economy
- **Fans**: Unlock levels, determine battle power
- **Streams**: Generated from challenges, converted to credits
- **Suno Credits**: Main currency for store purchases
  - Earn: Complete challenges, quiz, NPC quests
  - Spend: Buy equipment, instruments, education
- **Songs Created**: Track total compositions

### Challenge Rewards
- **Base Rewards**: 50-100 fans, 100-200 streams per challenge
- **Bonus Credits**: 25-75 Suno Credits per musician learned
- **Style Unlock**: Gain musician's Suno generation prompt
- **Progressive Difficulty**: Higher levels = better rewards

---

## NPC Encounters

### Anessa - Quest NPC (30% Spawn Rate)
- **Appearance**: Blue pixel character with "?" marker
- **Behavior**: Spawns in 30% of new rooms
- **Interaction**: Walk onto same tile to trigger quest
- **Quest Type**: Remix challenges
- **Rewards**: 50-100 fans, 100-200 streams, 25-75 credits
- **One-Time**: Disappears after quest completion

### Wandering Musician - Green Character (20% Spawn Rate)
- **Appearance**: Green pixel person with 🎵 symbol
- **Behavior**: Spawns in 20% of new rooms (rare encounter)
- **Interaction**: Walk onto tile to trigger music challenge
- **Effect**: Spawns a new musician challenge on the map
- **One-Time**: Disappears after encounter
- **Purpose**: Provides additional challenge opportunities

### Enemy Musicians - Battle NPCs (Level 2+)
- **Appearance**: Red pixel character with 💀 symbol
- **Spawn Condition**: One per room starting at Level 2
- **Behavior**: Autonomous movement with pathfinding AI
- **Battle Mechanics**:
  - Risk: 10-50% of your fans
  - Reward: 10-50% of enemy fans (if you win)
  - Enemy Strength: 50% of fans needed for next level
- **Persistence**: Remains until defeated or level up

---

## Store & Economy

### Cleffy's Music Store
Access via 🛒 button on right sidebar (draggable modal)

#### 🎚️ Recording Equipment
- **Basic Home Studio** (Free) - 1.0x fan multiplier
- **Professional Equipment** ($300, Level 2) - 1.2x multiplier
- **Studio-Grade** ($800, Level 4) - 1.5x multiplier

#### 🎹 Instruments
- **Electric Guitar** ($150, Level 1) - Unlocks rock, metal, indie
- **Professional Keyboard** ($200, Level 2) - Unlocks electronic, pop, R&B
- **Drum Kit** ($300, Level 3) - Unlocks punk, jazz, funk
- **Orchestra Access** ($600, Level 4) - Unlocks classical, cinematic

#### 🎓 Music Education
- **Theory Basics** ($100, Level 1) - Chord progressions
- **Advanced Production** ($250, Level 2) - Mixing, mastering
- **Songwriting Masterclass** ($400, Level 3) - Lyric optimization

### Store Features
- **Level-Gated**: Items unlock at specific levels
- **One-Time Purchase**: Owned items marked with ✓
- **Balance Display**: Shows available Suno Credits
- **Item Details**: Name, description, price, level requirement

---

## Quiz System

### Suno Timeline Quiz
Access via 🧠 button on right sidebar (draggable modal)

#### Quiz Features
- **100 Questions**: True/False format
- **Topics**: Complete Suno AI history (April 2023 - July 2025)
- **Coverage**:
  - Bark model release
  - V2, V3, V3.5, V4, V4.5 updates
  - Mobile apps, partnerships
  - Features: Audio Input, Covers, Personas, Remix
  - Leadership changes, acquisitions

#### Mechanics
- **No Repeats**: Questions don't repeat until all answered
- **Rewards**: 10 Suno Credits per correct answer
- **Maximum Earnings**: 1,000 credits total
- **Explanations**: Detailed answers after each question
- **Progress Tracking**: Shows score and questions answered
- **Reset**: Retake quiz after completing all 100

---

## Arcade Games

### Access
- Click 🕹️ **Arcade** button on right sidebar
- Opens draggable modal with 4 game options
- Each game rewards 100 Suno Credits on completion

### Game Modes
1. **🦤 Flappy DODO** - Pitch Game
   - Control bird with your voice pitch
   - Avoid obstacles by singing high/low
   - Pitch detection via microphone

2. **🐍 Musical Snake** - Rhythm Game
   - Classic snake with music mechanics
   - Collect items to grow
   - Rhythm-based scoring

3. **🎵 DodoGuessr** - Tag Guessing
   - Guess music tags and genres
   - Test your music knowledge
   - Multiple choice format

4. **🎮 DODOTRIS** - Musical Tetris
   - Tetris with music integration
   - Match melodies to clear lines
   - Audio-visual feedback

---

## Advanced Features

### World Map System
- **2D Grid Display**: Shows all explored rooms
- **Current Location**: Orange cell with 📍 marker
- **Explored Rooms**: Blue cells with ✓ marker
- **Fast Travel**: Click any explored room to teleport
- **Room Info**: Displays coordinates and total explored count

### Music Player (Bottom Bar)
- **Queue System**: Unlimited song playlist
- **Playback Controls**: Play/pause, previous, next
- **Now Playing**: Shows current song name
- **Queue Info**: Track position (e.g., "2/5 songs")
- **Auto-Play**: Songs play automatically when queue

d
- **CDN Integration**: Streams from Suno's servers

### Battle System
- **Enemy Encounters**: Starting at Level 2
- **Fan Stakes**: Risk 10-50% of fans
- **Song Submission**: Submit Suno URL to battle
- **Win/Lose Mechanics**: Based on song quality + randomness
- **Rewards**: Gain portion of enemy's fans on victory
- **Persistence**: Defeated enemies disappear

### Settings Panel
- **Font Size Slider**: Adjust global text size (12-24px)
- **Live Preview**: See sample text at current size
- **Persistent**: Setting applies to all game text
- **Range Labels**: Clear min/max indicators

### Help Panel
- **Controls Guide**: Keyboard shortcuts and interactions
- **Feature Overview**: Brief description of all game systems
- **Tips**: Exploration hints and gameplay strategies
- **Always Available**: Accessible anytime via 📖 button

---

## Technical Details

### Procedural Generation
- **Seeded Random**: Coordinate-based seeds ensure consistency
- **Room Keys**: Format "x,y" for storage
- **State Persistence**: Rooms saved/loaded automatically
- **NPC Placement**: Smart positioning avoids conflicts

### Spawn Rates
- **Musicians (Challenges)**: 3-4 per new room
- **Anessa**: 30% chance per room
- **Wandering Musician**: 20% chance per room
- **Enemies**: 100% (one per room at Level 2+)

### Save System
- **Auto-Save**: Rooms saved when leaving
- **State Storage**: JavaScript object with room coordinates as keys
- **Data Saved**:
  - Terrain layout
  - Active challenges
  - NPC positions
  - Enemy defeat status
  
### Audio System
- **Web Audio API**: Custom sound generation
- **Beep Effects**: 800Hz sine wave for UI interactions
- **Footsteps**: 150-200Hz with random variation
- **Music Playback**: 60% volume with queue management

---

## Pixel Art Characters

### Player Character
- Red head, blue body
- Animated with CSS
- Pixel art style with box-shadows
- Visible on map as current position

### Anessa NPC
- Blue pixel character
- "?" marker above head
- Quest indicator animations
- Autonomous movement AI

### Wandering Musician (formerly Dodo)
- **Green pixel character** (changed from orange)
- **🎵 music symbol** (changed from 🦤 bird)
- Triggers music challenges
- Rare encounter (20% spawn)

### Enemy Musicians
- Red/dark pixel character
- 💀 skull marker
- Battle-ready stance
- Pathfinding AI movement

---

## Modal Windows (All Draggable)

### Design Principles
- **Glass-Morphism**: Translucent backgrounds with blur
- **Orange Accents**: Border color #f39c12
- **Hover Effects**: Headers illuminate on hover
- **Close Animations**: X button rotates 90° on hover
- **Smooth Shadows**: Multi-layer shadows for depth

### Modal Types
1. **Settings** - 450px wide, font controls
2. **Store** - 400px wide, scrollable categories
3. **Help** - 400px wide, control guide
4. **World Map** - 450px wide, room grid
5. **Quiz** - 420px wide, question interface
6. **Arcade** - 500px wide, game selection

### Dragging Behavior
- **Grab Cursor**: Shows on header hover
- **Grabbing Cursor**: Shows while dragging
- **Boundary Limits**: Cannot drag off-screen
- **Smooth Movement**: Real-time position updates
- **Release**: Drop modal anywhere on screen

---

## Room Naming System

### Procedural Names
- **Music-Themed**: Combines musicians, instruments, genres
- **Format**: "Location | City, Time Period"
- **Example**: "The Hendrix Studio | Liverpool, 1960s"
- **Consistency**: Same coordinates = same name
- **Variety**: Millions of possible combinations

### Name Components
- **200+ Musicians**: Historical figures from all eras
- **50+ Instruments**: From piano to synthesizer
- **60+ Genres**: Classical to experimental
- **80+ Descriptors**: Studio, club, palace, cosmic, etc.

---

## Challenge System

### Challenge Flow
1. **Find**: Use 🔍 button or encounter wandering musician
2. **Spawn**: Challenge appears on map as music note icon
3. **Approach**: Walk to challenge tile
4. **Interact**: Press Space to start
5. **Complete**: Learn style, earn rewards
6. **Progress**: Challenge marked as complete (✅)

### Challenge Types
- **Musician Battles**: Learn historical styles
- **Style Mastery**: Unlock Suno generation prompts
- **Progressive Difficulty**: Scales with player level
- **Location-Based**: Era-appropriate encounters

### Rewards Structure
- **Fans**: 50-100 base (character bonuses apply)
- **Streams**: 100-200 base
- **Suno Credits**: 25-75 bonus
- **Style Unlock**: Musician's generation prompt
- **Progress**: Contributes to level advancement

---

## User Experience Features

### Accessibility
- **Keyboard Navigation**: Full game playable with keyboard
- **Visual Feedback**: Clear indicators for all interactions
- **Audio Cues**: Beep sounds confirm actions
- **Help System**: Always available, comprehensive guide
- **Font Scaling**: Adjustable for readability

### Quality of Life
- **Fast Travel**: Click map to teleport to explored rooms
- **Auto-Save**: Rooms persist automatically
- **Message System**: Clear feedback for all actions
- **Resource Display**: Always visible in top bar
- **Modal Persistence**: Panels stay where you position them

### Visual Polish
- **Pixel Art Characters**: Retro aesthetic
- **Smooth Animations**: CSS transitions on all elements
- **Color Coding**: Consistent color scheme throughout
- **Hover States**: Interactive elements respond to mouse
- **Shadows & Depth**: Layered UI for visual hierarchy

---

## Game Tips

### Exploration
- Walk to room edges (dashed borders) to discover new areas
- Each room has unique terrain - some are maze-like
- Use World Map to see where you've been
- Change time periods to meet different musicians

### Progression
- Complete challenges to earn fans and level up
- Visit Cleffy's Store to buy permanent upgrades
- Take the quiz for easy Suno Credits
- Battle enemies (Level 2+) for big fan rewards

### Strategy
- Rare NPCs (Anessa, Wandering Musician) provide bonus opportunities
- Higher-level musicians offer better rewards
- Equipment multipliers stack with character bonuses
- Save credits for expensive late-game items

---

**This documentation reflects the current implementation as of the latest build.**