306 lines
8.5 KiB
Markdown
306 lines
8.5 KiB
Markdown
# 🎮 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! 🗡️⚔️🛡️
|
|
|