How MineDnD works¶

What the mod does and how it's meant to be used, for players, operators (server admins, the "game master" of a campaign) and content authors (people writing datapacks). Every number below is a default that a world can change in its settings.

MineDnD is the engine: the character, levels, item powers, the stations that make items, requirement rules, loot, achievements and titles as systems. What exists in a world (which items, recipes, rules, enchantments, achievements and titles) comes from its datapacks. The examples on this page come from the Default Content datapack (namespace dnd5e), one world built with the engine, a separate download; without it the engine works the same, with only what your own datapacks add.

Reference pages: - Commands: every /dnd command. - Datapacks: datapack formats and world settings. - Default content: every item, enchantment and rule of the Default Content datapack, in tables; items and enchantments one by one.

1. In one paragraph¶

MineDnD adds a Dungeons & Dragons character to every player. Six ability scores change how they fight, move and survive. They gain levels (from the operator, or by playing if the world turns adventure XP on) and spend ability points to raise scores. Magic items have bonuses and powers that only work with enough ability. Many of them are crafted, others are rare. Requirement rules can also ask for ability scores to craft, place or use ordinary things like anvils or beacons. Everything is data: a world changes items, rules and numbers with datapacks, and needs no code.

2. Who does what¶

Role	Can	How
Player	See the character sheet, spend points, craft and use items, earn XP	Key K (character sheet), V (ability of the item in hand), G (ability of worn armor), crafting table, playing
Operator	Set levels, XP, points and scores; give items; reset characters; place item chests	`/dnd …` commands (operator permission, like vanilla `/give`)
Content author	Add or change items, recipes, enchantments, requirement rules, translations, world settings	Datapacks: plain JSON files (reference)

3. The character¶

3.1 Ability scores¶

Strength (STR), Dexterity (DEX), Constitution (CON), Intelligence (INT), Wisdom (WIS), Charisma (CHA).

New characters start with every score at 10 (setting starting_score).
The modifier is D&D's floor((score − 10) / 2): 10–11 → +0, 14 → +2, 20 → +5, 8 → −1.
The effective score is the base score plus bonuses from equipped items and the title (max 30). All effects and item requirements use it; requirement rules use the base score alone.
Points can raise a base score up to 20. Operators can set scores from 1 to 30.

3.2 What the scores do (defaults)¶

