WOOL Language Documentation

The header consists of a series of lines, each with a \{key: value\}-pair. The two required key-value pairs are:

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:

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

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

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.

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:

If you want to document your WOOL scripts with comments, WOOL Supports line-comments. Everything after a double-slash // is considered a comment:

Pay attention when including hyperlinks in your text (e.g. https://www.woolplatform.eu) - in this case, the first forward-slash should be escaped, as follows:

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, it’s your party). For example:

There are two ways a WOOL dialogue can end:

Example 1:

Example 2:

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.

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

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 _ (underscores).

In short: variables names start with a letter, then contain letters, numbers or underscores, for example:

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

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: \<< \>> \[[ \]]

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:

WOOL allows you to set variables using the [set] statement.

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:

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.

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

Please note that “==” is treated as strictly-equals.

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

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:

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 in your application you cannot be sure whether or not boolean variables have been assigned a value, our advice is to always use the if-equals-true-else construction:

Sometimes you might want to couple some event or action to a statement uttered by a speaker. WOOL supports Actions of type link, image, video, or generic, all of which are shown below.

The link example:

The image example:

The video example:

The generic example:

The four examples above show the four basic cases of using [action]-Statements. Every Action requires a type and a value. The type must be one of {link, image, video, generic}. The value has a specific and obvious meaning for types link, image, and video. For generic actions, you are free to assign your value tag, and write your WOOL Client to handle it however you like.

Besides the type and value parameters, an Action may have any number of additional parameters. See some examples below:

In this example, we added the text parameter to the action of type link, so that we can tell our client to render the text, and turn it into a hyperlink.

In the example below, we extend our generic action to pass along some additional information to our recipe book widget. In this case, we want our UI to wait 2000ms, and then open the recipe book to page 42.

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

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

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

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:

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.

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

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

So, the minimum valid example is as follows:

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

Very similar is numeric input:

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:</p>

This results in the variable $breakfastTime being set to the provided input (e.g. "07:45"). There are four optional parameters:

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:

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

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:

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, there should be a file named "CarsDialogue.wool" in the same folder as the current .wool script. Note that you don’t have to link to the "Start" Node of a dialogue script, and you can choose any valid Node name.