Admin Toolkit

插件

· 作者 everett2323

一款功能丰富的管理员工具包。

0 本站下载 0 关注 更新于 4 个月前

最新 1.3 · 1.21.11 · Paper / Purpur

一键开服(送7天)

开发者须知: 正在构建配套或扩展插件?请滚动至本文档底部的开发者专区,以获取完整的 API 规范、GUI 挂钩标题和运行时生命周期钩子。

AdminToolkitPlugin

AdminToolkit 是一款面向 Paper(Minecraft 1.21.1)的全面服务器管理插件。它通过单一命令触发一个精致的图形用户界面(GUI),允许管理员无需记忆复杂命令即可管理世界属性、玩家行为和个人设置。

功能特性

集中式管理 GUI

  • 主命令: 通过 /admin 命令访问所有工具。
  • 快速导航: 使用带有标签补全功能的 /admin [player] 直接跳转到特定玩家的操作菜单。

世界管理

  • 时间控制: 即时切换白天和黑夜。
  • 天气控制: 在晴朗、下雨和暴风雨之间切换。
  • 维护模式: 切换服务器访问权限;启用时仅管理员可以加入。
  • 全局操作: 将所有玩家传送回出生点或发送全服广播消息。
  • 聊天管理: 清空全局聊天或开启全局静音以停止所有非管理员聊天。

玩家管理

  • 惩罚: 击杀、踢出和封禁,支持预设或自定义理由。
  • 控制: 冻结/解冻移动以及天罚(闪电打击)。
  • 实用工具: 查看物品栏、末影箱、传送至玩家或将玩家传送到你身边。
  • 消息传递: 通过 GUI 向玩家发送直接的管理员消息。
  • 权限: 直接管理玩家的 OP 状态或使用虚假 OP恶作剧。
  • 游戏模式: 将特定玩家设置为生存、创造、冒险或旁观者模式。
  • 历史记录: 查看玩家的透视历史以查看本会话中挖掘的所有珍贵矿石。
  • 恢复: 即时治疗、喂食或饥饿玩家,用于测试或管理目的。

反作弊系统

  • 透视警报: 实时全局监控可疑的挖掘活动。
  • 追踪矿石: 完全可定制的菜单,选择哪些方块(钻石、远古残骸等)会触发警报。
  • 交互式通知: 聊天警报可点击;点击警报可立即打开挖掘者的透视历史和坐标。

自我管理

  • 游戏模式: 快速在生存、创造、冒险和旁观者模式之间切换。
  • 隐身模式: 对其他玩家完全不可见。
  • 管理必备: 自我治疗和自我喂食。

系统与持久化

  • 实时健康监控: 在 GUI 内实时跟踪 TPS 和内存使用情况。
  • 智能持久化: 维护模式、全局静音、隐身、冻结和追踪矿石设置会在服务器重启后自动保存并恢复。

安装与使用

  1. 从 Releases 页面下载最新的 JAR 文件(或自行编译)。
  2. 将 JAR 文件放入 Paper 服务器的 plugins/ 文件夹中。
  3. 重启服务器。
  4. 在游戏中使用 /admin 打开工具箱。

权限

  • admintoolkit.admin: 需要此权限才能使用所有管理功能(默认为 OP)。

开发

前置要求

  • Java 21
  • Gradle

技术细节

  • 平台: Paper API (1.21.1)
  • 文本引擎: Adventure API (基于组件)
  • 构建系统: Gradle (Kotlin DSL)

开发者专区(配套与扩展 API 参考)

本节记录了配套或扩展插件集成到 AdminToolkitPlugin 所需了解的一切内容,无需阅读其源代码。

  • 目标要求: Paper 1.21.x | Java 21
  • 主类: org.codingdude1234.AdminPlugin.adminToolkit.AdminToolkit
  • 插件名称(在 plugin.yml 中): AdminToolkitPlugin

1. 公共 Java API(用于向 GUI 注入按钮)

AdminToolkit 在包 org.codingdude1234.AdminPlugin.adminToolkit.api 下暴露了一个小型公共 API。

