MinecoloniesEntityFix - Решение проблемы заморозки жителей Minecolonies на Spigot

На серверах, работающих на базе Spigot (и его форках), существует механизм оптимизации entity-activation-range, настроенный в файле spigot.yml. По умолчанию этот механизм "выключает" логику мобов, если игрок находится дальше определенного радиуса (обычно 32 блока).

Для обычных мобов это полезно для снижения нагрузки на процессор. Но для мода Minecolonies это критично. Жители колонии перестают работать (не ходят на работу, не строят, не едят), как только игрок отходит от колонии на расстояние чуть больше чанка. В результате колония "замирает", что делает игру на сервере невозможной, если игроки часто покидают базу.

Тестировал на версии: minecolonies-1.20.1-1.1.1143

MinecoloniesEntityFix

Плагин для принудительной активации сущностей Minecolonies (жителей, строителей, стражников), игнорируя ограничения entity-activation-range в spigot.yml.

Решение

Данный плагин запускает фоновую задачу (BukkitRunnable), которая периодически "будит" всех жителей колоний на сервере. Он напрямую взаимодействует с NMS (Net Minecraft Server) уровнем, чтобы пометить сущности как активные, заставляя сервер обрабатывать их AI и действия, даже если ни одного игрока нет поблизости.


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

Файл config.yml позволяет гибко настроить интервал проверки:

yaml
Интервал активации в тиках (20 тиков = 1 секунда)
Рекомендуется: 20-40 тиков (1-2 секунды)
Слишком низкое значение (1-10) может повысить нагрузку на CPU.
activation-in**terval-ticks: 20

Режим отладки: true — вывод в консоль количества активированных сущностей
debug: false
Техническая реализация

Плагин автоматически определяет сущности мода по их классу (содержит citizen, minecolonies, visitor, mercenary, builder и т.д.) и выполняет принудительную активацию через NMS метод entity.activated = true, обходя стандартные проверки расстояния Spigot.

Совместимость

Ядро сервера: Spigot, Paper, Purpur (версии 1.20.1 и выше, с вероятностью обратной совместимости до 1.18).
Мод: Minecolonies (все версии, использующие стандартную систему сущностей).

Рекомендации по производительности

Если на сервере одновременно активно 5+ колоний (более 300 жителей), рекомендуется установить activation-interval-ticks: 40.

Плагин затрагивает только живых существ (LivingEntity), не влияя на предметы, капли опыта или транспорт, что исключает лишнюю нагрузку.

activation-interval-ticks: 20 — как часто плагин проверяет и активирует жителей. 20 тиков = 1 секунда. Если поставить 40 (2 сек) — нагрузка ниже, но жители могут чуть медленнее реагировать. 20 — оптимально для стабильности.

max-entities-per-tick: 600 — сколько жителей плагин обрабатывает за один раз. Если у вас на сервере 300 жителей, а лимит стоит 100, то за один цикл активируется только 100, остальные подождут следующего. 600 — это много, подходит для мощных серверов с тысячами жителей. Для обычного сервера можно снизить до 100-200, чтобы снизить нагрузку.

debug: false — если включить, то в консоль будет писаться каждое действие плагина (какого жителя активировал и т.д.). Полезно для проверки, но на постоянной основе лучше не включать, чтобы консоль не засорялась.

track-builder-actions: false — если включить, плагин будет писать в лог, какие блоки строители ломают и ставят. Нужно только для отладки, чтобы убедиться, что строители действительно работают.

keep-chunks-loaded-when-no-players: false — если поставить true, то чанки с жителями будут оставаться загруженными, даже когда на сервере никого нет. Сейчас false — значит когда последний игрок выходит, всё останавливается. Включите true, если хотите, чтобы колонии работали 24/7.

keep-chunks-loaded-when-players-online: false — если поставить true, то чанки с жителями будут принудительно загружаться, даже когда игроки онлайн, но ушли далеко от своей колонии. Сейчас false — значит пока игроки на сервере, чанки грузятся только в радиусе их нахождения. Если игроки часто путешествуют и жалуются, что колония замирает, включите true.

chunk-ticket-update-interval-ticks: 40 — как часто плагин обновляет "билеты" на удержание чанков. 40 тиков = 2 секунды. Это отдельный интервал, который работает реже, чем активация жителей, чтобы снизить лишнюю нагрузку.

enable-ownership-check-for-force-load: true — проверка, кому принадлежат жители. При true плагин принудительно загружает чанки только для тех жителей, чьи владельцы сейчас онлайн. При false — загружает всех жителей подряд. Сейчас true — это экономный режим, чтобы не грузить чужие колонии.

make-invulnerable-when-force-loaded: true — делает жителей неуязвимыми к урону, когда их чанки загружены принудительно (игрок далеко или офлайн). Это чтобы жители не погибли от мобов, пока игрок их не защищает. Если выключить (false), жители смогут умирать даже когда игрока нет рядом.


** Команды MinecoloniesEntityFix
Основная команда: `/mcfix`
Алиас: `/minecoloniesfix`
Требуемое право для всех подкоманд: `minecoloniesfix.admin` (по умолчанию `op`).**
---
`/mcfix`
Показывает краткую справку по доступным подкомандам.
---
`/mcfix status`
Показывает текущее состояние плагина:
- активна ли задача активации;
- количество сущностей в кэше;
- количество force-loaded чанков (по внутреннему кэшу);
- количество онлайн-игроков в кэше;
- текущий интервал активации и лимит обработки;
- состояние debug.
---
`/mcfix reload`
Перезагружает `config.yml` через `reloadConfig()`.
Когда использовать:
- после ручного изменения конфигурации,
- для применения новых значений без полного рестарта сервера.
---
`/mcfix scan`
Принудительно запускает пересканирование сущностей Minecolonies (`scanForMinecoloniesEntities()`),
обновляет кэш и возвращает актуальное количество найденных сущностей.
---
`/mcfix run`
Ручной запуск одного цикла активации (`activateMinecoloniesEntities()`).
Полезно для быстрой проверки поведения после изменения настроек.
---
`/mcfix debug `
Управление параметром `debug` в конфиге на лету:
- `on` — включить,
- `off` — выключить,
- `toggle` — переключить.
Изменение сразу сохраняется в `config.yml` (`saveConfig()`).**