This posting may take more explanation than usual.

Undum is a great open source hypertext (or interactive fiction, if you will) engine for creating stories that allow reader choices and unfold over time. A bit like a web-optimized Choose Your Own Adventure(tm).

Guard fields are a feature from the Eastgate StorySpace engine, which allow a richer form of linking. They’re described as follows:

Guard fields act like sentries, allowing readers to follow a link only if they meet specified conditions. Guard fields are valuable when you want the Storyspace web to change as the reader proceeds through the text.

Guard fields effectively split an entire hypertext fiction into “alternate universes”, producing a result that can’t be reasonably reproduced in printed form; not even the CYOA conceit of “if you choose X go to page Y” is sufficient. Your reading of the story contains state information.

Back to Undum: this is an object-oriented system. For what hypertext authors call “nodes” or “lexia”, Undum uses a Situation object. As you progress through the story, you move from one Situation to the next. Entering and leaving a situation trigger events, for which you can supply a JavaScript function. There also exists a single Character object (that’s you) which can accumulate state.

Step one is a global Situation-enter handler that stores the name of the just-now-visited Situation in a steadily-growing list. = function(chr,sys,frm,to) {
if (to.charAt(0) != '-')
sys.setCharacterText("<p>" + prettify(to) + "</p>");

At any point, we can easily test whether a node has been visited by looking through the list:

var seen = function(name,chr) { return $.inArray(name,chr.sandbox.visited) >= 0; }

In the code, we also construct a list of situations, each of which pulls the actual story text from a uniquely named div element. A typical situation gets built like this:

start: new undum.Situation({
enter: function(chr,sys,frm) { sys.write($("#node-start").html()); }

but those that involve guard fields, which by convention start with a hyphen character, can involve logic, like this:

"-conditional-link": new undum.Situation({
enter: function(chr,sys,frm) {
if (seen("secret-node",chr))
sys.doLink("tragicending"); }

With this, when the system encounters a link to “-conditional-link”, which situation that leads to depends on which Situations you’ve previously visited. That’s just the beginning: much more rich and complicated possibilties are out there.

I, the author of the JavaScript code in this posting, hereby contribute it to the public domain. Have fun with it. Let me know if you have questions.