Руководство

Как сделать плагин для Folia

Обновлено: 18 октября 2026 г.

Folia это форк Paper, который делит мир на регионы и обрабатывает их тики в разных потоках, чтобы большие серверы могли использовать много ядер процессора. Единого основного потока больше нет, и это ломает привычный планировщик Bukkit. Плагин для Folia это плагин для Paper, написанный под эту модель, и он должен заявить об этом в своём plugin.yml.

Пример с деталями по времени, которые нужны Folia.

Сгенерировать это в Codexe

Шаг за шагом

  1. 1.Убедитесь, что вам нужна Folia

    Folia помогает серверам, где много игроков разбросано по миру. Большинство серверов работает на Paper; многие популярные плагины не поддерживают Folia, поэтому сначала проверьте те, на которые вы полагаетесь.

  2. 2.Собирайте под Folia API

    Используйте зависимость folia-api для своей версии из репозитория PaperMC с областью provided в проекте Maven или Gradle.

  3. 3.Замените планировщик Bukkit

    Bukkit.getScheduler() не работает на Folia. Используйте региональный планировщик для работы в определённом месте, планировщик сущности для работы с игроком или мобом, глобальный региональный планировщик для задач на весь мир и асинхронный планировщик для ввода-вывода.

  4. 4.Трогайте объекты только из их собственного региона

    Меняйте блок или сущность только в том потоке, которому они принадлежат. Используйте teleportAsync вместо teleport и планируйте задачу в регионе цели, прежде чем её менять.

  5. 5.Заявите поддержку Folia

    Добавьте folia-supported: true в plugin.yml. Без этого Folia отказывается загружать плагин.

  6. 6.Проверьте на сервере Folia

    Компиляция доказывает, что код собирается под Folia API, но не то, что он потокобезопасен. Запустите его на тестовом сервере Folia с несколькими игроками в разных местах.

Четыре планировщика

ПланировщикКак получитьДля чего использовать
RegionBukkit.getRegionScheduler()Работа в точке мира: установка блоков, спавн
Entityentity.getScheduler()Работа с одним игроком или мобом, следует за ним между регионами
Global regionBukkit.getGlobalRegionScheduler()Время в мире, погода, всё, что не привязано к месту
AsyncBukkit.getAsyncScheduler()База данных, файлы, веб-запросы, но никогда не мир

Что обычно ломается

  • Повторяющиеся задачи для всех игроков: один цикл по всем игрокам онлайн больше не работает; вместо этого запускайте задачу в планировщике сущности каждого игрока.
  • Телепорты и задержки: для «телепорта через 3 секунды» нужен планировщик сущности и teleportAsync.
  • Общие данные: словари и счётчики, которые используются из нескольких регионов, должны быть потокобезопасными, например конкурентными коллекциями.
  • Зависимости: библиотека, которая вызывает планировщик Bukkit, на Folia выбрасывает UnsupportedOperationException.

Один плагин для Paper и Folia

Планировщики region, entity, global и async в актуальных версиях входят и в Paper API, поэтому плагин, который использует только их и заявляет folia-supported: true, может работать и на Paper, и на Folia. Часто это лучший вариант: один .jar для любого сервера.

С Codexe

Выберите тип Folia. Сгенерированный плагин планирует работу через планировщики region, entity, global region и async, заявляет folia-supported: true и собирается под Folia API через Maven. Он компилируется и проверяется, прежде чем получить статус «Готово».

Укажите в запросе детали по времени («каждую минуту для каждого игрока онлайн», «телепорт через 3 секунды»): именно здесь код для Folia отличается сильнее всего. «Попробовать сейчас» пока не запускает серверы Folia, поэтому проверяйте .jar на своём сервере Folia.

Вопросы

Работают ли плагины Paper на Folia?

Только если они написаны для неё и заявляют folia-supported: true. Обычный плагин Paper, который использует планировщик Bukkit, будет отклонён или упадёт.

Работает ли плагин для Folia на Paper?

Да, если он использует только те API, которые есть и в Paper, а в актуальных версиях Paper это включает планировщики Folia.

Мой плагин для Folia выбрасывает исключение про планировщик

Какой-то код, часто из библиотеки, всё ещё использует планировщик Bukkit. Попросите в чате проекта перенести его в планировщик region или entity.

Создайте плагин для Folia

Этот промпт откроется уже готовым к отправке:

“Плагин для Folia 1.21.4 под названием RTP: /rtp телепортирует игрока в случайное безопасное место в радиусе 5000 блоков после 3-секундной задержки, которая отменяется при движении, через планировщик сущности и teleportAsync, кулдаун 10 минут для каждого игрока хранится в SQLite, folia-supported: true, радиус, кулдаун и сообщения в config.yml.”

Сгенерировать это в Codexe
Как сделать плагин для Folia (региональные планировщики) | Codexe