Automated Publishing for TTRPGs
Using itch.io's automation features for tabletop rpg publishing
Itch.io is a popular platform for TTRPG publishing. Given it’s history as a indie video game platform, it probably comes at no surprise that there exists a way to bundle up game releases, version them and automate updates via the itch client. The beauty of this is that itch doesn’t actually care what kind of content is within the package. We can leverage this to have automatically updating rulebooks for our RPGs!
In this article, I’ll present how we do that1, using a earlier game concept that I didn’t get around to launching:
Preamble: this guide assumes some familiarity with command-line utilities. butler is command-line only (that is, cmd.exe, Terminal, shell, etc).
First, download the itch client: https://itch.io/app. Install and log in. This allows you to both install butler and test your game’s installation.
Using the itch client, install the butler command line tool. The advantage of using the itch client is that it’ll keep butler up-to-date. Simply click the Install button after searching for ‘butler’ and it should default to the stable install for your OS.
Alternatively, you can install butler directly from https://itchio.itch.io/butler — it’s just a single executable — you may use the
butler upgrade
command periodically to update itself.Add the butler installation directory to your system path.
Windows: Open Windows menu, type
env
. Highlight the “Edit environment variables for your account” and hit enter. Click theEnvironment Variables
button, highlight the upper “Path”, hit the Edit… button, and Add a new path. This should be the directory that contains butler.exe (the suggested itch.io client installation — step 3 above — puts it into%APPDATA%\itch\apps\butler
)
Log in by issuing the
butler login
command at a command-line/terminal prompt:Windows: Start menu > Search > type “cmd”. Type
butler login
and hit enter. This will open an authorization page in your web browser. Log into itch (if not already logged in) and hit the Authorize button to allow butler to use your account2
Create a new project using the itch web interface. Keep it in draft mode for now. Feel free to edit description, pricing, tags, rewards, anything except for uploading files. We will be doing that using butler in the next steps.
Create your project directory on your local machine. Fill the directory with all the files you want to deliver. Only the files within this directory are delivered, so name the directory whatever you wish. For the purposes of this post, I’ll be naming this directory “content” for simplicity.
Push a build using command line:
Open a terminal window as in step 6
Navigate to the directory you wish to upload
Issue the push command. This is an example. You will need to customize it for your needs:
butler push . berdandy/gastronomy:rulebook
To help you customize it, let’s break that down:
butler
- the name of the exectuable. Don’t change this.push
- the operation we are performing. Don’t change this either..
- what to push. The period character means “current directory.”berdandy
- my username on itch. Change this.gastronomy
- the name of the project I’m uploading. Change this.rulebook
- the name of the channel I’m uploading. For TTRPGs, there’s no special meaning here, you can use whatever keyword you wish. It affects the name of the zip file created. This is roughly analogous to platform. Video games would naturally have a channel for windows, mac, linux, etc. These show up as seperate downloads.
The product name and channel name are used to name the zip file that is downloadable by your user. In the example above, that would add
gastronomy-rulebook.zip
to the project.Note: if your content directory contains only a single file — like a pdf — itch will present it to the user as a direct download (as long as it’s small enough), rather than a zip file. This doesn’t seem to work for the first version, for some reason.
Edit your game on itch, and change the type of your product to Book. Itch defaults to Executable, but it’ll remember what you set as long as you keep your channel name consistent.
Save your edits. Take the game out of draft and launch it normally, if you’re happy with the results.
Pushing Updates
To update a game, simply go back to the content directory and issue the same push command again:
butler push . berdandy/gastronomy:rulebook
Every time you push a build, the version number will increase (even if there are 0 changes). However, itch will intelligently re-use differences from version to version, minimizing the amount downloaded.
What does it look like to the player?
When a player goes to the project page in the itch client and clicks on Install, they’re presented with a channel and installation location prompt:
Once it’s installed, the itch client checks for updates every 30 minutes (and on startup). You can force it to update as a user in the Preferences.
Screenshots and instructions provided are for Windows, but this mechanism is similar for mac and linux users of butler. Installation and system path setting are the only variations. This is left as an exercise for the reader.
If you notice something that says wharf, don’t worry. That’s the underlying technology that butler uses to publish builds.