Tensura Guild ‐ Task creation

Tensura Guild Commission Task JSON Authoring Wiki

This document explains how to add new Free Guild commission tasks for data pack authors, modpack authors, and mod maintainers. Guild commissions are data-driven, so most new tasks only require a task JSON file and matching localization entries. Java code changes are not required for ordinary task additions.

File Location

Guild commission JSON files are loaded from:

src/main/resources/data/tensura_guild/guild_tasks/<task_id>.json

Example:

src/main/resources/data/tensura_guild/guild_tasks/kill_5_slimes.json

This file becomes the task ID:

tensura_guild:kill_5_slimes

Data packs can also add tasks under their own namespace:

data/<your_namespace>/guild_tasks/<task_id>.json

The task ID becomes:

<your_namespace>:<task_id>

Use only lowercase letters, numbers, and underscores in file names. Example: collect_8_magic_ore_shards.json.

Minimal Structure

A task needs at least these fields:

{
  "title": "task.tensura_guild.collect_4_hipokute_flowers.title",
  "description": "task.tensura_guild.collect_4_hipokute_flowers.description",
  "rank": "F",
  "required_item": "tensura:hipokute_flower",
  "amount": 4,
  "reward_item": "tensura:bronze_coin",
  "reward_count": 6,
  "experience": 5
}

title and description are localization keys, not direct display text. Add matching entries to the language files, or the game will display the raw keys.

Language file locations:

src/main/resources/assets/tensura_guild/lang/zh_cn.json
src/main/resources/assets/tensura_guild/lang/en_us.json

Localization entry example:

{
  "task.tensura_guild.collect_4_hipokute_flowers.title": "Collect 4 Hipokute Flowers",
  "task.tensura_guild.collect_4_hipokute_flowers.description": "Hipokute flowers are important materials for recovery medicine and refinement recipes. Bring back 4 hipokute flowers."
}

Field Reference

Field	Type	Required	Default	Description
`title`	string	Yes	None	Localization key for the task title.
`description`	string	Yes	None	Localization key for the task description.
`rank`	string	No	`F`	Task rank. Valid values are `F`, `E`, `D`, `C`, `B`, `A`, and `S`. The value is normalized to uppercase.
`target`	resource ID	No	None	Target entity ID. If present, the task is a kill task.
`required_item`	resource ID	No	None	Required item ID. If present, the task is an item submission task.
`required_item_tag`	resource ID	No	None	Required item tag ID. Any inventory item matching the tag can be submitted.
`required_mod`	string	No	None	Required mod ID. If that mod is not loaded, the task is skipped.
`amount`	positive integer	Yes	None	Required kill count or item count. For multi-spawn target tasks, the actual required count is generated from `spawn_count` to `spawn_max_count`.
`reward_item`	resource ID	Yes	None	Reward item ID.
`reward_count`	positive integer	Yes	None	Reward item count.
`experience`	integer	No	`5`	Adventure experience awarded on completion. Negative values are clamped to `0`.
`party_only`	boolean	No	`false`	Whether the task must be accepted by a party. If `true`, the player must be in a party with at least 2 online members, and the party leader must accept the task.
`reward_per_member`	boolean	No	`false`	For party tasks, whether every participating member receives the full item reward. If `false`, the reward is split between online participants, and the remainder goes to the leader.
`experience_per_member`	boolean	No	`false`	For party tasks, whether every participating member receives the full adventure experience reward. If `false`, experience is split between online participants, and the remainder goes to the leader.
`structure_tag`	resource ID	No	None	Used by structure-area kill tasks. The kill must happen near a structure in this structure tag.
`structure_radius`	integer	No	`0`	Structure-area radius in blocks. Must be greater than `0` to work with `structure_tag`.
`time_limit_ticks`	non-negative integer	No	See below	Task time limit in ticks. `20 ticks = 1 second`. If a task should have a clear time limit, set this explicitly.
`spawn_target`	boolean	No	`false`	Whether accepting the task generates target coordinates and spawns the target entity when the player approaches the coordinates. Only works for kill tasks.
`spawn_radius`	integer	No	`0`	Maximum horizontal distance from the accepting player to the generated target coordinates. Must be greater than `0` for `spawn_target` to work.
`spawn_min_distance`	integer	No	`0`	Minimum horizontal distance from the accepting player to the generated target coordinates. Clamped to `0..spawn_radius`.
`spawn_trigger_distance`	integer	No	`0`	Distance from the target coordinates at which the target entity spawns. Must be greater than `0` for `spawn_target` to work.
`spawn_count`	integer	No	`1`	Minimum number of target entities spawned by a coordinate-based target task.
`spawn_max_count`	integer	No	`1`	Maximum number of target entities spawned by a coordinate-based target task. If lower than `spawn_count`, it is raised to `spawn_count`.
`spawn_biomes`	resource ID array	No	`[]`	Allowed biomes for the generated target coordinates. Empty means no biome restriction.
`refresh_chance`	decimal	No	`1.0`	Chance for the task to enter the board refresh candidate pool. Range: `0.0..1.0`. Manual command insertion ignores this value.

