Initial commit: Echoes of the Ashes - Telegram RPG Bot
This commit is contained in:
Joan
202
web-map/README.md
Normal file
202
web-map/README.md
Normal file
@@ -0,0 +1,202 @@
|
||||
# 🗺️ Echoes of the Ashes - Interactive Map Visualizer
|
||||
|
||||
A web-based interactive map viewer for the RPG game world.
|
||||
|
||||
## Features
|
||||
|
||||
- **Interactive Canvas Map**: Drag, zoom, and explore the game world
|
||||
- **Real-time Location Data**: Dynamically loaded from game data
|
||||
- **Distance Calculations**: Shows travel distances and stamina costs
|
||||
- **Location Details**: Click on locations to see full information
|
||||
- **Connection Routes**: Visual representation of all travel paths
|
||||
- **Statistics Dashboard**: View map statistics and metrics
|
||||
- **Responsive Design**: Works on desktop and mobile devices
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Option 1: Docker (Recommended)
|
||||
|
||||
The map server is included in the docker-compose setup:
|
||||
|
||||
```bash
|
||||
docker compose up -d echoes_of_the_ashes_map
|
||||
```
|
||||
|
||||
Access the map at: **http://localhost:8080**
|
||||
|
||||
### Option 2: Standalone Python Server
|
||||
|
||||
```bash
|
||||
cd web-map
|
||||
python server.py
|
||||
```
|
||||
|
||||
Optional: Specify a custom port
|
||||
```bash
|
||||
python server.py --port 3000
|
||||
```
|
||||
|
||||
## Features Overview
|
||||
|
||||
### Map Controls
|
||||
|
||||
- **🖱️ Pan**: Click and drag to move around the map
|
||||
- **🔍 Zoom**: Use mouse wheel or zoom buttons to adjust view
|
||||
- **🎯 Reset**: Return to default view
|
||||
- **🏷️ Toggle Labels**: Show/hide location names
|
||||
|
||||
### Location Information
|
||||
|
||||
Click on any location node to see:
|
||||
- Location name and description
|
||||
- Coordinates (X, Y)
|
||||
- Number of interactables
|
||||
- Connected locations with distances
|
||||
- Estimated stamina costs for travel
|
||||
|
||||
### Map Legend
|
||||
|
||||
- **Green Circles**: Locations
|
||||
- **Blue Lines**: Travel routes
|
||||
- **Orange Circle**: Selected location
|
||||
- **Pink Badge**: Number of interactables at location
|
||||
|
||||
## Map Statistics
|
||||
|
||||
The dashboard shows:
|
||||
- **Total Locations**: Number of places in the game world
|
||||
- **Total Routes**: Number of connections between locations
|
||||
- **Longest Route**: Maximum distance between connected locations
|
||||
- **Average Distance**: Mean distance across all routes
|
||||
|
||||
## Technical Details
|
||||
|
||||
### Data Source
|
||||
|
||||
The map dynamically loads data from `/map_data.json`, which is generated from the game's world loader. The data includes:
|
||||
|
||||
```json
|
||||
{
|
||||
"locations": [
|
||||
{
|
||||
"id": "start_point",
|
||||
"name": "🌆 Ruined Downtown Core",
|
||||
"description": "...",
|
||||
"x": 0.0,
|
||||
"y": 0.0,
|
||||
"interactable_count": 3
|
||||
}
|
||||
],
|
||||
"connections": [
|
||||
{
|
||||
"from": "start_point",
|
||||
"to": "gas_station",
|
||||
"direction": "north",
|
||||
"distance": 2.0
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Server Architecture
|
||||
|
||||
- **Backend**: Python HTTP server with dynamic data generation
|
||||
- **Frontend**: Vanilla JavaScript with HTML5 Canvas
|
||||
- **Responsive**: CSS Grid and Flexbox layout
|
||||
- **Real-time**: Live data from game world loader
|
||||
|
||||
### Port Configuration
|
||||
|
||||
Default port: **8080**
|
||||
|
||||
To change the port, modify:
|
||||
1. `docker-compose.yml`: Update the ports mapping
|
||||
2. Or use `--port` flag when running standalone
|
||||
|
||||
## Customization
|
||||
|
||||
### Styling
|
||||
|
||||
Edit `index.html` to customize:
|
||||
- Colors and gradients
|
||||
- Card layouts
|
||||
- Typography
|
||||
- Responsive breakpoints
|
||||
|
||||
### Map Appearance
|
||||
|
||||
Edit `map.js` to customize:
|
||||
- Node sizes and colors
|
||||
- Line widths
|
||||
- Scale factors
|
||||
- Animation effects
|
||||
|
||||
## Production Deployment
|
||||
|
||||
### With Reverse Proxy (Nginx/Caddy)
|
||||
|
||||
```nginx
|
||||
location /map {
|
||||
proxy_pass http://localhost:8080;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
}
|
||||
```
|
||||
|
||||
### Public Access
|
||||
|
||||
To make it accessible globally:
|
||||
|
||||
1. **Port Forward**: Open port 8080 on your firewall
|
||||
2. **Domain**: Point a subdomain to your server
|
||||
3. **SSL**: Use Let's Encrypt for HTTPS
|
||||
|
||||
Example with Caddy:
|
||||
```
|
||||
map.yourdomain.com {
|
||||
reverse_proxy localhost:8080
|
||||
}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Map Not Loading
|
||||
|
||||
1. Check if server is running:
|
||||
```bash
|
||||
docker ps | grep map
|
||||
```
|
||||
|
||||
2. Check logs:
|
||||
```bash
|
||||
docker logs echoes_of_the_ashes_map
|
||||
```
|
||||
|
||||
3. Verify port is accessible:
|
||||
```bash
|
||||
curl http://localhost:8080
|
||||
```
|
||||
|
||||
### Data Not Updating
|
||||
|
||||
The map data is generated dynamically. If you've changed location coordinates:
|
||||
1. Restart the map server
|
||||
2. Hard refresh browser (Ctrl+F5)
|
||||
|
||||
### Connection Issues
|
||||
|
||||
If running in Docker, ensure the container is on the correct network and ports are properly mapped.
|
||||
|
||||
## Development
|
||||
|
||||
To modify the map visualization:
|
||||
|
||||
1. Edit `map.js` for canvas rendering logic
|
||||
2. Edit `index.html` for layout and UI
|
||||
3. Edit `server.py` for data serving logic
|
||||
|
||||
The server auto-loads changes - just refresh your browser!
|
||||
|
||||
## License
|
||||
|
||||
Part of the Echoes of the Ashes RPG project.
|
||||
Reference in New Issue
Block a user