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.

Reference pages: - Commands: every /dnd command. - Datapacks: datapack formats and world settings. - Default content: every built-in item, enchantment and rule, 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 (item ability), 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, by hand or with MineDnD Studio (local worlds and online servers)

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 (max 30). All effects use it.
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
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
WIS, CHA	No direct effect yet; they count for requirements	See the backlog

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.

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)¶

Off by default: players earn no adventure XP by playing; the operator (the DM) gives levels and XP with /dnd level add and /dnd xp add, which always work. A world turns it on with "experience": { "enabled": true } in its settings (or the editor's World settings form). Vanilla XP is never affected: orbs, enchanting and the XP bar work as usual either way.

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)
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: 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, 500 and 3000 ores, 1000 and 5000 logs, 100 and 500 fish, cooking 200 and 1000 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	3000 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	5000 logs	+10% log chopping speed
The Angler	500 fish	Luck of the Sea I
The Master Chef	1000 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

5.1 Item abilities¶

There are two kinds: - Fireball: a bolt of fire that flies straight, damages and sets on fire, 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.

How they work: - Damage 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. - Trigger: an item 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. - Tooltip: shows "Right click: Fireball" or "Press V: …", the damage for the player's current scores, and the costs.

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.
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, plus an enchanted book for each custom enchantment level.
Commands: operators use /dnd give, or /dnd catalog chests for chests with everything.
Example world: the chests appear in front of the player on the first join.

5.3 The built-in items¶

70 items: weapons, armour, off-hand accessories, tomes, tools, potions. 57 of them can be made: 53 in a crafting table, the 4 potions in a brewing stand. - 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. These have no recipe; for now they come only from commands, the creative tab and the example world chests.

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

6. Enchantments¶

The built-in pack adds 24 enchantments. Some only work with enough ability, e.g.: - 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, is in enchantments. 12 come from enchanting tables. All 24 can be found in loot chests, fishing and librarian trades, so the treasure ones are found only there.

7. Requirement rules¶

Rules ask for ability scores to craft (or brew), place and/or use things. Some built-in examples: - 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.

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 (built-in, changeable by 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, and a message explains how to start.

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 a built-in one replaces it.
Built-in content: it's a datapack ("MineDnD Default Content"), on in every world; /datapack disable "minednd:default_content" turns it off.
MineDnD Studio: a desktop app (Windows, macOS, Linux) that edits all of this with forms, wizards and explanations, on a local world or an online server; it shows the built-in content read-only and copies entries into your own pack.

/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 modpack (.mrpack) bundles everything, plus optional performance and visual mods.
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.