# Fire Nation Attacked - Major Update Plan v2

## Overview

This document outlines the planned features for the next major update. Please respond inline with `> your response` or edit directly.

---

## 1. Level System (10 Levels)

### Design Approach
- Each level has its own music track (~45 seconds)
- Music synchronized with enemy spawns at key moments
- One JSON file per level defining spawns
- Design for **medium difficulty speed**, accept slight timing variations on easy/hard

### Level File Format (Proposed)
```json
{
  "id": 1,
  "title": "First Contact",
  "music": "level1.mp3",
  "duration_ms": 45000,
  "spawns": [
    { "time_ms": 0, "type": "ember_scout", "lane": 0.5 },
    { "time_ms": 2500, "type": "ember_scout", "lane": 0.35 },
    { "time_ms": 5000, "type": "flare_serpent", "lane": 0.6 }
  ]
}
```

**Questions:**

Q1: Is this JSON format good, or would you prefer something else (YAML, custom text format)?

>good

Q2: Should `lane` be 0-1 (percentage of screen height) or pixel values?

>%

Q3: For music-synced moments, should we add an optional `cue` field to mark important sync points?

>no but I think it's important that we're able to add comments at the end of lines so that we know why we choose certain values

---

## 2. Level Duration & Flow

### Feedback on 45 Seconds
45 seconds per wave is appropriate for this style. Tower defense waves typically range 30-90 seconds. For a music-synced arcade game with 10 levels:
- Keeps intensity high without fatigue
- Total playtime ~8-10 minutes per run
- Good for "one more try" loop

### Between Waves
Current flow (continuous with rain transition) maintains momentum and musical continuity. A "ready" button would break this.

### Die & Retry
Keeping the restart-from-beginning design is good. Level select adds complexity and reduces tension.

**Questions:**

Q4: Confirm: keep current rain transition between waves, no "ready" button?

>yes

Q5: On death, should music fade out gracefully or cut immediately?

>fade out and then go back to the start screen music

---

## 3. Difficulty Balancing

### Current Modifiers
| Difficulty | Speed | Damage | Score |
|------------|-------|--------|-------|
| Easy | 0.7x | 0.7x | 1x |
| Medium | 1.0x | 1.0x | 2x |
| Hard | 1.3x | 1.4x | 3x |

### Proposed Approach
- Design levels for medium speed
- Easy: enemies arrive slower, music may extend slightly past last enemy
- Hard: enemies arrive faster, brief silence after music ends before wave complete

**Questions:**

Q6: Should hard mode also have MORE enemies, or just faster/stronger ones?

>More ennemies

Q7: Current score multipliers (1x/2x/3x) - keep these or adjust?

>Let's do: (1x/2x/4x)

---

## 4. New Enemy Types

### Current Enemies
| Enemy | Speed | HP | Well Damage | Color | Pattern |
|-------|-------|-----|-------------|-------|---------|
| Ember Scout | 168 | 6 | 8 | Orange #ff6b4a | Straight |
| Flare Serpent | 112 | 10 | 12 | Yellow #ffbd4a | Sine |
| Basalt Guardian | 118 | 21 | 20 | Red #ff3758 | Square zigzag |

### New Enemy 1: Swift Cinder (Fast Enemy)
| Property | Value | Notes |
|----------|-------|-------|
| Speed | 672 (4x base) | Very fast |
| HP | 4 | Low - quick to kill if you react |
| Well Damage | 5 | Low |
| Color | Hot red/white | Intense, signals danger |
| Pattern | Straight | No dodging, pure speed test |

The trace segments will naturally appear more spaced due to speed (ghost system handles this automatically).

### New Enemy 2: Inferno Boss
| Property | Value | Notes |
|----------|-------|-------|
| Speed | 80 | Slow, menacing |
| HP | 50 | High - needs sustained fire |
| Well Damage | 0 | Doesn't reach well, explodes first |
| Color | Blue #4a9fff | Distinct from others |
| Pattern | Straight | Predictable |
| Explodes at | 50% of screen width | Spawns 5 Ember Scouts |

**Explosion Mechanics:**
- If killed before 50%: No explosion, costs ~60 water
- If reaches 50%: Explodes into 5 Ember Scouts spreading in fan pattern
- Total water to kill fragments: ~100 (5 scouts at ~20 each)
- Incentive: Kill early to save water

**Questions:**

Q8: Swift Cinder speed 4x (672) - is this too fast? Should we test 3x (504) first?

>let's try x4 first

Q9: Inferno Boss explosion at exactly 50%, or slightly random (45-55%) for variety?

>repeatable 40%

Q10: When boss explodes, should fragments spread in a fan pattern, or scatter randomly?

>repeatable fan pattern

Q11: Should boss have a visual "charging up" effect as it approaches explosion point?

>yes

Extra notes: Swift Cinder should have 1HP so they get one shot.

---

## 5. Level Editor (Developer Mode)

### Concept
A graphical interface to create/edit levels:
- Play/pause timeline
- Drag enemies from palette onto playfield
- Click to place at current time + Y position
- Generates JSON level file
- Could enable community level creation

### Implementation Approach
1. Separate page/mode accessible via URL parameter (`?editor=true`) or key press
2. Shows enemy palette on side
3. Timeline scrubber at bottom
4. Click on playfield to place enemy at that Y position and current time
5. Export button generates JSON

**Questions:**

Q12: Priority - build editor before or after the 10 levels are playable with music?

>Create the 10 levels with music first. Do your best to create decent V0 of each level, but we'll probably use the editor to improve them.

Q13: Should editor be accessible to players, or hidden developer-only tool?

>accessible to players without adding clutter/confusion.

