HTTPS SSH

Xyzzanie is an Discord bot written in Python allowing you to play parser interactive fictions that run on various virtual machines (including the Z-machine and Glulx). Note that you'll have to host it yourself to be able to use it.

Installation

You'll need the following modules (which you can install with pip install -r requirements.txt):

Moreover, you'll need interpreters compiled with remglk. You can get remglk here and interpreters for various virtual machines here (you'll probably mainly want Bocfel or Frotz for Z-machine and git or Glulxe for Glulx). You'll need to compile them yourself, or ask someone to do it for you.

Note: I had trouble compiling some of them, in particular Glulxe. I could compile Glulxe from here however. For Windows, the interpreters have to be compiled with Cygwin. If you need help, you could try the intfiction.org forum, where I'll likely answer.

Once it's done, place the interpreters in the interpreters folder. Place your story files in the stories folder. You'll need to modify the supported_extensions dictionary in glk_interface.py to tell the script which interpreters to use (I may move that to an external JSON file later).

Note: On Windows, you'll also need to copy cygwin1.dll (found in your Cygwin installation) alongside the interpreters.

To test if everything is working before creating your Discord bot, you can run glk_interface.py in a terminal and interact with the script as if you were on Discord (see below for how to interact with the bot).

I tested the bot on macOS, Linux and Windows. Everything worked as expected, but there may be some issues on Windows. If you encounter one, please file a bug!

Running your bot

  1. First of all, you need to have a Discord account. Log in on their website.
  2. Go to the developper section of the site and click on New App. Give it a name, a description and, optionnaly, an avatar.
  3. On the bot's page, click on Create a Bot User and confirm.
  4. On the same page, click on click to reveal next to Token in the "bot" section. Copy the revealed token to a file called token.txt, that you'll place in the same folder than xyzzanie.py. This token will link the script to the bot's account.
  5. Invite the bot to a Discord server. If you have the right to manage your server, you can use the link https://discordapp.com/oauth2/authorize?client_id=INSERT_CLIENT_ID_HERE&scope=bot&permissions=0, where you replace INSERT_CLIENT_ID_HERE with your bot's client ID, as found at the top of its page.

Once all this is done, all you need is to run xyzzanie.py to connect your bot. Each channel on every server the bot was invited will be able to play independantly to the stories in the stories folder without interfering with each other. I however don't know how well the performance will be if many game sessions are running at the same time. When the script is interrupted, all game progress is lost.

If you want a more permanent solution, you'll have to host it somewhere (like Heroku); you'll have to do some research on your own to know how to do it.

DISCLAIMER: Since the bot launches processes on the machine it is installed, there could be security issues where Discord users could access to your computer. I don't think there are any, but I will not be held responsible if something happens.

Interacting with the bot

To interact with the bot, you have to prefix your Discord message with >> to launch stories and perform other meta actions, and > to submit a command to a game. (You can change these prefixes if they don't suit you in the glk_interface.py file).

Getting help

Type >>help to get a brief summary on how to interact with the bot, and to get a link to this readme.

Getting informations about the bot

Type >>about to get informations about the bot, such as its author and the repository link.

Listing the stories available

Type >>list to get the list of the stories that are available to be played.

Note: If there are a lot of story files in the stories directory, it could be quite long. I should maybe make the bot send a private message to the user that requested the list.

Refreshing the story list

Type >>refresh if you added or removed stories in the stories folder. If you don't do that, people won't be able to launch newly added stories.

Playing a story

Type >>play [story file] to play the specified story file, as written in the list produced by >>list.

It is not currently possible to save your progress or to upload a savefile.

Also, please quit the story after playing it (whether you finished it or not). If you don't do that, it will leave a process running uselessly.

Forcequitting a story

Type >>forcequit to immediatly end the story currently being played. Do that if you encounter a problem. Otherwise, juste try quitting the story normally by typing >quit.

Interacting with a story

Type > followed by your command to interact with the story being played; >get lamp for instance. If the game is not displaying a prompt, that could mean it is waiting for a single keypress instead. In that case, juste type an empty command (>) to move the story forward. If a command is typed, then only the first character will be submitted as the key pressed, except if the command is one of the following:

  • left
  • right
  • up
  • down
  • return
  • delete
  • escape
  • tab
  • pageup
  • pagedown
  • home
  • end
  • func1
  • func2
  • func3
  • func4
  • func5
  • func6
  • func7
  • func8
  • func9
  • func10
  • func11
  • func12

The named key will be pressed instead.

The key pressed is not important in a vast majority of game, so just enter an empty command > when no prompt is displayed and you'll be good most of the time.

Licence

Xyzzanie is released under the MIT License. Please see the LICENSE.txt.

Xyzzanie?

xyzzy + zizanie