Border Quest

Border Quest

Серверный мод для Fabric для Minecraft 1.21, который превращает границу мира в кооперативное испытание с прогрессией. Игроки собирают ресурсы, жертвуют их алтарям и открывают всё больший мир — этап за этапом.

Возможности

Требования

Только для сервера. Клиентам не нужно устанавливать этот мод.

Установка

1. Поместите border-quest-mod-x.x.x.jar в папку mods/ вашего сервера вместе с Fabric API.
2. Запустите сервер один раз — config/borderquest.json создастся автоматически.
3. Отредактируйте конфиг под свой сервер, затем выполните /bq reload.

Команды

Все команды начинаются с /bq (доступен псевдоним через любой зарегистрированный алиас).

Команды игрока

Команды оператора (уровень прав 2)

Чтобы пожертвовать, кликните правой кнопкой по любому блоку-алтарю, держа предметы в руке. /bq submit работает откуда угодно и сканирует весь ваш инвентарь.

Конфигурация

Расположение файла: config/borderquest.json

{
  // Общее ---------------------------------------------------------------------

  // Длительность праздничных фейерверков при завершении этапа (тики, 20 = 1с)
  "celebrationDurationTicks": 200,

  // Урон в секунду, пока игрок находится за границей
  "borderDamagePerBlock": 0.2,

  // Расстояние (в блоках), на котором показывается предупреждение о границе
  "borderWarningBlocks": 5,

  // Масштаб координат Nether (граница Nether = радиус Обычного мира / netherScale)
  "netherScale": 8.0,

  // Частицы алтарей -----------------------------------------------------------

  "altarParticlesEnabled": true,
  // Как часто появляются частицы, в тиках (20 = раз в секунду)
  "altarParticlePeriodTicks": 20,

  // Объявления о пожертвованиях ------------------------------------------------

  // Рассылать сообщение всем игрокам, когда одно пожертвование достигает этого количества
  "donationAnnouncementsEnabled": true,
  "donationAnnounceMinItems": 16,

  // Блокировка измерений -------------------------------------------------------

  // Запретить игрокам входить в измерение до достижения нужного этапа
  "worldLocks": [
    { "worldId": "minecraft:the_nether", "requiredStage": 5 },
    { "worldId": "minecraft:the_end",    "requiredStage": 7 }
  ],

  // Discord webhook -----------------------------------------------------------

  "discordEnabled": false,
  "discordWebhookUrl": "https://discord.com/api/webhooks/YOUR_ID/YOUR_TOKEN",
  "discordUsername": "Border Quest",
  "discordAvatarUrl": "",   // Оставьте пустым, чтобы использовать аватар webhook по умолчанию

  // Этапы ---------------------------------------------------------------------

  "stages": [
    {
      "borderRadius": 10,
      "title": "Расчистите территорию",
      // Требуемые предметы с фиксированным количеством
      "requirements": [
        { "itemId": "minecraft:cobblestone", "count": 64 }
      ],
      // Категории, определяемые по биому (мод сам подбирает нужный тип брёвен)
      "categoryRequirements": [
        { "category": "logs", "count": 64 }
      ],
      // Награды, выдаваемые ВСЕМ игрокам онлайн при завершении
      "rewards": []
    },
    {
      "borderRadius": 25,
      "title": "Первые шаги к цивилизации",
      "requirements": [
        { "itemId": "minecraft:iron_ingot", "count": 32 },
        { "itemId": "minecraft:bread",      "count": 32 }
      ],
      "categoryRequirements": [],
      "rewards": [
        // Выдать 3 хлеба каждому игроку онлайн
        { "type": "item",   "itemId": "minecraft:bread", "count": 3 },
        // Наложить Haste I на 30 с
        { "type": "effect", "effectId": "minecraft:haste", "duration": 600, "amplifier": 0 },
        // Выдать 50 очков опыта
        { "type": "xp", "amount": 50 }
      ]
    }
    // ... добавляйте сколько угодно этапов
    // ПОСЛЕДНИЙ этап означает полную свободу (используйте borderRadius: 29999984)
  ]
}

### Структура этапа

