SCOPENET-MC/docs/vantage-setup.md

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.

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.
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:

./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:

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):

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:

    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):

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):

PANEL_MEMORY=1536M

Then recreate the container:

docker compose up -d --build

Option B: Panel running directly on the host

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.