User Tools

Site Tools


Sidebar

Passage markup

basics

coding

extra

list

section

whitespace

Macros

basics

colour

data structure

date and time

game state

live

maths

number

revision

saving

showing and hiding

string

styling

url

deprecated

Types of data

Special keywords

Special passage tags

harlowe:cycling-link

This is an old revision of the document!


(cycling-link: Bind], …String) → Command

A command that, when evaluated, creates a cycling link - a link which does not go anywhere, but changes its own text to the next in a looping sequence of strings, and sets the optional bound variable to match the string value of the text.

Example usage:

  • (cycling-link: bind $head's hair, "Black", "Brown", "Blonde", "Red", "White") binds the “hair” value in the $head datamap to the current link text.
  • (cycling-link: "Mew", "Miao", "Mrr", "Mlem") has no bound variable.

Rationale:

The cycling link is an interaction idiom popularised in Twine 1 which combines the utility of a dial input element with the discovery and visual consistency of a link: the player can typically only discover that this is a cycling link by clicking it, and can then discover the full set of labels by clicking through them. This affords a number of subtle dramatic and humourous possibilities, and moreover allows the link to sit comfortably among passage prose without standing out as an interface element.

The addition of a variable bound to the link, changing to match whichever text the player finally dialed the link to, allows cycling links to affect subsequent passages, and thus for the link to be just as meaningful in affecting the story's course as any other, even though no hooks and (set:)s can be attached to them.

Details:

If one of the strings is empty, such as (cycling-link: "Two eggs", "One egg", ""), then upon reaching the empty string, the link will disappear permanently. If the first string is empty, an error will be produced (because then the link can never appear at all).

If attempting to render one string produces an error, such as (cycling-link: "Goose", "(print: 2 + 'foo')"), then the error will only appear once the link cycles to that string.

The bound variable will be set to the first value as soon as the cycling link is displayed - so, even if the player doesn't interact with the link at all, the variable will still have the intended value.

If you want to include the current value of the bound variable in the link's series of strings, simply refer to it directly after the bind: (cycling-link: bind $hat, $hat, "Beret", "Poker visor", "Tricorn") will place $hat's current value in the series, and, as the first value, it will harmlessly overwrite $hat with itself (and thus leave it unchanged). Additionally, if you have an array of strings that you'd like to reuse for the same cycling link in multiple passages, say as (set: $allHats to (a: "Helmet", "Beret", "Poker visor", "Tricorn")), and you'd like each cycling link to start on whatever matching value is currently in $hat, simply first provide $hat as the first value, then follow it with $allHats with $hat removed: (cycling-link: bind $hat, $hat, ...($allHats - (a:$hat))). (Note that this doesn't preserve the order of $allHats relative to $hat, however.)

If only one string was given to this macro, an error will be produced.

harlowe/cycling-link.1555393855.txt.gz · Last modified: 2019/04/16 01:50 by l