Datapacks¶

MineDnD items, recipes, enchantments, requirement rules, achievements, titles, translations and world settings live in a normal Minecraft datapack inside the world. MineDnD Studio edits all of it with forms; this page is the file format.

<world>/datapacks/<your_pack>/
├── pack.mcmeta
└── data/<namespace>/
    ├── items/             ← MineDnD items (any subfolders)
    │   └── weapons/flame_sword.json
    ├── recipe/            ← how players make them: crafting table or brewing stand
    │   └── weapons/flame_sword.json
    ├── enchantment/       ← custom enchantments (vanilla format)
    │   └── holy_strike.json
    ├── crafting_requirements/  ← ability scores needed to craft, brew, place or use things
    │   └── redstone_torch.json
    ├── tags/potion/       ← potion tags, for rules about groups of potions (optional)
    ├── advancement/       ← achievements, and the advancements that unlock recipes
    ├── title/             ← titles, unlocked by achievements
    └── lang/              ← translations, one file per language
        ├── en_us.json
        └── it_it.json

World settings go in data/minednd/settings.json (see World settings).

The mod's built-in datapack is a complete working example: src/main/resources/resourcepacks/default_content (namespace minednd; everything in it is listed in Default content). Copy any file into your own pack as a starting point.

In the default content	Shows
Flame Sword, Dagger of Venom, Ranger's Bow, Wizard's Staff	Requirements on weapons; custom and vanilla enchantments; unbreakable
Ring of Strength, Amulet of Health, Tome of Clear Thought	Off-hand stat bonuses; the tome (+2 INT) unlocks the staff (INT 13)
Boots of Elvenkind, Belt of Giant Strength, Shield of Faith, Cloak of Protection	Bonuses by armor slot; dyed leather; vanilla `attribute_modifiers`
Holy Strike, Venom Strike, Fleetfoot	Enchantments: damage, on-hit effect with a STR/DEX condition, attribute while worn
Sneak Attack, Stoneskin, Hellish Rebuke, Darkvision, Stormcaller	Entity flags, protection, reacting when hit, effects every tick, weather conditions
Potions (Hill Giant Strength, Heroism, …)	`minecraft:potion_contents` with custom effects, brewed in the brewing stand (`minednd:brewing`)
`data/minecraft/tags/enchantment/`	Making custom enchantments appear in enchanting tables, loot and trades
`crafting_requirements/`	Recipe id, item, item list and item tag targets; same scores for several actions; different scores per action; use-only (ender pearl); potions by tier (`brewing/`, with the potion tags in `tags/potion/`)

pack.mcmeta for Minecraft 26.3:

{ "pack": { "description": "My campaign", "min_format": 121, "max_format": 121 } }

Items¶

Files: data/<namespace>/items/**/*.json. Before 0.3.0 this folder was called gm_items: the mod still reads it (with a warning in the log), and MineDnD Studio moves it for you.

The item id is the file path: data/my_campaign/items/weapons/flame_sword.json → my_campaign:weapons/flame_sword (used by /dnd give).

{
  "category": "weapons",
  "stack": {
    "id": "minecraft:iron_sword",
    "count": 1,
    "components": {
      "minecraft:item_name": { "translate": "item.my_campaign.flame_sword", "fallback": "Flame Sword" },
      "minecraft:lore": [
        { "translate": "item.my_campaign.flame_sword.lore", "fallback": "Forged in the Plane of Fire", "italic": true, "color": "gray" }
      ],
      "minecraft:rarity": "rare",
      "minecraft:enchantments": { "minecraft:fire_aspect": 2, "my_campaign:holy_strike": 1 }
    }
  }
}

category (optional, default misc): groups items in the creative tab and in /dnd catalog list.
Names and lore: use { "translate": "<key>", "fallback": "<English text>" } so they appear in each player's language (see Translations). Plain text like "Flame Sword" also works, but is the same for everyone.
Prefer minecraft:item_name over minecraft:custom_name: it shows in the rarity color and isn't italic (custom_name looks like an anvil rename).
stack: a vanilla item stack, exactly like in /give or loot tables. Any vanilla component works: names, lore, enchantments, attribute_modifiers, unbreakable, dyed_color, item_model, ...
Every catalog item automatically gets minecraft:custom_data → minednd_catalog_id, so the mod can recognise it later.
A broken file is skipped and logged (Skipping item ... in the server log); the rest still loads.

Stat bonuses¶

The item component minednd:stat_bonus:

"minednd:stat_bonus": {
  "bonuses": { "str": 2, "con": 1 },
  "slot": "offhand"
}

bonuses: any of str, dex, con, int, wis, cha, each between -10 and +10.
slot (optional, default any): where the item must be for the bonus to apply: any, hand, mainhand, offhand, armor, head, chest, legs, feet.
Bonuses show in the item tooltip, and in the character sheet as [+2] next to the score.
The component also works outside the catalog, e.g. /give @s minecraft:stick[minednd:stat_bonus={bonuses:{str:2}}].

