blade/SCOPENET-MC
1
1 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Rework BlueMap claiming and expand ranks guilds chat and warps

Browse Source
This commit is contained in:
scoped committed 2026-09-30 18:09:18 -04:00
1 parent 434ed5338a
commit 6a2944a88e
68 files changed
+1453 -2500
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/deployment.md
+3 -5
View File
@@ -23,11 +23,9 @@ The panel listens on `PANEL_PORT` (default `8080`). Docker checks
`docker compose ps` before directing players to it. If `ADMIN_PASSWORD` is
blank on first start, the generated password appears in the panel logs.
To show a Vantage world map in the launcher, deploy Vantage next to each game
server and configure its manifest URL in the panel. See
[Live map setup](live-map.md). Vantage needs access to the game world's saved
files, so it runs alongside the game server rather than inside the panel
container.
To show a 2D world map and claim land in the launcher, install BlueMap on the
game server and configure its public web address in the panel. See
[Live map setup](live-map.md).
The named `panel-data` volume holds the database, uploads, hosted launcher
downloads, and the generated JWT signing key. Preserve that volume when
docs/live-map.md
+11 -65
View File
@@ -1,75 +1,21 @@
# Live Map (central Vantage)
# Live map and land claims
> **Looking for the simplest map?** Use BlueMap: [bluemap.md](bluemap.md). It needs nothing on the panel, adds guild claims, pins and a player panel, and shows inside the launcher.
>
> **Setting up the panel-hosted Vantage map?** Follow [vantage-setup.md](vantage-setup.md). This page is the overview.
SCOPENET uses [BlueMap](https://bluemap.bluecolored.de/) for terrain. Install BlueMap on the Minecraft server and make its web app reachable from players' computers. In the panel's **Servers → server settings**, enter the BlueMap **Map address**. The launcher opens the same map in its Live Map window and reads BlueMap's low resolution 2D tile images for the Guilds territory view.
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.
The terrain address must serve BlueMap's `settings.json`, per-map `settings.json`, and low resolution PNG tiles from the same URL path. A URL such as `https://maps.example.com/` works. If BlueMap is hosted below a path, include the trailing slash, for example `https://example.com/bluemap/`.
```
Minecraft server ──(SCOPENET plugin/mod)──► Admin panel ──► Launcher "Live Map" button
chunks + players HTTPS / WebSocket mirror + Vantage Vantage viewer in-app
```
## Center on the player
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*.
Turn on **Live player positions** in the server settings and leave `livemap.enabled: true` in the SCOPENET plugin or mod configuration. The game server sends current positions to the panel. The panel returns each signed-in player only their own position to the launcher. The **Find me** button centers the territory view on it; the blue dot marks their position. Positions expire when the server stops sending updates.
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.
The BlueMap map itself remains available when position relay is off. In that case, players can pan manually, but **Find me** is unavailable.
## Turn it on
## Claim controls
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.
In **Guilds & Territories**, select the game server and dimension. Left click a chunk to claim it for your guild, or drag across chunks to claim an area. Right click or right drag unclaims your guild's chunks. Alt drag pans; the wheel zooms. The overlay shows your guild's claims in green and other guilds' claims in red. The panel checks membership and claim limits for every request; only successful claims appear in the final map state.
## Panel requirements
BlueMap must have rendered the area to show terrain. Claims can still be managed by the in-game `/claim` and `/unclaim` commands when the web map is unavailable.
Rendering needs two things on the machine running the panel:
## Existing world mirror
| 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.
Older SCOPENET game integrations uploaded region chunks to the panel under `/api/server/v1/livemap`. The panel retains those ingest endpoints for compatibility with existing servers, but the launcher terrain comes from BlueMap. Current integrations send player positions only.
docs/ranks-guilds-and-warps.md
+21
View File
@@ -0,0 +1,21 @@
# Ranks, guild roles, chat and warps
## Level ranks
In the panel's **Leveling** page, create a **Player Title / Prefix** reward at each global level milestone. A title can name a LuckPerms group and a Discord role ID. The highest title the player has earned is shown in Paper chat and, when LuckPerms is installed, its configured group is assigned automatically. SCOPENET only changes LuckPerms groups explicitly named on title rewards. Existing panel group to LuckPerms mappings still work independently.
In **Settings → Discord community**, enable role sync and optionally set a base role ID. Linked players receive the Discord role for their highest earned title; players without a mapped title receive the base role. When a higher title replaces a lower one, the old managed title role is removed. Players without a linked Discord account cannot receive a Discord role; in-game chat shows the base `Novice` title until they earn a title.
Paper chat shows `[Guild tag] [Level title] [LuckPerms group display] nickname: message`. LuckPerms prefixes and suffixes decorate the name. Messages support `**bold**`, `*italic*`, `__underline__`, `~~strikethrough~~`, backtick code, and Bukkit `&` formatting. `&#RRGGBB` colors and `&` codes require `scopenet.chat.color`, which is granted to operators by default. Players set or clear a persistent nickname with `/nick <name|off>`; chat also respects display names set by other plugins.
## Guilds
Players can request to join a guild from the launcher directory. Leaders and officers review those requests from the guild roster. Leaders can edit the guild description, message of the day, icon and banner from **Guild settings**. They can create and assign custom roles with permissions for invites, kicks, claims, posts and guild details. Deleting a role returns its members to `member`.
The in-app territory view uses the configured BlueMap 2D tile address for each server. It centers on the player's last position when position relay is enabled. Left click or drag to claim; right click or drag to unclaim. On Paper, `/autoclaim on` claims each new unclaimed chunk entered while walking; `/autoclaim off` stops it. Auto-claim stops on a failed claim so it does not repeatedly send requests at the claim limit or in another guild's territory.
## Warps and item sharing on Paper
Players use `/reqwarp <name>` at the requested location. An operator or player with `scopenet.command.warp.manage` uses `/warprequests`, then `/warpapprove <name>` or `/warpdeny <name>`. Admins can create and remove warps directly with `/setwarp <name>` and `/delwarp <name>`. Pending requests are stored in `plugins/SCOPENET/warp_requests.yml`; approved warps are stored in `warps.yml`.
`/hand` sends the held item as a clickable chat entry. Other players can inspect a read-only snapshot for five minutes. The launcher **Command Guide** lists these commands and their permission nodes.
docs/vantage-setup.md
-254
View File
@@ -1,254 +0,0 @@
# 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.