Help

Fabularium helps you to write and play interactive fiction.

It is both an Android implementation of Andrew Plotkin's GLK API Specification (with some extensions) and an integrated game / file management system. It is packaged with third-party compilers and interpreters ('terps'), to allow you to write and play interactive fiction across a wide range of formats.

Fabularium was written by Tim Cadogan-Cowper. It is free, open source software (FOSS). The bundled terps and compilers, and other useful libraries, were released by their respective authors under FOSS licences. Tap Licences under the app's main menu to see the complete list.

  1. Get it: Download a game that Fabularium supports. Currently: adrift, advsys, agt, alan, glulx, html (e.g. Twine), hugo, level9, magnetic scrolls, scott, tads2, tads3, zcode.

    You can find many free games at http://ifdb.tads.org and http://www.ifarchive.org/. Good games for beginners include Admiral Jota's Lost Pig and Emily Short's Bronze. For more advanced players I would recommend full interactive novels, such as Anchorhead by Michael Gentry (strongly influenced by the works of HP Lovecraft and not suitable for children), Blue Lacuna by Aaron Reed, The Plant by Michael Roberts and Blighted Isle by Eric Eve. Or try something completely different - Victor Gijsber's Kerkerkruip, a short-form roguelike in the IF medium. If you have any old Infocom (zcode) games lying around - such as Douglas Adams' The Hitchhiker's Guide to the Galaxy - they should all work under Fabularium also.
  2. Add it: Once you have downloaded the game or compressed archive (e.g. ZIP) to your device:
    1. Open Fabularium.
    2. Go to the Explore tab and look for the file - it will usually be in the Downloads folder.
    3. (only for compressed archives) Select the file and choose "Uncompress" from the menu. The archive will extract to the same directory.
    4. Select the game, then choose "Add to Game List (auto)" from the menu. This command attempts to auto-detect the details of the game using the Babel library. In most cases this should work fine. However if the game is not recognised by Babel you may need to add it manually. To do that, simply choose "Add to Game List (manual)" and fill in the game details (IFID, title and game format). Note: you can also select multiple games and/or directories and add them in one go using these commands.
    5. Go to the Play tab. The new games have now been added to your Fabularium library and should appear in the window.
  3. Play it: Short-press a game to play it.

Note: When you add games as above, Fabularium copies each game to the Fabularium/Games folder. So you can delete the original file if you want. You can also copy the game into the Fabularium/Games folder yourself and hit refresh. Should you want to remove a game from your library, simply delete it from the Fabularium/Games folder (and again hit refresh).

Long-press on the game in the PLAY tab, then select REMOVE. This command will only remove the game, not the game's data. I.e. if you add the game back to your library afterwards, you will still be able to use saved games, etc. To remove the game's data as well, you need to delete the relevant folder under Fabularium/GameData. These folders are titled according to IFIDs (unique identifiers for each game). You can determine the IFID for any game in the library by long-pressing its icon in the PLAY tab and selecting ABOUT.

