PunishNotify
?️ 适用于 Paper 1.21.11 的 Discord 处罚通知插件,支持附带网页证据
English Description | Русское описание
? English
PunishNotify 是一款强大且轻量的 Minecraft Paper 1.21.11 插件,旨在无缝连接服务器管理(通过 EssentialsX)与您的 Discord 管理频道。
当管理员封禁、静音、踢出、警告或监禁玩家时,PunishNotify 会拦截该操作并启动高速 Discord 通知流程。PunishNotify 的独特之处在于其基于网页的交互式证据提交系统:在通知发布到 Discord 之前,管理员会在游戏中收到带有操作按钮的提示,允许他们通过浏览器界面直接拖放截图或视频。
✨ Key Features
- ? Comprehensive Punishment Tracking: Automatically detects
ban,tempban,unban(pardon),mute,unmute,kick,warn,jail, andunjailevents. - ?️ Web Evidence Uploader:
- Generates a secure, temporary web upload link sent directly to the moderator in Minecraft chat.
- Interactive Drag & Drop web interface built with modern UI.
- Supports multiple image and video formats (up to configurable file size & count limits).
- Automatically embeds the primary image into the Discord embed while attaching remaining files as message attachments.
- Files are automatically deleted from server storage once dispatched.
- ⏳ Smart Timeout & Skip Logic:
- Moderators can click [Skip] in chat or on the web page to instantly send the webhook without evidence.
- Configurable timeout (default: 2 minutes) automatically dispatches the webhook without attachments if no files are uploaded in time.
- ? Fault-Tolerant Retry Queue:
- Outages or Discord API rate limits will not cause lost reports.
- Failed dispatches enter an in-memory retry queue with configurable attempt counts and backoff intervals.
- ⚙️ Granular Event Toggles: Individually enable or disable webhook notifications for specific punishment types in
config.yml.
? How It Works
1. Moderator executes punishment command (/ban, /mute, /warn, etc.)
│
▼
2. PunishNotify intercepts event & generates a unique upload token
│
▼
3. In-Game Prompt sent to Moderator: [Upload Evidence] [Skip]
│
┌───────────────┴───────────────┐
▼ ▼
[Moderator Uploads File] [Skip or Timeout (120s)]
│ │
▼ ▼
Embed created with images Embed created without attachments
│ │
└───────────────┬───────────────┘
▼
4. Dispatch to Discord Webhook (with retry queue if API fails)
? Commands & Permissions
| Command | Permission | Default | Description |
|---|---|---|---|
/punishnotify reload |
punishnotify.reload |
op |
Reloads plugin configuration (config.yml). |
/punishnotify skip <token> |
punishnotify.skip |
op |
Skips evidence uploading for an active punishment token. |
| (Admin Super-node) | punishnotify.admin |
op |
Grants full access to all plugin commands and permissions. |
⚙️ Configuration Guide (config.yml)
The configuration file is located at plugins/PunishNotify/config.yml.
| Path | Type | Default | Description |
|---|---|---|---|
discord.webhook-url |
String |
"" |
The Discord Webhook URL. Webhooks are disabled if empty. |
discord.username |
String |
"PunishNotify" |
Custom bot display name in Discord. |
discord.avatar-url |
String |
"" |
Direct image URL for the Discord webhook avatar. |
discord.retry-enabled |
Boolean |
true |
Enables the automatic retry queue for failed webhook transmissions. |
discord.retry-max-attempts |
Integer |
5 |
Maximum delivery attempts before dropping a report. |
discord.retry-interval-seconds |
Integer |
30 |
Time interval (seconds) between retry attempts. |
http-server.enabled |
Boolean |
true |
Enables the built-in HTTP server for evidence uploading. |
http-server.port |
Integer |
8734 |
Network port for the HTTP upload server. |
http-server.bind |
String |
"0.0.0.0" |
Network interface IP binding (0.0.0.0 listens on all interfaces). |
http-server.public-url |
String |
"" |
Public external URL displayed to moderators (e.g. http://server.example.com:8734). If empty, defaults to http://<bind>:<port>. |
evidence.max-file-size-mb |
Integer |
25 |
Maximum allowed size (in MB) per uploaded file. |
evidence.max-files |
Integer |
10 |
Maximum number of files permitted per punishment report. |
evidence.timeout-seconds |
Integer |
120 |
Waiting period (seconds) before auto-sending report without evidence. |
events.ban |
Boolean |
true |
Send webhook notifications for player bans (/ban, /tempban). |
events.unban |
Boolean |
true |
Send webhook notifications for player unbans (/pardon, /unban). |
events.mute |
Boolean |
true |
Send webhook notifications for player mutes. |
events.unmute |
Boolean |
true |
Send webhook notifications for player unmutes. |
events.kick |
Boolean |
true |
Send webhook notifications for player kicks. |
events.warn |
Boolean |
true |
Send webhook notifications for player warnings (/warn). |
events.jail |
Boolean |
true |
Send webhook notifications for player jailing. |
events.unjail |
Boolean |
true |
Send webhook notifications for player release from jail. |
? Compatibility & Requirements
- Minecraft Server: Paper 1.21.11(或现代 Paper 分支)。
- Java Version: Java 21 或更高版本。
- Dependencies: EssentialsX 2.20+(软依赖;用于惩罚事件追踪)。
? 从源码构建
# Clone the repository
git clone https://github.com/Golub4ik-Official/PunishNotify.git
# Build with Gradle (JDK 25 required)
./gradlew build
编译后的 JAR 文件位置:build/libs/PunishNotify-1.2.0.jar
?? Русский
PunishNotify — это производительный плагин для серверов Paper 1.21.11, организующий интеграцию системы наказаний игрового сервера (EssentialsX) с каналами модерации в Discord.
Когда модератор выдаёт бан, мут, кик, предупреждение или отправляет игрока в тюрьму, PunishNotify перехватывает событие и запускает процесc публикации в Discord. Главная особенность плагина — интерактивная система прикрепления доказательств через веб-интерфейс: модератору в чате Minecraft выдаётся ссылка с кнопками, открывающая страницу в браузере для быстрой загрузки скриншотов или видео с помощью Drag-and-Drop.
✨ Основные возможности
- ? Полный отслеживаемый спектр наказаний:
бан,временный бан,разбан,мут,размут,кик,предупреждение (warn),тюрьма (jail)иосвобождение. - ?️ Веб-загрузчик доказательств:
- Генерация уникальной безопасной ссылки для загрузки файловых доказательств.
- Современный веб-интерфейс загрузки с поддержкой перетаскивания файлов (Drag & Drop).
- Поддержка изображений и видеофайлов с гибким ограничением размера и количества.
- Автоматическое встраивание первого изображения в embed Discord-сообщения и прикрепление оставшихся файлов к сообщению.
- Файлы автоматически удаляются с сервера сразу после отправки.
- ⏳ Таймаут и пропуск:
- Возможность нажать [Пропустить] в чате или на веб-странице для мгновенной отправки отчёта без файлов.
- Настраиваемый таймаут (по умолчанию 2 минуты), по истечении которого отчёт уходит в Discord автоматически без доказательств.
- ? Очередь повторной отправки (Retry Queue):
- Временные сбои сети или ограничение запросов Discord (rate-limit) не приведут к потере отчётов.
- Неотправленные отчёты попадают в очередь в памяти с настраиваемым количеством попыток и интервалом повтора.
- ⚙️ Гибкое отключение событий: Возможность включать/отключать уведомления для каждого типа наказаний в
config.yml.
? Принцип работы
1. Модератор выдаёт наказание (/ban, /mute, /warn и т.д.)
│
▼
2. PunishNotify перехватывает событие и создаёт токен загрузки
│
▼
3. Модератор получает кнопки в чате: [Загрузить] [Пропустить]
│
┌───────────────┴───────────────┐
▼ ▼
[Загрузка файлов в UI] [Пропуск / Таймаут 120с]
│ │
▼ ▼
Embed с медиа-файлами Embed без вложений
│ │
└───────────────┬───────────────┘
▼
4. Отправка вебхука в Discord (с повторами при сбоях)
? Команды и права
| Команда | Право (Permission) | По умолчанию | Описание |
|---|---|---|---|
/punishnotify reload |
punishnotify.reload |
op |
Перезагружает конфигурацию плагина (config.yml). |
/punishnotify skip <token> |
punishnotify.skip |
op |
Пропускает загрузку доказательств для наказания с указанным токеном. |
| (Админ супер-право) | punishnotify.admin |
op |
Полный доступ ко всем командам и правам плагина. |
⚙️ Гайд по настройке конфигурации (config.yml)
Файл конфигурации расположен по пути plugins/PunishNotify/config.yml.
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
discord.webhook-url |
String |
"" |
Discord Webhook URL。若为空,则禁用发送功能。 |
discord.username |
String |
"PunishNotify" |
Discord 中机器人的显示名称。 |
discord.avatar-url |
String |
"" |
Discord 机器人头像的直接链接。 |
discord.retry-enabled |
Boolean |
true |
在 Discord API 不可用时启用重试机制。 |
discord.retry-max-attempts |
Integer |
5 |
发送报告的最大尝试次数。 |
discord.retry-interval-seconds |
Integer |
30 |
重试间隔(秒)。 |
http-server.enabled |
Boolean |
true |
启用内置的证据上传 Web 服务器。 |
http-server.port |
Integer |
8734 |
Web 服务器端口。 |
http-server.bind |
String |
"0.0.0.0" |
网络 IP 接口 (0.0.0.0 表示所有可用接口)。 |
http-server.public-url |
String |
"" |
供管理员使用的外部 URL(例如 http://server.example.com:8734)。若为空,则使用 http://<bind>:<port>。 |
evidence.max-file-size-mb |
Integer |
25 |
单个文件的最大大小(MB)。 |
evidence.max-files |
Integer |
10 |
每次处罚允许上传的最大文件数量。 |
evidence.timeout-seconds |
Integer |
120 |
自动发送前等待证据的超时时间(秒)。 |
events.ban |
Boolean |
true |
发送封禁通知(/ban, /tempban)。 |
events.unban |
Boolean |
true |
发送解封通知(/pardon, /unban)。 |
events.mute |
Boolean |
true |
发送静音通知。 |
events.unmute |
Boolean |
true |
发送解除静音通知。 |
events.kick |
Boolean |
true |
发送踢出通知。 |
events.warn |
Boolean |
true |
发送警告通知(/warn)。 |
events.jail |
Boolean |
true |
发送监禁通知。 |
events.unjail |
Boolean |
true |
发送释放监禁通知。 |
? 兼容性与要求
- Minecraft 服务器: Paper 1.21.11(或兼容分支)。
- Java 版本: Java 21 及以上。
- 依赖项: EssentialsX 2.20+(
softdepend,用于事件追踪所必需)。
? 从源码构建
# 克隆仓库
git clone https://github.com/Golub4ik-Official/PunishNotify.git
# 通过 Gradle 构建(需要 JDK 25)
./gradlew build
生成的 JAR 文件:build/libs/PunishNotify-1.2.0.jar
你是这个资源的作者?登录后可认领此资源。
相似资源
PacketEvents 是一款专为 Minecraft Java 版打造的协议库,旨在简化数据包的处理与传输。
ExyliaPlugins 的库。
通过对话框或铁砧界面帮助你的 Anthme
重新定义服务器上的生物运输方式。使用高度可定制的口袋道具,安全地捕获、存储和释放任何实体。
为基于 Spigot/Paper/Folia 的服务器添加对 Vivecraft 的支持
用于绘制游戏内地图或在浏览器中随探索实时进行地图绘制的实时地图。
评论 0
登录后参与评分
还没有评论,来抢沙发吧