150 lines
7.9 KiB
Markdown
150 lines
7.9 KiB
Markdown
# Контракт 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 команды выглядят так:
|
||
|
||
```text
|
||
mute Steve 1h actor:Moderator флуд
|
||
ban Steve 7d actor:Moderator читы
|
||
kick Steve actor:Moderator нарушение правил
|
||
```
|
||
|
||
Правила обработки `actor:`:
|
||
|
||
- учитывать аргумент только когда `CommandSender` является консолью;
|
||
- для команды игрока всегда записывать автором самого игрока;
|
||
- не разрешать игроку подменять автора через `actor:`;
|
||
- убрать `actor:<ник>` из сохраняемой причины.
|
||
|
||
## Команды
|
||
|
||
### Mute
|
||
|
||
```text
|
||
/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:
|
||
|
||
```text
|
||
moderation.command.mute
|
||
moderation.command.unmute
|
||
```
|
||
|
||
AdminMode вызывает `/mute` и `/unmute` из карточки игрока. Кнопка Unmute доступна по отдельному праву и передаёт причину, если модератор её указал.
|
||
|
||
### Ban
|
||
|
||
```text
|
||
/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:
|
||
|
||
```text
|
||
moderation.command.ban
|
||
moderation.command.unban
|
||
```
|
||
|
||
Если нужна история, её можно вести отдельным append-only журналом, но актуальный статус всегда нужно проверять в Paper ProfileBanList.
|
||
|
||
### Kick
|
||
|
||
```text
|
||
/kick <player> [actor:<name>] <reason...>
|
||
```
|
||
|
||
Обязательное поведение:
|
||
|
||
- команда работает только для игрока онлайн;
|
||
- отключает игрока Adventure-компонентом с причиной и именем модератора;
|
||
- не создаёт постоянное наказание;
|
||
- возвращает понятную ошибку, если игрок уже вышел.
|
||
|
||
Permission:
|
||
|
||
```text
|
||
moderation.command.kick
|
||
```
|
||
|
||
## Существующая команда Warn
|
||
|
||
Warn остаётся в ядре сервера и должен принимать:
|
||
|
||
```text
|
||
/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`:
|
||
|
||
```yaml
|
||
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.
|