# 🎮 Web Adventure - Community RPG

A multiplayer browser-based RPG where players collaborate to defeat a boss monster before time runs out!

## 🚀 Quick Start

### Option 1: Easy Launcher (Recommended)
```bash
cd /Users/luka/dev/me/web-adventure
python launcher.py
```
This will automatically start the backend server and open the game in your browser.

### Option 2: Manual Start
```bash
# Terminal 1 - Start backend
cd /Users/luka/dev/me/web-adventure
python -m uvicorn backend:app --reload --host 0.0.0.0 --port 8000

# Terminal 2 - Open frontend
# Open file:///Users/luka/dev/me/web-adventure/index.html in your browser
```

### Option 3: Shell Script
```bash
/Users/luka/dev/me/web-adventure/start.sh
```

## 📋 Requirements

- Python 3.8+
- Modern web browser (Chrome, Firefox, Safari, Edge)
- No additional Python packages needed (all included in requirements.txt)

## ⚙️ Installation

### First Time Setup

1. **Clone/Navigate to Project**
   ```bash
   cd /Users/luka/dev/me/web-adventure
   ```

2. **Install Dependencies** (one-time only)
   ```bash
   pip install -r requirements.txt
   ```

3. **Run the Game**
   ```bash
   python launcher.py
   ```

That's it! The game should automatically open in your browser.

## 🎯 How to Play

### Game Objective
**Defeat the boss monster before time runs out!** The game lasts 30 minutes. If you succeed, you win big rewards. If you fail, the world resets.

### Getting Started
1. Enter your username (1-30 characters)
2. Choose your player color
3. Click "Enter the World"
4. You spawn in a random location on the map

### Player Mechanics

**Stats**
- **Level**: Increases as you gain experience (exp)
- **Health**: Decreases when attacked, recovers slowly
- **Action Points**: Limited actions per minute (start with 20)
  - Each action (move, attack, gather, build) costs 1 AP
  - Regenerates 1 per minute naturally
  - Farms increase regeneration rate
- **Attack/Defense**: Combat stats affecting damage and damage taken
- **Movement Capacity**: How far you can move per action

### Movement
- Use directional buttons: ⬆ ⬇ ⬅ ➡
- Move up to 5 tiles per action
- Follow other players to find resources and monsters

### Gathering Resources
- Click 🌳 **Gather** button near Trees or Mountains
- Gain **Wood** or **Stone**
- Resources are used to build structures
- Limited range (must be close to resource)

### Combat System
- Click ⚔️ **Attack** button to attack nearby enemies
- **Damage = Your Attack - Enemy Defense + random variance**
- Each attack costs 1 action point
- Defeat monsters to:
  - Gain experience points
  - Level up (every 100 exp = +1 level)
  - Increase your stats
  
**Boss Monster**
- Appears when players reach level 10+
- Significantly stronger than regular monsters
- Requires coordination with other players
- Defeating it = **Victory!** (before timer runs out)

### Building Structures
Three types of structures, each costing different resources:

**🏠 House** (20 Wood, 10 Stone)
- Provides +20 max health bonus
- Makes you more durable
- Helpful for survivability

**🌾 Farm** (15 Wood, 5 Stone)
- Increases action point regeneration nearby
- Generates action points faster for nearby players
- Great for team bonuses

**🛡️ Guard Tower** (30 Wood, 20 Stone)
- Provides +2 defense bonus
- Reduces damage taken
- Helps defend against monsters

**Structure Benefits**
- Structures provide bonuses to all nearby players (radius ~10 tiles)
- Multiple structures stack their bonuses
- Permanent until world resets

### Resource Types
- **Wood**: From trees (green cones) - Used in all structures
- **Stone**: From mountains (gray cones) - Used in all structures

### Winning the Game
1. **Level Up** to at least level 10
2. **Boss Appears** automatically when conditions are met
3. **Coordinate Attacks** with other players
4. **Defeat the Boss** before the 30-minute timer ends
5. **Victory!** All players receive major experience rewards

### Game Over Conditions
- **Victory**: Boss defeated before time runs out
- **Defeat**: Timer reaches 0:00
- World resets and player stats return to level 1

## 🎮 Control Summary

| Action | Button | Cost | Effect |
|--------|--------|------|--------|
| Move Up | ⬆ | 1 AP | Move 5 tiles north |
| Move Down | ⬇ | 1 AP | Move 5 tiles south |
| Move Left | ⬅ | 1 AP | Move 5 tiles west |
| Move Right | ➡ | 1 AP | Move 5 tiles east |
| Gather | 🌳 | 1 AP | Collect nearby resource |
| Attack | ⚔️ | 1 AP | Damage nearby monster/boss |
| Build House | 🏠 | 1 AP | Place house structure |
| Build Farm | 🌾 | 1 AP | Place farm structure |
| Build Tower | 🛡️ | 1 AP | Place tower structure |

