Tasks

Add, edit, and remove tasks

Wiki home · Task givers · Rewards

A task template defines the work. Its category determines where it can be offered, and its giver's reward pools supply the payout. Edit files under config/taskbound/data/<namespace>/task_templates/.

Edit an existing task

Find its template in config/taskbound/data/taskbound/task_templates/. For example, Hunter's Pest Control task is hunter/catalog/1_01_pest_control.json.

Change	Field
Required amount	Each objective's parameters.required_count. Use a positive integer.
Target	The objective-specific parameter, such as entity, item, or block.
Description	Template description: optional non-blank plain text, shown literally.
Title	Template title: optional non-blank plain text. An existing variant conditions.title override takes precedence.
Timer	Optional template time_limit_ticks: positive integer, 1200 ticks per minute. Omit for untimed.
Unlock level	Template minimum_reputation_level; its category must also be unlocked.
Last eligible level	maximum_reputation_level; use null for no upper limit.
Relative frequency	Template base_weight, or variant weight when choosing among variants.
Difficulty and payout budget	base_difficulty plus difficulty_components, then the giver's reward_multiplier.

Every shipped template includes editable title and description beside its objectives. These fields are literal server-provided text, so no client resource pack is needed. Keep the required display_text field as the 1.0 fallback. Omit optional fields to use that fallback; empty strings, nulls and non-string values are invalid.

Title precedence is the existing variant conditions.title override (translated as before), then template title (literal), then the title derived from display_text. Description uses template description (literal), otherwise display_text (translated as before). For per-client translations, omit the literal fields and use language keys.

Changing an objective count or condition does not rewrite the description or difficulty. Keep all three consistent. New offers snapshot the text; already accepted tasks keep their saved text and requirements. Original 1.0 tasks without the new fields still use their language keys.

Add a task

Create config/taskbound/data/mytasks/task_templates/watch/zombie_patrol.json:

{
  "id": "mytasks:watch/zombie_patrol",
  "category_id": "mytasks:watch/starter",
  "minimum_reputation_level": 1,
  "maximum_reputation_level": null,
  "base_weight": 10.0,
  "base_difficulty": 6,
  "display_text": "Defeat five zombies to help protect the village.",
  "title": "Zombie Patrol",
  "description": "Defeat 5 zombies to help protect the village.",
  "required_capabilities": ["minecraft:kill_entity"],
  "variants": [
    {
      "id": "mytasks:watch/zombie_patrol/standard",
      "weight": 1.0,
      "objectives": [
        {
          "type": "kill_entity",
          "parameters": {
            "required_count": 5,
            "entity": "minecraft:zombie"
          },
          "difficulty_components": [],
          "required_capabilities": ["minecraft:kill_entity"]
        }
      ],
      "conditions": {
        "source_catalog_id": "mytasks:watch/zombie_patrol"
      },
      "difficulty_components": [],
      "required_capabilities": []
    }
  ]
}

Add mytasks:watch/zombie_patrol to the category's template_ids. The starter category already contains that reference. Use the remaining example files to make this task available through its own giver.

Keep source_catalog_id on new vanilla-event tasks. It identifies the source definition and enables validation of supported objective parameters and conditions. It can be the same ID as your new template; it does not require another file. Capability names advertise implemented event support; changing them does not implement a new objective type.

For another variant, duplicate the variant object, give it a unique id, and change its objectives and weight. One variant is selected when the task is generated. Multiple objectives within that selected variant must all be completed.

Supported vanilla objective types

Use the capability minecraft:<type> for each of these types. Every objective needs required_count; an objective field named count is unsupported. These are the supported vanilla-event types for new tasks:

Type	Target parameters	What counts
kill_entity	entity, entity_tag, or hostile_only: true	Credited kills. Optional method: "melee".
catch_item	fish_item or fish_item_tag	Items obtained through fishing loot.
craft_item	item	Manually crafted output units.
gather_block	block	Directly broken original blocks.
harvest_crop	block	Mature minecraft:wheat or minecraft:cocoa.
enchant_item	item	Enchanting; optional method: "table" or "anvil", required_enchantment, and minimum_enchantment_level.
challenge_action	action	shield_block, shield_block_skeleton_arrows, shield_block_piglin, or bow_hit_on_hostile.

