ZAdmin

ZAdmin

A modern, modular, high-performance in-game administration platform for Paper 1.21.x servers.

ZAdmin is a standalone administration panel that works out of the box on any Paper server with no dependency on private or third-party plugins. Every major feature is an independent module that can be enabled, disabled and reloaded at runtime, and a clean public API lets other developers extend the panel without ZAdmin ever depending on their plugins.

Features

Requirements

• Java 21+
• Paper 1.21.x (Bukkit Inventory API only — no external GUI framework)

Optional soft-dependencies: Vault, PlaceholderAPI, LuckPerms, Geyser/Floodgate.

Commands & Permissions

Base permission: zadmin.use. Every action has its own node (e.g. zadmin.player.freeze, zadmin.reports.claim, zadmin.logs.export, zadmin.developer.view). Grant zadmin.* for full access. See plugin.yml for the complete list.

Configuration

All files live in plugins/ZAdmin/ and hot-reload with /admin reload:

• config.yml — behaviour toggles, logging, economy, notifications, freeze, backups, chat filter, escalation, alt detection, cross-server sync, metrics, module flags
• messages.yml — every user-facing string (MiniMessage)
• gui.yml — dashboard icons, slots, names and lore
• database.yml — SQLite (default) or MySQL/MariaDB connection

Database

SQLite is the default and requires no setup. For MySQL/MariaDB, set type: mysql in database.yml and fill in the connection details. All database access is asynchronous and connection-pooled via HikariCP; the server thread is never blocked on I/O.

Public API

ZAdmin exposes a stable, generic API — it contains no references to any specific plugin.

Add ZAdmin as a softdepend in your plugin.yml, then:

import com.zadmin.api.*;
import com.zadmin.gui.Button;
import com.zadmin.util.ItemBuilder;
import org.bukkit.Material;

ZAdminProvider api = ZAdminAPI.get();

// 1. Add a button to the dashboard
api.registerDashboardButton(DashboardButton.of(31, "myplugin.use",
        Button.of(ItemBuilder.of(Material.NETHER_STAR).name("<gold>My Feature").build(),
                ctx -> ctx.player().performCommand("myplugin open"))));

// 2. Add a tab to the Player Inspector
api.registerPlayerInspectorTab(new PlayerInspectorTab() {
    public String id() { return "myplugin_homes"; }
    public String permission() { return "myplugin.homes"; }
    public Button build(Player viewer, UUID target) {
        return Button.of(ItemBuilder.of(Material.RED_BED).name("<aqua>Homes").build(),
                ctx -> { /* open your homes GUI for target */ });
    }
});

// 3. Register a named action
api.registerAction(new AdminAction() {
    public String id() { return "myplugin:reset"; }
    public String permission() { return "myplugin.reset"; }
    public void execute(Player staff, UUID target) { /* ... */ }
});

// 4. Register a module (enabled/disabled/reloaded by ZAdmin)
api.registerModule(myModule);

// 5. Receive notifications (forward to Discord, a web panel, etc.)
api.registerNotificationProvider(n ->
        getLogger().info("[" + n.severity() + "] " + n.type() + ": " + n.title()));

Prefer accessing the API from your own onEnable (or later) to guarantee availability. Use ZAdminAPI.isAvailable() / ZAdminAPI.getOrNull() for null-safe access. The API is also registered with Bukkit's ServicesManager as com.zadmin.api.ZAdminProvider.

PlaceholderAPI

When PlaceholderAPI is installed, ZAdmin registers the zadmin expansion: %zadmin_tps%, %zadmin_mspt%, %zadmin_memory_used%, %zadmin_memory_max%, %zadmin_frozen%, %zadmin_vanished%, %zadmin_god%, %zadmin_muted%.

Architecture

com.zadmin
├── api          Public extension points (generic, plugin-agnostic)
├── command      /admin command + tab completion
├── config       YAML loading, message service
├── database     Database abstraction (SQLite / MySQL via HikariCP), schema
├── gui          Menu framework (Bukkit Inventory API only) + built-in menus
├── hook         Soft integrations (Vault, PlaceholderAPI, LuckPerms, Floodgate)
├── listener     Global event listeners (connection, freeze, state, economy)
├── model        Immutable domain records + enums
├── module       Module framework + built-in modules
├── placeholder  PlaceholderAPI expansion
├── scheduler    Async task executor (main-thread marshalling)
├── service      Business logic (async, cached, thread-safe)
├── storage      DAOs (pure JDBC, async-safe)
└── util         Text/MiniMessage, ItemBuilder, TimeUtil, cooldowns

Design principles: SOLID, explicit composition root (dependency injection in ZAdminPlugin), no duplicated logic, thread-safe services, fully asynchronous database & logging, intelligent caching, and clean resource cleanup on disable. Built to comfortably serve 300+ concurrent players.

Privacy

Two features are disabled by default because they process player IP addresses:

• Alt detection (alt-detection.enabled) stores and compares players' last-known IPs.
• Cross-server sync (sync.enabled) shares punishment data across servers on a common database.

If you enable them, you are responsible for disclosing the practice to your players and for complying with applicable data-protection law (e.g. GDPR). ZAdmin never shows raw IPs through the alt-detection UI (only the resulting account names) unless player.show-ip is separately enabled.

Anonymous usage metrics are sent to bStats by default. To opt out, set metrics.enabled: false in config.yml, or disable bStats globally in plugins/bStats/config.yml.

License

Released for public use. Attribution appreciated.