Ability	Effect	Example
STR	Melee damage (fists and weapons, not bows) +10% per modifier point (floor ×0.5)	STR 14 → ×1.2, STR 20 → ×1.5, STR 30 → ×2
STR	Log chopping speed +15% per point (floor ×0.5)	STR 14 → ×1.3, STR 20 → ×1.75
STR	Mining speed on every other block (stone, ores, dirt…) +10% per point (floor ×0.5)	STR 14 → ×1.2, STR 20 → ×1.5
DEX	Movement speed and air control (jumps carry further) +4% per point (floor ×0.75); not creative flight	DEX 14 → ×1.08, DEX 20 → ×1.2
DEX	Attack rate +8% per point (floor ×0.7): melee cooldown, bow draw, crossbow reload (stacks with Quick Charge), trident wind-up	DEX 14 → ×1.16, DEX 20 → ×1.4
CON	Max health +1 heart per point (at least 5 hearts)	CON 14 → +2 hearts, CON 20 → +5
CON	Hunger drains 7% slower per point (×0.25 to ×1.5)	CON 14 → ×0.86, CON 20 → ×0.65
INT	Vanilla XP from mining blocks and from kills (also with projectiles) +10% per point (floor ×0.5); furnaces, breeding, fishing and trading are unaffected	INT 14 → ×1.2, INT 20 → ×1.5
INT	Arcana, enchanting table: counts as +1 level per point for an offer's level requirement (what enchanting costs and how strong the offers are don't change)	INT 20 at level 25 → can pick a level 30 offer
INT	Arcana, imbuing: −1 level of cost per 2 points (never below 1)	INT 14 → a 5-level wand costs 4, INT 20 → 3
INT	Arcana, anvil: −5% level cost per point (×0.5 to ×1.25), so items get "Too Expensive!" later	INT 14 → ×0.9, INT 20 → ×0.75
WIS	Willpower: harmful effects (poison, wither, slowness, weakness…) last 10% less per point (×0.5 to ×1.25), from any source	WIS 14 → ×0.8, WIS 20 → ×0.5
WIS	Potions you drink last 10% longer per point (floor ×0.7); splash and lingering don't	WIS 14 → ×1.2, WIS 20 → ×1.5
WIS	Luck +0.4 per point (vanilla's luck: better fishing and loot, like Luck of the Sea)	WIS 14 → +0.8, WIS 20 → +2
CHA	Villagers and wandering traders ask 5% less per point (at most 50% off; low CHA up to 15% more); adds up with Hero of the Village and reputation, never below 1 emerald	CHA 14 → ×0.9, CHA 20 → ×0.75 (10 emeralds → 8)
CHA	Bartering: 5% chance per point that a piglin gives a second roll of its barter loot for your gold	CHA 14 → 10%, CHA 20 → 25%
CHA	Presence: villagers' good opinion of you (trades, curing a zombie villager) grows 10% faster per point (floor ×0.5), which lowers their prices too; from CHA 16, iron golems don't turn on you over what villagers think (hitting one still does)	CHA 20 → ×1.5
CHA	Intimidation: hostile mobs notice you from 5% closer per point (×0.5 to ×1.15), as sneaking does	CHA 14 → ×0.9, CHA 20 → ×0.75

Low scores give a mild malus with a floor, so weak characters stay playable. Every number is a world setting. /dnd stats and the character sheet show item bonuses in aqua; hovering an ability in the character sheet lists what it does now, with the numbers for the player's score.

3.3 The character sheet¶

Open it with K, or with the button next to the inventory. It shows: - the level and the adventure XP bar ("XP 60 / 100", or "Max level"); - the unspent points; - each score with its modifier. Item bonuses are shown in aqua; - the title button: wears the next unlocked title (or none); its tooltip says what the worn title gives.

With points to spend, each ability gets + and − buttons: - Points can be added and taken back freely, up to the score cap (20 from points) and never below the saved score. New scores and their modifiers show in yellow, and "Points: 1 (2 unsaved)" counts what's left. - Save spends them all at once, after a confirmation that lists the changes (e.g. "Strength 10 → 12"). Saved points are final: only an operator can undo them (/dnd reset stats refunds the points from levels). - Discard puts the unsaved points back. Closing the sheet with unsaved points asks whether to save or discard.

4. Progression¶

4.1 Levels and points¶

Characters start at level 1. The maximum is 20 (setting max_level, up to 100).
Each level gives 3 ability points (setting points_per_level), announced with "Level up!" in chat.
Points never disappear on death. Operators can add points without levels (/dnd points add).

4.2 Adventure XP (levelling by playing)¶

On with the Default Content datapack, which turns it on (without XP for repeat kills, see the table). Without that pack it's off: players earn no adventure XP by playing, and a world turns it on with "experience": { "enabled": true } in its settings. Either way the operator (the DM) can give levels and XP with /dnd level add and /dnd xp add, which always work. Vanilla XP is never affected: orbs, enchanting and the XP bar work as usual.

When it's on, players earn adventure XP by doing things for the first time, so exploring and trying new things levels a character, and grinding (mob farms, mining, smelting) doesn't:

Source	Default
First kill of each hostile mob type	25 + 0.5 × its max health (zombie 35, enderman 45, wither 175)
Completing an advancement	25 task, 75 goal, 200 challenge
Entering a biome for the first time	15
Entering a dimension for the first time (not the starting one)	100
Walking into a kind of structure for the first time (village, stronghold, bastion, …; variants count once)	40
First death from each cause (drowning, lava, falling, a creeper, …)	25
First time mining each block of `#minednd:first_time_xp` (ores, ancient debris, amethyst, sculk, spawners, …)	10
Each item crafted or smelted for the first time	3
Each food or drink tried for the first time (food, potions, milk, honey)	5
Each status effect received for the first time	10
Each kind of animal tamed / bred for the first time	30 / 15
Each item fished up for the first time	10
Each kind of potion brewed for the first time	10
First trade with each villager profession (and the wandering trader)	15
Each enchantment received for the first time from an enchanting table	20
Every further kill (`repeat_kills`, `repeat_kill_health`)	0.25 × max health (zombie 5); off with the Default Content datapack
Vanilla XP orbs picked up (mining ores, smelting, kills, fishing, trading, breeding)	0 (off) per XP point

Daily cap: further kills and vanilla orbs together give at most 60 XP per Minecraft day of play (daily_xp_cap; sleeping doesn't reset it), so farms can't replace adventuring. First times and advancements have no cap.
Level cost: an exponential curve: level 1 → 2 costs 3000 XP and each next level 5% more (19 → 20: 7220; about 91,600 XP in total). Balanced so level 2 takes about 3–4 days of play (at ~2 hours a day) and each next level a bit longer; level 20 is a long-term goal. First times give most XP early, the further kills keep later levels reachable. Worlds can choose a linear, logarithmic or power curve, their own formula of level, or a table of costs (level_curve).
Display: gains show "+N XP: first craft: Stick" (and so on) above the hotbar (in chat on the death screen); orbs count silently. At the maximum level XP stops counting.
Stacking with advancements: some first times also complete a vanilla advancement (taming a wolf: "Best Friends Forever"); both give their XP.
Separate from vanilla XP: enchanting never costs levels.
Configurable: every amount, the curve, animal kills, repeat kills, and an optional XP loss on death.

4.3 Achievements and titles¶

Achievements (Default Content datapack): the advancements screen gets a MineDnD tab (27 achievements), meant as long-term goals: exploring (25, 45 and 60 biomes; 15 kinds of structures), 20 and 30 kinds of monsters, 250 and 1000 zombies, 250 and 1000 kills with a bow or crossbow, 1000 and 10000 ores, 5000 and 10000 logs, 500 and 5000 fish, cooking 1000 and 10000 food (and eating 35 different foods), 10 and 30 kinds of potions, character level 5, 10 and 20, an ability score of 20. Some are hidden until done: dying in 30 different ways, killing 10,000 cows with arrows. They show like vanilla ones: notification, chat message, frames.
What counts: the things done for the first time are recorded in every world (also with adventure XP off), and vanilla statistics from the start, so achievements about them complete with what the player already did. Achievements that count repetitions (zombies, ores, logs, fish, cooking, kills with a bow) start counting when added.
Adventure XP: achievements give the usual 25 / 75 / 200, except those that count repetitions: those reward with titles, so grinding still isn't the way to level.
Titles: an achievement can unlock a title. The player wears one at a time (character sheet or /dnd title); it shows above their name to everyone else (never to themselves, like names) and gives a small bonus while worn:

Title	Unlocked by	While worn
The Miner	10000 ores	Fortune I on ores, with a pickaxe
Zombie Killer	1000 zombies	+10% damage against zombies
The Archer	1000 kills with a bow or crossbow	+5% damage with bows and crossbows
The Explorer	45 biomes	+10% adventure XP from new biomes and structures
The Lumberjack	10000 logs	+10% log chopping speed
The Angler	5000 fish	Luck of the Sea I
The Master Chef	10000 food cooked, 35 foods eaten	hunger drains 5% slower
The Alchemist	30 kinds of potions brewed	drunk potions last 10% longer
The Survivor (hidden)	30 ways to die	+1 heart
The Cow Slayer (hidden)	10,000 cows killed with arrows	Looting III against cows, with a bow or crossbow

A title's enchantment never adds to a real one: the higher level wins. Revoking the advancement locks the title.
Datapacks add their own achievements and titles.

5. MineDnD items¶

MineDnD items are normal items for every player: a vanilla item (the look and basic behaviour) plus MineDnD properties.

Property	What it does	Example
Stat bonus	Raises scores while the item is in a given slot	Ring of Strength: +2 STR in the off hand
Requirements	Minimum scores for the item's powers (enchantments, bonus, ability). Below them it's the plain base item	Flame Sword needs STR 12
Item ability	A power on right click, or on the V key	Wizard's Staff shoots fire bolts; Flame Sword is thrown and comes back
Enchantments, name, lore, colour…	Vanilla components	Potions with custom effects, dyed armour

A MineDnD item is never used as its plain base item in a recipe: an Apprentice Wand isn't a stick for torches, a Flame Sword can't be smelted into nuggets, and a MineDnD diamond sword can't be upgraded to netherite. Only MineDnD recipes that ask for it take it (datapacks).

5.1 Item abilities¶

An item can have one power. The kinds: - Fireball: a bolt of fire that flies straight, damages, sets on fire and can poison or slow, never breaks blocks, and fizzles in water or after 5 seconds. - Throw: a magical copy of the weapon flies out, hits the first creature, then flies back through blocks. The real weapon stays in the hand. - Boost: effects and attribute boosts on yourself for a few seconds: Speed, Haste, Resistance, mining at 200%, a longer reach, jumping higher… Some also reach the players near you. - Charged strike: your next hits within a few seconds (melee, arrows, spells) deal extra damage and can poison, burn, push back or call lightning. - Healing: restores health, can remove harmful effects (Poison, Wither…) and heal the players near you. - Burst: damages, pushes back, burns or slows the creatures around you (never players or your own pets). - Blink: teleports you to the farthest free spot where you look. - Leap: throws you where you look; no fall damage until you land. - Call lightning: strikes the creature or block you look at.

How they work: - Damage and healing can grow with an ability score, e.g. +1.5 per INT modifier point. - Costs: each use has a cooldown and can cost durability and hunger (not in creative). With an empty food bar, hunger-costing powers don't work. A blink with nowhere to go, or lightning with nothing in reach, costs nothing. - Trigger: an item in hand uses either right click (replacing its normal right click) or the V key. The key keeps the normal right click, so a bow with a power still draws. Worn armor uses the G key (the first worn piece, head to feet, whose power is ready). Both keys can be changed in Options → Controls → MineDnD. - Tooltip: shows "Right click: …", "Press V: …" or "Worn, press G: …" with the power's name, what it does for the player's current scores (damage, healing, seconds, effects), and the costs. - Boosts, charged hits and a leap's fall protection end on logout or death.

5.2 Getting items¶

Crafting: items with a recipe are made in a crafting table. Most recipes upgrade the plain base item with special ingredients; e.g. the Sun Blade is a golden sword, 4 copper ingots, 3 glowstone dust and a blaze rod. A recipe appears in the recipe book (with the "new recipes" toast) the first time the player gets its special ingredient, e.g. blaze powder for the Flame Sword; anyone who puts the right ingredients in the grid crafts it anyway.
Smithing: a datapack can add MineDnD smithing templates: in the smithing table, a template with a base item and an addition makes a MineDnD item, and the template is used up. Templates are often rare: hidden, limited, found in chests.
Imbuing: the enchanting table has a second tab, Imbue: a base (a stick, a blaze rod, a book…), a catalyst and lapis lazuli make a wand, a staff, a spellbook or an off-hand item, for experience levels like enchanting, with a recipe list. Requirement rules can ask for scores per recipe: in the Default Content, stronger items need more INT (divine ones WIS too).
Fletching: the fletching table opens like a crafting table, with two tabs. Fletching makes arrows, bows and crossbows in a 3×3 grid (vanilla's and MineDnD's), with a recipe list; Upgrade turns a bow or crossbow into a legendary one with a template, like the smithing table.
Brewing: MineDnD potions are brewed in a brewing stand from a vanilla potion and a reagent, e.g. Superior Healing is a Potion of Healing II with a ghast tear. The brewing stand has a recipe list (book button) with every potion of the world, vanilla and custom: see 7.1.
Creative tab "MineDnD": every item (hidden ones too), plus an enchanted book for each custom enchantment level.
Loot: a datapack can put MineDnD items in chests, mob drops and fishing, e.g. a rare smithing template in ancient city chests (loot).
Commands: operators use /dnd give, or /dnd catalog chests for chests with everything.
Limited items: a datapack can make an item scarce (e.g. only 3 in the world). Once that many have been crafted, brewed or found, none are left ("none left in this world") and only operators can give more (limited items).
Hidden items: a datapack can keep an item secret: it's not in the creative tab, the recipe book or the brewing stand's list until you find one. Operators and players in creative mode see them (hidden items).
Example world: the chests appear in front of the player on the first join.

5.3 An example: the Default Content items¶

The Default Content datapack uses all of the above: weapons, armour, off-hand accessories, arrows with effects, tomes, tools, potions, smithing templates and food (a few of them secret), made at every station, and food that gives a timed buff when eaten (Strength, Resistance, Night Vision…), written in its tooltip. Its choices, which your world can change or ignore: - Early game: copper, leather and stone; requirements up to 11. - Mid game: iron, emerald, quartz and obsidian; 12–13. - Legendary: e.g. the Vorpal Sword or the Hammer of Thunderbolts. Each world has only a few of them: they're found in rare chests, from mobs or fishing, or made in a smithing table with a rare template found the same way (the Hammer's template only a game master gives). Their recipes are secrets.

Every item, with its recipe drawn as a crafting grid (or what it's brewed from), is in items.

6. Enchantments¶

Enchantments are vanilla's data-driven ones, added by datapacks (enchantments). MineDnD lets their effects ask for ability scores (the minednd:ability_scores condition), and an item's own requirements switch off its enchantments below them. Levels can go past X; a pack names them in its translations (the Default Content names XI to XX).

The Default Content's enchantments, for example: - Sneak Attack: extra damage while sneaking, with DEX 13. - Stoneskin: protection, with CON 13. - Hellish Rebuke: sets attackers on fire, with CHA 12. - Stormcaller: lightning in thunderstorms, with WIS 14.

Others give attributes or tool bonuses. Each one, level by level, and where it's found (enchanting tables, loot, fishing, librarian trades), is in enchantments.

7. Requirement rules¶

Rules ask for ability scores to craft (or brew), place and/or use things. Some examples from the Default Content datapack: - crafting diamond tools needs STR 13; - an enchanting table needs INT 14 to craft, INT 12 to place, and INT 12 + WIS 10 to use; - a beacon needs WIS 14 to place; - brewing a Potion of Healing needs WIS 10, a Splash Potion of Poison WIS 12 + INT 11.

Rules check the base scores, the ones the player raised with points: bonuses from items and the title don't count. With STR 12 and a Ring of Strength (+2), the effective STR is 14, but a rule asking for STR 13 isn't met.

What players see: - Crafting a restricted recipe gives no result, and the message above the hotbar says what's needed. - Placing: the block stays in the hand. - Using: nothing happens. Blocks can still be placed against a restricted block. - Tooltips list "To craft / To brew / To place / To use" with each score green (met) or red (not met). - Creative players ignore place and use rules (configurable). Crafting rules apply to everyone. - Crafter blocks can't craft restricted recipes, since there is no player to check.

7.1 Brewing¶

Potions have tiers (Default Content datapack, changeable by other datapacks): base bottles (water, awkward, mundane, thick) are free; potions with effects need WIS 10; stronger (II) and longer versions, and splash potions, WIS 12 + INT 10; lingering potions WIS 13 + INT 12; harmful ones (poison, harming, weakness, slowness) one more INT. The four MineDnD potions need WIS 13–14 plus INT or CHA 12–14.
Who brews: the player who last put in or took out the stand's bottles, reagent or blaze powder. The stand brews a restricted potion only while that player is online and has the scores; bottles they can't brew stay as they are (the others still brew), and the message above their hotbar says what's needed. A stand filled only by hoppers doesn't brew restricted potions.
Recipe list: the brewing stand has a recipe book button. It opens a list of every potion the world can brew, with tabs (all, potions, splash, lingering, custom), a search box and a filter for what the player can brew right now. Hovering a potion shows what goes in the bottles and on top, and its requirements in green or red; clicking it shows the recipe faded in the stand's slots, and clicking a faded bottle shows how to brew that one. Greyed-out bottles need higher scores; red slots mean missing ingredients.
Drinking: rules can also restrict drinking or throwing a potion ("use"), and a MineDnD potion with its own requirements can't be drunk or thrown below them.
Custom potions keep their own name ("Potion of Superior Healing"), where vanilla would call a potion with only custom effects "Uncraftable Potion".

8. The example world¶

On the Create World screen, the MineDnD example world button (Game tab, under Commands) creates a Survival world on Hard with commands allowed, so players can set their scores. On the first join, double chests in front of the player hold every item and enchanted book of the world's datapacks, and a message explains how to start. Add the Default Content datapack under Data Packs before pressing the button; without any MineDnD content the chests stay empty and the message says how to add it.

9. Configuring a world¶

World settings (data/minednd/settings.json): ability effect rates and floors, starting score, points per level, max level, score cap, the adventure XP curve and sources, death loss, creative exemption. Every field is optional.
Content: add or override items, recipes, enchantments, requirement rules and translations. A file with the same path as one in another pack replaces it, when its pack is higher (load order).
The Default Content datapack: add it to the world for the official items, rules, achievements and titles, or only parts of it, or none (how).

/reload applies changes to items, recipes, rules, translations and settings. New or changed enchantments need the world to be reloaded (rejoin, or restart the server).

10. Multiplayer¶

The server and every player need MineDnD, Fabric API and Fabric Loader for Minecraft 26.3, with the same MineDnD version: a player with another version (or without MineDnD) can't join and is told which version to install.
The server's world needs the datapacks (e.g. the Default Content); players don't: the mod sends them the names and rules.
The modpack (.mrpack) bundles the mod, Fabric API and optional performance and visual mods (datapacks go in each world, not in the modpack).
Character data is saved with each player on the server and follows them across sessions and deaths.

11. Known limitations¶

WIS and CHA have no effect of their own yet.
Legendary items can't be obtained in survival without an operator (loot is planned).
The recipe book lists recipes the player can't craft yet; the crafting grid simply gives no result.
Restricted potions don't brew in stands filled only by hoppers, or while their brewer is offline.
A splash or lingering version of a MineDnD potion is another item with its own recipe (gunpowder or dragon's breath don't convert custom potions).

See the backlog for what's planned.