YAML Reference for D&D Character Sheets

Introduction

This document specifies what you can put in a YAML character sheet. Most of the document is taken up with an alphabetical list of all the keys, but this reference also provides some details about what you can put in your text, and it mentions some keys that are special.

As you perused the guide, you will see examples both with and without quotation marks. YAML’s rules for quotation are actually fairly involved, but for the character sheets, most quotation marks are optional.

A couple of other notes:

What you can write: Beyond plain text

YAML handles plain text well and does not hit you with a ton of bureaucracy (special quote marks and so on). But sometimes you want more than plain text. And I provide a hook: the back end exploits the full power of the LaTeX typesetting system. LaTeX can be intimidating, but it is very powerful, and it provides not only traditional typesetting but also graphic-design tools. (Much of the graphic design has been done using the TikZ package.)

You can benefit from LaTeX without being an expert. You just need to know that the text that you write is interpreted by LaTeX, and that LaTeX treats the \, {, and } characters specially. (If you are an expert, you will also want to know that LaTeX’s other special characters are escaped by the back end.)

The \ character marks a LaTeX macro, and you will sometimes want to use macros in your text:

To help you write numbers like spell attack modifiers or spell DCs, which may change as your character evolves, I have defined a handful of custom macros In any text field you can write any of the following:

Special YAML keys

Keys for changing font size

Some key names can have ” FONT” appended to control the font used when rendering the named section in the character sheet. The value should be a LaTeX font command, as in these examples:

The sections that support FONT keys are ATTACKS, FEATURES, MAGIC, EQUIPMENT, and PROFICIENCIES

If a font-size specification seems not to be having any effect, there is a bug in my code. Open a Github issue.

Keys with calculated values

The following keys are automatically calculated rendering engine. Unless you want to override the calculated values, do not include them in a YAML file:

Other calculated keys may be included, but when they are absent, the rendering engine calculates them:

Alphabetical list of keys

Each key is described briefly; most are followed by examples. Unless otherwise specified, a key expects to be associated with text.

ALIGNMENT

A string.

AGE

Could be a number or just a string describing a life stage. The age is displayed in parentheses after the character’s name.

ARMOR CLASS

A number, which is displayed prominently in a shield-shaped box.

ATTACKS

A list of attack possibilities, each of which is described by a table with these fields:

If AMMO COUNT is given, AMMO TYPE must also be given.

Examples:

ATTACKS:
  - NAME: Shortsword
    ATTACK: "+4"
    DAMAGE: "1d6+2"
    TYPE: piercing
    RANGE: "5 ft."
    # No ammo fields for melee weapons

  - NAME: Light Crossbow
    ATTACK: "+4"
    DAMAGE: "1d8+2"
    TYPE: piercing
    RANGE: "80/320 ft."
    AMMO TYPE: "bolts"
    AMMO COUNT: 20
    NOTES: "Loading property"

  - NAME: Dagger (thrown)
    ATTACK: "+4"
    DAMAGE: "1d4+2"
    TYPE: piercing
    RANGE: "20/60 ft."
    AMMO COUNT: 3
    AMMO TYPE: daggers

  - NAME: Sling
    ATTACK: "+4"
    DAMAGE: "1d4+2"
    TYPE: bludgeoning
    RANGE: "30/120 ft."
    AMMO TYPE: "bullets"
    # Count omitted when not tracked

BACKGROUND

A string that is displayed in the character-information section.

CANTRIPS KNOWN

A number that may be used for cantrip tracking, checked against the cantrips listed in MAGIC. May appear only on the GM’s sheet. Accepts the same formula syntax as SPELLS KNOWN (see below).

CHA

The Charisma ability score, a number, as in CHA: 15.

CHA SAVING (calculated by the system)

If the character CLASS indicates saving-throw proficiency in Charisma, the rendering engine defines CHA SAVING to be true. Otherwise CHA SAVING is left undefined.

CHARACTER NAME

The character’s name, which is displayed prominently.