## 🏗️ Project Structure

```
web-adventure/
├── backend.py           # FastAPI server with game logic
├── index.html           # Complete frontend with 3D rendering
├── launcher.py          # Easy startup script
├── start.sh             # Bash startup script
├── requirements.txt     # Python dependencies
├── README.md            # This file
└── SETUP.md             # Detailed setup guide
```

## 🔧 Backend API

### REST Endpoints

**POST /api/login**
- Login and create player
- Body: `{"username": "name", "color": "#FF6B6B"}`
- Returns: Player data, session ID, game status

**GET /api/game/state**
- Get full game state (players, monsters, structures, resources)
- Returns: Complete game world data

**POST /api/player/{player_id}/move**
- Move player
- Body: `{"dx": 5, "dy": 0}`
- Returns: New position, action points

**POST /api/player/{player_id}/action**
- Perform action (attack, gather, build)
- Body: `{"action_type": "attack", "target_id": "monster_123"}`
- Returns: Action result

**POST /api/game/start**
- Start/restart the game round
- Returns: Game status

**GET /api/health**
- Server health check
- Returns: `{"status": "ok"}`

### WebSocket Connection

**WS /ws/{player_id}**
- Real-time game updates (10 updates/second)
- Receive: Player positions, monster data, boss status, timer
- Automatic game tick updates

## 📊 Game Configuration

Edit constants in `backend.py` to customize:

```python
GAME_DURATION = 30 * 60              # 30 minutes
GRID_SIZE = 500                      # 500x500 tile map
ACTION_POINTS_MAX = 20               # Starting action points
ACTION_POINTS_REGEN_INTERVAL = 60    # 1 minute regeneration
MONSTER_SPAWN_RATE = 0.1             # Spawn rate per tick
MAX_MONSTERS = 50                    # Max monsters on map
BOSS_HEALTH_BASE = 1000              # Boss starting health
MIN_LEVEL_FOR_BOSS = 10              # Minimum level to spawn boss
```

## 🎨 Customization

### Colors
Edit the color array in `index.html` to add/change player colors:
```javascript
const colors = ['#FF6B6B', '#4ECDC4', '#45B7D1', ...];
```

### Game Duration
Change `GAME_DURATION` in `backend.py`:
```python
GAME_DURATION = 15 * 60  # 15 minutes instead of 30
```

### Difficulty
Adjust these values in `backend.py`:
- Increase `BOSS_HEALTH_BASE` for harder boss
- Increase `MONSTER_SPAWN_RATE` for more monsters
- Change `MIN_LEVEL_FOR_BOSS` for earlier/later boss appearance

## 🐛 Troubleshooting

### Port 8000 Already in Use
```bash
# Find process using port 8000 and kill it
lsof -i :8000
kill -9 <PID>

# Or use different port
python -m uvicorn backend:app --host 0.0.0.0 --port 8001
```

### Browser Won't Load Game
- Make sure backend is running: http://localhost:8000/docs
- Try refreshing the page
- Clear browser cache
- Try a different browser

### Game Lags
- Reduce player count (have fewer people logged in)
- Lower monitor refresh rate
- Close other browser tabs

### Action Points Not Regenerating
- Game must be running (wait for "Game Started" message)
- Action points regenerate every 60 seconds
- Farm structures nearby increase regeneration

## 📝 Technical Stack

- **Backend**: FastAPI + Uvicorn + WebSockets
- **Frontend**: HTML5 + Three.js (WebGL)
- **Real-time**: WebSocket protocol for live updates
- **Language**: Python 3.8+, JavaScript

## 🚀 Future Features

- Persistent database for leaderboards
- Player guilds/teams
- More structure types
- Trading between players
- PvP combat zones
- Quests and achievements
- Mobile app version
- Seasonal resets with new content
- Boss tier progression
- Special events and limited-time challenges

## 📞 Support

If you encounter issues:
1. Check error messages in browser console (F12)
2. Check terminal output for server errors
3. Verify all dependencies installed: `pip list`
4. Try restarting the server

## 🎉 Enjoy!

You now have a working multiplayer RPG! Invite friends, explore, and defeat the boss together!

Good luck, adventurer! 🗡️⚔️🛡️