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

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.

Admin Toolkit

Compatibility

Minecraft: Java Edition

Platforms

Tags

Creators

Details