# Commands Configuration

# Commands Configuration

**File:** `commands/categories.json`

This file controls how server commands are displayed and categorized in the Info Hub.

## Complete Example

```json
{
  "settings": {
    "groupBy": "auto",
    "showAliases": true,
    "showPermissions": false,
    "itemsPerPage": 6,
    "showDefaultCommands": true,
    "showModCommandsOnly": false,
    "hiddenCommands": [],
    "hiddenPrefixes": [],
    "allowedPlugins": [],
    "blockedPlugins": []
  },
  "execution": {
    "enabled": false,
    "requireConfirmation": true,
    "allowedCommands": [],
    "blockedCommands": ["ban", "kick", "mute", "op", "deop", "stop", "restart"],
    "parameterInputEnabled": true
  },
  "uncategorized": {
    "name": "Other",
    "icon": "Furniture_Ancient_Chest_Small",
    "color": "#797b7c"
  },
  "pluginMappings": {},
  "categories": [
    {
      "id": "general",
      "name": "General",
      "description": "Basic server commands",
      "icon": "Deco_Book_Pile_Small",
      "permission": null,
      "priority": 1,
      "color": "#b4c8c9",
      "plugins": [],
      "commands": ["help", "info", "spawn", "rules"]
    }
  ],
  "customCommands": []
}
```

---

## Settings

The Commands tab lists only the commands the player may use, with category pills, the description (vanilla descriptions translated), usage, aliases, parameter fields, selectable sub-commands, **To chat** and **Run**. Commands registered later by other mods are picked up the next time the tab opens.

### Display Settings

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `groupBy` | String | `"auto"` | How to group commands (see below) |
| `showAliases` | Boolean | `true` | Show command aliases |
| `showPermissions` | Boolean | `false` | Show permission nodes |
| `itemsPerPage` | Integer | `6` | Commands per page |
| `showDefaultCommands` | Boolean | `true` | Show Hytale default commands |
| `showModCommandsOnly` | Boolean | `false` | Only show mod/plugin commands |
| `hiddenCommands` | Array | `[]` | Commands to always hide |
| `hiddenPrefixes` | Array | `[]` | Hide commands starting with these prefixes (e.g., `"hytale:"`, `"debug:"`) |
| `allowedPlugins` | Array | `[]` | Only show commands from these plugins (empty = all) |
| `blockedPlugins` | Array | `[]` | Hide commands from these plugins |

### Grouping Options (`groupBy`)

| Value | Description |
|-------|-------------|
| `"plugin"` | **Recommended!** Automatic categories per plugin |
| `"category"` | Only use manually defined categories |
| `"auto"` | Automatic assignment based on command names |
| `"none"` | No categorization, single list |

---

## Command Execution

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `execution.enabled` | Boolean | `false` | Show the **Run** button in the Commands tab (the command runs as the player) |
| `execution.requireConfirmation` | Boolean | `true` | No longer used since 3.0.0 (kept readable) |
| `execution.allowedCommands` | Array | `[]` | Only allow these commands (empty = all except blocked) |
| `execution.blockedCommands` | Array | `["ban", "kick", "op", "deop", "stop", "restart"]` | Never allow these commands (players with the bypass node from `permissions.bypassCommandFilter` skip this list) |
| `execution.parameterInputEnabled` | Boolean | `true` | Show parameter fields in the command detail |

:::caution Disabled by Default
Command execution is **disabled by default**. Enable it only if you want players to run commands directly from the Info Hub book. A command always runs as the player and still needs its own permission. Without execution, players can still use **To chat**, which puts the command into their chat without running it.
:::

### Security Recommendation

Always block dangerous commands:

```json
"execution": {
  "enabled": true,
  "blockedCommands": ["op", "deop", "stop", "restart", "ban", "kick", "mute"]
}
```

---

## Categories

### Category Definition

```json
{
  "id": "teleport",
  "name": "Teleportation",
  "description": "Movement and teleport commands",
  "icon": "Tool_Map",
  "permission": null,
  "priority": 2,
  "color": "#7a9cc6",
  "plugins": ["personal-warps"],
  "commands": ["tp", "tpa", "home", "sethome", "warp"]
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | String | Unique category ID |
| `name` | String | Display name |
| `description` | String | Description text |
| `icon` | String | Item ID for icon |
| `permission` | String | Permission to view (null = everyone) |
| `priority` | Integer | Sort order (lower = higher) |
| `color` | String | Hex color code |
| `plugins` | Array | Auto-assign all commands from these plugins |
| `commands` | Array | Manually assign specific commands |

### Admin Category Example

```json
{
  "id": "admin",
  "name": "Administration",
  "description": "Admin only",
  "icon": "Deco_Inkwell",
  "permission": "infohub.admin",
  "priority": 10,
  "color": "#e94560",
  "plugins": [],
  "commands": ["ban", "kick", "mute", "gamemode"]
}
```

---

## Plugin Mappings

Assign all commands from a plugin to a specific category:

```json
"pluginMappings": {
  "Achievement-System": "achievements",
  "RPG-Leveling": "leveling",
  "Economy": "economy"
}
```

The key is the plugin name, the value is the category ID.

---

## Custom Commands

For commands that aren't automatically detected:

```json
"customCommands": [
  {
    "name": "daily",
    "description": "Claim daily reward",
    "usage": "/daily",
    "aliases": ["reward"],
    "permission": null,
    "category": "gameplay",
    "plugin": "DailyRewards",
    "executable": true
  }
]
```

| Field | Type | Description |
|-------|------|-------------|
| `name` | String | Command name (without /) |
| `description` | String | Command description |
| `usage` | String | Usage syntax |
| `aliases` | Array | Command aliases |
| `permission` | String | Required permission |
| `category` | String | Category ID to assign to |
| `plugin` | String | Plugin name to display |
| `executable` | Boolean | Allow execution from UI |

---

## Examples

### Hide Specific Commands

```json
"settings": {
  "hiddenCommands": ["debug", "test", "internal"]
}
```

### Only Show Specific Plugins

```json
"settings": {
  "allowedPlugins": ["Achievement-System", "Economy", "Teleport"]
}
```

### Block Certain Plugins

```json
"settings": {
  "blockedPlugins": ["AdminTools", "Debug"]
}
```

### Uncategorized Commands Style

```json
"uncategorized": {
  "name": "Miscellaneous",
  "icon": "Furniture_Ancient_Chest_Small",
  "color": "#888888"
}
```