From 97bdcbb7af2210d1301421872d50e3af48d5a0c8 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 30 Sep 2026 19:01:38 +0000 Subject: [PATCH] Docs: full Vantage 3D map setup guide; fully commented Paper example config Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01DjMbLQujBHunCCu5GpsHaT --- docs/live-map.md | 2 + docs/vantage-setup.md | 254 +++++++++++++++++++ examples/paper/config.yml | 97 ++++--- panel/web/src/components/LiveMapPanel.svelte | 2 +- 4 files changed, 320 insertions(+), 35 deletions(-) create mode 100644 docs/vantage-setup.md diff --git a/docs/live-map.md b/docs/live-map.md index e250020..d2b41da 100644 --- a/docs/live-map.md +++ b/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. diff --git a/docs/vantage-setup.md b/docs/vantage-setup.md new file mode 100644 index 0000000..df3cb38 --- /dev/null +++ b/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: (product site ). 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: . + +* **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//.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 `/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 `/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 `/livemap//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 ` | Memory budget for rendering. Start at `1024`. | +| `--threads ` | Maximum parallel tile renders. Give at least `2`. | +| `--radius ` | 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 ` | 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 `/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` | `/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 /livemap//world --assets --out \ + --host 127.0.0.1 --port --players-file --dimension +``` + +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. diff --git a/examples/paper/config.yml b/examples/paper/config.yml index c903c58..e30d2b1 100644 --- a/examples/paper/config.yml +++ b/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. 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. +# ============================================================================== diff --git a/panel/web/src/components/LiveMapPanel.svelte b/panel/web/src/components/LiveMapPanel.svelte index 33cc06f..50d3ae5 100644 --- a/panel/web/src/components/LiveMapPanel.svelte +++ b/panel/web/src/components/LiveMapPanel.svelte @@ -130,7 +130,7 @@ {#if !status.generator.installed || !status.assets.configured}

The panel stores what the server sends, but rendering needs the Vantage generator and Minecraft client assets. - Install them as described in docs/live-map.md — until then launchers show a “map is being set up” message. + Install them as described in docs/vantage-setup.md — until then launchers show a “map is being set up” message.

{/if} {#if status.last_error}

Generator: {status.last_error}

{/if}