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(Location location);
Optional<Region> getRegionAt(String worldName, int blockX, int blockY, int blockZ);
String getRegionName(Location location);
Optional<Region> getRegionById(String id);
Collection<? extends Region> getRegions();
Collection<? extends Region> getRegions(String worldName);
boolean reload();

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.