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

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

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

The server auto-loads changes - just refresh your browser!

License

Part of the Echoes of the Ashes RPG project.