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

| Area | What you get |
|------|--------------|
| Dashboard | A configurable inventory GUI hub (/admin) with MiniMessage text, configurable icons/slots, sounds, decorative panes and pagination. |
| Player Manager | Online player list → Player Inspector showing username, UUID, ping, health, hunger, saturation, XP, gamemode, world, coordinates, rotation, balance (Vault), prefix/suffix & group (LuckPerms), and optional IP. |
| Player Actions | Teleport, heal, feed, clear inventory, view inventory / ender chest, freeze, god mode, vanish, kick, ban, warn, mute, message, staff notes, alt detection, inventory snapshots, copy UUID. |
| Inventory Snapshots | Destructive actions (e.g. clear inventory) capture a restorable snapshot first. Browse a player's snapshot history and shift-click to roll back with one click. |
| Alt Detection | Optionally flags accounts sharing a last-known IP. Off by default (stores/compares IPs — a privacy-sensitive feature). |
| Chat Filter | Optional anti-spam (rate limit + duplicate suppression) and regex word/link blocklist, with configurable violation escalation. Bypassed by zadmin.chat.bypass. |
| Punishment Escalation | Configurable ladder (e.g. WARN → MUTE:1h → BAN:7d → BAN:perm) applied by offence count, plus one-click reason presets. |
| Cross-Server Sync | Over a shared MySQL/MariaDB datastore, propagates bans/mutes and staff broadcasts across a network. Off by default; no effect on SQLite. |
| Metrics | Anonymous, aggregate usage stats via bStats. Honors both ZAdmin's metrics.enabled and the global bStats opt-out. |
| Freeze System | Frozen players cannot move, break/place blocks, attack, interact, drop items or (optionally) run commands. Staff are alerted if a frozen player disconnects. |
| Staff Notes | Unlimited per-player notes with category/title/content, pagination, add & delete, database-backed. |
| Reports | Pending / Claimed / Closed queues with claim, close, teleport-to-target and history. |
| Punishments | Warn, kick, mute, tempmute, ban, tempban, blacklist — with history, durations, permanent storage and in-GUI revocation. |
| Economy Monitor | Tracks deposits/withdrawals, flags suspicious (large) transactions, filters & history. Gracefully disabled without Vault. |
| Logging | Async, batched audit log across commands, joins/quits, punishments, economy, teleports, staff actions, deaths and more — with category filters, pagination and export. |
| Scheduler | GUI editor for broadcasts, commands, saves, backups and restarts on interval or daily/weekly/monthly schedules. |
| Developer Tools | Plugin list & versions, world/chunk inspector, performance monitors (TPS/MSPT/RAM/threads), placeholder tester, PDC/metadata/permission inspector. No NMS. |
| Server Dashboard | Live TPS, MSPT, RAM, CPU load, worlds, chunks, entities, tile entities, players, plugins — auto-refreshing. |
| Modules | Enable/disable/reload every feature at runtime; state persists to config. |
| Notifications | In-game popups (TPS drops, new reports, frozen leavers, backups completed, punishments) with configurable sounds, plus an API for external providers. |
| Hooks | Auto-detects Vault, PlaceholderAPI, LuckPerms and Geyser/Floodgate; missing plugins simply disable their related functionality with no errors. |

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

| Command | Aliases | Description |
|---------|---------|-------------|
| /admin | /zadmin, /adm | Open the dashboard |
| /admin reload | | Reload config & modules (zadmin.settings.edit) |
| /admin module <enable\|disable\|list> [id] | | Manage modules (zadmin.modules.manage) |
| /admin backup | | Run a manual backup (zadmin.settings.edit) |
| /admin version | | Show version |

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.