Admin Toolkit

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

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.