Ramus 2.2 manual

Please enable Javascript to play.

Ramus is a template for hypertext fiction or games self-contained in a single web page. Emphasis on template: to make your own, simply replace the content of an existing document. As long as certain elements are left in place, it should continue to function as before.

You need to know HTML to work with Ramus. It's not for everyone.

As of 17 April 2020, this manual is a work in progress. Please excuse the mess.

Ramus documents are made of many little fragments, usually simple div elements. All they need to have is an ID, so you can point links at them. In Ramus 2.1, links had all the power.

That changed in version 2.2 with the addition of a little scripting language, that also hijacks standard HTML elements (and also with the option of leaving them alone if you say so).

The only mandatody elements in a Ramus document are some sort of container with "transcript" as ID (you can change that, see below) and the script at the end. You'll also want a hidden section to keep the story fragments until they're needed. There should be at least one such fragment with "start" as ID (you can change that also, at the top of the script).

As of version 2.1, there's also an optional status line that can be used to keep track of progress if at all desirable. Last but not least, Ramus now keeps track of visited fragments.

The script is short enough to fill two sheets of paper on both sides, and should be the last thing in the file, so you can copy it elsewhere easily.

The status line is in fact comprised of three separate elements, whose IDs are "status", "moves" and "score", respectively. They can be placed anywhere in the document, or even removed entirely. Here's how they work:

The status text is taken from the title element of each story fragment as it's visited, if one is present at all; otherwise it's not changed.

The move counter is incremented every time the player follows a link.

The score is incremented whenever the player visits a passage with the data-score attribute.

Scoring requires a relatively modern browser to work.

Ramus keeps track of which story fragments were already visited, and adds the "visited" or "unvisited" class to their containers as they are displayed. You can use styling to show or hide parts of them accordingly.

This feature requires a relatively modern browser to work; otherwise visits will still be noted, but without any visual changes.

As of version 2.2, Ramus includes a little scripting language. It's kind of clunky and doesn't have a name yet. The goal was to make something easy to use while keeping Ramus not too large. Here's a small sample: 


	<s>set a 1</s> <s>echo $a</s>
	<s>test $a = 1</s>
		<s>iftrue echo Is too!</s>
		<s>iffalse echo Is not!</s>

Each command is contained in an <s> tag, and can appear anywhere in a story fragment; the command's output will replace its text at that point. Be careful where you put an include command.

(Note: you can still use an <s> tag for its intended purpose by giving it an attribute, for example some dummy class.)

Speaking of which, each command is made of words separated by whitespace. The first word says what built-in function to call, and the rest are passed to it as arguments: 

command (arg) (arg) ...

Arguments that start with a dollar sign ("$") are looked up as variables in an internal dictionary. Javascript variables are not directly accessible. Numeric arguments are parsed accordingly. This happens before calling the function.

Beware that few checks are performed on commands. Results may be silently wrong. This is so the story keeps working instead of stopping the player cold. Check the browser console for warnings to make sure.

Scripts should work in any browser released from 2011 onward.

As of version 2.2, there are six built-in functions in Ramus:

Use set to, well, set variables: 

<s>set a 10</s> <s>set b $a</s>

With echo you can display their values to the player: 

<s>echo Right now, a is $a and b is $b</s>

You can display a whole other fragment with include: 

<s>set choice left-path</s> <s>include $choice</s>

Included fragments are scored, marked as visited and parsed for scripts, but their title attribute (if any) is ignored.

test checks if a condition is true and sets an internal flag accordingly: 

<s>test $b = 10</s>

test doesn't support full arithmetic expressions, but only a few checks and comparisons.

Last but not least, iftrue and iffalse look at the internal flag set by test and run the rest of their arguments as a command, but only if the flag is true or false, respectively: 

<s>iftrue echo Is too!</s> <s>iffalse echo Is not!</s>

If test couldn't perform the check for some reason, neither branch is taken.

That's about it for now. Start over?

The general syntax of test is as follows: 

test operand1 comparison operand2

Where comparison can be one of = (or ==), !=, <, <=, > or >=. Note that you can't actually write a literal "<"/">" in HTML code, it has to be "&lt;" and "&gt;" instead, respectively.

Apart from that, there's one other form: 

test visited fragment-id

which does just what it seems to. The fragment id doesn't start with a hash sign, but can be stored in a variable just fine.