Let software tooling check the consistency of your roleplay scripts for you!

(French version of this article available here on Electro-GN)


Every  writer will confirm it to you: it is not easy to remain coherent when  you are working, for several months, on a long story. It is even less so  when the story in question is lived by dozens of characters, each with  their own partial vision of the truth. And live action roleplay games  (LARPs) are especially exposed to this problem.

The  danger does not lie in the first draft of the writing: if he has all  his ideas well in place, the author does not risk much, except for a few  typos and interchanges of names. It is during subsequent modifications  (changes in the chronology of facts, additions of twists and turns,  etc.) that the information — disseminated and duplicated in the  documents of the various participants — will gradually become obsolete  and inconsistent. Eventually, even the character sheets of a common  “murder&mystery party” will end up full of spatial, temporal,  lexical and structural improbabilities if they are not rigorously  checked and compared after each evolution of the scenario.

What can we do to prevent this, without spending a lifetime doing comparative proofreading? First, undoubtedly, deduplicate texts common to several players, which lead to tedious copy and paste (multiplying errors and artificially inflating the mass of the text). Then, allow the author to review the interdependent sets of changes he has successively applied to his scenario. Finally, give him summaries of key information, easier to review than verbose literary texts. And all this in as automated a way as possible,  because the number of documents to be managed can make the smallest  operation very time-consuming (and at risk of carelessness).

The benefits of Pychronia Tools machinery

To benefit from these precious writing facilities during the creation of the Chrysalis:Mindstorm mystery party (French only), I set up a specific writing process,  involving simple text files (which contain the scenario), various  existing software tools, as well as a module “Pychronia Tools” developed  for the occasion.

Once  this machinery is in place, all you have to do is start it up  and — magic — a hundred PDF files appear one after the other in the  output folder: game master’s manual, complete and summarized character  sheets for players, documents to print on beautiful scrolls to serve as  clues in play, summary sheets for extras….

This tool is much more than a simple document generator: it includes an automatic check of the script consistency.  Now, if an index is mentioned in one place but not provided in another,  or if the same symbol has different values from one file to another,  the error is reported.

Extract of consistency errors returned by the program:

