Staff Utils v1.0.1

StaffUtils is the staff plugin I always wanted but could never quite find. I got tired of running 3-4 different plugins just to handle basic moderation stuff, so I built one that handles it all — staff mode, punishments, freezing, reports, IP bans, chat filtering, Discord logging, and more, all in one jar.

Everything is managed through clean GUIs or simple commands. Your staff don't need a manual to figure it out.


Punishment System

This is where StaffUtils really shines. The entire punishment flow can be done through an interactive GUI — just run /punish <player> and you're walked through selecting the type, duration, reason, and a final confirmation screen before anything goes through.

• Ban — Temp or permanent, with a custom disconnect screen showing the reason, duration, and ban ID
• Mute — Temp or permanent, players get notified when they try to chat with their remaining time
• Kick — Immediate disconnect with a custom kick screen
• Warn — Formal warnings that stack up, with configurable auto-actions when a player hits the threshold (auto-kick, tempban, or permban)
• IP Ban — Ban by IP address with temp or permanent durations. Catches all accounts on the same address

All punishments are logged with unique IDs, timestamps, staff member names, and full reason history. Temp bans and mutes expire automatically — a background task checks every 60 seconds so nothing lingers. Nothing gets lost.

Punishment GUI

The /punish GUI walks your staff through the entire process step by step:

• Pick a punishment type (ban, mute, kick, warn)
• Select a duration from presets (1h up to 90d, permanent, or type a custom one)
• Choose a reason from categorized presets or type your own
• Review everything on a confirmation screen before executing

The main screen also shows the player's current status at a glance — total punishments, active warnings, whether they're currently banned or muted. There's also a paginated history browser and an active punishments viewer built right in.

Duration presets are color-coded by severity so your staff can quickly tell the difference between a 1-hour mute and a 90-day ban at a glance.

Staff Mode

Toggle with /staffmode — puts you into a clean moderation state:

• Vanish (hidden from all non-staff players, including late joiners)
• God mode (invulnerable)
• Creative mode with flight
• Your inventory, gamemode, and flight state are all saved and restored when you toggle off
• Interactive hotbar items for quick access to teleport, freeze, invsee, punish, and history tools

Don't need the full staff mode? Use /vanish on its own to toggle visibility without changing your gamemode or inventory.

Freeze

/freeze <player> locks a player in place. They can look around but can't move, break/place blocks, use items, drop things, or fight. Commands are blocked too (with a configurable whitelist so they can still /msg if you want). If a frozen player logs out, all online staff get notified immediately.

Report System

Regular players can /report <player> <reason> to flag rule-breakers. Reports come through to all online staff with a sound notification and full details. Staff can view all open reports with /report list and mark them resolved with /report resolve <id>. Built-in cooldown prevents spam.

Staff Notes

Attach persistent notes to any player with /staffnotes <player> add <note>. Notes survive restarts and are visible to all staff — useful for tracking context that doesn't fit neatly into a punishment ("warned verbally in Discord", "suspected alt of X", etc.). View with /staffnotes <player> list, remove with /staffnotes <player> remove <id>.

More Tools

• /invsee — Open and view another player's inventory
• /playerinfo — Quick summary of a player: UUID, IP, location, health, food, ping, gamemode
• /spectate — Enter spectator mode following a player's POV. Run again with no args to stop
• /staffchat — Staff-only chat channel with @mention pings and sound alerts
• /stafflist — See all online staff with status indicators (staff mode, vanished, etc.)
• /warnings — View a player's warning history with numbered entries
• /clearwarnings — Wipe all warnings from a player
• /history — Full punishment history (opens a GUI for players, prints to console for console)

Chat Filter

Configurable automatic chat filtering with a simple word list and regex pattern support. When a player triggers the filter, you choose what happens — block the message silently, issue an automatic warning, mute them, or kick them. Staff with bypass permission are unaffected, and all violations are logged and notified to online staff.


Discord Webhook

Paste a Discord webhook URL into the config and every punishment gets sent as a rich embed to your Discord channel — type, player, staff member, reason, duration, and timestamp. Great for keeping logs outside of Minecraft or letting your team see moderation activity at a glance.

PlaceholderAPI

If PlaceholderAPI is installed, StaffUtils registers 14 placeholders you can use in scoreboards, tab lists, or anywhere else:

• %staffutils_warnings% — Warning count
• %staffutils_punishments% — Total punishment count
• %staffutils_is_banned% / %staffutils_is_muted% / %staffutils_is_frozen%
• %staffutils_is_staffmode% / %staffutils_is_vanished%
• %staffutils_ban_reason% / %staffutils_ban_remaining%
• %staffutils_mute_reason% / %staffutils_mute_remaining%
• %staffutils_notes% / %staffutils_reports% / %staffutils_staffchat_toggled%

Folia Support

StaffUtils fully supports Folia's regionized multithreading. All scheduling, teleportation, and entity operations use the correct region/entity schedulers when running on Folia, and fall back to standard Bukkit scheduling on Spigot and Paper. No config needed — it's detected automatically at startup.



Tip: Give your staff staffutils.staff to grant all permissions at once.
staffutils.notify controls who receives punishment broadcast notifications.
staffutils.report defaults to all players so anyone can submit reports.
staffutils.chatfilter.bypass lets staff talk without being filtered.


Everything is configurable in config.yml — the message prefix, staff mode behavior (vanish, god mode, flight), staff chat format, freeze settings (which commands are allowed), warning thresholds and auto-actions, report cooldowns, chat filter words/patterns/actions, Discord webhook URL, and what gets written to the activity log.

Punishments are persisted in punishments.yml, IP bans in ipbans.yml, reports in reports.yml, and staff notes in notes.yml — all survive restarts. File saves run asynchronously so your main thread stays clean. Staff actions are logged with timestamps to staff-log.txt so you always have a paper trail.

• Spigot, Paper, or Folia 1.21+
• Java 21
• Optional: PlaceholderAPI (for placeholders)

Drop StaffUtils.jar into your plugins folder and restart. That's it. Config generates on first run. PlaceholderAPI and Discord webhook are optional — just enable them in the config if you want them.