> For the complete documentation index, see [llms.txt](https://docs.ohalee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ohalee.com/products/ultimateguilds/ranks.md).

# Ranks & Permissions

Ranks, and what each of them is allowed to do inside a guild.

Ranks are defined in `ranks.yml`. A server can run three of them or eight, name them what it likes, and decide for itself whether moderators may ban.

The file ships with the five ranks UltimateGuilds had before 3.0, carrying exactly the permissions they had then, so an upgraded server behaves identically until you edit it.

## Defining a rank

```yaml
ranks:
  moderator:
    display-name: "ranks.moderator.display_name"
    weight: 20
    permissions:
      - INVITE
      - KICK
```

<table><thead><tr><th width="180">Key</th><th>Meaning</th></tr></thead><tbody><tr><td>The section name</td><td>The rank's key. It is what gets stored against each member, so renaming a section moves nobody: keep the key and change the display name instead.</td></tr><tr><td>display-name</td><td>A translation key from your language file. Players see what it resolves to.</td></tr><tr><td>weight</td><td>Authority. Higher outranks lower, promotion moves one step up the weights, and the highest weight runs the guild.</td></tr><tr><td>permissions</td><td>What a member holding this rank may do.</td></tr></tbody></table>

{% hint style="info" %}
The highest rank is the guild master. Promotion never reaches it — ownership is handed over with `/guild admin` — so a guild always has exactly one.
{% endhint %}

## Permissions

<table><thead><tr><th width="240">Permission</th><th>Allows</th></tr></thead><tbody><tr><td>INVITE</td><td>Invite players to the guild</td></tr><tr><td>KICK</td><td>Remove a member who does not outrank you</td></tr><tr><td>BAN / UNBAN</td><td>Ban a player from the guild, and lift a ban</td></tr><tr><td>PROMOTE / DEMOTE</td><td>Move a member up or down the ranks</td></tr><tr><td>TRANSFER_OWNERSHIP</td><td>Hand the guild over to another member</td></tr><tr><td>RENAME</td><td>Rename the guild</td></tr><tr><td>SET_TAG / SET_COLOR</td><td>Change the guild tag and its colour</td></tr><tr><td>SET_DESCRIPTION</td><td>Change the guild description</td></tr><tr><td>SET_MAX_MEMBERS</td><td>Raise the member limit, within what the player's server permissions allow</td></tr><tr><td>DISBAND</td><td>Delete the guild</td></tr><tr><td>MANAGE_RANKS</td><td>Create, delete and edit the guild's ranks</td></tr><tr><td>MANAGE_RELATIONS</td><td>Offer, declare and drop standings with other guilds</td></tr></tbody></table>

A permission the file names that does not exist is skipped with a warning, and the rank keeps the ones that do.

## Adding a rank

Add a section with a weight that places it where you want, and give it a `guilds.list.separator.<key>` line in your language file so `/guild list` has a heading for it. A key containing `-` becomes `_` in that message key: `co-leader` reads `guilds.list.separator.co_leader`.

{% hint style="warning" %}
Removing a rank while members still hold it stops those guilds from loading, with a message naming the rank. Move the members off it first, or keep the key.
{% endhint %}