# Permissions

# Permissions

VoiceHub keeps permissions simple: every player can use the player commands, admins need one admin node, and you can optionally lock channel creation or single channels behind a permission.

---

## Player Commands

All player commands (`open`, `create`, `join`, `leave`, `list`, `info`, `whisper`, `invite`, `kick`, `mute`, `password`, `moderate`, `request`, `grant`, `revoke`) are open to every player. They have no permission node of their own. What a player may do inside a channel depends on their [channel role](#channel-level-permissions).

To stop players from creating channels, set `allowPlayerCreatedChannels` to `false` in `config.json`. Then only players with `kyuubisoft.voicehub.create` can create channels (command and UI).

---

## Admin Permission

| Permission | Command / Feature | Default | Description |
|---|---|---|---|
| `kyuubisoft.voicehub.admin` | `/ksvoice admin ...`, `/ksvoice proximity ...`, admin panel | staff only | All admin operations: panel, list, create, delete, mute, forcejoin, proximity |
| `kyuubisoft.voicehub.create` | `/ksvoice create` and the Create tab | staff only | Only checked when `allowPlayerCreatedChannels` is `false` |

Admins also bypass password and invite-only restrictions when joining channels through the UI.

---

## Configurable Permissions

Both nodes can be renamed in `config.json` under `permissions`:

| Config Key | Default Value | Description |
|---|---|---|
| `adminPermission` | `kyuubisoft.voicehub.admin` | Permission checked for all admin operations |
| `createPermission` | `kyuubisoft.voicehub.create` | Permission checked when `allowPlayerCreatedChannels` is `false` |

```json
{
  "permissions": {
    "adminPermission": "kyuubisoft.voicehub.admin",
    "createPermission": "kyuubisoft.voicehub.create"
  }
}
```

A changed `adminPermission` takes effect after a server restart, because the admin commands read it when they are registered.

---

## Channel-Level Permissions

Inside a voice channel, each member has a role that determines what they can do:

| Role | Actions |
|---|---|
| **Owner** | Edit channel settings, set password, toggle moderation, kick, mute, invite, grant/revoke talk power, delete channel |
| **Moderator** | Kick, mute, invite, grant/revoke talk power |
| **Member** | Request talk power, leave, use text chat (`!vc`) |

Owners and moderators always have talk power in moderated channels.

---

## Per-Channel Join Permissions

Admin-created channels can require a custom permission to join. This is set with the `--perm` flag:

```
/ksvoice admin create VIPLounge GROUP --perm myserver.vip.voice
```

Only players with `myserver.vip.voice` will be able to join that channel. This check applies in both the command and the UI.

---

## Permission Flow Examples

### Player creates and manages a channel
1. Any player can use `/ksvoice create`.
2. If `allowPlayerCreatedChannels` is `false`, the player needs `kyuubisoft.voicehub.create`.
3. The creator becomes channel **Owner** and can kick, mute, set a password and so on.

### Admin manages server voice
1. Needs `kyuubisoft.voicehub.admin`.
2. Can open the admin panel, force-delete channels, voice-ban players and adjust proximity settings.

## LuckPerms Examples

```bash
# Voice admins
/lp group admin permission set kyuubisoft.voicehub.admin true

# Only VIPs may create channels (with allowPlayerCreatedChannels: false)
/lp group vip permission set kyuubisoft.voicehub.create true
```