Staff+

Staff+ is an enterprise-grade, high-performance moderation and utility plugin built for modern Minecraft networks. It ships as two platform-specific JARs — one for Paper/Purpur/Folia backend servers and one for Velocity proxies — sharing a unified core engine for consistent punishment management across your entire network.

Paper Edition runs on Paper/Purpur/Folia 1.20–1.21+ servers with full Folia multi-threaded region safety, and includes advanced staff tools like vanish, inventory inspection, and spectator monitoring.

Velocity Edition runs on Velocity 3.3.0+ proxies and enforces bans, IP-bans, and mutes at the network gateway before players even reach a backend server.

Both editions share the same database, configs, and migration system — deploy one or both depending on your setup.

Platform Comparison

Features

Cross-Platform Core

• Shared Database: Both Paper and Velocity editions read and write to the same punishment database (SQLite or MySQL), enabling seamless network-wide moderation.
• Shared Configs: config.yml and messages.yml use identical formats on both platforms via the Okaeri configuration framework.
• Unified Migration Engine: Import punishments from 7+ plugins on either platform.

Folia Safety (Paper Edition)

• Asynchronous Lifecycles: All commands, database transactions, and packet actions run on Folia-compliant regional or asynchronous schedulers.
• Folia Teleportation Safety: Standard teleports are replaced with safe, non-blocking teleportAsync futures, completely preventing thread crashes.
• Isolated Packet Loops: Visually toggling features (like Vanish hide/show packets) are scheduled on each recipient's specific regional thread, guaranteeing thread-safety.

Proxy Gateway Enforcement (Velocity Edition)

• Pre-Login Ban Check: Intercepts login attempts at the proxy level and rejects banned players before they reach any backend server.
• Network-Wide Mute Filter: Blocks chat messages from muted players across all connected servers.
• IP-Ban Gateway: Enforces IP bans at the proxy gateway, preventing banned IPs from connecting to any server in the network.

Vanish (Paper Only)

• Total Invisibility: Completely removes the player from the online count, player ping lists, tab completions, and visible lists.
• Physical Interaction Bypass: Vanished staff bypass physical pressure plates and tripwire triggers entirely.
• Silent Containers: Allows opening chest, furnace, and barrel interfaces silently without triggering container animations or audio.
• Stealth Suppression: Prevents mob targeting, item pickups, and suppresses join/quit messages entirely while active.
• Visual Action Bar Indicator: Real-time HUD showing vanished status via safe asynchronous repeating tasks.

Moderation (Both Platforms)

• Comprehensive Actions: Integrated /ban, /tempban, /ip-ban, /tempip-ban, /mute, /tempmute, and /warn.
• Warning Profiles: Track individual warning logs via /warns <player> [list/clear].
• Dynamic Time Parsing: Sophisticated time parser supporting complex units (e.g. 1d, 12h, 45m) and infinite duration mappings (perm).
• Relational Storage: Backed by a high-performance database manager supporting both local SQLite databases and remote MySQL servers, managed via a shaded, thread-safe HikariCP connection pool.
• Linked Account Alt-Detection: On player login, automatically scans, logs, and broadcasts alternate accounts sharing the IP address, color-coding active (green) and banned (red) profiles.
• Dynamic Command & History Parity: Multi-threaded /history <player>, /staffhistory <staff>, and /staffrollback <staff> commands supported by dynamic database-backed name tab completions.
• Warning Escalation Ladder: Scale punishments dynamically (e.g. tempmutes scaling to permanent bans) based on active warning levels. Command dispatches execute safely on each platform's native scheduler.
• Non-Blocking Discord Webhook Logs: Real-time embeds logging all mute, ban, and warning dispatches using modern non-blocking Java 21 HttpClient interfaces with zero impact on region ticks.
• Administrative Overwrite Hierarchy Protection: Custom staff weight ranks (staff.hierarchy.weight.<number>) blocking junior staff from overriding, deactivating, or removing punishments placed by senior administrators or the Console (Integer.MAX_VALUE).
• IP-Ban Exemption Bypass: Whitelist specific accounts (/staffallow) to connect and bypass active IP-bans without lifting the IP ban itself for other accounts sharing the IP.

Punishment Importer & Migration (Both Platforms)

