# Guard Fields

Storyspace links have guard fields – expressions that determine whether the link may be followed at the current moment. Guard fields let some links change behavior depending on what the reader has seen and done earlier in the reading, and are indispensable to large hypertext narratives.

If the guard field is satisfied, the link may be followed; if not, the link is ignored and another link, if any, will be followed.

For additional background on guard fields and their use, see Getting Started With Hypertext Narrative.

New users are advised to skip the next section and go direct to “New Guard Fields” further below so as to start using current syntax. Existing users with old documents should consider revising old code to the current form to ensure ongoing compatibility.

### Traditional Guard Fields

Storyspace 3 fully supports the traditional guard field syntax used in previous versions of Storyspace.

Guard fields may test for the word on which the user clicked, even if that word has no text link. The guard field

> Nearly

will be satisfied if the user clicks on the word “Nearly” or “nearly” - note the match is case-insensitive. Guard fields may also test for whether the user has previously visited a writing space.

> “Prologue”

will be satisfied if the reader has visited the writing space named Prologue. Conditions may be combined;

> "Prologue"|"William"

will be satisfied if the reader has visited either Prologue or William.

> "Prologue" & nearly

will be satisfied only if the user has clicked on the word “nearly” and has already visited Prologue.

When Storyspace 3 reads a document that was composed in a previous version of Storyspace, it automatically identifies traditional guard fields thus:

> `guard(...traditional guard field...)`

If you wish, you may write new guard fields using this syntax as well. For example, a link with the guard field

> `guard("Prologue")`

will be followed only if the reader has already visited the prologue.

### New Guard Fields

In Storyspace 3, a guard field is a Tinderbox expression to be evaluated. If the result is false, the empty string, the date never, or the number zero, the guard field will not be satisfied. If the result is any other value, the guard field is satisfied.

When evaluating guard field expressions, the following keywords are bound:

> source

> destination

> this (bound to the link’s source)

Traditional guard fields may also be used by passing the traditional guard field without any additional quotes as the argument of the guard function:

> `guard(Prologue)`

is satisfied in the reader has clicked on the word “Prologue”.

> `guard("Prologue")`

is satisfied if the reader has visited the note named “Prologue”.

In addition, the source’s $ChosenWord will contain the most recently clicked word, if any.

New Syntax

In Storyspace 3, a guard field may use any Tinderbox expression. For example

> `$Visits("the castle")`

is true only if the note named "the castle" has been visited at least once, and

> `$ChosenWord=="ambition"`

is true only if the reader clicked on the word “ambition”. Testing the $ChosenWord value replaces the legacy form of testing guard(). Thus the following codes to the same thing but the second form is recommended this:

> `guard(ambition)` Old syntax: works but now deprecated.

> `$ChosenWord=="ambition"` Current syntax: recommended.

Some new convenience functions have been added to make guard fields easier to read and write. The expression

> visited("the castle")

is true if $Visits is greater than zero -- that is, if the note named the castle has been visited in this reading. Conversely,

> `unvisited("the castle")`

is true if $Visits is greater than zero. The shortcut

> `unvisited()`

is true if $Visits(destination) – the number of visits to the destination of the link, is zero.

The new syntax is clearer and more flexible. For example, the link

> `visited("the castle") & $Health(/characters/hero)>10`

if true only if the reader has visited the castle at least twice and if the hero’s health is at least 10. Here, we assume $Health is a numeric user attribute, and the note /characters/hero is used to keep track of the current status of the hero.

In map view, links with guard fields are distinguished by a small diamond, about a quarter of the way along the link. If the guard field is satisfied, the diiamond is solid; if the guard field is not satisfied, the diamond is hollow.