README file from
GithubDnD Character Sheet Helper
[!NOTE] DnD Character Sheet Helper is an Obsidian Plugin that brings the DnD Rulebook 5.5e (2024) right inside your Digital Character Sheet. This is not a replacement for the DnD Player's Handbook, but just a handy tool that gives you the information you might need, or you wouldn't remember on top of your mind, while playing.
[!NOTE] Player Self-Policing & Modularity: Due to the openness and modularity of this plugin, the decision was made to let players choose whatever they want without creating unnecessary filtering, restrictions, and extra overhead and complexity on the plugin's logic and database files. The user of this plugin should use the provided warnings and lack of information given in certain areas as a reminder to always read through the Player's Handbook if they need to make a choice that they do not know the implications of or don't have the contents of the option they are about to choose at the top of their heads. Again, this is not a replacement for the Player's Handbook, just a simple and easy way to create, manage, and view a player's Character Sheet.
(I'll also remind that the files are not supposed to be super complex, but easily created with the templates given below in case a user wants to make their own Custom Rulebook with Homebrewed Classes, etc.)
If there are any races or classes you want me to add to this plugin, make a feature request on GitHub.
(If any text has been written wrong please make an Issue Report on GitHub. I maintain it myself)
DnD Wizard:
You can use the Character Creation Wizard Ribbon Button on the Obsidian sidebar (sword icon) or the command palette on an open note to create your new DnD Character Sheet, just fill all the availabe fields and options in the wizard and your Character Sheet will be created for you; just be sure to stick to the rules of the Player's Handbook and read throug it to know which options you want to choose. Everything will be placed in appropriate frontmatter variuables (file properties) that then can be fetched by the rest of the code blocks in the Character Sheet Template provided by the creation wizard.
For creating a Character Sheet on your own, you may use one, or all of the code blocks below to assist you into managing your chracter:
DnD Healthbar:
A Health-bar widget with integrated Hit Dice, Saving Throws, Exhaustion (1–6), and the ability to add Temporary Hit Points.
A Sample of the Code Block looks like this:
```dnd-health
health: $num$
currentHealth: $num$
hitDice: $array$ // [ "<HitDie>", <SpentCount> ] (or $string$ "<HitDie>")
level: $num$
exhaustion: $num$ // <optional, 0-6>
```
DnD Information:
There are two modes to this plugin, one of them shows information related to your character and anothe one on combat, with each one having different variables that you may need to fill in.
A Sample of the Code Block looks like this:
```dnd-info
mode: character
race: $array$
raceLineage: $array$
class: $array$
subclass: $array$
background: $string$
backgroundFeat: $string$
level: $num$
languages: $array$
```
or this:
```dnd-info
mode: combat
armor: $string$
armorAc: $num$
armorAcBonus: $num$
armorAcMod: $num$
initiativeMod: $num$ // <optional>
attackStat: $string$
attackRollMod: $num$
speed: $num$
speedMod: $num$
speedSublabel: $string$
```
DnD Ability Scores:
An Ability Scores widget that displays Scores, Modifiers, Saving Throw Proficiencies, and supports Homebrew Abilities with the extras variable.
A Sample of the Code Block looks like this:
```dnd-abilities
strength: $num$
dexterity: $num$
constitution: $num$
intelligence: $num$
wisdom: $num$
charisma: $num$
proficiencies: $array$
extras: $array$ //optional
```
The extras variables allows you to add your own homebrew abilities right besides the standard DnD ones and follows this structure:
[ [ "<"Ability-Name">", "<"Ability-Abbreviation">", "<"Ability-Score">", "<"Saving-Throw-Modifier">"], [<"second Ability">], [<"third Ability">] ]
DnD Skills:
A Simple widget that displays your character's skills, proficienies, half-proficiencies and experties on those skills, with support for bonuses on certain items and a Tool Proficiencies badge.
A Sample of the Code Block looks like this:
```dnd-skills
proficiencies: $array$
expertise: $array$
half_proficiencies: $array$
tools: $array$ // <optional>
bonuses: $array$
```
The proficiencies variable array structure looks like this: [ ["<Skill>", "<class/background/extra>"] ], to distinguish to the rest of the plugin the origins of that proficiency. The bonuses variable holds bonuses that items may grant and the structure is as follows: [["<Item-Name>","<Skill>>","<Value-to-Add>"]]
DnD Controls:
This is an array of buttons that control various parts of the character sheet, mainly changing frontmatter (file properties) values that then correspond to changes in the character sheet. The buttons are: Level Up, Equip Items, Inventory, Manage Character, and Spellbook (which will only appear if the DnD_spellcastingAbility frontmatter variable is populated, and updates automatically whenever DnD_spellcastingAbility is added or changed via Level Up or Manage Character).
A Sample of the Code Block looks like this:
```dnd-controls
align: right/center/right-up/right-down // <optional>
```
DnD Character Features:
Given the appropriate variables and values this plugin can give you useful information of your character directly inside your Obsidian Note. It displays all the Action related Features from your Class (with Multi-class support), Subclass, Race Traits, Background Feat and Extra Feats added at your own disposal.
A Sample of the Code Block looks like this:
```dnd-features
level: $num$
class: $array$
classLevels: $array$
subclass: $array$
classChoices: $array$
race: $string$
raceLineage: $string$
background: $array$
extraFeats: $array$
featureUses: $array$
weaponMastery: $array$
hide: $array$
```
Any of the variables (except for level) can be omitted and only the variables with a value will be used and displayed. Sections with no features to display (such as subclass before your class unlocks one) will automatically hide themselves.
The variable classLevels is used when you have multiple classes on your character and the plugin needs to know how many levels each class has. The order of the levels should be the same as the class order.
The variable classChoices stores class-specific feature selections (such as Warlock Eldritch Invocations, Fighter Fighting Styles, Sorcerer Metamagic, or Blood Hunter Blood Curses & Crimson Rites) grouped by router using the structure: [ [ "<Router-Filename>", [ [ "<Choice-Filename>", "<Level-Gained>" ], ... ] ], ... ].
The variable extraFeats (linked to frontmatter.DnD_extraFeats on character sheets) stores additional Feats gained outside of Backgrounds or automatic class grants, and can be added or removed anytime after character creation via Manage Character -> Feats.
Write down a Feature's name as it appears on the screen inside the variable hide (or manage it via the Manage Character button) to hide it from view.
The variable featureUses savesthe state of the checkboxes on each Class or Subclass Feature, Race Trait and Feat of the character wit this structure: [ [ "<Feature's-Name>", "<Available-Uses>", "<Expended-Uses>"], ... ]
The variable weaponMastery connects to frontmatter.DnD_weaponMastery using the structure [ "<Number-of-Weapons-from-JSON>", [ "<Filename-of-Weapon>", "<Filename-of-Weapon>", ... ] ]. Whenever dnd-features renders, it automatically synchronizes index 0 (available mastery slots unlocked from class/subclass features and feats) while preserving index 1 (the array of mastered weapon filenames).
DnD Spells:
A Widget that uses a certain array strcuture to display DnD spells on your Obsidian Note.
A Sample of the Code Block looks like this:
```dnd-spells
spellcastingAbility: $string$
spellPools: $array$ // <optional>
spells: $array$
preparedSpells: $array$
spellSlots: $array$
```
The spells and preparedSpells variables follow this structure: [ [["<Cantrip-1>", "<Cantrip-2>"],"0"], [["<Level-1-Spell>", "<Level-2-Spell>"],"1"] ], spellPools accepts an array of spell pool router filenames (e.g. ["druid-spells", "elf-cantrips"], synced via frontmatter.DnD_spellPools on character sheets so Spellbook opens all granted pools with a pool switcher), and spellSlots follows [ ["<Max-Slots>", "<Used-Slots>"], ... ]. Class/Subclass spellcasting ability takes priority over Race/Lineage traits, can be overridden anytime in Manage Character -> Attack & Weapons, and racial spells are tagged Innate (excluded from class cantrip and prepared spell limits). The Spellbook preview also shows which Classes can cast each spell.
[!TIP] Click or tap on a spell card to view its full description.
DnD Character Inventory:
An easy way to manage your character's inventory including. There is a section for managing your Gold, a section for Weapon / Armor, a section for starter items and a section for extra items added in later on.
A Sample of the Code Block looks like this:
```dnd-inventory
weapon: $string$
weaponDamage: $string$
weaponMastery: $array$ <optional>
armor: $string$
armorAc: $string$
class: $string$
classEquipment: $string$
classChosenItems: $array$ <optional>
background: $string$
backgroundEquipment: $string$
backgroundChosenItems: $array$ <optional>
starterEquipment: $array$
inventoryItems: $array$
customItems: $array$
wealthAdded:
wealthSpent:
```
Weapons and Amor related varibales are optional and when not set that section will not be made visible.
The Gold section is always visible and will have as base rate the gold provided by the class + background. There after, you can use the Add and Spend buttons that will change the Gold amount displayed. When using the aforementioned buttons the ammount added/spent will be as properties inside your character's note that then will be used to calculate the Total Gold you currently have.
The Backpack section is also always visible and wil be automatically populated with the items given to your character from their class and background. If given the choice between items from your class or background you will have to use the class-chosen-items and background-chosen-items. You can get more information on each item by hovering your cursor over it.
starterEquipment/inventoryItems structure: [ ["<item-filename>", "<quantity>", "<show: true/false>"], ... ]
customItems structure: [ ["<Name>", "<quantity>", "<show: true/false>", "<weight>", "<cost>", "<type>", "<description>"], ... ]
customItems <cost> is written with its currency, e.g. "50 GP", "5 SP", "2 PP" or "5 CP" (a bare number is treated as GP).
[!TIP] The aforementioned variables are used to select an Artisan's Tool, a Musical Instrument, or a Gaming Set depeding on what's provided by the class or background. For more information on your choices always look through the actual DnD Player's Handbook.
Rules Block:
A way to add Custom Rules to your Character Sheet.
A Sample of the Code Block looks like this:
```dnd-rules
rules: $array$
```
Critical Role:
I have also added Critcal Role's Campaign 4 Desperate Measures mechanic. I just thought it was an interesting mechanic and I've used it in my campaigns ever since I found out about it. To use it you just add Desperate Measures into the Rules Block
Extra Features:
- Code Blocks have frontmatter support by using the key-word "frontmatter." + a note property's name.
Settings Menu:
-
Class & Subclass combination toggle
-
Custom Rulebook folder path inside your Obsidian Vault for Homebrewed DnD.
There's also a toggle to have the Custom Rulebook be prioritied
- Theme Engine
Not anything special, just some basic custom color pallete pane for you to change any color to your liking.
Homebrew:
This plugin also supports custom rules by adding the path of your custom Rulebook that is inside your Obsidian Vault. This is the folder structure used and what the plugin expects:
rulebook/
├── classes/
│ └── <add your custom classes & subclasses>
├────── classChoices/
│ ├── classRouterFiles/
│ │ └── <add your custom class choice routers>
│ └── <add your custom class choices>
├── feats/
│ ├── featRouters/
│ │ ├── <add your custom feat routers>
│ └── <add your custom feats>
├── items/
│ └── <add your custom items>
├── markdown/
│ └── <add your custom markdown>
├── races/
│ ├── racialSpells/
│ │ └── <add your custom racial spell routers>
│ └── <add your custom races>
├── rules/
│ └── <add your custom rules>
├── spells/
│ ├── spellPools/
│ │ └── <add your custom spell pool routers>
│ └── <add your custom spells>
├── backgrounds.json
├── classes.json
├── items.json
├── races.json
├── rules.json
└── weapon-masteries.json
The backgrounds.json, classes.json and races.json work as router files to the specific feat, class, or race JSON is needed for better modularity.
[!TIP] All text fields support the markdown format with some custom spacing so that information can more easily fit inside the UI. Use
\nfor line-break and\tfor tabs as normal.
The structure of each JSON file is as follows:
- classes/races/items/rules.json:
{
"<Class/Race/Item/Rule/Feat/Spell_Filename>": "<Class/Race/Item/Rule/Feat/Spell_Display_Name>"
}
- backgrounds.json:
{
"<Background>": {
"feat": "<Feat_Given>",
"abilityBonusPool": ["<List_of_Abilities>"],
"skills": ["<List_of_Skills>"],
"startingEquipment": {
"A": {
"items": {
"<item>": 0,
"<type+|>": 0
}, "gold": 0
},
"B": { "items": {}, "gold": 0 }
}
}
}
<spell-pool-name>.json(insiderulebook/spells/spellPools/):
{
"<Spell-Slot-Level>": {
"<Filename>": "<Spell-Name>",
}
}
Cantrips are on "Level 0" and the rest of the Spell Levels are as normal.
- class.json:
{
"class": "<Class_Name>",
"hitDice": "<Hit_Dice>",
"savingThroughProf": ["<List_of_Abilities>"],
"proficiencyBonus": ["<Level_1_Bonus>", "..."], // <optional>
"scalingDice": ["<Level_1_Die>", "..."], // <optional>
"skillsPool": [["<List_of_Skills>"], <Number_of_Skills_that_can_be_chosen> ],
"startingEquipment": {
"A": {
"items": {
"<Item-File-Name>": 0,
"<Item-File-Name>": 0,
"musical-instrument|": 0, // <optional_DnD_item_type>
"artisans-tool|musical-instrument": 0, // <optional_DnD_multiple_items_w/_type>
"<item_type|>" : 0 // <optional_homebrew_item_type>
}, "gold": 0
},
"B": { "items": {}, "gold": 0 }
},
"spellcastingAbilities": [ "<Spellcasting-Ability>" ], // <optional>
"spellsPool": "<Spells-List-Filename>", // <optional>
"spellcasting": {
"<Level>": { "cantrips": <num>, "preparedSpells": <num>, "slots": [0, 0, 0, 0, 0, 0, 0, 0, 0] }
}, // <optional>
"features": {
"<Level>": [
{
"name": "<Feature_Name>",
"description": "<Feature_Description>",
"badge": "<Custom_Badge_Text_Inplace_of_Level>", // <optional>
"classChoices": ["<Choice-Router-Filename>"], // <optional>
"grantedExpertise": [["<Skills-Pool>"], <num>], // <optional>
"grantedSubclasses": "<Subclasses-Filename>", // <optional>
"grantedFeats": ["<ability-score-improvement>", "<Feat_Name>", "<Feat_Router_Filename>"], // <optional>
"uses": ["<Number-of-Uses>", "<short/long>" ], // <optional>
"speedMod": <num>, // <optional>
"initiativeMod": "<num | proficiencyBonus | Ability-Name>", // <optional>
"weaponMastery": <num>, // <optional>
"hide": true // <optional>
}
]
}
}
<class>-subclasses.json: Subclasses can also define spellcasting independently from their base class (e.g. Eldritch Knight, Arcane Trickster, or Order of the Profane Soul), unlocking the Spellbook only for characters who pick that archetype:
{
"<Subclass-Name>": {
"spellcastingAbilities": [ "<Spellcasting-Ability>" ], // <optional>
"spellsPool": "<Spell-Pool-Router-Filename>", // <optional>
"spellcasting": {
"<Level>": { "cantrips": <num>, "preparedSpells": <num>, "slots": [0, 0, 0, 0, 0, 0, 0, 0, 0] }
}, // <optional>
"<Level>": [
{
"name": "<Feature_Name>",
"description": "<Feature_Description>"
}
]
}
}
Sometimes DnD classes or backgrounds offer a choice of an item category (like any Musical Instrument or Artisan's Tool) rather than a specific item. To handle this you can use items' Type instead of a single item's filename
By adding a pipe character (|) to an item key in your class.json or backgrounds.json (e.g: "musical-instrument|": 1 or "artisans-tool|musical-instrument": 1), you tell the plugin to wait for the player's choice. The plugin will automatically scan the player's class-chosen-items or background-chosen-items variables in their note, find an item whose "type" matches the requirement, and seamlessly add it to their inventory.
The grantedSubclases variable grants the player the Sublcasses that are included in the json file entered and are given to the player on the level it is placed at.
The grantedFeats variable gives the player feat choices or automatic feats when that level is reached. The array can contain:
- Specific feat filenames (e.g.
"actor","alert"): directly grants the feat if only one is listed, or offers a choice between them. - Router filenames inside
feats/featRouters/(e.g."general-feats","epic-boon-feats","origin-feats"): provides a secondary dropdown allowing the player to pick any feat within that category. "ability-score-improvement": triggers the standard Ability Score Improvement milestone (+2 to one stat or +1 to two stats) in the Level Up modal.
The uses variable sets how many uses this feature has, and when used checkboxes will appear at the top right of that feature's line acording to the value it was set. For the amount of uses it accepts single numbers and in string it accepts math (+, -,, *, /) and will also automatically imput the value of a core DnD ability.
The scalingDice array stores level-scaling dice for a class (such as a Monk's Martial Arts die) and is used when the Unarmed Strike weapon is equipped.
To give a class a custom Unarmored Defense AC calculation, include a hidden feature named "Unarmored Defense" ("hide": true) at the level it is unlocked with its "description" set to the AC formula (for example, "10+dexterity+wisdom" for Monk or "10+dexterity+constitution" for Barbarian).
The speedMod variable on a class/subclass feature or feat defines bonus movement speed (in feet) that contributes to the character's total walking speed. Speed bonuses are resolved deterministically:
-
Scaling Features (e.g. Monk Unarmored Movement): Features sharing the same feature name scale by replacement—reaching a higher level tier replaces earlier values rather than stacking cumulatively (e.g., Monk Level 2: +10 ft, Level 6: +15 ft, Level 10: +20 ft, Level 14: +25 ft, Level 18: +30 ft).
-
Armor Condition Enforcement: Unarmored Movement bonuses automatically disable when armor is worn; Barbarian Fast Movement or Ranger Roving bonuses automatically disable if heavy armor is worn. Feat speed bonuses apply regardless of armor.
-
Multiclassing & Feats: Different class features (e.g. Barbarian Fast Movement + Ranger Roving) and Feats (e.g. Speedy +10 ft, Epic Boon of Speed +30 ft) stack additively.
-
Custom & Gear Modifiers: Manual adjustments or magic item bonuses can be managed in the "Speed" tab of Manage Character or directly in the note's
DnD_customSpeedModfrontmatter property. The overall combined bonus is saved toDnD_speedModand displayed alongside base speed indnd-info(mode: combat). -
$class-subclasses.json:
{
"<Subclass_Name>": {
"<Level>": [
{
"name": "<Feature_Name>",
"description": "<Feature_Description>"
}
]
}
}
- feat.json:
{
"name": "<Feat_Name>",
"description": "<Feat_Description>",
"uses": ["<Number-of-Uses>", "<short/long>" ], // <optional>
"speedMod": <num>, // <optional>
"initiativeMod": "<num | proficiencyBonus | Ability-Name>", // <optional>
"weaponMastery": <num>, // <optional>
"improveAbility": [ [ "<Ability-to-Improve>", <value>, <maxCap> ], ... ], // <optional>
"proficiencySavingThrow": "<improvedAbility | Ability-Name | Array>", // <optional>
"grantedExpertise": [ [ "<skill_pool>" ], <count> ] // <optional>
}
The improveAbility array defines ability score increases granted by this feat. It accepts 3-element tuples [ [ "<Ability-to-Improve>", <value>, <maxCap> ], ... ]:
<Ability-to-Improve>: lowercase ability name (e.g."strength"), multiple choice joined with|(e.g."strength|dexterity"or"intelligence|wisdom|charisma"), or"any".<value>: integer bonus to add (typically1).<maxCap>: maximum score cap for the ability (typically20for General Feats or30for Epic Boons).
The proficiencySavingThrow property grants saving throw proficiency. It accepts "improvedAbility" (automatically grants proficiency in whichever ability was chosen in improveAbility, disabling abilities the character is already proficient in during Level Up), an explicit ability string (e.g. "constitution"), or an array of mixed entries (e.g. ["improvedAbility", "wisdom"]).
The grantedExpertise property grants expertise in skill proficiencies. It accepts a 2-element tuple [ [ "<skill_pool>" ], <count> ] (e.g. [[], 1] allows choosing 1 skill from any currently known skill proficiency lacking expertise).
The uses variable sets how many uses this feature has, and when used checkboxes will appear at the top right of that feature's line acording to the value it was set. For the amount of uses it accepts single numbers and in string it accepts math (+, -,, *, /) and will also automatically imput the value of a core DnD ability.
- race.json:
{
"traits": [
{
"name": "<Trait_Name>",
"description": "<Trait_Description>",
"lineage": "Lineage_Name", // <optional>
"uses": ["<Number-of-Uses>", "<short/long>" ], // <optional>
"grantedFeats": ["<Feat_Filename>", "<Feat_Router_Filename>"], // <optional>
"initiativeMod": "<num | proficiencyBonus | Ability-Name>", // <optional>
"spellcastingAbilities": ["Intelligence", "Wisdom", "Charisma"], // <optional>
"racialSpells": "<racial-spells-router-filename>", // <optional, inside races/racialSpells/>
"spellsPool": "<extra-spell-pool-filename>" // <optional, inside spells/spellPools/>
}
]
}
The lineage variable in the race.json is a Flag, making it so that this trait will appear if that and the race-lineage variable in the code block have the same value, while also swapping out the "Trait" badge for a "Lineage" badge.
The grantedFeats variable works the same as on Class Features: a single feat filename directly grants that feat automatically, while multiple entries and/or feat router filenames from feats/featRouters/ (such as ["skilled", "origin-feats"] on Human's Versatile trait) prompt the player to pick their feat during Step 3: Features Options of Character Creation.
The uses variable sets how many uses this feature has, and when used checkboxes will appear at the top right of that feature's line acording to the value it was set. For the amount of uses it accepts single numbers and in string it accepts math (+, -,, *, /) and will also automatically imput the value of a core DnD ability.
Racial spell traits can specify spellcastingAbilities (used as fallback if the character's class/subclass grants no spellcasting ability), racialSpells pointing to a router in rulebook/races/racialSpells/<file>.json ({ "<Lineage or base>": { "<CharLevel>": { "<SpellLevel>": { "<spell-slug>": "<Spell Name>" } } } }), and an optional spellsPool router filename added to DnD_spellPools (such as elf-cantrips for High Elf's Wizard cantrip list).
- item.json:
{
"name": "<Item's_name>",
"type": "<weapon/armor/gear/artisans-tool/musical-instrument/gaming-set>",
"description": "<Item's_Description>",
"weight": 0,
"damage": "<Damage_Dice+Damage_Type>", // <optional>
"mastery": "<Weapon_Mastery_Property>", // <optional>
"ac": "<Armor's_Base_AC>", // <optional>
"category": "<Light/Medium/Heavy>",
"cost": "<Amount> <PP/GP/SP/CP>" // e.g. "50 GP", "5 SP", "5 CP"
}
- weapon-masteries.json:
{
"<weapon-mastery>": "<description>"
}
The weapon-masteries.json file defines all valid Weapon Mastery properties and their full descriptions. When an item has a "mastery" field matching a key in weapon-masteries.json, its mastery description is shown in the Item Info and Inventory modals, and on the equipped weapon card if the weapon's filename is listed in DnD_weaponMastery[1]. If an item's "mastery" cannot be found in weapon-masteries.json, the plugin will not display it. The plugin also automatically generates markdown/weapon-masteries.md from weapon-masteries.json whenever the plugin loads or detects a change in the Custom Rulebook.
- spell.json:
{
"name": "<Name>",
"level": <1/2/3>,
"school": "<Abjuration/Transmutation>",
"castingTime": "<Action/Bonus Action>",
"range": "<X feet/Self>",
"components": ["V", "S", "M"],
"materials": "<Material Description>",
"duration": "<Instantaneous/1 hour>",
"concentration": false,
"ritual": false,
"classes": "<Classes-that-can-Cast>",
"description": "<Description>"
}
- rule.json:
{
"name": "Desperate Measures",
"rules": [
{
"name": "<Rule_Section_Name>",
"description": "<Rule_Section_Description>",
"badge": "<Custom_Badge_Text>" // <optional>
}
]
}
Markdown:
If you place some special markdown files inside the markdown folder, you can embed them right into the code block's text with this file link: [<Anchor-Text>](note:<Markdown-Filname>)
Acknowledgements:
This plugin was made because of my want to have a comfortable Character Sheet in Obsidian without hassle. I first stumbled upon hay-kot's Obsidian DnD UI Toolkit and was the inspiration for the color pallete and the reason I started this project, because if it wasn't for his plugin and making it possible to have some of the crucial DnD Character Sheet elements inside an Obsidian Note, I would have never gone through the trouble of making my own plugin to expand upon it.