Titles

A title is an award a mercenary earns for something they did - a kill count, a place they visited, a stretch of service, a beating they survived.

Titles apply to all mercenaries, contracted or hostile. Bandits can be given titles outright through a bandit profile, and can also earn them through play like anyone else.

File location

data/magic_realms/mercenaries/titles/<id>.json

The file's path is the title's stable identifier (e.g. data/magic_realms/mercenaries/titles/dragonslayer.json becomes magic_realms:dragonslayer).

Schema

Requirement types

Each entry in requirements is { "type": …, "target": …, "amount": … }. target and amount are optional and mean different things per type.

A leading # on a tag id is accepted and ignored, so "minecraft:undead" and "#minecraft:undead" both work.

Structure visits count the entry, not the time spent - standing in a fortress doesn't inflate the counter, but leaving and returning does.

Reward types

Everything in rewards is optional. A purely cosmetic title just leaves it out.

For weapon_bonus, set item, item_tag, or both - matching either is enough. Keep them in one entry rather than two, or a weapon matching both gets the multiplier applied twice.

How rewards stack

A mercenary holding several titles gets all of their rewards at once, and multipliers multiply:

• incoming_damage_multiplier compounds downward, so five titles at 0.9 give 0.59 (41% reduction), not 50%. This is self-limiting - each title takes a share of what's left - so stacking approaches immunity without reaching it.
• damage_bonus_vs and weapon_bonus multipliers compound upward, and this is where over-tuning bites. A title at 1.5× against undead, plus another at 3×, plus a 1.3× axe bonus, is 5.85× against a zombie holding an axe.

Flat values (bonus_damage, add_value attribute modifiers) simply sum. As a rule of thumb, keep early titles flat and save multiplicative rewards for capstones.

Example: a kill milestone

The simplest useful shape - one requirement, one flat reward.

{
  "display_key": "title.magic_realms.veteran",
  "description_key": "title.magic_realms.veteran.desc",
  "color": "gold",
  "priority": 40,
  "requirements": [
    { "type": "total_kills", "amount": 1000 }
  ],
  "rewards": {
    "attribute_modifiers": [
      {
        "attribute": "minecraft:generic.armor",
        "id": "magic_realms:veteran_armor",
        "amount": 3.0,
        "operation": "add_value"
      }
    ],
    "incoming_damage_multiplier": 0.95
  }
}

Example: a class-locked weapon specialist

Two requirements in "all" mode, rewarding a fighting style rather than raw stats.

{
  "display_key": "title.magic_realms.axemaster",
  "description_key": "title.magic_realms.axemaster.desc",
  "color": "#C97B4A",
  "priority": 65,
  "requirement_mode": "all",
  "requirements": [
    { "type": "entity_class", "target": "warrior" },
    { "type": "total_kills", "amount": 400 }
  ],
  "rewards": {
    "weapon_bonus": [
      { "item_tag": "c:tools/axe", "multiplier": 1.3, "bonus": 1.0 },
      { "item": "minecraft:netherite_axe", "bonus": 2.0 }
    ]
  }
}

The netherite axe matches both entries, so it picks up the tag bonus and its own - that's the intended way to give one item extra weight on top of a family.

Example: exploration, with two routes to the same reward

"any" mode, plus a status immunity and a passive effect.

{
  "display_key": "title.magic_realms.unclouded",
  "description_key": "title.magic_realms.unclouded.desc",
  "color": "#A8D8E8",
  "priority": 60,
  "requirement_mode": "any",
  "requirements": [
    { "type": "visit_structure", "target": "minecraft:ancient_city" },
    { "type": "damage_taken", "amount": 4000 }
  ],
  "rewards": {
    "immune_effects": [
      "minecraft:blindness",
      "minecraft:darkness",
      "minecraft:nausea"
    ],
    "passive_effects": [
      { "effect": "minecraft:night_vision", "show_particles": false }
    ]
  }
}

Example: a title chain

has_title lets a capstone require others first. Because evaluation cascades within a single pass, a chain resolves the moment its last prerequisite is met.

{
  "display_key": "title.magic_realms.living_legend",
  "description_key": "title.magic_realms.living_legend.desc",
  "color": "#FFE066",
  "priority": 200,
  "requirement_mode": "all",
  "requirements": [
    { "type": "has_title", "target": "magic_realms:veteran" },
    { "type": "has_title", "target": "magic_realms:sworn_sword" },
    { "type": "boss_kills", "amount": 10 }
  ],
  "rewards": {
    "attribute_modifiers": [
      {
        "attribute": "minecraft:generic.attack_damage",
        "id": "magic_realms:legend_damage",
        "amount": 0.15,
        "operation": "add_multiplied_total"
      }
    ],
    "natural_regen": true
  }
}

Unobtainable titles

A title with no requirements is never earned naturally. It can only be granted deliberately - by command, by a bandit profile, or by code. This is the shape to use for story rewards, signature titles belonging to a named character, or anything you want to hand out on your own terms.

{
  "display_key": "title.magic_realms.mace_lord",
  "description_key": "title.magic_realms.mace_lord.desc",
  "color": "#B08D57",
  "priority": 150,
  "announce": false,
  "requirements": [],
  "rewards": {
    "weapon_bonus": [
      { "item": "minecraft:mace", "item_tag": "c:tools/mace", "multiplier": 1.5 }
    ]
  }
}

Set "hidden": true as well if the title should apply its rewards without ever appearing on the nameplate or in the selector.

Managing titles in game

/human title list     <target>
/human title progress <target>
/human title grant    <target> <title>
/human title revoke   <target> <title>
/human title display  <target> <title>
/human title clear    <target>

progress is the useful one while authoring: it lists every unearned title with a completion percentage and a per-requirement breakdown, so you can see exactly how far off a mercenary is. grant bypasses requirements entirely, which is how you test a title without grinding for it.