Documentation

WOOL is a platform for authoring and executing dialogues between virtual characters and humans in Java or JavaScript applications. The platform is completely open source, and licensed under the permissive MIT License. You can find all the latest source code on our GitHub Page:

WOOL on GitHub: www.github.com/woolplatform

The GitHub project is currently hosting the following two repositories:

On this page we are working to collect various documentation resources.

What is the WOOL Platform?

At its core, WOOL is a language definition that can be used to write interactive dialogue. The WOOL platform consists of (1) the dialogue language definition, (2) a powerful editor for creating dialogue scripts, and (3) a set of tools to execute these dialogues within your application (currently supporting Java and JavaScript-based applications).

The documentation below is thus structured as follows:

  • WOOL Language Definition
  • Using the WOOL Editor
  • Tools for creating WOOL applications:
    • Java Tools
    • JavaScript Tools

WOOL Language Definition

Table of Contents

1. Basics & Terms

A WOOL dialogue definition is essentially a definition of a series of dialogue steps (that we refer to as nodes) linked together through user replies.

We define the following terms:

  • Node — A dialogue step that contains one Statement and a one or more Replies.
  • Statement — Something an agent says.
  • Reply — A possible reply that a user of the system can give.
  • Agent — A virtual speaker within a dialogue.

2. WOOL Nodes

A Node consists of two parts, a header, and a body.

2.1. Header

The header consists of a series of lines, each with a {key: value}-pair. The two required key-value pairs are:
  • title — a String that uniquely identifies this Node within this WOOL dialogue.
  • speaker — a String that defines the name of the Agent speaking in this Node.
Note: this is a major difference from Yarn. In WOOL, each node represents a single step in a dialogue, and thus belongs to a single speaker (whereas Yarn allows multiple speakers and statements in the same Node).

You are free to define other key-value pairs that might serve as meta-data in your application. The WOOL Editor uses the following additional ones:

  • colorID — a number between 0 and 9 specifying a colour. This is also used by the editor's run feature to allow multiple backgrounds, one for each colorID.
  • position — used to position the nodes in the editor.

Below is an example of what this looks like in a .wool file:

title: Start
speaker: Robin
position: -416,112
colorID: 3

2.2. Body

The body of a Node contains at least one Statement and zero or more Replys. A very basic example is given below:

Hello, my name is Robin!

[[Nice to meet you Robin!|NodeRobin2]]
[[Goodbye.|NodeEnd]]

This Node defines a Statement "Hello, my name is Robin!", uttered by the Agent "Robin" and two possible Reply options. When a user selects "Nice to meet you Robin!" he will be forwarded to a Node labeled "NodeRobin2", and when he selects "Goodbye." he will be forwarded to the Node labeled "NodeEnd".

2.3. File Format

A .wool file consists of a list of concatenated Nodes separated by === markers. The header and body of the Node are separated by the --- line. For example:

title: Start
speaker: Robin
position: -416,112
color: cyan
---
Hello, my name is Robin!

[[Nice to meet you Robin!|NodeRobin2]]
[[Goodbye.|NodeEnd]]
===
title: NodeRobin2
speaker: Robin
position: -216,112
color: red
---
Nice to meet you too, how are you doing?

[[I am fine and you?|NodeRobin3]]
[[Goodbye.|NodeEnd]]
===
...

2.4. Comments

If you want to document your WOOL scripts with comments, WOOL Supports line-comments. Everything after a double-slash // is considered a comment:
Robin: Thank you very much. // Thank the user for the gift.

// If it was a nice gift...
<<if $giftNice >>
   ...

3. WOOL Dialogues

A series of WOOL Nodes is called a WOOL Dialogue. The following rules apply to WOOL Dialogues:

  • All Node title's must be unique within a WOOL Dialogue.
  • There must be one Node with the title "Start" (this is the default starting point of the dialogue).
  • WOOL Dialogue files may contain letters, numbers, dashes and underscores, and end with .wool, valid examples include:
    • mydialogue.wool
    • my-dialogue.wool
    • my_dialogue-1.wool
    • 123dialogue_for-Robin.wool

3.1 Starting a Dialogue

Every WOOL Dialogue script must include a Node with title "Start". Applications that execute WOOL scripts can choose this as the default starting node for a conversation (or ignore it, and start somewhere else). For example:

title: Start
speaker: Robin
position: -416,112
color: cyan
---
Hello, my name is Robin!

[[Nice to meet you Robin!|NodeRobin2]]
[[Goodbye.|NodeEnd]]
===

3.2. Ending a Dialogue

There are two ways a WOOL dialogue can end:

  • The user doesn't have any Reply options in the Node (the Agent has the last say).
  • The user chooses a Reply option that leads to a Node with title "End" (user has the last say).

Example 1:

It was nice talking to you, bye!

Example 2:

Do you have any other questions?

[[I have nothing left to say.|End]]

