init

docs/03_Commands.md

@@ -0,0 +1,97 @@
+# 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.