Item requirements¶

The item component minednd:requirements:

"minednd:requirements": { "str": 12 }

Minimum ability scores to use the item's powers. Any of str, dex, con, int, wis, cha.
When the holder doesn't meet them, the item works as its plain base item: its minednd:stat_bonus, its minednd:active_ability, all its enchantments (Infinity, Unbreaking, Mending, Efficiency, protection, …) and minecraft:unbreakable are inactive (a Flame Sword is just an iron sword; a Ranger's Bow uses arrows and wears out). The base item's own stats (attack damage, armor) and any minecraft:attribute_modifiers stay. Nothing else is blocked. Items nobody carries (in a chest, an anvil) keep their enchantments, so anvils and grindstones work as usual.
Potions (potion, splash and lingering bottles) have nothing plain to fall back to: below their requirements they can't be drunk or thrown, and "To use this you need: …" appears above the hotbar.
The tooltip shows "Requires:" with each score green (met) or red (not met), plus a warning line when inactive.
Requirements count bonuses from other equipped items (e.g. a Ring of Strength helps reach STR 12), also from items that have requirements themselves once theirs are met (an Elven Chain Shirt, DEX 13, +1 DEX, helps reach a Ranger's Bow's DEX 14). An item's own bonus never counts for itself, and items can't unlock each other in a loop: each needs to be met without the other.

Item abilities¶

The item component minednd:active_ability. Left click is always the item's normal attack. This component gives the item a power on right click, or on the ability key (V by default, rebindable in Options → Controls → MineDnD):

"minednd:active_ability": {
  "type": "fireball",
  "damage": 4,
  "scaling": { "ability": "int", "per_modifier": 1.5 },
  "fire_seconds": 3,
  "cooldown": 30,
  "hunger_cost": 3
}

Field	Default	Range	Meaning
`type`	(required)	`fireball`, `throw`	`fireball`: a bolt of fire that flies straight, never breaks blocks, fizzles in water or after 5 s. `throw`: a magical copy of the weapon flies out, hits the first creature, then flies back through blocks (the real item stays in your hand).
`right_click`	`true`	`true`, `false`	`true`: right click uses the power, replacing the item's normal right click. `false`: the item keeps its normal right click (eating, drawing a bow, blocking with a shield…) and the ability key uses the power (main hand first, then off hand).
`damage`	4	0–100	Base damage (2 = one heart).
`scaling`	none		`{ "ability": "str", "per_modifier": 1 }`: adds `per_modifier` × the holder's modifier (score 14 → +2, 8 → −1) to the damage, never below 0. `per_modifier` is −20 to 20, default 1.
`fire_seconds`	0	0–60	Sets the target on fire.
`speed`	1.5	0.1–5	Projectile speed (an arrow at full draw is about 3).
`range`	16	1–64	`throw` only: blocks before it comes back.
`cooldown`	20	0–1200	Ticks (20 = 1 second) before the next use, shown on the hotbar.
`durability_cost`	0	0–100	Durability used per use (only on items with durability; Unbreaking does apply).
`hunger_cost`	0	0–40	Exhaustion per use, the vanilla hunger drain (4 = one hunger point). With an empty food bar the power can't be used.

On right click the ability replaces the item's normal right click: for food, bows, shields and other items whose right click matters, use "right_click": false.
It follows minednd:requirements: below them the power is dormant and a message says which scores are missing.
In creative mode there's no durability or hunger cost (the cooldown still applies).
The tooltip shows "Right click: …" or "Press V: …" (the key players actually bound), the damage for your current scores and the costs.
Use rules (crafting_requirements with "applies_to": ["use"]) are checked first, like for any right click.
Examples: items/weapons/wizard_staff.json (fireball, INT scaling, hunger cost) and items/weapons/flame_sword.json (throw, STR scaling, fire, durability cost), items/weapons/ranger_bow.json (fireball on the ability key, so the bow still draws on right click).

Recipes¶

Files: data/<namespace>/recipe/**/*.json. A MineDnD item can be crafted in a crafting table with a recipe of type minednd:crafting_shaped. It's a vanilla shaped recipe whose result names the MineDnD item, so the item is defined only once, in items/:

{
  "type": "minednd:crafting_shaped",
  "category": "equipment",
  "pattern": ["CGC", "GSG", "CBC"],
  "key": {
    "C": "minecraft:copper_ingot",
    "G": "minecraft:glowstone_dust",
    "S": "minecraft:golden_sword",
    "B": "minecraft:blaze_rod"
  },
  "result": { "item": "minednd:weapons/sun_blade" }
}

