?
Host a serverModrinth App
Sign in
ModsResource PacksData PacksShadersModpacksPluginsServers
Settings
Admin Toolkit

Admin Toolkit

A admin toolkit with lots of features.

144downloads
1follower
144downloads
1follower

Tags

Creators

Details

Licensed ARR
Published 6 months ago
Updated 3 months ago
All versions

1.3

Release
Admin Toolkit 1.3-API3 months ago 84
Download

Compatibility

Minecraft: Java Edition
1.21.x
Platforms
Paper
Purpur
Spigot

Changes

Added API handler

HOW TO USE:

AdminToolkit Plugin — Reference for Companion / Extension Plugins

This file documents everything a companion plugin needs to know to integrate with AdminToolkitPlugin without reading its source code.

  • Target: 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).

To read state directly, see Sections 6 and 7.

Plugin Integration

In your companion plugin.yml, add:

depend: [AdminToolkitPlugin]
# or
softdepend: [AdminToolkitPlugin]

2. Command

There is exactly one command: /admin

Usage Forms

  • /admin
    Opens the main GUI menu (see Section 4).
  • /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.

Base Permission

  • admintoolkit.use (Default: op)

3. Permissions (Complete List)

Wildcard-Style Parents (Grant 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
admintoolkit.use Open /admin main menu.
admintoolkit.protected Player cannot be kicked or banned via the toolkit.
admintoolkit.maintenance.bypass Player can join while maintenance mode is ON.
admintoolkit.viewhealth Shows Server Health item in main menu.

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

[!NOTE] Only admintoolkit.use, admintoolkit.protected, admintoolkit.maintenance.bypass, and admintoolkit.admin have explicit defaults (op). Everything else is undefined by default and must be granted explicitly through a permissions plugin (like LuckPerms).

4. GUI Menu Layout (For Detecting / Hooking Clicks)

AdminToolkit identifies menus by inventory title (plain text). If you want to inject items or cancel clicks, register an InventoryClickEvent listener with a priority after AdminToolkit and match against these exact strings:

Static Titles

  • Main menu: "Admin Toolkit" (9 slots)
  • World Properties: "World Properties" (27 slots)
  • Self Properties: "Self Properties" (27 slots)
  • Online Players list: "Online Players" (54 slots)
  • Anti-Cheat: "Anti-Cheat Controls" (27 slots)
  • Ore selection: "Select Tracked Ores" (54 slots)

Prefixed Dynamic Titles (Match with startsWith)

  • "Action: <playerName>" → Player action menu (45 slots)
  • "Reason: Kick <player>" or "Reason: Ban <player>" → Reason picker (27 slots)
  • "Gamemode: <playerName>" → Gamemode picker for a target (27 slots)
  • "X-Ray History: <playerName>" → X-ray record viewer (54 slots)

[!IMPORTANT] AdminToolkit calls event.setCancelled(true) on clicks in these menus. If you want to add your own items, listen at HIGH priority and set your own items back.

5. Chat-Driven Input Flows

Some actions ask the admin to type a value in chat. AdminToolkit listens to AsyncChatEvent at priority LOWEST and cancels the message when a "pending action" is set.

Pending actions include:

  • Broadcast: Next chat message is broadcast as [BROADCAST] ...
  • Message: Next chat message is sent to a specific target as [ADMIN] ...
  • ChangeName: Next chat message changes the admin's display name (type 'reset' to clear)
  • Kick / Ban: Next chat message is used as the custom reason

Companion Plugin Implication

If you also listen to AsyncChatEvent, listen at NORMAL or higher priority and check event.isCancelled(), otherwise you may echo captured input.

6. Config File (Persistent State)

  • Path: plugins/AdminToolkitPlugin/config.yml

Keys Saved on Shutdown

These values are written on plugin disable and read on enable:

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

In-Memory Only (Lost on Restart)

  • X-ray records (xrayRecords)
  • Impersonation mappings (impersonations)
  • Pending chat actions

Safe Reading Pattern

Plugin at = Bukkit.getPluginManager().getPlugin("AdminToolkitPlugin");
FileConfiguration cfg = ((JavaPlugin) at).getConfig();
boolean maintenance = cfg.getBoolean("maintenance-mode");
List<String> vanished = cfg.getStringList("vanished-players");

[!WARNING] The config is only saved on onDisable(). Values you see mid-runtime may be stale. If you need live state, watch for the same triggering event (e.g. PlayerLoginEvent for maintenance) instead of reading the config.

7. Runtime Behavior to Observe / React To

  • Vanish: Uses player.hidePlayer(plugin, target) / showPlayer. Keep your own vanish list or use a dedicated vanish API plugin to detect this, as you cannot read AdminToolkit's vanish set directly.
  • Freeze: Implemented by cancelling PlayerMoveEvent for frozen UUIDs. If you also handle PlayerMoveEvent, respect event.isCancelled().
  • Maintenance Mode: Blocks joins in PlayerLoginEvent unless the player has admintoolkit.maintenance.bypass. If your plugin also uses PlayerLoginEvent at LOW/NORMAL priority, be aware that the login may already be disallowed.
  • Global Chat Mute: Cancels AsyncChatEvent at priority LOWEST for players lacking admintoolkit.admin.
  • X-Ray Alerts: Fired on BlockBreakEvent for materials in the tracked-ores set. Alerts are broadcast to players holding admintoolkit.anticheat.alerts, featuring a clickable chat component that runs /admin xrayhistory <playerName>.
  • Impersonation: The admin's AsyncChatEvent is cancelled and re-fired via target.chat(text). This re-fire is a new AsyncChatEvent—your listener will see it as if the target sent it. If this matters, filter by admin identity or add a marker.
  • Punishment Protection: Any player with admintoolkit.protected cannot be kicked or banned through the toolkit's interface. This does not block /kick, /ban, or bans from other sources.

8. Depending on AdminToolkit

plugin.yml Configuration

name: MyCompanionPlugin
main: org.example.MyCompanionPlugin
api-version: '1.21'
depend: [AdminToolkitPlugin] # Hard dependency
# Or:
# softdepend: [AdminToolkitPlugin] # Optional dependency

Checking Dependency Status

Plugin at = Bukkit.getPluginManager().getPlugin("AdminToolkitPlugin");
if (at != null && at.isEnabled()) {
    // Safe to interact with the API
}

Executing Actions Programmatically

  • Open target GUI: player.performCommand("admin " + targetName);
  • Open X-Ray history: player.performCommand("admin xrayhistory " + name);

9. Build Environment

To avoid Application Binary Interface (ABI) issues, ensure your build environment targets matching specifications:

  • Paper API: io.papermc.paper:paper-api:1.21.11-R0.1-SNAPSHOT
  • Java: 21
  • Gradle: Kotlin DSL (build.gradle.kts)

Your companion plugin should target the same Paper API version or lower.

10. Quick Checklist for Adding a Feature

Case A: Adding a "Warn Player" or "Mute Target" Action

  1. In your own plugin, register a command (e.g., /warn).
  2. Add your own permission (e.g., mycompanion.warn).
  3. Optionally require admintoolkit.use so only AdminToolkit users see/use it.
  4. If you want the feature reachable from AdminToolkit's GUI, listen to InventoryClickEvent at EventPriority.HIGH, match the title "Action: <name>", and inject/handle your own item before responding.
  5. If your feature needs chat input, do not set your pending action while AdminToolkit already has one for that player, as they will collide.

Case B: Reacting to AdminToolkit Actions

  • Vanish / Freeze / Mute / Maintenance: Watch config.yml or the underlying Bukkit events (e.g., hidePlayer/showPlayer calls, cancelled PlayerMoveEvent, etc.).
  • Bans / Kicks: Register listeners for PlayerKickEvent / the server ban list.
  • X-ray Alerts: Listen to BlockBreakEvent yourself and check the same ore list. There is no custom event fired by AdminToolkit.