NeoBans

# NeoBans

A server-side punishment management mod for **Minecraft 1.21.1** running **NeoForge 21.1.x**.

Adds a full suite of ban, mute, kick, and warn commands along with an in-game GUI for staff to issue punishments. All punishment history is stored on the server and persists across restarts. **Players do not need the mod installed to join** — it is only required on the client if staff want to use the GUI.

---

## Features

- Permanent and temporary bans (player and IP)
- Permanent and temporary mutes
- Kick and warn commands
- In-game ban GUI with configurable preset reasons and durations (requires mod on staff client)
- Full punishment history per player
- Server-side ban list browser
- Fully configurable ban disconnect message with placeholder support
- Optional appeal link appended to ban messages
- Data stored as JSON in the world folder — no database required

---

## Requirements

| Requirement | Version |
|---|---|
| Minecraft | 1.21.1 |
| NeoForge | 21.1.x (tested on 21.1.222) |
| Java | 21 |

The mod is **server-side only**. Players without NeoBans can connect normally. Staff who want the `/ban` GUI need the mod on their client as well.

---

## Installation

1. Download the NeoBans `.jar` file.
2. Place it in your server's `mods/` folder.
3. Start the server once to generate the config file.
4. Edit `world/serverconfig/neobans-server.toml` to your liking (see [Configuration](#configuration) below).
5. Restart the server (or use `/reload` — the config will reload automatically).

For staff who want the GUI, they also place the same `.jar` in their client `mods/` folder.

---

## Commands

All commands require operator permission level 2 or higher.

### Ban

| Command | Description |
|---|---|
| `/ban` | Opens the player-select GUI (requires mod on client) |
| `/ban <player> [reason]` | Permanently bans a player |
| `/ban-ip <player\|ip> [reason]` | Permanently IP-bans a player or raw IP address |
| `/tempban <player> <duration> [reason]` | Temporarily bans a player |
| `/tempban-ip <player\|ip> <duration> [reason]` | Temporarily IP-bans a player or raw IP |
| `/unban <player>` | Pardons a player's active ban |

### Mute

| Command | Description |
|---|---|
| `/mute <player> [reason]` | Permanently mutes a player |
| `/tempmute <player> <duration> [reason]` | Temporarily mutes a player |
| `/unmute <player>` | Removes a player's active mute |

### Other

| Command | Description |
|---|---|
| `/kick <player> [reason]` | Kicks a player from the server |
| `/warn <player> <reason>` | Issues a formal warning |
| `/history <player>` | Opens the punishment history GUI for a player |
| `/banlist` | Opens the active ban list GUI |

### Duration format

Used by `/tempban`, `/tempban-ip`, and `/tempmute`.

| Suffix | Meaning |
|---|---|
| `m` | Minutes — e.g. `30m` |
| `h` | Hours — e.g. `2h` |
| `d` | Days — e.g. `7d` |
| `w` | Weeks — e.g. `2w` |
| `M` | Months — e.g. `1M` |
| `y` | Years — e.g. `1y` |
| `permanent` | No expiry |

---

## Configuration

The config file is generated at:

```
<world folder>/serverconfig/neobans-server.toml
```

### Options

#### `banReasons`

List of preset reasons shown in the `/ban` GUI. Editable without restarting — changes take effect the next time a staff member opens the GUI.

```toml
banReasons = [
    "Griefing",
    "Hacking / Cheating",
    "Harassment",
    "Inappropriate Content",
    "Spam",
    "Exploiting",
    "Racism / Hate Speech",
    "Other"
]
```

#### `appealLink`

URL shown at the bottom of every ban disconnect message. Set to `""` to hide the appeal line entirely.

```toml
appealLink = "https://your-server.com/appeal"
```

#### `banMessage`

The full disconnect message shown to a banned player. Supports Minecraft colour codes (`§` or `&`). Use `\n` for newlines.

```toml
banMessage = "§c§lYou are banned from this server!\n\n§fReason: §e{reason}\n§fBanned by: §e{banned_by}\n§fExpires: §e{expires}\n\n§7Punishment ID: {id}\n\n§eAppeal your ban: §b{appeal_link}"
```

**Available placeholders:**

| Placeholder | Value |
|---|---|
| `{reason}` | The ban reason |
| `{banned_by}` | The staff member who issued the ban |
| `{expires}` | `Permanent` or a human-readable time remaining (e.g. `3d 2h 15m`) |
| `{id}` | The internal punishment ID |
| `{appeal_link}` | The appeal URL — the **entire line** is removed if `appealLink` is empty |

---

## Data Storage

Punishments are saved to:

```
<world folder>/neobans/punishments.json
```

This file is written on every punishment action and on server shutdown. It is safe to back up while the server is running.

---

## Permissions

NeoBans uses NeoForge's built-in permission API. Each command has its own permission node so you can grant or deny them individually using a permissions mod such as [LuckPerms](https://luckperms.net/).

**If no permissions mod is installed**, every node falls back to vanilla operator level 2 — the behaviour is identical to before.

### Permission nodes

| Node | Commands |
|---|---|
| `neobans.ban` | `/ban`, `/ban-ip` |
| `neobans.tempban` | `/tempban`, `/tempban-ip` |
| `neobans.unban` | `/unban`, `/unban-ip` |
| `neobans.mute` | `/mute` |
| `neobans.tempmute` | `/tempmute` |
| `neobans.unmute` | `/unmute` |
| `neobans.kick` | `/kick` |
| `neobans.warn` | `/warn` |
| `neobans.history` | `/history` |
| `neobans.banlist` | `/banlist` |

Console always bypasses permission checks and has access to all commands.

### LuckPerms example

```bash
# Give a group access to kick and warn only
/lp group moderator permission set neobans.kick true
/lp group moderator permission set neobans.warn true

# Give a group full access
/lp group admin permission set neobans.* true
```

---