News Shop
Events Chat

Play-by-forum Bot - Development Notes

I’ve mentioned a few times that I’m working on a bot to help running Play-by-forum games for games that have hidden information. (An analogy I’ve used is that it’s a bit like a Tabletop Simulator but for PbF, so it has some generic concepts of objects and locations, but no actual rule implementations.)

Anyhow, I’m in the middle of development, and I wanted a place to post as I make significant changes, so that anyone using the bot has a place to see what has happened, so that’s what this thread is for.

The bot goes by @ref on the forums, and I’d be happy to show anyone who wants to use it for their games how to run things (and to add aliases that people suggest for games that they’re playing). Currently, it’s being used to play (and has aliases for) both the new games that @Sirlin talked about on his blog.

Setup Instructions

To start a new game with @ref, create a private thread (hopefully, soon, a public thread?) and invite all the players and @ref to it. That will be the main thread you’ll post commands and chat w/ each other in. The bot (@ref) will post information here, and will also create separate threads with each of the players to accept commands with hidden information.

When you want to give a command to the bot, use a format format:

This is a chat message, not a command.

draw 2
move Ace from hand to faceup

The horizontal rules divide the command sections from the chat sections.


On a thread the bot is watching, you can use a number of commands to interact with the game.

  • new game with {player2}, {player3}: Create a new game with yourself, @player1 and @player2
  • help: Still to be implemented, but will list out all available commands and loaded aliases
  • load aliases {alias name}: Load specific aliases for a game. Ping me directly to find out what aliases there are, and to contribute aliases for any games that you want to be able to play (coughCodexcough)
  • random from {option1}, {option2}, {option3}, ...: Pick a random option from a list (for instance, who should go first)

This sounds cool! How much does the bot handle? Is it doing rules-agnostic hand/deck tracking, or something more game-specific?

Yeah, it has built-in commands for locations (with a couple of different properties like who is the location visible to, and who can move things in and out of it), objects (with names and other arbitrary tags) that exist in locations, and counters, and then verbs for moving those objects and counters around. So, by default, it’s very game agnostic, but also very verbose.

The game-specific stuff comes in the form of aliases that basically let you expand a short string into a list of commands with string substitution, so that you can build a custom vocabulary to make playing a specific game easier.

I’d be curious about what it would take for it to be an improvement over the Codex tracking google sheet for playing Codex games.

Oddly enough, I was curious about the same thing :slight_smile: For tournament games, we’d probably want a way for judges to check the game state, possibly for spectators and players to look at the history after the game’s finished. But the bot itself could check for things like teching too many copies of a card, since you’d have a codex location to pull them out of, which would be pretty nice. Handling technician draws could potentially be a bit niggly, since you’re ordering another player to move a card between two locations you yourself can’t see.

Yeah, we’ve got a similar problem in another game where one player needs to modify something that is owned by the other player. I’ll add TODO’s for supporting that (I think just being able to specify someone else’s location is fine, as long as the bot makes public the fact that the action is being done), and also for showing another player hidden state (for your judging scenario).

1 Like

Yeah, that should be fine. I think most of those interactions with the opponent’s cards move a random card. The only exception I can think of would be if someone knew the card on top of their deck, skipped their draw/discard step, then got a technician draw during the opponent’s turn, so you’d need to mess around with a top-of-deck location like the spreadsheet does. Yuck.

EDIT: Oh, and there are effects that let you look at the opponent’s hand. Eyes of the Chancellor makes opponent hands visible while it’s active; Martial Mastery, Community Service, and Carrion Curse let you see the opponent’s hand as an instant event, and the latter two let you choose cards to move elsewhere.

The bot already has ways to reference particular locations in a location. Not sure if that would handle your technician problem or not.

I hadn’t thought about converting locations from private to public and back again, but that should be pretty doable.

1 Like

Based on my experience with the Codex sheet:

  1. If it’s not rules-enforced, it has to be very easy to roll back game states. It’s a little clunky, but doing it all by Google Sheet lets me use version control to correct mistakes. Before I had this suggested to me, I actually manually corrected things by figuring out what cards went where, and it was a headache–it’d be even worse with ref’s commands, I think.
  2. Codex’s game state changes very dramatically from turn to turn compared to Shin Yomi, and I’ve got a little trepidation about ref’s way of handling it (remembering to put a “look” command in every post). I guess for me, I just really like having the spreadsheet available to casually look over at any time.
  3. Is there a way to make the private commands available after the match somehow? From a spectator standpoint, it’s neat to see what options someone had in their hand on a given turn.

Bug Fix

I think I just fixed the transactionality on parsing/processing so that a failure in one post will stop further processing on that game, and won’t commit any changes from the post with the error. (Although, I don’t have a test harness that simulates discourse, so… hopefully it’s fixed?)



  • Improved error handling so that once a command fails in a game, future pending commands in that game will be skipped.
  • Improved set up shortcuts for the first of the Patrons-only games
  • Allowed locations to be ordered or unordered to make information clearer in each of the cases where those matter.

Bug Fix

Fixed an issue where comments # this is a comment wouldn’t parse right at the end of non-alias commands.



Now you can use objects with spaces in their names without requiring quotes around them object names!



Too numerous to count, but including:

  • Counters now actually start at the value you specify
  • Add timestamps to posts so that they don’t get flagged by the “body to similar” check in discourse


  • Always-on mode: No more 5 minute waits for responses (while my computer is on. RasPi coming later this week to actually run all the time)
  • Object/Location/Counter deletion commands

I just made the first post in this thread a bit of a how-to/wiki for using the bot. Those of you w/ access to Patron-only features, please don’t put that info into the post. However, if someone wants to try a Codex game using @ref, let me know. (I don’t actually know how to play Codex myself, so I couldn’t play the trial game, probably). I’d also be interested in seeing if Flash Duel would be playable over the forum.



Now you can modify other players locations and counters by prefixing their names with {player}'s. So, if I want to randomly discard a card from @mysticjuicer’s hand, I’d say move random from mysticjuicer's hand to mysticjuicer's discard.


to mysticjuicer's discard?

1 Like

Good call. Without that, it would steal his card to my discard. :upside_down_face:



Fixed an issue where the bot would post the same response multiple times if it was processing multiple messages in one cycle.

The bot is done wn until I can figure out why I can’t get a response from the forums from inside my network (my phone, when not on wifi, works fine… So, I’m pretty confused)

I’ve been having trouble accessing the forum all day, so it might not be on your end.