# Member Roles

ExcellentClaims features a built-in role system for claim members. Claim owners can use this to give specific permissions to their members to avoid griefing or abuse.

## :icon-phs-shield-check: Permissions

The following permissions are available to use in roles:

{.compact}
| Permission | Description |
| --- | --- |
| `ADMIN` | Grants all permissions and full administrative access within the claim. |
| `ADD_MEMBERS` | Allows inviting or adding new members to the claim. |
| `BUILDING` | Allows placing and breaking blocks. |
| `BLOCK_INTERACT` | Allows interacting with blocks (e.g., doors, buttons, levers, pressure plates). |
| `CHEST_ACCESS` | Allows opening and modifying the contents of chests, barrels and shulker boxes. |
| `CONTAINERS` | Allows access to other container blocks (e.g., furnaces, hoppers). |
| `DAMAGE_MOBS` | Allows attacking and dealing damage to mobs within the claim. |
| `DEMOTE_MEMBERS` | Allows lowering the role of existing claim members. |
| `DROP_ITEMS` | Allows dropping items on the ground within the claim. |
| `ENTITY_INTERACT` | Allows interacting with entities (e.g., trading with villagers, mounting horses, shearing sheep). |
| `ITEM_INTERACT` | Allows using items in hand (e.g., using flint and steel, throwing ender pearls, eating). |
| `MANAGE_CLAIM` | Allows modifying core settings and properties of the claim. |
| `MANAGE_MEMBERS` | Allows overarching control over the claim's member list and their roles. |
| `MANAGE_RULES` | Allows toggling and configuring claim-specific rules and flags. |
| `MERGE_CLAIM` | Allows merging this claim with an adjacent owned claim. |
| `PICKUP_ITEMS` | Allows picking up dropped items within the claim. |
| `PROMOTE_MEMBERS` | Allows raising the role of existing claim members. |
| `PURGE_MEMBERS` | Allows removing all non-owner members from the claim simultaneously. |
| `REMOVE_MEMBERS` | Allows kicking specific members from the claim. |
| `RENAME_CLAIM` | Allows changing the display name of the claim. |
| `SET_CLAIM_DESCRIPTION` | Allows updating the description or lore of the claim. |
| `SET_CLAIM_SPAWN` | Allows setting or moving the claim's home/teleport spawn location. |
| `SET_CLAIM_ICON` | Allows changing the item icon that represents the claim in GUI menus. |
| `SET_CLAIM_PRIORITY` | Allows adjusting the overlapping priority level of the claim. |
| `SPLIT_CLAIM` | Allows dividing the claim into smaller, independent claims. |
| `TELEPORT` | Allows teleporting to the claim's designated home location. |
| `USE_COMMANDS` | Allows executing server commands while standing inside the claim. |
| `USE_PORTALS` | Allows entering and using Nether or End portals located within the claim. |
| `VIEW_MEMBERS` | Allows viewing the list of players who are currently members of the claim. |

!!!warning
Right now, all permissions related to interacting with the environment only work as an **allowance** and depend on the corresponding claim settings in [Rules](/rules/about).

For example, removing the `DROP_ITEMS` permission will not stop members from throwing items unless a rule specifically forbids it.
!!!

## :icon-phs-number-circle-three: Priority / Hierarchy

The priority property is used to build the correct role hierarchy. The higher a role's priority, the higher it is in the hierarchy.

- When new members are added to a claim, they get the **lowest** role in the hierarchy. This can later be changed by members with promotion or demotion permissions.
- Members with promotion permissions cannot promote anyone **above** their own role.
- Members with demotion permissions cannot demote anyone of **their own** or a **higher** role.
- Claim owners do **not** have a role and automatically bypass all claim permissions.

!!!warning
Make sure you set the correct priority values for your roles to ensure the hierarchy works properly.
!!!

## :icon-phs-gear: Configuration

Roles are set up in the `/config/ranks/ranks.yml` file. There is no limit to the maximum number of roles.

Role settings:
- **DisplayName** - The role name shown in messages and the GUI.
- **Priority** - The role priority (see above).
- **Permissions** - The role permissions (see above).

!!!tip
When setting up role permissions, each higher role (by priority) automatically inherits the permissions of all previous roles.
!!!

```yaml ranks.yml
Ranks:
  member:
    DisplayName: Member
    Priority: 1
    Permissions:
    - BLOCK_INTERACT
    - DROP_ITEMS
    - ITEM_INTERACT
    - PICKUP_ITEMS
    - TELEPORT
    - VIEW_MEMBERS
  trusted:
    DisplayName: Trusted
    Priority: 10
    Permissions:
    - BUILDING
    - CHEST_ACCESS
    - CONTAINERS
    - DAMAGE_MOBS
    - ENTITY_INTERACT
    - USE_COMMANDS
    - USE_PORTALS
  moderator:
    DisplayName: Moderator
    Priority: 25
    Permissions:
    - ADD_MEMBERS
    - DEMOTE_MEMBERS
    - MANAGE_CLAIM
    - MANAGE_MEMBERS
    - PROMOTE_MEMBERS
    - REMOVE_MEMBERS
  admin:
    DisplayName: Admin
    Priority: 100
    Permissions:
    - ADMIN
```