Плагин pvp kkCabins [1.0]

• Выделение регионов встроенным выделителем или WorldEdit/FAWE
• Создание кабинок и областей дверей командами
• Автоматическое закрытие/открытие дверей (материал определяется автоматически)
• Контроль входа/выхода: дуэлянтов невозможно вытащить из кабинки (жемчуг Эндера, плод хоруса, команды, сторонние плагины, эксплойты)
• PvP только между участниками активной дуэли — атака через границу кабинки запрещена (включая стрелы и снаряды)
• Обратный отсчёт перед боем и стадия лута с таймером
• Телепорт победителя на варп кабинки; проигравший возрождается на worldspawn
• Тестовые бойцы DUMMY (Vindicator или NPC-игрок Citizens) — плагин воспринимает их как игроков
• GUI управления dummy, авто-респавн, дуэли dummy против dummy
• Настраиваемые уровни обхода блокировок (bypass)
• Полная локализация: MiniMessage, HEX-цвета, пользовательская палитра
• Режим отладки с лог-файлом и уведомлениями в чат

• Сервер: Spigot / Paper / Purpur 1.16.5 — 1.21.4
• Java для сборки: 17 и новее (байткод — Java 16, совместим с 1.16.5 и новее)
• Опционально: WorldEdit или FastAsyncWorldEdit — выделение регионов их топором
• Опционально: Citizens — dummy в виде NPC-игрока; ZNPCs определяется, но без API используется Vindicator

1. Скопируйте kkCabins-1.0.jar в папку plugins/ сервера.
2. Перезапустите сервер.
3. Сконфигурируйте plugins/kkCabins/config.yml и locale.yml при необходимости (/kkcabins reload применяет изменения).

Важно: данные хранятся в plugins/kkCabins/: config.yml (кабинки, варпы, bypass-уровни), locale.yml (сообщения и цвета), dummies.yml (состояние dummy, создаётся при первом включении отладки), debug.log.

Нажмите, чтобы раскрыть...

• selector — выдаёт выделитель (см. раздел 5).
• create cabin — создаёт кабинку из текущего выделения. Дубликат ID запрещён.
• create door — назначает область дверей кабинке из текущего выделения. Область не может совпадать со всей кабинкой. Материал определяется автоматически (см. раздел 6.2).
• delete — удаляет кабинку (недоступно во время дуэли).
• warp create — создаёт варп: без аргументов — на вашей позиции; x y z — с вашими углами обзора; x y z yaw pitch — полная позиция.
• warp set — привязывает варп кабинке (точка телепорта победителя).
• warp tp — телепорт к варпу (только игроки).

• ЛКМ по блоку — первая точка, ПКМ — вторая.
• Предмет помечен внутренним ключом (PersistentDataContainer) — переименованный топор из наковальни не сработает.
• Название и lore настраиваются в locale.yml (секция selector).

1. Игроки (и/или dummy) входят в свободную кабинку — приходят уведомления о входе и присоединении соперника.
2. При достижении минимального числа участников стартует обратный отсчёт (actionbar).
3. Двери закрываются, кабинка переходит в состояние боя, всё внутри — бойцы.
4. PvP разрешён только между бойцами этой кабинки. Атака изнутри наружу и снаружи внутрь — запрещена (включая стрелы и снаряды).
5. Смерть участника = поражение: победитель получает стадию лута (таймер в actionbar), по окончании которой телепортируется на варп кабинки (или спавн основного мира, если варп не задан). Проигравший возрождается на worldspawn.
6. Двери открываются строго по окончании таймера лута.

Стадия лута — продолжение дуэли: победитель по-прежнему заперт в кабинке, послаблений на вход/выход нет. Двери не открываются раньше срока ни при каких условиях.

Нажмите, чтобы раскрыть...

• Область дверей задаётся отдельно (create door).
• Материал определяется автоматически по блокам области дверей: приоритет у дверных блоков (двери, люки), иначе самый частый не-air блок; если область пуста — WHITE_STAINED_GLASS.
• Определённый материал сохраняется в конфиг как door.material — его можно задать вручную.
• Сообщение с определённым материалом выводится при включённых debug-уведомлениях; факт закрытия логируется в debug.log.