Unlike the "Start" Node, the "End" Node is not mandatory to include in your WOOL Dialogue, as there are other ways to end the conversation. There is also nothing stopping you from creating a dialogue that can only loop indefinitely. When creating WOOL-based applications, you can also choose to provide a User Interface element that can "cancel" a dialogue at any time.

Note: the node with the Title "End" is thus treated as a special case. When other nodes refer to it, this Node should be created in the dialogue as usual, however its contents must be empty. When the "End" node is reached in a WOOL Dialogue, the application should simply "close" the conversation. The special meaning of Nodes titled "Start" and "End" is different from Yarn, and are marked as such in the WOOL Editor.

4. WOOL Statements

Ultimately, every WOOL Node should output some text to display to the user, but WOOL Statements allow for a lot of flexibility in structuring and personalizing your dialogue.

4.1. Basic Statements

The most basic Statement is a simple line of text, that is uttered by the speaker (Agent) of the Node:
Hello, how are you?

4.2. Basic Statements with Variables

You can use variables within your Statements. Variables start with a $-sign, followed by one of A-Z a-z and then any number of a-z A-Z 0-9 or _ (underscore). In short: start with a letter, then use letters, numbers or underscores, for example:

  • $variableName
  • $variable_name
  • $var123

These variables can be used within Statements to inject their values into a sentence, like so:

Hello $userFirstName, how are you?

4.3. Basic Statements with Special Characters

What if you actually want to include a $ character in your text? If it's not followed by A-Z a-z, you can just type $. But otherwise you can escape it with a backslash: \$. And to include a backslash? Just escape it with another backslash: \\. In fact you can escape any character with \ and it will not be treated as a special character. Some more examples: \<< \>> \[[ \]]

4.4. Basic Statements with Markup

For the rest, WOOL doesn't care about any markup you might want to apply, if you want to add HTML tags around text, please go ahead. The parsers will ignore it, and simply output the text including markup to your application:
Hello <b>$userFirstName</b>, how are you?

4.5. Control Statements: Setting Variables

WOOL allows you to set variables using the <<set>> Statement:

<<set $userFirstName = "Bob">>
<<set $points = 0>>
<<set $hasReplied = true>>

The example above shows the three most common cases for setting either String, number or boolean variables. However, WOOL is much more flexible, and allows for example the set-Statements below:

<<set $points = $points + 1>>
<<set $name = $firstname + " " + $lastname>>
<<set $string = "String" + 12345>> // $string is set to "String12345"
<<set $string = 1 + 2 + "3">> // is parsed from left to right, $string = "33"
<<set $string = 1 + (2 + "3")>> // using brackets, resulting in $string = "123"

As you can see, you don't have to define the type of the variable manually. Be careful when using more complex statements though. For example, when trying to add up numbers with Strings, WOOL will treat the result as a String.

4.6. Control Statements: Conditionals

WOOL supports if-then-else Statements. The simple example:

<<if $dayPart == "Morning" >>
   Good morning ladies and gentlemen!
<<elseif $dayPart == "Afternoon" >>
   Good afternoon peoples!
<<else>>
   Good evening everyone!
<<endif>>

Please note that "==" is treated as strictly-equals.

WOOL also supports nesting these if-statements, if needed:

<<if $dayPart == "Morning" >>
    <<if $userFriendly == true>>
        Good morning, sir! How are you today.
    <<else>>
        Mornin'.
    <<endif>>
<<elseif $dayPart == "Afternoon" >>
   ...

Note that in the case of boolean variables ($userFriendly), you can leave out the " == true" part. E.g. the following is valid and will work as expected if $userFriendly is an actual boolean value:

<<if $userFriendly>>

However, if $userFriendly is actually a String with value "No, he is not friendly.", this expression will evaluate to true. If the variable is empty (or "unset"), the expression will evaluate to false.

Be careful with using the short-hand form <<if $variableName>>, because it is not strict, while for example <<if $variableName == false>> is strict. This means that if the variable $variableName has not been assigned a value, the following will happen:

  • <<if $variableName>> will evaluate to false
  • <<if $variableName == false>> will also evaluate to false (which may be counter intuitive)

If in your application you cannot be sure whether or not boolean variables have been assigned a value, our advice is to always use <<if $variableName == true>>, to avoid confusion.

4.7. Control Statements: User Interface Actions

Sometimes you might want to couple some event or action to a statement uttered by a speaker. WOOL supports specifically images, video or other generic actions.

The image example:

And here you can see a picture of a dog.
<<action type="image" value="dog.png">>

The video example:

I would like to show you this cool video I found.
<<action type="video" value="https://www.youtube.com/watch?v=dQw4w9WgXcQ">>

The "generic action" example:

Let me show you something in this book I found.
<<action type="generic" value="OPEN_RECIPE_BOOK">>

An example with specified delay:

Okay, I'll take you to the puzzle game, just a second...
<<action type="generic" value="LAUNCH_PUZZLE_GAME" delay="10">>

