# Utility Commands

Convenience and admin commands: healing, flying, god mode, inventory management and info commands. Cooldowns and costs are configurable per command in `modules/utility.yml`. Cooldowns are bound to the player and survive a relog, but not a server restart; expired entries are cleaned up by the module itself.

## Health & status

| Command | Syntax | Permission (self) | Permission (others) | Default | Description |
|---|---|---|---|---|---|
| `/heal` | `/heal [player]` | `util.heal` | `util.heal.others` | op | Heal fully and extinguish fire |
| `/feed` | `/feed [player]` | `util.feed` | `util.feed.others` | op | Fill hunger and saturation |
| `/god` | `/god [player]` | `util.god` | `util.god.others` | op | Toggle invulnerability (persists with `god-persist`). Only keeps hunger from dropping: eating still restores it and natural regeneration works |
| `/fly` | `/fly [player]` | `util.fly` | `util.fly.others` | op | Toggle flight mode (not persisted) |
| `/speed` | `/speed <value> [player]` | `util.speed` | `util.speed.others` | op | Walk/fly speed 0 to 10 (1 = normal) |

> **Note:** Commands that take a player target (`/heal`, `/feed`, `/fly`, `/god`, `/speed`, `/gamemode`, `/exp`, `/hunger`, `/clear`, `/clearenderchest`, `/invsee`, `/endersee`, `/seen`) require the full player name. A partial name (e.g. `Max` for `Maxine`) answers "player is not online" instead of hitting the first matching player. `/heal <own name>` and `/feed <own name>` behave like `/heal` and `/feed` without arguments: the `util.heal` / `util.feed` permission, cooldown and cost apply the same way; `util.heal.others` / `util.feed.others` alone is not enough.

## Game mode

| Command | Syntax | Permission (self) | Permission (others) | Default | Description |
|---|---|---|---|---|---|
| `/gamemode` | `/gamemode <mode> [player]` (alias `/gm`) | `util.gamemode` | `util.gamemode.others` | op | Set game mode (`survival`/`s`/`0`, `creative`/`c`/`1`, `adventure`/`a`/`2`, `spectator`/`sp`/`3`) |
| `/glow` | `/glow [colour\|off] [player]` | `util.glow` | `util.glow.others` | op | Glowing outline in one of the 16 team colours (`red`, `aqua`, `light_purple` and so on, also `orange`, `pink`, `lime`); without a colour a menu opens, `off` switches it off. Lasts until logout |

> **Note:** The colour is only sent to the clients, the server scoreboard stays untouched; it also colours the name above the head. Plugins that manage their own name tag teams (TAB and similar) can override the colour.

## Inventory & items

| Command | Syntax | Permission (self) | Permission (others/all) | Default | Description |
|---|---|---|---|---|---|
| `/repair` | `/repair [all\|hand]` (alias `/fix`) | `util.repair` | `util.repair.all` | op | Repair the item in hand, with `all` the whole inventory. `all` only charges when at least one damaged item is in the inventory; "no damaged items" is free |
| `/hat` | `/hat` | `util.hat` | - | op | Swap item into the helmet slot (even with a helmet on). If the current helmet carries Curse of Binding, the command refuses in survival, adventure and spectator mode; in creative mode the swap works |
| `/clear` | `/clear [player]` (alias `/ci`) | `util.clear` | `util.clear.others` | op | Clear inventory |
| `/clearenderchest` | `/clearenderchest [player]` (alias `/clearec`) | `util.clearenderchest` | `util.clearenderchest.others` | op | Clear ender chest |
| `/ec` | `/ec` (alias `/enderchest`) | `util.ec` | - | `true` | Open your own ender chest virtually |
| `/invsee` | `/invsee <player>` | `util.invsee` | - | op | View/edit another inventory |
| `/endersee` | `/endersee <player>` (alias `/ecsee`) | `util.endersee` | - | op | View/edit another ender chest |
| `/exp` | `/exp <give\|take\|set> <player> <amount>` (alias `/xp`) | - | `util.exp` | op | Manage XP levels using the Minecraft formula |
| `/hunger` | `/hunger <player> <value>` | - | `util.hunger` | op | Set food level (0 to 20) |