!!! ERROR IN hints registry for key golden_box_with_blood : [‘needed’] requires a provided hint
!!! ERROR IN symbols registry for key murder_date : [‘3 January 2018′,’15 March 2018']

And  thanks to the automatically generated summary tables, it is possible to  check at a glance that each player is well informed of the facts  concerning him/her, that the distribution of key information is more or  less balanced, and that major events are correctly recorded in summary  sheets.

Extract from the automatic summary of the “facts” of the scenario:

Character  names are in italics when they have the “fact” in question only in  their complete character sheet, not in their summary sheet.


As  a result, the game master can rely quietly on his own (self-generated)  documents to set up and monitor the game: detailed scenario, evening  planning, checklist of materials and writings to be placed in the  premises, automatic summary of missions and special skills of each  player…

On  top of that, this machine can also send its game documents, by email,  to each player (e.g. character card and documents initially owned). This  avoids the drama that awaits each organizer: spoiling a participant by  sending him the wrong documents.

This  system obviously adds a certain complexity to the project, compared to  some common Word/LibreOffice files. But it provides invaluable support  in terms of scenario scalability and robustness, detecting  inconsistencies and automating daunting tasks. Personally, he saved me  more than once, when I switched the names of some characters in cards,  or forgot to warn some players of the new misdeeds they were supposed to  have committed in the past.

How to set up such a process?

Step 1: Move away from rich office files (docx, odt, pdf…) to a plain text  format, easily manipulable, where the formatting is explicitly indicated  by special characters. The documents in game with  high graphic and typographical needs (posters, scrolls, newspapers…)  can be left aside, in more usual office automation files: Word,  LibreOffice, InDesign…

Example of plain text (restructuredtext format):

Manuel du Maître de Jeu

.. contents:: Table des Matières
    :depth: 2

Concept de la soirée mystère

**Chrysalis:Mindstorm** est un huis clos entre `enquête 
<https://fr.wikipedia.org/wiki/Enqu%C3%AAte>`_ criminelle et conflit
géopolitique, où des agents secrets et des civils de divers pays se 
retrouvent face à un *redoutable* inspecteur de police, qui va les 
pousser dans leurs derniers retranchements.

Rendering of this text once converted to PDF:


Step 2: Use a version manager for scenario files. This makes it possible to go  back in time at any time, to avoid horrifying accidental file  modifications, and to check the consistency of each of the changes made  (renaming a place, adding information for a group of players…).

Viewing a change made to the rules of the game:


Step 3: Add  a small processing engine, to enrich the text with simple and practical  features: allow one file to include another, define reusable text  blocks, insert variables (e. g. the date of a crucial event, different  for each session of the mystery evening), display different information  according to the team to which the targeted player belongs….

Step 4: Automate consistency checks. To do this, I created specific tags in the processing engine, which I then inserted as I wrote:
 — The  {% fact %} tag is used to announce a fact (e. g. “so-and-so tried to  rob Loyd Georges”), and to indicate whether the player is the author or  just a witness.
 — The {% hint %} tag allows you to request the existence of a physical clue (letter, object…) to give to the player.
 — The  {% symbol %} tag ensures that a value is unique in all scenario files  (e. g. the exact time of a crime), while avoiding the use of “variables”  that obscure the text.

Example of using special tags to enrich a scenario text:

To  the attention of {{agent_gamma_fake_name }} : the country of {% symbol  “Balberith” for “first_country_at_war” %} has entered the war, following  the plot led by agent Epsilon {% fact “agent_epsilon_triggered_war” as  author %}. You have a testimony signed by him and attesting to it. {%  hint “epsilon_signed_testimony_for_agent_gamma” is needed %}.

As  we can see, these tags each have their own syntax, and can use other  features of the processing engine, such as variables (of which we have  an example with {{agent_gamma_fake_name }}).

Step 5: Link  all this with scripts, which will automate the different steps of  creating game documents: gathering useful data (including player  photos), distributing scenario pages for each participant (global  context, personal context, game rules…), transforming them into PDF  format, and generating summary sheets for the game master.

Some of the PDF documents generated, next to their plain text sources:


The future

All this is all well and good, but what about the rest of the role-playing  community? Can it benefit, more broadly, from the functionalities  offered by this scriptwriting support system?

The  answer is yes. However, as seen in the steps above, this tooling  requires a certain affinity with processes that are usually reserved for  computer development; an affinity that many GN authors do not have.

I  am therefore listening to authors tempted by the experience, in order  to see with them how they work, what formats and tools they are able to  use, and how this system could be generalized to suit their use. I could  then see to extract this code (which is currently strongly linked to  the structure of the Chrysalis game files), to make it more autonomous  and more easily deployable.

Note that software such as Twine already allows scenarios to be created in a fairly simple way, with a  mini-language to define variables and use logical operations. Pychronia  Tools machinery therefore only makes sense for the very high level of  integration it offers, with its automated consistency checks and  end-to-end generation scripts.

Interested in this scriptwriting support system? Feel free to contact me using the information on the Chrysalis Website.

Appendix : Details for computer literate people

My machinery is based on the Python language and its document manipulation/creation ecosystem.

As  for the “plain text” format of the scenario, many “markup languages”  can be used for this purpose: restructuredtext, markdown, textile,  latex, or even html… I chose restructuredtext for  its clarity, versatility, and its advanced integration with the Python  language. To edit these text files, of course, Pycharm, Notepad++,  Geany, or a simple notebook can do the trick.

For  the version manager (or “VCS”), I chose Git and its excellent  TortoiseGit graphical interface (available under Windows only  unfortunately). Mercurial, Bazaar, DARCS, or others are just as  relevant. At a minimum, we can use the versioned file backup proposed by  Dropbox et al., even if it offers only a few features to visualize the  differences between several writing steps…

Visualization, via GIT, of the sets of modifications made to the scenario:


Regarding the template engine used to process text files (and for specific tags), finally, I have integrated the powerful Jinja2,  which allows you to create variables and macros directly in the  templates. The data handled by this engine comes, in my case, from a  tree structure of Yaml files, but many other sources (python file, csv,  xml…) are very easily integrated.