EasyWebMap

EasyWebMap

Built for the European Hytale survival server at play.hyfyve.net

A live web map for your Hytale server. View your world in a browser, track players in real-time, and easily integrate with your community website.

Quick Start

Download the latest EasyWebMap.jar from Releases

Put it in your server's mods folder

Restart your server

Open http://localhost:8080 in your browser

What You Can Do

Live World Map

See your entire world rendered in a web browser

Terrain updates automatically as players build or destroy blocks

Zoom in/out and pan around freely

Uses Hytale's native map rendering (same as the in-game map)

Real-Time Player Tracking

See all online players on the map with arrow markers

Arrows rotate to show which direction players are facing

Click any player in the sidebar to jump to their location

Player positions update every second via WebSocket

Website Integration

Embed the map directly on your community website using an iframe:

<iframe src="http://your-server-ip:8080" width="100%" height="600"></iframe> Or link to it from your server's website, Discord, or forums.

REST API

Build custom tools using the built-in API:

Endpoint Returns

GET /api/worlds List of available worlds

GET /api/players/{world} All players in a world (name, position, direction)

GET /api/tiles/{world}/{z}/{x}/{y}.png Map tile image

WS /ws Real-time player position updates

Example: Fetch player positions

const response = await fetch('http://your-server:8080/api/players/world'); const players = await response.json(); // [{ name: "Steve", x: 100, y: 64, z: -200, yaw: 1.57 }, ...] Example: WebSocket for live updates

