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.