WIP: Directive Interfaces

There are many different ways one might design the directive interface. This page shows the extremes of each option, but the design we settle on will likely be a combination of several.

Spells

Using options

.. spell:: Burning Hands
    :level: 1
    :school: evocation
    :casting-time: 1 action
    :range: self
    :area: 15 foot cone
    :components: V, S
    :duration: instantaneous

    As you hold your hands with thumbs touching and fingers spread, a thin sheet of flames shoots forth from your
    outstretched fingertips. Each creature in a 15 foot Cone must make a Dexterity saving throw. A creature takes 3d6
    fire damage on a failed save, or half as much damage on a successful one.

    The fire ignites any flammable objects in the area that aren’t being worn or carried.

Advantages:

• uses existing directive parser, so less fiddly
• easy to implement

Disadvantages:

• can't nest options, so forces us to flatten interface and parse some things out
• potentially more difficult to get semantic markup (have to parse option text, e.g. 15 foot cone into {num: 15, unit: feet, shape: cone})
• how to handle "at higher levels"? That section could potentially contain markup, and I don't think options can contain markup (verify) and I think they can only be 1 line (also verify)

Using a serialization syntax (JSON/YAML/whatever)

.. spell:: Burning Hands
    level: 1
    school: evocation
    components: {verbal: true, somatic: true}
    range:
        type: self
        shape: {range: {num: 15}, shape: cone}
    casting_time:
        num: 1
        unit: action
    duration:
        type: instantaneous
    text: |
        As you hold your hands with thumbs touching and fingers spread, a thin sheet of flames shoots forth from your outstretched fingertips. Each creature in a 15 foot Cone must make a Dexterity saving throw. A creature takes 3d6 fire damage on a failed save, or half as much damage on a successful one.

        The fire ignites any flammable objects in the area that aren’t being worn or carried.
    
    damage: {base: 3d6}
    save: {ability: dex, description: "half damage"}
    higher_levels:
        text: "When you cast this spell using a spell slot of 2nd level or higher, the damage increases by 1d6 for each slot level above 1st."
        levels:
            2: { damage: 4d6, description: null }
            ...

Advantages:

• easy to parse and validate
• close to API schema

Disadvantages:

• No syntax highlighting
• syntax in syntax is finicky to edit
• yet another language for new people to learn

Using special roles/directives in the directive body

.. spell:: Burning Hands
    :level: 1
    :school: evocation

    .. basic::

        :casting-time:`1 action`
        
        .. range::
            :type: self

            .. shape::
                :shape: cone
                :range: 15 ft

        :duration:`instantaneous`

    .. body::
        
        As you hold your hands with thumbs touching and fingers spread, a thin sheet of flames shoots forth from your outstretched fingertips. Each creature in a 15 foot Cone must make a Dexterity saving throw. A creature takes 3d6 fire damage on a failed save, or half as much damage on a successful one.

        The fire ignites any flammable objects in the area that aren’t being worn or carried.

    .. higher-levels::
        :damage: lvl * 1d6
        .. one could imagine this being a sort of function that returns the damage for a given level

        When you cast this spell using a spell slot of 2nd level or higher, the damage increases by 1d6 for each slot level above 1st.

Advantages:

• more closely matches HTML output
• uses existing directive parser, so less fiddly
• easier to deal with "messy" unstructured format (you just query the resulting nodetree like you would with HTML selectors)

Disadvantages

• design space is very large, might take a while to settle on something that works
• we'll have to un-messify the messy format anyways for API output

Using a new custom syntax

Disadvantages:

• have to write parser
• no syntax highlighting
• design space is large