# Configuration

# Configuration

The main configuration file `mods/kyuubisoft_infohub/config.json` controls the core behavior of the Info Hub. All options can also be edited in the [admin window](./admin-panel) (Book & sections, Join, General).

## Complete Example

```json
{
  "schemaVersion": 3,
  "language": "en-US",
  "command": {
    "name": "ksinfo",
    "aliases": ["hub", "hilfe", "menu"],
    "description": "Opens the Info Hub"
  },
  "joinMessage": {
    "enabled": true,
    "delaySeconds": 2,
    "message": [
      "",
      "&8━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
      "  &6Welcome to the server!",
      "  &7Use &e/ksinfo &7for all information!",
      "&8━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
      ""
    ],
    "showOnlyOnFirstJoin": false,
    "cooldownMinutes": 0,
    "i18n": {
      "de-DE": ["", "  &6Willkommen!", "  &7Nutze &e/ksinfo &7für alle Infos!", ""]
    }
  },
  "infoItem": {
    "enabled": true,
    "itemId": "InfoHub_Book",
    "giveOnFirstJoin": true,
    "giveOnEveryJoin": false,
    "hotbarSlot": 8,
    "giveDelaySeconds": 3
  },
  "globalSearch": {
    "enabled": true,
    "minQueryLength": 2,
    "maxResults": 20,
    "searchIn": {
      "commands": true,
      "faq": true,
      "rules": true,
      "team": false,
      "news": true,
      "pages": true
    }
  },
  "sections": {
    "news": {
      "icon": "Ore_Prisma",
      "priority": 0,
      "permission": null,
      "enabled": true,
      "command": null
    },
    "commands": {
      "icon": "Tool_Pickaxe_Iron",
      "priority": 1,
      "permission": null,
      "enabled": true,
      "command": "commands"
    },
    "rules": {
      "icon": "Weapon_Sword_Iron",
      "priority": 2,
      "permission": null,
      "enabled": true,
      "command": "rules"
    },
    "faq": {
      "icon": "Ore_Gold",
      "priority": 3,
      "permission": null,
      "enabled": true,
      "command": "faq"
    },
    "serverinfo": {
      "icon": "Ore_Prisma",
      "priority": 4,
      "permission": null,
      "enabled": true,
      "command": null
    },
    "team": {
      "icon": "Weapon_Longsword_Iron",
      "priority": 5,
      "permission": null,
      "enabled": true,
      "command": "team"
    }
  },
  "display": {
    "hubTitle": "Info Hub",
    "showSectionDescriptions": true
  },
  "permissions": {
    "adminReload": "infohub.admin.reload",
    "bypassCommandFilter": "infohub.bypass.commandfilter"
  },
  "banner": { "enabled": true },
  "rules": { "requireAcknowledgement": false },
  "onboarding": { "openHubOnFirstJoin": false },
  "news": { "joinHint": false },
  "bookLinks": [
    { "id": "achievements", "label": "Achievements", "icon": "Ore_Gold",
      "command": "/ksachievements", "plugin": "kyuubisoft:achievements", "enabled": true }
  ]
}
```

---

## Settings Reference

### General Settings

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `language` | String | `"en-US"` | Server default language, used when a text has no translation in the player's language. With KyuubiSoft Core the server language is set in `/kssettings` instead. Available: `en-US`, `de-DE`, `fr-FR`, `es-ES`, `pt-BR`, `ru-RU`, `pl-PL`, `tr-TR`, `it-IT` |
| `schemaVersion` | Integer | `3` | Written by the plugin. Files from before 3.0.0 are upgraded once on the first start |

### Command Settings

| Setting | Type | Description |
|---------|------|-------------|
| `command.name` | String | Main command to open the Info Hub |
| `command.aliases` | Array | Alternative commands (default `hub`, `hilfe`, `menu`; `help` is never registered) |
| `command.description` | String | Command description |

### Join Message

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `joinMessage.enabled` | Boolean | `true` | Enable welcome message |
| `joinMessage.delaySeconds` | Integer | `2` | Delay after join in seconds |
| `joinMessage.message` | Array | - | Message lines (with color codes) |
| `joinMessage.showOnlyOnFirstJoin` | Boolean | `false` | Only show on first ever join |
| `joinMessage.cooldownMinutes` | Integer | `0` | Cooldown between messages (0 = always) |
| `joinMessage.i18n` | Object | - | Optional lines per language, e.g. `{"de-DE": ["...", "..."]}`. A player without lines in their language gets the server language's lines, else `message` |

`{player}` and `{server}` are replaced in the join message.

### Info Item

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `infoItem.enabled` | Boolean | `true` | Enable info item system |
| `infoItem.itemId` | String | `"InfoHub_Book"` | Item ID for the info item |
| `infoItem.giveOnFirstJoin` | Boolean | `true` | Give item on first join |
| `infoItem.giveOnEveryJoin` | Boolean | `false` | Give item on every join |
| `infoItem.hotbarSlot` | Integer | `8` | Hotbar slot 0-8 |
| `infoItem.giveDelaySeconds` | Integer | `3` | Delay before giving item |

### Global Search

