# Live Map (central Vantage)

> **Setting it up?** Follow the step-by-step guide: [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.