echoes-of-the-ash/web-map/README.md

🗺️ 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:

docker compose up -d echoes_of_the_ashes_map

Access the map at: http://localhost:8080

Option 2: Standalone Python Server

cd web-map
python server.py

Optional: Specify a custom port

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:

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:

{
  "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)

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:

   docker ps | grep map
   

2. Check logs:

   docker logs echoes_of_the_ashes_map
   

3. Verify port is accessible:

   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.