Use this template for a quest that spawns a named threat, lets the player talk to it, then branches on attack or spare.

First Quest

{
  "title": "QUEST TITLE",
  "summary": "Villager-facing summary shown before acceptance.",

  "flow": {
    "on_kill": "modid:kill_branch_2",
    "on_spare": "modid:spare_branch_2"
  },

  "goals": [
    {
      "id": "talk_to_threat",
      "talk": "minecraft:zombie",
      "amount": 1,
      "name": "NAMED THREAT"
    },
    {
      "id": "kill_threat",
      "kill": "minecraft:zombie",
      "amount": 1,
      "attack_only": true,
      "from_threats": true
    }
  ],

  "threat": {
    "entity": "minecraft:zombie",
    "name": "NAMED THREAT",
    "structure": "minecraft:ruined_portal",
    "search_radius": 4000,
    "spawn_on_accept": true,
    "spawn_min_radius": 3,
    "spawn_max_radius": 6,
    "spare": true,
    "glow": false,
    "max_health": 150,
    "equipment": {
      "mainhand": "minecraft:diamond_sword",
      "helmet": {
        "item": "minecraft:iron_helmet",
        "enchants": {
          "minecraft:unbreaking": 3
        }
      }
    },
    "line": "Quest giver line that describes the threat.",
    "target": "Initial line spoken by the threat.",
    "talk": [
      ["Player question one?", "Threat answer one."],
      ["Player question two?", "Threat answer two."]
    ]
  },

  "choice": {
    "attack": {
      "label": "Attack choice label.",
      "traits": ["trait_from_attack"],
      "return": "Quest giver line after the target is killed."
    },
    "spare": {
      "label": "Spare choice label.",
      "line": "Immediate line after sparing the target.",
      "post": "Follow-up line shown after the spare.",
      "villager": "Quest giver line after spare.",
      "traits": ["trait_from_spare"],
      "rewards_from_giver": true,
      "rewards": {
        "xp": 160,
        "items": {
          "minecraft:iron_ingot": 4
        }
      },
      "after": {
        "offer_chance": 70,
        "ambush_chance": 30,
        "nothing_chance": 0,
        "ambush": "minecraft:zombie",
        "ambush_name": "Fallback Ambush Name",
        "count": 5,
        "ambush_max_health": 50,
        "ambush_equipment": {
          "helmet": "minecraft:leather_helmet"
        },
        "line": "Line used when the spared target offers the next quest.",
        "ambush_line": "Line used if mercy triggers an ambush.",
        "nothing": "Line used if no follow-up happens."
      }
    }
  },

  "dialogue": {
    "return": "Quest giver line after kill.",
    "reward": "Quest giver reward line.",
    "done": "Quest giver already-completed line."
  },

  "rewards": {
    "xp": 260,
    "items": {
      "minecraft:emerald": 10
    }
  }
}

For spare-enabled threat confrontations, prefer the talk plus attack_only kill pattern shown above. The first interaction opens dialogue without completing the stage; the stage completes only after the player explicitly chooses attack or spare.

Kill Branch

{
  "title": "KILL BRANCH TITLE",
  "summary": "Follow-up summary after the player chose attack.",

  "dialogue": {
    "intro": "Intro line.",
    "offer": [
      ["Player question?", "Quest giver answer."]
    ],
    "return": "Return line.",
    "reward": "Reward line.",
    "done": "Already completed line."
  },

  "goals": ["kill 3 minecraft:zombified_piglin"],

  "threats": [
    {
      "entity": "minecraft:zombified_piglin",
      "name": "Branch Threat",
      "structure": "minecraft:ruined_portal",
      "search_radius": 4000,
      "spawn_on_accept": true,
      "spare": false,
      "max_health": 70,
      "equipment": {
        "mainhand": "minecraft:golden_sword"
      }
    }
  ],

  "rewards": {
    "xp": 360,
    "items": {
      "minecraft:emerald": 14
    }
  }
}

Spare Branch