• 7 Supported Platforms: Seamlessly import mutes, bans, warnings, and IP bans from:
  • Vanilla Minecraft: Direct imports from banned-players.json and banned-ips.json in the server root.
  • Essentials / EssentialsX: Automated scans of mutes and bans in user profiles under plugins/Essentials/userdata/*.yml.
  • LiteBans: Migrates bans, mutes, and warnings from H2/SQLite/MySQL databases. Supports auto-detection of the litebans.mv.db H2 file or manual JDBC parameters.
  • AdvancedBan: Integrates and normalizes legacy SQL Punishments tables from SQLite or MySQL.
  • MaxBans: Migration of bans, IP bans, mutes, and warnings from SQLite or MySQL.
  • BanManager: Integrates historical player bans, mutes, and warnings with configurable table prefixes.
  • BungeeAdminTools (BAT): Imports entries from database tables bat_ban and bat_mute.
• Dynamic Auto-Scanning: Scans your server's active files on command, extracts SQLite paths or remote SQL database credentials, and allows zero-configuration migrations.
• Batch Operations: Commits imported records inside a single transaction using batch inserts, migrating thousands of records instantly.
• Non-Blocking Futures: Runs connection setups, configuration decodes, and database commits fully asynchronously on non-blocking thread pools.

Spectator Follow (Paper Only)

• Cinematic Camera Tracking: Teleports staff in spectator mode to follow the target seamlessly.
• Velocity-Predicted Follow: Computes target movements and velocity vectors (target.getVelocity()) to position the camera slightly ahead of the target, eliminating stutter and rubber-banding.
• Throttled Teleports: Auto-updates run at a throttled 4-tick (200ms) interval with a 400ms cooldown, giving client-side predicted movements and Paper's async teleportation futures time to fully resolve.
• Configurable Boundary Tether: Allows staff to orbit or move freely within a 10-block radius. Going beyond the boundary gently tethers the camera back into offset.

Inventory Inspector (Paper Only)

• 54-Slot Live GUI: View and edit target players' main inventories (0-35), armor slots (helmet, chestplate, leggings, boots), off-hand items, and stats.
• Live Stats & Shortcuts:
  • Golden Apple: Displays health, food levels, and experience dynamically.
  • Potion Bottle: Shows a live list of active potion effects and durations.
  • Ender Chest: Quick-access shortcut item to inspect their Ender Chest directly.
• Unparalleled Folia Safety: Completely avoids asynchronous block-state reads (which crash under Folia when querying .getOpenInventory().getTopInventory().getHolder() on block-based inventories in other regions). Instead, it implements a thread-safe custom session registry that cleanly tracks active inspect views and propagates updates regionally.

Shortcuts (Paper Only)

• Instant Gamemode Shifts: Rapid commands including creative (/gmc), survival (/gms), spectator (/gmsp), and adventure (/gma).
• Flight Mode: Seamless command flight toggles via /fly.

Commands & Permissions

Network-Wide Commands (Paper & Velocity)

Paper-Only Commands

Admin Wildcard: The permission node staff.admin grants access to all capabilities of the plugin by default. Bypass Node: Players with the permission staff.vanish.see can see vanished players in-game, in tab lists, and in commands.

Installation

Paper Edition (Paper / Purpur / Folia)

1. Download StaffPlus-Paper-1.2.3.jar from Modrinth or GitHub Releases.
2. Place the JAR in your server's plugins/ folder.
3. Restart your server.
4. Edit plugins/Staff/config.yml and plugins/Staff/messages.yml to your liking.

Velocity Edition (Proxy)

1. Download StaffPlus-Velocity-1.2.3.jar from Modrinth or GitHub Releases.
2. Place the JAR in your Velocity proxy's plugins/ folder.
3. Restart your proxy.
4. Edit plugins/staffplus/config.yml and plugins/staffplus/messages.yml to your liking.
5. Permissions & Backend Forwarding:
   • If you use LuckPerms on Velocity, grant staff staff.admin (/lpv user <name> permission set staff.admin true).
   • If you manage permissions and OPs exclusively on your backend Paper servers, Staff+ automatically forwards commands executed on Velocity down to the player's connected Paper server (velocity-forward-to-backend: true), allowing Paper to evaluate LuckPerms and OP status seamlessly!

Shared Database (Network Mode)

To share punishments across your entire network, configure both editions to use the same MySQL or MariaDB database:

# config.yml (same on both Paper and Velocity)
storage-type: "mysql" # or "mariadb"
mysql-host: "your-db-host"
mysql-port: 3306
mysql-database: "staffplus"
mysql-username: "your-user"
mysql-password: "your-password"

Configuration

The plugin uses Okaeri Config to generate, validate, and auto-update clean YAML configuration structures. Both platforms share identical configuration formats.

config.yml

# Storage type: SQLITE, MYSQL, or MARIADB
storage-type: "sqlite"

# MySQL / MariaDB Connection Details (only used if storage-type is MYSQL or MARIADB)
mysql-host: "localhost"
mysql-port: 3306
mysql-database: "minecraft"
mysql-username: "root"
mysql-password: "password"
mysql-pool-size: 10
mysql-use-ssl: false

# Vanish settings (Paper only — ignored on Velocity)
vanish-silent-container-clicks: true
vanish-ignore-pressure-plates: true
vanish-disable-mob-targeting: true
vanish-disable-item-pickup: true

# Warning escalation ladder settings
warning-ladder-enabled: true

# Actions to run when a player reaches a specific number of active warnings
warning-ladder-actions:
  1: "tempmute {player} 1h [Warning Ladder] First warning"
  2: "tempmute {player} 12h [Warning Ladder] Second warning"
  3: "tempban {player} 3d [Warning Ladder] Reached 3 warnings"
  4: "ban {player} [Warning Ladder] Reached 4 warnings"

# Discord Webhook logging settings
discord-webhook-enabled: false
discord-webhook-url: ""
discord-webhook-username: "Staff+ Moderation"
discord-webhook-avatar-url: "https://i.imgur.com/8Qp49X0.png"

# Hex color codes for webhook embeds (without the #)
discord-webhook-color-ban: "FF5555"
discord-webhook-color-mute: "FFAA00"
discord-webhook-color-warn: "FFFF55"

# Update Checker settings (Modrinth)
update-checker-enabled: true
update-checker-notify-admins: true

# Staff Ban Leaderboard settings
bans-leaderboard-enabled: true

# Velocity Proxy Settings (Velocity only)
velocity-proxy-commands: true
velocity-forward-to-backend: true
velocity-disconnect-on-kick: true

messages.yml

Features full Adventure MiniMessage compatibility, enabling gorgeous native text styling, hex colors, and gradients (e.g. <gradient:#FF5F6D:#FFC371>Text</gradient>).

# Prefix for all plugin messages
prefix: "<color:#A0A0A0>[<color:#00E262>Staff+<color:#A0A0A0>] "

no-permission: "<color:#E20000>You do not have permission to execute this command."
player-only: "<color:#E20000>This command can only be executed by a player."
cannot-overwrite-punishment: "<color:#E20000>You cannot override a punishment placed by a higher-ranking staff member ({staff})."
player-allowed: "<color:#00E262>You have allowed {player} to bypass IP bans."
player-allowed-broadcast: "<color:#00E262>{player} has been exempted from IP bans by {sender}."
player-unallowed: "<color:#00E262>You have removed IP ban exemption for {player}."
player-unallowed-broadcast: "<color:#00E262>{player} is no longer exempted from IP bans."
player-not-found: "<color:#E20000>Player '{player}' has not been found or registered."
invalid-duration: "<color:#E20000>Invalid duration format! Use e.g. 1d, 12h, 30m or perm."

# Mutes
player-muted: "<color:#00E262>You have muted {player} for {time}. Reason: {reason}"
player-muted-broadcast: "<color:#E2B700>{player} has been muted by {sender} for {time}. Reason: {reason}"
you-are-muted: "<color:#E20000>You are muted! Remaining time: {time}. Reason: {reason}"

# Bans
player-banned: "<color:#00E262>You have banned {player} for {time}. Reason: {reason}"
player-banned-broadcast: "<color:#E20000>{player} has been banned by {sender} for {time}. Reason: {reason}"
ban-kick-message: "<color:#E20000>You have been banned from the server!\n\nReason: {reason}\nExpiry: {time}"

# Vanish (Paper only)
vanish-enabled: "<color:#00E262>You are now vanished."
vanish-disabled: "<color:#00E262>You are no longer vanished."
vanish-action-bar: "<color:#00E262>★ YOU ARE VANISHED ★"

Build & Compilation

Staff+ is a multi-module Gradle project producing two independent shaded JARs.

Requirements

• Java 21 or higher
• Gradle (installed or via wrapper)

Build Command

Compile and build both platform JARs:

./gradlew clean build

The compiled plugins will be located at:

staff-paper/build/libs/StaffPlus-Paper-1.0.0.jar    # Paper/Purpur/Folia servers
staff-velocity/build/libs/StaffPlus-Velocity-1.0.0.jar  # Velocity proxies

Project Structure

StaffPlus/
├── staff-core/          # Shared platform-agnostic library
│   └── src/main/java/   # Database, Punishment model, Configs, Migration, Utils
├── staff-paper/         # Paper/Folia backend plugin
│   └── src/main/java/   # Paper commands, listeners, vanish, monitor, invsee
├── staff-velocity/       # Velocity proxy plugin
│   └── src/main/java/   # Velocity commands, login/chat listeners
├── build.gradle          # Root configuration
└── settings.gradle       # Multi-module declaration

Note: The Gradle shadow configuration automatically relocates eu.okaeri, com.zaxxer.hikari, org.h2, and org.xerial libraries to private namespaces (me.ayosynk.staff.libs.*) to prevent conflicts with any other plugins on the classpath.

Continuous Integration

Staff+ implements a fully automated CI/CD pipeline via GitHub Actions to compile, validate, and distribute artifacts for both platforms.

Dev Builds

• Frequency: Built automatically on every push to the master or main branches.
• Release Target: Published under the rolling dev-latest pre-release tag on GitHub.
• Rolling Policy: The pipeline automatically overwrites the previous dev-latest tag on every build, maintaining a clean releases page.
• Artifacts: Both StaffPlus-Paper and StaffPlus-Velocity JARs are published in every release.

Stable Releases

• Frequency: Generated whenever a semantic Git version tag matching v* (e.g., v1.0.0) is pushed to the repository.
• Release Target: Published as a dedicated production release containing formal release notes and both platform-ready shaded JAR assets.

bStats Metrics

Both editions of Staff+ integrate with bStats to collect anonymous usage statistics. This helps us understand how the plugin is being used and guides future development.

• Paper Edition: Uses bstats-bukkit for server-side metrics.
• Velocity Edition: Uses bstats-velocity (Plugin ID: 31693) for proxy-side metrics.

If you wish to opt-out of anonymous metrics collection, you can disable it by navigating to the plugins/bStats/config.yml file on your server or proxy and setting enabled: false.

Developer Notes

For developers looking at the source code of Staff+, here is a summary of the architecture:

Multi-Module Architecture

1. staff-core: Platform-agnostic shared library containing the database layer, punishment model, config system, migration engine, and utility classes. Uses ForkJoinPool.commonPool() for async operations — no platform-specific scheduler dependencies.
2. staff-paper: Paper/Folia plugin implementing StaffPlatform interface. Contains all Paper-specific commands, listeners, vanish, monitor, invsee, and gamemode shortcuts. Uses Folia-safe regional schedulers.
3. staff-velocity: Velocity proxy plugin implementing StaffPlatform interface. Contains proxy-level commands and login/chat event listeners for network-wide enforcement.

Folia Threading Rules (Paper)

1. Async Teleportation: Never call Player#teleport() on Folia. Always use Player#teleportAsync() and queue dependent actions using .thenRun() or .thenAccept().
2. Recipient Thread Safety: Action updates (like recipient.hidePlayer() or recipient.showPlayer()) must execute on the recipient's regional thread context. Wrap these calls in SchedulerUtils.runEntity(plugin, recipient, ...) to guarantee packet delivery.
3. Avoid cross-region block state reads: Calling open.getHolder() on block-based inventories open in other regions throws threading exceptions. Instead, maintain an in-memory, thread-safe registry of InvseeSession objects.
4. Cinematic Follow Damping: Use interval checking (≥4 ticks), velocity extrapolation, and a task cooldown to maintain smooth follower views.