> **Note:** On Folia, `/invsee` and `/endersee` only open while viewer and target tick on the same world region (target nearby). Otherwise "is too far away" is shown so two regions never edit the same inventory at once. No restriction on Paper.

## Virtual workbenches

| Command | Syntax | Permission | Default | Description |
|---|---|---|---|---|
| `/workbench` | `/workbench` (alias `/craft`, `/wb`) | `util.workbench` | `true` | Virtual crafting table |
| `/anvil` | `/anvil` | `util.anvil` | `true` | Virtual anvil |
| `/trash` | `/trash` (alias `/disposal`) | `util.trash` | `true` | Disposal inventory (contents deleted on close) |

More workstations are bundled in the [Stations](stations.md) module with its hub GUI.

## Item text: coloured names, signatures, lore

Three rights, all off by default, that let players personalise their items. Text may contain MiniMessage colours, formatting and gradients, for example `<gradient:#ff00aa:#aa00ff><b>Mythic Shield</b></gradient>`. Click or hover tags are stripped, lengths count visible characters only, and the moderation module's word filter applies here too. Costs and cooldowns are set in `modules/utility.yml` under `cost.commands` and `cooldown.commands` with the keys `rename`, `sign` and `lore`: for `/lore` only `add` counts, for `/sign` only a new or refreshed signature, and a rejected input never costs anything. The price applies per item in the stack, so a stack of 16 costs sixteen times the value.

| Command | Syntax | Permission | Default | Description |
|---|---|---|---|---|
| `/rename` | `/rename <text>` / `/rename reset` | `itemtext.rename` | op | Gives the item in your hand a coloured name. Like the anvil it allows 50 characters, but visible ones only: formatting does not count, so a gradient name fits. `reset` removes the name again. |
| Anvil name | type the name into the anvil | `itemtext.rename` | op | The anvil renders the name as MiniMessage too, but within the game's 50 character field, tags included. Use `/rename` for long formatting. Plain text without MiniMessage tags follows vanilla's rules in the anvil, also for players with `itemtext.rename`; `ascii-only` and `allowed-symbols` apply to coloured names (text with tags) and to `/rename` only. The word filter always applies. While `/rename` has a cost or cooldown, the anvil keeps the name unformatted and points players to `/rename`. With `rename` in `disabled-commands`, coloured anvil names are off as well; `sign` and `lore` can be switched off there the same way. Nexo users need no extra setting: Mira hands every name it writes to Nexo's packet layer in MiniMessage form, so coloured names stay formatted after an anvil pass. |
| `/sign` | `/sign` / `/sign check` | `itemtext.sign` | op | Writes "Signed by <your name> on <date>" under the lore of the item in your main hand. The name is your formatted nick or your account name. Several players can sign the same item, the signatures stack directly under each other as one block (`max-signatures`, default 5); every player signs an item once. Signing again after a nick change refreshes the name in your signature, the date stays. `/sign check` tells whether and by whom an item is really signed, because only the stored signature counts, not the text in the lore: per signature the name shown when signing (a nick, possibly), the account name behind it (when known to the server, else `?`) and the date, so a signature made under a borrowed nick can be told apart. Checking is open to everyone (`itemtext.check`, default `true`), especially traders without signing rights. |
| `/lore` | `/lore add <text>` / `/lore remove [no]` / `/lore list` / `/lore clear` | `itemtext.lore` | op | Your own lines under the enchantments. `list` shows your lines numbered, `remove` deletes your last line or, with a number, a specific one, `clear` all of yours. Foreign lore, from cosmetics for example, stays untouched. |

## Info commands

