AveriaBans

AveriaBans

A clean, modern punishment system for Paper, with a built-in web panel.

Bans, mutes, IP punishments, warnings, kicks, freezes, alt detection, and a password-protected website where your staff team can manage everything from a browser, including viewing any player's inventory exactly like in-game.

Highlights

• Every punishment type: permanent and temporary bans, mutes, IP bans and IP mutes, warnings, kicks and freezes.
• Takes over /ban, /kick, /mute…: AveriaBans overrides vanilla, Essentials and any other plugin that registers the same commands, so your staff always use one system. (Other plugins stay reachable as /essentials:ban etc. Can be turned off.)
• Alt detection: see every account that shared an IP with a player, get alerted when a banned player's alt joins, and review recent alt joins.
• Freeze for screenshares: frozen players can't move, build, fight, use items or run commands. Logging out while frozen can auto-ban them.
• Punishment presets: define reusable presets like hacking or spam and apply them with /punish .
• Built-in web panel: dashboard, punishment search, issue and revoke punishments, player lookup, online players, staff logs, alt alerts. Each staff member has their own account.
• Inventory viewer: see a player's inventory and ender chest drawn like the real Minecraft inventory, with full item tooltips (name, enchantments, lore, attributes). Works for offline players too.
• Staff logs: every ban, mute, unban, freeze and panel login is recorded with who did it and whether it came from in-game, the console or the web panel.
• Discord webhooks: punishments, pardons, freezes and ban-evasion alerts posted to your Discord.
• Fully customizable messages: every message is in messages.yml, with MiniMessage, hex colors and legacy & codes supported.
• Lightweight: local SQLite storage, no external database or web server needed.

Requirements

• Paper (built against 1.20.4)
• Java 21
• For the web panel: one free port on your server (on hosts like Pterodactyl, add an extra port allocation).

Getting started

1. Drop AveriaBans.jar into your plugins folder and start the server.
2. Open plugins/AveriaBans/config.yml and set web-panel.admin-username to the name you want for the main admin account. Change web-panel.port if needed.
3. Run /ab reload (or restart). The console prints the web panel address, for example 203.0.113.5:8085. Staff can see it any time with /ab panel.
4. Open the panel, type your admin username, leave the password empty, and press Sign in. You'll be asked to choose a password. Do this straight away, before anyone else can.
5. Add your staff on the panel's Staff accounts page. Each person signs in with their username and an empty password the first time, and chooses their own password.

Commands

` · [optional] · Durations look like 30m, 2h, 7d, 1mo, 1y or combined like 1d12h`.

Bans

Command · Aliases · Description · Permission
/ban [reason] · Permanently bans a player. Works for offline players. · averiabans.command.ban
/tempban [reason] · Bans a player for a set time. · averiabans.command.tempban
/unban · /pardon · Lifts a player's active ban. · averiabans.command.unban
/banlist [players\ · ips] [page] · /bans · Lists all active bans, 8 per page. Hover an entry for details, click it to unban. · averiabans.command.banlist

Banned players see a kick screen with the reason, who banned them, the expiry and your appeal link.

IP bans