{
  "title": "SPARE BRANCH TITLE",
  "summary": "Follow-up summary after the player chose spare.",

  "flow": {
    "next": "modid:spare_branch_3"
  },

  "dialogue": {
    "intro": "Intro line from the spared target or quest giver.",
    "offer": [
      ["Player question?", "Answer."]
    ],
    "return": "Return line.",
    "reward": "Reward line.",
    "done": "Already completed line."
  },

  "goals": [
    {
      "collect": "minecraft:iron_ingot",
      "amount": 4
    }
  ],

  "rewards": {
    "xp": 240,
    "items": {
      "minecraft:emerald": 6
    }
  }
}

Use this when the player must build or gather something first, then a new wave of threats appears in a later stage.

Based on questlines/village_build/village_pig_enclosure.json.

Key points:

• sequential_objectives: true makes stage 0 finish before stage 1 starts.
• Build objectives use place, bring, collect, or other normal objective shortcuts.
• Threats can be assigned to stage: 1 and spawned around the quest giver with spawn_origin: "quest_giver".
• Use from_threats: true on kill goals when the spawned named/custom threats should count.
• Add one threats entry per mob to spawn. amount is not read on threat entries.

{
  "title": {
    "translate": "quest.example.first_pen_defense.title",
    "fallback": "A Pen Worth Defending"
  },
  "summary": {
    "translate": "quest.example.first_pen_defense.summary",
    "fallback": "Build a small animal pen, bring livestock inside, then defend it from raiders."
  },
  "sequential_objectives": true,
  "dialogue": {
    "intro": {
      "translate": "quest.example.first_pen_defense.dialogue.intro",
      "fallback": "The villager points to a bare patch of grass near the farm."
    },
    "offer": [
      [
        {
          "translate": "quest.example.first_pen_defense.dialogue.offer.0.0",
          "fallback": "What do you need built?"
        },
        {
          "translate": "quest.example.first_pen_defense.dialogue.offer.0.1",
          "fallback": "A fence, a gate, two torches, and enough room for the first herd."
        }
      ]
    ],
    "return": {
      "translate": "quest.example.first_pen_defense.dialogue.return",
      "fallback": "The pen held. So did you."
    },
    "reward": {
      "translate": "quest.example.first_pen_defense.dialogue.reward",
      "fallback": "Take this. A defended farm feeds more than one house."
    },
    "done": {
      "translate": "quest.example.first_pen_defense.dialogue.done",
      "fallback": "The animals are still inside, and the raiders are gone."
    }
  },
  "goals": [
    {
      "id": "place_fences",
      "place": "minecraft:oak_fence",
      "amount": 12,
      "stage": 0,
      "range": 60
    },
    {
      "id": "place_gate",
      "place": "minecraft:oak_fence_gate",
      "amount": 1,
      "stage": 0,
      "range": 60
    },
    {
      "id": "place_torches",
      "place": "minecraft:torch",
      "amount": 2,
      "stage": 0,
      "range": 60,
      "say": {
        "translate": "quest.example.first_pen_defense.goals.place_torches.say",
        "fallback": "The pen is lit. Stay close."
      }
    },
    {
      "id": "bring_animals",
      "bring": "minecraft:pig",
      "amount": 2,
      "stage": 0,
      "range": 60
    },
    {
      "id": "kill_raiders",
      "kill": "minecraft:pillager",
      "amount": 3,
      "stage": 1,
      "from_threats": true
    },
    {
      "id": "kill_raider_captain",
      "kill": "minecraft:vindicator",
      "amount": 1,
      "stage": 1,
      "from_threats": true
    }
  ],
  "threats": [
    {
      "entity": "minecraft:pillager",
      "name": {
        "translate": "quest.example.first_pen_defense.threats.0.name",
        "fallback": "Hungry Raider"
      },
      "stage": 1,
      "spawn_origin": "quest_giver",
      "spawn_min_radius": 18,
      "spawn_max_radius": 30,
      "spawn_on_accept": true,
      "spare_enabled": false,
      "glow": true
    },
    {
      "entity": "minecraft:pillager",
      "name": {
        "translate": "quest.example.first_pen_defense.threats.1.name",
        "fallback": "Fence-Cutting Raider"
      },
      "stage": 1,
      "spawn_origin": "quest_giver",
      "spawn_min_radius": 18,
      "spawn_max_radius": 30,
      "spawn_on_accept": true,
      "spare_enabled": false,
      "glow": true
    },
    {
      "entity": "minecraft:pillager",
      "name": {
        "translate": "quest.example.first_pen_defense.threats.2.name",
        "fallback": "Torch-Kicking Raider"
      },
      "stage": 1,
      "spawn_origin": "quest_giver",
      "spawn_min_radius": 18,
      "spawn_max_radius": 30,
      "spawn_on_accept": true,
      "spare_enabled": false,
      "glow": true
    },
    {
      "entity": "minecraft:vindicator",
      "name": {
        "translate": "quest.example.first_pen_defense.threats.3.name",
        "fallback": "Fence Breaker"
      },
      "stage": 1,
      "spawn_origin": "quest_giver",
      "spawn_min_radius": 22,
      "spawn_max_radius": 34,
      "spawn_on_accept": true,
      "spare_enabled": false,
      "glow": true,
      "max_health": 40.0
    }
  ],
  "rewards": {
    "xp": 180,
    "items": {
      "minecraft:emerald": 6,
      "minecraft:wheat": 12
    }
  },
  "traits": {
    "complete": [
      "farm_defender"
    ]
  }
}

