# Rewards

# Rewards

Every quest can grant one or more rewards when completed. Rewards are defined in the `rewards` array of a quest definition and are automatically granted to the player upon turn-in.

## Reward Structure

```json
"rewards": [
  { "type": "quest_tokens", "amount": 10 },
  { "type": "item", "item_id": "Tool_Pickaxe_Copper", "amount": 1 }
]
```

Each reward requires a `type` field and type-specific parameters described below.

## All Reward Types

### Quest Tokens

The primary quest currency. Players earn tokens from completing quests and can spend them in the Quest Token Shop.

```json
{ "type": "quest_tokens", "amount": 25 }
```

| Field | Required | Description |
|-------|----------|-------------|
| `amount` | Yes | Number of tokens to grant |

### Item

Grants a specific item directly to the player's inventory.

```json
{ "type": "item", "item_id": "Tool_Pickaxe_Copper", "amount": 1 }
```

| Field | Required | Description |
|-------|----------|-------------|
| `item_id` | Yes | The item ID (e.g. `Weapon_Sword_Iron`, `Food_Bread`) |
| `amount` | Yes | Number of items to give |

:::note Full Inventory
If the item does not fit, the part that did not fit is saved as a **pending reward**. Pending rewards are handed out at the player's next login, and admins can hand them out at once with **Deliver now** in the Players tool of the [admin window](./admin-panel#players).
:::

### Lootbag

Grants a loot bag that the player can open for randomized rewards.

```json
{ "type": "lootbag", "lootbag_id": "hunter_reward" }
```

| Field | Required | Description |
|-------|----------|-------------|
| `lootbag_id` | Yes | The loot bag definition ID |

The bag is rolled when the reward is paid. Rolled items that do not fit wait as pending rewards. An unknown bag ID pays 30 quest tokens instead.

### Currency

Grants a named currency (gold, silver, custom currencies).

```json
{ "type": "currency", "currency": "gold", "amount": 100 }
```

| Field | Required | Description |
|-------|----------|-------------|
| `currency` | Yes | Currency name (e.g. `gold`, `silver`) |
| `amount` | Yes | Amount to grant |

### RPG XP

Grants general character experience points via the RPG leveling system.

```json
{ "type": "rpg_xp", "amount": 500 }
```

| Field | Required | Description |
|-------|----------|-------------|
| `amount` | Yes | XP amount to grant |

### MMO XP

Grants skill-specific experience points via the MMO skill tree system.

```json
{ "type": "mmo_xp", "skill": "mining", "amount": 150 }
```

| Field | Required | Description |
|-------|----------|-------------|
| `skill` | Yes | Skill name (e.g. `mining`, `combat`, `woodcutting`) |
| `amount` | Yes | XP amount to grant |

### Endless XP

Grants experience points for the Endless leveling system.

```json
{ "type": "endless_xp", "amount": 200 }
```

| Field | Required | Description |
|-------|----------|-------------|
| `amount` | Yes | XP amount to grant |

### Leveling XP

Grants experience points for the main character leveling system.

```json
{ "type": "leveling_xp", "amount": 300 }
```

| Field | Required | Description |
|-------|----------|-------------|
| `amount` | Yes | XP amount to grant |

### Title

Unlocks a title that the player can display. Titles are managed by KyuubiSoft Achievements; the admin window has a picker for them.

```json
{ "type": "title", "title_id": "forest_protector" }
```

| Field | Required | Description |
|-------|----------|-------------|
| `title_id` | Yes | Title identifier (e.g. `mining_master`, `newcomer`) |

### Achievement

Unlocks an achievement of KyuubiSoft Achievements for the player.

```json
{ "type": "achievement", "achievement_id": "story_complete" }
```

| Field | Required | Description |
|-------|----------|-------------|
| `achievement_id` | Yes | Achievement identifier |

### Command

Executes a server command as a reward. Supports placeholder substitution for the player name.

```json
{ "type": "command", "command": "give {player} Food_Apple 10", "executor": "console" }
```

| Field | Required | Description |
|-------|----------|-------------|
| `command` | Yes | The command string. Use `{player}` as a placeholder for the player name |
| `executor` | No | Who runs the command: `"console"` (default) or `"player"` |

