开发者须知: 正在构建配套或扩展插件?请滚动至本文档底部的开发者专区,以获取完整的 API 规范、GUI 挂钩标题和运行时生命周期钩子。
AdminToolkitPlugin
AdminToolkit 是一款面向 Paper(Minecraft 1.21.1)的全面服务器管理插件。它通过单一命令触发一个精致的图形用户界面(GUI),允许管理员无需记忆复杂命令即可管理世界属性、玩家行为和个人设置。
功能特性
集中式管理 GUI
- 主命令: 通过
/admin 命令访问所有工具。
- 快速导航: 使用带有标签补全功能的
/admin [player] 直接跳转到特定玩家的操作菜单。
世界管理
- 时间控制: 即时切换白天和黑夜。
- 天气控制: 在晴朗、下雨和暴风雨之间切换。
- 维护模式: 切换服务器访问权限;启用时仅管理员可以加入。
- 全局操作: 将所有玩家传送回出生点或发送全服广播消息。
- 聊天管理: 清空全局聊天或开启全局静音以停止所有非管理员聊天。
玩家管理
- 惩罚: 击杀、踢出和封禁,支持预设或自定义理由。
- 控制: 冻结/解冻移动以及天罚(闪电打击)。
- 实用工具: 查看物品栏、末影箱、传送至玩家或将玩家传送到你身边。
- 消息传递: 通过 GUI 向玩家发送直接的管理员消息。
- 权限: 直接管理玩家的 OP 状态或使用虚假 OP恶作剧。
- 游戏模式: 将特定玩家设置为生存、创造、冒险或旁观者模式。
- 历史记录: 查看玩家的透视历史以查看本会话中挖掘的所有珍贵矿石。
- 恢复: 即时治疗、喂食或饥饿玩家,用于测试或管理目的。
反作弊系统
- 透视警报: 实时全局监控可疑的挖掘活动。
- 追踪矿石: 完全可定制的菜单,选择哪些方块(钻石、远古残骸等)会触发警报。
- 交互式通知: 聊天警报可点击;点击警报可立即打开挖掘者的透视历史和坐标。
自我管理
- 游戏模式: 快速在生存、创造、冒险和旁观者模式之间切换。
- 隐身模式: 对其他玩家完全不可见。
- 管理必备: 自我治疗和自我喂食。
系统与持久化
- 实时健康监控: 在 GUI 内实时跟踪 TPS 和内存使用情况。
- 智能持久化: 维护模式、全局静音、隐身、冻结和追踪矿石设置会在服务器重启后自动保存并恢复。
安装与使用
- 从 Releases 页面下载最新的 JAR 文件(或自行编译)。
- 将 JAR 文件放入 Paper 服务器的
plugins/ 文件夹中。
- 重启服务器。
- 在游戏中使用
/admin 打开工具箱。
权限
admintoolkit.admin: 需要此权限才能使用所有管理功能(默认为 OP)。
开发
前置要求
技术细节
- 平台: 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 创建。
DEVELOPER NOTICE: Building a companion or extension plugin? Scroll down to the Developer Area at the bottom of this document for full API specifications, GUI hook titles, and runtime lifecycle hooks.
AdminToolkitPlugin
AdminToolkit is a comprehensive server administration plugin for Paper (Minecraft 1.21.1). It provides a sleek graphical user interface (GUI) triggered by a single command, allowing administrators to manage world properties, player actions, and personal settings without memorizing complex commands.
Features
Centralized Admin GUI
- Main Command: Access all tools via the
/admin command.
- Quick Navigation: Use
/admin [player] with tab-completion to jump directly to a specific player's action menu.
World Management
- Time Control: Instantly switch between Day and Night.
- Weather Control: Toggle between Clear, Rain, and Storm.
- Maintenance Mode: Toggle server access; only admins can join when active.
- Global Actions: Teleport all players to spawn or send server-wide broadcast messages.
- Chat Management: Clear global chat or toggle a Global Mute to stop all non-admin chat.
Player Management
- Punishments: Kill, Kick, and Ban with predefined or custom reason support.
- Control: Freeze/Unfreeze movement and Smite (lightning strike).
- Utility: View inventories, Ender Chests, Teleport to players, or Bring players to you.
- Messaging: Send direct admin messages to players via the GUI.
- Permissions: Manage player OP status directly or use the Fake OP prank.
- Gamemode: Set specific players to Survival, Creative, Adventure, or Spectator.
- History: View a player's X-Ray History to see all valuable ores mined this session.
- Restoration: Instantly Heal, Feed, or Starve players for testing/admin purposes.
Anti-Cheat System
- X-Ray Alerts: Real-time, global monitoring for suspicious mining activity.
- Tracked Ores: Fully customizable menu to select exactly which blocks (Diamonds, Ancient Debris, etc.) trigger alerts.
- Interactive Notifications: Chat alerts are clickable; clicking an alert instantly opens the mining player's X-Ray history and coordinates.
Self Management
- Gamemode: Quickly toggle between Survival, Creative, Adventure, and Spectator.
- Vanish Mode: Become completely invisible to other players on the server.
- Admin Essentials: Self-heal and self-feed.
System & Persistence
- Live Health Monitor: Real-time TPS and Memory usage tracking within the GUI.
- Smart Persistence: Maintenance mode, Global Mute, Vanish, Freeze, and Tracked Ore settings are automatically saved and restored across server restarts.
Installation & Usage
- Download the latest JAR from the Releases page (or build it yourself).
- Place the JAR in your Paper server's
plugins/ folder.
- Restart your server.
- Use
/admin in-game to open the toolkit.
Permissions
admintoolkit.admin: Required for all admin features (defaults to OP).
Development
Prerequisites
Technical Details
- Platform: Paper API (1.21.1)
- Text Engine: Adventure API (Component-based)
- Build System: Gradle (Kotlin DSL)
Developer Area (Companion & Extension API Reference)
This section documents everything a companion or extension plugin needs to know to integrate with AdminToolkitPlugin without reading its source code.
- Target Requirements: Paper 1.21.x | Java 21
- Main Class:
org.codingdude1234.AdminPlugin.adminToolkit.AdminToolkit
- Plugin Name (in
plugin.yml): AdminToolkitPlugin
1. Public Java API (For Injecting Buttons Into The GUI)
AdminToolkit exposes a small public API under the package: org.codingdude1234.AdminPlugin.adminToolkit.api
The API lets a companion plugin add its own buttons to any of these menus:
AdminMenu.MAIN → "Admin Toolkit" (9 slots)
AdminMenu.WORLD → "World Properties" (27 slots)
AdminMenu.SELF → "Self Properties" (27 slots)
AdminMenu.ANTI_CHEAT → "Anti-Cheat Controls" (27 slots)
AdminMenu.PLAYER_ACTION → "Action: <playerName>" (45 slots)
Minimal Example
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 = first free slot
.permission("mywarn.use") // optional
.onClick(ctx -> {
Player target = ctx.target(); // non-null in PLAYER_ACTION
if (target != null) target.sendMessage("You have been warned!");
})
.build());
}
Behavior Details
- Rendering: Buttons are rendered every time the menu is opened.
- Permissions: If
.permission(...) is set, the button is hidden from players who lack it, and clicks by unauthorized players are refused.
- Slots:
.slot(int) picks a fixed slot; if that slot is already used by a built-in item, the button is skipped for that render. .slot(-1) auto-places into the first empty slot.
- Click Handling: The click event is automatically cancelled before your handler runs.
- Lifecycle: When your plugin disables, all of its buttons are removed automatically.
- Uniqueness: The pair
(owner plugin name, button id) is unique. Re-registering with the same pair replaces the existing button.
Limitations (What the API does NOT currently expose)
- Reading vanished / frozen / xray state.
- Custom events fired by AdminToolkit.
- Adding entirely new top-level submenus (workaround: register a button on
AdminMenu.MAIN whose onClick opens your own Inventory).
2. Command Forms & Subcommands
There is exactly one base command: /admin
/admin → Opens the main GUI menu.
/admin <onlinePlayerName> → Opens the Player Action GUI directly for that player.
/admin xrayhistory <playerName> → Opens the X-Ray history GUI for that player (works for offline players).
Tab completion suggests online player names for the first argument.
3. Permissions (Complete Reference List)
Wildcard-Style Parents (Grants All Children)
admintoolkit.admin → Grants everything below + use + maintenance.bypass
admintoolkit.worldproperties → All admintoolkit.worldproperties.*
admintoolkit.playermanagement → All admintoolkit.playermanagement.*
admintoolkit.selfmanagement → All admintoolkit.selfmanagement.*
admintoolkit.anticheat → All admintoolkit.anticheat.*
Standalone Permissions
| Permission |
Description |
Default |
admintoolkit.use |
Open /admin main menu. |
op |
admintoolkit.protected |
Player cannot be kicked or banned via the toolkit. |
op |
admintoolkit.maintenance.bypass |
Player can join while maintenance mode is ON. |
op |
admintoolkit.viewhealth |
Shows Server Health item in main menu. |
Undefined |
Sub-Category Permissions
- World Properties (
admintoolkit.worldproperties.*): setday, setnight, teleportall, clearweather, setrain, setstorm, broadcast, maintenance, clearchat, globalmute
- Player Management (
admintoolkit.playermanagement.*): kill, kick, ban, freeze, gamemode, message, impersonate, heal, feed, starve, smite, fakeop, op, deop, invsee, endersee, info, teleportto, bring, xrayhistory
- Self Management (
admintoolkit.selfmanagement.*): gamemode, heal, vanish, changename
- Anti-Cheat (
admintoolkit.anticheat.*):
alerts → Toggles X-Ray alerts and receives alert messages.
trackedores → Can edit which ores are tracked.
4. GUI Menu Titles (For Manual Clicks & Hooking)
AdminToolkit identifies menus by inventory title (plain text). If you want to manually hook into them, register an InventoryClickEvent listener with a priority after AdminToolkit (HIGH or higher) and match against these strings:
Static Titles
- Main Menu:
"Admin Toolkit"
- World Properties:
"World Properties"
- Self Properties:
"Self Properties"
- Online Players List:
"Online Players"
- Anti-Cheat:
"Anti-Cheat Controls"
- Ore Selection:
"Select Tracked Ores"
Prefixed Dynamic Titles (Match with startsWith)
"Action: <playerName>" → Player action menu.
"Reason: Kick <player>" or "Reason: Ban <player>" → Punishment reason picker.
"Gamemode: <playerName>" → Gamemode selector for a target player.
"X-Ray History: <playerName>" → X-ray mining record viewer.
5. Chat-Driven Input Interception
Some GUI actions request textual chat inputs. AdminToolkit listens to Paper's AsyncChatEvent at priority LOWEST and cancels the event if the following internal flags are set:
- Broadcast / Message → Processes text as a formatted server alert or direct admin text.
- ChangeName → Changes the admin's display name (typing 'reset' clears it).
- Kick / Ban → Applies text as a custom reason.
Extension Note: If your companion plugin handles chat triggers, ensure it respects event.isCancelled() at a NORMAL or higher priority.
6. Config File Schema & Live State
- Path:
plugins/AdminToolkitPlugin/config.yml
Saved Persistent Keys (Written on Shutdown / Read on Startup)
maintenance-mode: boolean
chat-muted: boolean
xray-alerts: boolean
tracked-ores: # List of Material enum names (e.g., DIAMOND_ORE)
vanished-players: # List of UUID strings
frozen-players: # List of UUID strings
Note: X-ray logs, active player impersonations, and pending chat inputs are in-memory only and lost on restarts.
Live State Safe Pattern
Plugin at = Bukkit.getPluginManager().getPlugin("AdminToolkitPlugin");
FileConfiguration cfg = ((JavaPlugin) at).getConfig();
boolean maintenance = cfg.getBoolean("maintenance-mode");
[!WARNING]
Runtime config values may be stale as state transitions are only flushed on onDisable(). To fetch accurate runtime state updates, track the underlying Bukkit events directly.
7. Core Runtime Hooks & Event Interactions
- Vanish: Handled using
player.hidePlayer(plugin, target). Track via standard hide/show calls as AdminToolkit does not expose its hidden set dynamically.
- Freeze: Runs via cancelled
PlayerMoveEvent lookups. Companion logic should respect this cancellation state.
- Maintenance Mode: Disallows logins via
PlayerLoginEvent unless players hold admintoolkit.maintenance.bypass.
- Global Chat Mute: Cancels
AsyncChatEvent at LOWEST priority for all users lacking the admintoolkit.admin permission.
- X-Ray Alerts: Tracks
BlockBreakEvent matching materials in the tracked-ores string list and notifies nodes carrying admintoolkit.anticheat.alerts.
- Impersonation: Cancels the admin's message and fires
target.chat(text). This creates an entirely new AsyncChatEvent where the sender identity is changed to the target player.
- Punishment Protection: Bypasses toolkit-instantiated GUI bans/kicks if a target player resolves
admintoolkit.protected. (Note: This does not block core native /ban or /kick source contexts).
8. Dependency Configuration
Add to your companion plugin.yml:
name: MyCompanionPlugin
main: org.example.MyCompanionPlugin
api-version: '1.21'
depend: [AdminToolkitPlugin] # Hard dependency
# Or use: softdepend: [AdminToolkitPlugin]
Initialization Guard Code:
Plugin at = Bukkit.getPluginManager().getPlugin("AdminToolkitPlugin");
if (at != null && at.isEnabled()) {
// Securely invoke hooks or API buttons here
}
Created for Paper Minecraft by Paper Minecraft administrators.
评论 0
登录后参与评分
还没有评论,来抢沙发吧