# Banning

Staff++ overrides the default ban command with its own `ban` command. Next to the permanent ban command it also adds the `tempban` command. With every ban a reason must be given why this player is getting banned.

## Configuration

```yaml
ban-module:
    # Whether or not the plugin will use "/ban-player" features.
    enabled: true
    permban-template: ''
    tempban-template: ''
    # List of staff ranks. Ordered from low to highest rank.
    # when configured, staff members can only ban player with a lower rank.
    ranks: []
    appeals:
        enabled: true
        unban-on-approve: true
        resolve-reason-enabled: false
        fixed-reason: false
        reasons:
            - ''
```

### Commands

| Command                                        | Description                                            |
| ---------------------------------------------- | ------------------------------------------------------ |
| /ban \[player] \[reason]                       | Permanently ban a player                               |
| /tempban \[player] \[amount] \[unit] \[reason] | Temporary ban a player the given duration              |
| /ban-extend \[player] \[amount] \[unit]        | Extend the ban duration of a temporarily banned player |
| /ban-reduce \[player] \[amount] \[unit]        | Reduce the ban duration of a temporarily banned player |
| /unban \[player] \[reason]                     | Unban a player from the server                         |
| /manage-bans                                   | Opens the bans overview GUI                            |

### Permanent banning

`/ban [player] [reason]`

```
/ban playername He was bothering me
```

### Temporary banning

`/tempban [player] [amount] [unit] [reason]`

```
/tempban playername 15 MINUTE He was bothering me
```

The duration of the tempban is specified by \[amount] \[unit]

Amount must be a positive number > 0 and unit must be one of the following:

* SECOND
* MINUTE
* HOUR
* DAY
* WEEK
* MONTH
* YEAR

#### Restricting tempban duration

The tempban command can also be configured to restrict the duration a staff member can use for a ban.\
Give the staff member and extra permission with a duration limit as suffix. Example: `staff.bans.tempban.limit.2w` , with this permission a staff member can only issue a ban for a maximum duration of 2 weeks.

{% hint style="warning" %}
A staff member must have both permissions to use the command. So for a 2 week duration limit the permissions needed are:

* `staff.bans.tempban`
* `staff.bans.tempban.limit.2w`
  {% endhint %}

**Possible time values:**

* s = second
* m = minute
* h = hour
* d = day
* w = week
* M = month
* y = year

*Time values cannot be combined. For example this is invalid: ".1m30s" instead type ".90s"*

### Extending/reducing ban duration

A ban duration can be extended or reduced by the following commands: 

`/ban-reduce [player] [amount] [unit]`\
`/ban-extend [player] [amount] [unit]`\
\
This command can also be limited in duration the same way a tempban is limited.\
Giving the player the following 2 permissions will limit the extension duration for example:

* staff.`bans`.extendban
* staff.`bans`.extendban.limit.2w

{% hint style="warning" %}
When extending a ban, the staff member cannot extend the ban further than his tempban limit will allow. This is to prevent a staff member spamming an extend command.\
This means that if a player is banned for 2 months. His ban cannot be extended by a staff member whose tempban limit is 3 weeks for example.
{% endhint %}

### Unbanning

`/unban [player] [reason]`

```
/unban playername We are friends now
```

### Silent banning

The `-silent` can be used to ban/tempban/unban players without sending out a notification to anyone.

```
/ban playername -silent He was bothering me
```

## Showing ban reason on ban/rejoin

If you want banned players can see the reason why they are banned you can edit the kick message in the lang files:

```yaml
ban-tempbanned-kick: "[Banned] You have been temporarily banned from this server. Ban ends in: %duration%"
ban-permabanned-kick: "[Banned] You have been permanently banned from this server"
```

#### placeholders

Inside the message the following placeholders can be used

| placeholder | description                                           |
| ----------- | ----------------------------------------------------- |
| %target%    | The banned player's username                          |
| %issuer%    | The staff members username                            |
| %reason%    | The ban reason                                        |
| %duration%  | Human readable duration. Only available with tempbans |


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://wiki.staffplusplus.org/features/banning.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.