Basic Arcweave tutorial | Part 19: Function visits

Use visits to get the number of times an element has been loaded (i.e. visited) in Play Mode.

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.

Why track visits

So far, to track whether the player has visited parts of the story (that is, whether they've performed specific actions or received specific pieces of information), we've been using global variables. The downside of this approach is that the global variables list can quickly get out of control: you end up with tons of variables, one for every story or dialogue case that needs to be checked later on, causing major clutter.

To solve this issue, Arcweave offers visits, a function that returns how many times the player has visited a specific element.

✅ For scoped alternatives to global variables, see Board variables and Component variables.

Demo project

As a demo, we'll be using a short project called In a tavern. You can see its boards here and play it below:

visits in elements

We can call visits from an element's Arcscript segments.

Demo study: element

In the demo project In a tavern, go to the Beginning board and find the element titled Sigh.

Here, we have used the visits function in a simple way: in the dialogue with the druid, we've added an if statement that checks whether the player has already asked the necromancer for money.

Notice the if statement included in its content:

"I see," you sigh.
if visits(asking_necromancer) > 0

    "At least, I had _something_ in my pockets," says the druid, glaring at Solon.
endif

ℹ️ Remember: visits tells you how many times an element has been visited. If the visits count of the element Asking Necromancer is greater than 0, this means we've already spoken to the necromancer.

Add visits to elements

To recreate the above element:

1. Create a new element.
2. Double click its body and type its rich text content as usual.
3. Create a new line and start an Arcscript segment (Ctrl/Cmd + Shift + C).
4. Type in a conditional expression that uses visits: e.g. if visits()
5. Press Enter and type some rich text, e.g. "You've already spoken with the necromancer."
6. Close with an endif, as you already know from Part 12 of this tutorial.
7. Specify the argument of visits, i.e. what goes between the parentheses. This will be the title of the element you want to get the visits of. This is how you fill it in:
   1. Place your cursor between the parentheses of visits().
   2. Type the @ character (just as you would when mentioning a component or a board). This brings up a pop-up list of elements you can choose from.
   3. Continue typing to narrow down the selection, and select Asking Necromancer.
   4. The argument will be automatically filled in (in snake case): asking_necromancer.

visits in branches

We can also call visits from inside a branch.

Demo study: branch

From the same element as before (titled Sigh), one of the output connections leads to a branch, which has the following condition:

if visits(asking_necromancer) > 0

This branch diverts to a new element where the player can give the Druid a pat on the back.

In Play Mode, this extra line and the extra option will only appear if the player has already visited the Asking Necromancer element.

Add visits to branches

To include a visits call in a branch:

1. Create a new branch.
2. Double-click its if condition and type an expression that uses visits, e.g. visits()... The branch already displays the if keyword, so don't type it.
3. Specify the argument of visits, i.e. what goes between the parentheses. This will be the title of the element you want to get the visits of. This is how you fill it in:
   1. Place your cursor between the parentheses of visits().
   2. Type the @ character (just as you would when mentioning a component or a board). This brings up a pop-up list of elements you can choose from.
   3. Continue typing to narrow down the selection, and select Asking Necromancer.
   4. The argument will be automatically filled in (in snake case): asking_necromancer.

Element titles in visits

When used as an argument of visits, an element's title is automatically converted to snake_case (i.e. all words are in lowercase, with underscores instead of spaces), while the @ character disappears once the element is selected.

This happens under the hood: what you see isn't plain text code. In fact, the function's argument becomes a link to the source element. Clicking it will take you directly to the element it refers to, which is very convenient.

Simplified syntax

As mentioned, the visits function returns the number of visits, which is an integer.

Very often, though, we don't care about the exact count; we only care about whether an element has or hasn't been visited at all.

In these cases, we can simplify the syntax. Arcweave treats zero visits as false and any other number of visits as true, so this...

if visits(asking_necromancer) > 0

... can be simplified to:

if visits(asking_necromancer)

This is still valid, and functions the same way — it's a convenient shorthand for the very common case of only caring whether something has happened, not how many times.

visits without argument

First time descriptions

If you're calling visits from inside an element and want to reference that same element, you can call the function without any arguments.

This makes it easier to add first-time descriptions in an element, i.e. text that only appears the first time the element is visited:

You enter the tavern.
if visits() == 1
  Whoa, you've never been in such a place before!
endif

You approach the bartender.

Varying text per visit

A variation of the above is creating text that differs with every visit.

Let's say we expect the player to visit an element several times. If we don't want the player to keep getting the same response every time they loop back, we can modify the content based on how many times they've visited the element, using visits without an argument.

This is done in the demo project's element titled Ask about skeleton:

if visits() == 1
  "I see you remembered to bring your skeleton along, though. Carrying a pouch would have been too much?"
elseif visits() == 2
  "Are you sure the skeleton has no money?" you ask.

  Solon Blasphemius shrugs.
else
  You don't bother asking him again.
endif

What's next

This was a more demanding chapter, but now you've learned one of the most powerful functions of Arcscript!

In the next part of the tutorial, you'll learn how to use Arcscript in labels, as well as an alternative way to create and connect items in a board.