AdminMode/MODERATION_PLUGIN_CONTRACT.md

Контракт moderation-плагина для AdminMode

Этот документ описывает минимальные команды и поведение отдельного moderation-плагина, необходимого для работы кнопок Mute, Unmute, Kick и Ban в AdminMode 1.2 на Paper 26.1.2.

AdminMode выполняет команды от консоли и передаёт реального модератора отдельным аргументом actor:<ник>. Активные баны должны храниться только в стандартном Paper ProfileBanList, иначе BanList и кнопка разбана в AdminMode не увидят их.

Формат сроков

Плагин обязан принимать как минимум:

• 1h — один час;
• 1d — один день;
• 7d — семь дней;
• 30d — тридцать дней;
• permanent — бессрочно.

Рекомендуется дополнительно принимать любое положительное значение в формате <число><s|m|h|d|w|y>. Нулевые, отрицательные, неизвестные и переполненные значения должны отклоняться без применения наказания.

Автор наказания

При вызове из AdminMode команды выглядят так:

mute Steve 1h actor:Moderator флуд
ban Steve 7d actor:Moderator читы
kick Steve actor:Moderator нарушение правил

Правила обработки actor::

• учитывать аргумент только когда CommandSender является консолью;
• для команды игрока всегда записывать автором самого игрока;
• не разрешать игроку подменять автора через actor:;
• убрать actor:<ник> из сохраняемой причины.

Команды

Mute

/mute <player> <duration> [actor:<name>] <reason...>
/unmute <player> [actor:<name>] [reason...]

Из AdminMode команда вызывается по полному Bukkit namespace moderationcommands:unmute, чтобы её не перехватывали FlectonePulse и другие плагины с собственной командой /unmute. Namespace предполагает, что имя плагина в его plugin.yml — ModerationCommands.

Обязательное поведение:

• разрешать мутить онлайн- и офлайн-игрока по UUID;
• хранить UUID, последнее имя, автора, причину, время выдачи и expiresAt между перезапусками;
• автоматически считать временный мут истёкшим;
• отменять сообщения через Paper AsyncChatEvent, пока мут активен;
• блокировать настраиваемый список чат-команд, минимум /msg, /tell, /w, /whisper, /reply, /r и /me;
• при попытке писать показывать причину и оставшийся срок;
• /unmute должен немедленно снимать активный мут;
• повторный mute обновляет существующее активное наказание, а не создаёт конфликтующие записи.

Permissions:

moderation.command.mute
moderation.command.unmute

AdminMode вызывает /mute и /unmute из карточки игрока. Кнопка Unmute доступна по отдельному праву и передаёт причину, если модератор её указал.

Ban

/ban <player> <duration> [actor:<name>] <reason...>
/unban <player> [actor:<name>] [reason...]

Обязательное поведение:

• разрешать банить онлайн- и офлайн-профили;
• разрешать профиль до UUID, не создавать отдельные name-only баны;
• получать ProfileBanList через Bukkit.getBanList(BanListType.PROFILE);
• добавлять бан через typed ProfileBanList с причиной, Instant окончания или null для permanent, а также фактическим автором;
• после добавления бана отключать игрока онлайн с сообщением о причине и сроке;
• /unban удаляет тот же профиль из Paper ProfileBanList;
• не использовать собственный кэш или базу как источник активного бана: AdminMode снимает бан напрямую через BanEntry.remove().

Permissions:

moderation.command.ban
moderation.command.unban

Если нужна история, её можно вести отдельным append-only журналом, но актуальный статус всегда нужно проверять в Paper ProfileBanList.

Kick

/kick <player> [actor:<name>] <reason...>

Обязательное поведение:

• команда работает только для игрока онлайн;
• отключает игрока Adventure-компонентом с причиной и именем модератора;
• не создаёт постоянное наказание;
• возвращает понятную ошибку, если игрок уже вышел.

Permission:

moderation.command.kick

Существующая команда Warn

Warn остаётся в ядре сервера и должен принимать:

/warn <player> <duration> <reason...>

Минимально поддерживаемые сроки совпадают со списком выше, включая permanent. Источник истории, срока и статуса варнов — AdminMode (plugins/AdminMode/warn-history.json), поэтому отдельная команда /unwarn для интеграции не требуется.

Возвращаемый результат команд

Все обработчики Bukkit-команд должны:

• возвращать true, только если команда распознана и наказание принято;
• возвращать false при неверном синтаксисе, неизвестном сроке или невозможности применить действие;
• не изменять данные при ошибке валидации;
• корректно работать от консоли без OP/LuckPerms-проверки;
• проверять соответствующий permission при вызове игроком.

AdminMode создаёт локальную запись warn только после успешного dispatchCommand. Для Mute/Ban/Kick состояние и сообщения об ошибках полностью отвечает moderation-плагин.

Настройка AdminMode

Стандартные шаблоны plugins/AdminMode/config.yml:

moderation_actions:
  dispatch_as_console: true
  commands:
    warn: "warn {target} {duration} {reason}"
    mute: "mute {target} {duration} actor:{moderator} {reason}"
    unmute: "moderationcommands:unmute {target} actor:{moderator} {reason}"
    ban: "ban {target} {duration} actor:{moderator} {reason}"
    kick: "kick {target} actor:{moderator} {reason}"

После установки moderation-плагина выполните /adminmode reload или перезапустите сервер, затем проверьте каждую команду сначала вручную из консоли и только потом через Dialog.