Task Types

1. Basic Kill Task

Use target to specify the entity ID. amount is the required kill count.

{
  "title": "task.tensura_guild.kill_5_slimes.title",
  "description": "task.tensura_guild.kill_5_slimes.description",
  "rank": "F",
  "target": "minecraft:slime",
  "amount": 5,
  "reward_item": "tensura:bronze_coin",
  "reward_count": 6,
  "experience": 5
}

Progress comes from player kill events. The player must actually kill the target entity for progress to increase.

2. Item Submission Task

Use required_item or required_item_tag. When the player submits the task, the system checks the player's inventory and consumes the required items.

{
  "title": "task.tensura_guild.collect_5_magic_ore_shards.title",
  "description": "task.tensura_guild.collect_5_magic_ore_shards.description",
  "rank": "F",
  "required_item": "tensura:magic_ore_shard",
  "amount": 5,
  "reward_item": "tensura:bronze_coin",
  "reward_count": 6,
  "experience": 5
}

Tasks named with craft_* are still item submission tasks. The system does not listen for crafting events. It only checks the player's inventory when the task is submitted.

3. Item Tag Submission Task

Use required_item_tag when multiple items should count as the same required material.

{
  "title": "task.tensura_guild.collect_64_oak_tool_racks.title",
  "description": "task.tensura_guild.collect_64_oak_tool_racks.description",
  "rank": "D",
  "required_item_tag": "tensura_guild:tool_rack",
  "amount": 64,
  "reward_item": "tensura:silver_coin",
  "reward_count": 10,
  "experience": 20
}

Matching tag file example:

src/main/resources/data/tensura_guild/tags/item/tool_rack.json

{
  "replace": false,
  "values": [
    "tensura:oak_tool_rack",
    "tensura:spruce_tool_rack"
  ]
}

Do not set both required_item and required_item_tag unless you intentionally want either the exact item or any item in the tag to count.

4. Structure-Area Kill Task

Use target, structure_tag, and structure_radius. The target entity must be killed near a structure in the specified structure tag.

{
  "title": "task.tensura_guild.party_clear_giant_ant_nest.title",
  "description": "task.tensura_guild.party_clear_giant_ant_nest.description",
  "rank": "E",
  "target": "tensura:giant_ant",
  "amount": 20,
  "reward_item": "tensura:silver_coin",
  "reward_count": 30,
  "experience": 25,
  "party_only": true,
  "experience_per_member": true,
  "structure_tag": "tensura_guild:giant_ant_nests",
  "structure_radius": 150
}

Structure tag file example:

src/main/resources/data/tensura_guild/tags/worldgen/structure/giant_ant_nests.json

{
  "values": [
    "tensura:nests/giant_ant"
  ]
}

structure_radius is measured in blocks. If the radius is too small, kills near the edge of the structure may not count. Use a radius that covers the structure size with some margin.

5. Coordinate-Based Target Spawn Kill Task

Use spawn_target:true. After accepting the task, the player receives target coordinates. When the player enters the spawn_trigger_distance range, the system looks for nearby ground and spawns the target entity.

Single target example:

{
  "title": "task.tensura_guild.kill_1_supermassive_slime.title",
  "description": "task.tensura_guild.kill_1_supermassive_slime.description",
  "rank": "D",
  "target": "tensura:supermassive_slime",
  "amount": 1,
  "reward_item": "tensura:gold_coin",
  "reward_count": 1,
  "experience": 40,
  "time_limit_ticks": 36000,
  "spawn_target": true,
  "spawn_radius": 3000,
  "spawn_min_distance": 1000,
  "spawn_trigger_distance": 100,
  "refresh_chance": 0.2,
  "reward_per_member": true,
  "experience_per_member": true
}

Group target example:

