squaremap-markers

A lightweight, cross-platform add-on for Squaremap that allows server administrators to define custom map regions, borders, and markers using simple JSON configuration files.

Instead of relying on in-game banners or manual commands, squaremap-markers lets you permanently define towns, regions, pathways, markers, and custom icons directly from your server's file system.

⚠️ NOTE: This mod is currently in BETA, and has only been tested on local basic test servers for each platform. It should, in theory, work with squaremap >= 1.1.0 and minecraft >= 26.1. Please report any errors or issues here.

✨ Features

• Multi-Platform: Runs on Paper (and Folia), Fabric, NeoForge, and Sponge.
• Multiple Files: Split your markers across multiple .json files.
• Rich Geometries: Native support for Rectangles, Polygons (with holes), Polylines, Ellipses, and Circles.
• Custom Icons: Drop image files into the icons/ folder to instantly use them on your map.
• Interactive: Support for hover tooltips and clickable HTML hyperlinks.
• Hot-Reloading: Reload all files and icons from in-game with a single command.

📥 Installation

1. Ensure you have the latest version of Squaremap installed.
2. Download the squaremap-markers jar file for your specific platform.
3. Place the jar file into your server's plugins/ or mods/ directory.
4. Restart the server.
5. The configuration files are generated in:
   • Paper: plugins/SquaremapMarkers/
   • Fabric, NeoForge, Sponge: config/squaremap-markers/

💻 Commands & Permissions

Command	Permission	Description
/squaremapmarkers reload (alias /smm reload)	squaremapmarkers.command.reload	Reloads all JSON files and custom icons.

⚙️ Configuration Guide

You can create as many .json files as you want inside the main squaremap-markers folder. The plugin will scan the folder and load them all.

1. Basic Structure

Every file must start with a layers object. A single file can contain multiple layers, and a single layer can contain multiple markers. Layers sharing an id across files are merged; a marker id repeated within the same layer replaces the earlier one and is logged as a warning.

{
  "layers": {
    "layer_id_here": {
      "name": "Display Name on Map",
      "world": "minecraft:overworld",
      "default_hidden": false,
      "show_controls": true,
      "z_index": 5,
      "layer_priority": 0,
      "markers": {
        // Markers go here
      }
    }
  }
}

Layer ids, marker ids and icon names may only contain a-z A-Z 0-9 . _ -.

The world of a layer/marker is a dimension identifier such as minecraft:overworld, minecraft:the_nether or mypack:mydim. An unqualified name like overworld is assumed to be in the minecraft namespace. Identifiers are lowercase only.

2. Layer Options

• name: Display name on the map. Defaults to the layer id.
• world: Default dimension for every marker in the layer. Markers may override it.
• options: Default styling for every marker in the layer, merged field by field with each marker's own options. See below.
• default_hidden: Whether the layer starts hidden. Defaults to false.
• show_controls: Whether the layer appears in the map's layer control. Defaults to true.
• z_index: Draw order on the map. Defaults to 0.
• layer_priority: Ordering within the layer control. Defaults to 0.

3. Marker Options

All marker types accept an optional options object to customize their appearance:

• stroke: Whether to draw the outline at all. Defaults to true.
• stroke_color: Hex color for the outline (e.g., "#FF0000").
• stroke_weight: Thickness of the outline (integer).
• stroke_opacity: Outline transparency from 0.0 to 1.0.
• fill: Whether to fill the shape at all. Defaults to true.
• fill_color: Hex color for the inside of the shape.
• fill_opacity: Transparency from 0.0 (invisible) to 1.0 (solid).
• fill_rule: "nonzero" or "evenodd" — how self-intersections and holes are filled.
• hover_tooltip: Text shown when hovering over the marker.
• click_tooltip: HTML shown when clicking the marker (supports hyperlinks <a href="...">).

Squaremap's defaults if you omit them: stroke on, blue, weight 3, full opacity; fill on with fill_opacity 0.2 and fill_rule evenodd (the fill colour follows the stroke colour unless you set it).

4. Marker Types

⬛ Rectangle

Exactly two points, the opposite corners. Order does not matter.

"pvp_arena": {
  "type": "rectangle",
  "points": [
    {"x": -100, "z": -100},
    {"x": 100, "z": 100}
  ]
}

⬟ Polygon

Polygons close themselves, so do not repeat the first point at the end — if you do, it is dropped. Add an optional holes array (a list of point lists) to cut regions out of the shape; holes close themselves the same way.

