Faction Map

Description

Faction Map is a Minecraft plugin that draws a lightweight 3D map of a server's world in the browser, with Medieval Factions politics on top: each faction's territory tinted in its own colour, claim borders, faction names, and alliance, war and vassal links between factions.

It is a faction-native map, not a general-purpose one. The terrain is the top surface only: no caves, interiors, entities or lighting. That keeps it cheap. The plugin reads only chunks that players have already loaded, within a fixed main-thread budget per tick, and it never writes to the world or to Medieval Factions. Without Medieval Factions it still draws the terrain.

Live: Saltmarsh claims more land (13 to 29 chunks) and the open viewer picks it up without a reload.

The design is RFC 0002 in the Dans-Plugins RFC repository. This is the first milestone (M1): the skeleton, the capture and tile pipeline, the embedded web server and the faction layers.

Installation

First Time Installation

1. Download the plugin from the GitHub releases page. Take the jar from the latest stable release. The dev prerelease there is an automated build of main that has not been through any release check: use it only to try unreleased changes, and back up the server first. You can also build the jar with ./gradlew build (see Testing).
2. Place the jar in the plugins folder of your server.
3. Optional: install Medieval Factions 7.0.0 or later for the faction layers.
4. Restart your server.
5. Open http://127.0.0.1:8199/ on the server machine. The map fills in as players explore.

The viewer listens on 127.0.0.1 only. To show the map to players, put it behind your reverse proxy, or change web.host (see the Configuration Guide).

Supported Minecraft versions

The versions in minecraft-versions.json: 1.21.11, 26.2 and 26.3, on Spigot or Paper. CI checks that every Bukkit class, field and method the jar uses exists on each of them, and that its bytecode (Java 21) loads on each. Folia is not supported.

Usage

Documentation

• User Guide – what the map shows and how it stays up to date
• Commands Reference – /fmap
• Configuration Guide – every option in config.yml

What it guarantees

• Read-only. No block writes, no world saves, no command dispatch, no chunk loading (only chunks for which isChunkLoaded is true are read), and Medieval Factions through its getters only: never its database, its REST API, or a save or delete. Everything the plugin writes is under plugins/FactionMap/ and is derived: deleting that folder is always safe and rebuilds the same tiles. CI checks this on the jar's bytecode (scripts/check_read_only.py).

• A main-thread budget. Capture stops each tick once capture.mainThreadBudgetMicros (500 µs by default) would be exceeded. Meshing, tile writing and the web server run on their own threads.

• Works on phones. The panel becomes a bottom sheet that can be hidden.

• No player data. The map reads no player names, UUIDs or positions. Faction names are shown by default and can be replaced with letters; faction homes are off by default.

Support

You can find the support Discord server here.

Experiencing a bug?

Please fill out a bug report here.

• Known Bugs

Contributing

• CONTRIBUTING.md

Testing

Unit Tests

Linux:

./gradlew clean test

Windows:

.\gradlew.bat clean test

If you see BUILD SUCCESSFUL, the tests have passed. The build downloads the Medieval Factions 7.0.0 release jar that the integration compiles against and checks its SHA-256.

Read-only and API checks

python3 scripts/check_read_only.py --self-test
python3 scripts/check_read_only.py build/libs
curl -fsSL -o /tmp/check_api_compat.py https://raw.githubusercontent.com/Dans-Plugins/release-gates/v23/gates/check_api_compat.py
python3 /tmp/check_api_compat.py --versions minecraft-versions.json target build/libs

check_read_only.py checks the jar's bytecode against the read-only rules (see What it guarantees); check_api_compat.py checks every Bukkit class, field and method the jar uses against each version in minecraft-versions.json. CI runs both after ./gradlew clean build.

Smoke and performance gate

tools/smoke/ boots the plugin on a throwaway Spigot 26.3 server with Medieval Factions and four mineflayer bots, which create factions, claims and relations; the areas around their faction sites are force-loaded. gate.py then measures the performance budget: p99 main-thread time per tick ≤ 1 ms with no tick above 5 ms after warm-up, and a block change reaching the served tile in ≤ 3 s. The Smoke workflow runs it in GitHub Actions on every pull request. Usage reporting and bStats are switched off on that server before its first boot.

This is the beginning of the README. Read the rest at the original. Read the full README ↗