76 lines
4.1 KiB
Markdown
76 lines
4.1 KiB
Markdown
# Live Map (central Vantage)
|
||
|
||
> **Looking for the simplest map?** Use BlueMap: [bluemap.md](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](vantage-setup.md). This page is the overview.
|
||
|
||
The panel hosts a [Vantage](https://github.com/thoughts-on-things/vantage-mc) 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.
|