Use Arcweave's scripting language to write complex interactive stories

Arcscript comes in small segments—and the’re cute, too.

You write stories that people can play.

Players proceed by making choices and eventually reach one of the endings, hopefully finding some delight—and enlightenment—in the process.

If you are an Arcweave beginner, you'll first want to read about how to write your interactive story in Arcweave, before you continue with this, more advanced article.

Interactivity allows different players to experience the story differently. Each makes their own choices, while controlling a character with different skills and stats.

I will assume you want your story to take into consideration player and story facts, and respond accordingly during the play through. Examples include:

• allowing the player to pick their character’s name.
• randomly generating player stats, like strength, sanity, and health.
• having a scoring system, like gold coins or any generic score points.
• checking if the player has done or seen something; whether they’ve heard or spoken a line of dialogue or whether they’ve collected an item.
• keeping track of the time of day, et al.

To deal with the above situations, you’ll need a way to store information, which you can then retrieve and change.

In Arcweave, you can use variables and its scripting language, arcscript.

Whoa, what are variables?

When it comes to computers and programming, variables are a fundamental entity.

Think of variables as containers. Each container has a label and some content.

A variable’s name is their label, which helps us access it among others. A variable’s value is their content. And it’s important to remember that variables can change values anytime we want.

This is part of their power!

Variables in Arcweave

To access your Arcweave project’s variables, click on Global variables, at the bottom left. From there, you can create and delete variables, or change their type and initial value.

You can create variables of the types integer, float, boolean, and string.

To learn everything about variables, watch Episode 10 from our tutorial series on YouTube.

Using arcscript to access variables

Arcweave’s scripting language allows you to access variables and read or change their values during the story.

You can use arcscript in:

• branches: write conditions, to divert the story flow accordingly,
• elements: set variables and write “smart,” dynamic content, and
• connection labels: set variables and write “smart,” dynamic option text.

Arcscript in branches

A branch is one of the item types Arcweave uses to structure story flow (the others being elements and jumpers).

When the story flow reaches a branch, the branch diverts the flow to the connection that meets certain conditions.

Branches consist of one if condition—this is the necessary minimum. Then, they can have one or more elseif conditions and they can end with an else one.

The if/elseif conditions expect you to add arcscript expressions. For example:

A branch

Let's have a look at the example from the picture above:

This is the logic of this branch: if the score is less or equal than 4, the flow follows the branch’s first output connection. If not, there is another check, whether the score is less than 10. If that is also false, the flow follows the output of the else condition.

Another branch

Obviously, an elseif is not always necessary. In this branch there can be only two outcomes, depending on whether the player has the sword or not.

A third branch

The else is not always necessary either. If the if condition is false, then the story flow stops there.

This is a very common case for when you want a player option to appear only if a condition is met.

To learn more about branches, watch Episodes 11 & 12 of our video tutorials:

Arcscript in elements

You probably already know how to use elements to write your story. Did you know you can also add code segments inside elements?

Once in edit mode, inside an element, click on the arcscript segment icon (with the <> symbol), to start typing code.

You can use code inside elements, to write dynamic text or assign values to variables.

Writing dynamic text

Your story can produce different outputs if different conditions are met. For example, the element in the image above:

Another way to create dynamic text is through the use of the show() function, which renders the value of its arguments as text. For example:

For a gold of, let’s say 15, this will produce: You are carrying 15 gold coins.

Some more examples of show():

• string: show(player_name) shows: Guybrush.
• integer: show(score) shows: 5
• boolean: show(has_sword) shows: true
• concatenation: show("The score is ", score, ".") shows: The score is 5.
• expression: show((4 > 5)) shows: false

(Notice the use of an extra pair of parentheses for an expression as argument for show().)

Episode 14 of our tutorials demonstrates the function show(), as well as roll(), which lets some randomness step into your story:

Variable assignments

The other use of code inside elements is to assign values to variables, during story runtime.

For assignments, Arcscript uses common programming expressions like:

• score = 5, which makes the value of the score variable equal to 5.
• score = score + 5, which makes the value of score go up by 5. This is also expressed as score += 5.

For example:

To see this feature in action, watch Episode 13 of our tutorial series:

Arcscript in connection labels

You can also use arcscript in connection labels, in exactly the same way as in elements.

While editing a connection label, click on the arcscript segment icon (the <> one) and start typing code.

You can make variable assignments, call functions like show() and roll(), or evaluate if statements to produce dynamic text.

Watch Episode 22 of our tutorials, for more of this feature:

Dig deeper…

I hope you don’t get intimidated by a little coding! Arcscript is simple and you can master it in very little time.

To get to know all its tricks, the best way is to go through its page in the Arcweave Documentation. You’ll find all its functions—it’s not all just a show(), you know—and a few examples to get inspiration from.