In this example, the delay parameter defines that the action should be executed with some delay (whether you interpret this as 10 seconds, 10 milliseconds or 10 days is up to your UI developer).

Finally, you can add other parameters to action-Statements, so as long as you don't call them type, value or delay you should be fine:

Okay, I'll take you to the puzzle game, just a second...
<<action type="generic" value="LAUNCH_PUZZLE_GAME" delay="10" difficulty="medium" background-color="#0000FF" num_players="2">>

5. WOOL Replies

Every Node can define zero or more (indefinite, but please consult your UI designer) Reply options, the different types are defined below.

5.1. Basic Replies

The standard Reply option defines a "user statement" and "Node Pointer", separated by a | (pipe).

[[Are you sure, Robin?|NodeConfirm]]

The user should be forwarded to the Node labeled NodeConfirm when selecting the "Are you sure, Robin?" option.

5.2. Auto-forward Replies

In replies, you can leave out the statement, and just provide a Node Pointer, but you can only have one of these:

[[NodeConfirm]]

This should allow your user to go to the NodeConfirm node when selecting e.g. a default "Continue" button, or automatically after some time (up to your UI design). You can not have two of these options in the same Node, but you can mix them with Basic replies, like so:

Would you like me to sign you up?

[[Yes, please do so!|Confirm]]
[[No, let's not.|Cancel]]
[[UserInDoubt]]

In the example above, you could for example give the user some time to choose between the "Yes, please do so!" and "No, let's not" options, and after some time, automatically progress the dialogue to the UserInDoubt Node.

5.3. Input Replies

You can ask a user to provide various types of input using Input Reply options. The easiest way is to request some text input:

What is your first name?

[[None of your business Robin.|RobinInsulted]]
[[My name is <<input type="text" value="$userFirstName" min="2" max="30">>, why do you ask?|RobinInputGiven]]

The general format of this statement is: (optional) beforeText, inputStatement, (optional) afterText. (optional) min, (optional) max.

That means that the following is the minimal example that is also valid:

What is your first name?

[[None of your business Robin.|RobinInsulted]]
[[<<input type="text" value="$userFirstName">>|RobinInputGiven]]

When a user chooses the Input Reply, the provided text is assigned to the value of the $userFirstName variable.

Very similar is numeric input:

[[I am <<input type="numeric" value="$userAge" min="0" max="120">> years old.|RobinInputGiven]]

In both cases the min and max parameters are optional (you can have none, either, or both).

Furthermore, WOOL supports time input in hours and minutes:

[[I ate my breakfast at <<input type="time" value="$breakfastTime" granularityMinutes="15" startTime="09:00" minTime="06:00" maxTime="12:00">> this morning.|BreakfastTimeGiven]]

This results in the variable $breakfastTime being set to something like "07:45". There are four optional parameters:

  • granularityMinutes: In the example this is 15, meaning that you can enter 00, 15, 30 or 45. You can use any value between 1 and 60. The default is 1.
  • startTime: The time that the input widget should show initially. For example "09:00", but you can also write "now", or even a variable: "$breakfastTimeYesterday". If you leave it out, then the input widget will start empty.
  • minTime: The minimum time that the user can enter. The default is "00:00".
  • maxTime: The maximum time that the user can enter. The default is "23:59".

5.4. Replies with Setting Variables

Instead of setting a variable in a single set-Statement, you can also set a variable as part of a Reply option, like in the following example:

Do you prefer meat or fish?

[[Meat please.|NodeMeat|<<set $likesMeat = true>>]]
[[Fish for me.|NodeFish|<<set $likesFish = true>>]]

5.5. Replies with Actions

Just like you are able to link a set-Statement to a Reply, you can also add action-Statements to replies, like so:

[[Please show me the recipes.|RecipesStart|<<action type="generic" value="OPEN_RECIPE_BOOK">>]]

5.6. Replies linking to other dialogues

There's only so much you want to put into one WOOL dialogue definition before you start losing track (and/or sanity), so WOOL allows you to link between different dialogue definitions, like so:

What should we talk about now?

[[Know anything about cars?|CarsDialogue.Start]]
[[What about fishing?|FishingDialogue.Start]]

In this example, the first Reply option would take the user to the Node labeled "Start" of the Dialogue labeled "CarsDialogue". So, in this case, your application should be aware of a file named "CarsDialogue.wool". Note that you don't have to link to the "Start" Node of a dialogue script, and you can choose any valid Node name.

Note: currently, it's up to the application developer how to organize their WOOL script files, and thus how you deal with linking between dialogues. Support for "WOOL Projects" is currently in development, which should help streamline this process.

Using the WOOL Editor

Check out the WOOL Editor tutorials:

Tools for creating WOOL applications

Java Tools

You can always find the latest javadoc version on this url: https://www.woolplatform.eu/documentation/javadoc/latest/index.html

All Javadoc versions:

Check out the Java Tutorials:

JavaScript Tools

Documentation coming soon...