RegionLib

This repository contains two coordinated projects:

• region-painter/: a Node.js + React web application for painting region definitions on a grid, attaching metadata, and exporting/importing JSON.
• regionlib-plugin/: a Maven-based Paper/Folia-compatible plugin for Paper 1.21.11 that loads those JSON files and resolves block coordinates to regions at runtime.

Repository Layout

RegionLib/
├── examples/
│ └── demo-overworld.json
├── region-painter/
│ ├── src/
│ └── package.json
└── regionlib-plugin/
├── src/main/java/
├── src/main/resources/
├── mvnw
└── pom.xml

RegionPainter

The painter is the primary authoring tool. It currently supports:

• chunk-based region painting with paint, fill, erase, pick, and pan tools
• JSON save/load for full projects
• per-region ids, display names, colors, tags, flat attributes, and optional yMin / yMax
• guide image loading with opacity, scale, and offset controls
• local autosave in the browser
• direct export into the format consumed by the plugin

Run it locally:

cd region-painter
npm install
npm run dev

Create a production build:

cd region-painter
npm run build

RegionLib Plugin

The plugin loads JSON files from plugins/RegionLib/regions/*.json and exposes a central lookup API for other plugins.

Current API surface:

Optional<Region> getRegionAt(Locationlocation);
Optional<Region> getRegionAt(StringworldName, intblockX, intblockY, intblockZ);
StringgetRegionName(Locationlocation);
Optional<Region> getRegionById(Stringid);
Collection<? extendsRegion> getRegions();
Collection<? extendsRegion> getRegions(StringworldName);
booleanreload();

Build it with the Maven wrapper:

cd regionlib-plugin
./mvnw package

The built jar is written to regionlib-plugin/target/.

Commands

• /regionlib whereami [player]
• /regionlib info <region-id>
• /regionlib reload
• /regionlib lookup <world> <block-x> <block-z> [y]

Shared JSON Format

The web app and plugin both use the same project file structure:

{
"version": 2,
"projectName": "Demo Overworld",
"worldName": "world",
"grid": {
"width": 16,
"height": 16,
"coordinateMode": "chunk-centered"
},
"background": {
"imageDataUrl": null,
"opacity": 0.58,
"scale": 1,
"offsetX": 0,
"offsetY": 0
},
"regions": [
{
"id": "capital_core",
"name": "Capital Core",
"color": "#ef6351",
"tags": ["spawn", "urban"],
"attributes": {
"climate": "temperate"
},
"yMin": null,
"yMax": null,
"rows": [
{ "y": -2, "spans": [[-2, 0]] }
]
}
]
}

rows are compressed chunk runs, where each entry stores a y row and inclusive x spans for that row. The coordinates are chunk coordinates, not raw world block coordinates. The center axes represent world 0,0, so an even-sized grid spans equally around that origin. The plugin converts world positions into chunk coordinates using:

chunkX = floor(blockX / 16)
chunkZ = floor(blockZ / 16)

Older project files that still use cells arrays remain import-compatible in both the painter and the plugin.

yMin / yMax are optional and only apply after the x/z chunk resolves to a region.

Example Data

examples/demo-overworld.json matches the included plugin bootstrap example and can be loaded into the painter immediately.