Tasks

Add, edit, and remove tasks

Looking for the task list? The full task catalog lists each task's objectives, tier, timer and reward information. This page explains how to customize those tasks.

A task template defines the work. A category controls where it is offered, and the giver's reward pools supply its payout. Use config/taskbound/data/<namespace>/task_templates/.

Edit an existing task

The default Hunter task Pest Control is taskbound/task_templates/hunter/catalog/1_01_pest_control.json under config/taskbound/data/.

Change	Field
Title and description	Template title and description
Required quantity	Objective parameters.required_count, a positive integer
Target	Type-specific entity, item, block, or other supported parameter
Timer	Template time_limit_ticks; omit for untimed, use a positive integer for timed
Unlock level	minimum_reputation_level; the category must also be unlocked
Last eligible level	maximum_reputation_level, or null for no upper limit
Relative chance	Template base_weight or variant weight
Effort and reward budget	base_difficulty, difficulty components, and the giver's reward multiplier
Explicit currency payout	Variant conditions.currency_reward; new Farmer, Starcatcher and Porter templates use it

Descriptions are written text, not generated from objective counts. When changing requirements, update the text and difficulty too. New offers use the changes; accepted tasks keep their saved requirements and rewards.

Since 1.1.0, kill tasks can select exact damage types or damage tags, including explosion-only kills. See damage requirements and modded weapons for a copyable objective and attribution rules.

The shipped templates contain plain-text title and description. Keep the required display_text field. Omit optional text fields to use their translation fallback; do not use null, blank, or non-string values. An existing variant conditions.title override takes priority over template title.

For multi-step text, use one • bullet per objective, in objective order, separated by \n inside the JSON string. When action-bullet count matches objective count, completed bullets become checkmarks. Put shared restrictions on separate unbulleted lines. The objective counts remain the authoritative progress display.

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

Create the giver and category and reward from the shared example before reloading. The category's template_ids must include this task, and the template's category_id must point back to that category.

Keep source_catalog_id on vanilla-event tasks; for custom tasks it can equal the template ID and does not require another file. Use capabilities matching the objectives: normally minecraft:<objective_type>; Starcatcher uses starcatcher:catch. Adding a capability name cannot add a new mechanic by itself. See the objective reference.

Each variant has its own unique ID, positive selection weight, and objectives. One variant is selected per generated task; all of that variant's objectives must finish. There is no template-level fixed rewards array: use variant conditions.currency_reward for a fixed currency payment, or reward entries and pools.

Timers and phases

Set time_limit_ticks to a positive integer. 1200 ticks = one minute at normal server speed; 18000 is fifteen minutes. Omit the field for untimed tasks. Zero, null, and fractional values are invalid. Timing starts on acceptance and includes any final hand-in.

In the selected variant's conditions, use:

Field	Effect
one_time: true	No more offers after a successful claim
objective_order: "strict"	Complete objectives one at a time in listed order
objective_stages: [0, 0, 1, 1]	Finish both phase-0 objectives before either phase-1 objective
no_death: true	Do not die before claiming
reset_on_death: true	Death resets progress
cooldown_ticks: 24000	Override the same-template cooldown after claim

Do not combine objective_order and objective_stages. A stage array needs one integer per objective, must start at zero, be nondecreasing, and rise by at most one between adjacent entries.

Item hand-ins

Use hand_in_item, exactly one of item or item_tag, and required_count. Plain hand-ins can use existing supplies. Potion, enchantment, and task-produced-item restrictions are available in the objective reference.

Put hand-ins in the final phase, after other objectives. They are submitted together in the board's inventory popup. Combined requirements must fit 36 simultaneous stacks. Tagged hand-ins accept mixed matching stacks, such as several wool colors, and show the remaining total; fill only enough to meet the requirement. Count ordinary item requests at their normal stack size. For example, 130 wheat needs three slots and two unstackable swords need two. Larger requirements cannot open the popup; reduce the amounts or split the task.

Remove a task

1. Remove its ID from the category's template_ids.
2. Remove the template file from all active config/datapack sources that supply it.
3. If it was the category's last task, remove that category too and unlink it from the giver. An empty template_ids list is invalid.
4. Save all related changes and reload once.

Deleting only a referenced template leaves an invalid catalog. Accepted tasks retain their saved work and payouts after removal. For removing a whole guild, use the giver removal steps.