# WebMap Integration

# WebMap Integration

KyuubiSoft Panel integrates with EasyWebMap to provide a live, interactive map of your Hytale world with real-time player tracking.

## Overview

The WebMap feature provides:
- **Live 2D map** of your server world
- **Real-time player positions** with names
- **Chunk visualization** showing loaded areas
- **Zoom and pan** controls
- **Coordinate display** on hover
- **WebSocket updates** for instant refresh

## Requirements

- **EasyWebMap Plugin** - Must be installed on the server
- **KyuubiAPI Plugin** - Provides the data bridge
- **Port Configuration** - WebMap ports must be accessible

## Configuration

### Environment Variables

```bash
# WebMap HTTP port for tile serving
WEBMAP_PORT=18081

# WebMap WebSocket port for live updates
WEBMAP_WS_PORT=18082
```

### Plugin Configuration

In your server's `plugins/EasyWebMap/config.json`:

```json
{
  "enabled": true,
  "httpPort": 18081,
  "wsPort": 18082,
  "renderDistance": 10,
  "updateInterval": 1000,
  "showPlayers": true,
  "showChunkBorders": false
}
```

## Accessing the Map

### Via Panel

1. Navigate to **WebMap** in the sidebar
2. The map loads automatically
3. Use controls to navigate

### Direct Access

Open in browser:
```
http://YOUR_SERVER:18081
```

### Embedded View

The panel proxies the WebMap through:
```
http://YOUR_PANEL:18080/api/webmap/
```

This allows single-port access when using a reverse proxy.

## Map Controls

### Navigation

| Control | Action |
|---------|--------|
| **Scroll** | Zoom in/out |
| **Drag** | Pan the map |
| **Double-click** | Center on location |
| **Right-click** | Copy coordinates |

### Interface Elements

- **Zoom Buttons** - +/- for zoom control
- **Layer Toggle** - Show/hide different layers
- **Player List** - Click to center on player
- **Coordinates** - Current mouse position
- **Fullscreen** - Expand to full screen

## Player Tracking

### Live Positions

Players appear as markers on the map:
- **Online players** - Show current position
- **Moving players** - Update in real-time via WebSocket
- **Player names** - Displayed above markers

### Player Information

Click on a player marker to see:
- Username
- Current coordinates (X, Y, Z)
- Health status
- Current world

## Proxy Architecture

The panel acts as a reverse proxy to the WebMap:

```
Browser → Panel (18080) → WebMap HTTP (18081)
                       → WebMap WS (18082)
```

### Why Proxy?

1. **Single port exposure** - Only expose panel port
2. **Authentication** - Uses panel JWT tokens
3. **CORS handling** - Avoids cross-origin issues
4. **SSL termination** - Single HTTPS endpoint

### Proxy Endpoints

| Panel Endpoint | Target |
|----------------|--------|
| `/api/webmap/*` | WebMap HTTP server |
| `/api/tiles/*` | WebMap `/api/tiles` |
| `/api/worlds/` | WebMap `/api/worlds` |
| `/api/webmap-ws` | WebMap WebSocket |

## Reverse Proxy Setup

### Nginx Configuration

```nginx
# Panel and WebMap proxy
location / {
    proxy_pass http://localhost:18080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
}

# Direct WebMap access (optional)
location /map/ {
    proxy_pass http://localhost:18081/;
}
```

### With SSL

```nginx
server {
    listen 443 ssl;
    server_name panel.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:18080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

## API Reference

### Endpoints

The panel proxies WebMap requests to the external EasyWebMap service:

| Method | Panel Endpoint | Description |
|--------|----------------|-------------|
| GET | `/api/webmap/*` | General WebMap requests |
| GET | `/api/tiles/:z/:x/:y` | Get map tiles |
| GET | `/api/worlds/` | Get world and player data |
| WS | `/api/webmap-ws` | WebSocket for live updates |

### WebSocket Messages

**Player Update:**
```json
{
  "type": "player_update",
  "players": [
    {
      "name": "PlayerName",
      "x": 100,
      "y": 64,
      "z": -200,
      "world": "world"
    }
  ]
}
```

**Chunk Update:**
```json
{
  "type": "chunk_update",
  "chunk": {
    "x": 6,
    "z": -13,
    "rendered": true
  }
}
```

## Permissions

WebMap access is controlled through general server permissions. Users with `server.view` permission can access the WebMap feature.

## Troubleshooting

### Map Not Loading

1. **Check plugin installation:**
   ```bash
   docker exec hytale ls plugins/ | grep -i webmap
   ```

2. **Verify ports are accessible:**
   ```bash
   curl http://localhost:18081/
   ```

3. **Check plugin logs:**
   ```bash
   docker-compose logs hytale | grep -i webmap
   ```

### Players Not Showing

1. Ensure `showPlayers: true` in plugin config
2. Check KyuubiAPI plugin is connected
3. Verify WebSocket connection in browser dev tools

### Tiles Not Rendering

1. Wait for chunks to be generated
2. Check render distance setting
3. Verify disk space for tile cache

### WebSocket Disconnects

1. Check reverse proxy WebSocket config
2. Verify `TRUST_PROXY=true` if proxied
3. Check browser console for errors

## Performance Tips

1. **Limit render distance** - Lower `renderDistance` for better performance
2. **Increase update interval** - Higher `updateInterval` reduces CPU usage
3. **Use tile caching** - Tiles are cached after first render
4. **Limit simultaneous viewers** - Many viewers increase bandwidth