@nicetouch/yarn-bound

What is YarnBound?

Yarn is a language for writing dialogue trees.

YarnBound attempts to be the simplest way to use the Yarn language in the context of a javascript application. It is a wrapper around a specific forked version of bondage.js, where effort has been made to comply with the Yarn 2.0 spec.

Quality-of-life features on top of bondage.js:

• A simpler API
• History of previous Results
• Option to return text and a subsequent options block together as one result
• Option to run a custom command handler function instead of returning a CommandResult
• include an isDialogueEnd property with the last Result in a dialogue

Bondage.js also does not support

• Character: some text annotation
• [b]Markup[/b]

because these are not language features (it's confusing). YarnBound adds these things.

The only thing I know to be missing from the spec and non-unity-specific docs (at time of Yarn 2.0's release) is the built-in wait command, because I can't tell what I would want it to do.

Usage

Install with npm i -S yarn-bound or grab yarn-bound.js from the /dist/ folder.

For information on how to write Yarn, visit the official documentation. Start there! YarnBound is useful after you have a yarn dialogue written and in string format. It's worth skimming the Yarn language spec as well.

To get started with YarnBound, import and create a new instance.

import YarnBound from 'yarn-bound'
// or node:
// const bondage = require('yarn-bound')
// or in a script tag:
// <script src="path-to-file/yarn-bound.min.js"></script>

const runner = new YarnBound(options)

You can then access the first Result with:

runner.currentResult

To continue the dialogue, call advance().

runner.advance()
runner.currentResult // is now the next Result

If you were on an Options Result, you would call advance() with the index of the desired option.

runner.advance(2)
runner.currentResult // is now the Result after the selected option

You can also call jump() with the title of a node to jump directly to that node. This allows for external control over the story flow.

That's all there is to the basic operation!

Available Options

dialogue (required): string - The Yarn dialogue to run. A .yarn file in string form.

startAt: string: - The title of the node to start the dialogue on.

• default: "Start"

functions: object - An object containing custom functions to run when they are called in a yarn expression.

• As the Yarn docs mention, these should not have side effects. They may execute at unexpected times.
• You can also use runner.registerFunction(key, func) after initialization.

variableStorage: object - A custom storage object with get() and set() functions (a new Map(), for instance.)

• Unless you have a specific need you can omit this and use the built-in default.
• One use is supplying variables with initial values, though you could also do that in the dialogue.

handleCommand: function - If you provide this, YarnBound will advance() right past Command Results, instead calling handleCommand() with the Command Result as the single argument (see below for the data structure).

combineTextAndOptionsResults: boolean - If this is true, a Text Result followed by an Options Result will be combined into one Options Result with a text property.

• This is convenient if you want to show prompts and responses at the same time.

locale: string - Used for pluralization markdown attributes.

Results Data

Results, found on runner.currentResult, come in three flavors:

• TextResult
• OptionsResult
• CommandResult

You can tell which kind it is by using instanceof

runner.currentResult instanceof YarnBound.TextResult

runner.currentResult instanceof YarnBound.OptionsResult

runner.currentResult instanceof YarnBound.CommandResult

A TextResult looks like this:

{
  "text": "This is a line of text.",
  "hashtags": ['someHashtag'],
  "metadata": {/* see below */}
}

If it is the last Result in the dialogue, there will also be a isDialogueEnd property with the value of true.

An Options Result looks like this:

{
  "options": [
    {
      "text": "Red",
      "isAvailable": true,
      "hashtags": []
    },
    {
      "text": "Blue",
      "isAvailable": true,
      "hashtags": []
    }
  ],
  "metadata": {/* see below */}
}

If combineTextAndOptionsResults is enabled, there could be a text property on the Options Result. advance() from it with an option's index as usual.

A Command Result looks like this:

{
  "command": "someCommand",
  "hashtags": [],
  "metadata": {/* see below */}
}

It could also have a isDialogueEnd property on it. Command Results are handled and skipped through when a handleCommand function is supplied.

Every Result contains metadata which includes node header tags including title, and also any file tags.

  {
    "title": "StartingNode",
    "someTag": "someTag",
    "filetags": [
      "someFiletag"
    ]
  }

Full example

Let's start with this code:

import YarnBound from 'yarn-bound';

// empty lines and uniform leading whitespace are trimmed
// so you can write your nodes in template strings neatly.
const dialogue = `
  title: WhereAreYou
  ---
  Where are you?
  -> Home
    Nice.
    <<doSomething home>>
  -> Work
    Rough.
    <<doSomething work>>
  That's it!
  ===
`

const runner = new YarnBound({
  dialogue,
  startAt: 'WhereAreYou'
})

When we log out runner.currentResult above, we will get a TextResult with the text "Where are you?"

to continue, we call

runner.advance()

and runner.currentResult will be an OptionsResult with an options array with two objects in it. One object's text property is "Nice" and one's is "Rough". We will choose "Nice" by calling:

runner.advance(0)

Now, runner.currentResult is a CommandResult where command is "doSomething home".

runner.advance()

One final TextResult, but this time isDialogueEnd is true.

If combineTextAndOptionsResults was true, the first value for runner.currentResult would be the same OptionsResult as above, but with a text property that says "Where are you?".

If a handleCommand function was supplied, it would be called and we would skip straight from the OptionsResult to the last TextResult.

Functions

If you are supplying a functions object, it would look like this:

const runner = new YarnBound({
  dialogue,
  functions: {
    someFunction: (arg) => {/* do stuff */},
    someOtherFunction: (arg1, arg2) => {/* do other stuff */},
  }
})

History

An array containing Results already visited is located at runner.history.

React Component

A simple react component can be found at: react-dialogue-tree

Caveats

When a handleCommand function is supplied, ending a dialogue with a command or set of commands can cause unexpected behavior. Any commands at the end of the dialogue will be handled upon reaching the last non-command result (usually, a command will only be handled when advancing past the previous non-command result). This is furthermore a problem when ending the dialogue with a command inside a conditional:

Dialogue Ending With Conditional

The lookahead feature won't handle commands or set variables, so a dialogue like this will behave inconsistently:

<<set $a = false>>
Hello
<<set $a = true>>
<<some command>>
<<if $a == true>>
  Goodbye
<<endif>>

When processing the "Hello" TextResult, the lookahead feature will detect the end of the dialogue because it will see if $a == true evaluate to false, since it hasn't.

Thinking that the dialogue is over, it will try to handle any trailing commands, actually doing the variable setting and this time reaching the if $a == true block.

YarnBound will correct itself and not include the isDialogueEnd flag prematurely, but any side effects performed by setting the variable and handling the command will have already happened. This can cause bugs!

It is suggested to avoid this pattern. But if you must use it, or prevent lookahead for any other reason, there is a special <<pause>> command you can use:

<<set $a = false>>
Hello
<<set $a = true>>
<<some command>>
<<pause>>
<<if $a == true>>
  Goodbye
<<endif>>

Note that you will have to call advance() again after reaching the pause command. Even if you have supplied a handleCommand function, runner.currentResult will be a CommandResult, with a command of "pause".

Also note, however, that a "pause" command at the end of a dialogue will never have the isDialogueEnd flag, as lookahead is disabled.

Other included versions

A minified version exists at yarn-bound/dist/yarn-bound.min.js.

If you want to transpile for yourself, use import YarnBound from 'yarn-bound/src/index' and make sure your transpiler isn't ignoring it. You will also need to transpile @mnbroatch/bondage, and include both in your bundle, if necessary.

A version compatibile with internet explorer is at yarn-bound/dist/yarn-bound.ie.js.