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
Section titled “Reward Structure”"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
Section titled “All Reward Types”Quest Tokens
Section titled “Quest Tokens”The primary quest currency. Players earn tokens from completing quests and can spend them in the Quest Token Shop.
{ "type": "quest_tokens", "amount": 25 }| Field | Required | Description |
|---|---|---|
amount | Yes | Number of tokens to grant |
Grants a specific item directly to the player’s inventory.
{ "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. :::
Lootbag
Section titled “Lootbag”Grants a loot bag that the player can open for randomized rewards.
{ "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
Section titled “Currency”Grants a named currency (gold, silver, custom currencies).
{ "type": "currency", "currency": "gold", "amount": 100 }| Field | Required | Description |
|---|---|---|
currency | Yes | Currency name (e.g. gold, silver) |
amount | Yes | Amount to grant |
RPG XP
Section titled “RPG XP”Grants general character experience points via the RPG leveling system.
{ "type": "rpg_xp", "amount": 500 }| Field | Required | Description |
|---|---|---|
amount | Yes | XP amount to grant |
MMO XP
Section titled “MMO XP”Grants skill-specific experience points via the MMO skill tree system.
{ "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
Section titled “Endless XP”Grants experience points for the Endless leveling system.
{ "type": "endless_xp", "amount": 200 }| Field | Required | Description |
|---|---|---|
amount | Yes | XP amount to grant |
Leveling XP
Section titled “Leveling XP”Grants experience points for the main character leveling system.
{ "type": "leveling_xp", "amount": 300 }| Field | Required | Description |
|---|---|---|
amount | Yes | XP amount to grant |
Unlocks a title that the player can display. Titles are managed by KyuubiSoft Achievements; the admin window has a picker for them.
{ "type": "title", "title_id": "forest_protector" }| Field | Required | Description |
|---|---|---|
title_id | Yes | Title identifier (e.g. mining_master, newcomer) |
Achievement
Section titled “Achievement”Unlocks an achievement of KyuubiSoft Achievements for the player.
{ "type": "achievement", "achievement_id": "story_complete" }| Field | Required | Description |
|---|---|---|
achievement_id | Yes | Achievement identifier |
Command
Section titled “Command”Executes a server command as a reward. Supports placeholder substitution for the player name.
{ "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.
:::
:::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
Section titled “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
Section titled “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
Section titled “Tier Multiplier”The 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
Section titled “Multiple Rewards”Every quest can have any number of rewards. It is recommended to always include at least quest_tokens as a baseline reward:
"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
Section titled “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:
{ "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
Section titled “How Rewards Are Granted”- Player completes all objectives — the quest moves to the “ready to turn in” state (quests with
options.auto_claimcomplete right away) - Player turns in the quest — with Claim reward in the Questbook or at the quest giver NPC
- Consumed items are checked first — for objectives with
consumeItems, nothing is completed or taken while items are missing - All rewards are processed — items go to inventory, tokens are added, XP is granted
- If an item does not fit — the rest becomes a pending reward, handed out at the next login
- A completion message is shown to the player with a summary of all rewards received