PhantomBansA complete GUI punishment suite: bans, mutes, warns, silent punishments, reports, and appeals
By zArrowTan, part of Arrow Plugins.
OverviewPhantomBans is a full moderation suite for your staff team. Bans, IP-bans, mutes, warns, and kicks (permanent or temporary), silent punishments that only staff can see, a reports and appeals workflow, staff notes, deep player lookups, alt detection, GeoIP and VPN blocking, and Discord webhooks. Almost everything runs through clean paginated GUIs, every screen and message is editable, and the jar stays tiny by loading its libraries at runtime. Run a network? Punishments sync across all your servers, with optional proxy support. Switching from another plugin? Bring your punishment history with you.
The Active Reports menu
Punishment Types- Bans & IP-Bans: permanent or temporary, with custom ban screens
- Mutes & IP-Mutes: permanent or temporary, enforced in chat
- Warns: with configurable thresholds that auto-escalate (for example, 5 warns mutes, 10 bans for a week, 15 bans permanently, all editable)
- Kicks: with a custom kick screen
- Punishment templates: escalating ladders of steps per offence, so repeat offenders climb the punishment chain automatically
What a banned player sees
The kick screen
A muted player's notice
/ban
/tempban
/ipban
/mute
/tempmute
/ipmute
/warn
/kick
Silent PunishmentsPunish without tipping off the server. Add
-s to a ban or mute, or use the /silentban and /silentmute aliases. The target sees the normal ban or mute, but the public broadcast is suppressed, and only staff with the right permission get a quiet heads-up about who issued it. Perfect for catching alts and rule-breakers without the audience.
IP Tools, GeoIP & Alt Detection- IP punishments: ban or mute by IP to shut down ban evaders
- Alt detection: flags accounts sharing an IP, with
/altsto investigate and a ban-evasion auto-flag - GeoIP country control: block chosen countries with a dedicated screen, or flip to allow-list mode to permit only the countries you choose
- VPN blocking: turn away VPN and proxy connections
An IP-banned player's screen
The VPN block screen
/alts to investigate shared IPs
Reports & Appeals- Player reports: players report rule-breakers with
/report, and staff review them in a live menu - Appeals workflow: review punishments and accept, deny, or escalate them, each with its own note
The active reports menu
The reports menu when it's all quiet
Reporting a player with /report
Player LookupA single menu with everything you need on a player: first and last seen, play time, total bans, total mutes, name history, and their country.
The player lookup menu
First seen and last seen
Total bans
Total mutes
Name history
Country (GeoIP)
History, Notes & Checks- Punishment history: browse a player's full record in a paginated menu with
/history, or audit a staff member's actions with/staffhistory - Staff notes: leave private notes on players with
/note - Quick checks:
/checkbanand/checkmuteto see a player's active status at a glance
Browsing a player's punishment history
Checking a player's mute with /checkmute
🖥 GUI-Driven Everywhere
- Punish, history, lookup, reports, appeals, and staff notes all open as clean paginated menus
- Duration, reason, and template selectors so staff rarely need to type long commands
- Quick-pick preset reasons in the punishment GUI, fully editable
- Confirmation screens to prevent misfires
The player punish menu, staff open it to punish without typing commands
Custom Screens & Messages- Editable screens: ban, tempban, IP-ban, kick, country-blocked, and VPN-blocked, all yours to reword
- Full message control: every player-facing string is editable, with MiniMessage formatting, hex, and gradients
- Safe updates: config and language files keep your edits while merging in new keys on update
Integrations & Storage- Discord webhooks: mirror punishments to Discord as rich embeds, with separate per-event webhooks for bans, mutes, kicks, warns, unbans, reports, appeals, staff notes, and the audit log, each toggled on or off independently. Silent punishments can be kept out of Discord too.
- PlaceholderAPI: placeholders like
%phantombans_is_banned_<player>%for scoreboards, tab, and chat - Storage: SQLite by default, or MySQL / MariaDB, all async so the main thread never blocks
- Tiny jar: around 300KB, with libraries downloaded at runtime instead of bloating the file
Migrate From Your Old PluginAlready running another punishment plugin? Bring your history with you. PhantomBans imports existing punishment data from LiteBans, AdvancedBan, and LibertyBans, so you keep every ban, mute, and warn on record when you switch.
- Safe by default: run
/pb import <source>for a dry-run preview that reads and reports counts but writes nothing, then addconfirmwhen you're ready - Clean re-runs: imported rows are tagged by source, so re-importing won't create duplicates
- File or network databases: reads each plugin's local database, or a live MySQL / MariaDB source
A dry-run preview, then the real import with confirm
Network SyncRunning more than one server? PhantomBans syncs punishments across your whole network. Ban, mute, unban, and unmute on any server and it applies everywhere, with banned players kicked network-wide the instant the punishment lands. Silent punishments stay silent across every server too.
- Cross-server enforcement: bans and mutes propagate to every backend automatically
- Optional proxy support: companion jars for Velocity (recommended) and BungeeCord (experimental) reject banned players right at the proxy, before they reach a backend
- Opt-in: enable it in
network.yml. Single-server setups are unaffected - One requirement: every server must share one MySQL or MariaDB database for sync to work
CommandsMain command
/pb (alias /pbans) opens a paginated, clickable help menu.Punishments
/ban,/tempban,/ipban(alias/pban)/mute,/tempmute,/ipmute/warn,/kick(alias/pkick)/unban,/unmuteto lift punishments- Add
-sto a ban or mute, or use/silentbanand/silentmute(plus/unsilentban,/unsilentmute)
Staff Tools
/report <player> <reason>report a player/lookup <player>open the player lookup menu/history(alias/hist) and/staffhistory <staff>/alts <player>investigate shared IPs/note(alias/notes) leave a staff note/checkban <player>,/checkmute <player>/pb import <litebans|advancedban|libertybans> [dry|confirm]import punishments from another plugin
The in-game help menu
PermissionsAll nodes use the
phantombans.* prefix, with phantombans.admin as a grant-all parent. Silent punishments are gated separately: phantombans.silent.use to issue them and phantombans.silent.see to receive the quiet staff notices.
Requirements- Server: Paper 1.21+ or a Paper fork (Purpur), supporting 1.21.x and newer
- Java: 21 or higher
- Storage: SQLite out of the box, MySQL or MariaDB optional (a shared MySQL/MariaDB is required for network sync)
- Networks: optional Velocity or BungeeCord proxy support
- Optional: PlaceholderAPI and Vault
Installation- Drop the jar into your
plugins/folder. - Start the server once to generate the config and screen files.
- Edit to taste, then reload, and your staff are ready to go.
MetricsThis plugin uses bStats to collect anonymous usage stats. You can opt out anytime in
plugins/bStats/config.yml.
Support & DocsFull setup and configuration guides are in the documentation. Need help, found a bug, or want to suggest a feature? Join the Discord.
