# Configuration

# Title Configuration

Titles are cosmetic labels that appear on a player's nametag, in chat, or both. They are earned by completing specific achievements and can be selected by the player through a UI.

## How Titles Are Granted

Titles are defined **inside achievement definitions**. When a player completes an achievement that has a `title` field, that title is unlocked and becomes available for selection.

```json title="Achievement with a title reward"
{
  "id": "spider_hunter_4",
  "category": "combat",
  "difficulty": "hard",
  "requires": "spider_hunter_3",
  "title": {
    "id": "exterminator",
    "color": "#8B4513"
  },
  "trigger": {
    "type": "kills",
    "target": "Spider",
    "count": 100
  }
}
```

### Title Fields

| Field | Required | Default | Description |
|-------|----------|---------|-------------|
| `id` | yes | -- | Unique title identifier. Its text comes from the localization key `achievements.title.<id>`. |
| `color` | no | `"#FFFFFF"` | Hex color code for the title in chat. |

:::info
Not every achievement needs a title. Titles are optional rewards for milestone achievements. Many achievements only grant items or lootbags.
:::

## Display Configuration

Title display is controlled through the main `config.json` in the Achievements data folder (`mods/kyuubisoft_achievements/config.json`).

```json title="config.json (display section)"
{
  "display": {
    "displayMode": "both",
    "titlePosition": "prefix",
    "nametagFormat": "{title}\n{name}",
    "chatFormat": "[{title}] {name}: {message}",
    "titleColor": "#FFD700",
    "showRpgLevel": false,
    "rpgLevelFormat": "Lv.{level}",
    "rpgLevelColor": "#55FFFF",
    "rpgLevelPosition": "after_name"
  }
}
```

### Display Mode

| Value | Description |
|-------|-------------|
| `"nametag"` | Title appears above the player's head only. |
| `"chat"` | Title appears as a chat prefix only. Colors work in this mode. |
| `"both"` | Title appears in both nametag and chat. |

### Title Position (Nametag)

| Value | Result |
|-------|--------|
| `"prefix"` | `[Title] Username` (default; also used for unknown values) |
| `"above"` | Uses `nametagFormat` for multi-line layout (e.g. `{title}\n{name}`). |
| `"below"` | `Username [Title]` (multi-line below is not supported by the engine). |

:::caution
Hytale nameplates only support plain text. Color codes do **not** work in nametags. Colored titles are only visible in chat mode.
:::

### Nametag Format

The `nametagFormat` field supports `{title}` and `{name}` placeholders, along with `\n` for line breaks.

```
"{title}\n{name}"    -->  Exterminator
                          PlayerName

"[{title}] {name}"  -->  [Exterminator] PlayerName
```

### RPG Level Integration

If the RPG Leveling plugin is installed, you can show player levels alongside titles.

| Field | Default | Description |
|-------|---------|-------------|
| `showRpgLevel` | `false` | Enable level display. |
| `rpgLevelFormat` | `"Lv.{level}"` | Format string. `{level}` is replaced with the actual level. |
| `rpgLevelColor` | `"#55FFFF"` | Hex color for the level text (chat only). |
| `rpgLevelPosition` | `"after_name"` | Where to place the level: `before_name`, `after_name`, or `after_title`. |

### LuckPerms Integration

When LuckPerms is installed, player prefixes from LuckPerms are combined with achievement titles in chat:

```
[LuckPerms-Prefix] [Achievement-Title] Username: message
```

LuckPerms formatting codes (`<rainbow>`, `<gradient>`, `&a`, etc.) are fully supported in chat. Suffix formatting from LuckPerms is applied to the username color.

## Title Selection

### `/kstitles`

Opens the **titles tab of the achievement book**, where players browse their unlocked titles and choose which one to display.

**Alias:** `/title`

**Access:** `ks.achievements.user.titles` — allowed by default; deny it to take the command away from a group.

Selecting a title applies it immediately to the player's nametag and/or chat display. Players can also clear their current title to show just their username.

## Title Localization

Title names are localized through the achievement plugin's localization system. Add entries to your language files:

| Key | Purpose |
|-----|---------|
| `achievements.title.<id>` | Localized title display name |

Put your own texts into `localization/custom_<lang>.json` of the Achievements data folder, so updates never overwrite them.

**Example:**
```json title="localization/custom_en-US.json"
{
  "achievements.title.warrior": "Warrior",
  "achievements.title.exterminator": "Exterminator",
  "achievements.title.snake_charmer": "Snake Charmer",
  "achievements.title.arachnophobe": "Arachnophobe"
}
```

## Example Titles from Default Achievements

| Title ID | Color | Achievement | Requirement |
|----------|-------|-------------|-------------|
| `warrior` | #FF4444 | First Blood | Kill 1 mob |
| `exterminator` | #8B4513 | Spider Hunter IV | Kill 100 spiders |
| `arachnophobe` | #4B0082 | Spider Hunter V | Kill 500 spiders |
| `snake_charmer` | #228B22 | Snake Slayer III | Kill 100 snakes |
| `venom_master` | #006400 | Snake Slayer IV | Kill 500 snakes |

## Command Reference

| Command | Aliases | Description | Access |
|---------|---------|-------------|--------|
| `/kstitles` | `/title` | Open the titles tab of the achievement book | `ks.achievements.user.titles` (allowed by default) |