Q14: Key to enter editor mode - suggestion: press 'E' on title screen?

>Should just be a mouse clickable menu, e.g. "editor mode".

---

## 6. Music System

### Current State
- Menu has procedural music via AudioManager
- No per-level music

### Proposed System
- Intro/menu: loops provided track
- Each level: plays level-specific track once
- Music continues through rain transition
- If wave ends before music: let music finish
- If music ends before wave: continue in silence (acceptable)

### Audio Format
WAV files are too large (~15-50MB each). Recommendations:

| Format | Size (45s stereo) | Browser Support | Quality |
|--------|-------------------|-----------------|---------|
| WAV | ~15MB | Universal | Lossless |
| MP3 192kbps | ~1MB | Universal | Excellent |
| OGG 192kbps | ~1MB | All except old Safari | Excellent |
| AAC 192kbps | ~1MB | Universal | Excellent |

**Recommendation: MP3** for universal compatibility and 90%+ size reduction.

**Questions:**

Q15: MP3 acceptable, or preference for another format?

>It's fine but are you sure we know how to play it? I've always struggled to do this in Python, or maybe in JS it's trivial?

Q16: Will you provide the music files, or should I create silent placeholders for testing?

>Everything is in the assets folder. You can turn them into .mp3.

Q17: Should menu music crossfade into level 1 music, or hard cut?

> Fade out, short silence, starts music lvl 1.

---

## 7. Water Management

### Current Problem
Too easy to run out of water, especially with more enemies in later levels.

### Proposed Fix
Increase water gained from vacuuming sacred well:
- Current: `wellVacuumRate: 30` (units/sec to tank)
- Proposed: `wellVacuumRate: 150` or higher
- Result: ~0.7 seconds to fully refill tank
- Cost: ~7% of sacred well HP per full refill

This makes water management tactical (choose when to refill) without being punishing.

### Brainstorm Ideas (Future)
- Enemies occasionally drop water orbs
- Combo kills create water splash
- Special "rain cloud" enemy that releases water when killed
- Power-up that temporarily gives infinite water

**Questions:**

Q18: Is the faster well-vacuum approach sufficient, or do you want to explore water drops from enemies?

>It's sufficient but 0.7s is too short. Let's try 1s.

Q19: Should tank drain rate also be adjusted, or keep current?

>Let's keep it constant for now.

---

## 8. Sensitivity Settings

### Proposed UI
Small, minimalistic settings accessible from title screen:
- Two sliders: X sensitivity, Y sensitivity
- Default: middle position (current values)
- Range: 0.5x to 2x current sensitivity
- Saves to localStorage

### UI Location Options
A. Small gear icon in corner of title screen
B. Below difficulty selection buttons
C. Hidden until mouse moves to edge of screen
D. Press 'S' key to toggle settings overlay

**Questions:**

Q20: Which UI location do you prefer (A/B/C/D)?

>A

Q21: Should sensitivity be adjustable during gameplay, or only on title screen?

>Only title screen

---

## 9. HuggingFace Login Instructions

### Current Issue
- Instructions are outdated
- Process is confusing (click link, generate key, paste in terminal)
- Ctrl+Shift+V for paste is non-obvious
- Wireless vs Light robot adds complexity (SSH required for wireless)

### Proposed Approach
1. Update in-game instructions text
2. Link to external detailed guide with screenshots
3. Guide covers both Light and Wireless setups

**Questions:**

Q22: What is the correct updated HuggingFace login command?

>hf auth login

Q23: Where should the external guide be hosted? (GitHub wiki, docs site, etc.)

>Let's just write a text that appears when the users clicks on "How to see and publish leaderboards?" Something like:
 "To see and publish leaderboards, you need to authenticate your machine to HuggingFace. The procedure depends on the type of robot you have:
 If you have a Reachy Mini Lite, type this command in a terminal on your PC and follow the instructions to provide a key with `write` permissions: `hf auth login` (make sure you activate Mini's virtual environment, or do `pip install --upgrade huggingface_hub`)
 If you have a Reachy Mini Wireless, the same procedure must be done on the embedded computer using SSH. You can follow this procedure: 
 From your computer:
 `ssh pollen@reachy-mini.local`
 -> password is `root` 
  you'll then be on a terminal inside the embedded computer. There type:
  `source /venvs/apps_venv/bin/activate`
  and then:
  `hf auth login` --> follow the instructions and provide a key with `write` permissions
  
Extra documentation:
https://huggingface.co/docs/huggingface_hub/en/quick-start
"

Q24: Should the game detect if HF is not configured and show a reminder?

>I think it already does, we just need to improve the message (cf above)

---

## 10. Implementation Order (Proposed)

### Phase 1: Foundation
1. [ ] Convert WAV music to MP3
2. [ ] Create level file loading system
3. [ ] Add music playback per level
4. [ ] Create 10 basic level JSON files (placeholder enemy patterns)

### Phase 2: New Enemies
5. [ ] Implement Swift Cinder (fast enemy)
6. [ ] Implement Inferno Boss (exploding enemy)
7. [ ] Update enemy color scheme

### Phase 3: Balance & Polish
8. [ ] Adjust water management (well vacuum rate)
9. [ ] Add sensitivity settings UI
10. [ ] Update HuggingFace instructions
11. [ ] Test and balance all 10 levels

### Phase 4: Level Editor (Optional)
12. [ ] Build level editor interface
13. [ ] Add export/import functionality

**Questions:**

Q25: Does this order make sense? Any changes to priority?

>good. Handle the hf loging first.

Q26: Any features to cut or defer to a later update?

>

---

## Notes & Additional Ideas

(Add any other thoughts here)

>