Use this when a structure should contain generated quest items, a written-book clue, and a demolition step near a target block.

Based on questlines/sculk/sculk_mineshaft_investigation.json.

Key points:

• read_book objectives must include item: "minecraft:written_book".
• quest_book.title, quest_book.author, and quest_book.pages can be translation objects.
• Use in_chest: true with container to spawn the objective item inside a generated container.
• Generated chest/container items are placed into random empty slots by the quest item spawner.
• detonate_tnt should use block for the target block near the explosion, not the TNT block itself.
• force_place_block: true can prepare the target block when the structure does not reliably contain one.

{
  "title": {
    "translate": "quest.example.mine_demolition.title",
    "fallback": "Notes Under the Mine"
  },
  "summary": {
    "translate": "quest.example.mine_demolition.summary",
    "fallback": "Find a sealed mineshaft, recover the foreman's notes, and destroy the marked spawner."
  },
  "sequential_objectives": true,
  "goals": [
    {
      "id": "reach_old_mine",
      "reach": "minecraft:mineshaft",
      "structure": "minecraft:mineshaft",
      "radius": 3200,
      "range": 80,
      "stage": 0,
      "auto_advance": true
    },
    {
      "id": "read_foreman_notes",
      "type": "read_book",
      "item": "minecraft:written_book",
      "amount": 1,
      "structure": "minecraft:mineshaft",
      "container": "minecraft:barrel",
      "stage": 1,
      "radius": 3200,
      "in_chest": true,
      "auto_advance": true,
      "tag": "example_foreman_notes",
      "quest_book": {
        "title": {
          "translate": "quest.example.mine_demolition.book.title",
          "fallback": "Foreman's Notes"
        },
        "author": {
          "translate": "quest.example.mine_demolition.book.author",
          "fallback": "Mine Foreman"
        },
        "pages": [
          {
            "translate": "quest.example.mine_demolition.book.page.0",
            "fallback": "We sealed the lower drift after the spawner woke again. If anyone returns, place charges near the cage, not in the tunnel mouth."
          }
        ]
      },
      "block_patch": {
        "radius": 4,
        "palette": [
          "minecraft:sculk",
          "minecraft:deepslate"
        ]
      }
    },
    {
      "id": "take_tnt_from_barrel",
      "collect": "minecraft:tnt",
      "amount": 3,
      "mandatory": false,
      "sequential": true,
      "stage": 1,
      "in_chest": true,
      "structure": "minecraft:mineshaft",
      "container": "minecraft:barrel"
    },
    {
      "id": "place_demolition_charges",
      "place": "minecraft:tnt",
      "amount": 3,
      "structure": "minecraft:mineshaft",
      "stage": 2,
      "range": 12
    },
    {
      "id": "detonate_spawner",
      "type": "detonate_tnt",
      "block": "minecraft:spawner",
      "required_mob": "minecraft:skeleton",
      "structure": "minecraft:mineshaft",
      "force_place_block": true,
      "amount": 3,
      "stage": 2,
      "radius": 3200,
      "range": 14,
      "auto_advance": true,
      "block_patch": {
        "radius": 3,
        "palette": [
          "minecraft:sculk",
          "minecraft:deepslate"
        ]
      }
    },
    {
      "id": "kill_what_crawls_out",
      "kill": "minecraft:zombie",
      "amount": 4,
      "stage": 3,
      "from_threats": true
    }
  ],
  "threats": [
    {
      "entity": "minecraft:zombie",
      "name": {
        "translate": "quest.example.mine_demolition.threats.0.name",
        "fallback": "Sculk-Crowned Dead"
      },
      "stage": 3,
      "spawn_origin": "player",
      "spawn_min_radius": 8,
      "spawn_max_radius": 16,
      "spawn_on_accept": true,
      "spare_enabled": false,
      "glow": true,
      "equipment": {
        "head": "minecraft:sculk"
      }
    },
    {
      "entity": "minecraft:zombie",
      "name": {
        "translate": "quest.example.mine_demolition.threats.1.name",
        "fallback": "Sculk-Marked Dead"
      },
      "stage": 3,
      "spawn_origin": "player",
      "spawn_min_radius": 8,
      "spawn_max_radius": 16,
      "spawn_on_accept": true,
      "spare_enabled": false,
      "glow": true,
      "equipment": {
        "head": "minecraft:sculk"
      }
    },
    {
      "entity": "minecraft:zombie",
      "name": {
        "translate": "quest.example.mine_demolition.threats.2.name",
        "fallback": "Sculk-Marked Dead"
      },
      "stage": 3,
      "spawn_origin": "player",
      "spawn_min_radius": 8,
      "spawn_max_radius": 16,
      "spawn_on_accept": true,
      "spare_enabled": false,
      "glow": true,
      "equipment": {
        "head": "minecraft:sculk"
      }
    },
    {
      "entity": "minecraft:zombie",
      "name": {
        "translate": "quest.example.mine_demolition.threats.3.name",
        "fallback": "Sculk-Marked Dead"
      },
      "stage": 3,
      "spawn_origin": "player",
      "spawn_min_radius": 8,
      "spawn_max_radius": 16,
      "spawn_on_accept": true,
      "spare_enabled": false,
      "glow": true,
      "equipment": {
        "head": "minecraft:sculk"
      }
    }
  ],
  "rewards": {
    "xp": 320,
    "items": {
      "minecraft:emerald": 10,
      "minecraft:echo_shard": 1
    }
  }
}