该 API 允许配套插件在这些菜单中添加自己的按钮:

  • AdminMenu.MAIN → "Admin Toolkit" (9 个槽位)
  • AdminMenu.WORLD → "World Properties" (27 个槽位)
  • AdminMenu.SELF → "Self Properties" (27 个槽位)
  • AdminMenu.ANTI_CHEAT → "Anti-Cheat Controls" (27 个槽位)
  • AdminMenu.PLAYER_ACTION → "Action: <playerName>" (45 个槽位)

最小示例

AdminToolkitAPI api = AdminToolkitAPI.get();
if (api != null) {
    api.registerButton(AdminMenu.PLAYER_ACTION,
        CustomButton.builder(this, "warn")
            .material(Material.YELLOW_WOOL)
            .displayName("Warn Player")
            .lore("Sends a warning to this player")
            .slot(-1)                           // -1 = 第一个可用槽位
            .permission("mywarn.use")           // 可选
            .onClick(ctx -> {
                Player target = ctx.target(); // 在 PLAYER_ACTION 中不为空
                if (target != null) target.sendMessage("You have been warned!");
            })
            .build());
}

行为详情

  • 渲染: 每次打开菜单时都会渲染按钮。
  • 权限: 如果设置了 .permission(...),缺乏该权限的玩家将看不到该按钮,且未授权玩家的点击将被拒绝。
  • 槽位: .slot(int) 选择固定槽位;如果该槽位已被内置物品占用,则该次渲染时跳过此按钮。.slot(-1) 自动放置到第一个空槽位。
  • 点击处理: 在你的处理程序运行之前,点击事件会自动被取消。
  • 生命周期: 当你的插件禁用时,其所有按钮都会自动移除。
  • 唯一性: (所有者插件名称, 按钮 ID) 对是唯一的。使用相同的对重新注册将替换现有按钮。

限制(当前 API 未暴露的内容)

  • 读取隐身/冻结/透视状态。
  • AdminToolkit 触发的自定义事件。
  • 添加全新的顶级子菜单 (变通方法:在 AdminMenu.MAIN 上注册一个按钮,其 onClick 打开你自己的 Inventory)。

2. 命令形式与子命令

这里恰好有一个基础命令:/admin

  • /admin → 打开主 GUI 菜单。
  • /admin <在线玩家名称> → 直接为该玩家打开玩家操作 GUI。
  • /admin xrayhistory <玩家名称> → 为该玩家打开 X-Ray 历史 GUI(对离线玩家也有效)。

Tab 补全会建议第一个参数的在线玩家名称。

3. 权限(完整参考列表)

通配符式父级权限(授予所有子权限)

  • admintoolkit.admin → 授予其下所有权限 + 使用权限 + maintenance.bypass
  • admintoolkit.worldproperties → 所有 admintoolkit.worldproperties.*
  • admintoolkit.playermanagement → 所有 admintoolkit.playermanagement.*
  • admintoolkit.selfmanagement → 所有 admintoolkit.selfmanagement.*
  • admintoolkit.anticheat → 所有 admintoolkit.anticheat.*

独立权限

权限 描述 默认值
admintoolkit.use 打开 /admin 主菜单。 op
admintoolkit.protected 玩家无法通过工具包被踢出或封禁。 op
admintoolkit.maintenance.bypass 维护模式开启时,玩家可以加入服务器。 op
admintoolkit.viewhealth 在主菜单中显示服务器健康状态项。 未定义

子类别权限

  • 世界属性 (admintoolkit.worldproperties.*): setday, setnight, teleportall, clearweather, setrain, setstorm, broadcast, maintenance, clearchat, globalmute
  • 玩家管理 (admintoolkit.playermanagement.*): kill, kick, ban, freeze, gamemode, message, impersonate, heal, feed, starve, smite, fakeop, op, deop, invsee, endersee, info, teleportto, bring, xrayhistory
  • 自我管理 (admintoolkit.selfmanagement.*): gamemode, heal, vanish, changename
  • 反作弊 (admintoolkit.anticheat.*):
    • alerts → 切换 X-Ray 警报并接收警报消息。
    • trackedores → 可编辑被追踪的矿石种类。

4. GUI 菜单标题(用于手动点击与挂钩)

AdminToolkit 通过库存**标题(纯文本)**来识别菜单。如果你想手动进行挂钩,请注册一个优先级在 AdminToolkit 之后(HIGH 或更高)的 InventoryClickEvent 监听器,并匹配以下字符串:

静态标题

  • 主菜单: "Admin Toolkit"
  • 世界属性: "World Properties"
  • 自身属性: "Self Properties"
  • 在线玩家列表: "Online Players"
  • 反作弊: "Anti-Cheat Controls"
  • 矿石选择: "Select Tracked Ores"

前缀动态标题(匹配 startsWith)

  • "Action: <playerName>" → 玩家操作菜单。
  • "Reason: Kick <player>" 或 "Reason: Ban <player>" → 惩罚原因选择器。
  • "Gamemode: <playerName>" → 目标玩家的模式选择器。
  • "X-Ray History: <playerName>" → X 光挖矿记录查看器。

5. 聊天驱动的输入拦截

某些 GUI 操作需要文本聊天输入。AdminToolkit 以 LOWEST 优先级监听 Paper 的 AsyncChatEvent,并在设置以下内部标志时取消该事件:

  • Broadcast / Message → 将文本处理为格式化服务器警报或直接管理员文本。
  • ChangeName → 更改管理员的显示名称 (输入 'reset' 可清除它)。
  • Kick / Ban → 将文本用作自定义理由。

扩展说明: 如果您的插件处理聊天触发器,请确保它在 NORMAL 或更高优先级上尊重 event.isCancelled()。

6. 配置文件架构与实时状态

  • 路径: plugins/AdminToolkitPlugin/config.yml

保存的持久化键(关闭时写入 / 启动时读取)

maintenance-mode: boolean
chat-muted: boolean
xray-alerts: boolean
tracked-ores: # Material 枚举名称列表(例如 DIAMOND_ORE)
vanished-players: # UUID 字符串列表
frozen-players: # UUID 字符串列表

注意:X 光日志、活动的玩家伪装和待处理的聊天输入仅存在于内存中,重启后会丢失。

实时状态安全模式

Plugin at = Bukkit.getPluginManager().getPlugin("AdminToolkitPlugin");
FileConfiguration cfg = ((JavaPlugin) at).getConfig();
boolean maintenance = cfg.getBoolean("maintenance-mode");

[!WARNING] 运行时配置值可能已过时,因为状态转换仅在 onDisable() 时刷新。要获取准确的运行时状态更新,请直接跟踪底层 Bukkit 事件。

7. 核心运行时钩子与事件交互

  • 隐身(Vanish): 通过 player.hidePlayer(plugin, target) 处理。由于 AdminToolkit 未动态暴露其隐藏玩家列表,需通过标准的隐藏/显示调用进行追踪。
  • 冻结(Freeze): 通过拦截 PlayerMoveEvent 实现。伴生逻辑应尊重此取消状态。
  • 维护模式(Maintenance Mode): 除非玩家持有 admintoolkit.maintenance.bypass 权限,否则禁止登录(通过 PlayerLoginEvent 拦截)。
  • 全局聊天禁言(Global Chat Mute): 对于缺乏 admintoolkit.admin 权限的所有用户,以 LOWEST 优先级取消 AsyncChatEvent。
  • 透视警报(X-Ray Alerts): 追踪匹配 tracked-ores 字符串列表中材质的 BlockBreakEvent,并向持有 admintoolkit.anticheat.alerts 权限的节点发送通知。
  • 冒充(Impersonation): 取消管理员的消息并触发 target.chat(text)。这将创建一个全新的 AsyncChatEvent,其中发送者身份被更改为目标玩家。
  • 惩罚保护(Punishment Protection): 如果目标玩家解析出 admintoolkit.protected 权限,则绕过由工具包实例化的 GUI 封禁/踢出操作。(注意:这不会阻止核心的原生 /ban 或 /kick 来源上下文)。

8. 依赖配置

添加到您的伴生插件 plugin.yml 中:

name: MyCompanionPlugin
main: org.example.MyCompanionPlugin
api-version: '1.21'
depend: [AdminToolkitPlugin] # 硬依赖
# 或使用:softdepend: [AdminToolkitPlugin]

初始化保护代码:

Plugin at = Bukkit.getPluginManager().getPlugin("AdminToolkitPlugin");
if (at != null && at.isEnabled()) {
    // 在此安全地调用钩子或 API 按钮
}

由 Paper Minecraft 管理员为 Paper Minecraft 创建。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源