web-adventure/SETUP.md

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

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

# 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

/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

   cd /Users/luka/dev/me/web-adventure
   

2. Install Dependencies (one-time only)

   pip install -r requirements.txt
   

3. Run the Game

   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:

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:

const colors = ['#FF6B6B', '#4ECDC4', '#45B7D1', ...];

Game Duration

Change GAME_DURATION in backend.py:

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

# 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! 🗡️⚔️🛡️