# Tier System

# Tier System

The Tier System assigns rarity levels to quests based on their difficulty. Each tier has a colour, a display name per language and a reward multiplier. Server owners can fully customize tiers or use the built-in defaults, in `config.json` or in the **Rewards & economy** tab of the [admin window](./admin-panel#settings).

## Default Tiers

Out of the box, the system provides four tiers:

| Tier | Difficulty | Color | Reward Multiplier |
|------|-----------|-------|-------------------|
| Common | easy | Gray `#A0A0A0` | 1.0x |
| Rare | medium | Blue `#4169E1` | 2.0x |
| Epic | hard | Purple `#9932CC` | 3.0x |
| Legendary | legendary | Gold `#FFD700` | 5.0x |

The reward multiplier scales the numeric rewards of that quest. A Legendary quest with a base reward of 3 iron ore grants 15 iron ore (3 × 5.0). The Questbook shows the multiplier on the quest's difficulty chip, and the reward amounts already include it. Switch `tierSystem.enabled` off ("Apply tier factor" in the admin window) to pay base rewards only.

## How Tiers Are Assigned

Each quest definition has a `difficulty` field. The tier system maps this difficulty string to a tier:

```
Quest difficulty: "easy"    --> Tier: Common  (1.0x rewards)
Quest difficulty: "medium"  --> Tier: Rare    (2.0x rewards)
Quest difficulty: "hard"    --> Tier: Epic    (3.0x rewards)
Quest difficulty: "legendary" --> Tier: Legendary (5.0x rewards)
```

Alternative difficulty names are also recognized:

| Input | Maps To |
|-------|---------|
| `normal`, `simple`, `basic` | Common (easy) |
| `uncommon`, `moderate`, `challenging` | Rare (medium) |
| `difficult`, `very_hard`, `expert` | Epic (hard) |
| `extreme`, `mythic`, `artifact`, `ancient` | Legendary |

If a quest has no difficulty or an unrecognized value, it defaults to Common.

## Configuration

The tier system is configured in `config.json` under `tierSystem`:

```json
{
  "tierSystem": {
    "enabled": true,
    "tiers": [
      {
        "id": "common",
        "difficulty": "easy",
        "color": "#A0A0A0",
        "multiplier": 1.0,
        "weight": 50,
        "name": { "en": "Common", "de": "Gewoehnlich" }
      },
      {
        "id": "rare",
        "difficulty": "medium",
        "color": "#4169E1",
        "multiplier": 2.0,
        "weight": 30,
        "name": { "en": "Rare", "de": "Selten" }
      },
      {
        "id": "epic",
        "difficulty": "hard",
        "color": "#9932CC",
        "multiplier": 3.0,
        "weight": 15,
        "name": { "en": "Epic", "de": "Episch" }
      },
      {
        "id": "legendary",
        "difficulty": "legendary",
        "color": "#FFD700",
        "multiplier": 5.0,
        "weight": 5,
        "name": { "en": "Legendary", "de": "Legendaer" }
      }
    ]
  }
}
```

### Tier Definition Fields

| Field | Required | Description |
|-------|----------|-------------|
| `id` | Yes | Unique identifier (e.g., `"common"`, `"rare"`) |
| `difficulty` | Yes | Difficulty string that maps quests to this tier |
| `color` | No | Hex color for UI display (default: `#FFFFFF`) |
| `multiplier` | No | Reward multiplier (default: `1.0`) |
| `weight` | No | Not used. How often a quest is drawn comes from its pool weight |
| `name` | No | Localized display names by language |

:::tip
The `name` field supports any number of languages. If no localization key (`tier.<id>.name`) exists in the translation files, the inline `name` map is used as fallback.
:::

## Tiers and Pool Selection

Tiers do not decide which quests are drawn. Daily and weekly quests are drawn by the `weight` of each **pool entry**, the same with the tier system on or off. The shipped pools give the four variants of a quest family the weights 50, 30, 15 and 5, so a Legendary variant shows up about 5% as often as its family. See [Daily & Weekly Pools](./daily-weekly-pools#weight-system).

## Custom Tier Systems

You can define any number of tiers with custom names, colors, and multipliers. The tiers are ordered by their position in the array (first = lowest, last = highest).

### Example: 5-Tier System

```json
{
  "tierSystem": {
    "enabled": true,
    "tiers": [
      { "id": "basic", "difficulty": "easy", "color": "#808080", "multiplier": 1.0 },
      { "id": "uncommon", "difficulty": "normal", "color": "#2E8B57", "multiplier": 1.5 },
      { "id": "rare", "difficulty": "medium", "color": "#4169E1", "multiplier": 2.0 },
      { "id": "epic", "difficulty": "hard", "color": "#9932CC", "multiplier": 3.5 },
      { "id": "mythic", "difficulty": "legendary", "color": "#FF4500", "multiplier": 7.0 }
    ]
  }
}
```

### Example: Simple 3-Tier System

```json
{
  "tierSystem": {
    "enabled": true,
    "tiers": [
      { "id": "normal", "difficulty": "easy", "color": "#FFFFFF", "multiplier": 1.0 },
      { "id": "hard", "difficulty": "hard", "color": "#FF6600", "multiplier": 2.5 },
      { "id": "extreme", "difficulty": "legendary", "color": "#FF0000", "multiplier": 5.0 }
    ]
  }
}
```

:::info
If the `tiers` array is empty or not provided, the system falls back to the built-in 4-tier defaults (Common/Rare/Epic/Legendary).
:::

## Tier Display in the UI

Tiers affect how quests appear throughout the UI:

- **Questbook** -- a difficulty chip with the tier colour and the reward multiplier; rewards are shown with the factor applied
- **Quest Tracker HUD** -- the quest icon has a rarity ring
- **Admin window** -- the Pools tab groups the tier variants of a quest family

## Integration with Mod Editor

The Mod Editor admin panel includes a **Tier Generator** feature. This tool creates multiple difficulty variants from a single quest template:

1. Create a base quest (e.g., "Mine Stone" with 50 stone)
2. Use the tier generator to produce variants:
   - `daily_mine_stone` (Common) -- 50 stone, 1x rewards
   - `daily_mine_stone_rare` (Rare) -- 100 stone, 2x rewards
   - `daily_mine_stone_epic` (Epic) -- 200 stone, 3x rewards
   - `daily_mine_stone_legendary` (Legendary) -- 500 stone, 5x rewards

The generator scales both objective counts and rewards based on the tier multiplier, then adds all variants to the appropriate quest pool.

:::warning
When creating custom tiers, make sure your quest definitions use matching `difficulty` values. A quest with `"difficulty": "mythic"` will only map to a tier that has `"difficulty": "mythic"` (or a recognized fallback alias). Unmatched difficulties default to the lowest tier.
:::