A downloadable tool for Windows, macOS, and Linux

Buy Now5.00€ EUR or more

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


  • 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)

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?

What is inside?

  • An installer which will setup play by the writing for you
  • An executable (Windows, MacOS, 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


  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.


  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/`


  1. Make sure Espanso works fine in your system and starts and works correctly (test with :espanso)
  2. Download the MacOs zip archive
  3. Unzip and merge the archive PlayBTW_v3_01_ai_macos.zip into ~/Library/Application\ Support/espanso You can also run unzip -o -d ~/Library/Application\ Support/espanso ~/Downloads/PlayBTW_v3_01_ai_macos.zip

Note 1: If you get an error saying "Apple cannot check this application for malicious software":


1. Press OK, then open "Privacy & Security" and scroll down until you see this:


2. Press "Allow Anyway" 

3. Runn a command again like :qq. Now you should get this window:


4. This time press "Open". From now on, all commands should work.

Alternatively, you can build the MacOS version yourself from the GitHub repository's code by yourself, which will also run faster as you can use the standard build instead the fat build. Building it yourself will automatically make MacOS trust this software on your MacBook.

Note 2: If you accidentally replace, and do not merge and get errors, simply restart the Espanso service and all will be fine.

That's it, test an oracle example with :qq.

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 Sierra, 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!


Useful links

PlatformsWindows, macOS, Linux
Rated 5.0 out of 5 stars
(10 total ratings)
Tagsartificial-intelligence, chat-gpt, dice-roller, journaling, software, Solo RPG, writing


Buy Now5.00€ EUR or more

In order to download this tool you must purchase it at or above the minimum price of 5.00€ EUR. You will get access to the following files:

PlayBTW_v3_11_ai_linux.zip 13 MB
PlayBTW_v3_11_ai_macos.zip 13 MB
PlayBTW_v3_11_ai_windows.zip 10 MB

Download demo

PlayBTW_v1_11_example_windows.exe 5.8 MB
README_3_11.pdf 74 kB

Development log

View all posts


Log in with itch.io to leave a comment.

Can we expect an Android port any time soon?

it would be great, but unfortunately not possible :(

Regarding AI, any chance of supporting Ollama in future?

Still love this App! 

One small thing: in the windows installer (at least for me) in the version 3.0 the poker deck is not installed. So the folder "cards_tables" and the file "poker_deck.txt" (which is in the git) was missing.

Yesss you are right, it is broken. Couldn't have time yet, but will be fixed soon! - I think creating the folder manually solves it for now

Yeah that worked for me. 

If somebody cant wait for an update: 

You can find the table here: https://github.com/saif-ellafi/play-by-the-writing/blob/main/tables/poker_deck.t...   

Just copy it to your "PlayBTW\cards_tables" folder (you have to create the cards_tables folder)

I must admit I skipped a few versions, but I've just updated to v2.05 and I'm having trouble with the API key, as ChatGPT says it doesn't use API keys anymore: it uses API tokens.  I'm not sure what to do next.

Hey AB2014, I am not sure what is going to be honest, using it right now with my OpenAI API key and working just fine. Are you placing the API key in the config file? Tried generating a new one? If not, let's catch up in Discord for a chat. #jeansenvaars

Well, the good news is that I found the API keys in OpenAI rather than ChatGPT. I copied the key into the file and saved it, but I'm having trouble getting AI results. Espanso says there is a problem during rendering, and the logs say I've exceeded my current quota and should check my plan and billing details.

Yes, you might need to review your billing status, your payment method to be valid, and so on. This is a bit outside the scope of what my tool can do I am afraid :) It did happen once to me that I had to update my payment method and load some credit in OpenAI for it to work. Good luck!

Any chance we could get a Mac version?

I'll do my best to find a way to compile it for MacOS. Follow me to stay tuned to updates!

You're awesome! Thank you!

Released for MacOS! I hope you can try it and let me know if it works fine :)

Hi! I've just bought the mac version and the idea is really great- but it's extremely slow. I'm not sure if you have a mac, but even something like the "qq" command takes 5-10 seconds for me (M1 mac). Honestly, it's slower than opening a new browser, googling a table, and clicking. If I can't fix this I'm wondering if I can get a refund because at the speed it's at, it's not usable for me.

Hey volaix - thanks for letting me know. I don't have an M1 Mac, so I unfortunately can't tell what is going on :( I have tried this on a MacBook Pro (Intel), and I don't think I'll be able to figure this out anytime soon. I'll get you a refund - you purchased today 13th of March no?


This is a game changer for solo RPGing! I cannot recommend it enough.

It is :D Thank you so much!!

If you enjoy solo roleplaying on your pc then you need this great little program.  Once installed it works anywhere that you type! In this way it supports whatever your favourite writing software might be.  It contains the author’s three solo roleplaying engines which I highly recommend and the very well liked Mythic.

I also want to say that I run Linux on my PC (Ubuntu LTS) and Jensen tirelessly helped me move mountains to get it to work for me.  He is a great guy and I am very grateful for the time he gave me!

hey i'd love to purchase this but i cannot pay thru paypal and that's the only option it gives me, is there any way i can pay thru ko-fi or something the equivalent amount?

Hello - thank you so much. Sure, drop me a ko-fi and I'll use the email from the payment to send you the installers :)

epic, i'll do that right now! tysm!!

Hi.  I’m trying to run this on Ubuntu Linux.

If I place your folders in   .config/espanso/config   it doesn’t work.  If I move them all to   .config/espanso/match   I can get :dd and :arr to work and nothing else.

It appears that you just need to advise me on the correct placement of the folders.  Thanks!

Also anyone trying to run espanso on Ubuntu 22.04 will fail unless you run xorg instead of wayland(default) at the login screen (cog - bottom right of screen).  This drove me nuts until I figured it out!

Hi crinklechips - thanks for trying this out.

Are you trying the "purchased" zip version or installing by yourself from GitHub? If from GitHub, please follow up on the repository. My quick guess is that you are trying to copy folders without compiling it first.

Best regards

Hi Jeansen,

I bought it.  I’m only an amateur Linux user.  I don’t know how to compile programs.  Also, you deserve the money ;-)  I really hope you can help but at the end of the day it was only $3.

(1 edit)

Thank you, no worries, didn't mean to check. It was just a typical issue on the users who try to install it from GitHub. Installing in Linux the zipfile should be quite straightforward.

1. Make sure you are running the last version of espanso espanso --version should say 2.1.8.

2. Then just run

unzip ~/Downloads/PlayBTW_v1_35_base_with_ai_Linux.zip -d ~/.config/espanso/

This will unzip the package into the espanso folder. That's it, then typing :qq should trigger the oracle yes/no prompt :) If you have issues on Wayland/X11, double check the installation instructions on https://espanso.org/docs/install/linux/#choosing-the-right-install-method. I personally use the AppImage install method in X11 (OpenSUSE Tumbleweed, KDE) and it works just fine. 

Good luck and let me know if it works out! JV

Forgot to reply.  Couldn't get it to work.  Never mind.  I don't have the tech skills to fix whatever needs fixing.

reach out to me in Discord servers and I gladly can help you. My nickname is: jeansenvaars

Awesome tool! I also hope you'll add the Mythic GME 2e.
FYI: I think you forgot to add the playbtw_gum2.yml script to the installer. I added it via your git repo afterwards for myself and could use the new GUMv2 keywords then.

Ohhh thank you so much for letting me know, wll update with GUM v2.9 and make this update. Yeah the problem with Mythic is handling lists, and need to pull those hundred elements tables, hehe. But hopefully one day

(1 edit)

I know the tables for Mythic 2e aren’t included, but I did add these myself and can confirm it works really well.  The most time consuming part was getting the tables into plain text lists from the pdf.

Does this include Mythic GM 2E?

Hi, no, sorry. Only up to Mythic v1. But I should do it soon, as I wanted to use it myself next :)

(3 edits)

Hi there, I have built this from source without errors, but Espanso refuses to detect it. I have tried placing the various folders (some of which were generated blank for some reason, again no errors) into both \AppData\Roaming\espanso\match\packages\ and \AppData\Roaming\espanso\config to zero success. Nothing happens for any commands. I checked the search bar and it definitely does not see the packages. 

I even went as far as downloading a different package using the command line installer to verify that I was putting anything in the right spot, and that program works just fine and was placed into the packages directory.

I am an idiot and was copying the folders from the build directory, rather than the ones in the root of the project. Instead, I am running into a new problem. All commands output the following:

 [Espanso]: An error occurred during rendering, please examine the logs for more information.

Looking at the logs, this appears to be the error:

13:07:48 [worker(23344)] [WARN] extension 'script' on var: 'output' reported an error: could not execute script: '`C:\Users\Administrator\AppData\Roaming\espanso/scripts/playbtw_example`', error: '`The system cannot find the path specified. (os error 3)`'

13:07:48 [worker(23344)] [ERROR] error during rendering: rendering error

Caused by:

    could not execute script: '`C:\Users\Administrator\AppData\Roaming\espanso/scripts/playbtw_example`', error: '`The system cannot find the path specified. (os error 3)`'

I have no idea how to fix this.

Hey Jeansen, just curious if Play by the Writing is able to installed on a Mac or if there are still plans for a Mac conversion?

Hi Benjamin, sorry, don't possess a mac right now to be able to compile it there. If there is anyone willing, the source code is open source!

Hi Jeansen,

In the video you use the AI autocomplete feature automatically, without opening a different window. Is there any way to do this in the current version? I use this with a journal app on an old game and opening the AI window makes the game crash.

hey! The old way (as in the video) required you to copy (Ctrl-C) the prompt you wanted to give to the AI. I am afraid that method was very unreliable. Not sure there will be any other way around for now

Hello Jeansen! I'm from the Philippines and it won't seem to let me pay via PayPal just using my bank account. I don't use cards and just pay via the bank connected to my PayPal. Is there any other way to send payment?? Thanks! Love your PUM btw :)

Hi iameggnest, reach out to me in Discord I'll send you a copy: JeansenVaars#2857

Expect some delays I am currently travelling :) best

(1 edit)

Greetings, Jeansen. Idk why but my payment thru PayPal is not working(most likely to be my own "Asian" problem...that I can't buy stuff that is in euros.). So I had to download the source code and compiled those scripts myself. And only 10 or more minutes, I'm already loving Playbtw as much as how I like Mythic. I might talk about it on my blog/channel, since I cannot find a way to pay for it or buy you a ko-fi.

Ah, by the way, ":mre"  is not working, showing :[Espanso]: An error occurred during rendering, please examine the logs for more information. " Can I ask why? or how can I fix it?


Hey thank you so much KeepOnSurviving, glad you like it. Yes need to fix some commands and the documentation, :mre was for Random Event, it was changed to :mac (action), will fix to make both work, need to double-check what is happening with the focus in that roll. I think Random Event should include the focus.

Got it. Thanks for the reply. 

1.17 should contain mentioned fixes! thanks

Hello Jeansen, couple of questions for you: Does Play-btw works in obsidian once installed with no additional plugin or integration? and, how does one upload the Mythic GM Emulator tables? Does it require programming knowledge?

Hi daniboiwp! Mythic tables are included, since the application is open source with no commercial license. And yes, it works in Obsidian and literally everywhere in your computer, including Paint, Word, your Browser, or inside a videogame. Hope that helps!

Thanks! Just got it, will let you know how it goes.

Would this work on Mac? (Or is it just for Windows and Linux so far?)

Deleted 172 days ago

Released for MacOS! I hope you can try it and let me know if it works fine :)

My anti-virus software freaked out on the file PlayBTW_v1_11_base_windows.exe.  Is anyone else seeing that?

did that happen now for the first time or is it the first time you try it out? You can check the open source version and build the software if in doubt as well. Alternatively, right click on the installer and open with a zip program. Not sure what I can do hmm

It installed peacefully the first time.  But hey, the anti-virus software is always updating itself, so it might be a new rule or something.  If nobody else is seeing this, I'll chalk it up as a false positive.

Strange. But no, nothing changed, only tables and the .yml expressions. It is all same old Python behind this.

Me again, but in a good way this time. With the help of the video, I now have it working just fine. It's a great tool! Thanks so much for the extra support as well - I hope my experiences will help others.

Fantastic! I am glad. Yes, I should have started with a Video. It really feels it gives certain confidence towards the application, and with it, I also got a few extra downloads :) Thanks and enjoy it!

Sorry, it's me again. I downloaded and installed v1.3 with the AI, but I'm not seeing any of the files listed above as PDF instructions. So, I don't know how to use the software beyond your sample video. Any idea where those files are?

Hi! Sorry that it is confusing. I have added a README.pdf file that can be downloaded for free with all instructions inside. Do ask if anything is still confusing.

I will make a YouTube video soon and append it here!

The README file is what I was looking for. It came with the example but not the full version, so thanks for that! I can see how a video would be helpful, as the files on GitHub look great, but getting them from there to where I need them doesn't look like a job for a noob.

will do!!

This is great! Been looking for both a good way to do rolls and text expansion in my journals as I prep for games and this seems a lot better to work with than AutoHotKey (Win) or the built-it expander for MacOS.

Tested this out and it looks like it works with no issue in Obsidian and Notion as well if you use those for organizing your notes like I do.

Thanks a lot for the feedback! Let me know if the oracles suit you :) I am planning to add some basic mythic checks too.

This sounds really interesting, but I can't get it to work. I installed Espanso, then the example file, but when I type what I'm supposed to type, I just get "An error occurred during rendering, please examine the logs for more information."  I checked the logs and they say:

error: '`The system cannot find the path specified. (os error 3)`'

Any ideas?

Sounds like you need to add espanso to the $ENV:Path variable (Win) or Path (if you are on Linux or MacOS).  This may help:


How to Add to Windows PATH Environment Variable (helpdeskgeek.com)


How to Set the PATH Variable in macOS (techpp.com)

Linux (Ubuntu)

How to Add a Directory to Your $PATH in Linux (howtogeek.com)

Hope this helps!


Adding the espansod.exe tothe  PATH environment variable makes no difference, unfortunately. Is the problem caused by not finding Espanso, or by not finding the example script? When I used date (preceded by a colon) that worked. The logs say:

22:56:07 [worker(3700)] [ERROR] error during rendering: rendering error

Caused by:

    could not execute script: '`C:\Users\andyb\AppData\Roaming\espanso/scripts/playbtw_example`', error: '`The system cannot find the path specified. (os error 3)`'

I'm not sure which path can't be found.

(5 edits)

Hello there AB2014! Thanks for testing this out.

This error occurs if Espanso cannot find the executable script. In the Windows zip, this is called playbtw_example.exe and is located at C:\Users\user\AppData\Roaming\espanso\scripts (after you install it). This executable contains the logic such as for dice rolling.

If you are on Windows, perhaps an Antivirus thinks this is malicious and removed it when you extracted it? I am on Windows 11 and using default "Windows Security" with Windows Defender, and no issues.

(and thanks yakuzadave for trying to help! appreciated)

Still no luck, unfortunately. The Setup tells me it will install the file PlayBTW_v1_2_example, but it doesn't look like the different file name is the problem. It looks like the file just never arrives. There is no error message or warning, and if I run the Setup again immediately, there is no warning of a duplicate file. I'm using Windows 10 and Windows Defender, but I'm due to upgrade to Windows 11 in the next few days, so I'll try again after that.

(1 edit)

Ohhh!!! I have double-checked :( you are right. Totally my fault. This example will never work. I did not compile it correctly :( :( :(. Will upload a _v1_2_example_2 again. Shame on me.

Now uploaded a correct one. But that means on the good side that your error was healthy and it will work :)

Hey, is there any chance you could compile the script for Mac as well?
Or do the core functions (dice rolling, random tables) also work directly in Espanso without that script?

(1 edit)

Hi! Thanks for the interest. Soon Linux and MacOS! Stay tuned. Rolling from random tables or weighted tables can function without a script, but not system specific logic or dice rolling. I will be considering soon if to package the source code version so to let users run it however they want.

(1 edit)

Hi, After long hesitation, I am making my mind to favour Espanso and your Play by the writing system. But I only use Linux. Any news about it?

Edit: Sorry. Forget it. I just read the open-source instructions and could install it myself easily. Some issues, though, that I expect to correct soon. Otherwise, I will contact you for assistance. Splendid work! As usually.

(1 edit)

Solo Historias! Yes you are welcome to try it, I didn't update it because I got zero downloads on Linux :) Do let me know if you prefer building it yourself (run the build.sh script) or I can make the build for you, if you still face issues. Best regards

Hi, I installed the dependency for md2pdf, but the installation halts at this point: File “playbtw_all_ai.spec”, line 3, in <module> from md2pdf.core import md2pdf ModuleNotFoundError: No module named ‘md2pdf.core’

Please create an issue in Git, so we can debug it there, instead of here :) Thanks

Released for MacOS! I hope you can try it and let me know if it works fine :)