Play by the Writing is a small application powered by Espanso that enables rolling dice, random tables, and playing solo RPG systems directly when writing with your keyboard. Just write down the magic keywords, and they will be replaced with the result of such command, wherever you are typing from.

It comes preconfigured to let you roll dice, seek random tables easily, and play Solo RPGs with various GM emulators including Mythic GM Emulator 2nd edition, Plot/Scene/Game Unfolding Machine, One Page Solo Engine,  and MUNE right away as you type.

Each system has its own specific set of commands outlined in the documentation provided, as well as an interactive, easy-to-use, search tool. When you can't remember any specific command, then there is also the option to press Alt + Space which will bring up a handy menu to search all available commands across the supported functions and systems.

To put it in plain words, for example, when you write down the command “:qq” (a yes/no oracle), an answer text like “[No]” or “[Yes, but]” will appear. That’s it!

Discuss PlayBTW on Discord

Features

• Call your GM emulators right away from your note-taking application:
  Mythic 2e, PUM, SUM, GUM, OPSE, MUNE
• Roll dice anywhere in your system just with a short command,
  like :rr2d6+1. → 2d6+1: 11)
• Seek random tables and roll on them super fast, getting the results in your text
• Use ChatGPT and Dall-E to interact with AI from anywhere (needs OpenAI account) with high levels of customization
• An insane amount of random tables is included to roll right away
• (Advanced) Use nested tables to roll many tables in one go
• (Advanced) Configure your own random tables to access them anywhere

How to use?

1. Install Espanso (free) before you install Play by the Writing
2. Install Play by the Writing with either the installer, unzipping, or compiling the source code yourself
3. Launch Espanso and play!

For using AI, after installing Play by the Writing, run :aisetup - this will ask you for your OpenAI API Key (and place it in $HOME/PlayBTW/config/openai.txt)

OpenAPI API Key can be found here: https://platform.openai.com/api-keys

Test if everything works by typing :qq, if you get an Oracle yes/no answer, you're good to go! Have fun.

Check YouTube explanation video

Installable Version

If you are a Windows user, the recommended way to use this is with the installer found HERE There's a price tag on it to justify the work effort overall, for the installer. If you use the open-source version, please consider a donation too.

Open Source Version

The installable is compilable from the source code available HERE. If you know some Python and want to fiddle with Espanso, the source code for this is Open Source and Free (consider a donation!) Instructions included in the source code files.

What is included?

• Example kit: Test before you buy. Once installed, by writing :example you should see a happy output.
• Core kit: Includes dice rolling, random tables, weighted tables from:
  • Mythic GM Emulator
  • Plot Unfolding Machine (PUM)
  • Scene Unfolding Machine (PUM)
  • Game Unfolding Machine (GUM)
  • One Page Solo Engine (OPSE)
  • Conjecture Games (CRGE, UNE, BOLD)
  • The Madey Upy Namey Emulator (MUNE)
  • Storyteller's Prompty Questions (PROMPTY)
• AI kit: Includes Core kit + OpenAI ChatGPT and Dall-E integration

What is inside?

• An installer which will setup play by the writing for you
• An executable (Windows, MacOS with Intel CPUs, Linux) that is run by Espanso to support dice rolling and random tables' logic
• Other configuration files necessary for PlayBTW
• Random Tables as included and used by PlayBTW (plain text)
• Instructions in PDF format (README, INSTALL, KEYWORDS, LICENSE)

Is this safe?

• Espanso itself is an open-source application
  
• Play by the Writing is open source, feel free to compile it from source
• Microsoft Windows may consider PlayBTW unsafe, you'll have to trust me, and ignore the warnings or set an exception if necessary
• I am an indie developer; I do most of my stuff for free and open source - Including Mythic GME Tools for Foundry VTT
• I do this for love. But this took me quite a bunch of hours to get it right. This is why this time I decided to put a minimum price cap for it 😊 Take it as a contribution and a coffee for me

Executable version instructions

The installer will install everything correctly by default, only change the installer path if you know what you're doing. Just press next until it installs. That's it.

