ArdaRegions

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

What it does

Regions

Define polygons in game. You can name them, add descriptions, set them to be discoverable, and set parent/child links.

Discovery

When a player enters a region for the first time, it's marked as discovered for the player, and they get a "DISCOVERED" popup. Player's can also see their current location at the top left of the screen.

Map Types

Use your servers in-built BlueMap, or upload a Region Overlay to draw regions on.

Requirements

• Minecraft 1.20.1
• Fabric Loader
• Fabric API
• Fabric Permissions
• BlueMap

Optional

• LuckPerms

Setup

1. Install on Server

1. Add ArdaRegions jar to your servers /mods/ directory
2. Start the server - the database and config will be created

2. Install on Client

1. Add ArdaRegions to your clients /mods/ directory
2. Start your client

3. Setting up the Map Tiles

1. Install and run BlueMap, so it renders your world
2. On the server, run /ardaregions processtiles. This will process BlueMap's tiles into ArdaRegions tiles.
3. Optionally add an aditional Map Overlay to config/arda-regions/map-overlay.json on your client. Set the worldSize to the width of your image in Minecraft Blocks, and the worldX and worldY to the top left corner coordinates of your Minecraft World.
4. Switch between these maps by pressing the Map Overlay button in /ardaregions panel

4. Setting up Permissions

ArdaRegions can use either the in-built Minecraft op permission system, or a permission system using the Fabric Permissions API, such as LuckPerms.

If you are using LuckPerms, or another mod that implements the Fabric Permissions API, give the user the ardaregions.admin permission node to allow them to use Admin commands.

Commands

• /ardaregions panel – open the region map (admin).
• /ardaregions processtiles – process BlueMap tiles (admin).
• /ardaregions resetprogress – reset your own discoveries.
• /ardaregions resetprogress <player> – reset another player’s discoveries (admin).
• /ardaregions view <region_id> - view a 3d representation of the specified region (admin).
• /ardaregions viewall - view a 3d representation of all regions (admin).
• /ardaregions viewnone - disable 3d representation view (admin).
• /ardaregions viewcurrent - view current regions 3d representation (admin).

Credits

A massive thankyou to everyone who assisted in the development of this mod:

• Xone for beta-testing, bug-finding, and for making textures and graphics.
• Fornad for beta-testing, bug-finding, and for being the first user.
• The entire ArdaCraft team for supporting the development of this project.
• Blue (BlueMap) for helping me utilise his mod's tileset.

API

ArdaRegions includes a client-side API that allows other mods to utilise Regions events such as discovery, current region, region lists.

Getting the API

Entrypoint (recommended):
In fabric.mod.json:

"entrypoints": { "arda-regions:api": [ "your.mod.YourApiEntrypoint" ] }

Your class implements ArdaRegionsApiEntrypoint:

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 and use getRegionAPI() / getExplorationAPI() / events } }

Or later:
ArdaRegionsAPI.getInstance() returns the API. Throws if the mod is not loaded. Prefer the entrypoint so you get the API as soon as it’s 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 (world ID from 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) True if the region exists isPointInRegion(String regionId, double x, double z, int y, String world) True if (x, z, y) in that world 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) True if player has discovered that region getDiscoveryCount(UUID playerId) Number of regions discovered getDiscoveredRegionsAsObjects(UUID playerId) Discovered regions as ApiRegion objects

Data types

ApiRegion
id, name, parentId, childrenIds, polygons, metadata.
getDescription() returns metadata.get("description") as string if present.

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

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

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

Events

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

Event Callback When getRegionDiscoveredEvent() (UUID playerId, String regionId) Player discovers a region 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-side only)

Example:

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