A Slack / Discord* Bot for playing Gamebooks (v2.0)
Storyteller is a bot for use with Slack which helps a group of people play through a gamebook co-operatively. It was designed for Fighting Fantasy, but can now play a number of different gamebook types, including Lone Wolf.
It should work with almost any gamebook.
Storyteller adds commands to read the story, manage your character and roll dice for fights and other challenges. It will assist you in playing the game but does not strictly enforce rules - replicating the experience of playing with a real book and dice.
Storyteller is programmed in PHP, requires no database and is state-based. This means it can be installed on an ordinary web-server.
- Discord is also supported, with some caveats, see Using Discord below.
Anything without a character sheet is supported, this includes the Choose Your Own Adventure books.
The following Fighting Fantasy books currently work very well: Battleblade Warrior, Black Vein Prophecy, Bloodbones, Caverns of the Snow Witch, The Citadel of Chaos, City of Thieves, Creature of Havoc, Crypt of the Sorcerer, Deathmoor, Deathtrap Dungeon, Demons of the Deep, Eye of the Dragon, The Forest of Doom, House of Hell, Island of the Lizard King, Legend of Zagor, Masks of Mayhem, Portal of Evil, Rebel Planet, Return to Firetop Mountain, Scorpion Swamp, Seas of Blood, Starship Traveller, Stealer of Souls, Talisman of Death, Temple of Terror, Trial of Champions, The Warlock of Firetop Mountain. Most other can still be played.
The first 20 Lone Wolf books have good support, as do the 8 Lone Wolf: New Order books.
The following other books / series are supported: Alice's Nightmare in Wonderland, The Crystal Maze Adventure, The Sonic The Hedgehog Gamebooks, The Narnia Solo Games books.
The full list of supported books is here: http://htmlpreview.github.io/?https://github.com/JiFish/Storyteller/master/extras/book_support.html
Download and unzip. Place on a webserver running PHP. PHP7 is recommended.
1. Set-Up Slack
First you must create an incoming and outgoing webhook. In Slack, go to Administration > Manage Apps > Custom Integrations.
- Set the channel to where you want the story to be told. You will probably want to dedicate a channel to the story.
- Give the bot a good name. I suggest Storyteller or StorytellerBot.
- Make a note of the Webhook URL. Open
slack_hookto this URL.
- Set the channel to the same channel as the incoming hook.
- Set the trigger word. I suggest using
!to keep things simple. The trigger word must be prefixed to every command.
- Set the URL to where your installation will be located.
- Make a note of the Webhook Token. Open
slack_tokento this value.
2. Get the story
By default Storyteller ships with a very short and simple sample book. It isn't very fun, so you'll likely want to replace it. You have 3 options.
Option 1: Install Lone Wolf books
Joe Dever has generously allowed Project Aon to host copies of the Lone Wolf gamebooks. I've provided a tool that downloads the books ready for use. If you go with this option, the config.ini file will be updated for you, and you can skip section 3. Run the script and follow the on-screen prompts:
It is your responsibility to comply with with the Project Aon Licence. Also, consider making a donation: https://www.projectaon.org/
Option 2: Import a book you own
Storyteller comes with two tools for importing existing texts: one for plain text and one for htmlz. Use htmlz if your book has images. If you own the book in a eBook format, you can use the tool calibre (https://calibre-ebook.com/) to convert it to one of these two formats.
Many books, notably Fighting Fantasy, are not currently available in eBook formats. Your only option here is to scan and OCR the text yourself!
The text is converted to a php array. See
jofm.php in books for an example
book. The converters aren't perfect and you may need to clean up the output
Import from plain text .txt file
Use the bookconvert.php script in the tools directory e.g.
php tools/bookconvert.php mybook.txt mybook
Import from .htmlz file
htmlzconvert.php will attempt to extract images from the book to Storyteller's images directory at the same time as converting the text.
php tools/htmlzconvert.php mybook.htmlz mypicturebook
Option 3: Write your own adventure
Perhaps one of the best ways to get a story in to the bot is to write your own. Choose a set of supported rules you like and come up with your own adventure. If anyone does do this, please consider submitting your story back here. I'd love to include longer stories with this distribution.
3. Add your book to config.ini
Once you have your book php file, put it in the
books directory. Next add a
new section to
config.ini for your book.
- The section name will be used as the book id.
nameis the full title of the book.
fileis the php file from step 2.
rulesis the ruleset to use for the book. This controls which stats are available, the character sheet and ensures character generation matches the book. You can look up the correct book type in
book_support.htmlfound in the extras directory. Use
nonefor books with no character sheet.
Here is an example section:
[wofm] name = "Warlock of Firetop Mountain" file = books/wofm.php rules = ff_wofm
[general] to your book id.
3a. Add book images (optional)
Create a directory in
images with the name of your book id and copy in
illustrations. The images should be named after the page number e.g.
4. Adjust other config.ini settings (optional)
You may wish to adjust other settings in config.php at this point. You might
like to remove
load from the disabled commands list. This will
allow players to use save-points. Alternatively, you could add the
command to this list if you want to prevent players from undoing their
5. Get the code online
- Upload the installation to your PHP enabled web-server. No database is needed. The uploaded directory must be writeable.
- Make sure it's location matches what you step up for the outgoing hook in step 1. If it's different go back and alter the hook.
- If you are not using apache, you must replicate the rules in
.htaccessto ensure the installation is secure.
6. Ready to play!
!library in the channel you chose for the webhook to see a list of available
books and open one with the
!book commands shown.
!0 to read the background page and
!1 to start the story. When the
story tells you to turn to a page or section, you can read it in the same way,
For games with character sheets, like Lone Wolf or Fighting Fantasy, the use
!newgame to roll a character.
!help will list other commands available for the open gamebook.
1. Outgoing hook replacement
The bot can also be used for Discord. The biggest limitation is Discord does not support outgoing hooks. You can work around this one of two ways:
- Run a discord bot to emulate outgoing hooks. There's a working python
discord_oghook_bot.pyin the extras directory. Setting up a discord app account and getting tokens ready etc. is left as an exercise for the reader.
.htaccess. This will allow entering commands by submitting a URL like
http:\\yourdomain.com\storyteller\input.php?c=!echo%20Hello%20World!You could submit this with a form (see
example-form.htmlin the extras directory.) Or use your imagination! If you come up with a creative input method, please consider submitting it back here!
2. Other complications
- Don't forget to add
/slackto the end of your discord incoming hook to make it slack compatible. It will look like
discord_modeto true in
config.ini. This will ensure messages are formatted correctly for Discord.
images/emoji_cacheis writeable. Discord does not support emoji avatars, so emoji PNGs are cached and sent instead. This will cause a short delay when using an emoji for the first time.
Usage Tips and Hints
- Remember, you have to enforce the rules!
!helpto see some basic commands. Help will be customised depending on the ruleset.
- If a book adds complications to the normal
!helpto see if there is parameter or alternate command that can help you. The Fighting Fantasy rulesets has several alternate fight rules programmed. Most others allow you to stop fights after a given number of rounds.
- If the book asks you to do something there isn't a command for, you can
always roll dice with
!rolland apply any effects manually.
It is YOUR responsibility to comply with copyright laws and determine what is fair-use.
Do you accept bug reports?
Yes. Particularly security issues should be reported. Please provide a test case and post it on the github project's issue page.
What about support requests and feature ideas?
Sure. You can also post them on the issues page. No promises though.
Will you support other books?
I'd like to. Please make requests on the issues page.
What about pull requests / patches etc.?
What about a proper bot that isn't state-based / support for other chat software?
I'd like to do this, but I'm not sure how to best achieve this with PHP. This is why the discord outgoing hook bot is written in python.