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

docs/live-map.md

@@ -1,5 +1,7 @@
 # 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.
 

docs/vantage-setup.md

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

examples/paper/config.yml

@@ -1,96 +1,125 @@
-# SCOPENET Paper plugin  ->  plugins/SCOPENET/config.yml (this is a copy of the file the plugin creates on first start)
 # ==============================================================================
-# SCOPENET Minecraft Server Configuration
+# SCOPENET Paper plugin  ->  plugins/SCOPENET/config.yml
+# Fully commented example. Every key shown here is read by the plugin; the values
+# are the defaults. Remove anything you don't want to change.
+# Requires Paper 1.20+ and online-mode=true in server.properties.
 # ==============================================================================
-# Connect to your SCOPENET Panel instance by pasting your server token below.
-# Create a server under 'Servers' in the web panel to generate a token.
 
+# --- Connection (required) ----------------------------------------------------
+# The panel's address, with no trailing path. Use the address players and servers
+# can reach, normally the same HTTPS address you set as the panel's Public address.
 panel-url: "https://panel.example.com"
+
+# The server token. In the panel: Servers -> your server -> Generate token.
+# It starts with "sn_". Keep it secret; anyone with it can act as this server.
 token: ""
 
 # ==============================================================================
-# Feature Toggles
-# Every system below is fully toggleable. You do not need to force all features
-# on every server—turn on only what makes sense for your server's gameplay style.
+# Feature toggles
+# Turn off anything you don't want on this server. Changing a value needs
+# "/scopenet reload" or a restart. The panel can still switch features off for you.
 # ==============================================================================
 
 leveling:
-  # Global & Server leveling progression (tracks playtime, kills, mining, etc.)
+  # Global and per-server levels, earned from playtime, kills, mining and more.
   enabled: true
-  # Multiplier for account-wide Global Level XP (1.0 = standard speed)
+  # Speed of the account-wide Global Level. 1.0 is normal, 2.0 is double.
   global-xp-multiplier: 1.0
-  # Multiplier for this server's specific Server Level XP (1.5 = 1.5x speed)
+  # Speed of this server's own Server Level. Higher than global by default so
+  # a server's level feels alive.
   server-xp-multiplier: 1.5
 
 quests:
-  # Daily and Weekly quests progression tracking
+  # Daily and weekly quests. How many are offered is set in the panel
+  # (Progression -> Quest limits).
   enabled: true
 
 achievements:
-  # Minecraft-themed achievements and milestone unlock notifications
+  # Achievement tracking and unlock notifications.
   enabled: true
 
 guilds:
-  # Guilds partying system and /guild commands
+  # Guilds, /guild commands, the guild bank and guild market.
   enabled: true
-  # FTB Chunks-style chunk land-claiming and protection against other guilds
+  # Guild land claims. Other players can't build or break in a claimed chunk
+  # unless they are in that guild (or have scopenet.claims.bypass).
+  # Claims are checked against a local copy that refreshes from the panel, so
+  # breaking blocks never waits on the network.
   land-claiming: true
-  # Allow guild members to damage each other (PvP friendly fire)
+  # Let guild members hurt each other.
   friendly-fire: false
 
 social:
-  # Friends status, direct messaging bridge, and server game invites
+  # Friends, direct messages and game invites.
   enabled: true
-  # Show player guild tag and level title in chat formatting
+  # Show guild tag and level title in chat.
   chat-prefixes: true
 
 essentials:
-  # Essentials commands (/spawn, /home, /sethome, /delhome, /back, /tpa, /tpaccept, /tpdeny, /rtp, /warp, /playtime)
+  # /spawn /home /sethome /delhome /back /tpa /tpaccept /tpdeny /rtp /warp /playtime
   enabled: true
-  # Maximum homes per player
+  # Homes per player.
   max-homes: 5
-  # RTP search radius
+  # /rtp picks a random safe spot within this many blocks of 0,0.
   rtp-radius: 2500
 
 livemap:
