Use Arcweave's visits() function to check visited elements

You don't need to create a variable for every thing the player does.

To track whether the player has made specific choices or played specific parts of your story, one way is to store the information in a global variable and check its value when needed. For example, the value of the met_Balrog variable determines whether the player can see the Balrog in the camping description, as well as get the option to talk to them.

This works, but it can soon blow your list of global variables out of proportions. Imagine having tens of variables, one for every story or dialogue branch that needs to be checked later on.

To solve this issue, we implemented visits(), a function that checks if and how many times the player has visited a specific element. You should use visits() instead of a variable whenever you can, to avoid cluttering your variables list.

Let’s see the visits() function in action.

Add a visits() check to another element

Consider the story sample Red Riding Hood’s Mum, which you may have already seen in my older blog post Write your interactive story with Arcweave. To check whether the Wolf has come with us, we can actually use the visits() function, instead of the global variable with_wolf.

(If you haven't read that post, perhaps you'd like to give it a read first, so that you understand the changes we apply here.)

This is how it initially looks:

We split the choice in 2 elements and adjust the contents accordingly: one where the Wolf follows and one where he stays put. Then, both branches rejoin the flow, as the player approaches the cottage.

This way, not only do we get a separate element for each option, content and all, but we can also check which of the two elements the player has visited.

From the cottage element, delete the branch’s “if” code and start typing: if visits(@wolf... As soon as you type the ‘@’ character—just as with mentioning components or boards—a list of element titles will appear. Typing “wo…” narrows the list down.

Select Wolf joined. Then, close the parentheses. Your branch now will look like this:

You can now delete the met_wolf variable from your Global Variables list. Make sure you're not using it anywhere else—otherwise, use the visits() function, there, too.

Congratulations, you've just eliminated an unused variable!

The argument of visits()

Notice that the element’s title Wolf joined gets converted to snake_case (wolf_joined) and—similar to what happens with board & component mentions, the “@” character disappears.

Moreover, the function’s argument is now a link to the source element. Click it and you’ll teleport to the element it refers to.

Number or boolean?

By using visits() in the above syntax, it returns false (if the number of visits is 0) or true (if greater).

In case we need to use the actual returned number of visits, we can apply a relevant syntax, as in this case:

In the first element, titled Calculate milk the show() function takes as argument the value returned by the visits() function, counting the visits to the Drink milk element. (Careful with all the parentheses!) Every time we visit the Drink milk element, the number rendered by show() increments.

Of course, this produces "1 cups of milk," so you ideally want to add an if/else condition that saves your grammar:

Calling visits() from within the same element

Here's one last trick: if we call visits() from inside an element and want to mention the element itself, we can do so by calling it without an argument.

Video tutorial on visits()

To study the visits() function in more detail and with more examples, watch Episode 21 from our YouTube tutorial series:

The visits() function is an easy way to check how many times the player has visited a specific element. Use it whenever you can, instead of creating variables for everything the player has done. Its intuitive mentioning of element titles makes it super easy to use—and it's definitely worth decluttering your Global Variables list!