• Отмена телепортов наружу (команды, плагины); жемчуг Эндера и плод хоруса не выводят из дуэли никого, даже с полным bypass (внутри кабинки жемчугом пользоваться можно).
• Отскок от границы + счётчик нарушений: третья попытка — принудительный телепорт внутрь.
• Задача удержания (каждые 0.5 с): выбравшегося любым способом бойца возвращает на последнюю позицию внутри.
• Вертикальный эскейп: позиция на уровне потолка или выше (Y / Y+1 от верхней границы региона) — телепорт в центр кабинки.
• Дальний эскейп: 1.7+ блока за территорию — телепорт в центр (центр вычисляется по безопасной высоте — без попадания в блоки).
• Watchdog: если бойцов внутри нет дольше 3 секунд — повторная попытка принудительного возврата; бой завершается только если телепорт физически невозможен.

Замечание: OP по умолчанию имеет все права, включая любые bypass.level.X. Для «чистого» теста ограничений снимите OP или выдайте точечные права через perms-плагин.

Нажмите, чтобы раскрыть...

bypass_settings:
  level.0:
    gamemodes: [SPECTATOR]   # вход ходьбой только в этих режимах (пусто = без ограничения)
    ender_pearl: false       # вход жемчугом Эндера запрещён
    chorus_fruit: false      # вход плодом хоруса запрещён
    force_tp_in: true        # можно телепортироваться ВНУТРЬ командами/плагинами
    force_tp_out: true       # можно телепортироваться ИЗНУТРИ НАРУЖУ командами/плагинами
    force_tp_player: false   # нельзя телепортировать ИГРОКА во время дуэли

cabins:
  cabin_1:
    region:                  # регион кабинки
      pos1: {world: world, x: 0, y: 60, z: 0}
      pos2: {world: world, x: 10, y: 70, z: 10}

    door:                    # область дверей
      pos1: ...
      pos2: ...
      material: WHITE_STAINED_GLASS   # авто-определение при create door
 
   players: {min: 2, max: 2}
    timers: {start: 5, end: 10}

• Ключи в bypass_settings вида level.<число> становятся правами kkcabins.bypass.level.<число>; прочие ключи игнорируются (пишется предупреждение).
• timers.start — отсчёт до боя (сек), timers.end — стадия лута (сек).
• Раздел warps хранит варпы (мир, координаты, углы).

colors:
  primary: "#99ff75"    # HEX
  secondary: "<white>"  # minimessage-тег
  accent: "#2aff8a"
  error: "red"          # имя цвета minimessage

• {c:primary}текст{/c:primary} — включить/выключить цвет.
• {/c} — сбросить все цвета далее.
• Невалидное значение цвета (например qwdhas) — ошибка в консоль, debug.log и уведомление админам при включённых debug-уведомлениях; цвет заменяется на белый.

• Citizens — NPC-игрок. attack=off — стоит без оружия; attack=on — деревянный меч, сам идёт к цели. Урон по нему нативный.
• ZNPCs — у плагина нет стороннего API, dummy создаётся как Vindicator (с уведомлением).
• Без NPC-плагинов — Vindicator. attack=off — AI выключен, без оружия («не поднимет топор»); attack=on — железный топор, сражается сам. HP/урон — из настроек dummy.

• debug enable — включает режим, создаёт debug.log, возвращает деспавненных ранее dummy. Режим переживает рестарт сервера (признак — существующий debug.log).
• debug notifications on|off — уведомления об ошибках и предупреждениях игрокам с правом kkcabins.debug.notify (по умолчанию выключены). Также включает показ служебных сообщений (регион из WorldEdit, материал дверей).
• debug disable — выключает режим и уведомления, деспавнит dummy (состояние сохраняется), удаляет пустой dummies.yml.

• Получение: Bukkit.getServicesManager().load(CabinsAPI.class, plugin) либо Main.getInstance().getApi().
• События: CabinPlayerEnterEvent, CabinPlayerLeaveEvent, CabinFightStartEvent, CabinFightEndEvent, CabinWinnerDeclaredEvent.
• Policy-слой: сторонний плагин может переопределять минимум участников и решения об уроне/телепорте.
• Пакет: com.kk.cabins.api.

• При рестарте сервера во время дуэли снимок блоков дверей теряется: после принудительного завершения боя стекло в проёме останется — уберите вручную.
• Пакетные NPC (ZNPCsPlus и аналоги) не поддерживаются: нет ни реальной сущности для урона, ни стабильного API.
• Dummy-Vindicator не умеет обходить препятствия (ванильный моб-ИИ) и внутри кабинки возвращается принудительно, как и игроки.
• Проигравший дуэль всегда возрождается на спавне основного мира, даже если его кровать вне кабинки.