Basic Arcweave tutorial | Part 13: Functions show & roll

Learn more about manipulating outcomes using two Arcscript functions:

• show: Render the value of a variable as text for the player to see.
• roll: Generate random integer numbers, imitating die rolls.

The show and roll functions are two of Arcweave's core Arcscript tools for rendering dynamic content and introducing randomness into your stories.

This tutorial walks you through how each function works and how to combine them to create compelling, unpredictable narrative outcomes.

Video tutorial

Watch this tutorial as a video:

⚠️ This video does not reflect the latest updates to Arcweave's UI.

✅ You can play the finished version of the Tutorial Project here and explore its diagrams and structure here.

show

Simple use

The show function renders whatever is placed inside its parentheses, inline with any surrounding text.

For example:

gold = 100
You now have
show(gold)
gold coins in your purse.

This renders as: You now have 100 gold coins in your purse.

Multiple arguments

Multiple arguments of show must be separated by a comma. Study the following example:

name = "Burton"
times_said = 100
admits = true
show("My name is ", name, " and I've said it ", times_said, " times already: it is all ", admits, "!" )

This renders as: My name is Burton and I've said it 100 times already: it is all true!

⚠️ Notice the spaces needed in the above syntax to properly render the sentence (as in "My name is "). The space character is part of a string, so it must be included in quotation marks.

Line breaks

If you need line breaks to be rendered before or after the show content, you can add them to the rich text that wraps the show Arcscript segment.

You may also add line breaks in show's arguments using the \n character inside a string:

These are a few of my favorite things:

show(raindrops, "\n", roses, "\nand whiskers on kittens.")

Assuming 0 and 1.5 are the values of raindrops and roses respectively, the above element renders as follows:

These are a few of my favorite things:

0
1.5
and whiskers on kittens.

Add player morale

Let's now add show to our tutorial game.

Suppose we want to add a morale score to our player. To do this, we will follow these steps:

1. Create a player_morale variable (integer).
2. When the game starts, player_morale will be assigned a random value. We'll do this using roll (see next section on this page).
3. We will introduce the morale to the player in the first couple of elements with a smooth use of show.

Create morale variable

Create a new integer variable:

1. Go to Global variables and click + New variable.
2. Name the new variable player_morale, make it an Integer, and give it any value to begin with. Since it will be assigned a new value at random, we won't care about the value filled in here.

Introduce morale

We can introduce the morale score to the player in one of the first elements, e.g. the Office. Moreover, we can add a short, conditional comment by the narrator, depending on whether the value of player_morale is high or mediocre.

✅ The Arcscript segment that includes the roll function will be explained a little further below.

You rub your eyes. You are on the floor. Your office. It's midday. And you have work to do.

You start with a morale of
player_morale = roll(6, 3)
show(player_morale, ".")
if player_morale < 12
    It's not that great, to be honest, but you have to work with what you've got.
elseif player_morale >= 12 and player_morale < 18
    It's a pretty good morale to start with.
else
    You feel really elevated!
endif

Going through your diary, you see that you can barely make it on time for your appointment with the Linetti siblings. Something about a lost heirloom. You can read their folder while on the bus. But you must go, now!

Still, you stink...

Reassign and show

During the game, whenever player_morale changes, you can use an assignment expression followed by a call to show, to update the morale score and notify the player of the change. For example:

player_morale -= 2
show("Your morale is now ", player_morale, ".")

roll

The roll function generates a random integer in the style of tabletop RPG dice rolls.

roll(m)

roll(m) returns a random number between 1 and m (inclusive), equivalent to rolling an m-sided die (dm).

For example, roll(6) simulates rolling 1d6 (a 6-sided die).

roll(m, n)

roll(m, n) is equivalent to rolling n m-sided dice and adding the results together. Therefore, the number returned is between n and m * n.

Example: roll(6, 3) simulates rolling 3d6, which is the classic roll for ability scores in Dungeons & Dragons.

⚠️ Note that the probability distribution when rolling multiple dice is not uniform, but forms a bell curve, since most results cluster around the average.

Assign initial morale

As we saw in the element above, to randomly assign the initial morale value, we use:

player_morale = roll(6, 3)

Let's see a few more ways we can use roll in our game.

Randomize stat changes

Instead of deducting a fixed number of morale points, you can deduct a random amount:

player_morale -= roll(4)

This deducts a random value between 1 and 4.

If you want a minimum result of 0 instead of 1, roll one die size higher and subtract 1:

player_morale -= roll(5) - 1

Store roll results

To track the result of a roll in the debugger, assign it to a dedicated variable first:

roll_result = roll(5) - 1
player_morale -= roll_result

After you create roll_result as a global Integer variable (in Global variables, like player_morale), you can watch its value change in the debugger panel as you replay the project.

Moreover, storing the roll result in a roll_result variable lets you reuse it repeatedly in conditions, such as in branches.

roll in branches

Beyond modifying stats, roll is useful for making events happen with some randomness. To do this, you need to roll and then check all possible results in a branch, diverting the flow accordingly.

A warning

Consider the following branch:

• if roll(4) == 1...
• elseif roll(4) == 2...
• elseif roll(4) == 3...
• else...

Can you tell what is wrong with it?

The problem with the above branch is that, instead of rolling once and comparing the result with each of the possible numbers 1, 2, 3, and 4, each condition includes a new call to roll, which generates a new result. This produces unpredictable branch behavior.

Store the roll result

This is where storing the roll result is important.

Instead of calling roll in the branch, call it in the content of any element before the branch, storing the result in the roll_result variable. You can do this with just one Arcscript segment:

roll_result = roll(4)

Then, connect this element with the branch and check the value of roll_result against all possible roll outcomes:

• if roll_result == 1...
• elseif roll_result == 2...
• elseif roll_result == 3...
• else...

What's next

Use show to display variable values to the player and roll to introduce chance for stat changes, character encounters, or any outcome you want to leave to fate.

The next tutorial will teach you how to share and export your project.