# 🎵 Tony's Dev Tunes - Suno Music Adventure RPG

A comprehensive music-themed RPG game with multiple arcade mini-games, built with React 18 and TypeScript. Explore an infinite world, battle historical musicians, travel through time, and build your music career using the Suno AI platform.

## 🎮 What Is This?

**Tony's Dev Tunes** is an interactive musical experience combining:
- **RPG Game**: Music adventure with 134 historical musicians across 15 eras
- **Arcade Mini-Games**: Flappy DODO, Musical Snake, DodoGuessr, and DODOTRIS
- **Audio Player**: Custom music player for your creations
- **Educational Content**: Learn about Suno AI and music history through interactive gameplay

## ✨ Key Features

### 🆕 **New Enhancement Systems** (Recently Added)
- **Genre Mastery**: 30 music genres with 10-level progression, 101 unlockable skills
- **Statistics Dashboard**: Comprehensive analytics tracking play time, challenges, exploration
- **Quest System**: 5 branching questlines with dialogue choices and multiple endings
- **World Events**: 12 time-based events (Woodstock, Live Aid, MTV Launch, etc.)
- **Tutorial System**: 10-step guided onboarding for new players
- **Enhanced Audio**: Toggle sound effects in settings

### 🎮 **Core Gameplay**

### 🗺️ **Infinite World Exploration**
- **10x10 grid rooms** with procedurally generated maze-like terrain
- **Infinite world** - explore unlimited connected rooms
- **Time travel** through 15 different eras (1720s - 2020s)
- **Location-based encounters** - meet musicians in their historical cities

### 🎼 **Musician Battle System**
- **134 historical musicians** from Bach to contemporary artists
- **Era-specific encounters** - meet Mozart in 1780s Vienna, Elvis in 1950s Memphis  
- **Learn musical styles** - unlock style prompts for Suno generation
- **Music challenges** - battle musicians to master their techniques
- **Genre XP System** - Automatically earn XP and level up 30 genres

### ⏰ **Time Travel Mechanics**
- **15 time periods** covering 300 years of music history
- **Location changes** - each era transports you to historically accurate cities
- **Scrollable timeline** in left sidebar
- **Era-based musician spawning** - encounter musicians from their correct time periods

### 🎯 **Game Mechanics**
- **4 character types**: Indie Artist, Electronic Producer, Pop Star, Rock Musician
- **5 level progression**: From Aspiring Artist to Established Artist
- **Complex mazes**: 25-35% obstacle density for challenging exploration
- **Smart NPC spawning**: 
  - Anessa (quest giver): 30% spawn rate
  - Wandering Musician (green character with 🎵): 20% spawn rate
  - Enemy battles at level 2+
- **Practice Jam mode**: Relaxed 3-minute Flappy DODO preset with in-game tips and a lightweight leaderboard that syncs once you're back online

### 🎨 **UI Features**
- **Draggable modals** - all panels can be moved and positioned
- **Font size control** - adjust text size (12-24px) via settings
- **Full-screen layout** - sidebars, top bar, bottom music player
- **Beautiful modals** - glass-morphism design with glowing borders
- **Responsive controls** - WASD/Arrow keys for movement

### 🕹️ **Arcade Mini-Games**
- **Flappy DODO** - Pitch-based bird game with Suno cover generation and Practice Jam leaderboard
- **Musical Snake** - Rhythm-based snake game
- **DodoGuessr** - Music tag guessing game
- **DODOTRIS** - Musical Tetris
- **Practice Spotlight** - Quick-start overlays highlight featured artists, tempo tips, and challenge recommendations
- **Practice Insights (NEW!)** - Arcade sessions now surface mentor tips and signature abilities tied to RPG musicians to guide song-specific practice

### 📚 **Educational Content**
- **100-question Suno Timeline Quiz** covering Suno AI history (2023-2025)
- **10 credits per correct answer**
- **Detailed explanations** for each question
- **Learn about Suno features** through interactive gameplay

### 🏪 **Progression Systems**
- **Cleffy's Music Store** - buy equipment, instruments, and education
- **Equipment upgrades** - boost fan multipliers and unlock genres
- **Level-gated content** - unlock new items and challenges as you progress
- **Music player** - queue and play your created songs

### 🔧 **Backend Helpers**
- **/leaderboard & /leaderboard/record** - capture Practice Jam scores with offline-first caching
- **/practice/hints** - serve curated tips that surface inside Practice Jam overlays
- **/practice/spotlight** - return featured artist spotlights + recommended challenges for practice overlays

## 🚀 Getting Started

### Installation

```bash
# Install dependencies
pnpm install
```

### Development

```bash
# Start development server
pnpm start

# Runs on http://localhost:3000
```