Use this when the player gathers items, travels to another structure, gives the items to a spawned target, then returns to the original quest giver.

Based on delivery_cobblestone_oak_log_other_village.json.

Key points:

• The delivery target is configured in threat.
• delivery_objectives must list the objective ids that should be handed over.
• The target talk objective should usually use auto_advance: true.
• Add a final return: true objective in the next stage if the player must report back.
• min_structure_distance is useful when the target should not spawn in the same village.

{
  "title": {
    "translate": "quest.example.remote_delivery.title",
    "fallback": "Stone for the Next Village"
  },
  "summary": {
    "translate": "quest.example.remote_delivery.summary",
    "fallback": "Carry supplies to a messenger waiting in another village."
  },
  "sequential_objectives": true,
  "goals": [
    {
      "id": "delivery_cobblestone",
      "collect": "minecraft:cobblestone",
      "amount": 32,
      "mandatory": true,
      "stage": 0
    },
    {
      "id": "delivery_oak_logs",
      "collect": "minecraft:oak_log",
      "amount": 16,
      "mandatory": true,
      "stage": 0
    },
    {
      "id": "deliver_to_messenger",
      "talk": "minecraft:villager",
      "amount": 1,
      "mandatory": true,
      "stage": 0,
      "auto_advance": true,
      "name": {
        "translate": "quest.example.remote_delivery.goals.deliver_to_messenger.name",
        "fallback": "Village Messenger"
      },
      "say": {
        "translate": "quest.example.remote_delivery.goals.deliver_to_messenger.say",
        "fallback": "The messenger takes the supplies. Return to the villager who sent you."
      }
    },
    {
      "id": "return_to_sender",
      "return": true,
      "amount": 1,
      "mandatory": true,
      "stage": 1
    }
  ],
  "threat": {
    "entity": "minecraft:villager",
    "name": {
      "translate": "quest.example.remote_delivery.threat.name",
      "fallback": "Village Messenger"
    },
    "structure": "minecraft:villages",
    "search_radius": 4200,
    "spawn_radius": 10,
    "spawn_on_accept": true,
    "spare_enabled": false,
    "glow": false,
    "target_line": {
      "translate": "quest.example.remote_delivery.threat.target_line",
      "fallback": "If you have the stone and oak, hand them over before the wall gives way."
    },
    "delivery_objectives": [
      "delivery_cobblestone",
      "delivery_oak_logs"
    ],
    "delivery_choice_label": {
      "translate": "quest.example.remote_delivery.threat.delivery_choice_label",
      "fallback": "Hand over supplies"
    },
    "delivered_line": {
      "translate": "quest.example.remote_delivery.threat.delivered_line",
      "fallback": "That will hold. Tell them the road between our villages is still worth keeping open."
    },
    "depart_after_delivery": false,
    "min_structure_distance": 700
  },
  "rewards": {
    "xp": 180,
    "items": {
      "minecraft:emerald": 7,
      "minecraft:bread": 6
    }
  }
}