{
  "title": "task.tensura_guild.kill_unicorn_group_flower_forest_c.title",
  "description": "task.tensura_guild.kill_unicorn_group_flower_forest_c.description",
  "rank": "C",
  "target": "tensura:unicorn",
  "amount": 3,
  "reward_item": "tensura:gold_coin",
  "reward_count": 1,
  "experience": 25,
  "time_limit_ticks": 36000,
  "spawn_target": true,
  "spawn_radius": 3000,
  "spawn_min_distance": 0,
  "spawn_trigger_distance": 100,
  "spawn_count": 3,
  "spawn_max_count": 6,
  "spawn_biomes": [
    "minecraft:flower_forest"
  ],
  "refresh_chance": 0.85
}

For group spawn tasks, the actual required kill count is randomly generated when the task is accepted. The range is spawn_count..spawn_max_count. amount is still required in the JSON, but the generated count is used for the active task.

If spawn_biomes is not empty, the system tries to find an allowed biome within spawn_radius. If no suitable biome can be found near the player, the task will not be displayed or cannot be accepted.

Single target spawn tasks track a specific entity UUID. If the target is killed by an unauthorized player, the task group fails. Group target spawn tasks count kills near the target coordinates instead.

6. Party Task

Set party_only:true to force party acceptance.

{
  "title": "task.tensura_guild.kill_1_orc_disaster_party.title",
  "description": "task.tensura_guild.kill_1_orc_disaster_party.description",
  "rank": "B",
  "target": "tensura:orc_disaster",
  "amount": 1,
  "reward_item": "tensura:gold_coin",
  "reward_count": 2,
  "experience": 30,
  "party_only": true,
  "reward_per_member": true,
  "experience_per_member": true,
  "spawn_target": true,
  "spawn_radius": 3000,
  "spawn_min_distance": 500,
  "spawn_trigger_distance": 100,
  "spawn_biomes": [
    "minecraft:desert",
    "minecraft:badlands",
    "minecraft:eroded_badlands",
    "minecraft:wooded_badlands",
    "tensura:desert_of_death"
  ]
}

Notes:

party_only:true requires at least 2 online party members, and only the party leader can accept the task.
Even when party_only:false, a task accepted while the player is in a party is handled as a party task.
If reward_per_member:false, item rewards are split, and any remainder goes to the leader.
If experience_per_member:false, adventure experience is split, and any remainder goes to the leader.

Rank And Refreshing

rank decides which adventure rank can see the task. A player must reach the task's rank before the task can appear for them.

Rank order:

F -> E -> D -> C -> B -> A -> S

Current total adventure experience thresholds:

Rank	Required Total Adventure Experience
F	Starts at `0`
E	Starts at `101`
D	Starts at `301`
C	Starts at `501`
B	Starts at `701`
A	Starts at `1001`
S	Starts at `2001`

When the commission board refreshes, each rank pool selects a random number of tasks:

Rank	Tasks Per Refresh
F	`4..9`
E	`3..8`
D	`3..8`
C	`3..7`
B	`2..5`
A	`2..5`
S	`1..3`

refresh_chance controls whether a task enters the candidate pool:

{
  "refresh_chance": 0.35
}

Recommended values:

Normal task: omit the field, default is 1.0.
Rare task: 0.35 or lower.
Frequent variant: 0.85.
Test task: omit the field so it is easier to refresh.

Time Limits

time_limit_ticks uses ticks:

20 ticks = 1 second
1200 ticks = 1 minute
72000 ticks = 60 minutes
28800 ticks = 1 commission day
288000 ticks = 10 commission days

Example:

{
  "time_limit_ticks": 36000
}

Recommendations:

If the task should have a clear time limit, set time_limit_ticks.
Long crafting or submission tasks can use 288000.
Short tracking kill tasks can use 36000.
Avoid relying on defaults, especially for item submission tasks.

Optional Mod Tasks

If the task target comes from an optional mod, set required_mod:

{
  "title": "task.tensura_guild.craft_1_giant_spirit_pill_s.title",
  "description": "task.tensura_guild.craft_1_giant_spirit_pill_s.description",
  "rank": "S",
  "required_item": "mortal_cultivation:giant_spirit_pill",
  "required_mod": "mortal_cultivation",
  "amount": 1,
  "reward_item": "tensura:gold_coin",
  "reward_count": 15,
  "experience": 50,
  "time_limit_ticks": 288000
}

If mortal_cultivation is not loaded, this task is skipped during data loading. This prevents missing item or entity problems.

