# Agent Instructions for Fire Nation Attacked

This file contains instructions for AI agents working on this project.

## Visual Testing

### Overview

Visual regression tests use Playwright to capture screenshots across multiple browsers:
- **Chromium** (Chrome/Edge)
- **Firefox**
- **WebKit** (Safari)

Tests are located in `visual_testing/`.

### Prerequisites

1. The game server must be running on port 8000
2. Playwright browsers must be installed

### Running Visual Tests

```bash
# 1. Start the game server (from project root)
cd /home/remi/reachy_mini_apps/fire_nation_attacked
python -m fire_nation_attacked.main &

# 2. Navigate to visual testing directory
cd visual_testing

# 3. Install dependencies (first time only)
npm install
npx playwright install --with-deps chromium firefox
# For WebKit/Safari (requires sudo on Linux):
sudo npx playwright install --with-deps webkit

# 4. Run tests for all browsers
npx playwright test

# Or run for specific browser:
npx playwright test --project=chromium
npx playwright test --project=firefox
npx playwright test --project=webkit
```

### Screenshots Output

Screenshots are saved to `visual_testing/screenshots/<browser>/`:

| Screenshot | Description |
|------------|-------------|
| `01-tutorial-welcome.png` | First-time tutorial popup with robot diagram |
| `02-main-menu-difficulty.png` | Main menu with EASY/MEDIUM/HARD buttons |
| `03-main-menu-leaderboard.png` | Main menu with leaderboard/scores visible |
| `04-level-intro.png` | Level intro screen with title and image |
| `05-gameplay-enemies.png` | Active gameplay with enemies on battlefield |
| `06-gameplay-flames.png` | Gameplay with enemies attacking (flames) |
| `07-sacred-well-attack.png` | Sacred well under attack (HP reduced) |
| `08-water-puddles.png` | Water puddles on battlefield |
| `09-hud-wave-score.png` | HUD showing wave counter and score |
| `10-water-tank-partial.png` | Water tank bar partially drained |
| `11-sacred-well-hp.png` | Sacred well HP indicator during attack |
| `12-game-over.png` | Game over screen with RESTART button |
| `13-editor-empty.png` | Level editor initial empty state |
| `14-editor-with-level.png` | Editor with level created |
| `15-editor-enemy-panel.png` | Enemy types panel in editor |
| `16-viewport-*.png` | Different viewport sizes (720p, fullhd, macbook, 1440p) |

### Important: Game Input Simulation

The game requires `fireActive = true` (simulating antenna spray) to select buttons.
Mouse clicks don't work - tests use `sprayAt()` helper function that:
1. Sets `window.gameState.pointer` to target position
2. Sets `window.gameState.fireActive = true`
3. Waits for game to process the input
4. Sets `fireActive = false`

The game state is exposed via `window.gameState` for testing purposes.

### WebKit/Safari on Linux

WebKit requires system dependencies that need sudo:
```bash
sudo npx playwright install --with-deps webkit
```

### GitHub Actions

The `.github/workflows/visual-test.yml` workflow runs visual tests on:
- Ubuntu (Chromium, Firefox, WebKit)
- macOS (Chromium, Firefox, WebKit) - **Real Safari engine**
- Windows (Chromium, Firefox)

Screenshots are uploaded as artifacts and retained for 7 days.

### Analyzing Screenshots

After running tests, review screenshots for:

1. **Layout issues** - Elements cut off, overlapping, or mispositioned
2. **Font rendering** - Text clarity differences between browsers
3. **Color accuracy** - Gradients, transparency, shadows
4. **Responsive scaling** - UI adapts properly to viewport sizes
5. **Canvas sizing** - Game canvas fills viewport without gaps
6. **Button positions** - EASY/MEDIUM/HARD buttons aligned correctly
7. **Gameplay elements** - Enemies, flames, water, traces render correctly

### Common Issues

| Issue | Likely Cause | Solution |
|-------|--------------|----------|
| Port 8000 in use | Existing server running | `pkill -f "fire_nation_attacked"` |
| WebKit fails | Missing system deps | Run with sudo |
| Screenshots show menu not gameplay | Button click didn't work | Check `sprayAt()` targeting |
| No enemies visible | Wait time too short | Increase `waitForTimeout` |
| Tests timeout | Slow machine | Increase timeout in config |

### Test Configuration

Edit `visual_testing/playwright.config.js` to:
- Change base URL (default: `http://localhost:8000`)
- Adjust timeouts
- Add/remove browser projects
- Enable auto-start of server (uncomment `webServer` section)

## Project Structure

```
fire_nation_attacked/
├── fire_nation_attacked/     # Main Python app
│   ├── main.py              # FastAPI server
│   └── static/              # Frontend assets
│       ├── index.html       # Game page
│       ├── editor.html      # Level editor
│       ├── game.js          # Game logic
│       ├── render.js        # Canvas rendering
│       ├── state.js         # Game state (exposed as window.gameState)
│       └── config.js        # Configuration
├── visual_testing/          # Playwright tests
│   ├── tests/
│   │   └── visual.spec.js   # Test definitions
│   ├── screenshots/         # Output screenshots
│   │   ├── chromium/
│   │   ├── firefox/
│   │   └── webkit/
│   ├── playwright.config.js # Playwright config
│   └── package.json         # Node dependencies
└── .github/workflows/
    └── visual-test.yml      # CI workflow
```

## Game Flow Reference

```
Tutorial Welcome (first time)
    ↓
Main Menu ("waiting" phase)
  - EASY / MEDIUM / HARD buttons
  - TUTORIAL button
  - SCORES button
    ↓
Level Intro (3 seconds)
    ↓
Wave (active gameplay)
  - Enemies spawn and move right
  - Player sprays water to kill enemies
  - Enemies shoot flames at sacred well
    ↓
Cleanup (between waves)
    ↓
Rain (refill phase)
    ↓
Upgrade Selection (every 2 waves)
    ↓
Next Wave... or Game Over / Victory
```