| Command | Syntax | Permission | Default | Description |
|---|---|---|---|---|
| `/near` | `/near [radius]` | `util.near` | `true` | Nearby players sorted by distance (vanished players hidden) |
| `/ping` | `/ping [player]` (alias `/latency`) | `util.ping` | `true` | Latency, color coded; others: `util.ping.others` |
| `/tps` | `/tps` | `util.tps` | op | TPS of the last 1/5/15 minutes plus MSPT |
| `/list` | `/list` (alias `/online`, `/who`) | `util.list` | `true` | Online players, sorted by group with LuckPerms |
| `/whois` | `/whois <player>` (alias `/playerinfo`) | `util.whois` | op | UUID, health, location, game mode, level; IP only with `util.whois.ip` |
| `/seen` | `/seen <player>` (alias `/lastseen`) | `util.seen` | `true` | Last online time (offline players too). Unknown names are resolved in the background (no server lag); while a lookup is still running the command answers "please wait a moment". Own cooldown key `seen` (`cooldown.commands.seen`, default 3 s, bypass `cooldown.bypass.seen`) |

> **Tip:** `/trash` is the safe item disposal without lava or fall damage.

## Configuration (modules/utility.yml)

```yaml
# Enables or disables the utility module.
enabled: true

utility:
  # Persists god mode across restart/reload.
  god-persist: true
  # Default and maximum search radius for /near in blocks.
  near-default-radius: 200
  near-max-radius: 500
  # Disables individual commands without disabling the module.
  # Example: ["heal", "repair", "anvil"]
  disabled-commands: []
  # Item text (coloured anvil names, /sign, /lore). Lengths count
  # visible characters without tags.
  itemtext:
    # Own lore lines per item, at most 64 (larger values are capped at 64,
    # one warning in the log).
    max-lore-lines: 5
    max-line-length: 48
    # Visible characters for /rename, 50 matches the anvil.
    max-name-length: 50
    # Only printable ASCII plus allowed-symbols in item names and lore
    # (/rename, /lore, coloured anvil names). Same rule as nick.ascii-only,
    # full list: see [Nick Characters](nick-chars.md).
    ascii-only: true
    allowed-symbols: "★☆✦✧♥♡♦♣♠•◆◇●○■□▲▼►◄→←↑↓↔♪♫☀☾✓✗❀✿"
    max-signatures: 5
    sign-date-format: "dd.MM.yyyy"

cooldown:
  commands:
    # Seconds per command. 0 = no cooldown. For unlisted commands
    # (e.g. ec, hat, exp) just add an entry with the command name.
    heal: 0
    feed: 0
    repair: 0
    workbench: 0
    anvil: 0
    trash: 0
    near: 0
    glow: 0
    # /seen is open to everyone and resolves unknown names in the
    # background; the short cooldown keeps macro spam in check.
    seen: 3

cost:
  commands:
    # Price per command. 0 = free.
    heal: 0
    feed: 0
    repair: 0
    workbench: 0
    anvil: 0
```

## Complete example config

```yaml
enabled: true

utility:
  god-persist: false
  near-default-radius: 100
  near-max-radius: 250
  disabled-commands:
    - hunger
  itemtext:
    max-lore-lines: 5
    max-line-length: 48
    # Visible characters for /rename, 50 matches the anvil.
    max-name-length: 50
    # Only printable ASCII plus allowed-symbols in item names and lore
    # (/rename, /lore, coloured anvil names). Same rule as nick.ascii-only,
    # full list: see [Nick Characters](nick-chars.md).
    ascii-only: true
    allowed-symbols: "★☆✦✧♥♡♦♣♠•◆◇●○■□▲▼►◄→←↑↓↔♪♫☀☾✓✗❀✿"
    max-signatures: 5
    sign-date-format: "dd.MM.yyyy"

cooldown:
  commands:
    heal: 300
    feed: 120
    repair: 600
    workbench: 0
    anvil: 0
    trash: 0
    near: 30
    seen: 3

cost:
  commands:
    heal: 50.0
    feed: 25.0
    repair: 200.0
    workbench: 0
    anvil: 0
```