Play demo game

Ramus 2 is an interactive fiction authoring system that takes its input from Org Mode files such as those created by Orgzly for Android. Now you can make CYOA with the same tool that handles your agenda, to-do list or the outline of your next novel. Not only that, but you can do it on the go, even when the Internet is down!

At its simplest, Ramus 2 consists of an interpreter that takes an ordinary .org file and treats it as a text adventure. The results may be nonsensical if you try it with a project planning file, for instance, but it will work all the same. The format itself is text-based and human-readable: you can write stories with any programmer's editor if for some reason you can't or won't use the aforementioned apps. All you lose is some convenience.

As of January 2019 a Ramus 2 adventure can be bundled with the skeleton interpreter to make a stand-alone web page.

Downloads and license

Ramus 2 is free and open source software under the Artistic License 2.0; see the included text file for details.

When the Ramus 2 interpreter is bundled with a story file of your own making, the resulting web page belongs to you. Set terms as desired. Beware however that anyone can still use it to open and play any other story file, or even remove your data to produce a pristine copy of the interpreter. The latter would then fall under the Artistic License 2.0 again.

A similar principle applies to the command line interpreters.

Tips for Org Mode users

See the example adventure for basic structure (pending a proper tutorial).

Node properties

While you can write a Ramus 2 story file as a simple hierarchy of passages, that yields a highly formulaic kind of CYOA known as the Cave of Time structure, with many short playthroughs that never intersect. To do anything more advanced, you will need to add properties. That's easy to do in Orgzly: simply open a note and tap the Add Property button. If you're using a text editor, it's a bit more involved.

Consider the following start of a game:

My, are you hungry right now. Got to grab a bite or else.

* Head to the kitchen
:set: hungry broke

A thorough search fails to turn up anything edible in the fridge.

Note the text right after the headline, from :PROPERTIES: to :END:. That's called a "property drawer" in Org Mode parlance; each intervening line consists of a property name between colon signs, followed by the property value (which ends at the first newline character). There can't be any other content between the headline and its property drawer, not even a blank line.

(Actually Ramus 2 is more tolerant than that; other tools aren't.)

There are several effects you can achieve with properties: set a label for a jump (and jump to it), set or unset flags, and condition the display of a choice on the existence and/or absence of certain flags. You can also override the status line, and give the passage a title, if not an illustration.

Supported properties

Note that while you can't have changing text within a passage, you can have multiple passages with the same headline, but with mutually exclusive conditions, so the player will only ever be offered one or the other as a choice. This is how you present alternate outcomes in Ramus 2.


In addition to the content proper, a Ramus 2 story file can contain metadata: information about the work itself, such as the title and author. These are shown when first loading a story file, if they are present at all.

Metadata in Ramus 2 always takes this form:

#+TITLE: An Interactive Fiction
#+AUTHOR: Anonymous

Field names must be in all caps, and the value must follow on the same line. These special lines can appear anywhere in the file, but it's best to put them at the beginning. In case of duplicates, the last occurrence is kept.

Ramus 2 supports all the special lines recognized by Org Mode: TITLE, AUTHOR, EMAIL, DATE, LANGUAGE and OPTIONS. It also supports metadata specific to interactive fiction: SUBTITLE, URL, GENRE, CRUELTY, LICENSE, IFID. Most of them are normally empty; "title" and "author" default to the values given above.

The language should be an ISO code such as "en-US". Org Mode options are ignored.

Intro to IFIDs

The IFID is the interactive fiction equivalent to an ISBN, except instead of being handed out by a central authority, it's generated by a computer algorithm that does its best to ensure no two numbers are ever the same. If you don't have one, don't worry too much about it. If you want one anyway, there's an IFID generator over on the TADS website.

To do