Description

ArdaRegions

Region discovery and tracking for Minecraft servers. Define regions on your map, let players discover them by exploring.

What it does

Regions

Define polygon regions in-game using the region map panel. Each region has an ID, display name, optional description, Y bounds, world assignment, and optional parent/child hierarchy. Regions can be marked discoverable or not (defaults to discoverable). Parent regions can contain child regions; the mod resolves nested overlaps using the hierarchy chain.

Region data is stored in H2 databases under the world save (world/arda-regions/db/). Admins can maintain multiple region databases and switch between them in the map editor.

Discovery

When a player enters a region they have not discovered yet, and that region is discoverable, it is recorded and they see a DISCOVERED popup with the region name and description.

Discovery progress is stored per player in a separate H2 database (configurable). The HUD uses a gameplay/discovery region snapshot from the server, which can differ from the database currently open in the map editor—so admins can edit one dataset while players continue to use another for location and discovery.

Players also see their current location (deepest region in the hierarchy chain) in the top-left HUD while playing.

Map panel

Open the interactive region map with /ardaregions panel (admin). From the panel you can:

Pan and zoom the map
Draw and edit region polygons
Create, update, and delete regions
Manage parent regions and discoverable flags
Switch basemap between:
- BlueMap — pre-processed tiles served from the server
- Image layers — custom PNG overlays from config
- None — polygons only, no basemap
Switch the active editor database and world for editing

3D region view (admin)

Admins can visualize region outlines in the world:

/ardaregions viewcurrent — current region
/ardaregions view <region_id> — a specific region
/ardaregions viewall — all regions
/ardaregions viewnone — hide outlines

These commands run on the client while connected to a server (they check ardaregions.admin via the server).

Requirements

Minecraft 1.20.1
Fabric Loader (≥ 0.16.0)
Fabric API
Fabric Permissions API (bundled with the mod; used for permission checks with OP level 2 fallback)

Optional

LuckPerms (or any mod implementing the Fabric Permissions API) — recommended for granting ardaregions.admin without OP
BlueMap — render your world, then process tiles for the in-game map (see below)

Setup

1. Install on server

Add the ArdaRegions jar to your server's mods/ directory.
Start the server. On first run it creates:
- world/arda-regions/db/ — H2 databases (regions, editor context, discoveries)
- world/serverconfig/arda-regions/gameplay.json — gameplay settings (discovery database name)

2. Install on client

Add ArdaRegions to your client's mods/ directory.
Start the client and join a server running the mod.

The region map, discovery HUD, and client-side admin commands require both server and client.

3. Map tiles and image overlays (optional)

BlueMap basemap

Install and run BlueMap so it renders your world.
On the server, run /ardaregions processbluemaptiles (admin). This converts BlueMap's tile output into ArdaRegions tiles under ardaregions/ in the server working directory. Clients stream these tiles when BlueMap is selected in the map panel.
From the client you can also run /ardaregions processbluemaptiles to request processing via the server.

Image overlay layers

Add one or more layers in config/arda-regions/map-layers.json on the client (the server can sync layers to clients when configured on the server). Legacy map-overlay.json is still read and migrated automatically.

Example:

{ "layers": [ { "id": "overview", "name": "Overview", "imagePath": "overview.png", "worldSize": 53887, "worldX": -19584.0, "worldZ": -10240.0, "autoCalibrateBounds": false } ] }

imagePath — PNG file relative to config/arda-regions/
worldSize — width of the image in Minecraft blocks (X axis)
worldX / worldZ — top-left corner of the image in world coordinates
autoCalibrateBounds — if true, bounds can be derived from processed BlueMap tiles when available

Switch basemaps using the map layer dropdown in /ardaregions panel.

4. Permissions

ArdaRegions checks permissions through the Fabric Permissions API. Without a permissions mod, OP level 2 is used as the fallback for admin actions.

With LuckPerms (or similar), grant:

Node Purpose ardaregions.admin Region map panel, 3D view commands, tile processing, resetting other players' progress, in-map region editing

Players can always run /ardaregions resetprogress on themselves without admin.

