# Permissions

**Version:** 1.0.0

Guilds uses two layers:

1. **Permission nodes** on the server decide who may use a command at all, who is an admin and who may open every lock.
2. **Rank rights** inside each guild decide what a member may do in that guild: invite, kick, lock for the guild, use the storage, and so on. The leader sets them on the **Ranks** tab.

Command syntax is on the [Commands](./commands) page.

---

## Player nodes (allowed by default)

Every player command checks its own node `ks.guilds.user.<action>`. These nodes are **allowed unless you set them to `false`**. A player without one gets "You lack the permission for that."

| Permission | Command |
|------------|---------|
| `ks.guilds.user.open` | `/ksguild` (opens the guild window) |
| `ks.guilds.user.create` | `/ksguild create` |
| `ks.guilds.user.invite` | `/ksguild invite` |
| `ks.guilds.user.accept` | `/ksguild accept` |
| `ks.guilds.user.deny` | `/ksguild deny` |
| `ks.guilds.user.join` | `/ksguild join` |
| `ks.guilds.user.request` | `/ksguild request` |
| `ks.guilds.user.withdraw` | `/ksguild withdraw` |
| `ks.guilds.user.leave` | `/ksguild leave` |
| `ks.guilds.user.kick` | `/ksguild kick` |
| `ks.guilds.user.promote` | `/ksguild promote` |
| `ks.guilds.user.demote` | `/ksguild demote` |
| `ks.guilds.user.transfer` | `/ksguild transfer` |
| `ks.guilds.user.disband` | `/ksguild disband` |
| `ks.guilds.user.info` | `/ksguild info` |
| `ks.guilds.user.contribute` | `/ksguild contribute` |
| `ks.guilds.user.help` | `/ksguild help` |
| `ks.guilds.user.lock` | `/ksguild lock` |
| `ks.guilds.user.unlock` | `/ksguild unlock` |
| `ks.guilds.user.lockinfo` | `/ksguild lockinfo` |
| `ks.guilds.user.autolock` | `/ksguild autolock` |
| `ks.guilds.user.home` | `/ksguild home` |
| `ks.guilds.user.sethome` | `/ksguild sethome`, and the **Set here** button on the **Settings** tab (it runs this command) |
| `ks.guilds.user.land` | `/ksguild land add`, `remove` and `list` (only with KyuubiSoft Claims 2.0) |
| `ks.guilds.user.chat` | `/gc` and the guild chat mode. Without it, chat lines stay in the general chat even while the mode is on |

:::note[The window has one node]
The guild window only checks `ks.guilds.user.open`. Its buttons (invite, accept, promote, lock, storage, home, ...) do not check the command nodes above; there the rank rights decide. To keep a group away from guilds completely, set `ks.guilds.user.open` and the command nodes they should not use to `false`.
:::

---

## Admin nodes (not granted by default)

| Permission | What it unlocks |
|------------|-----------------|
| `ks.guilds.admin` | `/ksguild admin` and the admin window, also from the **Guilds** tile in the `/ksadmin` hub. In the admin window: step into any guild as described on [UI Pages](./ui-pages#admin-window). On locks, also with the normal commands: change and remove every lock, break every locked block, and lock blocks somebody else set down or that stand in someone else's claim. Does **not** open locked blocks |
| `ks.guilds.admin.bypass` | Opens and uses every locked chest, door and gate, breaks locked blocks, and may lock blocks somebody else set down or that stand in someone else's claim |

- Give both to staff who should handle locks. `ks.guilds.admin` alone can remove a lock, but cannot open a locked chest while the lock is there.
- Inside their own guild, admins follow the rank rights like everyone else when they use `/ksguild` or the guild window. Admin powers over guilds only apply in the admin window.
- The `/ksadmin` hub needs Core's `ks.admin`; the **Guilds** tile in it also checks `ks.guilds.admin`.
- The lock window says "Admins always get in"; in game that means players with `ks.guilds.admin.bypass`.

---

## Rank rights inside a guild

These are not permission nodes. Each guild sets them per rank on the **Ranks** tab; only the leader may change them. The leader always has every right.

| Right (as shown in the window) | Allows | Default ranks |
|--------------------------------|--------|---------------|
| Invite members | Invite players | Officer, Veteran, Member |
| Accept join requests | Accept and decline join requests | Officer, Veteran |
| Remove lower ranks | Remove members of a lower rank | Officer |
| Promote and demote, up to below their own rank | Move lower members one rank up or down | Officer |
| Write the announcement | Write and remove the announcement | Officer |
| Lock chests and doors for the guild | Create guild locks | Officer, Veteran, Member |
| Change and remove other members' guild locks | Change and remove any guild lock of the guild, and lock chests that a guild mate set down | Officer |
| Put items into the guild storage | Put items in | all ranks |
| Take items from the guild storage | Take items out, up to the daily limit of the rank | Officer, Veteran, Member |
| Travel to the guild home | Use `/ksguild home` and **To the guild home** | all ranks |
| Set the guild home | Set and remove the guild home | Leader only |
| Manage guild land | Add and remove guild land and set its ranks (with Claims) | Leader only |

The admin sets the defaults for **new** guilds with `defaultRights` in `config.json`; existing guilds keep their own table.

**Leader only, always:** renaming the guild, changing tag, colour, crest and joining mode, the setting "No damage between members", renaming ranks and changing rights, handing over the leadership and disbanding.

**Fixed rules for locks:**

| Who | Private lock | Guild lock |
|-----|--------------|------------|
| May open | The owner and the players added to it | Members from the lock's rank, and the players added to it |
| May change or remove | The owner | Whoever set it (while in the guild) and members with **Change and remove other members' guild locks** |
| May break the block | The owner | Whoever set it (while in the guild) and ranks Officer and Leader |

Players with `ks.guilds.admin` may change, remove and break every lock; players with `ks.guilds.admin.bypass` may open and break every lock. Creatures and explosions never break a locked block.

---

## Internal node

| Permission | Note |
|------------|------|
| `ks.guilds.nameplate.tag` | Guild tags registered with KyuubiSoft Nameplates carry this node so players cannot pick another guild's tag in the Nameplates tag list. Give it to nobody |

`/kslang` has no permission.