Skip to content

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.

"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.

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

{ "type": "quest_tokens", "amount": 25 }
FieldRequiredDescription
amountYesNumber of tokens to grant

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

{ "type": "item", "item_id": "Tool_Pickaxe_Copper", "amount": 1 }
FieldRequiredDescription
item_idYesThe item ID (e.g. Weapon_Sword_Iron, Food_Bread)
amountYesNumber 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. :::

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

{ "type": "lootbag", "lootbag_id": "hunter_reward" }
FieldRequiredDescription
lootbag_idYesThe 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.

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

{ "type": "currency", "currency": "gold", "amount": 100 }
FieldRequiredDescription
currencyYesCurrency name (e.g. gold, silver)
amountYesAmount to grant

Grants general character experience points via the RPG leveling system.

{ "type": "rpg_xp", "amount": 500 }
FieldRequiredDescription
amountYesXP amount to grant

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

{ "type": "mmo_xp", "skill": "mining", "amount": 150 }
FieldRequiredDescription
skillYesSkill name (e.g. mining, combat, woodcutting)
amountYesXP amount to grant

Grants experience points for the Endless leveling system.

{ "type": "endless_xp", "amount": 200 }
FieldRequiredDescription
amountYesXP amount to grant

Grants experience points for the main character leveling system.

{ "type": "leveling_xp", "amount": 300 }
FieldRequiredDescription
amountYesXP 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" }
FieldRequiredDescription
title_idYesTitle identifier (e.g. mining_master, newcomer)

Unlocks an achievement of KyuubiSoft Achievements for the player.

{ "type": "achievement", "achievement_id": "story_complete" }
FieldRequiredDescription
achievement_idYesAchievement identifier

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

{ "type": "command", "command": "give {player} Food_Apple 10", "executor": "console" }
FieldRequiredDescription
commandYesThe command string. Use {player} as a placeholder for the player name
executorNoWho 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. :::

TypeKey FieldsScales with TierFallback
quest_tokensamountYes—
itemitem_id, amountYes (amount)Pending reward if inventory full
lootbaglootbag_idNo30 Quest Tokens
currencycurrency, amountYes—
rpg_xpamountYesQuest Tokens (XP / 10)
mmo_xpskill, amountYesQuest Tokens (XP / 10)
endless_xpamountYesQuest Tokens (XP / 10)
leveling_xpamountYesQuest Tokens (XP / 10)
titletitle_idNo25 Quest Tokens if not granted
achievementachievement_idNo15 Quest Tokens if not granted
commandcommand, executorNo—

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.

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).

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

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 }
]

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:

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" }
]
}
  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