LiteBanX (BanX)

An insanely customizable punishment plugin for Paper 1.21+.

Bans, IP-bans, tempbans, mutes, warns, kicks, and notes — with order-insensitive command parsing, offline-player support, alt detection, and a full staff GUI. Built to be the last punishment plugin you need to install.

---

Features

• Full punishment suite — ban, IP-ban, tempban, temp-IP-ban, mute, tempmute, warn, tempwarn, kick, and staff notes
• Order-insensitive parsing — flags and durations can be typed in any order
• Offline-player support — punish players who aren't online via async Mojang lookup
• Warning-point escalation — configurable thresholds that automatically escalate punishments
• Alt detection — flags accounts sharing an IP with a punished player
• Staff GUI — a full in-game staff panel (/staff) including a spectate mode
• Themed punishment screens — configurable ban/mute/kick screens
• MySQL or SQLite — HikariCP-pooled storage, your choice of backend
• PlaceholderAPI support — expose punishment data to other plugins
• Webhooks — send punishment events to Discord or any webhook endpoint
• Importers — migrate existing data straight from AdvancedBan and LiteBans

---

Commands

Command	Description
/ban <player|ip> [reason]	Permanently ban a player or IP
/tempban <player|ip> <time> [reason]	Temporarily ban a player
/ipban <ip|player> [reason]	Ban an IP address
/tempipban <ip|player> <time> [reason]	Temporarily ban an IP address
/unban <player|ip> [reason]	Unban a player or IP
/mute <player> [reason]	Permanently mute a player
/tempmute <player> <time> [reason]	Temporarily mute a player
/unmute <player> [reason]	Unmute a player
/warn <player> [reason]	Warn a player
/tempwarn <player> <time> [reason]	Issue an expiring warning
/unwarn <player> [id|*]	Remove a warning
/kick <player> [reason]	Kick a player
/note <player> <message>	Add a private staff note
/unnote <player> [id|*]	Remove a staff note
/checkban <player|ip>	Check active punishments for a player or IP
/history <player> [page]	View a player's punishment history
/banlist [page]	List all active bans
/mutelist [page]	List all active mutes
/warnslist [page]	List all warnings
/notes <player> [page]	View staff notes for a player
/iphistory <player|ip> [page]	View IP history
/alts <player|ip>	Detect alt accounts sharing an IP
/staffhistory <player> [page]	View punishments issued by a staff member
/clearhistory <player> [types]	Clear a player's punishment history
/banx <subcommand>	Root command — every subcommand namespaced (e.g. /banx ban Steve cheating)
/litebanx <reload|import|preset|version|debug|dump>	Admin command
/staff [gui|stop]	Open the staff GUI, or stop spectating

---

Permissions

Every command is gated by its own litebanx.<action> node, so you can grant exactly the subset of tools each staff rank needs. Highlights:

Permission	Default	Description
litebanx.ban / litebanx.tempban / litebanx.ipban / litebanx.unban	op	Ban management
litebanx.mute / litebanx.tempmute / litebanx.unmute	op	Mute management
litebanx.warn / litebanx.tempwarn / litebanx.unwarn	op	Warning management
litebanx.kick	op	Kick players
litebanx.note / litebanx.unnote / litebanx.notes	op	Staff notes
litebanx.history / litebanx.history.others	op	View own / others' history
litebanx.alts / litebanx.iphistory	op	Alt and IP investigation tools
litebanx.staff / litebanx.spectate	op	Staff GUI and spectate mode
litebanx.admin	op	Reload, import, and admin tools
litebanx.exempt / litebanx.override	op	Exempt a rank from punishment / override exempt players
litebanx.*	op	Grants everything above

---

Configuration highlights

• storage.type — sqlite or mysql, with full HikariCP pool tuning for MySQL
• settings.prefix / settings.legacy-color-codes — MiniMessage or legacy &-code formatting, your choice
• settings.exempt-permission — holders of this node can't be punished (unless the punisher has litebanx.override)
• punishment.ban-ip-on-ban / punishment.ban-offline-ip — automatic IP-ban behavior
• punishment.max-temp-duration — cap non-admin temp punishment lengths
• storage.expiry-check-interval / storage.prune-interval / storage.auto-prune-days — automatic housekeeping for expired and old records

Messages and punishment reason templates live in separate messages.yml and reasons.yml files.

---

Setup

1. Drop LiteBanX.jar into your server's plugins/ folder.
2. Restart the server.
3. Pick a storage backend in config.yml (SQLite works out of the box; MySQL needs connection details).
4. Already running AdvancedBan or LiteBans? Use /litebanx import to migrate your existing data.

---

Requirements & compatibility

• Server: Paper 1.21+ (Purpur works).
• Java: 21 or newer.
• Optional: PlaceholderAPI for punishment-data placeholders.

---

LiteBanX is open-source and MIT-licensed.