5. Advanced: separate discovery database

In world/serverconfig/arda-regions/gameplay.json:

{ "discoveryDatabaseBase": "ardaregions" }

discoveryDatabaseBase is the H2 file base name (under world/arda-regions/db/) where player discoveries are stored. This is independent of which region database the map editor has open. Change only with care; existing discoveries remain in the old file until migrated manually.

Commands

Run /ardaregions with no arguments for a command list. Admin-only entries are shown only if you have permission.

Command Where Permission Description /ardaregions panel Client Admin Open the interactive region map /ardaregions processbluemaptiles Client or server Admin Process BlueMap tiles into ArdaRegions tiles /ardaregions resetprogress Client or server — Reset your own discoveries /ardaregions resetprogress <player> Client or server Admin Reset another player's discoveries /ardaregions view <region_id> Client Admin Show a 3D outline for one region /ardaregions viewall Client Admin Show all region outlines /ardaregions viewnone Client Admin Hide region outlines /ardaregions viewcurrent Client Admin Show the current region outline

On the dedicated server, panel and view* respond with a reminder to use them from the client; resetprogress and processbluemaptiles work on the server console or in-game.

API

ArdaRegions exposes an API for other mods: region queries, player exploration, map editor context, and Fabric events (discovery, CRUD, client discovery popup).

Getting the API

Entrypoint (recommended) — in your fabric.mod.json:

"entrypoints": { "arda-regions:api": [ "your.mod.YourApiEntrypoint" ] } import mc.ardacraft.ardaregions.api.ArdaRegionsAPI; import mc.ardacraft.ardaregions.api.ArdaRegionsApiEntrypoint; public class YourApiEntrypoint implements ArdaRegionsApiEntrypoint { @Override public void onApiReady(ArdaRegionsAPI api) { // Store api; use getRegionAPI(), getExplorationAPI(), getMapEditorContextAPI(), events } }

Or later: ArdaRegionsAPI.getInstance() — throws if the mod is not loaded. Prefer the entrypoint so you receive the API as soon as it is ready.

Region API (IRegionAPI)

From api.getRegionAPI().

Method Description getRegion(String regionId) Region by ID, or empty getAllRegions() All regions getRegionsByWorld(String worldId) Regions in a world (registry key, e.g. minecraft:overworld) getChildRegions(String parentId) Direct children of a region getParentRegion(String regionId) Parent of a region, or empty regionExists(String regionId) Whether the region exists isPointInRegion(String regionId, double x, double z, int y, String world) Whether the point is inside the region

Exploration API (IPlayerExplorationAPI)

From api.getExplorationAPI().

Method Description getDiscoveredRegions(UUID playerId) Set of discovered region IDs hasDiscovered(UUID playerId, String regionId) Whether the player discovered that region getDiscoveryCount(UUID playerId) Number of regions discovered getDiscoveredRegionsAsObjects(UUID playerId) Discovered regions as ApiRegion objects

Data types

All in mc.ardacraft.ardaregions.api.data. Immutable.

ApiRegion — id, name, parentId, childrenIds, polygons, metadata.
getDescription() returns metadata.get("description") as a string when present.
discoverable is stored in metadata as a boolean (defaults to discoverable when absent).

ApiPolygon — vertices (list of ApiPoint2D), minY, maxY, world.
isWithinYBounds(int y) for the Y check.

ApiPoint2D — x, z (double). Getters: getX(), getZ().

Events

Fabric Event<T>. Register with event.register(callback).

Event Callback When getRegionDiscoveredEvent() (UUID playerId, String regionId) Player discovers a region (server) getRegionCreatedEvent() (ApiRegion region) Admin creates a region getRegionUpdatedEvent() (ApiRegion oldRegion, ApiRegion newRegion) Admin updates a region getRegionDeletedEvent() (String regionId) Admin deletes a region getClientDiscoveryPopupEvent() (String regionId, String regionName, String description, float alpha) Client shows the discovery popup (client only)

Example:

api.getRegionDiscoveredEvent().register((playerId, regionId) -> { // ... });