Regions

Regions is the low-level building block Eternal Empires uses to mark areas of the world as special. It doesn't implement protection, plots, or spawn areas itself — instead it gives other plugins (plots, for example) a shared way to define an area, attach arbitrary metadata to it, and ask "is this location inside a region, and which one takes priority here?"

What it does

A region is made up of one or more RegionParts (chunk-aligned pieces of a world) and carries a numeric priority plus arbitrary string metadata. When two regions overlap the same location, the one with the higher priority wins — that's how, for example, a plot region can carve out an exception inside a larger claimed area. Regions themselves don't do anything visible in-game; other plugins query RegionProvider to find out which region (if any) covers a given world/x/y/z and read its metadata to decide what to do.

The plugin does provide a couple of admin-facing commands for inspecting regions directly:

Commands

Command	Description	Permission
/region	Show help/info for the region system	regions.command.region
/region info	List all regions at your current location, ordered by priority	regions.command.region.info
/region visualize	Toggle a particle outline for the region at your location	regions.command.region.visualize
/region visualize <regionId>	Toggle a particle outline for a specific region by ID	regions.command.region.visualize

Commands can be disabled entirely via config (see below) if a server only wants other plugins to use Regions as a library, without exposing any player-facing commands.

The API

RegionProvider is the entry point — it resolves regions by ID or by looking up what covers a given location. RegionPartProvider deals with the individual chunk-aligned pieces regions are built from, keyed by ChunkId. A Region exposes its parts, priority, a contains(world, x, y, z) check, and a simple string key/value metadata store (getMetadata, setMetadata, hasMetadata, removeMetadata) that other plugins use to attach their own data to a region without Regions needing to know anything about what that data means.

Modules

• api — public interfaces (Region, RegionPart, RegionProvider, RegionPartProvider, ChunkId). No implementation, published for other plugins to depend on.
• common — the MongoDB-backed implementation via Morphia.
• paper — the Paper plugin: commands, region visualization, and startup wiring.

Requirements

Java 21, Paper 1.20 or newer, and a MongoDB instance. Regions depends on multilanguage for command messages.

Building

./gradlew build

To get a plugin jar, build the paper module's shadow jar:

./gradlew paper:shadowJar

The resulting jar is written to paper/build/libs/.

Configuration

On first run, two files are generated under plugins/regions/:

config.yml:

commands: true   # set to false to disable the /region commands entirely and use Regions purely as a library

database.yml configures the MongoDB connection used to store regions:

host: localhost
port: 27017
database: regions
username: admin
password: 'my-password'   # leave blank if your MongoDB has no auth configured

Using the API from another plugin

If you're building a plugin that needs to know whether a location falls inside a defined area — protection, custom spawn zones, PvP toggles, anything territory-based — depend on regions-api instead of building your own spatial lookup:

repositories {
    maven {
        url 'https://packages.eternalempires.net'
    }
}

dependencies {
    compileOnly 'net.eternalempires:regions-api:VERSION'
}

Replace VERSION with the release you want to target — see the Releases page for available versions.

License

See LICENSE.

Contributing

See CONTRIBUTING.md.