ArdaRegions

ArdaRegions - это мод для Minecraft (Fabric) на версию 1.20.1, который добавляет на сервер полноценную систему регионов с механикой открытия (discovery). Если вы когда-нибудь хотели, чтобы игроки сами находили новые локации на карте и получали за это уведомления - этот мод сделает именно это.

В ванильном Майнкрафте нет встроенного инструмента для разметки территорий и отслеживания их посещения. На серверах с RPG или приключенческими картами админам приходится либо ставить плагины (Bukkit/Spigot), либо обходиться без фич. ArdaRegions решает эту проблему прямо на Fabric - без перехода на другие платформы.

Что делает мод

Регионы

Вы можете создавать полигональные регионы прямо в игре через специальную карту-редактор. У каждого региона есть:

• ID и отображаемое название
• описание (необязательно)
• границы по Y
• привязка к миру
• родительский/дочерний регион (иерархия)
• флаг discoverable (открываемый) - по умолчанию включён

Родительские регионы могут содержать дочерние; мод разрешает пересечения через цепочку иерархии.

Данные регионов хранятся в H2-базах внутри папки сохранения мира (world/arda-regions/db/). Админы могут вести несколько баз и переключаться между ними в редакторе.

Открытие регионов

Когда игрок заходит в регион, который он ещё не открыл (и который помечен как discoverable), ему показывается всплывающее окно DISCOVERED с названием региона и описанием. Прогресс открытия хранится отдельно для каждого игрока в своей H2-базе (настраивается).

В HUD слева вверху игрок видит своё текущее местоположение - самый глубокий регион в цепочке иерархии.

Карта-редактор

Открывается командой /ardaregions panel (только для админов). В панели можно:

• перемещать карту и менять масштаб
• рисовать и редактировать полигоны регионов
• создавать, обновлять и удалять регионы
• управлять родительскими регионами и флагом discoverable
• переключать подложку между:
  • BlueMap - предварительно обработанные тайлы с сервера
  • Image layers - кастомные PNG-слои из конфига
  • None - только полигоны без подложки
• переключать активную базу редактора и мир для редактирования

3D-просмотр регионов (админ)

Админы могут видеть контуры регионов прямо в мире:

• /ardaregions viewcurrent - текущий регион
• /ardaregions view <region_id> - конкретный регион
• /ardaregions viewall - все регионы
• /ardaregions viewnone - скрыть контуры

Эти команды работают на клиенте при подключении к серверу (проверяют право ardaregions.admin через сервер).

Требования

• Minecraft 1.20.1
• Fabric Loader (≥ 0.16.0)
• Fabric API
• Fabric Permissions API (встроен в мод; используется для проверки прав с fallback на OP level 2)

Опционально

• LuckPerms (или любой мод, реализующий Fabric Permissions API) - рекомендуется для выдачи ardaregions.admin без OP
• BlueMap - рендеринг мира и обработка тайлов для внутриигровой карты (см. ниже)

Установка

1. Установка на сервер

1. Поместите jar ArdaRegions в папку mods/ на сервере.
2. Запустите сервер. При первом запуске создаются:
   • world/arda-regions/db/ - H2-базы (регионы, контекст редактора, открытия)
   • world/serverconfig/arda-regions/gameplay.json - настройки геймплея (имя базы открытий)

2. Установка на клиент

1. Добавьте ArdaRegions в папку mods/ клиента.
2. Запустите клиент и подключитесь к серверу с этим модом.

Карта регионов, HUD открытий и админские команды на клиенте требуют установки мода и на сервере, и на клиенте.

3. Тайлы карты и слои изображений (опционально)

Подложка BlueMap

1. Установите и запустите BlueMap так, чтобы он отрендерил ваш мир.
2. На сервере выполните /ardaregions processbluemaptiles (админ). Эта команда конвертирует тайлы BlueMap в тайлы ArdaRegions в папке ardaregions/ в рабочей директории сервера. Клиенты будут стримить эти тайлы, когда в панели выбрана подложка BlueMap.
3. С клиента тоже можно выполнить /ardaregions processbluemaptiles, чтобы запросить обработку через сервер.

Слои изображений (Image overlay)

Добавьте один или несколько слоёв в config/arda-regions/map-layers.json на клиенте (сервер может синхронизировать слои с клиентами, если настроено). Старый map-overlay.json тоже читается и автоматически мигрируется.

Пример:

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

• imagePath - PNG-файл относительно config/arda-regions/
• worldSize - ширина изображения в блоках Майнкрафт (ось X)
• worldX / worldZ - координаты левого верхнего угла изображения в мире
• autoCalibrateBounds - если true, границы могут быть получены из обработанных тайлов BlueMap (если доступны)

