BetterBans

# BetterBans - Professional Punishment Management

  

---

## Overview

BetterBans is a lightweight, high-performance punishment management plugin built for production servers and large networks. It features a fully async architecture, configurable offense ladders, pluggable storage, and complete MiniMessage support for every player-facing message.

No bloat. No lag. No deprecated APIs. Just clean, reliable punishment management.

---

## Features

**Core Punishments**
- Permanent and temporary bans
- Permanent and temporary mutes
- Kick with custom reason
- Full punishment history tracking

**Offense Ladder System**
- Define custom offense types (hacking, spam, toxicity, etc.)
- Each offense has a configurable escalation ladder
- Automatic punishment escalation on repeated violations
- Optional auto-reset after a configurable number of days

**Configurable Storage**
- **MySQL / MariaDB** with HikariCP connection pooling
- **Local JSON file** storage for smaller servers
- Automatic fallback to file storage if the database is unreachable

**Fully Customizable Messages**
- Every message, screen, and notification is configurable
- Full [MiniMessage]( https://docs.advntr.dev/minimessage/format.html) formatting support (colors, gradients, hover, click)
- Multi-line ban/kick disconnect screens
- Placeholders: `{player}`, `{staff}`, `{reason}`, `{duration}`, `{expires}`, `{offense}`, `{count}`
- Optional `{center}` prefix to center lines in chat

**Performance**
- Async-first design -- zero database calls on the main thread
- Thread-safe in-memory cache for instant ban/mute checks
- Ban checks on `AsyncPlayerPreLoginEvent` (before the player fully joins)
- Mute checks on Paper's `AsyncChatEvent`
- Lazy and eager expiration of temporary punishments

---

## Commands

| Command | Description | Permission |
|---|---|---|
| `/ban <player> <reason>` | Permanently ban a player | `betterbans.ban` |
| `/tempban <player> <duration> <reason>` | Temporarily ban a player | `betterbans.tempban` |
| `/kick <player> <reason>` | Kick a player from the server | `betterbans.kick` |
| `/mute <player> <reason>` | Permanently mute a player | `betterbans.mute` |
| `/tempmute <player> <duration> <reason>` | Temporarily mute a player | `betterbans.tempmute` |
| `/unban <player>` | Unban a player | `betterbans.unban` |
| `/unmute <player>` | Unmute a player | `betterbans.unmute` |
| `/offend <player> <offense>` | Apply an offense (escalating ladder) | `betterbans.offend` |
| `/betterbans reload` | Reload all configuration files | `betterbans.reload` |

All commands support full **tab completion**, **console usage**, and **custom feedback messages**.

---

## Duration Format

Durations are flexible and support compound values:

`30m` `1h` `6h` `12h` `1d` `3d` `7d` `30d` `1d12h` `7d6h30m`

Supported units: `s` (seconds), `m` (minutes), `h` (hours), `d` (days), `w` (weeks), `mo` (months), `y` (years)

---

## Permissions

| Permission | Description | Default |
|---|---|---|
| `betterbans.ban` | Use /ban | OP |
| `betterbans.tempban` | Use /tempban | OP |
| `betterbans.kick` | Use /kick | OP |
| `betterbans.mute` | Use /mute | OP |
| `betterbans.tempmute` | Use /tempmute | OP |
| `betterbans.unban` | Use /unban | OP |
| `betterbans.unmute` | Use /unmute | OP |
| `betterbans.offend` | Use /offend | OP |
| `betterbans.reload` | Use /betterbans reload | OP |
| `betterbans.notify` | Receive staff punishment broadcasts | OP |
| `betterbans.bypass.mute` | Bypass mute restrictions | false |

---

## Offense Ladder Example

Define offense types in `offenses.yml` with escalating punishments:

```yaml
offenses:
hacking:
display-name: "Hacking"
reset-after-days: -1
steps:
- type: TEMP_BAN
reason: "Hacking - 1st Offense"
duration: "30d"
- type: BAN
reason: "Hacking - Permanent"

chat-spam:
display-name: "Chat Spam"
reset-after-days: 30
steps:
- type: TEMP_MUTE
reason: "Chat Spam - Warning"
duration: "10m"
- type: TEMP_MUTE
reason: "Chat Spam - 2nd Offense"
duration: "1h"
- type: TEMP_BAN
reason: "Chat Spam - 3rd Offense"
duration: "1d"
- type: BAN
reason: "Chat Spam - Permanent"
```

Use `/offend <player> hacking` and the plugin automatically applies the correct step based on how many times the player has been reported.

---

## Message Customization

Every screen and message is fully configurable in `messages.yml`:

```yaml
ban-screen:
- "<red><bold>You are permanently banned</bold></red>"
- ""
- "<gray>Reason:</gray> <white>{reason}</white>"
- "<gray>Banned by:</gray> <white>{staff}</white>"

tempban-screen:
- "<red><bold>You are temporarily banned</bold></red>"
- ""
- "<gray>Reason:</gray> <white>{reason}</white>"
- "<gray>Expires:</gray> <white>{expires}</white>"

mute-message:
- "<red>You are permanently muted.</red>"
- "<gray>Reason:</gray> <white>{reason}</white>"
```

---

## Storage Configuration

**File Storage (default)**
```yaml
storage:
type: FILE
```

**MySQL / MariaDB**
```yaml
storage:
type: MYSQL
mysql:
host: localhost
port: 3306
database: betterbans
username: root
password: "your_password"
pool-size: 10
```

Tables are created automatically on first startup. If the database connection fails, the plugin falls back to local file storage automatically.

---

## Installation

1. Drop `BetterBans.jar` into your `plugins/` folder.
2. Start the server.
3. Configure `plugins/BetterBans/config.yml`, `messages.yml`, and `offenses.yml` to your liking.
4. Run `/betterbans reload` or restart the server.

---

## Requirements

- **PaperMC 1.21.1** (or compatible fork)
- **Java 17+**

---

## Support

Found a bug or have a feature request? Leave a message in the discussion tab or send a private message.