"town_border": {
  "type": "polygon",
  "points": [
    {"x": 300, "z": 300},
    {"x": 350, "z": 400},
    {"x": 250, "z": 400}
  ]
}

〰️ Polyline

Use polyline if you want an open line, or a closed loop drawn as a line rather than a filled shape.

"main_highway": {
  "type": "polyline",
  "points": [
    {"x": 0, "z": 0},
    {"x": 1000, "z": 0}
  ]
}

⭕ Circle & Ellipse

A circle takes a single radius; an ellipse takes radius_x and radius_z. All must be greater than 0.

"spawn_protection": {
  "type": "circle",
  "center": {"x": 0, "z": 0},
  "radius": 50
}

📍 Icons (Points)

Use exactly one of:

• icon — the name of an image in your icons/ folder (without the extension).
• icon_key — a Squaremap icon key registered by Squaremap itself or another plugin, used verbatim. Squaremap only ships one: squaremap-spawn_icon.

Use size for a square icon, or size_x and size_z to size each axis separately.

"server_shop": {
  "type": "icon",
  "point": {"x": 50, "z": 50},
  "icon": "treasure",
  "size": 32
}

An icon_key that is not registered renders as a broken image on the map, so it is logged as a warning during reload.

🖼️ Adding Custom Icons

1. Navigate to the icons/ directory inside the configuration folder.
2. Drop an image inside (e.g., treasure.png).
3. Run /squaremapmarkers reload in-game.
4. Set "icon": "treasure" (the filename without its extension) in your JSON file.

Any image format this Java runtime can decode works — on a standard JDK that is PNG, JPEG, GIF, BMP, TIFF and WBMP.

🩺 Troubleshooting

The reload logs the marker count I expect, but the map does not change. The markers are registered; Squaremap has not published them yet. In order:

1. Is the server ticking? Squaremap rebuilds markers.json from a server tick, every map.markers.update-interval-seconds (default 5). A server paused by pause-when-empty-seconds in server.properties (default 60, so any empty server) never does, and neither does one under /tick freeze. The reload still succeeds and the markers are registered — they just cannot reach the map. Check with /tick query; /tick sprint 400 publishes them immediately, and pause-when-empty-seconds=0 stops it recurring.
2. Is something in front of Squaremap caching it? Ask Squaremap's own web server directly, bypassing any proxy: curl -si localhost:8080/tiles/minecraft_overworld/markers.json. It sends an ETag but no Cache-Control on that path, so a reverse proxy or browser may hold on to an old copy. If that response is current and your site is not, the stale copy is in the proxy.
3. Is your web server reading the files instead? With internal-webserver.enabled: true and flush-json-immediately: false (both defaults), web/tiles/<world>/markers.json on disk is only rewritten when Squaremap stops. Set flush-json-immediately: true if anything other than Squaremap serves that directory.

A marker is missing and the log says the world "is not enabled in Squaremap". Squaremap only tracks worlds with map.enabled: true. Check the world value too — it is a dimension id such as minecraft:the_nether, not the level folder name.

🛠️ Building from Source

Run ./gradlew build in the root directory. Compiled jars will be located in the build/libs/ directory of each platform's respective module.

The build targets Minecraft 26.3 and Java 25. Gradle provisions both the Java 25 toolchain and the Java 25 daemon JVM automatically, so no local JDK setup is required beyond being able to run the wrapper.

./gradlew test runs the marker-parsing tests in the core module. The parser is kept free of any SquaremapProvider access so it can be tested without a running server.

Running a test server

Each of these boots a real server with this plugin/mod and a matching Squaremap already installed; the map is then served at http://localhost:8080.

./gradlew :paper:runServer
./gradlew :fabric:runServer
./gradlew :neoforge:runServer
./gradlew :sponge:runServer

The server directory is <module>/run/ (git-ignored). Minecraft requires you to accept the EULA before the first run of each, e.g.:

mkdir -p paper/run && echo "eula=true" > paper/run/eula.txt

📦 Releasing

Publishing uses mod-publish-plugin and targets Modrinth and GitHub releases from one command. Remember to set MODRINTH_TOKEN and GITHUB_TOKEN.

1. Set the version in build.gradle.kts. A version containing -alpha/-beta is published to the matching release channel automatically; anything else is published as stable.
2. Add a ## [<version>] - <date> section at the top of CHANGELOG.md.
3. ./gradlew clean build, and ideally ./gradlew :paper:runServer to smoke-test.
4. ./gradlew publishMods -PpublishDryRun=true to review, then without the flag to publish.