IDs must name resources present on the server. A tag parameter takes a resource ID such as minecraft:logs, without a leading #. Tags, recipes, and loot tables belong in normal datapacks, not the five config definition directories.

Optional objective context includes required_dimension, required_biome, required_biome_tag, required_time (day or night), required_weather (rain, snow, clear, or thunder), min_y, and max_y. Put these inside that objective's parameters, not the variant's conditions. See the condition reference for equipment, effect, and structure predicates. Fishing equipment provenance and other deferred tracking mechanisms cannot be enabled just by adding parameters.

Variant conditions can additionally contain:

Field	Meaning
one_time: true	Cannot be offered again after that player claims it.
objective_order: "strict"	Complete the objectives in their listed order.
no_death: true	Do not die before claiming the reward.
reset_on_death: true	Death resets progress.
cooldown_ticks: 24000	Override the cooldown after claiming this template; 20 ticks is normally one second.

There is no template-level fixed rewards array. Tune reward entries and pools, difficulty, and the giver's multiplier to change payouts.

Item hand-ins

Use hand_in_item with an item ID and required_count to request supplies. Basic hand-ins accept stockpiled or automated items. Optional potion, enchantment, and production-mark requirements are described in the production objective reference.

After completing the other objectives, the player selects Hand in at a Task Board. A native inventory popup lets them click, drag, or shift-click the exact stacks into matching request slots, then press Confirm. Items elsewhere in their inventory are not selected or consumed automatically. This lets players keep a particular renamed or enchanted stack and submit another eligible one.

The server checks the deposited supplies and task conditions before consuming them or granting rewards. Cancel, Escape, or closing returns deposits and the cursor stack using vanilla inventory handling; full-inventory overflow drops nearby, and death or disconnection follows vanilla's drop behavior. An expired or invalid task cannot be confirmed. Opening the popup does not pause a task timer.

All hand-ins are submitted together after the other work is complete; place them in the final phase of an ordered task. Limit the combined requirements to 36 simultaneous stacks, counting each objective separately at its item's normal maximum stack size. For example, 130 wheat uses 3 slots and 2 unstackable swords use 2 slots. A task exceeding that limit cannot open the hand-in popup. Reduce its requirements or split it into separate tasks.

Remove a task

1. Remove its ID from its category's template_ids.
2. Remove the template JSON from every active config/datapack source that supplies it.
3. If it was the category's last template, remove that category JSON too, and remove the category ID from the giver's category_ids. Categories cannot have an empty template_ids list.
4. Reload once after all related changes are saved.

Live references to missing templates remain validation errors; deleting only the template is incomplete. Removing or editing a template does not rewrite tasks players have already accepted. Those retain their saved requirements and rewards.

To remove a whole guild, follow the giver removal instructions; you do not need to unlink every child file individually.

Test the result

After a successful reload, obtain a new offer and perform its actual objective. For the example, use /taskbound debug offers @s mytasks:watch to refresh that giver's available offers, then accept Zombie Patrol from the board and defeat five zombies.

For a targeted inspection, /taskbound debug assign @s mytasks:watch mytasks:watch/zombie_patrol creates an accepted instance and /taskbound debug inspect @s shows player state. Assignment bypasses normal offer selection, so use the normal offer list to verify unlock levels, availability, and repeat restrictions. /taskbound debug complete bypasses gameplay progress and is only a claim-path check.

See timers and grouped phases and the production, world, and encounter guides for the new objective types.

Multi-step descriptions can use one • bullet line per objective, in objective order. Separate lines with \n inside JSON strings. When the number of action bullets matches the objective count, the board and journal replace completed bullets with checkmarks; unbulleted shared rules remain ordinary text. The Objectives section always uses the server-reported counts.