### Testing

```bash
# Run all tests
pnpm test

# Run tests once (no watch)
pnpm test --watchAll=false

# Generate coverage report
pnpm test --coverage --watchAll=false

# Run comprehensive validation suite
npx ts-node comprehensive-test.ts

# Quick validation
./validate.sh
```

### Production Build

```bash
# Create optimized production build
pnpm build

# Build output in /build directory
```

## 📁 Project Structure

```
tony_dev_tunes/
├── src/
│   ├── components/
│   │   ├── RPGGame.tsx             # Main RPG game component
│   │   ├── RPGGame.css             # RPG game styles
│   │   ├── RPGGame_settings.css    # Settings modal styles
│   │   ├── FlappyDODO/             # Pitch-based mini-game
│   │   ├── MusicalSnake/           # Rhythm mini-game
│   │   ├── DODOTRIS/               # Musical Tetris
│   │   ├── DodoGuessr.tsx          # Tag guessing game
│   │   ├── panels/                 # UI panels (Genre, Statistics, Quests)
│   │   └── ui/                     # Reusable UI components
│   ├── stores/                     # Zustand state management (TypeScript)
│   │   ├── gameStore.ts            # Player, world, progression state
│   │   ├── uiStore.ts              # UI state (modals, messages)
│   │   └── settingsStore.ts        # User preferences
│   ├── systems/                    # Game systems (10 managers)
│   │   ├── GenreManager.ts         # Genre XP, leveling, skills
│   │   ├── EventManager.ts         # Event lifecycle
│   │   ├── QuestEngine.ts          # Branching quests
│   │   ├── SaveManager.ts          # Compressed save system
│   │   └── ...                     # 6 more managers
│   ├── data/
│   │   ├── musicians.ts            # 134 musician database
│   │   ├── genres.ts               # 30 genres, 101 skills
│   │   ├── instruments.ts          # 20+ instruments, materials
│   │   ├── worldEvents.ts          # 12 world events
│   │   ├── questlines.ts           # 5 branching quests
│   │   ├── roomNames.ts            # Procedural room naming
│   │   └── sunoQuestions.ts        # 100 quiz questions
│   ├── hooks/                      # Custom React hooks (TypeScript)
│   ├── types/                      # TypeScript type definitions
│   ├── utils/                      # Utility functions
│   └── App.tsx                     # Main app component
├── public/                         # Static assets
├── comprehensive-test.ts           # TypeScript validation suite
├── validate.sh                     # Quick validation script
└── package.json                    # Dependencies

```

## 🎮 How to Play

### Controls
- **WASD / Arrow Keys** - Move your character
- **Space** - Interact with challenges/NPCs
- **Move to edges** - Explore new rooms (dashed borders)

### Sidebar Buttons (Right)
- 🔍 **Find Challenge** - Spawn new musician battles
- ⚙️ **Settings** - Adjust font size, toggle sound effects (NEW!)
- 🛒 **Store** - Buy upgrades with Suno Credits
- 📖 **Help** - View controls and features
- 🗺️ **World Map** - See explored rooms and fast travel
- 🧠 **Quiz** - Test your Suno knowledge
- 🕹️ **Arcade** - Play mini-games
- 🎵 **Genre Mastery** - Level up 30 genres, unlock 101 skills (NEW!)
- 📊 **Statistics** - View comprehensive analytics dashboard (NEW!)
- 📜 **Quest Log** - Track branching questlines (NEW!)
- 🚪 **Exit** - Return to main menu

### Time Travel (Left Sidebar)
- Click any time period (1720s - 2020s)
- Location updates automatically
- Find era-specific musicians

### Game Loop
1. **Explore** the map to find musician challenges
2. **Battle musicians** to learn their styles
3. **Complete challenges** to earn fans, streams, credits, and **genre XP** (NEW!)
4. **Level up genres** to unlock skills and earn bonuses (NEW!)
5. **Level up player** to unlock new content and quests
6. **Track progress** in Statistics dashboard (NEW!)
7. **Complete quests** from Wandering Musicians (NEW!)
8. **Participate in world events** for big rewards (NEW!)
9. **Travel through time** to meet different musicians
10. **Play mini-games** for bonus rewards

## 🏆 Progression

### 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)

### Resources
- **Fans** 👥 - Unlock levels and features
- **Streams** 🎧 - Generate Suno Credits
- **Suno Credits** 🎵 - Purchase store items
- **Active Challenges** 🎯 - Track current battles

## 🛠️ Technologies Used

