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

1. Download the latest JAR from the Releases page (or build it yourself).
2. Place the JAR in your Paper server's plugins/ folder.
3. Restart your server.
4. Use /admin in-game to open the toolkit.

Permissions

• admintoolkit.admin: Required for all admin features (defaults to OP).

Development

Prerequisites

• Java 21
• Gradle

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.