LightBans

Professional, lightweight moderation plugin for Paper & Spigot servers.

---

⚡ What is LightBans?

LightBans is a modern, fully-featured punishment management plugin designed to give server administrators complete control over player moderation — without the bloat. Built with performance in mind, LightBans runs fully async database operations so your server's TPS stays untouched.

Whether you're running a small SMP or a large network, LightBans provides every tool you need to keep your community safe.

---

🛡️ Features

Punishment Types

• Ban — Permanently or temporarily ban players from your server
• Temp Ban — Issue time-limited bans with flexible duration formats
• IP Ban — Ban by IP address to prevent alt account evasion
• Mute — Silence players permanently or temporarily
• Temp Mute — Time-limited mutes with remaining time tracking
• IP Mute — Mute by IP address across all accounts
• Kick — Instantly remove players from the server
• Softban — Ban, clear data, kick, and immediately unban a player
• Blacklist — Permanent, irrevocable blacklist with data removal

📋 Moderation Tools

• /history <player> — View a player's full punishment history
• /check <player> — See all currently active punishments
• /lightbans reload — Hot-reload configuration without restarting

🗄️ Database Support

• SQLite — Zero-configuration, works out of the box
• MySQL — Full MySQL support with HikariCP connection pooling for high-performance servers

🎨 Rich Color Support

LightBans supports multiple color formats in all messages:

• MiniMessage — <red>, <gradient:#ff0000:#00ff00>, <color:#ff6b6b>
• Legacy — &c, &a, &l, and all classic formatting codes
• Hex — &#ff6b6b, &#00ccff
• RGB — rgb(255,107,107)

🔊 Sound Effects

Every punishment type comes with configurable sound effects — toggle them on or off, and customize the sound, volume, and pitch for each action.

📢 Public Broadcasts

Optionally broadcast punishments to the entire server. When a player gets banned, muted, or kicked, everyone knows. Fully configurable and can be disabled per your preference.

🔔 Staff Alerts

Staff members with the lightbans.admin permission receive detailed alerts for every moderation action, including who issued the punishment and why.

✏️ Fully Customizable Messages

Every single message — ban screens, kick screens, mute notifications, staff alerts, error messages, and more — is fully configurable through messages.yml. Personalize every interaction to match your server's brand.

---

📎 Commands

| Command | Description | Permission |
|---------|-------------|------------|
| /ban <player> [duration] <reason> | Ban a player (permanent or temporary) | lightbans.ban |
| /tempban <player> <duration> <reason> | Temporarily ban a player | lightbans.tempban |
| /ipban <player> [duration] <reason> | IP ban a player | lightbans.ipban |
| /mute <player> [duration] <reason> | Mute a player | lightbans.mute |
| /tempmute <player> <duration> <reason> | Temporarily mute a player | lightbans.tempmute |
| /muteip <player> [duration] <reason> | IP mute a player | lightbans.muteip |
| /kick <player> <reason> | Kick a player | lightbans.kick |
| /softban <player> <reason> | Softban a player | lightbans.softban |
| /blacklist <player> <reason> | Permanently blacklist a player | lightbans.blacklist |
| /unban <player> | Unban a player | lightbans.unban |
| /unmute <player> | Unmute a player | lightbans.unmute |
| /unblacklist <player> | Remove from blacklist | lightbans.unban |
| /history <player> | View punishment history | lightbans.history |
| /check <player> | Check active punishments | lightbans.history |
| /lightbans reload | Reload configuration | lightbans.admin |

All commands also have /l prefix aliases (e.g., /lban, /lkick) to avoid conflicts with other plugins.

---

⏱️ Duration Format

Use any of the following for temporary punishments:

| Format | Meaning |
|--------|---------|
| 10m | 10 minutes |
| 5h | 5 hours |
| 2d | 2 days |
| 3w | 3 weeks |
| 1mo | 1 month |
| 1y | 1 year |

---

🔑 Permissions

| Permission | Description |
|------------|-------------|
| lightbans.admin | Full access to all LightBans commands |
| lightbans.ban | Allow banning players |
| lightbans.tempban | Allow temporarily banning players |
| lightbans.ipban | Allow IP banning players |
| lightbans.mute | Allow muting players |
| lightbans.tempmute | Allow temporarily muting players |
| lightbans.muteip | Allow IP muting players |
| lightbans.kick | Allow kicking players |
| lightbans.softban | Allow softbanning players |
| lightbans.blacklist | Allow blacklisting players |
| lightbans.unban | Allow unbanning & unblacklisting players |
| lightbans.unmute | Allow unmuting players |
| lightbans.history | Allow viewing punishment history & checks |
| lightbans.reload | Allow reloading the plugin |

---

⚙️ Requirements

• Server: Paper or Spigot (1.21+)
• Java: 17 or higher
• No dependencies required — everything is built-in

---

🚀 Why LightBans?

• Lightweight — Minimal resource usage, designed for performance
• Async everything — All database operations run off the main thread
• Essentials compatible — Automatically overrides conflicting commands from Essentials
• Modern — Built with Adventure API and MiniMessage support
• No bloat — Does one thing and does it well: moderation
• Easy setup — Drop the JAR in your plugins folder and go. Zero configuration required.

---

💬 Support

Found a bug or have a suggestion? Open an issue on the discord page — feedback is always welcome!

---