-  # Send world chunks and live player positions to the panel's central Live Map.
-  # Players open it from the launcher; you don't run Vantage on this server.
-  # It also needs "Live Map" switched on for this server in the panel.
+  # Send world chunks and player positions to the panel's central 3D Live Map.
+  # Nothing runs on this server; the panel renders it. Needs "Live Map" switched on
+  # for this server in the panel, and Vantage installed on the panel.
+  # Setup guide: docs/vantage-setup.md
   enabled: true
 
 economy:
-  # Server Economy commands (/balance, /pay, /baltop, /shop, /sell, /market, /orders, /trade, /transactions)
+  # /balance /pay /baltop /shop /sell /market /orders /trade /transactions
   enabled: true
-  # Currency symbol
+  # Shown next to amounts.
   currency-symbol: "$"
 
-
 # ==============================================================================
-# Plugin integrations
-# SCOPENET detects these plugins by itself; switch any of them off here.
+# Optional plugin integrations
+# SCOPENET finds these plugins by itself. Switch one off here if you don't want it.
+# "/scopenet status" shows which are active.
 # ==============================================================================
 integrations:
   luckperms:
     enabled: true
-    # Send each online player's LuckPerms rank to the panel (profiles, admin view).
+    # How often each online player's LuckPerms rank is sent to the panel, which
+    # shows it on profiles and the server page.
     report-interval-seconds: 60
-    # Let the panel add/remove LuckPerms group membership for groups an admin has mapped to a panel
-    # group (Panel > Players > Groups). LuckPerms stays in charge of permissions; this is off unless you opt in.
+    # Let the panel add or remove LuckPerms groups for players, for groups an admin
+    # mapped in Panel -> Players -> Groups. LuckPerms still decides real permissions.
+    # Off by default: turn it on only when you want panel groups to change ranks here.
     apply-panel-groups: false
   placeholderapi:
-    # %scopenet_level%, %scopenet_guild%, %scopenet_balance%, %scopenet_playtime%, %scopenet_quest_progress% ...
+    # Adds %scopenet_level%, %scopenet_guild%, %scopenet_balance%, %scopenet_playtime%,
+    # %scopenet_quest_progress% and more for scoreboards, tab lists, holograms and chat.
     enabled: true
   vault:
-    # Use the SCOPENET economy as Vault's economy, so other plugins' shops and jobs pay into it.
+    # Make SCOPENET's economy the Vault economy, so shop, jobs and other plugins
+    # use the same balances.
     enabled: true
   coreprotect:
+    # Show logging activity and backup status in the panel.
     enabled: true
-    # Folders scanned for world backups shown in the panel.
+    # Folders (relative to the server folder) checked for world backups.
     backup-folders:
       - backups
   worldguard:
+    # Show WorldGuard regions, including server-owned territory, in the panel.
     enabled: true
     report-interval-minutes: 5
   spark:
+    # Show TPS, MSPT, CPU and memory in the panel.
     enabled: true
     report-interval-seconds: 30
+
+# ==============================================================================
+# Permissions (set these in LuckPerms, not here)
+#   scopenet.command.<command>             e.g. scopenet.command.home
+#   scopenet.command.guild.*               every /guild subcommand
+#   scopenet.command.*                     everything
+#   scopenet.claims.bypass                 build in other guilds' claims (staff)
+#   scopenet.admin                         /scopenet status and reload
+# All nodes are listed in the plugin's plugin.yml.
+# ==============================================================================

panel/web/src/components/LiveMapPanel.svelte

@@ -130,7 +130,7 @@
     {#if !status.generator.installed || !status.assets.configured}
       <p class="hint-box small">
         The panel stores what the server sends, but rendering needs the Vantage generator and Minecraft client assets.
-        Install them as described in <code>docs/live-map.md</code> — until then launchers show a “map is being set up” message.
+        Install them as described in <code>docs/vantage-setup.md</code> — until then launchers show a “map is being set up” message.
       </p>
     {/if}
     {#if status.last_error}<p class="err small">Generator: {status.last_error}</p>{/if}