# 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 |