SCOPENET-MC/docs/live-map.md

Live Map (central Vantage)

Looking for the simplest map? Use BlueMap: bluemap.md. It needs nothing on the panel, adds guild claims, pins and a player panel, and shows inside the launcher.

Setting up the panel-hosted Vantage map? Follow vantage-setup.md. This page is the overview.

The panel hosts a Vantage 3D map for every game server, so nobody has to run Vantage next to Minecraft.

Minecraft server ──(SCOPENET plugin/mod)──► Admin panel ──► Launcher "Live Map" button
  chunks + players      HTTPS / WebSocket     mirror + Vantage      Vantage viewer in-app

1. Collect – the SCOPENET Paper plugin / Fabric / Forge mod reads the world's region files (only chunks newer than what the panel already has) and sends them to the panel over HTTPS. Player positions stream over a WebSocket (HTTPS fallback).
2. Store & render – the panel keeps a region-file mirror per server under <data>/livemap/<server id>/world and runs a vantage server sidecar over it on demand (stopped again after 15 idle minutes). Sidecars listen on loopback only.
3. Serve – GET /api/livemap/<server>/<dimension>/v1/worlds/default/… proxies the sidecar to signed-in launcher/admin sessions. Player markers come straight from memory. One map per server and dimension (overworld, the_nether, the_end).
4. View – the launcher checks GET /api/v1/servers/<id>/livemap; when Live Map is on for a server linked to the instance, the instance page shows a Live Map button that opens the map inside the launcher (and the Guilds territory view uses it too). Admins see the same map on Servers → your server.

Chunk data only reaches the panel when the game server has written it, so the map follows autosaves (and /save-all) rather than every block change.

Turn it on

1. Servers → your server → Settings → Live Map (on by default for new servers).
2. Update the plugin/mod. livemap.enabled: true (Paper config.yml) or livemap.enabled=true (config/scopenet.properties) is the default; set it to false to keep a server off the map locally.
3. The server page shows a checklist: generator, assets, world data, player positions.

Panel requirements

Rendering needs two things on the machine running the panel:

Setting	Meaning
SCOPENET_VANTAGE_BIN	The vantage executable (default: vantage on PATH, then /opt/vantage/vantage).
SCOPENET_VANTAGE_ASSETS	Minecraft client assets directory passed as --assets (default <data>/livemap/assets).
SCOPENET_VANTAGE_ARGS	Optional extra vantage server flags, e.g. --radius 2048 --memory 1024.

With Docker, either mount your binary at /opt/vantage/vantage and the assets at /data/livemap/assets, or bake a static Linux release in with VANTAGE_URL=<release archive> docker compose build. Until both exist the panel still stores what servers send and launchers show "the map is being prepared". Give the container more than the default 256 MB if Live Map is on (PANEL_MEMORY).

Security

• Game servers authenticate with their existing sn_… token; the endpoints refuse servers whose Live Map switch is off.
• Viewers must be signed in; the launcher attaches its session token natively, so it never reaches page scripts. Anyone with an account can view a server's map — use the server's access rules and leave Live Map off for private worlds.
• The sidecar gets a random per-process bearer token and never leaves loopback.

Ingest API (for reference)

All under /api/server/v1/livemap/ with Authorization: Bearer <server token>: GET config, GET manifest?dim=, POST chunks?dim= (binary records of i32 x, i32 z, u32 timestamp, u8 compression, u32 length, bytes), POST level (level.dat), POST players, GET ws (WebSocket: JSON players frames).

External Vantage (advanced)

Under Use an external Vantage map instead you can still point a server at a manifest.json / world.json you host yourself. It is only used when Live Map is off.