OpenD6 Tools

Welcome to a collection of tools to help preparing documents for the OpenD6 Table-Top Role-Playing Game (TTRPG).

The essence is Domain Specific Languages (DSL) to define spells, items, creatures, and characters using Python syntax. Python is a programming language, but there’s no real “programming” involved. The definition doesn’t involve iteration or conditional execution; it’s an explicit specification of the OpenD6 object.

There are three DSL’s:

• The opend6_tools.magic package is for designing spells, invocations, and items.

• The opend6_tools.character package is for building characters and creatures. (As a nod to the OpenD6 Fantasy Worldbook: Kingdom of the East, magical swords can have Charisma and Agility, and are essentially creatures, defined with this package.)

• The opend6.dice package is a small DSL for dice expressions, used by the other two packages.

The package includes the opend6_tools.notebook_extract application to extract Spell, Item, or Character definitions from a Jupyter Lab notebook into a Python module. Using JupyterLab permits easy, flexible, interactive computation of details. When defining a character, for example, the result of a change to the attributes can be computed and displayed immediately in JupyterLab. We call this the Change-Compute-Consider cycle for working on a design. The extract from the notebook can then be converted to RST to feed the publication pipeline.

The opend6_tools.dice module is also a command-line application to roll dice using the OpenD6 Wild Die rules.

Similarly, the opend6_tools.character package is also a command-line application to create blank character sheets.

Plus, just for the curious, there are two other other applications. See the Miscellaneous Applications section on creating some of the more complicated tables in the OpenD6 rules from first principles.

• The opend6_tools.die_simplification application.

• The opend6_tools.spell_measure application.

Additionally, some Jupyter Lab notebooks are part of this project. These can help to analyze spells and characters.

Contents:

• Installation and Quickstart
  • Installation
  • Quick Start
• Tutorial
  • Background
  • The Big Picture
  • This Tutorial
• Using the OpenD6 Tools
  • Creation
    • Spells, Invocations, and Items
    • Characters
    • Supporting Functions
  • Publication
    • Files and structure
    • Processing and control
• Applications
  • dice
    • Synopsis
    • Description
    • Examples
    • Options
    • Environment
    • Exit Status
    • See Also
  • character_sheet
    • Synopsis
    • Description
    • Examples
    • Options
    • Exit Status
    • See Also
  • notebook_extract
    • Synopsis
    • Description
    • Examples
    • Options
    • Exit Status
    • See Also
  • Other Applications
    • die_simplification
    • spell_measure
• Architecture
  • Context
    • Non-Functional Requirements
  • Containers
  • Components
  • Code
• Reference
  • dice
    • Implementation
  • magic Package
    • Defining Spells
    • Display and Output
    • Workbook Support
    • The Spellbook Wrapper
    • Implementation
  • character Package
    • Defining Characters and Creatures
    • Display and Output
    • Workbook Support
    • Application Wrapper
    • Implementation
  • notebook_extract app
    • Implementation
  • Miscellaneous Applications
    • die_simplification
    • spell_measure
• Notes
  • Notes on DSL Design
    • Rigor and Modes of Play
    • Non-Combat Mode
    • DSL Syntax
    • Phased DSL Design
    • Phase I – Capture
    • Phase II – Completeness
    • Phase III – Fluency
    • Conclusion
  • The Source Extraction Saga
    • Draft Documents
    • Design for Human Consumption
    • Colorful Prose

On DSL’s

These DSL’s provide a way to define OpenD6 objects (like spells or creatures) using using Python syntax. These DSL’s have a number of benefits:

• Incomplete definitions are easily identified. The Python syntax errors will show many spelling mistakes.

• Analytical tools can be used to locate inconsistent spell definitions.

• The spell difficulties and character dice budgets are directly computed from the details. This is consistent (and automatic); it avoids time with pencil, paper, or calculator.

• The definition is transformed into ReStructuredText documents with consistent organization. These can be processed by the Sphinx tool (and any other docutils tools) to create final publications.

The Text User Interface (TUI) of a DSL has a few advantages over a point-and-click Graphical User Interface (GUI).

• Any programming text editor can be used. A project consists entirely of text files which are always accessible.

• There’s no separate save-file format. (A GUI needs to save the state of the graphic presentation in some kind of file format: JSON, TOML, XML, etc.)

• Processing to do budget computations – either difficulty or dice – are an essential feature of the DSL.

• Conversion to other formats is done via Jinja templates to emit the details in the desired format. New templates can be added.

• Conversions from other sources (e.g., personal notes, a VTT tool, etc.) are a matter of transforming the source to Python format. This requires transforming source text into Python syntax. This is not easy, but it is relatively straight-forward text manipulation.

The advantage of a GUI is providing a known, fixed number of slots which must be filled. Most designers will create a block of text with a template character definition or a template spell definition. Many programming editors have convenient template management features.