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 cloak.org for basic structure (pending a proper tutorial).
- TODO/DONE states are parsed but ignored.
- Tags are parsed and preserved, but don't do anything yet.
- Ramus 2 recognizes the following special lines: TITLE, AUTHOR, DATE, EMAIL, LANGUAGE, and additionally SUBTITLE, URL, GENRE, CRUELTY, LICENSE, IFID. Not all are implemented as of April 2017.
- The OPTIONS special line is also parsed but ignored at this time.
- Inline formatting (bold/italic) is supported, but only for whole lines.
- Comment lines are recognized and skipped.
- Not supported: links, tables, date fields.
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
: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.
- label: sets a label for a jump, so you can reach that passage other than by explicit choice.
- goto: after displaying the body text of the current passage, ignore any choice here and jump to the passage with the given label instead.
- prompt: instead of jumping immediately as above, display a choice with the given text, that the player can take; this is so you can have "read more" passages.
- set: set the given flags if they didn't exist already. Flags are separated by whitespace, and global to the entire story.
- unset: unset the given flags if they happen to exist.
- show-if: only present this passage as a choice if all the given flags are set. This is cumulative with
- show-unless: only present this passage as a choice if none of the given flags are set. This is cumulative with
- status: override the left-hand side of the status line for this passage (by default it's the last choice you picked).
- title: show the given text in a standout style before the body of the passage.
- image: try to show the given URL as an image between the title (if any) and the body text.
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
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.
- validator and bundling tool;