pattern and key work exactly as in minecraft:crafting_shaped: up to 3 rows of up to 3 characters, a space is an empty slot, and each character maps to an item id, an item tag ("#minecraft:planks") or a list of items.
result.item: the item id (<namespace>:<path in items/>). Optional result.count (1-99, default 1).
category (optional): recipe book tab: equipment, building, redstone or misc (default).
show_notification (optional, default true): the "new recipes" toast when the recipe unlocks (see Unlocking below).
The crafted item is the catalog item exactly as it is when crafted (name, enchantments, bonuses, requirements, ability). If the catalog has no such item, the recipe crafts nothing.
Avoid the shape and ingredients of a vanilla recipe: when two recipes match the same grid, only one of them is used.
Requirement rules can restrict these recipes like any other: "recipes": ["minednd:weapons/sun_blade"] in crafting_requirements (the recipe id is the file's path). By result item they match the base item (e.g. minecraft:golden_sword).
MineDnD Studio edits recipes in the item's page (Recipe: a 3x3 grid, or the brewing form below) and keeps the file next to the item's name.
The built-in content has 53 crafting recipes and 4 brewing recipes (see Default content): most upgrade the plain base item with special ingredients.

Unlocking recipes¶

Crafting recipes unlock the Minecraft way: a recipe appears in a player's recipe book (with the "new recipes" toast) the first time they get one of its key ingredients. It's a vanilla advancement without display, in data/<namespace>/advancement/recipes/<recipe path>.json, whose reward is the recipe:

{
  "parent": "minecraft:recipes/root",
  "criteria": {
    "has_blaze_powder": { "trigger": "minecraft:inventory_changed", "conditions": { "items": [{ "items": "minecraft:blaze_powder" }] } },
    "has_magma_cream": { "trigger": "minecraft:inventory_changed", "conditions": { "items": [{ "items": "minecraft:magma_cream" }] } },
    "has_the_recipe": { "trigger": "minecraft:recipe_unlocked", "conditions": { "recipes": "minednd:weapons/flame_sword" } }
  },
  "requirements": [["has_the_recipe", "has_blaze_powder", "has_magma_cream"]],
  "rewards": { "recipes": ["minednd:weapons/flame_sword"] }
}

One inventory_changed criterion per item (an item id or "#tag"), all in one requirement group: any of them is enough. has_the_recipe completes the advancement for players who already have the recipe (e.g. from /recipe give), like in vanilla.
Any trigger works (e.g. minecraft:player_killed_entity, or a MineDnD achievement trigger): it's a normal advancement, and /advancement and /recipe work as usual.
A crafting recipe that no advancement unlocks is in every player's recipe book from the start (on join and after /reload), as before: datapacks made for older versions keep working.
The recipe book only shows recipes: anyone who places the right ingredients crafts the item, unlocked or not (as in vanilla, unless the limitedCrafting game rule is on). To restrict crafting, use requirement rules.
Built-in recipes unlock from their special ingredient (e.g. blaze powder or magma cream → Flame Sword, an echo shard → Shadow Dagger).
Updating a world: players who joined before this version had every MineDnD recipe. On their first join they lose the ones they haven't unlocked yet (once); those whose ingredients they carry come back at once.
Brewing recipes aren't unlocked: the brewing stand's recipe list always shows every potion, like vanilla.
MineDnD Studio edits this in the item's Recipe section (Unlocked by) and keeps the file next to the recipe.

Brewing recipes¶

Recipe type minednd:brewing. Since Minecraft 26.3 brewing is data-driven: every vanilla potion comes from a minecraft:brewing recipe (data/minecraft/recipe/brewing/*.json in the Minecraft jar). A minednd:brewing recipe works the same way in the brewing stand, but its result names a MineDnD item, and its bottle can be one:

{
  "type": "minednd:brewing",
  "input": { "item": "minecraft:potion", "potion_contents": { "potions": "minecraft:strong_healing" } },
  "reagent": { "item": "minecraft:ghast_tear" },
  "result": { "item": "minednd:potions/potion_of_superior_healing" }
}

input: what goes in the three bottle slots, in vanilla's format: a bottle item (minecraft:potion, splash_potion or lingering_potion) and the potion it holds (potion_contents.potions: a potion id like minecraft:awkward, a list, or a potion tag). Or { "catalog_item": "<MineDnD item id>" }: a bottle of that MineDnD item, to brew one custom potion from another.
reagent: the item on top, in vanilla's format ({ "item": "minecraft:ghast_tear" }; a list or an item tag work too). Any item, also ones vanilla never brews with. One is used up per brew.
result.item: the MineDnD item it makes, exactly as defined in items/. One bottle in, one bottle out.
Brewing takes 20 seconds and blaze powder, like vanilla. A splash or lingering version of a custom potion is another item with its own recipe.
Avoid a bottle and reagent pair that vanilla (or another recipe) already uses: only one of them would work. Studio warns about it.
A plain minecraft:brewing recipe also works for a custom potion written out in full in output (vanilla's format), but then it can't use requirement rules by MineDnD id, nor start from a MineDnD item.
Players see every brewing recipe of the world, vanilla and custom, in the brewing stand's recipe list (the recipe book button): see In game below.
The built-in potions: Superior Healing (Healing II + Ghast Tear), Hill Giant Strength (Strength II + Block of Iron), Heroism (Awkward Potion + Golden Apple), Invisibility (Night Vision + Golden Carrot).

Enchantments¶

Files: data/<namespace>/enchantment/*.json. These are vanilla data-driven enchantments. See the example holy_strike.json (extra damage against undead) and the vanilla ones (e.g. smite) for the format. Effects are limited to what vanilla's enchantment effect components can express (damage, attributes, potion effects, ...).

Custom enchantments appear in the MineDnD creative tab as enchanted books (one per level).
They don't show up in enchanting tables unless you also add them to the vanilla #minecraft:in_enchanting_table tag.
Give them a translatable name: "description": { "translate": "enchantment.my_campaign.holy_strike", "fallback": "Holy Strike" }.

The example pack contains three enchantments to copy from:

File	Type	Does
`holy_strike.json`	`minecraft:damage`	Extra damage against undead
`venom_strike.json`	`minecraft:post_attack`	Poisons the target, only if the attacker has STR 12 and DEX 12
`fleetfoot.json`	`minecraft:attributes`	+10% movement speed per level while worn on the feet

Ability requirements on enchantments¶

The condition minednd:ability_scores works in any effect's requirements (and in loot tables and predicates):

"requirements": {
  "type": "minednd:ability_scores",
  "entity": "attacker",
  "min": { "str": 12, "dex": 12 }
}

entity (optional, default attacker): whose scores to check: attacker (the wielder in attack effects), this, direct_attacker, attacking_player.
Uses effective scores (base + item bonuses).
Non-player entities (e.g. a mob holding the weapon) have no D&D stats and always pass.
Combine with other conditions using minecraft:all_of, as in venom_strike.json.
Unlike minednd:requirements on items, this isn't shown in tooltips: mention it in the item's lore if players should know.

Requirement rules¶

Files: data/<namespace>/crafting_requirements/**/*.json. Ability scores a player needs to craft a recipe or brew a potion and, optionally, to place or use an item (drink or throw a potion). Things not matched by any file have no requirements.

{
  "recipes": ["minecraft:redstone_torch"],
  "requirements": { "int": 12, "wis": 10 }
}

{
  "items": "minecraft:anvil",
  "applies_to": ["craft", "place"],
  "requirements": { "str": 13 }
}

Potions, by the potion they hold (in any bottle) or in some bottles only:

{
  "potions": ["minecraft:healing", "minecraft:strong_healing"],
  "requirements": { "wis": 12, "int": 10 }
}

{
  "items": "minecraft:splash_potion",
  "potions": "#minednd:harmful",
  "applies_to": ["craft", "use"],
  "requirements": { "int": 12 }
}

Different scores for each action:

{
  "items": "minecraft:enchanting_table",
  "requirements": {
    "craft": { "int": 14 },
    "place": { "int": 12 },
    "use": { "int": 12, "wis": 10 }
  }
}

recipes (optional): recipe ids, crafting or brewing. A vanilla recipe's id is its file name in the Minecraft jar under data/minecraft/recipe/: usually the item name (minecraft:redstone_torch), but some items have several recipes with other ids (e.g. minecraft:red_dye_from_poppy). Vanilla brewing recipes are minecraft:brewing/<bottle>_<potion>_<reagent>, e.g. minecraft:brewing/potion_awkward_ghast_tear. A MineDnD recipe's id is its file's path, e.g. minednd:potions/potion_of_heroism.
items (optional): targets every recipe whose result is this item, a list of items, or an item tag ("#minecraft:planks"). Handy when an item has several recipes.
potions (optional): potions, by what the bottle holds: a potion id (minecraft:healing), a list, or a potion tag ("#minednd:harmful"). Long and strong versions are separate potions (minecraft:long_poison, minecraft:strong_healing). Alone, it covers potions, splash and lingering potions and tipped arrows holding them; with items, only those items holding them (e.g. splash potions of poison, not drinkable ones).
At least one of recipes / items / potions is required. One file can list many recipes.
applies_to (optional, default ["craft"], only with the same-scores form): what the rule restricts. Any of:
craft: making it: crafting the recipe (crafting table, inventory grid; Crafters refuse it), or brewing the potion (brewing stand).
place: placing the item as a block. The block stays in the hand.
use: using the item (right click: eat, drink, throw, ...) and interacting with its placed block (e.g. opening an enchanting table). Blocked interactions do nothing, so you can still place blocks against it. For recipes rules, place and use apply to the recipe's result item.
requirements, one of two forms:
Same scores for every action: { "int": 12, "wis": 10 } (any of str, dex, con, int, wis, cha), applied to each action in applies_to.
Scores per action: { "craft": {…}, "place": {…}, "use": {…} }, listing only the actions to restrict. applies_to isn't used with this form. Scores are effective scores (item bonuses count).
If several files match the same recipe or item, the highest minimum per ability applies.

In game:

Crafting: applies to the crafting table and the 2x2 inventory grid. When the player doesn't qualify, the result slot stays empty and "To craft this you need: Intelligence 12, Wisdom 10" appears above the hotbar.
Placing and using: the action is blocked with "To place this you need: ..." / "To use this you need: ...". Players in creative mode are exempt from place and use (e.g. an operator building the world); crafting is restricted for everyone.
Item tooltips list the requirements per action ("To craft: Intelligence 14", "To place: ..."), green when the player meets them, red when not.
Blocks already placed in the world stay where they are; use decides whether players can interact with them.
The recipe book still lists the recipe (it can't know about requirements); it just won't produce a result.
Crafter blocks can't craft restricted recipes, since there's no player to check (otherwise they'd bypass the requirement).
Crafting and brewing only: furnaces, smithing tables and stonecutters are not restricted.
/reload applies changes.

Brewing in game¶

The brewing stand brews a restricted potion only for its brewer: the player who last put in or took out its bottles, reagent or blaze powder. Their scores decide, while they're online. Bottles they can't brew stay as they are (the others in the stand still brew), and "To brew this you need: Wisdom 12, Intelligence 10" appears above their hotbar when they set it up.
A stand filled only by hoppers, or whose brewer is offline, doesn't brew restricted potions (like a Crafter with restricted recipes).
Potion tooltips say "To brew: …" (and "To use: …" for drinking or throwing), green or red for the player.
The brewing stand has a recipe list, opened with the recipe book button: every potion of the world (vanilla, MineDnD and datapacks), with tabs for potions, splash, lingering and custom ones, a search box, and a filter for what the player can brew now. Hovering a potion shows what goes in the bottles and on top, and its requirements; clicking it shows the recipe faded in the stand's slots (click again for other ways to brew it), and clicking a faded bottle shows how to brew that bottle in turn. A greyed-out bottle means the player's scores are too low; a red slot that they lack the ingredients.

Built-in brewing tiers¶

The built-in pack (crafting_requirements/brewing/, with the potion tags #minednd:effects, #minednd:enhanced and #minednd:harmful) gives every vanilla potion a tier. Rules add up: the highest score per ability wins.

Potions	To brew
Water, Awkward, Mundane, Thick (any bottle)	Nothing
Potions with effects (`#minednd:effects`)	WIS 10
Stronger (II) and longer versions (`#minednd:enhanced`), splash potions with effects	WIS 12, INT 10
Lingering potions with effects	WIS 13, INT 12
Harmful potions (`#minednd:harmful`: poison, harming, weakness, slowness)	INT 11; lingering: INT 13
Superior Healing / Hill Giant Strength / Heroism / Invisibility	WIS 14 INT 12 / WIS 13 INT 13 / WIS 14 CHA 12 / WIS 13 INT 14

To change a tier, put a file with the same path in your own pack (e.g. data/minednd/crafting_requirements/brewing/splash_potions.json): it replaces the built-in one. To drop a tier, replace it with scores of 1 (a rule needs at least one score), or disable the built-in pack.

Achievements¶

Files: data/<namespace>/advancement/**/*.json. Achievements are vanilla advancements: the game shows them in the advancements screen (their own tab if you make a root), with the notification and the chat message. Any vanilla trigger works; MineDnD adds triggers for what vanilla can't count. The built-in pack has a MineDnD tab (minednd:minednd/..., 27 advancements, some hidden) that unlocks the starter titles.

Trigger	Conditions	Completes when
`minednd:discovered`	`kind`, `min` (1–10,000), optional `of` (ids or `#tags`)	the player has `min` different first times of `kind`: `biome`, `mob`, `death`, `dimension`, `structure`, `block`, `craft`, `food`, `effect`, `tame`, `breed`, `catch`, `brew`, `trade`, `enchantment` (e.g. `"of": ["#minecraft:is_nether"]` counts only Nether biomes)
`minednd:statistic`	`stat` (a statistic type: `minecraft:mined`, `killed`, `crafted`, `used`, `custom`, …), `target` (an id, or a `#tag` whose members are added up), `min`	the statistic reaches `min` (`"stat": "minecraft:mined", "target": "#c:ores", "min": 300`)
`minednd:cooked`	optional `item` (item conditions), `food` (`true`: only food)	the player takes cooked results out of a furnace, smoker or blast furnace, or food they put on a campfire finishes cooking
`minednd:level`	`min`	the character reaches that level
`minednd:ability_score`	optional `ability` (`str`, `dex`, …; any when absent), `min`	the character's own score (not item bonuses) reaches `min`
`minednd:repeat`	`count` (1–1,000,000), `of` (any criterion: `{"trigger": …, "conditions": …}`)	`of` has happened `count` times (`cooked` counts each item)

{
  "parent": "minednd:minednd/archer_2",
  "criteria": {
    "cows": {
      "trigger": "minednd:repeat",
      "conditions": {
        "count": 1000,
        "of": {
          "trigger": "minecraft:player_killed_entity",
          "conditions": {
            "entity": { "type": "minecraft:entity_properties", "entity": "this", "predicate": { "minecraft:entity_type": "minecraft:cow" } },
            "killing_blow": { "direct_entity": { "minecraft:entity_type": "#minecraft:arrows" }, "tags": [{ "id": "#minecraft:is_projectile", "expected": true }] }
          }
        }
      }
    }
  },
  "display": {
    "icon": { "id": "minecraft:leather" },
    "title": { "translate": "advancements.minednd.cow_slayer.title" },
    "description": { "translate": "advancements.minednd.cow_slayer.description" },
    "frame": "challenge",
    "hidden": true
  }
}

What counts: first times are recorded in every world (also with adventure XP off), and vanilla statistics from the start of the world, so discovered and statistic count what was done before the advancement existed. repeat and cooked count from when the advancement is there. Progress of repeat is saved per player.
Adventure XP: advancements give their frame's XP (advancement_task / _goal / _challenge), except those that count repetitions (a minednd:repeat or minednd:statistic criterion): reward those with a title.
Showing progress: a criterion is done or not, so "37/50" doesn't show. Make chains of thresholds instead (25 → 45 → 60 biomes), each its own advancement, like the built-in tab does.
Hidden: "hidden": true keeps an advancement out of the tab until it's done.

Titles¶

Files: data/<namespace>/title/*.json. A title is a reward worn above the head. It unlocks when its advancement is done (and locks again if that's revoked); a player wears one at a time, chosen in the character sheet or with /dnd title, and only the worn title's effects apply. The built-in pack has ten: The Miner, Zombie Killer, The Archer, The Explorer, The Lumberjack, The Angler, The Master Chef, The Alchemist, The Survivor and (hidden) The Cow Slayer.

{
  "name": { "translate": "title.minednd.miner", "color": "gray" },
  "description": { "translate": "title.minednd.miner.description" },
  "unlocked_by": "minednd:minednd/miner_2",
  "effects": [
    { "type": "enchantment_level", "enchantment": "minecraft:fortune", "level": 1, "item": "#minecraft:pickaxes", "blocks": "#c:ores" }
  ]
}

name: a text component (translatable, with a colour); description (optional): what it gives, shown in the character sheet's tooltip; unlocked_by: an advancement id.
item, target and blocks are optional conditions: an id, a #tag or a list of them.

Effect `type`	Fields	While worn
`enchantment_level`	`enchantment`, `level` (1–255), optional `item`, `target`, `blocks`	the item counts as having that enchantment at that level: Looting (kills), Fortune (block drops), Luck of the Sea (fishing); a real higher level wins, the two don't add up
`damage_bonus`	`amount` (0.1 = +10%), optional `item`, `target`	more damage (melee, arrows, tridents) against `target` / with `item`
`ability_bonus`	`ability`, `amount` (−10–10)	an ability score bonus, like an item's (it counts for requirements)
`xp_bonus`	`amount`, optional `sources`	more adventure XP from `biome`, a first-time kind (`structure`, `mob`, …), `advancement`, `kill` or `vanilla_xp` (all when absent)
`break_speed`	`amount`, optional `blocks`	breaks those blocks faster
`hunger`	`amount` (−0.05 = 5% slower)	hunger drains faster or slower
`max_health`	`amount` (2 = 1 heart)	extra max health
`potion_duration`	`amount`	potions the player drinks last longer

Amounts are −1 to 10 (max_health: −19 to 100). A broken title file is logged and skipped.

World settings¶

File: data/minednd/settings.json. How ability scores affect the world, how characters progress (and level up by playing), and how requirement rules behave, per world. Every field is optional: anything missing uses the default, so a campaign only writes what it changes:

{
  "abilities": { "strength": { "melee_damage_per_modifier": 0.2 } },
  "progression": { "points_per_level": 5 }
}

The full file with every default:

{
  "abilities": {
    "strength": {
      "melee_damage_per_modifier": 0.10,
      "min_melee_damage_multiplier": 0.5,
      "log_speed_per_modifier": 0.15,
      "min_log_speed_multiplier": 0.5
    },
    "dexterity": {
      "speed_per_modifier": 0.04,
      "min_speed_multiplier": 0.75,
      "attack_rate_per_modifier": 0.08,
      "min_attack_rate_multiplier": 0.7
    },
    "constitution": {
      "health_per_modifier": 2,
      "min_health_bonus": -10,
      "hunger_per_modifier": 0.07,
      "min_hunger_multiplier": 0.25,
      "max_hunger_multiplier": 1.5
    },
    "intelligence": {
      "xp_per_modifier": 0.10,
      "min_xp_multiplier": 0.5
    }
  },
  "progression": {
    "starting_score": 10,
    "points_per_level": 3,
    "max_level": 20,
    "max_score_from_points": 20
  },
  "experience": {
    "enabled": false,
    "level_curve": "exponential",
    "level_xp_base": 3000,
    "level_xp_increase": 150,
    "level_xp_growth": 1.05,
    "level_xp_formula": "3000 * 1.05^(level - 1)",
    "level_xp_table": [],
    "per_vanilla_xp": 0.0,
    "per_kill_health": 0.5,
    "passive_kills": false,
    "repeat_kills": true,
    "repeat_kill_health": 0.25,
    "daily_xp_cap": 60,
    "advancement_task": 25,
    "advancement_goal": 75,
    "advancement_challenge": 200,
    "death_loss": 0.0,
    "new_mob": 25,
    "new_biome": 15,
    "new_death": 25,
    "new_dimension": 100,
    "new_structure": 40,
    "new_block": 10,
    "new_craft": 3,
    "new_food": 5,
    "new_effect": 10,
    "new_tame": 30,
    "new_breed": 15,
    "new_catch": 10,
    "new_brew": 10,
    "new_trade": 15,
    "new_enchantment": 20
  },
  "requirements": {
    "creative_exempt": true
  }
}

Ability effects are 1 + rate × ability modifier, never below the min_… floor. A rate of 0 turns that effect off. Example: melee_damage_per_modifier: 0.2 makes STR 20 (+5) deal ×2.0 damage instead of ×1.5. Ranges: rates 0–10, floors 0–1 (attack rate 0.1–1), health_per_modifier 0–20 health (2 = 1 heart), min_health_bonus −19–0, hunger_per_modifier 0–1, max_hunger_multiplier 1–10.
Progression: starting_score (1–30) for new characters and resets, points_per_level (0–100), max_level (1–100), max_score_from_points (1–30, D&D: 20). Changes apply from now on: existing characters keep their scores and points (use /dnd reset to rebuild one).
Experience (adventure XP: players level up by playing; separate from vanilla XP):
enabled (default false): true lets players earn XP by playing. While it's off, only an operator gives levels and XP (/dnd level add, /dnd xp add), and the sources below are ignored. Vanilla XP always works as usual.

Level curve: what each level costs. level_curve picks the shape; with L the level being left (1 for 1 → 2), level L → L+1 costs:

`level_curve`	Cost of L → L+1	Uses
`linear`	`base + increase × (L − 1)`: the same extra XP every level	`level_xp_base`, `level_xp_increase`
`exponential` (default)	`base × growth^(L − 1)`: each level a fixed % more than the last (1.05 = +5%; below 1 = cheaper)	`level_xp_base`, `level_xp_growth`
`logarithmic`	`base × (1 + growth × ln L)`: rises quickly, then flattens	`level_xp_base`, `level_xp_growth`
`power`	`base × L^growth` (2 = quadratic)	`level_xp_base`, `level_xp_growth`
`formula`	your own expression of `level`	`level_xp_formula`
`table`	the listed costs in order; past the end, the last one repeats	`level_xp_table`

Ranges: level_xp_base 1–1,000,000, level_xp_increase 0–1,000,000, level_xp_growth 0–100, level_xp_table up to 100 costs of 1–1,000,000,000 (a table curve needs it in the same file). A formula may use numbers, + - * / %, ^ (power), parentheses, e, pi and ln (also log), log10, log2, sqrt, exp, abs, floor, ceil, round, min(a, b), max(a, b), pow(a, b), e.g. 1000 + 500 * ln(level) or 300 * level^2; one that gives no number at some level up to 100 (like ln(level - 1) at level 1) makes the file invalid. Costs are rounded and at least 1. With the defaults: 3000, 3150, 3308, … 7220 for 19 → 20. - Balance of the defaults: level 2 after about 3–4 days of play (at ~2 hours a day), each next level a bit longer than the last (about 6, 8, 9 … days), level 20 a long-term goal (around 300+ days of play). First times give most XP early and become rare later, so later kills (repeat_kills) keep high levels reachable; daily_xp_cap keeps farms from replacing adventuring. These are estimates from a model of how fast a typical player finds new things: tune level_xp_base to move level 2, level_xp_growth for the later levels. - By default XP comes from first times (the new_… values below), advancements and a little from later kills. Grinding can't go past the daily cap. - Kills: new_mob for the first kill of each hostile mob type, plus per_kill_health per point of its max health (0–100; passive_kills: true also counts animals). Later kills of a type give repeat_kill_health per point of max health (0–100, default 0.25: zombie 5 XP; repeat_kills: false turns them off). per_vanilla_xp per vanilla XP point picked up from orbs (0–100, default 0). Later kills and orbs together give at most daily_xp_cap XP per Minecraft day of play (20 minutes, counted by world time, so sleeping doesn't reset it; 0–1,000,000, default 60, 0 = no limit). advancement_task, advancement_goal, advancement_challenge: advancements shown in the advancements screen. - First times, each counted once per player (0–100,000; 0 turns one off):

Setting	The first time a player…	Default
`new_mob`	kills each mob type (plus the health-based XP)	25
`new_biome`	enters each biome	15
`new_death`	dies from each cause, i.e. damage type (drowning, lava, falling, a creeper, …)	25
`new_dimension`	enters each dimension, except the one they start in	100
`new_structure`	walks inside each structure; variants in the vanilla tags `#village`, `#mineshaft`, `#ocean_ruin`, `#shipwreck`, `#ruined_portal`, `#abandoned_camp` count once	40
`new_block`	mines each block of the block tag `#minednd:first_time_xp` (built in: `#c:ores`, ancient debris, amethyst, sculk, spawners, suspicious sand and gravel, …)	10
`new_craft`	crafts or smelts each item (crafting table, furnace, stonecutter, smithing table, …); MineDnD items count by their own id	3
`new_food`	eats or drinks each item (food, potions, milk, honey)	5
`new_effect`	gets each status effect	10
`new_tame` / `new_breed`	tames / breeds each kind of animal	30 / 15
`new_catch`	fishes up each item	10
`new_brew`	takes each kind of potion out of a brewing stand	10
`new_trade`	trades with each villager profession (and the wandering trader)	15
`new_enchantment`	gets each enchantment from an enchanting table	20

What a player has already done is saved with the player (in every world, also while adventure XP is off): changing these values never pays twice. To choose the blocks, add to or replace the tag in a datapack (data/minednd/tags/block/first_time_xp.json, "replace": true to start from scratch). Structure and dimension names come from the language keys structure.<namespace>.<path> and dimension.<namespace>.<path> (else the id in words). - death_loss (0–1): share of the XP towards the next level lost on death (0.5 = half). Levels are never lost. - /dnd xp add / /dnd xp set give or set XP by hand, also while enabled is false. - Requirements: creative_exempt (default true) lets creative players ignore place and use rules. - /reload applies changes; online players' health, speed and damage are updated right away. - Built-in "MineDnD World Settings" pack (minednd:settings, on by default): it has this file with every value at its default, shown above. Copy it as a starting point. Your own pack only needs the values it changes, e.g. { "experience": { "enabled": true } }. - /dnd info settings shows, in game, every value that differs from the default and which pack set it. - If several packs have this file, they are merged key by key: the built-in pack is always the base, then the others in the world's data pack order, so the highest pack wins for the keys it sets. - An invalid file (a value out of range, a typo in a value) is skipped as a whole: the server log names the pack and says why, and the other files still apply. - MineDnD Studio has a World settings page: every value explained, a score → effect table, the XP curve and presets.

Translations¶

Put one file per language in data/<namespace>/lang/, named with Minecraft's language codes (en_us, it_it, es_es, fr_fr, de_de, ...). Same format as a resource pack lang file:

data/my_campaign/lang/en_us.json

{
  "item.my_campaign.flame_sword": "Flame Sword",
  "item.my_campaign.flame_sword.lore": "Forged in the Plane of Fire",
  "enchantment.my_campaign.holy_strike": "Holy Strike"
}

data/my_campaign/lang/it_it.json

{
  "item.my_campaign.flame_sword": "Spada Fiammeggiante",
  "item.my_campaign.flame_sword.lore": "Forgiata nel Piano del Fuoco",
  "enchantment.my_campaign.holy_strike": "Colpo Sacro"
}

Each player sees their own language (Options → Language). Missing keys fall back to en_us, then to the fallback text in the item/enchantment JSON.
Datapacks normally can't carry translations: MineDnD loads these on the server and sends them to every player with the mod, so a single datapack holds everything. /reload updates them live.
Key names are up to you; the convention is item.<namespace>.<name> and enchantment.<namespace>.<name>.
Any text component can use these keys, e.g. /tellraw @a {"translate":"my_campaign.quest.intro"}.

Reloading¶

Change	How to apply it
Add or edit items or recipes	`/reload`: the creative tab and recipe books update automatically (new unlock advancements apply from the next inventory change)
Add or edit translations	`/reload`
Add or edit crafting requirements	`/reload`
Change world settings	`/reload`
Add or edit enchantments	Restart the server (vanilla limitation)