
Staff+
Staff+ 是一款企业级、高性能的管理与实用插件,专为现代 Minecraft 网络打造。它提供两个平台专用的 JAR 文件——一个用于 Paper/Purpur/Folia 后端服务器,另一个用于 Velocity 代理服务器——共享统一的核心引擎,从而在整个网络中实现一致的管理处罚管理。
Paper 版运行于 Paper/Purpur/Folia 1.20–1.21+ 服务器,完全支持 Folia 多线程区域安全,并包含高级管理工具,如隐身(vanish)、物品栏检查和旁观者监控。
Velocity 版运行于 Velocity 3.3.0+ 代理服务器,在玩家到达后端服务器之前,就在网络网关处执行封禁、IP 封禁和静音操作。
两个版本共享相同的数据库、配置文件和迁移系统——根据你的设置部署其中一个或两个均可。
平台对比
| 功能 |
Paper (Paper/Purpur/Folia) |
Velocity (代理) |
| Ban / TempBan / Unban |
✅ |
✅ |
| IP-Ban / TempIP-Ban / UnIP-Ban |
✅ |
✅ |
| Mute / TempMute / Unmute |
✅ |
✅ |
| Warn / Warns / Clear |
✅ |
✅ |
| History / StaffHistory |
✅ |
✅ |
| Staff Rollback |
✅ |
✅ |
IP-Ban Exemption (/staffallow) |
✅ |
✅ |
Punishment Migration (/staffimport) |
✅ |
✅ |
| Discord Webhook Logging |
✅ |
✅ |
| Warning Escalation Ladder |
✅ |
✅ |
| Hierarchy Protection |
✅ |
✅ |
| Alt-Detection (IP Matching) |
✅ |
✅ |
| SQLite / MySQL Storage |
✅ |
✅ |
| Vanish System |
✅ |
❌ |
| Spectator Monitor/Follow |
✅ |
❌ |
Inventory Inspector (/invsee) |
✅ |
❌ |
| Gamemode Shortcuts |
✅ |
❌ |
Flight Toggle (/fly) |
✅ |
❌ |
Global Ban History (/bans) |
✅ |
✅ |
Ban Leaderboard (/bansleaderboard) |
✅ |
✅ |
Kick (/kick) |
✅ |
✅ |
Unwarn (/unwarn) |
✅ |
✅ |
Checkban (/checkban) |
✅ |
✅ |
Live Reload (/staff reload) |
✅ |
✅ |
| Bedrock Geyser Forms |
✅ |
N/A |
| Modrinth Update Notifier |
✅ |
✅ |
| bStats Metrics |
✅ |
✅ |
| Folia Scheduler Safety |
✅ |
N/A |
| Proxy-Level Ban Enforcement |
❌ |
✅ |
| Limbo Kick Prevention |
❌ |
✅ |
| Transparent Backend Command Forwarding |
❌ |
✅ |
功能
跨平台核心
- 共享数据库: Paper 和 Velocity 版本均读取和写入同一个处罚数据库(SQLite 或 MySQL),从而实现无缝的全网络管理。
- 共享配置:
config.yml 和 messages.yml 通过 Okaeri 配置框架在两个平台上使用相同的格式。
- 统一迁移引擎: 可从任一平台导入来自 7 种以上插件的处罚记录。
Folia 安全(Paper 版)
- 异步生命周期: 所有命令、数据库事务和数据包操作均在符合 Folia 的区域调度器或异步调度器上运行。
- Folia 传送安全: 标准传送被替换为安全、非阻塞的
teleportAsync 未来任务,完全防止线程崩溃。
- 隔离的数据包循环: 视觉切换功能(如隐身隐藏/显示数据包)安排在每个接收者特定的区域线程上,确保线程安全。
代理网关执行(Velocity 版)
- 登录前封禁检查: 在代理级别拦截登录尝试,并在被封禁的玩家到达任何后端服务器之前就拒绝其连接。
- 全网络静音过滤器: 阻止所有已连接服务器上的静音玩家的聊天消息。
- IP 封禁网关: 在代理网关处执行 IP 封禁,防止被封禁的 IP 连接到网络中的任何服务器。
隐身(仅限 Paper)
- 完全隐形: 将玩家从在线计数、玩家延迟列表、Tab 补全和可见列表中完全移除。
- 物理交互绕过: 隐身的管理员完全绕过物理压力板和绊线触发器。
- 无声容器: 允许无声打开箱子、熔炉和桶界面,而不会触发容器动画或音频。
- 潜行抑制: 在激活时防止怪物锁定目标、拾取物品,并完全抑制加入/离开消息。
- 视觉动作栏指示器: 通过安全的异步重复任务实时显示隐身状态 HUD。
管理(两个平台通用)
- 综合操作:集成了
/ban、/tempban、/ip-ban、/tempip-ban、/mute、/tempmute 和 /warn。
- 警告档案:通过
/warns <player> [list/clear] 追踪个人警告日志。
- 动态时间解析:支持复杂单位(如
1d、12h、45m)和无限持续时间映射(perm)的高级时间解析器。
- 关系型存储:由高性能数据库管理器提供支持,支持本地 SQLite 数据库和远程 MySQL 服务器,并通过轻量级、线程安全的 HikariCP 连接池进行管理。
- 关联账号副号检测:玩家登录时,自动扫描、记录并广播共享 IP 地址的替代账号,并对活跃(绿色)和封禁(红色)档案进行着色标记。
- 动态命令与历史记录一致性:多线程支持的
/history <player>、/staffhistory <staff> 和 /staffrollback <staff> 命令,辅以基于动态数据库的名称标签补全功能。
- 警告升级阶梯:根据当前警告等级动态调整处罚(例如临时静音升级为永久封禁)。命令分发在各平台的原生调度程序上安全执行。
- 非阻塞 Discord Webhook 日志:使用现代非阻塞 Java 21
HttpClient 接口实时嵌入记录所有静音、封禁和警告分发操作,对区域刻数无任何影响。
- 管理员覆盖层级保护:自定义员工权重等级 (
staff.hierarchy.weight.<number>) 阻止低级员工覆盖、停用或移除高级管理员或控制台(Integer.MAX_VALUE)施加的处罚。
- IP 封禁豁免绕过:将特定账号列入白名单(
/staffallow),使其能够连接并绕过活跃的 IP 封禁,而无需为其他共享该 IP 的账号解除 IP 封禁。
处罚导入器与迁移(双平台支持)
- 7 种支持的平台:无缝导入静音、封禁、警告和 IP 封禁,来源包括:
- Vanilla Minecraft:直接从服务器根目录下的
banned-players.json 和 banned-ips.json 导入。
- Essentials / EssentialsX:自动扫描
plugins/Essentials/userdata/*.yml 下用户配置文件中的静音和封禁记录。
- LiteBans:从 H2/SQLite/MySQL 数据库迁移封禁、静音和警告。支持自动检测
litebans.mv.db H2 文件或手动配置 JDBC 参数。
- AdvancedBan:集成并规范化来自 SQLite 或 MySQL 的传统 SQL
Punishments 表。
- MaxBans:从 SQLite 或 MySQL 迁移封禁、IP 封禁、静音和警告。
- BanManager:集成具有可配置表前缀的历史玩家封禁、静音和警告。
- BungeeAdminTools (BAT):从数据库表
bat_ban 和 bat_mute 导入条目。
- 动态自动扫描:在命令触发时扫描服务器上的活动文件,提取 SQLite 路径或远程 SQL 数据库凭据,实现零配置迁移。
- 批量操作:使用批量插入在单个事务中提交导入的记录,瞬间迁移数千条记录。
- 非阻塞 Future:在 non-blocking 线程池上完全异步运行连接设置、配置解码和数据库提交。
观察者跟随(仅限 Paper)
- 电影式摄像机追踪:将处于观察者模式的员工传送至目标身后以实现无缝跟随。
- 速度预测跟随:计算目标移动和速度向量 (
target.getVelocity()),将摄像机定位在目标前方稍许位置,消除卡顿和橡皮筋效应。
- 节流传送:自动更新以节流的 4 刻(200ms)间隔运行,并带有 400ms 冷却时间,给予客户端预测运动和 Paper 的异步传送 Future 足够时间完全解析。
- 可配置边界束缚:允许员工在 10 格半径内环绕或自由移动。超出边界时,摄像机会柔和地被拉回偏移位置。
物品栏检查器(仅限 Paper)
- 54 槽位实时 GUI:查看并编辑目标玩家的主物品栏(0-35)、护甲槽(头盔、胸甲、护腿、靴子)、副手物品以及状态统计。
- 实时统计与快捷方式:
- 金苹果:动态显示生命值、饥饿值和经验值。
- 药水瓶:显示活跃药水效果及其持续时间的实时列表。
- 末影箱:快速访问快捷物品,直接检查其末影箱。
- 无与伦比的 Folia 安全性:完全避免异步方块状态读取(在其他区域的基于方块的物品栏上查询
.getOpenInventory().getTopInventory().getHolder() 时会导致 Folia 崩溃)。相反,它实现了线程安全的自定义会话注册表,干净地跟踪活跃的检查视图并在区域内传播更新。
快捷指令(仅限 Paper)
- 即时游戏模式切换:快速执行包括创造模式 (
/gmc)、生存模式 (/gms)、观察者模式 (/gmsp) 和冒险模式 (/gma) 的命令。
- 飞行模式:通过
/fly 无缝切换飞行模式。
命令与权限
网络级命令(Paper & Velocity)
| 命令 |
描述 |
用法 |
权限节点 |
/ban |
将玩家封禁出服务器。 |
/ban <player> [reason] |
staff.ban |
/tempban |
暂时封禁一名玩家。 |
/tempban <player> <duration> [reason] |
staff.tempban |
/unban |
解除玩家的封禁。 |
/unban <player> |
staff.unban |
/ip-ban |
封禁玩家的 IP 地址。 |
/ip-ban <player> [reason] |
staff.ipban |
/tempip-ban |
暂时封禁玩家的 IP 地址。 |
/tempip-ban <player> <duration> [reason] |
staff.tempipban |
/unip-ban |
解除 IP 地址或玩家的封禁。 |
/unip-ban <player/IP> |
staff.unipban |
/mute |
在聊天中静音一名玩家。 |
/mute <player> [reason] |
staff.mute |
/tempmute |
暂时静音一名玩家。 |
/tempmute <player> <duration> [reason] |
staff.tempmute |
/unmute |
解除玩家的静音。 |
/unmute <player> |
staff.unmute |
/warn |
警告一名玩家。 |
/warn <player> [reason] |
staff.warn |
/warns |
查看或清除警告记录。 |
/warns <player> [list/clear] |
staff.warns |
/history |
查看玩家的完整处罚日志(活跃/非活跃)。 |
/history <player> |
staff.history |
/staffhistory |
查看某名工作人员发出的所有处罚。 |
/staffhistory <staff> |
staff.staffhistory |
/staffrollback |
回滚某名工作人员放置的所有活跃处罚。 |
/staffrollback <staff> [confirm] |
staff.staffrollback |
/staffallow |
豁免某玩家/UUID 免受活跃 IP 封禁。 |
/staffallow <player> [remove] |
staff.staffallow |
/staffimport |
从其他插件导入处罚记录。 |
/staffimport <source> [params...] |
staff.import |
/bans |
查看最近的服务器封禁记录(GUI / Geyser 表单 / 聊天)。 |
/bans [page] [--chat] |
staff.bans |
/bansleaderboard |
按发出的封禁数量查看工作人员排行榜。 |
/bansleaderboard [--chat] |
staff.bansleaderboard |
/kick |
踢出在线玩家,并验证权限层级。 |
/kick <player> [reason] |
staff.kick |
/unwarn |
移除玩家最新或特定的警告。 |
/unwarn <player> [id] |
staff.unwarn |
/checkban |
审计玩家或 IP 的活跃封禁/IP 封禁状态。 |
/checkban <player/IP> |
staff.checkban |
/staff reload |
无需重启即可实时重新加载配置文件。 |
/staff reload |
staff.staff.reload |
Paper-Only Commands
| 命令 |
描述 |
用法 |
权限节点 |
/vanish |
切换完全隐身状态。 |
/vanish |
staff.vanish |
/invsee |
实时检查玩家的物品栏。 |
/invsee <player> |
staff.invsee |
/monitor |
旁观并平滑跟随一名玩家。 |
/monitor <player/leave> |
staff.monitor |
/fly |
切换玩家飞行模式。 |
/fly [player] |
staff.fly |
/gmc |
切换到创造模式。 |
/gmc [player] |
staff.gmc |
/gms |
切换到生存模式。 |
/gms [player] |
staff.gms |
/gmsp |
切换到旁观者模式。 |
/gmsp [player] |
staff.gmsp |
/gma |
切换到冒险模式。 |
/gma [player] |
staff.gma |
管理员通配符:权限节点 staff.admin 默认授予该插件的所有功能访问权限。
绕过节点:拥有 staff.vanish.see 权限的玩家可以在游戏内、标签列表和命令中看到隐身的玩家。
Installation
Paper Edition (Paper / Purpur / Folia)
- 从 Modrinth 或 GitHub Releases 下载
StaffPlus-Paper-1.2.3.jar。
- 将 JAR 文件放入服务器的
plugins/ 文件夹中。
- 重启服务器。
- 根据需要编辑
plugins/Staff/config.yml 和 plugins/Staff/messages.yml。
Velocity Edition (Proxy)
- 从 Modrinth 或 GitHub Releases 下载
StaffPlus-Velocity-1.2.3.jar。
- 将 JAR 文件放入 Velocity 代理的
plugins/ 文件夹中。
- 重启代理。
- 根据需要编辑
plugins/staffplus/config.yml 和 plugins/staffplus/messages.yml。
- Permissions & Backend Forwarding:
- 如果你在 Velocity 上使用 LuckPerms,请授予工作人员
staff.admin 权限(/lpv user <name> permission set staff.admin true)。
- 如果你仅在后端 Paper 服务器上管理权限和 OP 状态,Staff+ 会自动将在 Velocity 上执行的命令转发到玩家连接的 Paper 服务器(
velocity-forward-to-backend: true),从而让 Paper 无缝评估 LuckPerms 和 OP 状态!
Shared Database (Network Mode)
要在整个网络中共享处罚记录,请配置 两个版本 使用相同的 MySQL 或 MariaDB 数据库:
# config.yml (Paper 和 Velocity 上相同)
storage-type: "mysql" # 或 "mariadb"
mysql-host: "your-db-host"
mysql-port: 3306
mysql-database: "staffplus"
mysql-username: "your-user"
mysql-password: "your-password"
Configuration
该插件使用 Okaeri Config 来生成、验证和自动更新整洁的 YAML 配置结构。两个平台共享相同的配置格式。
config.yml
# 存储类型:SQLITE, MYSQL, 或 MARIADB
storage-type: "sqlite"
# MySQL / MariaDB 连接详情(仅当 storage-type 为 MYSQL 或 MARIADB 时使用)
mysql-host: "localhost"
mysql-port: 3306
mysql-database: "minecraft"
mysql-username: "root"
mysql-password: "password"
mysql-pool-size: 10
mysql-use-ssl: false
# Vanish 设置(仅限 Paper — 在 Velocity 上被忽略)
vanish-silent-container-clicks: true
vanish-ignore-pressure-plates: true
vanish-disable-mob-targeting: true
vanish-disable-item-pickup: true
# 警告升级阶梯设置
warning-ladder-enabled: true
# 当玩家达到特定数量的活跃警告时执行的操作
warning-ladder-actions:
1: "tempmute {player} 1h [Warning Ladder] First warning"
2: "tempmute {player} 12h [Warning Ladder] Second warning"
3: "tempban {player} 3d [Warning Ladder] Reached 3 warnings"
4: "ban {player} [Warning Ladder] Reached 4 warnings"
# Discord Webhook 日志记录设置
discord-webhook-enabled: false
discord-webhook-url: ""
discord-webhook-username: "Staff+ Moderation"
discord-webhook-avatar-url: "https://i.imgur.com/8Qp49X0.png"
# Webhook 嵌入的十六进制颜色代码(不含 #)
discord-webhook-color-ban: "FF5555"
discord-webhook-color-mute: "FFAA00"
discord-webhook-color-warn: "FFFF55"
# 更新检查器设置 (Modrinth)
update-checker-enabled: true
update-checker-notify-admins: true
# 员工封禁排行榜设置
bans-leaderboard-enabled: true
# Velocity 代理设置 (仅限 Velocity)
velocity-proxy-commands: true
velocity-forward-to-backend: true
velocity-disconnect-on-kick: true
messages.yml
完全支持 Adventure MiniMessage,启用华丽的原生文本样式、十六进制颜色和渐变(例如 <gradient:#FF5F6D:#FFC371>Text</gradient>)。
# 所有插件消息的前缀
prefix: "<color:#A0A0A0>[<color:#00E262>Staff+<color:#A0A0A0>] "
no-permission: "<color:#E20000>You do not have permission to execute this command."
player-only: "<color:#E20000>This command can only be executed by a player."
cannot-overwrite-punishment: "<color:#E20000>You cannot override a punishment placed by a higher-ranking staff member ({staff})."
player-allowed: "<color:#00E262>You have allowed {player} to bypass IP bans."
player-allowed-broadcast: "<color:#00E262>{player} has been exempted from IP bans by {sender}."
player-unallowed: "<color:#00E262>You have removed IP ban exemption for {player}."
player-unallowed-broadcast: "<color:#00E262>{player} is no longer exempted from IP bans."
player-not-found: "<color:#E20000>Player '{player}' has not been found or registered."
invalid-duration: "<color:#E20000>Invalid duration format! Use e.g. 1d, 12h, 30m or perm."
# 静音
player-muted: "<color:#00E262>You have muted {player} for {time}. Reason: {reason}"
player-muted-broadcast: "<color:#E2B700>{player} has been muted by {sender} for {time}. Reason: {reason}"
you-are-muted: "<color:#E20000>You are muted! Remaining time: {time}. Reason: {reason}"
# 封禁
player-banned: "<color:#00E262>You have banned {player} for {time}. Reason: {reason}"
player-banned-broadcast: "<color:#E20000>{player} has been banned by {sender} for {time}. Reason: {reason}"
ban-kick-message: "<color:#E20000>You have been banned from the server!\n\nReason: {reason}\nExpiry: {time}"
# 隐身 (仅限 Paper)
vanish-enabled: "<color:#00E262>You are now vanished."
vanish-disabled: "<color:#00E262>You are no longer vanished."
vanish-action-bar: "<color:#00E262>★ YOU ARE VANISHED ★"
构建与编译
Staff+ 是一个多模块 Gradle 项目,生成两个独立的阴影 JAR 文件。
要求
- Java 21 或更高版本
- Gradle (已安装或通过包装器使用)
构建命令
编译并构建两个平台 JAR 文件:
./gradlew clean build
编译后的插件将位于以下位置:
staff-paper/build/libs/StaffPlus-Paper-1.0.0.jar # Paper/Purpur/Folia 服务器
staff-velocity/build/libs/StaffPlus-Velocity-1.0.0.jar # Velocity 代理
项目结构
StaffPlus/
├── staff-core/ # 共享的平台无关库
│ └── src/main/java/ # 数据库、惩罚模型、配置、迁移、工具
├── staff-paper/ # Paper/Folia 后端插件
│ └── src/main/java/ # Paper 命令、监听器、隐身、监控、物品查看
├── staff-velocity/ # Velocity 代理插件
│ └── src/main/java/ # Velocity 命令、登录/聊天监听器
├── build.gradle # 根配置
└── settings.gradle # 多模块声明
注意:Gradle shadow 配置会自动将 eu.okaeri、com.zaxxer.hikari、org.h2 和 org.xerial 库重定位到私有命名空间 (me.ayosynk.staff.libs.*),以防止与类路径上的任何其他插件发生冲突。
持续集成
Staff+ 通过 GitHub Actions 实现了完全自动化的 CI/CD 管道,用于编译、验证和分发两个平台的工件。
开发版本
- 频率: 每当向
master 或 main 分支推送代码时自动构建。
- 发布目标: 发布在 GitHub 上滚动更新的 dev-latest 预发布标签下。
- 滚动策略: 管道会在每次构建时自动覆盖之前的
dev-latest 标签,保持发布页面整洁。
- 工件: 每个发布中都包含
StaffPlus-Paper 和 StaffPlus-Velocity JAR 文件。
稳定版本
- 频率: 每当向仓库推送匹配
v* 语义化 Git 版本标签(例如 v1.0.0)时生成。
- 发布目标: 作为专用的生产版本发布,包含正式的发行说明和两个平台就绪的阴影 JAR 资产。
bStats 指标
Staff+ 的两个版本都集成了 bStats 以收集匿名使用统计信息。这有助于我们了解插件的使用情况并指导未来的开发。
- Paper 版本: 使用
bstats-bukkit 进行服务器端指标收集。
- Velocity 版本: 使用
bstats-velocity (插件 ID: 31693) 进行代理端指标收集。
如果您希望退出匿名指标收集,可以通过导航到服务器或代理上的 plugins/bStats/config.yml 文件并将 enabled 设置为 false 来禁用它。
开发者备注
对于查看 Staff+ 源代码的开发者,以下是架构摘要:
多模块架构
- staff-core:跨平台共享库,包含数据库层、惩罚模型、配置系统、迁移引擎和工具类。使用
ForkJoinPool.commonPool() 处理异步操作——不依赖任何特定平台的调度器。
- staff-paper:实现
StaffPlatform 接口的 Paper/Folia 插件。包含所有 Paper 特有的命令、监听器、隐身(vanish)、监控(monitor)、查看物品栏(invsee)和游戏模式快捷方式。使用符合 Folia 安全标准的区域调度器。
- staff-velocity:实现
StaffPlatform 接口的 Velocity 代理插件。包含代理级别的命令以及用于全网络强制执行的登录/聊天事件监听器。
Folia 线程规则 (Paper)
- 异步传送:切勿在 Folia 上调用
Player#teleport()。始终使用 Player#teleportAsync(),并使用 .thenRun() 或 .thenAccept() 队列化依赖操作。
- 接收者线程安全:动作更新(如
recipient.hidePlayer() 或 recipient.showPlayer())必须在接收者的区域线程上下文中执行。将这些调用包装在 SchedulerUtils.runEntity(plugin, recipient, ...) 中以确保数据包发送。
- 避免跨区块状态读取:在其他区域打开的基于区块的物品栏上调用
open.getHolder() 会引发线程异常。相反,应维护一个内存中的、线程安全的 InvseeSession 对象注册表。
- 电影式跟随阻尼:使用间隔检查(≥4 tick)、速度外推和任务冷却来保持平滑的跟随视角。

Staff+
Staff+ is an enterprise-grade, high-performance moderation and utility plugin built for modern Minecraft networks. It ships as two platform-specific JARs — one for Paper/Purpur/Folia backend servers and one for Velocity proxies — sharing a unified core engine for consistent punishment management across your entire network.
Paper Edition runs on Paper/Purpur/Folia 1.20–1.21+ servers with full Folia multi-threaded region safety, and includes advanced staff tools like vanish, inventory inspection, and spectator monitoring.
Velocity Edition runs on Velocity 3.3.0+ proxies and enforces bans, IP-bans, and mutes at the network gateway before players even reach a backend server.
Both editions share the same database, configs, and migration system — deploy one or both depending on your setup.
Platform Comparison
| Feature |
Paper (Paper/Purpur/Folia) |
Velocity (Proxy) |
| Ban / TempBan / Unban |
✅ |
✅ |
| IP-Ban / TempIP-Ban / UnIP-Ban |
✅ |
✅ |
| Mute / TempMute / Unmute |
✅ |
✅ |
| Warn / Warns / Clear |
✅ |
✅ |
| History / StaffHistory |
✅ |
✅ |
| Staff Rollback |
✅ |
✅ |
IP-Ban Exemption (/staffallow) |
✅ |
✅ |
Punishment Migration (/staffimport) |
✅ |
✅ |
| Discord Webhook Logging |
✅ |
✅ |
| Warning Escalation Ladder |
✅ |
✅ |
| Hierarchy Protection |
✅ |
✅ |
| Alt-Detection (IP Matching) |
✅ |
✅ |
| SQLite / MySQL Storage |
✅ |
✅ |
| Vanish System |
✅ |
❌ |
| Spectator Monitor/Follow |
✅ |
❌ |
Inventory Inspector (/invsee) |
✅ |
❌ |
| Gamemode Shortcuts |
✅ |
❌ |
Flight Toggle (/fly) |
✅ |
❌ |
Global Ban History (/bans) |
✅ |
✅ |
Ban Leaderboard (/bansleaderboard) |
✅ |
✅ |
Kick (/kick) |
✅ |
✅ |
Unwarn (/unwarn) |
✅ |
✅ |
Checkban (/checkban) |
✅ |
✅ |
Live Reload (/staff reload) |
✅ |
✅ |
| Bedrock Geyser Forms |
✅ |
N/A |
| Modrinth Update Notifier |
✅ |
✅ |
| bStats Metrics |
✅ |
✅ |
| Folia Scheduler Safety |
✅ |
N/A |
| Proxy-Level Ban Enforcement |
❌ |
✅ |
| Limbo Kick Prevention |
❌ |
✅ |
| Transparent Backend Command Forwarding |
❌ |
✅ |
Features
Cross-Platform Core
- Shared Database: Both Paper and Velocity editions read and write to the same punishment database (SQLite or MySQL), enabling seamless network-wide moderation.
- Shared Configs:
config.yml and messages.yml use identical formats on both platforms via the Okaeri configuration framework.
- Unified Migration Engine: Import punishments from 7+ plugins on either platform.
Folia Safety (Paper Edition)
- Asynchronous Lifecycles: All commands, database transactions, and packet actions run on Folia-compliant regional or asynchronous schedulers.
- Folia Teleportation Safety: Standard teleports are replaced with safe, non-blocking
teleportAsync futures, completely preventing thread crashes.
- Isolated Packet Loops: Visually toggling features (like Vanish hide/show packets) are scheduled on each recipient's specific regional thread, guaranteeing thread-safety.
Proxy Gateway Enforcement (Velocity Edition)
- Pre-Login Ban Check: Intercepts login attempts at the proxy level and rejects banned players before they reach any backend server.
- Network-Wide Mute Filter: Blocks chat messages from muted players across all connected servers.
- IP-Ban Gateway: Enforces IP bans at the proxy gateway, preventing banned IPs from connecting to any server in the network.
Vanish (Paper Only)
- Total Invisibility: Completely removes the player from the online count, player ping lists, tab completions, and visible lists.
- Physical Interaction Bypass: Vanished staff bypass physical pressure plates and tripwire triggers entirely.
- Silent Containers: Allows opening chest, furnace, and barrel interfaces silently without triggering container animations or audio.
- Stealth Suppression: Prevents mob targeting, item pickups, and suppresses join/quit messages entirely while active.
- Visual Action Bar Indicator: Real-time HUD showing vanished status via safe asynchronous repeating tasks.
Moderation (Both Platforms)
- Comprehensive Actions: Integrated
/ban, /tempban, /ip-ban, /tempip-ban, /mute, /tempmute, and /warn.
- Warning Profiles: Track individual warning logs via
/warns <player> [list/clear].
- Dynamic Time Parsing: Sophisticated time parser supporting complex units (e.g.
1d, 12h, 45m) and infinite duration mappings (perm).
- Relational Storage: Backed by a high-performance database manager supporting both local SQLite databases and remote MySQL servers, managed via a shaded, thread-safe HikariCP connection pool.
- Linked Account Alt-Detection: On player login, automatically scans, logs, and broadcasts alternate accounts sharing the IP address, color-coding active (green) and banned (red) profiles.
- Dynamic Command & History Parity: Multi-threaded
/history <player>, /staffhistory <staff>, and /staffrollback <staff> commands supported by dynamic database-backed name tab completions.
- Warning Escalation Ladder: Scale punishments dynamically (e.g. tempmutes scaling to permanent bans) based on active warning levels. Command dispatches execute safely on each platform's native scheduler.
- Non-Blocking Discord Webhook Logs: Real-time embeds logging all mute, ban, and warning dispatches using modern non-blocking Java 21
HttpClient interfaces with zero impact on region ticks.
- Administrative Overwrite Hierarchy Protection: Custom staff weight ranks (
staff.hierarchy.weight.<number>) blocking junior staff from overriding, deactivating, or removing punishments placed by senior administrators or the Console (Integer.MAX_VALUE).
- IP-Ban Exemption Bypass: Whitelist specific accounts (
/staffallow) to connect and bypass active IP-bans without lifting the IP ban itself for other accounts sharing the IP.
Punishment Importer & Migration (Both Platforms)
- 7 Supported Platforms: Seamlessly import mutes, bans, warnings, and IP bans from:
- Vanilla Minecraft: Direct imports from
banned-players.json and banned-ips.json in the server root.
- Essentials / EssentialsX: Automated scans of mutes and bans in user profiles under
plugins/Essentials/userdata/*.yml.
- LiteBans: Migrates bans, mutes, and warnings from H2/SQLite/MySQL databases. Supports auto-detection of the
litebans.mv.db H2 file or manual JDBC parameters.
- AdvancedBan: Integrates and normalizes legacy SQL
Punishments tables from SQLite or MySQL.
- MaxBans: Migration of bans, IP bans, mutes, and warnings from SQLite or MySQL.
- BanManager: Integrates historical player bans, mutes, and warnings with configurable table prefixes.
- BungeeAdminTools (BAT): Imports entries from database tables
bat_ban and bat_mute.
- Dynamic Auto-Scanning: Scans your server's active files on command, extracts SQLite paths or remote SQL database credentials, and allows zero-configuration migrations.
- Batch Operations: Commits imported records inside a single transaction using batch inserts, migrating thousands of records instantly.
- Non-Blocking Futures: Runs connection setups, configuration decodes, and database commits fully asynchronously on non-blocking thread pools.
Spectator Follow (Paper Only)
- Cinematic Camera Tracking: Teleports staff in spectator mode to follow the target seamlessly.
- Velocity-Predicted Follow: Computes target movements and velocity vectors (
target.getVelocity()) to position the camera slightly ahead of the target, eliminating stutter and rubber-banding.
- Throttled Teleports: Auto-updates run at a throttled 4-tick (200ms) interval with a 400ms cooldown, giving client-side predicted movements and Paper's async teleportation futures time to fully resolve.
- Configurable Boundary Tether: Allows staff to orbit or move freely within a 10-block radius. Going beyond the boundary gently tethers the camera back into offset.
Inventory Inspector (Paper Only)
- 54-Slot Live GUI: View and edit target players' main inventories (0-35), armor slots (helmet, chestplate, leggings, boots), off-hand items, and stats.
- Live Stats & Shortcuts:
- Golden Apple: Displays health, food levels, and experience dynamically.
- Potion Bottle: Shows a live list of active potion effects and durations.
- Ender Chest: Quick-access shortcut item to inspect their Ender Chest directly.
- Unparalleled Folia Safety: Completely avoids asynchronous block-state reads (which crash under Folia when querying
.getOpenInventory().getTopInventory().getHolder() on block-based inventories in other regions). Instead, it implements a thread-safe custom session registry that cleanly tracks active inspect views and propagates updates regionally.
Shortcuts (Paper Only)
- Instant Gamemode Shifts: Rapid commands including creative (
/gmc), survival (/gms), spectator (/gmsp), and adventure (/gma).
- Flight Mode: Seamless command flight toggles via
/fly.
Commands & Permissions
Network-Wide Commands (Paper & Velocity)
| Command |
Description |
Usage |
Permission Node |
/ban |
Bans a player from the server. |
/ban <player> [reason] |
staff.ban |
/tempban |
Temporarily bans a player. |
/tempban <player> <duration> [reason] |
staff.tempban |
/unban |
Unbans a player. |
/unban <player> |
staff.unban |
/ip-ban |
IP-bans a player. |
/ip-ban <player> [reason] |
staff.ipban |
/tempip-ban |
Temporarily IP-bans a player. |
/tempip-ban <player> <duration> [reason] |
staff.tempipban |
/unip-ban |
Unbans an IP address or player. |
/unip-ban <player/IP> |
staff.unipban |
/mute |
Mutes a player in chat. |
/mute <player> [reason] |
staff.mute |
/tempmute |
Temporarily mutes a player. |
/tempmute <player> <duration> [reason] |
staff.tempmute |
/unmute |
Unmutes a player. |
/unmute <player> |
staff.unmute |
/warn |
Warns a player. |
/warn <player> [reason] |
staff.warn |
/warns |
View or clear warning history. |
/warns <player> [list/clear] |
staff.warns |
/history |
View complete punishment logs (active/inactive) for players. |
/history <player> |
staff.history |
/staffhistory |
View all punishments issued by a staff member. |
/staffhistory <staff> |
staff.staffhistory |
/staffrollback |
Rollback all active punishments placed by a staff member. |
/staffrollback <staff> [confirm] |
staff.staffrollback |
/staffallow |
Exempt a player/UUID from active IP bans. |
/staffallow <player> [remove] |
staff.staffallow |
/staffimport |
Import punishments from other plugins. |
/staffimport <source> [params...] |
staff.import |
/bans |
View recent server bans (GUI / Geyser Form / Chat). |
/bans [page] [--chat] |
staff.bans |
/bansleaderboard |
View staff leaderboard by bans issued. |
/bansleaderboard [--chat] |
staff.bansleaderboard |
/kick |
Kick an online player with hierarchy validation. |
/kick <player> [reason] |
staff.kick |
/unwarn |
Remove a player's latest or specific warning. |
/unwarn <player> [id] |
staff.unwarn |
/checkban |
Audit active ban/IP-ban status of player or IP. |
/checkban <player/IP> |
staff.checkban |
/staff reload |
Reload configuration files live without restart. |
/staff reload |
staff.staff.reload |
Paper-Only Commands
| Command |
Description |
Usage |
Permission Node |
/vanish |
Toggle complete invisibility. |
/vanish |
staff.vanish |
/invsee |
Inspect a player's inventory live. |
/invsee <player> |
staff.invsee |
/monitor |
Spectate and smoothly follow a player. |
/monitor <player/leave> |
staff.monitor |
/fly |
Toggle player flight. |
/fly [player] |
staff.fly |
/gmc |
Switch to creative mode. |
/gmc [player] |
staff.gmc |
/gms |
Switch to survival mode. |
/gms [player] |
staff.gms |
/gmsp |
Switch to spectator mode. |
/gmsp [player] |
staff.gmsp |
/gma |
Switch to adventure mode. |
/gma [player] |
staff.gma |
Admin Wildcard: The permission node staff.admin grants access to all capabilities of the plugin by default.
Bypass Node: Players with the permission staff.vanish.see can see vanished players in-game, in tab lists, and in commands.
Installation
Paper Edition (Paper / Purpur / Folia)
- Download
StaffPlus-Paper-1.2.3.jar from Modrinth or GitHub Releases.
- Place the JAR in your server's
plugins/ folder.
- Restart your server.
- Edit
plugins/Staff/config.yml and plugins/Staff/messages.yml to your liking.
Velocity Edition (Proxy)
- Download
StaffPlus-Velocity-1.2.3.jar from Modrinth or GitHub Releases.
- Place the JAR in your Velocity proxy's
plugins/ folder.
- Restart your proxy.
- Edit
plugins/staffplus/config.yml and plugins/staffplus/messages.yml to your liking.
- Permissions & Backend Forwarding:
- If you use LuckPerms on Velocity, grant staff
staff.admin (/lpv user <name> permission set staff.admin true).
- If you manage permissions and OPs exclusively on your backend Paper servers, Staff+ automatically forwards commands executed on Velocity down to the player's connected Paper server (
velocity-forward-to-backend: true), allowing Paper to evaluate LuckPerms and OP status seamlessly!
Shared Database (Network Mode)
To share punishments across your entire network, configure both editions to use the same MySQL or MariaDB database:
# config.yml (same on both Paper and Velocity)
storage-type: "mysql" # or "mariadb"
mysql-host: "your-db-host"
mysql-port: 3306
mysql-database: "staffplus"
mysql-username: "your-user"
mysql-password: "your-password"
Configuration
The plugin uses Okaeri Config to generate, validate, and auto-update clean YAML configuration structures. Both platforms share identical configuration formats.
config.yml
# Storage type: SQLITE, MYSQL, or MARIADB
storage-type: "sqlite"
# MySQL / MariaDB Connection Details (only used if storage-type is MYSQL or MARIADB)
mysql-host: "localhost"
mysql-port: 3306
mysql-database: "minecraft"
mysql-username: "root"
mysql-password: "password"
mysql-pool-size: 10
mysql-use-ssl: false
# Vanish settings (Paper only — ignored on Velocity)
vanish-silent-container-clicks: true
vanish-ignore-pressure-plates: true
vanish-disable-mob-targeting: true
vanish-disable-item-pickup: true
# Warning escalation ladder settings
warning-ladder-enabled: true
# Actions to run when a player reaches a specific number of active warnings
warning-ladder-actions:
1: "tempmute {player} 1h [Warning Ladder] First warning"
2: "tempmute {player} 12h [Warning Ladder] Second warning"
3: "tempban {player} 3d [Warning Ladder] Reached 3 warnings"
4: "ban {player} [Warning Ladder] Reached 4 warnings"
# Discord Webhook logging settings
discord-webhook-enabled: false
discord-webhook-url: ""
discord-webhook-username: "Staff+ Moderation"
discord-webhook-avatar-url: "https://i.imgur.com/8Qp49X0.png"
# Hex color codes for webhook embeds (without the #)
discord-webhook-color-ban: "FF5555"
discord-webhook-color-mute: "FFAA00"
discord-webhook-color-warn: "FFFF55"
# Update Checker settings (Modrinth)
update-checker-enabled: true
update-checker-notify-admins: true
# Staff Ban Leaderboard settings
bans-leaderboard-enabled: true
# Velocity Proxy Settings (Velocity only)
velocity-proxy-commands: true
velocity-forward-to-backend: true
velocity-disconnect-on-kick: true
messages.yml
Features full Adventure MiniMessage compatibility, enabling gorgeous native text styling, hex colors, and gradients (e.g. <gradient:#FF5F6D:#FFC371>Text</gradient>).
# Prefix for all plugin messages
prefix: "<color:#A0A0A0>[<color:#00E262>Staff+<color:#A0A0A0>] "
no-permission: "<color:#E20000>You do not have permission to execute this command."
player-only: "<color:#E20000>This command can only be executed by a player."
cannot-overwrite-punishment: "<color:#E20000>You cannot override a punishment placed by a higher-ranking staff member ({staff})."
player-allowed: "<color:#00E262>You have allowed {player} to bypass IP bans."
player-allowed-broadcast: "<color:#00E262>{player} has been exempted from IP bans by {sender}."
player-unallowed: "<color:#00E262>You have removed IP ban exemption for {player}."
player-unallowed-broadcast: "<color:#00E262>{player} is no longer exempted from IP bans."
player-not-found: "<color:#E20000>Player '{player}' has not been found or registered."
invalid-duration: "<color:#E20000>Invalid duration format! Use e.g. 1d, 12h, 30m or perm."
# Mutes
player-muted: "<color:#00E262>You have muted {player} for {time}. Reason: {reason}"
player-muted-broadcast: "<color:#E2B700>{player} has been muted by {sender} for {time}. Reason: {reason}"
you-are-muted: "<color:#E20000>You are muted! Remaining time: {time}. Reason: {reason}"
# Bans
player-banned: "<color:#00E262>You have banned {player} for {time}. Reason: {reason}"
player-banned-broadcast: "<color:#E20000>{player} has been banned by {sender} for {time}. Reason: {reason}"
ban-kick-message: "<color:#E20000>You have been banned from the server!\n\nReason: {reason}\nExpiry: {time}"
# Vanish (Paper only)
vanish-enabled: "<color:#00E262>You are now vanished."
vanish-disabled: "<color:#00E262>You are no longer vanished."
vanish-action-bar: "<color:#00E262>★ YOU ARE VANISHED ★"
Build & Compilation
Staff+ is a multi-module Gradle project producing two independent shaded JARs.
Requirements
- Java 21 or higher
- Gradle (installed or via wrapper)
Build Command
Compile and build both platform JARs:
./gradlew clean build
The compiled plugins will be located at:
staff-paper/build/libs/StaffPlus-Paper-1.0.0.jar # Paper/Purpur/Folia servers
staff-velocity/build/libs/StaffPlus-Velocity-1.0.0.jar # Velocity proxies
Project Structure
StaffPlus/
├── staff-core/ # Shared platform-agnostic library
│ └── src/main/java/ # Database, Punishment model, Configs, Migration, Utils
├── staff-paper/ # Paper/Folia backend plugin
│ └── src/main/java/ # Paper commands, listeners, vanish, monitor, invsee
├── staff-velocity/ # Velocity proxy plugin
│ └── src/main/java/ # Velocity commands, login/chat listeners
├── build.gradle # Root configuration
└── settings.gradle # Multi-module declaration
Note: The Gradle shadow configuration automatically relocates eu.okaeri, com.zaxxer.hikari, org.h2, and org.xerial libraries to private namespaces (me.ayosynk.staff.libs.*) to prevent conflicts with any other plugins on the classpath.
Continuous Integration
Staff+ implements a fully automated CI/CD pipeline via GitHub Actions to compile, validate, and distribute artifacts for both platforms.
Dev Builds
- Frequency: Built automatically on every
push to the master or main branches.
- Release Target: Published under the rolling dev-latest pre-release tag on GitHub.
- Rolling Policy: The pipeline automatically overwrites the previous
dev-latest tag on every build, maintaining a clean releases page.
- Artifacts: Both
StaffPlus-Paper and StaffPlus-Velocity JARs are published in every release.
Stable Releases
- Frequency: Generated whenever a semantic Git version tag matching
v* (e.g., v1.0.0) is pushed to the repository.
- Release Target: Published as a dedicated production release containing formal release notes and both platform-ready shaded JAR assets.
bStats Metrics
Both editions of Staff+ integrate with bStats to collect anonymous usage statistics. This helps us understand how the plugin is being used and guides future development.
- Paper Edition: Uses
bstats-bukkit for server-side metrics.
- Velocity Edition: Uses
bstats-velocity (Plugin ID: 31693) for proxy-side metrics.
If you wish to opt-out of anonymous metrics collection, you can disable it by navigating to the plugins/bStats/config.yml file on your server or proxy and setting enabled: false.
Developer Notes
For developers looking at the source code of Staff+, here is a summary of the architecture:
Multi-Module Architecture
- staff-core: Platform-agnostic shared library containing the database layer, punishment model, config system, migration engine, and utility classes. Uses
ForkJoinPool.commonPool() for async operations — no platform-specific scheduler dependencies.
- staff-paper: Paper/Folia plugin implementing
StaffPlatform interface. Contains all Paper-specific commands, listeners, vanish, monitor, invsee, and gamemode shortcuts. Uses Folia-safe regional schedulers.
- staff-velocity: Velocity proxy plugin implementing
StaffPlatform interface. Contains proxy-level commands and login/chat event listeners for network-wide enforcement.
Folia Threading Rules (Paper)
- Async Teleportation: Never call
Player#teleport() on Folia. Always use Player#teleportAsync() and queue dependent actions using .thenRun() or .thenAccept().
- Recipient Thread Safety: Action updates (like
recipient.hidePlayer() or recipient.showPlayer()) must execute on the recipient's regional thread context. Wrap these calls in SchedulerUtils.runEntity(plugin, recipient, ...) to guarantee packet delivery.
- Avoid cross-region block state reads: Calling
open.getHolder() on block-based inventories open in other regions throws threading exceptions. Instead, maintain an in-memory, thread-safe registry of InvseeSession objects.
- Cinematic Follow Damping: Use interval checking (≥4 ticks), velocity extrapolation, and a task cooldown to maintain smooth follower views.
评论 0
登录后参与评分
还没有评论,来抢沙发吧