Fix achievement icons in launcher, allow opening OAuth URLs, live map docs
- Shared achievement icon catalogue; launcher resolves icon/background/border ids - Tauri opener capability now allows http(s) URLs (fixes Discord sign-in) - Rewrite live map docs, admin guide progression section Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DjMbLQujBHunCCu5GpsHaT
This commit is contained in:
17 files changed
+511
-151
No files matched your search
+63
-36
@@ -1,44 +1,71 @@
|
||||
# Vantage live map
|
||||
# Live Map (central Vantage)
|
||||
|
||||
SCOPENET can display a [Vantage](https://github.com/thoughts-on-things/vantage-mc)
|
||||
world in the launcher's **Guilds & Claims → Territory** view. The map shows
|
||||
live terrain, optional player positions, SCOPENET guild names, and the claim
|
||||
outline for each nearby chunk. Clicking terrain selects the chunk; the Claim
|
||||
and Unclaim buttons use the existing authenticated SCOPENET API. Claim
|
||||
protection on the game server is unchanged.
|
||||
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.
|
||||
|
||||
## Set up the world map
|
||||
```
|
||||
Minecraft server ──(SCOPENET plugin/mod)──► Admin panel ──► Launcher "Live Map" button
|
||||
chunks + players HTTPS / WebSocket mirror + Vantage Vantage viewer in-app
|
||||
```
|
||||
|
||||
1. Install a Vantage release on the machine that can read the Minecraft world
|
||||
files. Give it read access to the save, and a separate writable cache.
|
||||
2. Start a live render for that world. For example:
|
||||
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*.
|
||||
|
||||
```sh
|
||||
vantage live /srv/minecraft/world --out /var/cache/vantage/world --host 127.0.0.1 --port 8268
|
||||
```
|
||||
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.
|
||||
|
||||
3. Put Vantage behind an HTTPS reverse proxy, or have your portal proxy its
|
||||
map files. The launcher's **Vantage live map manifest URL** is the complete
|
||||
`manifest.json` URL, such as `https://maps.example.com/manifest.json`.
|
||||
A pre-rendered multi-dimension world can use `world.json` instead. In the
|
||||
panel, open **Servers → your server → Edit** and save that URL.
|
||||
4. Link the game server to the correct launcher instance. Open that instance's
|
||||
Guilds & Claims page in the launcher. The selected game server controls both
|
||||
the Vantage world and the SCOPENET claims shown on it.
|
||||
## Turn it on
|
||||
|
||||
The native launcher streams map assets through its HTTP client so the map host
|
||||
does not need browser CORS headers. Browser-only development previews require
|
||||
CORS on the map host. The URL is included in the public game-server summary;
|
||||
use a map you intend players to see. Keep Vantage `server` bearer credentials
|
||||
out of this URL. For private worlds, put Vantage behind a session-gated proxy
|
||||
that serves the manifest and tile files with the player's existing session.
|
||||
Vantage's [server guide](https://github.com/thoughts-on-things/vantage-mc/blob/main/docs/server.md)
|
||||
describes the sidecar and its authorization boundary.
|
||||
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.
|
||||
|
||||
Live terrain comes from Vantage's read-only view of saved world files. Claims
|
||||
and guild names come from SCOPENET's claim database. If the map cannot be
|
||||
loaded, the launcher falls back to the chunk grid. The map does not run inside
|
||||
Minecraft; `/guild map` is still the Paper plugin's nearby chat radar.
|
||||
## Panel requirements
|
||||
|
||||
Vantage's web package is MIT licensed. See its
|
||||
[license](https://github.com/thoughts-on-things/vantage-mc/blob/main/LICENSE).
|
||||
Rendering needs two things on the machine running the panel:
|
||||
|
||||
| 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.
|
||||
Reference in new issue
Block a user