258 lines
6.3 KiB
Markdown
258 lines
6.3 KiB
Markdown
# 🗺️ 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
|
|
```
|
|
|
|
## Map Editor
|
|
|
|
The server includes a built-in web-based editor for managing game data.
|
|
|
|
### Accessing the Editor
|
|
|
|
Navigate to: **http://localhost:8080/editor**
|
|
|
|
### Authentication
|
|
|
|
The editor requires a password for access. Set it via environment variable:
|
|
|
|
```bash
|
|
export EDITOR_PASSWORD="your_secure_password"
|
|
export EDITOR_SECRET_KEY="$(python -c 'import secrets; print(secrets.token_hex(32))')"
|
|
```
|
|
|
|
**Default password (if not set):** `admin123`
|
|
|
|
> [!WARNING]
|
|
> **Security**: Always change the default password in production! Set `EDITOR_PASSWORD` in your `.env` file.
|
|
|
|
### Editor Features
|
|
|
|
- **Locations Tab**: Edit location properties, coordinates, danger levels, spawn tables
|
|
- **NPCs Tab**: Manage enemy stats, loot tables, and spawn weights
|
|
- **Items Tab**: Edit item properties, stats, crafting recipes, repair materials
|
|
- **Interactables Tab**: Manage interactable templates and actions
|
|
- **Connections Tab**: Create/delete connections between locations
|
|
- **Logs Tab**: View API container logs and restart the bot
|
|
|
|
### Environment Variables
|
|
|
|
| Variable | Description | Default |
|
|
|----------|-------------|----------|
|
|
| `EDITOR_PASSWORD` | Password for editor access | `admin123` |
|
|
| `EDITOR_SECRET_KEY` | Flask session secret key | Auto-generated |
|
|
| `PORT` | Server port | `8080` |
|
|
|
|
## 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**: Flask server with RESTful API
|
|
- **Frontend**: Vanilla JavaScript with HTML5 Canvas
|
|
- **Authentication**: Session-based with password protection
|
|
- **Data Storage**: Direct JSON file manipulation
|
|
- **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
|
|
|
|
To modify the editor:
|
|
|
|
1. Edit `editor.html` for editor UI layout
|
|
2. Edit `editor_enhanced.js` for editor functionality
|
|
3. Edit `server.py` API routes for backend logic
|
|
|
|
The server auto-loads changes - just refresh your browser!
|
|
|
|
## Security Best Practices
|
|
|
|
1. **Change Default Password**: Always set `EDITOR_PASSWORD` to a strong password
|
|
2. **Use HTTPS**: In production, use a reverse proxy (Traefik/Nginx) with SSL
|
|
3. **Restrict Access**: Use firewall rules to limit editor access to trusted IPs
|
|
4. **Backup Data**: Regularly backup `gamedata/` folder before making changes
|
|
5. **Test Changes**: Use the export/import feature to test changes before applying
|
|
|
|
## License
|
|
|
|
Part of the Echoes of the Ashes RPG project.
|