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

# 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

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

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

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:

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