Command · Aliases · Description · Permission
/ipban [reason] · /ban-ip, /banip · Permanently bans an IP address (a player's last known IP, or a raw IP). Kicks everyone online from that IP. · averiabans.command.ipban
/tempipban [reason] · /tempbanip · Temporarily bans an IP address. · averiabans.command.tempipban
/unipban · /pardon-ip, /pardonip, /unbanip · Lifts an active IP ban. · averiabans.command.unipban

Mutes

Command · Description · Permission
/mute [reason] · Permanently mutes a player. · averiabans.command.mute
/tempmute [reason] · Mutes a player for a set time. · averiabans.command.tempmute
/unmute · Lifts a player's active mute. · averiabans.command.unmute
/ipmute [reason] · Permanently mutes everyone on an IP address. · averiabans.command.ipmute
/tempipmute [reason] · Temporarily mutes everyone on an IP address. · averiabans.command.tempipmute
/unipmute · Lifts an active IP mute. · averiabans.command.unipmute

Muted players can't chat. With block-pm-when-muted: true they also can't use /msg, /tell, /w, /whisper, /r, /reply, /me or /say.

Warnings & kicks

Command · Description · Permission
/warn [reason] · Gives a player a formal warning, saved to their history. · averiabans.command.warn
/kick [reason] · Kicks an online player, saved to their history. · averiabans.command.kick

Freeze (screenshares)

Command · Aliases · Description · Permission
/freeze · /ss · Freezes a player, or unfreezes them if already frozen. · averiabans.command.freeze
/unfreeze · Unfreezes a player. · averiabans.command.unfreeze

Frozen players see a title and regular chat reminders. They can't move, break or place blocks, attack, interact, drop or pick up items, or use their inventory. Only the commands in freeze.allowed-commands work (by default /msg, /r, /tell, /w and /helpop). If they log out while frozen, staff are alerted and, with auto-ban-on-disconnect, they are banned automatically (1 day by default).

Punishment presets

Command · Description · Permission
/punish · Applies a preset from premade-punishments in config.yml. · averiabans.command.punish

premade-punishments:
hacking:
type: TEMP_BAN
duration: "7d"
reason: "Cheating / Unfair Advantage"
spam:
type: TEMP_MUTE
duration: "30m"
reason: "Chat Spam / Flooding"
advertising:
type: IP_MUTE
reason: "Malicious Advertising"

Types: BAN, IP_BAN, MUTE, IP_MUTE, KICK, WARN (TEMP_BAN, TEMP_MUTE etc. also work). Add a duration for a temporary punishment, or leave it out for a permanent one.

Alt accounts

Command · Aliases · Description · Permission
/alts · /alt, /dupeip · Lists every account that has shared an IP with this player, colored by status: online, offline, banned or IP-banned. · averiabans.command.alts
/recentalts · Shows alt-account joins within a timeframe, e.g. /recentalts 24h. Useful for catching evasion that happened while staff were offline. · averiabans.command.recentalts

When a player joins sharing an IP with other accounts, staff with averiabans.alerts.alts get an alert. If one of those accounts is banned, it's flagged as possible ban evasion and sent to Discord.

Admin (/averiabans, /ab)

Command · Description · Permission
/ab help · Shows the command list. · averiabans.command.help
/ab check · Shows a player's active ban and mute. · averiabans.command.check
/ab history · Shows a player's last 10 punishments. · averiabans.command.history
/ab panel · Shows the clickable web panel address. · averiabans.command.panel
/ab reload · Reloads config.yml and messages.yml and restarts the web panel. · averiabans.command.reload
ab panel reset · Console only. Clears a web panel account's password so its owner sets a new one at their next sign-in. Use this if the main admin forgets their password. · Console

Permissions

Everything defaults to OP except averiabans.command.help (everyone) and the bypass permissions (nobody). Give staff averiabans.admin for everything, or pick individual permissions below.

Group permission

Permission · Description
averiabans.admin · Every command, alert and broadcast permission below (not the bypass permissions).

Command permissions

Permission · Allows
averiabans.command.ban · /ban
averiabans.command.tempban · /tempban
averiabans.command.unban · /unban
averiabans.command.banlist · /banlist
averiabans.command.ipban · /ipban
averiabans.command.tempipban · /tempipban
averiabans.command.unipban · /unipban
averiabans.command.mute · /mute
averiabans.command.tempmute · /tempmute
averiabans.command.unmute · /unmute
averiabans.command.ipmute · /ipmute
averiabans.command.tempipmute · /tempipmute
averiabans.command.unipmute · /unipmute
averiabans.command.warn · /warn
averiabans.command.kick · /kick
averiabans.command.freeze · /freeze
averiabans.command.unfreeze · /unfreeze
averiabans.command.punish · /punish
averiabans.command.alts · /alts
averiabans.command.recentalts · /recentalts
averiabans.command.check · /ab check
averiabans.command.history · /ab history
averiabans.command.panel · /ab panel
averiabans.command.reload · /ab reload
averiabans.command.help · /ab help (default: everyone)

Alerts & broadcasts

Permission · Description
averiabans.broadcast.view · See punishment broadcasts when broadcasts.permission-only is on.
averiabans.alerts.alts · Get alerts when a player joins with alt accounts or evades a ban.
averiabans.alerts.freeze · Get alerts when a frozen player logs out.

Bypass (immunity)

These default to nobody, not even OPs. Console can always punish anyone.

Permission · Immune to
averiabans.bypass.ban · Bans
averiabans.bypass.mute · Mutes
averiabans.bypass.kick · Kicks
averiabans.bypass.freeze · Freezing
averiabans.bypass.warn · Warnings
averiabans.bypass.* · All of the above

Web panel

What's in the panel

• Dashboard: active bans and mutes, punishments in the last 24 hours, players online, top staff and latest staff activity.
• Punishments: search by player, IP, staff member or reason; filter by type and status; unban or unmute in one click.
• New punishment: ban, temp-ban, mute, temp-mute, IP-ban, IP-mute, warn or kick from the browser.
• Player lookup: active ban or mute, full history, known IPs, alt accounts with their ban status, and the player's inventory and ender chest.
• Online players: world, ping and IP, with freeze, kick and punish buttons.
• Staff logs: a searchable record of every staff action from in-game, the console and the panel.
• Alt alerts: the history of alt-account join detections.
• Staff accounts (main admin only): add staff, reset their passwords, or remove them.

Punishments from the panel work exactly like the in-game commands: players are kicked, broadcasts and Discord webhooks fire, and the staff member's panel username is recorded as who issued it.

Inventory viewer

The player lookup page shows the player's inventory and ender chest drawn like the real Minecraft screens: armor slots, offhand, player model, hotbar, stack counts, durability bars and the enchantment glint. Hover (or tap on mobile) any item to see its exact in-game tooltip, including custom names, enchantments, lore, attributes and potion effects.

• Online players: shows their live inventory.
• Offline players: shows the last saved copy, taken when they join, when they leave, and every 5 minutes while online.

Item icons, player heads and the pixel font load from the Minecraft Wiki, mcasset.cloud, mc-heads.net and Google Fonts in the viewer's browser.

Staff accounts & roles

Account · Can do
Main admin (set by web-panel.admin-username) · Everything, including managing staff accounts.
Staff (created by the main admin in the panel) · Everything except managing accounts.

• New accounts have no password. The person signs in with their username and an empty password, and chooses their own.
• Add accounts right before you share them: until a password is set, anyone who knows the username could set it first.
• The main admin can reset a staff member's password; they choose a new one at their next sign-in.
• Forgot the main admin password? Run ab panel reset in the console.
• To change the main admin, change admin-username and /ab reload. The previous main admin becomes a regular staff account.

Security

• Passwords are stored as salted PBKDF2 hashes in the database, never in config.yml.
• 5 wrong passwords from one IP locks that IP out for 10 minutes.
• Resetting a password or deleting an account signs that p