Skip to main content

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​

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

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

ControlAction
ScrollZoom in/out
DragPan the map
Double-clickCenter on location
Right-clickCopy 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 EndpointTarget
/api/webmap/*WebMap HTTP server
/api/tiles/*WebMap /api/tiles
/api/worlds/WebMap /api/worlds
/api/webmap-wsWebMap WebSocket

Reverse Proxy Setup​

Nginx Configuration​

# 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​

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:

MethodPanel EndpointDescription
GET/api/webmap/*General WebMap requests
GET/api/tiles/:z/:x/:yGet map tiles
GET/api/worlds/Get world and player data
WS/api/webmap-wsWebSocket for live updates

WebSocket Messages​

Player Update:

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

Chunk Update:

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

    docker exec hytale ls plugins/ | grep -i webmap

  2. Verify ports are accessible:

    curl http://localhost:18081/

  3. Check plugin logs:

    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