The book has a search field in the header. Enter or the magnifier opens the **Search** tab with type filter pills and counts; a hit opens exactly its entry. Sections a player cannot open never appear.

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `globalSearch.enabled` | Boolean | `true` | Enable global search |
| `globalSearch.minQueryLength` | Integer | `2` | Minimum search query length |
| `globalSearch.maxResults` | Integer | `20` | Maximum search results |
| `globalSearch.searchIn.commands` | Boolean | `true` | Include commands in search |
| `globalSearch.searchIn.faq` | Boolean | `true` | Include FAQ in search |
| `globalSearch.searchIn.rules` | Boolean | `true` | Include rules in search |
| `globalSearch.searchIn.team` | Boolean | `false` | Include team in search |
| `globalSearch.searchIn.news` | Boolean | `true` | Include news in search |
| `globalSearch.searchIn.pages` | Boolean | `true` | Include custom pages (entry level) in search |

With `globalSearch.enabled: false` the search field is hidden.

### Sections

Each section can be configured:

| Setting | Type | Description |
|---------|------|-------------|
| `icon` | String | Item ID for the section icon |
| `priority` | Integer | Sort order (lower = higher) |
| `permission` | String | Permission to view (null = everyone) |
| `enabled` | Boolean | Show the section in the book (also checked by its shortcut command) |
| `command` | String | Direct command for this section (null = no command; a new or renamed command needs a restart) |
| `commandAliases` | Array | Additional command aliases (optional) |

The sections are `news`, `commands`, `rules`, `faq`, `serverinfo` and `team`. `iconColor` from older files is no longer used.

:::tip Section Command Configuration
You can add a command to any section. For example, to add a command for the `serverinfo` section:

```json
"serverinfo": {
  "icon": "Ore_Prisma",
  "priority": 4,
  "enabled": true,
  "command": "serverinfo",
  "commandAliases": ["server", "info-server"]
}
```
:::

### Display Settings

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `display.hubTitle` | String | `"Info Hub"` | Title shown in the book header |
| `display.i18n` | Object | - | Optional hub title per language |
| `display.showSectionDescriptions` | Boolean | `true` | Show category descriptions (rules) in the book |
| `display.itemsPerPage`, `display.columns` | | | No longer used since 3.0.0 (kept readable) |

### Book options (3.0.0)

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `banner.enabled` | Boolean | `true` | Show the server banner on the Start tab. The image is the PNG in `banner/` (max 1520 x 240; larger images are scaled down). `/ksinfoadmin browsebanners` lists the files |
| `rules.requireAcknowledgement` | Boolean | `false` | Players confirm the current rules in a window inside the book; asked again when a rule changes. See [Rules](./rules-config#rules-acknowledgement) |
| `onboarding.openHubOnFirstJoin` | Boolean | `false` | Opens the Info Hub once for players joining for the first time |
| `news.joinHint` | Boolean | `false` | One chat line after join when the player has unread news |
| `bookLinks` | Array | 6 entries | "Your books" on the Start tab: Achievements, Quest Book, Season Pass, Pets, Bank and Shops. Each entry (`id`, `label`, `icon`, `command`, `plugin`, `enabled`, `i18n`) is only shown while its plugin is loaded; opening one closes the Info Hub and runs its command as the player |

### Permissions

| Setting | Default | Description |
|---------|---------|-------------|
| `permissions.adminReload` | `infohub.admin.reload` | Extra node allowed to run `/ksinfoadmin reload` |
| `permissions.bypassCommandFilter` | `infohub.bypass.commandfilter` | Node that skips the command blocklist in the Commands tab |

See [Permissions](./permissions).

### Broken files

A file with broken JSON is never overwritten: it is kept, copied to `<file>.corrupt-<timestamp>`, a clear error is logged and the defaults are used in memory until it is fixed. Files are no longer rewritten on every load, and keys unknown to this version are kept.

---

## Color Codes

Use these codes in messages:

| Code | Color | Code | Color |
|------|-------|------|-------|
| `&0` | Black | `&8` | Dark Gray |
| `&1` | Dark Blue | `&9` | Blue |
| `&2` | Dark Green | `&a` | Green |
| `&3` | Dark Cyan | `&b` | Cyan |
| `&4` | Dark Red | `&c` | Red |
| `&5` | Purple | `&d` | Pink |
| `&6` | Gold | `&e` | Yellow |
| `&7` | Gray | `&f` | White |

**Formatting:**

| Code | Effect |
|------|--------|
| `&l` | Bold |
| `&o` | Italic |
| `&n` | Underlined |
| `&r` | Reset |

A literal `&` followed by a space or another character (for example "Q&A", "Tom & Jerry") stays readable. Lower-case codes always work; upper-case codes from older content (`&C`, `&A`) still work, except straight after a letter or digit.

---

## Examples

### Minimal Join Message

```json
"joinMessage": {
  "enabled": true,
  "delaySeconds": 1,
  "message": [
    "&aWelcome! Type &e/ksinfo &afor help."
  ]
}
```

### Staff-Only Section

```json
"sections": {
  "admin-tools": {
    "icon": "Deco_Inkwell",
    "priority": 10,
    "permission": "infohub.section.admin",
    "enabled": true
  }
}
```

### Disable Info Item

```json
"infoItem": {
  "enabled": false
}
```