home yarn

This is a description of the Javascript API of yarn.

Configuration Variables

These should be set in the game header (before any named passage).

info.start

The name of the passage to start on when beginning a new game.

info.title

The title of the game, which, if given, will be put in the menu.

info.author

The author's name, which, if given, will be put next to the title in the menu.

info.restart

If true (which is the default), a restart link will be displayed in the menu.

Note: Without a restart link, the player will not be able to restart the game unless you provide a restart link (which currently isn't a simple task) in an accessible passage, or by manually deleting the save data cookie.

debug

Setting this to true will enable debug behaviors:
- there is no confirmation on the 'restart' menu item
- the debug panel is visible (a box for jumping to a different passage, the current save data values)

linksilly

If set to true, reverses pipelinks: links will be of the form [[display text|destination]] (twine) instead of the normal [[destination|display text]] (wikipedia).

fadeLength

The duration, in seconds, of the fade-in at the beginning of each passage.

Game Variables

save

The object which holds persistent data. When a user returns to the game page, this object is automatically restored from a cookie. Everything else (info, script globals, etc.) will be reset as if the game were newly loaded.

$ save.coins = 42;
$ save.inventory = ['bear', 'soup', 'onion'];

The wind picks up.
$ if (save.havecoat) write("It's a good thing you brought this coat along.");
$ else write("You start to shiver as the wind strips your body of its heat.");

The data may be anything that is JSON-serializable.

Functions

write(arg) -> null

Adds one or more lines to the current passage. arg is optional, and may be a string or a list of strings. Strings will be split on the newline character ('\n'). E.g., passing 'two\nlines' is the same as passing ['two', 'lines']. If arg is omitted, it is treated as if it were the empty string (''), which produces a blank line.

display(name) -> null

Show the named passage, without clearing anything written so far. This is used to include other passages in the current one.

Example:

:: one
in passage one

:: two
in passage two
$ display('one');
back in passage two

which looks like (with the player starting at passage 'two'):

in passage two
in passage one
back in passage two

randint(a, b) -> r

Return an integer between a and b, inclusive.

setColors(fg, bg) -> null

Set the foreground and background colors of the page. The arguments should be CSS colors.