- **React 18.3** - UI framework with TypeScript
- **TypeScript 5.3** - Type-safe development
- **Zustand 5.0** - Lightweight state management
- **Create React App** - Build tooling
- **Web Audio API** - Sound effects and audio processing
- **CSS Grid & Flexbox** - Responsive layouts
- **Jest & React Testing Library** - Testing framework
- **Chart.js 4.5** - Statistics visualization
- **date-fns 4.1** - Date formatting and manipulation

## 🎯 Game Features

### Musician Knowledge Base
- **134 legendary musicians** across 15 time periods (1720s-2020s)
- Historical context and musical styles
- Era-specific locations and genres
- Suno-compatible style prompts
- 30 music genres with 10-level mastery system

### NPC System
- **Anessa** - Quest giver (30% spawn rate, remix challenges)
- **Wandering Musician** - Green character (20% spawn, triggers Quest Log and shows available quests)
- **Enemy Musicians** - Battle system at level 2+ (risk/reward fan stakes)

### Modal System
- **All panels are draggable** - click and drag headers
- **Beautiful design** - glass-morphism with glowing borders
- **Persistent positioning** - panels remember their location
- **Easy closing** - X button with hover animations

### World Generation
- **Procedural terrain** - unique maze layouts per room
- **25-35% block density** - challenging navigation
- **Seeded randomization** - rooms stay consistent
- **Room naming** - music-themed procedural names

## 📖 Documentation

- **README.md** (this file) - Project overview, setup, and new features
- **GAME_FEATURES.md** - Detailed feature documentation
- **ARCADE_GAMES.md** - Mini-game documentation
- **suno_timelines.md** - Suno AI history reference

## 🧪 Validation

The project includes comprehensive validation tools to ensure code quality and data integrity:

```bash
# Run comprehensive TypeScript validation suite
npx ts-node comprehensive-test.ts

# Quick validation check
./validate.sh

# Run React tests
pnpm test
```

The validation suite checks:
- Data integrity (musicians, genres, instruments)
- System manager imports
- Feature coverage across eras and genres
- Quest and event systems
- Type safety across all TypeScript files

## 💡 New Feature Details

### Genre Mastery System
- **30 Genres**: Each with 10-level progression (300 total levels)
- **Auto XP**: Earn 50-90 XP when completing musician challenges
- **101 Skills**: Unlock skills at specific genre levels
- **Bonuses**: Up to +50% rewards at max level

### Statistics Dashboard
- **Auto-Tracking**: Play time, challenges, musicians defeated, exploration
- **Analytics**: Favorite genres, most played, heatmap
- **Progress Charts**: Visual representation of all progression

### Quest System
- **5 Questlines**: Save Mozart, Guide Elvis, Discover Hendrix, Beethoven's 10th, Jazz Fusion
- **Branching Choices**: Dialogue affects reputation and unlocks
- **Multiple Endings**: Each quest has 2+ possible outcomes
- **Access**: Press SPACE on Wandering Musician (green 🎵)

### World Events
- **12 Events**: Era-specific time-limited challenges
- **Auto-Spawn**: Checks every 60 seconds (5-12% chance)
- **Toast Notifications**: Appear top-right with timer and objectives
- **Examples**: Woodstock 1969, Live Aid 1985, MTV Launch 1981

### Tutorial System
- **Auto-Shows**: First-time players get guided 10-step tutorial
- **Navigation**: [←] Previous, [→] Next, [✕] Skip (in header)
- **Smart Triggers**: Auto-advances on actions (movement, room change)
- **Skippable**: Exit anytime with ✕ button

## 📝 Code Quality

This project follows TypeScript best practices with:
- **Strict type safety** across all stores and components
- **Optimized state management** using Zustand with persistence
- **Clean component architecture** with separation of concerns
- **Comprehensive testing** with Jest and React Testing Library
- **Performance optimizations** including memoization and lazy loading
- **Accessible UI** with keyboard navigation and sound settings

## 🙏 Credits

Created by Tony Tong as an educational tool for learning about music history and the Suno AI platform through interactive gameplay.

## 📝 License

This project uses Create React App and follows its licensing terms.

---

**Ready to start your music adventure? Run `pnpm start` and begin exploring!** 🎵

### 🎯 Quick Tips for New Features

**Genre XP**: Complete any musician challenge → Automatically earn XP → Level up genres → Unlock skills → Get bonuses

**Statistics**: Click 📊 button anytime to see all your progress and analytics

**Quests**: Reach Level 2+ → Meet Wandering Musician (green 🎵) → Press SPACE → Quest Log opens

**Events**: Play in different eras → Events spawn randomly → Toast notification appears top-right

**Tutorial**: New game → Tutorial auto-shows → Navigate with [←] [→] [✕] in header

**Sound Mute**: Settings → Uncheck "Sound Effects" → Silent button clicks and footsteps