const ws = new WebSocket('ws://your-server:8080/ws'); ws.onmessage = (e) => { const data = JSON.parse(e.data); console.log(data.worlds); // All player positions by world }; Multi-World Support

Switch between worlds using the dropdown

Configure which worlds are visible

Each world has its own tile cache

Commands

Command What it does

/easywebmap status Show connection count, cache info, SSL status, and server status

/easywebmap reload Reload the config file

/easywebmap clearcache Clear all caches (memory + disk)

/easywebmap pregenerate <radius> Pre-generate tiles around your position

/easywebmap renewssl Force immediate SSL certificate renewal

All commands require the easywebmap.admin permission.

HTTPS with Let's Encrypt (Free SSL)

EasyWebMap can automatically obtain and renew SSL certificates from Let's Encrypt. No manual certificate management required!

Quick Setup

Point your domain to your server - Make sure map.yourserver.com (or whatever domain you choose) points to your server's IP address.

Open port 80 - Let's Encrypt needs to verify you own the domain by connecting to port 80. Make sure your firewall allows this.

Add to your config.json:

{ "enableHttps": true, "httpsPort": 8443, "domain": "map.yourserver.com", "acmeEmail": "admin@yourserver.com" }

Restart your server - The plugin will automatically: Register with Let's Encrypt

Request a certificate for your domain

Start serving HTTPS on port 8443

That's it! Your map is now available at https://map.yourserver.com:8443

How It Works

When you enable HTTPS, the plugin:

Creates an account with Let's Encrypt (stored in ssl/account.key)

Requests a certificate for your domain

Responds to Let's Encrypt's HTTP-01 challenge on port 80

Stores the certificate in ssl/domain.crt and key in ssl/domain.key

Starts the HTTPS server

Checks daily if the certificate needs renewal (renews 30 days before expiry)

Automatically reloads the certificate without restarting

HTTPS Configuration Options

Setting Default What it does

enableHttps false Enable/disable HTTPS

httpsPort 8443 Port for HTTPS (use 443 if you have permission)

domain "" Your domain name (required for HTTPS)

acmeEmail "" Email for Let's Encrypt notifications (optional but recommended)

useProductionAcme true Set to false for testing (uses staging server, avoids rate limits)

SSL Commands

Command What it does

/easywebmap status Shows HTTPS status, domain, and certificate expiry date

/easywebmap renewssl Force immediate certificate renewal

Requirements

Domain name - You need a domain pointing to your server (IP addresses won't work with Let's Encrypt)

Port 80 accessible - Let's Encrypt validates domain ownership via HTTP on port 80

Port 8443 (or 443) accessible - For serving HTTPS traffic

Testing First

Before going live, test with Let's Encrypt staging server to avoid rate limits:

{ "enableHttps": true, "domain": "map.yourserver.com", "useProductionAcme": false } The staging server issues test certificates that browsers won't trust, but it proves everything works. Once verified, set useProductionAcme back to true and restart.

Using Port 443 (Standard HTTPS)

By default, HTTPS runs on port 8443. If you want to use the standard HTTPS port (443):

{ "httpsPort": 443 } Note: Binding to port 443 may require running the server as root/administrator, or using a reverse proxy.

Behind a Reverse Proxy

If you're using nginx or Apache as a reverse proxy, you can let the proxy handle SSL and keep EasyWebMap on HTTP only. Example nginx config:

server { listen 443 ssl; server_name map.yourserver.com;

ssl_certificate /etc/letsencrypt/live/map.yourserver.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/map.yourserver.com/privkey.pem;

location / { proxy_pass http://localhost:8080; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; } }

Configuration

Config file: mods/cryptobench_EasyWebMap/config.json

{ "httpPort": 8080, "updateIntervalMs": 1000, "tileCacheSize": 20000, "enabledWorlds": [], "tileSize": 256, "maxZoom": 4, "renderExploredChunksOnly": true, "chunkIndexCacheMs": 30000, "useDiskCache": true, "tileRefreshRadius": 5, "tileRefreshIntervalMs": 60000, "enableHttps": false, "httpsPort": 8443, "domain": "", "acmeEmail": "", "useProductionAcme": true }

Setting Default What it does

httpPort 8080 Web server port

updateIntervalMs 1000 Player update frequency (ms)

tileCacheSize 20000 Max tiles to cache in memory (~200MB at 10KB/tile)

enabledWorlds [] World whitelist (empty = all)

renderExploredChunksOnly true Only render chunks that players have explored (prevents lag/abuse)

chunkIndexCacheMs 30000 How long to cache the explored chunks index (ms)

useDiskCache true Save tiles to disk for persistence across restarts

tileRefreshRadius 5 Player must be within N chunks for tile to refresh

tileRefreshIntervalMs 60000 Minimum time between tile refreshes (ms)

enableHttps false Enable automatic HTTPS with Let's Encrypt

httpsPort 8443 Port for HTTPS connections

domain "" Your domain name for SSL certificate

acmeEmail "" Email for Let's Encrypt notifications

useProductionAcme true Use production Let's Encrypt (false = staging for testing)

Chunk Index Cache (chunkIndexCacheMs)

When renderExploredChunksOnly is enabled, the plugin needs to check which chunks have been explored. This requires reading an index from disk. To avoid reading disk on every tile request, the index is cached.

Trade-off:

Lower value (e.g., 5000ms): New exploration shows on map faster, but more disk reads

Higher value (e.g., 60000ms): Fewer disk reads, but newly explored areas take longer to appear

What this means in practice:

Cache Time Disk Reads Map Freshness

5000 (5s) ~12/min per world New chunks visible within 5 seconds

30000 (30s) ~2/min per world New chunks visible within 30 seconds

60000 (1min) ~1/min per world New chunks visible within 1 minute

Example scenario: A player explores a new area. With chunkIndexCacheMs: 30000, the new chunks won't appear on the web map until the cache expires (up to 30 seconds). The tile will show as empty until then.

Note: This only affects newly explored chunks. Already-explored chunks are always visible. The /easywebmap clearcache command clears this cache immediately if needed

Disk Cache & Smart Refresh

The plugin uses a smart caching system to minimize server load:

Disk Cache: Tiles are saved as PNG files to mods/cryptobench_EasyWebMap/tilecache/. These persist across server restarts, so the first visitor after a restart doesn't trigger mass tile generation.

Smart Refresh: Tiles only regenerate when:

The tile is older than tileRefreshIntervalMs (default: 60 seconds), AND

A player is within tileRefreshRadius chunks (default: 5 chunks)

Why this matters:

If no players are nearby, terrain can't have changed, so the cached tile is always valid

This means 99% of tile requests serve instantly from cache with zero server load

Only actively played areas regenerate, and only once per minute at most

Flow:

Request for tile → Memory cache? → Serve instantly ↓ no Disk cache? → Fresh enough? → Serve from disk ↓ no ↓ old Generate new Players nearby? → No: Serve stale (terrain unchanged) ↓ yes Regenerate tile Pre-generation

Use /easywebmap pregenerate <radius> to warm the cache:

Generates tiles in a square around your position

Skips already-cached tiles and unexplored chunks

Runs in background with 50ms delay between tiles to avoid lag

Example: /easywebmap pregenerate 50 generates up to 10,201 tiles

No max limit - use what you need (large values will take time)

Common Use Cases

Public server map - Let players see where everyone is exploring

Website widget - Embed on your server's homepage to show live activity

Stream overlay - Display the map on your Twitch/YouTube stream

Discord bot - Use the API to post player locations or screenshots

Admin tool - Monitor player activity across your server

FAQ

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

Q: How do I embed it on my website? Use an iframe: <iframe src="http://your-server:8080" width="800" height="600"></iframe>

Q: Can I hide certain worlds? Yes, add specific world names to enabledWorlds in config. Empty array shows all.

Q: How do I put it behind a reverse proxy? Point nginx/Apache to port 8080. WebSocket path is /ws.

Q: Why do some areas show as empty on the map? By default, only explored chunks are rendered (renderExploredChunksOnly: true). This prevents server lag and abuse from users scrolling to unexplored areas. Set it to false in config if you want to render all chunks (not recommended for public servers).

Q: Can users abuse the map to lag my server? Not with default settings. The renderExploredChunksOnly option (enabled by default) prevents rendering unexplored chunks, so scrolling around won't trigger chunk generation.

Q: How do I enable HTTPS? Add "enableHttps": true and "domain": "your-domain.com" to your config. The plugin automatically gets a free SSL certificate from Let's Encrypt. See the HTTPS section above for details.

Q: Why isn't my SSL certificate working? Common issues:

Domain doesn't point to your server's IP

Port 80 is blocked by firewall (Let's Encrypt needs this for verification)

Another service is using port 80 Check the server logs for specific error messages.

Q: Do I need to renew the certificate manually? No! The plugin automatically checks daily and renews certificates 30 days before they expire. You never need to touch it.

Q: Can I use my own SSL certificate instead of Let's Encrypt? Currently, only automatic Let's Encrypt certificates are supported. If you need to use your own certificate, put EasyWebMap behind a reverse proxy (nginx/Apache) that handles SSL.

Q: What if Let's Encrypt is down or rate-limited? The plugin will keep serving HTTP normally. It retries certificate requests and logs any errors. Once Let's Encrypt is available again, certificates will be obtained automatically.

Building from Source

mvn clean package cp target/EasyWebMap-1.0.0.jar /path/to/Server/mods/ Requires Java 25+ and Maven 3.8+.

License

MIT - Do whatever you want with it!