You can see the metadata for any game in your library by long-pressing its icon in the PLAY tab, then selecting ABOUT. Update this metadata (and the game's icon, if any) by pressing the GET METADATA button - assuming you have an internet connection.

No. All games are played offline. Currently Fabularium only accesses the internet when you ask it to download metadata for a game. If you are paranoid about your device leaking information to unknown servers and don't care about downloading metadata, feel free to disable Fabularium's internet permission altogether - how to do this varies from device to device. You might also consider installing a firewall app.

No sweat! You've got two options:

  1. Customise the built-in keyboard to do what you want. This is our recommended option, as once you learn how to do it you can set the keyboard up pretty much however you want (want a bilingual or trilingual keyboard? no problems). In fact you can make the built-in keyboard output any Unicode character or sequence of characters. The trick is to edit two files: fab.ini and keyboards.ini. First open keyboards.ini and study the Cyrillic example included there. Once you have an idea of how it works, define your own keyboard. Then go into fab.ini and use the "keyboard 'name of your keyboard'" command to use that keyboard. For example "keyboard cyrillic" would load the standard Cyrillic example. The beauty of this approach is that you can define different keyboards for different games, or terps, or you can just define one keyboard to use for everything, depending on where you place the "keyboard" command(s) in the fab.ini file.
  2. Use your normal system keyboard. This is less powerful than the above option, but probably easier for people who don't want to mess around with Fabularium's config files. To do this, simply go into the app settings, find the option "Use built-in keyboard" and disable it.

If you have any questions on this, feel free to contact me at tcowperapps@gmail.com

Fabularium goes to considerable effort to choose intelligent layout defaults - margins, line spacing, etc. However these settings may not always work so well depending on the device/terp/game combination. That's the bad news. The good news is that Fabularium is also highly customisable, so you can try to fix the problem yourself.

There are three ways you can customise Fabularium:

  1. Via the user interface: Go into the settings menu, change things as you see fit, test with your game until you have something that works for you.
  2. Via the main config file (advanced users): Go to the EXPLORE tab and open fab.ini under the Fabularium directory. You can edit and save this file directly in Fabularium's built-in bare-bones text editor. Again, make changes, test with you game; hopefully you can find something that works for you.
  3. Via a game-specific config file (advanced users): Same as the main config file, but this a .ini file in the game's data directory (under Fabularium/GameData/<IFID of game file>).

Note: You can revert fab.ini to its original form at any time using the menu command "Reset config files".

No, you don't need to uninstall and reinstall the app. Here is what you should do:

  1. Configuration files (fab.ini, keyboards.ini, etc.) To restore the default settings in Fabularium's config files, run the menu command "Reset config files".
  2. In-app settings. To restore the default in-app settings, you'll need to clear the app's data. How to do this varies from device to device - read your device's manual or look up instructions on the internet. Note: this will also clear any metadata you have downloaded for the games in your library.

Yes, I hear you.

Fabularium already supports a few tricks that might save you some typing time:

And there will be more tricks to come in the future, including:

If you have any other suggestions or comments on innovative input methods, I'd love to hear them. Send an email to tcowperapps@gmail.com

In most cases yes, but you may need to do a bit of fiddling, depending on the game format:

  1. Hugo: Add the extension ".glkdata" to the resource file and save it to the game's data folder (Fabularium/GameData/<IFID of game file>). For example, Tales of a Travelling Swordsman includes a resource file "TALES_TS". In this case, you'd copy that file to Fabularium/GameData/HUGO-25-54-06-09-29-06/TALES_TS.glkdata. The next time you play the game you should then see pictures, etc.
  2. Magnetic Scrolls / Level 9: Put the multimedia files in the same directory as the game file (under Fabularium/Games). To avoid any issues with name clobbering (e.g. Level 9 games often have supplementary files called 1.PIC, 2.PIC, etc.) you can group game files in separate subdirectories under Fabularium/Games. E.g. for the game Gnome Ranger you might make a subdirectory Fabularium/Games/gnome containing the dat and pic files; another subdirectory Fabularium/Games/scapeghost might contain files for that game; and so on. You can call those subdirectories whatever you want.
  3. TADS: Fabularium supports resources that are bundled into one TADS file, but does not currently support TADS resources in separate files (typically ".rs0", ".rs1", etc.).

Also ensure you haven't disabled the GLK graphics / sounds gestalts in the settings menu!

By default, Fabularium's data is stored under one folder - Fabularium - in the top-most directory of your device's primary shared/external storage directory. In the settings we refer to this as the "root path". This folder contains fab.ini and all of Fabularium's generated log files (glk.log, fab.log, terp.log).

By default, there are are then a number of sub-folders under the "root path", arranged as follows:

If you don't like these default locations, you can change them in the settings menu (under File Management). You will need to specify absolute (complete) paths to the new folders. If you ever want to go back to the default settings, just leave the paths blank. PLEASE TAKE EXTRA CARE USING THIS OPTION AND ONLY OVERRIDE THESE SETTINGS IF YOU KNOW WHAT YOU ARE DOING!! In particular, while Fabularium goes to considerable lengths to check any path overrides, don't try to put your files in Android system folders, etc!! Unlike with the default paths, as a safety precaution Fabularium will NOT automatically create any non-default folders you specify - you will need to do that yourself. You will also need to migrate any existing data you want to continue using across to the new locations manually. Finally, to recreate the default config files, etc. in the new locations, run the "Reset config files" menu command.

Fabularium currently includes two compilers: Inform and Tads 3. They can produce games in three of the leading IF formats - zcode, glulx and tads3. Please see the Licences page to find more info about the awesome people behind these compilers (chiefly Graham Nelson, Andrew Plotkin and Mike Roberts).

It is beyond the scope of this short document to explain how to code IF games in detail, but this should help to get you started:

  1. Create a new project: Go to the EXPLORE tab and make a new folder under Fabularium/Projects. Then create one (in the case of Inform) or more (optionally for Tads 3) empty source files under that directory. These files must have an extension of ".inf" or ".t3". Then go to the CREATE tab and hit 'refresh'. You should see an icon for your project appear (if you do not double-check you have at least one source file with an extension of ".inf" or ".t3"). You can long-press this icon to change the compiler arguments, etc.
  2. Code, compile, test, code, compile, test...: Short-press the relevant project icon. Enter code into the source files. Save each file and choose 'build' from the text editor's menu. A message from the compiler will pop up telling you whether you were successful or not. Once you have got your game successfully compiling, you can test it by choosing 'run' from the text editor menu.

Here's a "Hello World" example to illustrate:

  1. Create a folder Fabularium/Projects/hello
  2. Create a file Fabularium/Projects/hello.inf
  3. Paste this source code into that file: 
    ! "Hello world" example program
[ Main;
  print "Hello world!^";
];
  4. Go to the create tab and hit refresh
  5. You should see a new project appear - "hello"
  6. Tap it, to open it in the IDE
  7. Compile it by tapping the build button - a message should pop up saying "Success Inform 6.34" - close the message
  8. Now run the game by choosing Run from the IDE menu
  9. You should see your game screen pop up, saying "Hello world!"

For more information on how to write games for these compilers, see the TADS 3 Technical Manual and the Inform Designer's Manual.

This feature of Fabularium is a work in progress. While the basic functionality is there, in future releases - if there is sufficient demand - I intend to make this component more user friendly.

Here are the permissions Fabularium needs and why:

  1. Read/write external storage: Fabularium requires this permission to work properly - to read and write games, save files, logs, transcipts, etc. You need to allow this permission if you want to use Fabularium.

Well come on then, help me squash it!

First some important background. When you play a game in Fabularium, four layers need to work in harmony:

  1. Game - e.g. Curses.z5
    A compiled program that contains byte code instructions and data.
  2. Terp - e.g. Bocfel
    The interpreter or "terp" is a virtual machine that is capable of runnning games in specific formats (e.g. Bocfel knows how to run zcode games). The terp sends output and display instructions to the next layer, GLK, and receives user input back from that layer. Because GLK sits between the operating system and the terp, the terp typically doesn't have to worry too much about the specifics of what system it is running on - from the terp's perspective it's all GLK (well in theory anyway). Fabularium currently includes around 14 different terps, which between them can run the vast majority of open IF game formats you are likely to come across.
  3. GLK - Fabularium
    The GLK layer, in this case Fabularium, receives input-output instructions from the terp and then works out how to implement them on the underlying operating system. For example the terp, after interpreting instructions in the game, might tell Fabularium to make a window and then display some text in it. The terp doesn't worry about how that happens, that's Fabularium's job.
  4. Operating System - Android
    The final layer is the actual operating system, which in the case of Fabularium is Android.

Now, if something goes wrong, it could be due to a bug in any of these four layers. The least likely culprit is the terp. All of the terps included in Fabularium are mature code, developed over many years and now considered very stable. That leaves the other three. If the game is more mature, well-known and extensively tested, it's highly unlikely to be the culprit either, so in such cases it's probably Fabularium's fault. But don't entirely rule out bugs in Android either.

So what sort of information would help me to isolate and fix the problem? Well, aside from recording the config settings you were using and what you were doing immediately before the issue occurred, you should also look at the log files of your play session, located in the Fabularium folder - glk.log and terp.log. These log files are regenerated every time there is a playthough:

  1. glk.log contains messages from Fabularium's GLK layer, generated while you are playing a game, which explain what is going on under the hood and any problems Fabularium encounters. For example, occasionally a terp / game may make an invalid request, such as asking Fabularium to print text to a window that doesn't exist. Fabularium goes to considerable effort to manage and recover from such issues gracefully, but there may be rare occasions where recovery is impossible and the playthough must terminate.
  2. terp.log captures messages generated by the terp, as you play the game. If you encounter a problem, and that problems stems from the game itself, hopefully the terp will leave an explanatory message in this file before everything falls apart.

Once you have as much of this info as possible, please email me at tcowperapps@gmail.com to tell me about the issue. I want people to enjoy using this app and I hate bugs. The most frequent and informative bug reporters shall be immortalised in the Credits screen! :-)

I'm glad you feel that way. A lot of hard work has gone into it, not just from myself, but also from all of the generous people who wrote the terps, compilers and libraries that Fabularium incorporates and builds on. See the licences screen for more info.

And let's not forget all those generous authors who write interactive fiction and then freely distribute it for people like you and me to enjoy.

Fabularium is actually my way of saying a big thank you to these people after many years of enjoying the fruits of their labours.

If you want to give something back, here is what you can do:

  1. If you like a particular game (e.g. Blue Lacuna) or interpreter (e.g. Alan), track down its author and tell them so. Or write a review on one of the IF websites. Or consider donating. While for simplicity's sake we often refer to works of IF as "games", many authors see IF as an art form and, as with most artists, they like to know that their art is evoking a reaction, even if they make little or no actual money out of it.
  2. If you like Fabularium, please consider rating it in the Google Play Store - or wherever else you downloaded it from. Good ratings: (a) increase search rankings, helping other people to find the app; and (b) motivate the app's author to continue improving it. :-)