| Поле | Тип | Описание |
|---|---|---|
| `borderRadius` | double | Половина длины стороны квадратной границы (диаметр = радиус × 2) |
| `title` | string | Отображается в чате и в боковой панели списка игроков |
| `requirements` | list | Конкретные требуемые предметы — `itemId` + `count` |
| `categoryRequirements` | list | Требования, зависящие от биома — `category` + `count` |
| `rewards` | list | Награды, выдаваемые всем игрокам онлайн при завершении этапа |

**Встроенные категории**: `logs`, `planks`, `wool`, `sand`, `stone` — определяются как самые распространённые варианты, встречающиеся в биоме спавна.

### Типы наград

| `type` | Обязательные поля | Пример |
|---|---|---|
| `"item"` | `itemId`, `count` | `{ "type": "item", "itemId": "minecraft:diamond", "count": 2 }` |
| `"effect"` | `effectId`, `duration` (тики), `amplifier` (0 = уровень I) | `{ "type": "effect", "effectId": "minecraft:speed", "duration": 400, "amplifier": 1 }` |
| `"xp"` | `amount` | `{ "type": "xp", "amount": 100 }` |

---

## Настройка алтарей

Алтарями могут быть **любые блоки** — маяк, сундук, кастомный баннер — что угодно под тематику вашего сервера.

1. Поставьте блок в мире.
2. Посмотрите на него и выполните `/bq setaltar` (при желании `/bq setaltar Altar du Spawn`).
3. Теперь игроки могут нажать правой кнопкой мыши по блоку, чтобы пожертвовать предметы.

Чтобы удалить алтарь: посмотрите на него и выполните `/bq removealtar`.

> Позиции алтарей сохраняются в `world/data/borderquest_state.json` и переживают перезапуски.

---

## Интеграции с картами

### BlueMap

Требуется установленный на сервере **BlueMap**.
Мод автоматически отрисовывает:
- **Зелёный прямоугольник**, показывающий текущие границы на карте Верхнего мира.
- **Метку POI** для каждого алтаря (с его отображаемым именем, если оно задано).

Метки перестраиваются автоматически при перезагрузке BlueMap.

### Dynmap

Требуется установленный на сервере **Dynmap for Fabric**.
Те же метки, что и в BlueMap — отрисовываются через рефлексию, дополнительных зависимостей не нужно.

### JourneyMap и Xaero's Minimap / World Map

> **Только одиночная игра и LAN.** Эти моды работают на стороне клиента и недоступны в classpath выделенного сервера.

При игре в **одиночке или по LAN**, если установлены JourneyMap, Xaero's Minimap или Xaero's World Map:
- При регистрации алтаря для него создаётся **путевая точка**.
- При удалении алтаря путевая точка удаляется.
- Формы границ не поддерживаются (ограничение клиентских карт).

Интеграция использует рефлексию — дополнительная настройка не требуется.

---

## Discord-вебхук

1. Создайте вебхук на своём Discord-сервере: **Настройки канала → Интеграции → Вебхуки**.
2. Скопируйте URL и вставьте его в `borderquest.json`:
   ```json
   "discordEnabled": true,
   "discordWebhookUrl": "https://discord.com/api/webhooks/123456789/abc...",
   "discordUsername": "Border Quest",
   "discordAvatarUrl": ""

3. Выполните /bq reload.

Сообщение отправляется автоматически каждый раз при завершении этапа.

Блокировка измерений

По умолчанию:

• The Nether заблокирован до этапа 5.
• The End заблокирован до этапа 7.

Попытка войти в заблокированное измерение отменяет телепортацию и показывает красное сообщение. Настройте или уберите блокировки в borderquest.json в разделе worldLocks.

Сохранённое состояние

Состояние игры (текущий этап, сданные предметы, список алтарей, статистика жертвователей) сохраняется в:

<world>/data/borderquest_state.json

Делайте резервную копию этого файла, если хотите сохранить прогресс между сбросами карты.

Сборка из исходников

git clone <repo>
cd border-quest-mod
./gradlew build
# Output: build/libs/border-quest-mod-x.x.x.jar

Требования: Java 21, доступ в интернет (для загрузки Fabric Loom и BlueMap API).

Зависимости кратко:

Лицензия

MIT — см. LICENSE.