# Commands

All commands require the caller to be in one of the `staff_groups` from config. Player-only (no console support yet).

## Punishments

### /ban <player> <reason>

Permanent ban. Active across all servers in the network within a few hundred ms. Online target is disconnected immediately with the reason.

### /tempban <player> <duration> <reason>

Time-limited ban. Duration syntax: `30s`, `5m`, `2h`, `7d`, `1w`. Expires automatically (the active-ban query filters by `expires_at`).

### /mute <player> <reason>

Permanent mute. Cancels `PlayerChatEvent` for the target on every server. Loaded into a per-server in-memory cache on the target's connect so chat enforcement doesn't hit MySQL on every message.

### /tempmute <player> <duration> <reason>

Time-limited mute. Same duration syntax as tempban.

### /kick <player> <reason>

One-shot disconnect. Recorded in history but doesn't persist beyond that (the target can rejoin immediately).

### /warn <player> <reason>

Recorded in history and shown to the target as a message if they're online. No connection or chat impact.

### /unban <player>

Revokes any active ban or tempban for the player. Marks the punishment row as `active=0`, fills `revoked_at` / `revoked_by_*`. Original row stays in history.

### /unmute <player>

Same as unban but for mutes. Also clears the entry from the mute cache on any server where the player is online.

## Staff chat

### /sc <message>

Broadcasts on the cross-server staff chat channel. Visible only to other players whose `getGroupsForUser` overlaps with `staff_groups`.

System events (a ban being issued, an unban) also post a line on this channel automatically.

## Lookup

### /lookup <player>

Shows:
- Player's last-known name and UUID
- Online status (and which server they're on, if any)
- First-seen and last-seen timestamps
- Any active ban
- Any active mute

If the player has never connected, only the name/UUID lookup happens via online players and may return nothing.

### /history <player>

Last 20 punishment entries for the player, most recent first. Each entry shows id, state (`ACTIVE` / `EXPIRED` / `REVOKED`), type, who issued it, when, and the reason.

## Common error cases

| Error message | Cause |
|---|---|
| "You do not have permission to use this command." | Caller isn't in any of `staff_groups`. |
| "No player found with that name (online or in history)." | Name doesn't match any online player or any name in `staff_players_seen`. |
| "Database error: ..." | MySQL query failed. Check NetworkCore connection (`/networkcore status`). |
| "Bad duration. Use 30s, 5m, 2h, 7d, 1w." | Duration string didn't parse. Last char must be `s`/`m`/`h`/`d`/`w`, prefix must be a positive integer. |