Rewards

Add, edit, and remove rewards

Wiki home · Tasks · Task Givers

Task payouts and reputation-level gifts are different systems. rewards/ supplies candidates for newly generated tasks; level_rewards/ defines fixed supplies claimed once at intermediate guild levels.

Add an item reward

Create config/taskbound/data/mytasks/rewards/watch/emeralds.json:

{
  "id": "mytasks:watch/emeralds",
  "type": "ITEM",
  "pool_id": "mytasks:watch",
  "weight": 1.0,
  "cost": 6,
  "minimum_difficulty": 0,
  "maximum_difficulty": null,
  "minimum_reputation_level": null,
  "maximum_count": 1,
  "giver_restrictions": ["mytasks:watch"],
  "rarity_group": "common",
  "tangible": true,
  "payload": {
    "item": "minecraft:emerald",
    "count": 2
  }
}

Add mytasks:watch to the giver's reward_pool_ids; the Village Watch example already does this. There is no separate pool JSON file. Entries with the same pool_id belong to the same pool.

With only this entry in its pool, the example Zombie Patrol task has difficulty 6 and multiplier 1.0, giving a budget of 6. It can select this entry once and award two emeralds, plus the task's normal guild reputation. Create: Numismatics can convert the emerald payout as described below.

The custom two-emerald example above has its own fixed cost of 6; it is independent of the built-in catalog rebalance.

Tune a payout

Generation selects the task first, calculates its difficulty, then selects affordable rewards. The budget is round(difficulty_score × giver.reward_multiplier). The built-in higher-band emerald entries have lower costs per emerald and weights equal to cost⁴, targeting roughly difficulty^1.5 payouts within the three-pick limit. For example, taskbound:catalog/level_2/emerald_5 costs 10 budget points for five emeralds. This changes new task payouts; fixed level gifts and already accepted rewards stay unchanged.

Field	Meaning
pool_id	Pool this candidate belongs to. The giver selects pools.
weight	Relative chance among eligible, affordable candidates; positive number.
cost	Budget points spent each time the entry is selected; positive integer.
minimum_difficulty / maximum_difficulty	Inclusive difficulty range; null maximum means no upper limit.
minimum_reputation_level	Optional level gate; null means no extra gate.
maximum_count	Maximum number of times this entry can be selected for one task.
giver_restrictions	Allowed giver IDs; an empty array allows any giver whose pools include the entry.
rarity_group	rare entries are limited to one selection per task; common avoids that extra limit.
tangible	Keep true for item rewards. Selection seeks a tangible reward first.
payload.item	Registered item ID, including a modded ID when that mod is installed.
payload.count	Item units granted per selection; use a positive integer.

The default policy permits up to three reward selections in total. Actual item units are payload.count × number of selections; maximum_count is not the stack size. Higher weight does not make an unaffordable entry eligible. Higher cost spends more budget without changing the item quantity.

Ensure each intended difficulty range has an affordable item reward. A pool containing only expensive or ineligible entries can produce no item payout. An empty giver reward_pool_ids array means all pools, not no rewards.

For experience, use type EXPERIENCE and a payload such as {"experience_points": 20}. For additional reputation, use type REPUTATION and {"points": 2}; optional giver names a particular giver, otherwise it uses the task's giver. Mark these non-item candidates tangible: false and keep affordable tangible candidates in the pool. LOOT_TABLE and CALLBACK are reserved types without a built-in payout handler; do not use them for ordinary config rewards.

To edit a reward, keep its ID and change the relevant fields, then reload. To add another, create a new file with its own matching ID and choose its pool. To remove one, delete that reward file from all active sources and reload; pools contain no list that needs unlinking. Check that the remaining pool still has suitable rewards. Already accepted tasks keep their saved payouts, even if an entry is edited or removed.

Intermediate reputation gifts

Create the optional config/taskbound/data/mytasks/level_rewards/watch.json:

{
  "id": "mytasks:watch",
  "rewards": [
    {
      "level": 2,
      "items": [
        {"item": "minecraft:arrow", "count": 4}
      ]
    },
    {
      "level": 3,
      "items": [
        {"item": "minecraft:bread", "count": 2}
      ]
    }
  ]
}

The file's ID is the giver ID, not a new reward ID. Allowed levels are 2–4, 6–9, 11–14, and 16–19. Each level appears at most once, has at least one item, and each item count is 1–64. Levels 1, 5, 10, 15, and 20 are main milestones and cannot receive these gift entries.

Add a level entry to add a gift, edit its items to change it, or remove the level entry to remove an unclaimed gift. Removing the entire file removes all unclaimed gifts for that giver. Reload afterward. Gifts do not use reward weights, pools, budgets, or the giver's reward multiplier.

Gift claims are recorded by giver and level. Editing or restoring the file does not grant a second gift to someone who already claimed that level. A missing giver's gift file is ignored until that giver is restored. Intermediate levels still increase available offers even when no gift is configured.

Create: Numismatics

When Create: Numismatics is installed, built-in compatibility converts emerald task payouts to spurs by default. The default rate is one emerald = one spur; other items are retained. Without Numismatics, the same definitions award emeralds.

The server's taskbound-server.toml contains [rewards] settings use_numismatics_rewards (default true) and numismatics_spurs_per_emerald (default 1). Set the former to false to retain emeralds, or change the latter to adjust the rate. Conversion applies when new task offers are generated, so accepted tasks keep the currency and amount saved at acceptance. Fixed level_rewards gifts use the exact items you configure.

The board's Rewards heading uses the registered numismatics:spur item when conversion is enabled on the server and the mod/coin is available. Otherwise it uses minecraft:emerald. Individual reward icons still show the actual items in the saved task reward.

Check a reward change

Reload and inspect a new offer's displayed reward. Complete and claim it in a test world, then check the inventory and reputation change. Test each difficulty band you edited. For repeatable tests, operator debug assignment creates a fresh task snapshot, but it does not verify normal offer eligibility or actual objective tracking.