CLASS

The character’s class. It is used to determine saving-throw proficiencies, and it is displayed.

COLOR

A Boolean; if true, the rendering engine uses colored backgrounds in those templates that support color. (The colored backgrounds are primarily a teaching tool.) Defaults to true.

CON

The Constitution ability score, a number, as in CON: 15.

CON SAVING (calculated by the system)

If the character CLASS indicates saving-throw proficiency in Constitution, the rendering engine defines CON SAVING to be true. Otherwise CON SAVING is left undefined.

CP

Number of copper pieces in the character’s inventory. May also be left blank.

CURRENT HIT POINTS

Not actually used. It changes too frequently.

DESCRIPTION

A physical description of the character.

DEX

The Dexterity ability score, a number, as in DEX: 15.

DEX SAVING (calculated by the system)

If the character CLASS indicates saving-throw proficiency in Dexterity, the rendering engine defines DEX SAVING to be true. Otherwise DEX SAVING is left undefined.

DOCUMENT FONT

Controls the overall scale of fonts used to render the character sheet. May be 10pt, 11pt, or 12pt.

DOMAIN SPELLS

The number of spells a Cleric gets from their domain.

EP

Number of electrum pieces in the character’s inventory. May also be left blank.

Warning: The templates I made don’t show electrum pieces.

EQUIPMENT

(Multicolumn?)

May be a simple list of items, or a list of categories with items in each category. The categories are useful if the party is using the Alexandrian system of encumbrance by stones to track encumbrance.

The categories are as follows:

The simple list style looks like this:

EQUIPMENT:
  - "Leather Armor"
  - "Shortsword"
  - "Light Crossbow"
  - "Backpack"
  - "Bedroll"

The categorized style looks like this:

EQUIPMENT:
  NORMAL WEAPONS:
    - "Longsword"
    - "Shortbow"
  LIGHT ARMOR:
    - "Leather Armor"
  SLOTTED ITEMS:
    - "Arrows (20)"
    - "Rations (10 days)"
  SMALL ITEMS:
    - "Clothes"
  HEAVY ITEMS:
    - "Anvil (8 stones)"

It is also possible to code the structured equipment list using a list of strings. This interpretation is used when rendering a structured equipment list on the web form. Each line can optionally start with a category name followed by a colon, then the item name:

You can mix both styles in the same equipment list (see the Quick-Start Guide. Category names are case-insensitive and can be singular or plural (e.g., “light armor” or “light armors”). The rendering engine maps these forms to the standard category names.

For experts: the list-of-strings format, with one string per line, is defined by this EBNF grammar:

<equipment> ::= { [<category>:] <item> NL
                | <category>: NL {- <item> NL}
                }
<category>  ::= light armor | medium armor | ...
             |  <category>s

EQUIPMENT COLS

The number of columns used to display equipment in the equipment section.

Depending on the template, the default value may be one column or two.

EQUIPMENT LEFT

A Boolean that tells the default layout to put the equipment list in the left column, even if there is no magic. (With magic, the default is to use both columns for equipment.)

EXPERIENCE POINTS

For display, usually suggesting what’s needed to reach the next level.

FEATURES

A list of class features, racial traits, and so on. Each feature is a structured key-value table, which must have at least two keys:

The description is the default description, but the feature may also include an abbrev description, which is as short as possible, or a long description, which may contain more verbiage.

In addition, each feature may be labeled with any or all of the following properties:

If a feature has the attack, save, or enemy property, that feature will be displayed using an “attack color.” (Provided the template supports colors.) The other properties are used by the gmsheet and gmspells scripts in this repository, which create summaries for the Game Master to refer to at the table.

A very similar format is also used in the MAGIC list.

FEATURES:
  - name: Cunning Action
    description: Dash, Disengage, or Hide as a bonus action.
    abbrev: Bonus Dash, Disengage, or Hide
    bonus: true

  - name: Sneak Attack
    description: Add 1d6 damage to finesse or ranged weapon.  Needs Advantage,
      or straight roll w/target threatened.  1/turn.
    abbrev: >-
      +1d6 dmg finesse, ranged. Need Adv or target threatened (no Dis). 1/turn.
    attack: true

  - name: "Fey Ancestry"
    description: "You have advantage to save against charms and you can't be magically put to sleep."

  - name: "Bardic Inspiration 2/day"
    description: "Grant an ally within 60 ft. +1d6 inspiration they can use on any one check within 10 minutes."

FEATURES SPACE

In the default layout, an amount of vertical space that is placed after each feature in the FEATURES section. Defaults to 3pt.

GM NOTES

These private notes for the game master may be used by the gmsheet script.

GP

Number of gold pieces in the character’s inventory. May also be left blank.

HIT DICE

A string showing the type of the character’s hit dice.

INITIATIVE

The character’s initiative modifier.

INT

The Intelligence ability score, a number, as in INT: 15.

INT SAVING (calculated by the system)

If the character CLASS indicates saving-throw proficiency in Intelligence, the rendering engine defines INT SAVING to be true. Otherwise INT SAVING is left undefined.

LAYOUT

An optional key recommending a layout template. The system currently supports three templates:

LEVEL

A number giving the character’s level. The number is used to calculate the character’s proficiency bonus.

MAGIC

A list of spells, separated by level markers. A level marker is a table with a level key and possibly a slots key. The slots key is forbidden for level 0 spells (cantrips) and mandatory for spells of level 1 and up. Another form of level marker has key acquired at level and a number indicating at what level the spell is acquired. This number provides a reminder in the YAML file, but at present it serves no other function.

A spell is a structured key-value table, which must have at least two keys:

The description is the default description, but the spell may also include an abbrev description, which is as short as possible, or a long description, which may contain more verbiage.

In addition, each spell may be labeled with any or all of the following properties:

If a spell has the attack, save, or enemy property, that spell will be displayed using an “attack color.” (Provided the template supports colors.) The other properties are used by the gmsheet and gmspells scripts in this repository, which create summaries for the Game Master to refer to at the table.

A very similar format is also used in the FEATURES list.

MAGIC:
  - level: 0
  - name: "Fire Bolt"
    description: "Make a ranged spell attack (+5) to deal 1d10 fire damage"

  - level: 1
    slots: 2

  - name: "Magic Missile"
    description: "Create 3 darts that each deal 1d4+1 force damage"

  - name: Cure Wounds
    components: VS
    description: A touched creature regains 1d8\psam HP.

  - name: Thorn Whip
    components: VSM
    material: the stem of a plant with thorns
    description: >-
        A vine-like whip lashes at a creature within 30 ft.  Melee spell attack\psatk,
        1d6 piercing damage.  When hitting Large or smaller,
        pull up to 10 feet toward yourself.
    attack: true
    abbrev: >-
      Melee spell attack 30 ft, 1d6 pierce.  Pull \(\le\)Large 10 ft.

  - name: Shield
    description: >-
      Reaction; +5 AC until start of next turn, including triggering attack.
      No damage from \emph{magic missile}.
    reaction: true
    duration: 1 round

MAGIC SEPARATE

If true or similar value, the rendering engine puts the magic section on its own page. Otherwise the magic section goes with the other sections. (This feature is not yet implemented.)

MAX HP

The character’s maximum hit points, which is displayed prominently in a box.

MOTIVATION

An optional, short string displayed in italic text near the character’s name.

OTHER

You can put anything you want here.

PASSIVE PERCEPTION

May be displayed with the character’s other information, and is also used on the GM’s sheet. This key must be included whenever WIS (Wisdom) is present, because I’m not completely confident that the calculated value is correct.

PLAYER NAME

Name of the person playing the character.

PP

Number of platinum pieces in the character’s inventory. May also be left blank.

PREGENERATED

A Boolean field that marks pregenerated characters. Some templates will label such characters.

PROFICIENCIES

A list of the character’s skill, tool, language, and other proficiencies. A completely blank list element is interpreted as a separator between groups of related proficiencies. (Only the first two groups are shown on the GM’s summary sheet.) It is also permissible to nest proficiencies by including a table that maps a category to a list of proficiencies. Any category is permissible.

See also SECONDARY PROFICIENCIES.

PROFICIENCIES:
  - "Acrobatics"
  - "Arcana"
  - 
  - Dwarvish
  - "Language (Common)"
  - "Languages: Elvish"  # alternate format
  - 
  - "Simple Weapons"
  - "All Armor"
  -
  - Tools:
      - Thieves' Tools
      - Herbalism Kit

PROFICIENCY BONUS

The character’s proficiency bonus, which is displayed near the proficiencies. This value can be calculated by the system.

RACE

Character’s race and (optionally) subrace.

SECONDARY PROFICIENCIES

A list just like PROFICIENCIES, with two properties:

SENSES

Special senses that may be displayed on the character sheet.

SHEET ORIGIN

Metadata indicating where the character sheet came from.

SORCERY POINTS

The total number of sorcery points available to the character. May be displayed using circles that can be marked.

SPECIALTY

The character’s class specialty (subclass, domain, archetype, etc.).

SP

Number of silver pieces in the character’s inventory. May be left blank.

SPEED

Character’s normal movement speed. (The system does not yet track specialized speeds like climbing, swimming, and so on.)

SPELL ATTACK MODIFIER (calculated by the system)

This modifier is calculated using the character’s proficiency bonus and spellcasting ability modifier.

SPELL DC

A number that is normally calculated by the system, but can also be written explicitly. If it is written explicitly the system will validate it.

SPELLCASTING ABILITY

The ability your character uses to cast spells, if any. The system knows the spellcasting abilities of the core classes (CHA for Bard, Sorcerer, or Warlock; WIS for Cleric, Druid, or Ranger; andINT for Wizard).

SPELLCASTING ABILITY MODIFIER (calculated by the system)

The modifier for your spellcasting ability.

SPELLS KNOWN

A number that may be used for spell tracking. May appear only on the GM’s sheet. Instead of a plain number, you may give a formula: two ability names, or an ability name and LEVEL, joined by +, e.g. INT + LEVEL. Each name contributes its ability modifier, except LEVEL, which contributes the character’s LEVEL directly. SPELLS PREPARED and CANTRIPS KNOWN accept the same formula syntax.

SPELLS PREPARED

A number that may be used for spell tracking, checked against the spells listed in MAGIC. May appear only on the GM’s sheet. Accepts the same formula syntax as SPELLS KNOWN (see above).

STONES

A Boolean. In some layouts, causes an extra page to be added that can be used to track encumbrance using the Alexandrian stone system.

STR

The Strength ability score, a number, as in STR: 15.

STR SAVING (calculated by the system)

If the character CLASS indicates saving-throw proficiency in Strength, the rendering engine defines STR SAVING to be true. Otherwise STR SAVING is left undefined.

SUGGESTED MOTIVATIONS

A list of strings. On the 3-column layout only, rendered as a bulleted list next to MOTIVATION, to help a player personalize a pregenerated character.

SUGGESTED NAMES

A list of strings. On the 3-column layout only, rendered as a bulleted list to help a player personalize a pregenerated character.

TRAITS

A list of tables each containing a name and description key. May be used for the character’s personality traits, ideals, bonds, and flaws. Not used by any of the current templates.

VALIDATION ERRORS (generated by the rendering engine)

A list of strings.

If the rendering engine detects a badly formatted value or a value that is inconsistent with a calculated value, it adds an error message to the list. Some templates render this list as an additional error page.

WIS

The Wisdom ability score, a number, as in WIS: 15.

WIS SAVING (calculated by the system)

If the character CLASS indicates saving-throw proficiency in Wisdom, the rendering engine defines WIS SAVING to be true. Otherwise WIS SAVING is left undefined.