Common Templates

Collection Task Template

{
  "title": "task.tensura_guild.<task_id>.title",
  "description": "task.tensura_guild.<task_id>.description",
  "rank": "F",
  "required_item": "namespace:item_id",
  "amount": 1,
  "reward_item": "tensura:bronze_coin",
  "reward_count": 6,
  "experience": 5
}

Kill Task Template

{
  "title": "task.tensura_guild.<task_id>.title",
  "description": "task.tensura_guild.<task_id>.description",
  "rank": "F",
  "target": "namespace:entity_id",
  "amount": 1,
  "reward_item": "tensura:bronze_coin",
  "reward_count": 6,
  "experience": 5
}

Coordinate-Based Target Spawn Template

{
  "title": "task.tensura_guild.<task_id>.title",
  "description": "task.tensura_guild.<task_id>.description",
  "rank": "C",
  "target": "namespace:entity_id",
  "amount": 1,
  "reward_item": "tensura:gold_coin",
  "reward_count": 1,
  "experience": 25,
  "time_limit_ticks": 36000,
  "spawn_target": true,
  "spawn_radius": 3000,
  "spawn_min_distance": 500,
  "spawn_trigger_distance": 100,
  "spawn_biomes": [
    "minecraft:plains"
  ],
  "refresh_chance": 0.85
}

Party Boss Task Template

{
  "title": "task.tensura_guild.<task_id>.title",
  "description": "task.tensura_guild.<task_id>.description",
  "rank": "B",
  "target": "namespace:boss_entity",
  "amount": 1,
  "reward_item": "tensura:gold_coin",
  "reward_count": 2,
  "experience": 30,
  "party_only": true,
  "reward_per_member": true,
  "experience_per_member": true,
  "time_limit_ticks": 72000
}

Naming Guidelines

Keep the file name and localization key task ID consistent:

kill_5_slimes.json
task.tensura_guild.kill_5_slimes.title
task.tensura_guild.kill_5_slimes.description

Common prefixes:

kill_: kill task.
collect_: collection or item submission task.
craft_: crafted item submission task.
party_: forced party task.
find_: rare item search and submission task.

Task descriptions should state:

What the target is.
How many are required.
Whether the player must travel to target coordinates.
Whether a party is required.
Whether there is a time limit.
Whether the player must return to the guild to submit the task.

Testing Workflow

After adding or editing a task:

Confirm the JSON has no comments, trailing commas, or misspelled fields.
Confirm target, required_item, reward_item, and similar resource IDs exist.
Confirm title and description have entries in both zh_cn.json and en_us.json.
Run /reload in game to reload data.
Add the task to the task pool manually:

/tensuraguild task add tensura_guild:<task_id>

Or refresh the whole commission board:

/tensuraguild task refresh

If the task rank is too high, temporarily give yourself adventure experience:

/tensuraguild guild experience add @s 1000

Accept the task and verify the task paper, coordinates, progress, submission, rewards, and adventure experience.

If the task does not load, check the log for messages like:

Failed to parse guild task <id>: <error>

Common Mistakes

Missing amount, reward_item, or reward_count causes parsing failure.
Setting amount or reward_count to 0 is invalid or will be corrected. Do not use 0.
A wrong target entity ID means kills will not count, and coordinate-based spawn tasks may fail.
A wrong required_item ID means players can never submit the task.
A required_item_tag without a matching tag file means matching items cannot be submitted.
A structure_tag without a matching structure tag file makes structure-area kill tasks unable to count correctly.
spawn_target:true with spawn_radius or spawn_trigger_distance set to 0 will not work.
If spawn_biomes is too restrictive, the task may not appear or may not be accepted because no valid biome can be found nearby.
Missing localization entries will make the game show keys like task.tensura_guild.xxx.title.

Quick Checklist

Before submitting a new task, confirm:

The JSON file is under data/<namespace>/guild_tasks/.
The file name matches the <task_id> used by localization keys.
rank matches the intended difficulty.
The task uses one main logic type: target or required_item/required_item_tag.
Amount, reward, and experience match the rank.
Optional mod content uses required_mod.
Coordinate-based target spawn tasks include spawn_target, spawn_radius, and spawn_trigger_distance.
Party tasks have the intended party_only, reward_per_member, and experience_per_member values.
Both zh_cn.json and en_us.json have title and description entries.
After /reload, the task can be tested with /tensuraguild task add or /tensuraguild task refresh.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly