WebMap

Live demo: https://hynfinity.com/map

Hytale Server 2026.03.26 or later

A live web map for your Hytale server. View your world in a browser, track players in real-time, and embed the map on your community website.

Quick Start

1. Download the latest WebMap-*.jar from Releases
2. Drop it in your server's mods/ directory
3. Start the server
4. Open http://your-server-ip:8080 in a browser

Features

World map

• Hytale's native map rendering served as PNG tiles
• Configurable pyramid with averaged downsampling at each zoom level
• Background prewarmer pre-renders the full explored area so the first visitor doesn't wait for tiles
• Changes made in-game (place / break) update the web map within a few seconds — every tile a player edits is re-rendered, and only the tiles that actually changed are written to disk (per-tile content hash skips redundant writes)
• Tile cache on disk, browser cache for repeat views

Player tracking

• Every player is rendered with their real in-game head, composited from the server's character assets using the player's customisation
• Directional arrow above each marker shows where the player is looking (yaw)
• Player list drawer with live coordinates; click to center or follow
• Auto-follow survives temporary invisibility (e.g. crouching) and resumes when the player reappears
• Positions pushed in real-time over Server-Sent Events

Live chat

Public chat messages are relayed to a collapsible chat panel on the web map in real-time. A speech bubble also appears above the player's marker for 5 seconds. Players can opt out with /webmap chat. The panel opens by default on desktop and is collapsed on mobile.

Shareable URLs

Every view is reproducible via the URL hash — world, position, zoom and followed player are all encoded. Copy the URL to share an exact view, or reload to restore your last spot.

#world=overworld&x=-128.5&z=42&zoom=0&follow=<uuid>

Multi-world

Switch between worlds from the topbar. Each world has its own tile cache and its own dirty-tile tracker, so edits in one world never trigger re-renders in another.

Website embedding

<iframe src="http://your-server-ip:8080" width="100%" height="600"></iframe>

REST API

Commands

Aliases: /wm, /map. Non-admin commands are unrestricted unless a permission is explicitly set.

Configuration

The config file is created on first run in the plugin data folder.

{
  "configVersion": 4,
  "httpPort": 8080,
  "httpHost": "0.0.0.0",
  "basePath": "/",
  "threadPoolSize": 4,
  "tileCacheDirectory": "tile-cache",
  "tileCacheMaxEntries": 10000,
  "playerUpdateIntervalSeconds": 3,
  "tileRefreshIntervalSeconds": 300,
  "worldListMode": "whitelist",
  "enabledWorlds": [],
  "showPlayerAltitude": false,
  "showPlayersByDefault": true,
  "allowPlayerToggleVisibility": true,
  "hidePlayersWhenCrouching": true,
  "corsOrigin": "*",
  "minZoom": -3,
  "maxZoom": 4,
  "maxNativeZoom": 0,
  "prewarmEnabled": true,
  "prewarmStartupDelaySeconds": 10,
  "prewarmIntervalMinutes": 30,
  "prewarmThrottleMillis": 50,
  "showPlayerHeads": true,
  "showPlayerDirection": true,
  "characterAssetsPath": "",
  "playerHeadCacheMaxEntries": 500,
  "playerHeadSize": 32,
  "playerHeadProviderUrl": "https://hyvatar-worker.bodyagavril.workers.dev/?username={username}",
  "simpleClaimsEnabled": false,
  "simpleClaimsShowByDefault": true,
  "simpleClaimsFillOpacity": 0.25,
  "simpleClaimsRefreshSeconds": 30,
  "markersEnabled": false,
  "markersShowByDefault": true,
  "markersRefreshSeconds": 60,
  "markersFilterMode": "none",
  "markersFilterPatterns": [],
  "barterShopEnabled": false,
  "renderQuality": "medium",
  "notifyAdminsOnGeneration": true,
  "chatRelayEnabled": true,
  "showChatBubbles": true,
  "hstatsEnabled": true
}

HTTP server

Tiles & zoom

Players

Player heads

Live chat

Players can opt out of chat relay individually with /webmap chat.

Analytics

SimpleClaims integration

Off by default. When enabled, WebMap reads claim data from the SimpleClaims plugin via reflection and draws every claimed chunk as a clickable rectangle on top of the map. Clicking a rectangle opens a popup with the party name, owner, member count, PvP flag, and block protection flags.

If SimpleClaims is not installed, the plugin loads cleanly and the integration stays dormant — /api/claims/{world} returns 404, and the topbar toggle button is hidden. The rectangles sit on top of whatever the base tiles already show, so if SimpleClaims has also baked its own tint into the tiles, both remain visible.

The endpoint GET /api/claims/{world} returns one entry per party with the full chunk list as [[chunkX, chunkZ], ...] pairs. Each chunk is 32 × 32 blocks (Hytale's native chunk size).

Map markers (POIs)

Off by default. When enabled, WebMap displays native Hytale points of interest on the map — spawn points, forgotten temples, portals, shared player markers, and any markers added by other mods. Icons are the real Hytale marker images, bundled in the plugin JAR and auto-extracted from installed mod JARs at startup.

Markers are collected from Hytale's WorldMapManager marker providers when a player is online. A disk cache preserves markers across player disconnections and server restarts so the map is never empty.

If no marker-capable mods are installed, only the spawn point is shown.

Admins can place custom icon PNGs in {dataFolder}/marker-icons/ to override the bundled icons. Files are matched by name (e.g. Spawn.png, Temple_Gateway.png).

BarterShop integration

Off by default. When enabled, WebMap reads shop data from Makapar's Barter Shops directly from its JSON files on disk ({universe}/BarterShop/shops/). Clicking a shop marker on the map shows a "View Shop" button that opens a detail panel with every trade the shop offers (items sold / wanted with quantities).

If BarterShop is not installed, the integration stays dormant — the button is hidden and /api/shops/{world} returns 404. No compile-time dependency on BarterShop — the plugin reads plain JSON files.

Worlds

Reverse proxy

To serve the map behind nginx at https://play.example.com/map:

1. Set "basePath": "/map" in the config
2. Add the location block:

location /map/ {
    proxy_pass http://localhost:8080/map/;
    proxy_http_version 1.1;
    proxy_set_header Connection '';
    proxy_buffering off;
    proxy_cache off;
}

FAQ

How do I access the map from another device? Use the server's IP instead of localhost: http://192.168.1.100:8080.

Why do some areas show as empty? Only explored chunks are rendered by Hytale's map system. Unvisited chunks appear blank until a player walks near them.

Does it work on mobile? Yes. The UI has a horizontal topbar and a right drawer that slides in on narrow viewports.

How do I enable HTTPS? Use a reverse proxy (nginx, Caddy…) to handle TLS termination. The plugin serves HTTP only.

A player built something but the map still shows the old terrain. The update pipeline re-renders dirty tiles every few seconds in the background. If a tile hasn't refreshed after ~10s, check /webmap status — the processor will report how many base and zoom-out tiles are pending. A manual /webmap cache warm forces a full-world pass.