Переключать подложки можно через выпадающий список слоёв в /ardaregions panel.

4. Права доступа

ArdaRegions проверяет права через Fabric Permissions API. Без мода на права используется OP level 2 как fallback для админских действий.

С LuckPerms (или аналогом) выдайте:

Нода	Назначение
ardaregions.admin	Панель карты регионов, 3D-просмотр, обработка тайлов, сброс прогресса других игроков, редактирование регионов

Игроки всегда могут выполнить /ardaregions resetprogress на себе без админки.

5. Продвинутое: отдельная база открытий

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

{
  "discoveryDatabaseBase": "ardaregions"
}

discoveryDatabaseBase - это базовое имя H2-файла (в world/arda-regions/db/), где хранятся открытия игроков. Оно независимо от того, какая база регионов открыта в редакторе карты. Меняйте с осторожностью; существующие открытия останутся в старом файле до ручной миграции.

Команды

Выполните /ardaregions без аргументов для списка команд. Админские записи показываются только если у вас есть права.

Команда	Где	Права	Описание
/ardaregions panel	Клиент	Админ	Открыть интерактивную карту регионов
/ardaregions processbluemaptiles	Клиент или сервер	Админ	Обработать тайлы BlueMap в тайлы ArdaRegions
/ardaregions resetprogress	Клиент или сервер	-	Сбросить свои открытия
/ardaregions resetprogress <player>	Клиент или сервер	Админ	Сбросить открытия другого игрока
/ardaregions view <region_id>	Клиент	Админ	Показать 3D-контур одного региона
/ardaregions viewall	Клиент	Админ	Показать контуры всех регионов
/ardaregions viewnone	Клиент	Админ	Скрыть контуры регионов
/ardaregions viewcurrent	Клиент	Админ	Показать контур текущего региона

На выделенном сервере команды panel и view* отвечают напоминанием использовать их с клиента; resetprogress и processbluemaptiles работают из консоли сервера или из игры.

API для разработчиков

ArdaRegions предоставляет API для других модов: запросы регионов, исследование игроков, контекст редактора карты и Fabric-события (открытие, CRUD, всплывающее окно открытия на клиенте).

Получение API

Entrypoint (рекомендуется) - в вашем 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) {
        // Сохраните api; используйте getRegionAPI(), getExplorationAPI(), getMapEditorContextAPI(), events
    }
}

Или позже: ArdaRegionsAPI.getInstance() - выбрасывает исключение, если мод не загружен. Предпочтительнее entrypoint, чтобы получить API сразу после его готовности.

Region API (IRegionAPI)

Из api.getRegionAPI().

Метод	Описание
getRegion(String regionId)	Регион по ID или пустой Optional
getAllRegions()	Все регионы
getRegionsByWorld(String worldId)	Регионы в мире (registry key, например minecraft:overworld)
getChildRegions(String parentId)	Прямые дочерние регионы родителя
getParentRegion(String regionId)	Родитель региона или пустой Optional
regionExists(String regionId)	Существует ли регион
isPointInRegion(String regionId, double x, double z, int y, String world)	Находится ли точка внутри региона

Exploration API (IPlayerExplorationAPI)

Из api.getExplorationAPI().

Метод	Описание
getDiscoveredRegions(UUID playerId)	Множество ID открытых регионов
hasDiscovered(UUID playerId, String regionId)	Открыл ли игрок этот регион
getDiscoveryCount(UUID playerId)	Количество открытых регионов
getDiscoveredRegionsAsObjects(UUID playerId)	Открытые регионы как объекты ApiRegion

Типы данных

Все в пакете mc.ardacraft.ardaregions.api.data. Неизменяемые. ApiRegion - id, name, parentId, childrenIds, polygons, metadata.
getDescription() возвращает metadata.get("description") как строку если есть.
discoverable хранится в metadata как boolean (по умолчанию true если отсутствует). ApiPolygon - vertices (список ApiPoint2D), minY, maxY, world.
Метод isWithinYBounds(int y) для проверки по Y. ApiPoint2D - x, z (double). Геттеры: getX(), getZ().

События (Events)

Fabric Event<T>. Регистрация через event.register(callback).

Событие	Callback	Когда
getRegionDiscoveredEvent()	(UUID playerId, String regionId)	Игрок открывает регион (сервер)
getRegionCreatedEvent()	(ApiRegion region)	Админ создаёт регион
getRegionUpdatedEvent()	(ApiRegion oldRegion, ApiRegion newRegion)	Админ обновляет регион
getRegionDeletedEvent()	(String regionId)	Админ удаляет регион
getClientDiscoveryPopupEvent()	(String regionId, String regionName, String description, float alpha)	Клиент показывает всплывающее окно открытия (только клиент)
Пример:

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