WarpMarkers¶

Shows the server's public EssentialsX warps as clickable markers on the BlueMap web map. Each marker shows the warp name and the /warp command to get there.

What it does¶

Puts one marker per warp on the BlueMap map for that warp's world, in a layer called Warps that map viewers can toggle on and off.
Clicking a marker shows the warp's display name (for example Olea Grove) and the exact command (/warp olea_grove).
Shows only public warps by default. A warp is public when the LuckPerms group default can use it (essentials.warps.<name>). Staff and test warps stay off the map.
Re-reads the warp list every 5 minutes, so a new /setwarp or a new warp permission shows up on its own.

The web map has no idea who is looking at it, so a warp is either on the map for the whole internet or for nobody. That is why it checks the default group instead of each viewer.

How players use it¶

Players open the BlueMap web map, turn on the Warps layer if it is hidden, and click a marker. The popup shows the command to type in game, for example /warp olea_grove.

Staff guide¶

All commands need warpmarkers.admin (ops by default). Console works.

Task	Command
Check the BlueMap link, mapped worlds, and which warps are on the map	`/warpmarkers status`
Rebuild the markers now instead of waiting up to 5 minutes	`/warpmarkers refresh`
Re-read `config.yml` and rebuild the markers	`/warpmarkers reload`

Put a warp on the map. Let players use it, and the map follows on the next refresh:

/lp group default permission set essentials.warps.olea_grove true
/warpmarkers refresh

Take a warp off the map. Remove that permission from default, or add the warp name to visibility.never-show and run /warpmarkers reload.

A wildcard grant (essentials.warps.* on default) counts too, and would put every warp on the map.

Configuration¶

plugins/WarpMarkers/config.yml. /warpmarkers reload applies changes right away; no restart needed.

Key	Default	What it is for
`refresh-interval-seconds`	`300`	How often warps are re-read. Minimum 10
`marker-set.label`	`Warps`	Layer name in BlueMap's toggle list
`marker-set.default-hidden`	`false`	Start with the layer turned off
`visibility.mode`	`public-only`	`public-only` checks LuckPerms. `all` shows every warp, staff and test warps included
`visibility.public-group`	`default`	The group that decides what is public
`visibility.on-lookup-failure`	`hide`	What to do if LuckPerms cannot be read. `hide` is safe. `show` would publish staff warps
`visibility.always-show` / `never-show`	`[]`	Per-warp overrides by name, any case. `never-show` wins
`marker.icon`	blank	Blank uses BlueMap's own POI icon. Otherwise a path under the BlueMap webroot, like `assets/warp.svg`
`marker.y-offset`	`0.0`	Lift markers that sit inside terrain
`marker.label-format` / `detail-format`	see file	Text and popup HTML. Placeholders: `%warp%` (exact name, use for commands), `%warp_pretty%`, `%warp_capitalized%`, `%world%`, `%x%`, `%y%`, `%z%`
`world-map-overrides`	`{}`	Bukkit world name to BlueMap map ids. Only needed if the log says a world could not be matched

Example override:

world-map-overrides:
  safari:
    - world_safari

Data and storage¶

None. Warps are read from EssentialsX (or from plugins/Essentials/warps/<name>.yml when needed). Markers live only in BlueMap's memory and are removed when the plugin stops.

Troubleshooting¶

Symptom	Cause	Fix
No warps on the map	No warp is granted to `default`, or LuckPerms could not be read	`/warpmarkers status`. Look for `luckperms=MISSING` or a "Cannot read group" warning
A warp is missing	Its world has no BlueMap map, or it is not public	Check the log for `No BlueMap world matches` or `has no BlueMap map`. Add a `world-map-overrides` entry if needed
A staff warp is on the map	`default` has the permission, or a wildcard	Remove it, or add the warp to `never-show`
Plugin disables at boot	BlueMap is not installed	Install BlueMap
`status` says BlueMap NOT connected	BlueMap has not finished starting, or was reloaded	Wait for BlueMap, then `/warpmarkers refresh`

Log lines when it is working:

[WarpMarkers]: BlueMap <version> is up; mapping warps.
[WarpMarkers]: 'world' -> BlueMap world 'world#minecraft:overworld' maps=[world]
[WarpMarkers]: Warp markers: 12 of 28 warps shown, 12 markers across 5 mapped world(s) [mode=public-only group=default luckperms=yes]

If BlueMap is missing you will see BlueMap was not found on this server (neither as a mod nor as a plugin). Disabling.

Maintainer notes¶

BlueMap is a NeoForge mod on this network, not a Bukkit plugin. getPlugin("BlueMap") is always null, so the plugin checks for the BlueMap API class instead. This is also why no off-the-shelf BlueMap warp addon works here.
World matching is manual. BlueMapAPI.getWorld(...) returns nothing for Bukkit input on the mod platform. Four ways are tried in order: native lookup, save folder, dimension key (BlueMap ids look like world#minecraft:the_nether), then level name, but only if exactly one BlueMap world has that name (five of main's maps use the level name world). The config override beats all of them. getSaveFolder() is deprecated in BlueMap 5.7, so that step is wrapped in a broad catch.
EssentialsX is read by reflection (getWarps(), then getList() and getWarp(String) through the interface, because the implementation class is not always public). Warps in unloaded worlds fall back to their .yml file. No compile dependency on EssentialsX.
Fail closed. If LuckPerms cannot answer, warps are hidden and the plugin logs once.
A map with no warps gets its marker set removed, so the web map never shows an empty Warps toggle. A world with no map logs one warning, not one per warp.
BlueMap listeners are unregistered on disable so a reload does not stack old listeners.
Ops docs: documentation/plugins/warpmarkers-bluemap-warps.md in the ops repo.

Building¶

./libs/fetch-libs.sh   # first time only: gets the BlueMap jar to compile against
./gradlew build

Java 21. Output: build/libs/WarpMarkers-1.0.0.jar.

It compiles against the exact BlueMap 5.7 NeoForge mod jar that runs on main, because BlueMap does not publish a matching API artifact. The jar is not in git; fetch-libs.sh copies it from the GDHooks folder next door or downloads it. If BlueMap is upgraded on main, bump BLUEMAP_URL in that script and rebuild. Nothing is shaded; BlueMap, LuckPerms and EssentialsX come from the server.

Full command, permission and config tables: Reference.