Use this when accepting the quest should start a village raid and completing the raid should complete the objective.

Based on questlines/village_defense/village_defense_chain_3_the_bell_and_the_raid.json.

Key points:

• Use type: "defend_raid".
• amount: 1 is the normal value for a single raid defense objective.
• This objective depends on the normal Minecraft raid flow, so it should be offered from a villager in or near the village being defended.
• Use rewards with enchanted items when the raid reward should feel unique.

{
  "title": {
    "translate": "quest.example.bell_raid.title",
    "fallback": "The Bell and the Raid"
  },
  "summary": {
    "translate": "quest.example.bell_raid.summary",
    "fallback": "Stand with the village and survive the raid."
  },
  "dialogue": {
    "intro": {
      "translate": "quest.example.bell_raid.dialogue.intro",
      "fallback": "The villager stands beside the bell, one hand on the rope."
    },
    "offer": [
      [
        {
          "translate": "quest.example.bell_raid.dialogue.offer.0.0",
          "fallback": "You think they are coming now?"
        },
        {
          "translate": "quest.example.bell_raid.dialogue.offer.0.1",
          "fallback": "If we ring the bell, they will know we are ready to fight."
        }
      ]
    ],
    "return": {
      "translate": "quest.example.bell_raid.dialogue.return",
      "fallback": "The horn is silent. The village still stands."
    },
    "reward": {
      "translate": "quest.example.bell_raid.dialogue.reward",
      "fallback": "This was taken from the raid leader. By right of battle, it is yours."
    },
    "done": {
      "translate": "quest.example.bell_raid.dialogue.done",
      "fallback": "The bell rings for warning again, not fear."
    }
  },
  "goals": [
    {
      "id": "defend_the_village",
      "type": "defend_raid",
      "amount": 1
    }
  ],
  "rewards": {
    "xp": 650,
    "items": {
      "minecraft:emerald": 20,
      "minecraft:crossbow": {
        "count": 1,
        "enchantments": [
          {
            "id": "minecraft:power",
            "level": 3
          },
          {
            "id": "minecraft:unbreaking",
            "level": 2
          },
          {
            "id": "minecraft:piercing",
            "level": 1
          }
        ]
      }
    }
  },
  "traits": {
    "complete": [
      "village_defender"
    ]
  }
}

Use this when a quest should not appear until a villager rumor unlocks it.

Based on rumors/mine_smoke_below.json and blaze_mineshaft_threat.json.

Key points:

• The rumor file lives under data/<namespace>/rumors/<rumor_id>.json.
• unlock_quest should be the full quest id.
• When the rumor is discovered, the player receives the trait quest_discovered:<full quest id>.
• The hidden quest should require that trait.
• Use conditions.not_completed_quests so the rumor stops being useful after the quest is complete.
• Rumor line and discovered_line are currently plain strings.