Installer details

Play by the Writing (PbtW) files go inside Espanso's user config directory. IMPORTANT: Config directory is NOT the same as installation directory.

For example, if you install Espanso on the F:/ drive, the config directory will still be on the Windows installation drive, where your user files are.

The installer will identify this location automatically, so normally you don't have to switch the path installation of Play by the writing.

Microsoft Windows

Installer

1. Make sure Espanso works fine in your system and starts and works correctly (test with :espanso).
2. Download Play by the Writing Windows installer executables
3. Follow the installer instructions. By default, the installer should point to Espanso config folder: C:\Users\USERNAME\AppData\Roaming\espanso\. Adjust if it is different.

Linux

1. Make sure your Espanso installation is valid and espanso starts and works correctly (test with `:espanso`).
2. Download the Zip packages for Linux (either base or base with AI)
3. If using default paths, this should just work: `unzip ~/Downloads/PlayBTW_v3_01_ai_linux.zip -d ~/.config/espanso/`

MacOS (Intel only)

ARM, M1, M2 not supported / not tested

1. Make sure your Espanso installation is valid and working fine (test with :espanso)
2. Download the .pkg file and install it
3. Test with :qq . The first time might take a few seconds to respond.

Have fun!

Customization and Advanced usage

Match files and shortcut keywords

There are many files with .yml extension inside the match folder of espanso. Open with a text editor and change the lines that start with : in order to change their command keyword.

The match files point to the random tables included out of the box, which are in the tables folder, in the same level as the match folder. There you will find all included random tables by default (this will be overridden on every upgrade, so you should work in my_tables instead for customization).

Most match files entries point to a command using --table (or --wtable for weighted tables) which follow with a table name. This table name is the filename within the folder tables, and you can append using comma symbols more than once, i.e. table1,table2 when customizing.

Understanding this, will allow you to copy these segments to create your own commands with your own tables!

Customizing Random Tables

Play by the Writing stores its config and random tables in a different folder, precisely $HOME/PlayBTW/.

There are two types of tables. Ones ending in .txt (simple tables) and others in .psv (weighted tables). Check the ones available in the folder tables for examples of each.

Add your own tables in the my_tables folder within the espanso folder to keep your own tables safe and untouched after you upgrade PlayBTW.

You can also copy tables from Espanso's tables folder into my_tables and change them there, they will be prioritized!

Nesting tables

You can nest table rolls within others, by utilizing the format {{table_simple_name}} or w{{weighted_table_name}} where the table name refers to the file name. You can use these however you like, and even build sentences with more than one of them, i.e. Hello {{table_1}}, I hope you had a great {{table_2}}!

List tables

Inside the folder list_tables you can find references to tables that change during the course of your game, like Mythic's Characters List.

The tables here are generated dynamically as you use PBTW, but you can check this folder to make backup or changes manually.

Service Level Agreement of Purchase

• The software is free, what is sold is the installer and executable files for your convenience, and as a way to support the author
• This software is provided as-is, I support users on goodwill and listen to feedback and ideas, but cannot commit to eternal promises
• This software is only available on itch.io – For your safety, only download from there
• Tested in Windows 11, MacOS (Intel only!), and Linux (Ubuntu, and OpenSUSE)
• This software is purely and entirely recreational, and it should not cause any harm to your system. I cannot be held responsible for misuse or damage caused to your system.
• Users that have paid, shall receive all future updates for free. However, new content may be sold separately.
• No refunds! Sorry – Use the example package to test this software before you buy

This application has been made to have fun, and I am not a business. You can do whatever you would like to with this software, but be kind, say thanks, and share it with your friends!

JeansenVaars

Useful links

• https://jvhouse.xyz/
• https://ko-fi.com/jeansenvaars
• https://jeansenvaars.itch.io/play-by-the-writing
• https://jeansenvaars.itch.io/plot-unfolding-machine
• Game Unfolding Machine by JeansenVaars (itch.io)
• Mythic Game Master Emulator Second Edition - Word Mill Games | Mythic | DriveThruRPG.com