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:

```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.