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
elseif conditions expect you to add arcscript expressions. For example:
Let's have a look at the example from the picture above:
if score <= 4...
elseif score < 10...
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
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
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:
You reach at the door and
unlock it with the key.
knock it with your knuckles.
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:
You are carrying
gold of, let’s say
15, this will produce: You are carrying 15 gold coins.
Some more examples of
show("The score is ", score, ".")shows: The score is 5.
show((4 > 5))shows: false
(Notice the use of an extra pair of parentheses for an expression as argument for
Episode 14 of our tutorials demonstrates the function
show(), as well as
roll(), which lets some randomness step into your story:
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
scorevariable equal to
score = score + 5, which makes the value of
scorego up by
5. This is also expressed as
score += 5.
You take 3 gold coins from the chest.
gold += 3
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
roll(), or evaluate
if statements to produce dynamic text.
Watch Episode 22 of our tutorials, for more of this feature:
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.