Home›Java›Mods›AveriaBans
AveriaBans
ModsJava

AveriaBans

Java mod listed for Minecraft 1.20–26.x. Downloads from the MC Java Mods app on Android.

by Kai295 · on Modrinth

⬇ Download on Modrinth
AveriaBans — screenshot 1AveriaBans — screenshot 2AveriaBans — screenshot 3AveriaBans — screenshot 4

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.

a

Highlights


Requirements


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 http://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

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

Bans
Command Aliases Description Permission
/ban <player> [reason] Permanently bans a player. Works for offline players. averiabans.command.ban
/tempban <player> <duration> [reason] Bans a player for a set time. averiabans.command.tempban
/unban <player> /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 <player|ip> [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 <player|ip> <duration> [reason] /tempbanip Temporarily bans an IP address. averiabans.command.tempipban
/unipban <player|ip> /pardon-ip, /pardonip, /unbanip Lifts an active IP ban. averiabans.command.unipban
Mutes
Command Description Permission
/mute <player> [reason] Permanently mutes a player. averiabans.command.mute
/tempmute <player> <duration> [reason] Mutes a player for a set time. averiabans.command.tempmute
/unmute <player> Lifts a player's active mute. averiabans.command.unmute
/ipmute <player|ip> [reason] Permanently mutes everyone on an IP address. averiabans.command.ipmute
/tempipmute <player|ip> <duration> [reason] Temporarily mutes everyone on an IP address. averiabans.command.tempipmute
/unipmute <player|ip> 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 <player> [reason] Gives a player a formal warning, saved to their history. averiabans.command.warn
/kick <player> [reason] Kicks an online player, saved to their history. averiabans.command.kick
Freeze (screenshares)
Command Aliases Description Permission
/freeze <player> /ss Freezes a player, or unfreezes them if already frozen. averiabans.command.freeze
/unfreeze <player> 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 <player> <preset> 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 <player> /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 <timeframe> 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 <player> Shows a player's active ban and mute. averiabans.command.check
/ab history <player> 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 <username> 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

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.

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.
Security Address & port

Configuration

config.yml
strip-bold: true                     # remove bold formatting from all messages
date-format: "yyyy-MM-dd HH:mm:ss"
timezone: ""                         # blank = the server machine's timezone, or e.g. "Europe/London"
block-pm-when-muted: true            # muted players can't /msg, /r, /tell...
appeal-link: "discord.gg/averia"     # shown on ban screens as {appeal_link}

# Take over /ban, /kick, /mute, /banlist... from vanilla and other plugins.
override-other-plugin-commands: true

web-panel:
  enabled: true
  admin-username: ""                 # main admin; sign in with it to set its password
  port: 8085
  bind-address: ""                   # blank = automatic
  session-hours: 12
  detect-public-ip: true

discord:
  enabled: false
  webhook-url: ""

freeze:
  title: "<#E06C75>YOU ARE FROZEN</#E06C75>"
  subtitle: "<#ABB2BF>Do not log out! Check chat.</#ABB2BF>"
  chat-reminder: "<#E06C75>You are currently frozen by staff. Do not disconnect!</#E06C75>"
  reminder-interval-ticks: 60
  allowed-commands: ["/msg", "/r", "/tell", "/w", "/helpop"]
  auto-ban-on-disconnect: true
  auto-ban-duration: "1d"
  auto-ban-reason: "Logged out while frozen"

broadcasts:
  enabled: true
  permission-only: true              # only players with averiabans.broadcast.view see them

alerts:
  alts-join:
    enabled: true

default-reasons:                     # used when staff don't give a reason
  ban: "No Reason"
  mute: "No Reason"
  # ...one entry per punishment type
Duration format
Unit Write as Example
Seconds s, sec, seconds 30s
Minutes m, min, minutes 15m
Hours h, hr, hours 2h
Days d, day, days 7d
Weeks w, week, weeks 2w
Months mo, month, months 1mo
Years y, yr, year 1y

Combine units freely: 1d12h, 2w3d.

Message placeholders

All messages live in messages.yml and support MiniMessage (<#E06C75>, <gradient:...>, <hover:...>), hex colors (&#E06C75) and legacy codes (&c).

Placeholder Description
{prefix} The plugin prefix from messages.yml
{player} / {target} The punished player
{operator} / {staff} The staff member, or "Console"
{reason} Punishment reason
{duration} Original duration
{expires_in} Time remaining
{expires_at} Expiry date
{created_at} Date issued
{id} Punishment ID
{appeal_link} Your appeal link (ban screens)
Discord webhooks

Set discord.enabled: true and paste a webhook URL into discord.webhook-url. AveriaBans posts:


FAQ

Will this conflict with EssentialsX or other ban plugins?

No. With override-other-plugin-commands: true (the default), AveriaBans takes over /ban, /kick, /mute, /pardon and the rest from vanilla and other plugins. The other plugin's version still works with its prefix, e.g. /essentials:ban.

Do I need MySQL or a web host?

No. Everything is stored in a local SQLite file (plugins/AveriaBans/punishments.db), and the web panel runs inside the plugin.

I can't open the web panel.

Check that the port in web-panel.port is open in your firewall, or allocated to your server on your host. The address to use is printed in the console at startup and shown with /ab panel.

I forgot the main admin password.

Run ab panel reset <username> in the server console, then sign in with that username and an empty password to set a new one.

Why is a player's inventory not showing?

Inventories are saved when a player joins or leaves (and every 5 minutes while online). A player who hasn't joined since you installed AveriaBans won't have one saved yet.

Quick facts

Install steps are the general flow for this file type — How to install Minecraft Java mods & modpacks walks through it step by step.

File checked by MCModsHub

These come from our own check of the pack file, not from the source page.

Explore more