# Commands

Player-only (no console support yet). Every command is gated by a Hytale permission node via `requirePermission(...)` in the constructor.

## Permissions

| Command | Required permission |
|---|---|
| `/rank create`      | `networkranks.rank.create` |
| `/rank delete`      | `networkranks.rank.delete` |
| `/rank addperm`     | `networkranks.rank.edit` |
| `/rank removeperm`  | `networkranks.rank.edit` |
| `/rank setparent`   | `networkranks.rank.edit` |
| `/rank setprefix`   | `networkranks.rank.edit` |
| `/rank list`        | `networkranks.rank.list` |
| `/rank info`        | `networkranks.rank.info` |
| `/grant`            | `networkranks.grant` |
| `/tempgrant`        | `networkranks.grant` |
| `/revoke`           | `networkranks.revoke` |
| `/primary`          | `networkranks.primary` |
| `/ranks`            | `networkranks.lookup` |

Grant `networkranks.*` to your admin group for full control.

## /rank

Subcommand tree for managing rank definitions (not memberships).

### /rank create <id> <prefix> <priority>

Creates a new rank. `id` should be short and lowercase (e.g. `vip`, `mvp`). `prefix` is a single token (`[VIP]`, `[Mod]`). `priority` is an integer - higher means "more important" for sorting purposes.

The new rank has no parent and no permissions until you add them with `/rank setparent` and `/rank addperm`.

### /rank delete <id>

Deletes a rank. Built-in groups (`hytale:Adventurer`, `hytale:Admin`, etc.) cannot be deleted - the command will report "not found or is built-in".

Active grants of the deleted rank become orphaned. They stay in the DB but the rank lookup returns nothing, so they have no effect on permissions.

### /rank addperm <id> <permission>

Adds a permission node to the rank's direct permissions. Wildcards (`*`, `someplugin.*`) work the same way they do in Hytale.

### /rank removeperm <id> <permission>

Removes one permission. Doesn't touch inherited permissions.

### /rank setparent <id> <parent|none>

Sets a rank's parent. Permissions are inherited up the parent chain: `Admin` parent `ServerEditor` parent `WorldEditor` ... means an Admin has every permission those parents have. Pass `none` to clear the parent.

### /rank setprefix <id> <prefix>

Updates the rank's chat prefix. Takes effect immediately (cache invalidation broadcasts to all servers).

### /rank list

Lists all ranks with their priority, prefix, parent, and built-in flag.

### /rank info <id>

Shows a rank's metadata + the full list of direct permissions (not the inherited ones).

## Grants

### /grant <player> <rank>

Permanently grants `rank` to `player`. Player can be an online name or a UUID string (UUIDs are required for offline players, since we don't track every name we've ever seen).

The grant adds to the player's set of ranks; it doesn't replace existing ranks. Use `/primary` to change which one is used for display.

### /tempgrant <player> <rank> <duration>

Same as `/grant` but the grant expires after `duration`. Duration syntax: `30s`, `5m`, `2h`, `7d`, `1w`, `1mo`, `1y`. Expired grants don't count toward effective permissions.

### /revoke <player> <rank>

Marks all active grants of `(player, rank)` as revoked. Doesn't delete the row - revoked grants stay for history.

### /primary <player> <rank>

Marks `rank` as the player's primary (display) rank. Player must already have an active grant of it. Used by the chat prefix listener.

### /ranks <player>

Shows the player's active rank IDs, primary rank, and the 10 most recent grants (active, expired, and revoked).

## Hytale's built-in /perm and /op commands

Still work as before. Hytale routes them through `PermissionsModule.get()`, which routes through our provider. `/op Bob` becomes a `setUserGroup(uuid, "hytale:Admin")` call, which we implement as a fresh grant of the `hytale:Admin` rank.

So you have two ways to manage permissions:
- **Hytale's commands** (`/op`, `/perm group add`, etc.) - work with the built-in `hytale:*` groups
- **Our commands** (`/rank create vip ...`, `/grant Bob vip`) - work with both built-ins AND custom ranks you create

Either set of commands updates the same MySQL tables. Use whichever feels right.