Docs: full Vantage 3D map setup guide; fully commented Paper example config
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DjMbLQujBHunCCu5GpsHaT
This commit is contained in:
4 files changed
+320
-35
No files matched your search
@@ -0,0 +1,254 @@
|
||||
# Setting up the Vantage 3D Live Map
|
||||
|
||||
This is the complete, step-by-step guide. For a short overview of how the pieces fit, see [live-map.md](live-map.md).
|
||||
|
||||
**What you end up with:** every SCOPENET-connected server gets a 3D map inside the admin panel and a **Live Map** button in the launcher. You install Vantage **once, on the panel machine**. Nothing runs next to your Minecraft servers except the SCOPENET plugin or mod you already use.
|
||||
|
||||
```
|
||||
Minecraft server ──(SCOPENET plugin/mod)──► Panel ──runs──► vantage server ──► Admin page + Launcher button
|
||||
region files + players HTTPS / WebSocket mirror of the world (loopback only)
|
||||
```
|
||||
|
||||
> **Two things you must provide on the panel machine:** the `vantage` program, and the Minecraft **client assets** (textures and models) that Vantage needs to draw blocks. The panel will not draw a map until both exist. Everything else works out of the box.
|
||||
|
||||
---
|
||||
|
||||
## 0. Before you start
|
||||
|
||||
| You need | Notes |
|
||||
| --- | --- |
|
||||
| A running SCOPENET panel | With a **Public address** set in Settings, served over HTTPS. |
|
||||
| A game server running the SCOPENET plugin/mod | Paper plugin, or the Fabric/Forge mod. The server must be online with `online-mode=true` (the same requirement as SCOPENET itself). |
|
||||
| RAM | Allow **1 GB or more** for the panel when Live Map is on (the default 256 MB is too small). See [sizing](#7-sizing-and-performance). |
|
||||
| Disk | Roughly the size of the world's region files, plus the rendered tile cache (often the same again). |
|
||||
| A copy of Minecraft Java Edition | Needed **once**, to extract assets (step 2). It can be on any computer. |
|
||||
|
||||
Vantage is an MIT-licensed third-party project: <https://github.com/thoughts-on-things/vantage-mc> (product site <https://vantage.beacon-mc.io>). Its own server documentation is the authority on its flags.
|
||||
|
||||
---
|
||||
|
||||
## 1. Get the `vantage` program
|
||||
|
||||
Download the latest **CLI release** for the panel machine's operating system and CPU from the Vantage releases page: <https://github.com/thoughts-on-things/vantage-mc/releases/latest>.
|
||||
|
||||
* **Docker panel image:** the image has no shell and no libraries (it is built `FROM scratch`), so it needs a **statically linked Linux build** of `vantage` for the right architecture (x86_64 or arm64). If the release you pick is not static, it will fail to start inside the container with a "not found" error. In that case run the panel on the host, or use a static build.
|
||||
* **Bare-metal panel:** any build that runs on your OS works.
|
||||
|
||||
Put the file somewhere permanent and make it executable (`chmod 755 vantage`). Check it runs:
|
||||
|
||||
```sh
|
||||
./vantage --help
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Get the Minecraft client assets
|
||||
|
||||
Vantage draws blocks from the textures and models inside Minecraft's client `.jar`. You extract them once with Vantage's own command:
|
||||
|
||||
```sh
|
||||
vantage extract
|
||||
```
|
||||
|
||||
It automatically finds an installed Minecraft client jar (the launcher's `versions/<version>/<version>.jar`) and writes the assets out. Run `vantage extract --help` for the flags (for example to choose the jar or the output folder).
|
||||
|
||||
**Which version?** Use a client jar for the same Minecraft version your servers run, or a newer one. Newer is safer if the world contains newer blocks.
|
||||
|
||||
**Running extract on a different computer is fine.** Do it on your own PC (which has Minecraft installed), then copy the resulting folder to the panel machine. You do not need Minecraft on the server.
|
||||
|
||||
**Where the panel looks:** it passes the folder in `SCOPENET_VANTAGE_ASSETS` (default `<data dir>/livemap/assets`) to `vantage server --assets`. Vantage's own examples point `--assets` at a folder ending in `assets/minecraft`. So **copy the extracted folder to the panel, then point the setting at the folder Vantage expects**. If unsure, test it directly (this command should start and print that it is listening, then stop it with Ctrl+C):
|
||||
|
||||
```sh
|
||||
vantage server /path/to/any/world --assets /path/to/your/assets/folder --out /tmp/vantage-test
|
||||
```
|
||||
|
||||
If Vantage complains about missing assets, try the parent or the `minecraft` subfolder and use whichever works.
|
||||
|
||||
> **Licence note:** the assets are Mojang's. Extract them from a client you own, and do not redistribute them.
|
||||
|
||||
---
|
||||
|
||||
## 3. Install them on the panel
|
||||
|
||||
Pick **one** of the two layouts.
|
||||
|
||||
### Option A: Docker (recommended)
|
||||
|
||||
The provided `docker-compose.yml` already defines the three settings. Mount your files into the data volume or bake Vantage into the image.
|
||||
|
||||
**A1. Mount the files** (simplest; no rebuild). Put the binary and assets on the Docker host, then add volumes to the `panel` service in `docker-compose.yml`:
|
||||
|
||||
```yaml
|
||||
volumes:
|
||||
- panel-data:/data
|
||||
- ./vantage/vantage:/opt/vantage/vantage:ro # the static binary from step 1
|
||||
- ./vantage/assets:/data/livemap/assets:ro # the folder from step 2
|
||||
```
|
||||
|
||||
`SCOPENET_VANTAGE_BIN` (`/opt/vantage/vantage`) and `SCOPENET_VANTAGE_ASSETS` (`/data/livemap/assets`) already default to those paths.
|
||||
|
||||
**A2. Bake the binary in** (assets still come from a mount):
|
||||
|
||||
```sh
|
||||
VANTAGE_URL="https://…/vantage-x86_64-unknown-linux-musl.tar.gz" docker compose build
|
||||
```
|
||||
|
||||
`VANTAGE_URL` must be a direct link to a `.tar.gz` or `.zip` containing the `vantage` file for the **build machine's target architecture**.
|
||||
|
||||
**Raise the memory limit** in `.env` (or the compose file):
|
||||
|
||||
```env
|
||||
PANEL_MEMORY=1536M
|
||||
```
|
||||
|
||||
Then recreate the container:
|
||||
|
||||
```sh
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
### Option B: Panel running directly on the host
|
||||
|
||||
```sh
|
||||
export SCOPENET_VANTAGE_BIN=/opt/vantage/vantage
|
||||
export SCOPENET_VANTAGE_ASSETS=/var/lib/scopenet/livemap/assets
|
||||
# Optional extra flags for `vantage server`:
|
||||
export SCOPENET_VANTAGE_ARGS="--memory 1024 --threads 4"
|
||||
```
|
||||
|
||||
If you leave the two variables unset, the panel looks for `vantage` on `PATH` and then `/opt/vantage/vantage`, and for assets in `<data dir>/livemap/assets`. With systemd, put these in the unit's `Environment=` lines.
|
||||
|
||||
---
|
||||
|
||||
## 4. Turn the map on for a server
|
||||
|
||||
1. In the panel: **Servers → your server → Settings → Live Map** (on by default for new servers). Save.
|
||||
2. On the game server, make sure the plugin/mod has Live Map enabled. It is on by default:
|
||||
* **Paper** `plugins/SCOPENET/config.yml`: `livemap.enabled: true`
|
||||
* **Fabric/Forge** `config/scopenet.properties`: `livemap.enabled=true`
|
||||
3. **Restart the game server** (or reload the SCOPENET config) so it starts sending data.
|
||||
|
||||
The plugin reads the world's saved region files, sends only chunks newer than what the panel already has, and streams player positions every second.
|
||||
|
||||
**World location:** the plugin reads the main world's folder (the first world Paper loads, normally `world`), and the Fabric/Forge mod reads `level-name` from `server.properties`. The Nether and End are found either inside that folder (`DIM-1`, `DIM1`) or in Paper's sibling folders (`world_nether`, `world_the_end`).
|
||||
|
||||
---
|
||||
|
||||
## 5. Check that it works
|
||||
|
||||
Open **Servers → your server**. The Live Map card shows four checks:
|
||||
|
||||
| Check | Green when | If it is red |
|
||||
| --- | --- | --- |
|
||||
| **Vantage generator** | The panel found the `vantage` file. | Fix `SCOPENET_VANTAGE_BIN` / the mount (step 3). |
|
||||
| **Minecraft assets** | The assets folder exists. | Fix `SCOPENET_VANTAGE_ASSETS` (step 2–3). |
|
||||
| **World data** | Region files have arrived. | Wait for the server to upload. Big worlds take a while the first time. |
|
||||
| **Player positions** | Players are online and the server is sending them. | Have someone join; positions only flow while the server runs the plugin/mod. |
|
||||
|
||||
When all are green the map appears under **Overworld / Nether / End** tabs. In the launcher, the instance linked to that server shows a **Live Map** button. (The instance must be linked to the server in the panel, under the server's **Launcher instance** setting.)
|
||||
|
||||
**How fresh is it?** Chunk data only reaches the panel once the game server has *written it to disk*. The map therefore follows the server's autosaves (every few minutes by default). To refresh right now, run `/save-all` on the game server. Player positions are real-time.
|
||||
|
||||
---
|
||||
|
||||
## 6. How it behaves (good to know)
|
||||
|
||||
* **Sidecars start on demand.** The panel starts one `vantage server` per server and dimension when someone opens a map, and **stops it after 15 idle minutes**. The first open after idle takes a few seconds.
|
||||
* **Loopback only.** The sidecars listen on `127.0.0.1` with a random per-process token. They are never exposed. All map traffic goes through the panel and needs a signed-in session.
|
||||
* **The world mirror** lives in `<data>/livemap/<server id>/world`, and rendered tiles in a cache beside it. **Servers → Live Map → Reset map data** deletes both; the game server then uploads everything again.
|
||||
* **Pre-baking.** Vantage renders tiles in the background around spawn and players, so the map gets smoother after the first visit.
|
||||
|
||||
---
|
||||
|
||||
## 7. Sizing and performance
|
||||
|
||||
Put extra `vantage server` flags in `SCOPENET_VANTAGE_ARGS` (space separated). The useful ones:
|
||||
|
||||
| Flag | What it does |
|
||||
| --- | --- |
|
||||
| `--memory <MB>` | Memory budget for rendering. Start at `1024`. |
|
||||
| `--threads <n>` | Maximum parallel tile renders. Give at least `2`. |
|
||||
| `--radius <blocks>` | Limit how far from spawn the map extends. Saves CPU and disk on huge worlds. |
|
||||
| `--prebake off` | Only render what people look at. Lower CPU, slower first views. |
|
||||
| `--lod off` | Skip the zoomed-out overview. Smaller cache, but the map is only visible where tiles are loaded. |
|
||||
| `--scan-interval <s>` | How often it checks for changed regions (default `5`). |
|
||||
| `--caves`, `--light`, `--biome-blend` | Render quality options. See Vantage's docs. |
|
||||
|
||||
Rules of thumb:
|
||||
|
||||
* **1 server, modest world:** 1 GB panel memory, `--threads 2`.
|
||||
* **Several servers:** each open map dimension is its own process, and they stop after 15 idle minutes. Budget memory for the number of maps opened at once, not the number of servers.
|
||||
* **Huge worlds:** set `--radius`, or `--prebake off`, and be patient on the first upload.
|
||||
* **Disk:** watch `<data>/livemap`. **Reset map data** frees it.
|
||||
|
||||
---
|
||||
|
||||
## 8. Reverse proxy and HTTPS
|
||||
|
||||
The map is served from the panel's own address, so no new ports are needed. If the panel sits behind nginx, Caddy, Traefik or Cloudflare:
|
||||
|
||||
* Forward **WebSocket upgrades** to `/api/server/v1/livemap/ws`. The plugin falls back to plain HTTPS if WebSockets are blocked, but positions update faster with them.
|
||||
* Allow **large request bodies** for chunk uploads (`client_max_body_size 64m;` in nginx).
|
||||
* Do not cache `/api/livemap/` responses.
|
||||
* Keep the panel's **Public address** set to the HTTPS URL players use.
|
||||
|
||||
---
|
||||
|
||||
## 9. Privacy and access
|
||||
|
||||
* Anyone with a **signed-in account** can open a server's map. To keep a world private, leave Live Map **off** for that server, or restrict the server with its access rules.
|
||||
* The panel feeds Vantage **only the players who are online right now** (positions from the server plugin/mod). It does **not** expose the last-known positions of everyone who has ever logged in.
|
||||
* Game servers authenticate with their normal `sn_…` token; servers with Live Map off are refused.
|
||||
|
||||
---
|
||||
|
||||
## 10. Troubleshooting
|
||||
|
||||
| You see | Cause and fix |
|
||||
| --- | --- |
|
||||
| Generator "Not installed on the panel" | The panel can't find `vantage`. Check `SCOPENET_VANTAGE_BIN`, the volume mount, and that the file is executable. In Docker, check the file is a **static** Linux build for the right CPU. |
|
||||
| "Minecraft client assets for Vantage aren't configured" | The assets folder is missing or the path is wrong. Re-check step 2–3 and that the folder is readable by the container user (uid 65532). |
|
||||
| "Waiting for the game server to upload this world" | The panel has no `level.dat` or region files for that dimension yet. Check the plugin/mod is connected (server page shows Online), Live Map is on in **both** the panel and the plugin config, and wait for an autosave or run `/save-all`. |
|
||||
| Launcher shows "the map is being prepared" | Same as above, or the generator/assets check is red. |
|
||||
| "couldn't start the Vantage generator" | The file isn't executable, is for another CPU/OS, or (in Docker) isn't static. Try running it by hand. |
|
||||
| Map loads but is blank or shows pink/black blocks | Wrong or incomplete assets. Re-extract from a client jar of the right version. |
|
||||
| Map is out of date | Chunks appear only after the server saves. Run `/save-all`, or lower the autosave interval in the server settings. |
|
||||
| Some dimensions are greyed out | That dimension has no region data yet. Visit it in-game and save. |
|
||||
| Everything is slow | Raise `PANEL_MEMORY` and `--threads`, set `--radius`, or use `--prebake off`. |
|
||||
| No players on the map | Positions only arrive while the plugin/mod is running and someone is online. Confirm the "Player positions" check. |
|
||||
| Panel logs: generator stopped | Normal after 15 idle minutes. It restarts on the next open. |
|
||||
|
||||
Still stuck? Open the server page, read **"Generator: …"** under the checklist (it shows the last error from Vantage), and check the panel logs with `RUST_LOG=debug`.
|
||||
|
||||
---
|
||||
|
||||
## 11. Reference
|
||||
|
||||
**Panel settings (environment variables)**
|
||||
|
||||
| Variable | Default | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `SCOPENET_VANTAGE_BIN` | `vantage` on `PATH`, then `/opt/vantage/vantage` | The Vantage executable. |
|
||||
| `SCOPENET_VANTAGE_ASSETS` | `<data dir>/livemap/assets` | Extracted Minecraft client assets. |
|
||||
| `SCOPENET_VANTAGE_ARGS` | none | Extra flags appended to `vantage server`. |
|
||||
| `PANEL_MEMORY` (Docker) | `256M` | Container memory limit. Use `1G` or more for Live Map. |
|
||||
| `VANTAGE_URL` (Docker build arg) | empty | Direct link to a static Vantage release to bake into the image. |
|
||||
|
||||
**Game server settings**
|
||||
|
||||
| Where | Key | Default |
|
||||
| --- | --- | --- |
|
||||
| Paper `config.yml` | `livemap.enabled` | `true` |
|
||||
| Fabric/Forge `config/scopenet.properties` | `livemap.enabled` | `true` |
|
||||
| Panel, per server | Live Map switch | on for new servers |
|
||||
|
||||
**What the panel runs for each map** (for reference):
|
||||
|
||||
```
|
||||
vantage server <data>/livemap/<id>/world --assets <assets> --out <cache> \
|
||||
--host 127.0.0.1 --port <random> --players-file <players.json> --dimension <dim> <your extra flags>
|
||||
```
|
||||
|
||||
with the secret passed in `VANTAGE_SERVER_TOKEN`.
|
||||
|
||||
**Not verified here:** the exact names of Vantage's release files and the exact folder layout that `vantage extract` produces change between Vantage versions. This guide was written against Vantage's published README and server documentation; follow Vantage's own `--help` if they differ.
|
||||
Reference in new issue
Block a user