PhantomBans | Complete Moderation Suite 1.1.0

📋 Overview

PhantomBans 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

Command usage screenshots

/ban

/tempban

/ipban

/mute

/tempmute

/ipmute

/warn

/kick

🤫 Silent Punishments

Punish 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 /alts to 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 Lookup

A 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

Lookup detail items

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: /checkban and /checkmute to 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 Plugin

Already 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 add confirm when 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 Sync

Running 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

⌨️ Commands

Main command /pb (alias /pbans) opens a paginated, clickable help menu.

Punishments

• /ban, /tempban, /ipban (alias /pban)
• /mute, /tempmute, /ipmute
• /warn, /kick (alias /pkick)
• /unban, /unmute to lift punishments
• Add -s to a ban or mute, or use /silentban and /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

🔐 Permissions

All 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

1. Drop the jar into your plugins/ folder.
2. Start the server once to generate the config and screen files.
3. Edit to taste, then reload, and your staff are ready to go.First start needs internet once so the server can download the plugin's libraries (cached afterward).

   ---

   📈 Metrics
   
   This plugin uses bStats to collect anonymous usage stats. You can opt out anytime in plugins/bStats/config.yml.
   
   
   

   ---

   💬 Support & Docs
   
   Full setup and configuration guides are in the documentation. Need help, found a bug, or want to suggest a feature? Join the Discord.
   
   
   Read the documentation
   Click here to join the Discord
   
   Catch them quietly. Keep your server clean.