ArdaRegions

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

1. Add the ArdaRegions jar to your server's mods/ directory.
2. 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

1. Add ArdaRegions to your client's mods/ directory.
2. 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

1. Install and run BlueMap so it renders your world.
2. 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.
3. 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) -> {
    // ...
});

Credits

Thank you to everyone who helped develop this mod:

• Xone — beta-testing, bug-finding, textures and graphics
• Fornad — beta-testing, bug-finding, first user
• The entire ArdaCraft team — supporting the project
• Blue (BlueMap) — help integrating BlueMap's tileset