Rumor file:

{
  "id": "example_smoke_below",
  "weight": 15,
  "line": "Miners swear smoke is rising from shafts sealed for years.",
  "unlock_quest": "example:hidden_mineshaft_fire",
  "conditions": {
    "not_completed_quests": [
      "example:hidden_mineshaft_fire"
    ]
  },
  "discovered_line": "Rumor discovered: something hot and hostile is moving in an old mineshaft."
}

Hidden quest file:

{
  "title": {
    "translate": "quest.example.hidden_mineshaft_fire.title",
    "fallback": "Flame in the Mineshaft"
  },
  "summary": {
    "translate": "quest.example.hidden_mineshaft_fire.summary",
    "fallback": "A villager reports a blaze burning through an abandoned mineshaft."
  },
  "requires": {
    "traits": [
      "quest_discovered:example:hidden_mineshaft_fire"
    ]
  },
  "goals": [
    {
      "id": "kill_mine_blaze",
      "kill": "minecraft:blaze",
      "amount": 1
    }
  ],
  "threat": {
    "entity": "minecraft:blaze",
    "name": {
      "translate": "quest.example.hidden_mineshaft_fire.threat.name",
      "fallback": "Ignivar the Mineflame"
    },
    "structure": "minecraft:mineshaft",
    "search_radius": 4000,
    "spawn_on_accept": true,
    "spare_enabled": false,
    "max_health": 150.0,
    "offer_line": {
      "translate": "quest.example.hidden_mineshaft_fire.threat.offer_line",
      "fallback": "Something from the Nether is burning through an old mineshaft."
    },
    "target_line": {
      "translate": "quest.example.hidden_mineshaft_fire.threat.target_line",
      "fallback": "The blaze crackles with hostile heat. There is no sign it understands mercy."
    }
  },
  "rewards": {
    "xp": 260,
    "items": {
      "minecraft:emerald": 12,
      "minecraft:blaze_rod": 2
    }
  }
}

Use this when the quest giver or quest entity must be escorted to a target structure.

Based on questlines/armed_zombie/armed_zombie_chain_spare_2_forgotten_road.json.

Key points:

• Use the escort shortcut with a structure id. The parser converts it to escort_entity.
• radius controls how far the structure search can go.
• range controls how close the escorted entity must be to the target structure.
• This works well as a follow-up after a spare/recruit branch.

{
  "title": {
    "translate": "quest.example.forgotten_road.title",
    "fallback": "The Forgotten Road"
  },
  "summary": {
    "translate": "quest.example.forgotten_road.summary",
    "fallback": "Escort a spared enemy toward the village road it remembers."
  },
  "flow": {
    "next": "example:remembered_name"
  },
  "dialogue": {
    "intro": {
      "translate": "quest.example.forgotten_road.dialogue.intro",
      "fallback": "The spared creature keeps its weapon low and looks toward the road."
    },
    "offer": [
      [
        {
          "translate": "quest.example.forgotten_road.dialogue.offer.0.0",
          "fallback": "You remember a village?"
        },
        {
          "translate": "quest.example.forgotten_road.dialogue.offer.0.1",
          "fallback": "A bell. Smoke. A well with cracked stone. Take me there."
        }
      ]
    ],
    "return": {
      "translate": "quest.example.forgotten_road.dialogue.return",
      "fallback": "The bell. I know that sound."
    },
    "reward": {
      "translate": "quest.example.forgotten_road.dialogue.reward",
      "fallback": "I found this under the well stones. It was mine once."
    },
    "done": {
      "translate": "quest.example.forgotten_road.dialogue.done",
      "fallback": "The village road remembers me."
    }
  },
  "goals": [
    {
      "id": "escort_to_village",
      "escort": "minecraft:village_plains",
      "radius": 3500,
      "range": 40
    }
  ],
  "rewards": {
    "xp": 220,
    "items": {
      "minecraft:iron_ingot": 6,
      "minecraft:emerald": 4
    }
  },
  "traits": {
    "complete": [
      "escort_memory"
    ]
  }
}