TOML

What is TOML?

TOML is Tom's Obvious, Minimal Language and is very similar to working with an INI file. This system uses it due to how much easier it is to read than JSON while not having strict indentation or spacing rules.

PbtA Configuration Overview

The PbtA system uses TOML to define complete character sheet configurations. Every TOML file must contain certain required sections and can include various optional sections to customize your game:

Required Sections

• rollFormula - The dice formula for rolls (e.g., "2d6")
• [rollResults] - Success/failure ranges for dice rolls
• [character] - Player character configuration
• [npc] - Non-player character configuration

Optional Sections

• [statToggle] - Stat highlighting/penalties (e.g., Highlight, Debility)
• [statToken] - Token-based stat systems
• statShifting - Stat shifting mechanics (e.g., Masks)
• statClock - Add progress clocks to stats
• Global settings like minMod, maxMod, rollShifting

Basic TOML Syntax

The basic syntax of TOML for the sheet configuration uses the following structure:

• # Comment - Turn any line into a comment that gets ignored by prefixing it with #
• variable = "value" - Any variable can be assigned a value by setting it equal to some value. Numbers or true/false can be written directly, while text/strings should be in " quotation marks. Variable names should be machine-safe (letters, numbers, and hyphens only). The following types of values are supported:
  • String: "value" - Any text value enclosed in " marks. This is the most common type used in sheet configuration, and will also work for numbers. When in doubt, enter your value as a string surrounded by quotation marks.
  • Number: 0 - Numeric values can be entered without " marks.
  • Boolean: true - Boolean values can be entered as either true or false. Most commonly used for default values on checkbox attributes.
  • Array: ["Apple", "Orange", "Banana"] - Arrays of values, such as options for checkboxes. Arrays are a bit more advanced and will be covered later in the Character Sheets section.
  • Subgroup: Rather than having a value assigned directly, an option can be set as a subgroup, following the rules for writing groups listed below. More details and examples of groups and subgroups will be shown in the Character Sheets section.
• [group] - Groups can be defined with [ and ] around the group name. Groups can also be nested. Indentation of group children is not required, but is recommended for legibility. Nested groups need to include the parent group's prefix and a period, such as [group.subgroup]. Sub groups should be machine-safe (similar to variable names).

Configuration Structure

A complete PbtA TOML configuration follows this hierarchical structure:

# Global Settings
rollFormula = "2d6"
minMod = -3
maxMod = 4
rollShifting = true

# Stat System Configuration
statToggle = "Highlight"
statClock = 4
statShifting = true

# Roll Results
[rollResults]
  [rollResults.failure]
    range = "6-"
    label = "Miss..."
  [rollResults.success]
    range = "10+"
    label = "Success!"

# Character Configuration
[character]
  [character.stats]
    cool = "Cool"
    hard = "Hard"
  [character.attributes]
    [character.attributes.harm]
      type = "Clock"
      max = 6
      position = "top"
  [character.moveTypes]
    basic = "Basic Moves"
  [character.equipmentTypes]
    gear = "Gear"

# NPC Configuration  
[npc]
  [npc.attributes]
    [npc.attributes.harm]
      type = "Resource"
      position = "top"
  [npc.moveTypes]
    gm = "GM Moves"
  [npc.equipmentTypes]
    loot = "Loot"

Advanced TOML Features

Nested Groups

Groups can be nested to organize related configuration:

[character.attributes.conditions]
  type = "ListMany"
  position = "left"
  condition = true
  options = ["Afraid (-2 to engage)", "Angry (-2 to comfort)"]

Short vs Long Syntax

Many options support both short and long syntax:

# Short syntax
statToggle = "Highlight"
armor = "Number"

# Long syntax  
[statToggle]
  label = "Highlight"
  modifier = 1

[character.attributes.armor]
  type = "Number"
  position = "top"
  default = 0

Array and Object Formats

Lists can be defined as arrays or objects:

# Array format
options = ["Option 1", "Option 2", "Option 3"]

# Object format
[attribute.options]
  key1 = "Label 1"
  key2 = "Label 2"

Configuration Validation

TOML configurations are validated when saved. Common requirements:

• rollFormula must be present
• rollResults must have at least one result range
• character and npc sections must be present
• moveTypes and equipmentTypes cannot be empty
• Attribute types must be valid (Number, Text, LongText, etc.)
• Required attribute properties must be present (e.g., max for Clock types)

Machine-Safe Naming

All keys (group names, attribute names, stat names) must be machine-safe:

• Use only letters, numbers, and hyphens
• No spaces or special characters
• Examples: cool, basic-moves, npc-harm

Common Patterns

Minimal Configuration

rollFormula = "2d6"

[rollResults]
  [rollResults.success]
    range = "10+"
    label = "Success!"
  [rollResults.failure]
    range = "6-"
    label = "Miss"

[character]
  [character.stats]
    stat = "Stat"
  [character.moveTypes]
    basic = "Basic"
  [character.equipmentTypes]
    gear = "Gear"

[npc]
  stats = false
  [npc.moveTypes]
    gm = "GM"
  [npc.equipmentTypes]
    loot = "Loot"

Positioning Attributes

Attributes use position to control sheet placement:

[character.attributes.armor]
  type = "Number"
  position = "top"        # Top of sheet

[character.attributes.look]
  type = "LongText"  
  position = "left"       # Left sidebar

Valid positions: "top", "left", or omit to hide from sheet.