LiveBans — Punishment Management Done Right

LiveBans is a modern, high-performance punishment management plugin built with the **exact same database structure as LiteBans**. Whether you're migrating from LiteBans, sharing a database across a network, or starting fresh — LiveBans handles it all.


Why LiveBans?

LiteBans Database Compatible — Uses the same schema, same tables, same field names. Drop it in and it works with your existing LiteBans data instantly.

Developer API Included — Ships with the `litebans.api` package. Any plugin built for the LiteBans API works with LiveBans without modification.

Discord Webhook Integration — Sends color-coded embed notifications to your Discord channel for every punishment action. Red for bans, gold for mutes, yellow for kicks, purple for warnings, green for removals.

Punishment Templates — Define common punishments once in config, apply them with a single command. `/punish Player hacking` — that's it.

Duration Permissions — Control how long each staff rank can punish. Give helpers 1 hour, moderators 7 days, and admins permanent access. All permission-based, no extra config needed.

Fully Async — Every database operation runs off the main thread. Your server TPS stays untouched regardless of how many punishments you process.

HikariCP Connection Pooling — Enterprise-grade database connection management built in. Fast, reliable, handles high concurrency.


Core Features

Punishment Commands
- /ban [-s] <player> [reason] — Permanent ban
- /tempban [-s] <player> <duration> [reason] — Temporary ban
- /unban <player> [reason] — Remove a ban
- /mute [-s] <player> [reason] — Permanent mute
- /tempmute [-s] <player> <duration> [reason] — Temporary mute
- /unmute <player> [reason] — Remove a mute
- /kick [-s] <player> [reason] — Kick a player
- /warn [-s] <player> [reason] — Permanent warning
- /tempwarn [-s] <player> <duration> [reason] — Temporary warning
- /unwarn <player> [reason] — Remove most recent warning
- /banip [-s] <player|ip> [reason] — IP ban
- /unbanip <player|ip> [reason] — Remove IP ban

Staff Tools
- / history <player> — View complete punishment history
- /checkban <player> — Detailed ban status check (UUID + IP bans)
- /banlist [page] — Paginated list of all active bans
- /mutelist [page] — Paginated list of all active mutes
- /staffrollback <staff> [reason] — Revert all active punishments issued by a staff member
- /punish <player> <template> — Apply a predefined punishment template

Admin Commands
- /livebans reload — Reload configuration
- /livebans info — Display plugin information

Silent Mode
Add -s to any punishment command to execute it silently. Only staff members with `livebans.notify` permission will see the action.


Duration Format

Combine any of these units freely:

| Unit | Meaning | Example |
|------|---------|---------|
| `s` | Seconds | `30s` |
| `m` | Minutes | `15m` |
| `h` | Hours | `2h` |
| `d` | Days | `7d` |
| `w` | Weeks | `2w` |
| `mo` | Months | `1mo` |
| `y` | Years | `1y` |

Combined examples: `1d12h`, `2w3d`, `1mo2w5d`

---

Notifications

Discord Webhooks
Every punishment action sends a rich embed to your configured Discord webhook. Each type has its own color for easy scanning. Configure which events to send — enable or disable bans, mutes, kicks, warns, and removals individually.

Staff Alerts
When a player with active mutes or warnings joins the server, online staff members receive an automatic notification. Keeps your team informed without checking manually.

---

Punishment Templates

Define common punishments in your config and apply them instantly:

```yaml
templates:
hacking:
reason: "Using hacked client / unfair advantage"
duration: "30d"
type: ban
silent: false
spam:
reason: "Spamming in chat"
duration: "1h"
type: mute
silent: false
```

Then just run: /punish PlayerName hacking

---

Duration Permissions

Limit punishment durations per rank using permissions:

```
livebans.duration.ban.max.7d — Can ban for max 7 days
livebans.duration.ban.max.30d — Can ban for max 30 days
livebans.duration.mute.max.1h — Can mute for max 1 hour
livebans.duration.ban.permanent — Can permanently ban
livebans.duration.*.permanent — Can use any permanent punishment
```

No duration permissions set? No limit applied. Fully backwards compatible.

---

## Database

Requires MySQL or MariaDB. Uses the LiteBans table structure:
- litebans_bans
- litebans_mutes
- litebans_kicks
- litebans_warnings
- litebans_history
- litebans_servers

Already running LiteBans? Point LiveBans at the same database. It reads and writes the same format — no migration needed.

---

Integration with Other Plugins

Use LiveBans commands from any plugin, GUI menu, or anti-cheat:

```
livebans:ban %player% %reason%
livebans:tempban %player% %duration% %reason%
livebans:mute %player% %reason%
livebans:kick %player% %reason%
livebansunish %player% %template%
```

---

Requirements

- Java 17+
- Spigot or Paper 1.20+
- MySQL or MariaDB database