> For the complete documentation index, see [llms.txt](https://lethium.gitbook.io/lethium-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://lethium.gitbook.io/lethium-docs/server-setup/staff-moderation.md).

# Staff moderation: LethiumBans

LethiumBans: bans, mutes, warnings, templates, reports, staff mode and every staff permission.

Product page: [LethiumBans on BuiltByBit](https://builtbybit.com/resources/lethiumbans-staff-analytics-punish.108890/).

Files (the folder, the jar `DonutBans-2.2.2` and the permission nodes `donutban.*` keep the plugin's original name): `plugins/DonutBans/config.yml`, `templates.yml`, `messages.yml`, `identities.yml` (created on the first start). Apply changes with **`/donutban reload`**.

**LethiumBans** is included in the Clicker package. It is a full **punishment and staff suite**: bans, mutes, kicks, warnings, history, evidence, notes, reports, freeze, staff mode, vanish, invsee, alt detection, bait spawners for x-ray hunting, chat controls and staff chat. It replaces the vanilla `/ban`, `/kick`, `/gamemode` and more.

{% hint style="danger" %}
**Set these before launch** in `config.yml`:

* `license.key`: your LethiumBans license key.
* `server_name`: a short id for this server (default `donut1`). Used to scope punishments on a network.
* `appeal_url`: shown on ban screens (default `https://discord.gg/your-server`). Put your real appeal link.
  {% endhint %}

### Who can do what

Every command has a permission `donutban.<name>`, and **operators have them all by default**. Give staff ranks their nodes in LuckPerms, for example:

```
/lp group helper permission set donutban.staff true
/lp group helper permission set donutban.mute true
/lp group helper permission set donutban.warn true
/lp group mod permission set donutban.ban true
```

| Permission                                                           | Lets staff                                                   |
| -------------------------------------------------------------------- | ------------------------------------------------------------ |
| `donutban.staff`                                                     | Receive silent staff alerts and bypass cooldowns.            |
| `donutban.staff.broadcast.receive`                                   | Receive punishment broadcasts.                               |
| `donutban.ban`, `tempban`, `unban`, `banip`, `unbanip`               | Ban commands.                                                |
| `donutban.mute`, `unmute`                                            | Mute.                                                        |
| `donutban.kick`, `warn`, `unwarn`                                    | Kick and warn.                                               |
| `donutban.history`, `staffhistory`, `activity`                       | Look at history.                                             |
| `donutban.clearhistory`, `wipe`                                      | **Destructive.** Delete history or all data. Only top staff. |
| `donutban.editreason`, `evidence`, `notes`                           | Edit reasons, attach evidence, write notes.                  |
| `donutban.punish`, `donutban.template.<id>`                          | Use the punish GUI and each punishment template.             |
| `donutban.report`                                                    | **Everyone** can `/report`.                                  |
| `donutban.reports`                                                   | See and close reports.                                       |
| `donutban.freeze`, `check`                                           | Freeze a player and open the check GUI.                      |
| `donutban.invsee`, `invsee.edit`                                     | View (and edit) inventories and ender chests.                |
| `donutban.alts`, `lookup`, `lookup.ip`                               | Alt list and player lookup (IPs need the extra node).        |
| `donutban.vanish`, `vanish.see`, `staffmode`, `panel`                | Vanish, staff mode, staff panel.                             |
| `donutban.staffchat`, `adminchat`                                    | Staff chat channels.                                         |
| `donutban.chatlock`, `slowmode`, `clearchat` (+ `.bypass`)           | Chat controls.                                               |
| `donutban.gamemode.*`                                                | `/gm` shortcuts.                                             |
| `donutban.msg`, `helpop`                                             | **Everyone by default**: private messages and `/helpop`.     |
| `donutban.admin`                                                     | `/donutban reload`.                                          |
| `donutban.exempt` (and `.ban.exempt`, `.mute.exempt` ...)            | **Immune** to punishment. Give to top staff. Default off.    |
| `donutban.override`                                                  | Replace an active punishment instead of "already punished".  |
| `donutban.ban.max.<tier>`, `tempmute.max.<tier>`, `banip.max.<tier>` | Duration limits (below).                                     |

### Commands

| Area            | Commands                                                                                                                                                        |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Bans            | `/ban`, `/tempban <player> <duration>`, `/unban`, `/banip`, `/unbanip`                                                                                          |
| Mutes and chat  | `/mute` (`/tempmute`), `/unmute`, `/chatlock`, `/slowmode`, `/clearchat`, `/voicemute`                                                                          |
| Kicks and warns | `/kick`, `/warn`, `/unwarn`                                                                                                                                     |
| Templates       | `/punish <player> [template]` (GUI), `/offend <player> <template>` (escalating)                                                                                 |
| History         | `/history`, `/historygui`, `/banhistory`, `/mutehistory`, `/kickhistory`, `/warnhistory`, `/ipbanhistory`, `/staffhistory`, `/activity`, `/punishmentinfo <id>` |
| Edit            | `/editreason <id> <text>`, `/addevidence <id> <text or link>`, `/clearhistory`, `/wipe`, `/activepunish <player>`                                               |
| Notes           | `/notes`, `/notesgui`, `/addnote`, `/removenote`                                                                                                                |
| Reports         | `/report <player> <reason>` (everyone), `/reports`, `/reportsgui`, `/closereport`                                                                               |
| Investigation   | `/check`, `/freeze` (`/ss`), `/tempfreeze`, `/unfreeze`, `/lookup`, `/alts`, `/invsee`, `/echest`, `/sus`                                                       |
| Staff tools     | `/staffmode` (`/sm`), `/vanish` (`/v`), `/panel`, `/staffchat` (`/sc`), `/adminchat` (`/ac`), `/gamemode`, `/gmc`, `/gms`, `/gma`, `/gmsp`                      |
| Messaging       | `/msg`, `/reply`, `/msgtoggle`, `/msgblock`, `/msgunblock`, `/ignore`, `/helpop`, `/helpopmute`, `/spychat`                                                     |
| Cheat hunting   | `/bait`, `/spawnstash`, `/fakespawner`, `/fakeflag`, `/fakejoin`, `/fakeleave`, `/fakeplayer`, `/totempop`                                                      |
| Admin           | `/donutban reload`                                                                                                                                              |

Add `-s` to a punishment command to make it **silent** (only staff see it).

### Punishment templates (`templates.yml`)

A template is a named punishment with an **escalation ladder**. Each time a player is punished with it, the next, harsher duration is used.

```yaml
templates:
  xray:
    display: "X-Ray / Texture Pack"
    type: BAN
    permission: donutban.template.xray
    icon: DIAMOND_ORE
    reason: "Using X-Ray or a prohibited resource pack"
    durations:
      - 7d
      - 14d
      - 30d
      - 90d
      - permanent
```

| Key                         | Meaning                                                                       |
| --------------------------- | ----------------------------------------------------------------------------- |
| `type`                      | `BAN`, `IPBAN`, `MUTE`, `KICK` or `WARN`.                                     |
| `permission`                | Who can use it. Default `donutban.template.<id>`.                             |
| `durations`                 | First offence first. The last entry repeats. `permanent` or `-1` for forever. |
| `display`, `icon`, `reason` | How it shows in the GUI and on the ban screen.                                |

The shipped templates cover cheating, hacked client, x-ray, autoclicker, baritone, botting, anticheat evasion, ban evasion, alt abuse, scamming, exploiting, bug abuse, advertising and inappropriate skins. Use `/punish <player>` to pick one from a menu, or `/offend <player> <template>`.

### Safety rails in `config.yml`

| Setting                                            | Meaning                                                                                                                                                                                                                                                                                                |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `punishments.enabled`                              | Kill switch for every punishment.                                                                                                                                                                                                                                                                      |
| `unban.also_unban_ip`                              | Unbanning also removes the IP ban.                                                                                                                                                                                                                                                                     |
| `punish-guard.immunity.enabled`                    | Players with the `donutban.exempt` permissions cannot be punished.                                                                                                                                                                                                                                     |
| `punish-guard.duration-limits`                     | Staff can only give **temporary** punishments up to the largest `donutban.<key>.max.<tier>` they hold. Tiers: `1h, 6h, 12h, 1d, 3d, 1w, 2w, 1m, 3m, 1y`, or `unlimited`. `default-tier: "1h"` applies when they hold none. `exempt-templates: true` lets a template's own permission override the cap. |
| `ban_evasion.enabled`                              | New accounts on a banned player's IP are banned with `duration: match`.                                                                                                                                                                                                                                |
| `history_limit`                                    | History entries kept per view (50).                                                                                                                                                                                                                                                                    |
| `lookup.max_ips`, `max_alts`, `recent_punishments` | What `/lookup` shows.                                                                                                                                                                                                                                                                                  |
| `sfmode.*`                                         | Staff mode: vanishes on enter, hotbar tools, blocks damage and pickup, returns you to your old location on exit. `required_commands` must be used **in staff mode**.                                                                                                                                   |
| `storage.type`                                     | `sqlite` (default), `mysql`, `mariadb`, `postgresql` or `mongodb`.                                                                                                                                                                                                                                     |
| `sync.enabled`                                     | Cross-server punishments. Needs a shared database.                                                                                                                                                                                                                                                     |

### How it fits with the rest of the setup

* It depends on nothing, but softly connects to PlaceholderAPI, floodgate (Bedrock names), LPC and FancyNpcs.
* **Overlapping commands:** EssentialsX also has `/msg`, `/reply`, `/msgtoggle`, `/invsee`, `/vanish` and `/gamemode`. Only one plugin can own each name. If a command behaves unexpectedly, see Troubleshooting.
* **EasyCommandBlocker** limits which commands players see when they press Tab (see [Security and utilities](/lethium-docs/server-setup/security-and-utilities.md)). Staff commands are not in the default list, so they need their own EasyCommandBlocker group to auto-complete.
* Ban screens, punishment messages and the GUI text are in `messages.yml`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://lethium.gitbook.io/lethium-docs/server-setup/staff-moderation.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.