Tutorial

The point of the opend6_tools project is to help designers (as well as game masters) create consistent definitions of spells and characters. These tools handle the accounting details for spell difficulty and character dice allocations.

Background

The immediate focus of the tools is to publish documents. The publication process is centered around a chain of tools to write some text and get a slick, professional result in a number of distinct publication formats. This also means being able to perform two important tasks:

• Compute the difficulty for a Spell. (Or the dice budget for a Character or Creature.)

• Publish the Spell. (Or Character or Creature.)

These tasks – interestingly – suffer from a deep conflict. The kind of tool that facilitates one task exacerbates the other.

Consider using WYSIAYG (“What You See Is All You Get”) tools like a word processor and a spreadsheet. We can make a spreadsheet to automatate the computation – and recomputation – of difficulty for a spell. However, we don’t want to publish the spreadsheet; we need some kind of nicely-formatted summary. If, on the other hand, we focus on the published description of a spell – a blob of words – we are forced to do manual computations when changes are made.

Bottom-line: Automated computations and nice formatting for publication are incompatible. This conflict between computing and publishing makes exploration of design alternatives difficult. It can lead to rule books with errors: omissions and inconsistencies.

(Copy and paste from a spreadsheet to a book is off the table as a choice. This is too error-prone. Who can be sure all of the spreadsheet changes were properly copied into the rule books?)

The Change-Compute-Consider cycle is important here.

1. Change the definition of a spell (or character or creature.)

2. Compute the consequences, the spell difficulty or dice budget for the character.

3. Consider the change in the larger context of a world design, campaign design, or in the details of a scenario.

This needs to happen at the click of a mouse, permitting the designer to consider multiple alternatives quickly and easily.

To support Change-Compute-Consider, we are forced to step away from the limitations of WYSIAYG tools. We need to switch to a more sophisticated Publishing Pipeline: a sequence of transformation stages. The content will flow through these transformations to create the final, published form of the book (or web site, or printed hand-out for players.)

The general approach to working with a Publishing Pipeline is this:

1. Write the bulk of the source material using a programming text editor. The author use ReStructuredText (RST) markup for the structure and emphasis in the document. For example, bold text looks like this: **bold**. It’s wrapped in double * characters. Similarly, italic text looks like this: *italic*. Headings are underlined. List items are indented.

2. Write details of Spells, Invocations, Characters, Creatures, etc., in external files. These are not in RST format. The publishing pipeline tools will convert the working ideas from a computation-friendly form into the publication-friendly RST form.

3. Edit the various external files in a rapid Change-Compute-Consider cycle until things look good.

4. Use the Publishing Pipeline to convert everthing into RST, and from there into HTML (or PDF or EPUB) products. The idea is to seamlessly integrate RST we wrote plus RST made from our Spells, Invocations, Characters, Items, etc. Consistent editorial styling is part of the final conversion.

For advanced document designers, CSS styles can be added to alter the look. Additionally, the HTML templates used the pipeline can be changed to alter the structure of the resulting pages.

Changes are always made to the source documents; the target documents are generated from these. The target HTML, PDF, and EPUB are never touched manually, they’re simply distributed to the target audience.

The Big Picture

The goal is to create the book.html (or PDF or EPUB). Getting there requires creating a number of files in the book folder. Often, there’s at least one file per chapter. To keep the diagram simple, there are only two files: magic.rst and index.rst.

In order to allow a flexible, fast Change-Compute-Consider cycle, Jupyter Lab is used to create notebooks. The diagram shows one notebook with the unhelpful name of example_1.ipynb. Any more mreaningful name can be used; we strongly encourage using lower-case letters, digits, and _’s as the stem for the name. The suffix has to be .ipynb.

The diagram shows the designer using three distinct tools.

1. The bulk of the writing is done with a programming text editor. The Spyder Integrated Development Environment is helpful. Really, any programming editor can be used, even Jupyter Lab.

2. The more complicated Change-Compute-Consider part of the work is done with Jupyter Lab. This will do rapid computations on the Spell and Character definitions.

3. The final production will be done with the make command run from a Terminal window. This makes use the opend6_tools project and Sphinx to do the real work. It creates the final book.html from the book folder of files.

Yes, there are a lot of files. Yes, there are also a lot of tools. The core concept is to use “Domain Specific Languages” from the opend6_tools to facilitate the Change-Compute-Consider effort. Splitting the overall job into pieces helps create more complex documents, like books of TTRPG rules.

This Tutorial

This tutorial is in five parts.

1. Installing Software covers the basics of getting started working with advanced software tools for writing. For folks new to Python or new to programming, this is essential.

2. Start Writing dips into the world of ReStructuredText (RST) and how simple text files using plain-text markup are transformed into elegant HTML documents.

3. OpenD6 Tools shows how to install the opend6-tools library in a working Python virtual environment. This will show some aspects of the Change-Compute-Consider cycle

4. The Spell DSL looks closely at the Domain-Specific Language (DSL) for spells and how to incorporate a spell definition into an RST document. This section will look deeply at the Change-Compute-Consider cycle.

5. The Character DSL covers some features of the Domain-Specific Language (DSL) for characters and creatures and how to incorporate a creature definition into an RST document. This section also looks deeply at the Change-Compute-Consider cycle.