:::caution Console rule
A command reward that runs as the console has every right on the server. Adding, changing or removing one needs `ks.core.admin.dialog.console` in addition to `ks.quest.admin`, in the admin window, with `/ksquestadmin import` and in web editor imports. See [Permissions](./permissions#the-console-rule).
:::

:::tip When to use command rewards
Command rewards connect quests to other plugins: grant a permission, teleport a player or call a command of another mod. Use `"executor": "player"` whenever the command does not need console rights.
:::

## Reward Type Summary

| Type | Key Fields | Scales with Tier | Fallback |
|------|-----------|:----------------:|----------|
| `quest_tokens` | `amount` | Yes | -- |
| `item` | `item_id`, `amount` | Yes (amount) | Pending reward if inventory full |
| `lootbag` | `lootbag_id` | No | 30 Quest Tokens |
| `currency` | `currency`, `amount` | Yes | -- |
| `rpg_xp` | `amount` | Yes | Quest Tokens (XP / 10) |
| `mmo_xp` | `skill`, `amount` | Yes | Quest Tokens (XP / 10) |
| `endless_xp` | `amount` | Yes | Quest Tokens (XP / 10) |
| `leveling_xp` | `amount` | Yes | Quest Tokens (XP / 10) |
| `title` | `title_id` | No | 25 Quest Tokens if not granted |
| `achievement` | `achievement_id` | No | 15 Quest Tokens if not granted |
| `command` | `command`, `executor` | No | -- |

## Automatic Fallbacks

The quest system gracefully handles situations where external plugins are not installed:

- **RPG XP / MMO XP** -- If the leveling plugin is not available, XP rewards are converted to Quest Tokens at a rate of **XP / 10**.
- **Endless XP** -- If the Endless leveling plugin is not available, XP rewards are converted to Quest Tokens at a rate of **XP / 10**.
- **Leveling XP** -- If the leveling plugin is not available, XP rewards are converted to Quest Tokens at a rate of **XP / 10**.
- **Title** -- If KyuubiSoft Achievements is not installed or the title ID is unknown, the reward becomes **25 Quest Tokens**.
- **Achievement** -- If KyuubiSoft Achievements is not installed or the achievement ID is unknown, the reward becomes **15 Quest Tokens**.
- **Lootbag** -- If the lootbag ID is not found, the reward becomes **30 Quest Tokens**.
- **Currency** -- A named currency is paid through KyuubiSoft Core. Without an economy plugin the payment fails and is logged.

Before version 2.0.0, achievement and title rewards always paid the token fallback, and XP rewards written as `amount` paid 0 XP. Both are paid correctly now.

This means you can safely configure any reward type without worrying about crashes from missing plugins.

## Tier Multiplier

The [tier system](./tier-system) scales numeric rewards by the quest's difficulty (default factors 1×, 2×, 3× and 5×). `amount`-based rewards (Quest Tokens, Items, Currency, XP) are multiplied by the tier factor. For example, an Epic quest (3×) turns a `"amount": 10` token reward into 30 tokens.

Non-numeric rewards (Titles, Achievements, Lootbags, Commands) are not affected by the multiplier.

Daily and weekly quests also pay the token bonus from `economy.tokenEarnings` (`dailyQuestComplete`, `weeklyQuestComplete`). The Questbook and the admin window show the final values including the factor and the bonus.

In **economy mode** (`economy.rewardCurrency: "economy"`) every quest token reward is paid as coins of the economy plugin instead (tokens × `tokenExchangeRate`).

## Multiple Rewards

Every quest can have any number of rewards. It is recommended to always include at least `quest_tokens` as a baseline reward:

```json title="Example: Mixed reward set"
"rewards": [
  { "type": "quest_tokens", "amount": 10 },
  { "type": "item", "item_id": "Weapon_Sword_Iron", "amount": 1 },
  { "type": "lootbag", "lootbag_id": "hunter_reward" },
  { "type": "mmo_xp", "skill": "combat", "amount": 200 }
]
```

## Chapter Completion Rewards

Story chapters can also define rewards that are granted when all quests in a chapter are completed. They use the same reward format and the same reward builder in the admin window, but no tier factor:

```json title="Example: Chapter rewards in chapters.json"
{
  "id": "chapter_1_forest",
  "rewards": [
    { "type": "currency", "currency": "quest_tokens", "amount": 100 },
    { "type": "title", "title_id": "forest_protector" },
    { "type": "lootbag", "lootbag_id": "chapter_1_reward" }
  ]
}
```

## How Rewards Are Granted

1. **Player completes all objectives** -- the quest moves to the "ready to turn in" state (quests with `options.auto_claim` complete right away)
2. **Player turns in the quest** -- with **Claim reward** in the Questbook or at the quest giver NPC
3. **Consumed items are checked first** -- for objectives with `consumeItems`, nothing is completed or taken while items are missing
4. **All rewards are processed** -- items go to inventory, tokens are added, XP is granted
5. **If an item does not fit** -- the rest becomes a **pending reward**, handed out at the next login
6. **A completion message** is shown to the player with a summary of all rewards received