Arcscript

Arcweave has its own scripting language, Arcscript, with basic scripting capabilities. You can use Arcscript in the following two ways:

• As conditions, in branches.
• As segments, in element content and connection labels.

Arcscript in branches

Arcscript is used in branches to control flow with if, elseif, and else conditions.

Branch conditions use the expressions and condition operators described on this page. For how a branch evaluates its conditions, see branches.

Arcscript segments

Arcscript segments are single lines of code that you can add into the content of elements and labels.

They support assignment statements, conditional statements, and calls to built-in functions such as show() or reset().

ℹ️ In Play Mode, an Arcscript segment does not start a new paragraph. Text before and after a segment, including text produced by a conditional statement or show(), joins the same paragraph, separated by a space. To keep the text after a segment in a separate paragraph, leave an empty line after the segment.

Add Arcscript

To insert an Arcscript segment into the content of an element or connection label, you use the Arcscript icon of the formatting menu, the one with the symbol <>.

1. Double-click the element or label to enter content editing mode.
2. Place the cursor on the line where you want to insert the Arcscript segment.
3. Click the Arcscript icon (<>) in the formatting menu.
4. Press Enter to exit the Arcscript segment and continue writing in the next line.

✅ You can also toggle an Arcscript segment using the shortcut Ctrl/Cmd + Shift + C.

Auto-complete

While you type in an Arcscript segment or branch condition, Arcweave provides auto-complete suggestions.

Suggestions include:

• Global variables, and board and component variables with their scope, such as hero.health
• Built-in functions
• The keywords if, elseif, else, and endif
• The word operators and, or, not, and is
• The literals true and false

Use the arrow keys to select the relevant suggestion and press Enter or Tab to insert it in your code. Press Esc to close the suggestions.

Variables and scope

Global variables use their name directly. Board and component variables are String Field, Boolean, Integer, or Float attributes and use the owning board or component's custom ID as a scope:

health = 100
castle.health = 10
hero.health = 20

In this example, health, castle.health, and hero.health are three distinct variables. Unqualified names such as health resolve global variables only.

Scoped variables support string, boolean, integer, and float values. See Variable scope, Board variables, and Component variables for setup instructions.

Assignment statements

Assignment statements are of the form of variable = expression. For example:

x = 5
x = y + 5
name = "Tim"
has_key = true

ℹ️ Before using a variable, create it in Global variables or add a String Field, Boolean, Integer, or Float attribute to a board or component. Arcweave's auto-complete uses the variable's current name and scope.

Arcscript also supports the following operations, with their respective operators:

Operation	Operator	Description
Addition	+=	Adds the right-hand value to the variable and assigns the result.
Subtraction	-=	Subtracts the right-hand value from the variable and assigns the result.
Multiplication	*=	Multiplies the variable by the right-hand value and assigns the result.
Division	/=	Divides the variable by the right-hand value and assigns the result.
Modulo	%=	Applies modulo to the variable using the right-hand value and assigns the result.

For example:

x = 5
x += 10
x -= 2

With string values, += appends the right-hand text, for example ${ name += " Smith" }. The other compound operators cause an error when used with strings.

Conditional statements

Conditional statements are of the form: if.../elseif.../else/endif.

ℹ️ This section applies to conditional statements found in elements and labels. Conditional statements in branches follow the same logic, but do not close with endif expressions. See Condition evaluation.

Inside conditional statements you may have:

• other statements (assignments, function calls, or conditionals).
• text content.

⚠️ The if, elseif, else, and endif segments of a conditional statement cannot be inside a blockquote, although the text between them can. Inside a blockquote, you can use assignments and function calls.

Example of a conditional statement containing an assignment:

if x == 5
  y = 4
endif

Example of a conditional statement containing some text content:

if wielding_shield
  The knight is wielding a large shield.
endif

Example of a conditional statement containing some text content and a variable assignment:

if hasKey
  You unlock the door!
  doorUnlocked = true
else
  You cannot open the door
endif

Example of using elseif for multiple outcomes:

if age >= 18
  Look at you! All grown up!
  type = "adult"
elseif age > 0
  You are not an adult yet.
  type = "child"
else
  Are you sure you have been born?
  type = "unborn"
endif

Expressions

Arcscript supports expressions that use the following arithmetic operators:

Operator	Name	Description
+	Addition	Adds two numbers, or joins them as text if either is a string.
-	Subtraction	Subtracts the right-hand value from the left-hand value.
*	Multiplication	Multiplies two numeric values.
/	Division	Divides the left-hand value by the right-hand value.
%	Modulo	Returns the remainder of a division between two numeric values.
( )	Parentheses	Groups parts of an expression to control evaluation order.

Expressions may combine literals, function calls, and variables. Write string literals in double or single quotes, such as "Tim" or 'Tim'. A minus sign before a value negates it, such as -x.

Conditions

Conditional operators

Operator	Name	Description
==, is	Equality	Checks whether two values are equal. 5 and "5" are not equal.
!=, is not	Inequality	Checks whether two values are not equal.
>	Greater than	Checks whether the left-hand value is greater than the right-hand value.
>=	Greater than or equal	Checks whether the left-hand value is greater than or equal to the right-hand value.
<	Less than	Checks whether the left-hand value is less than the right-hand value.
<=	Less than or equal	Checks whether the left-hand value is less than or equal to the right-hand value.

Logical operators

Operator	Name	Description
&&, and	Logical AND	Evaluates to true if both conditions are true.
||, or	Logical OR	Evaluates to true if at least one condition is true.
!, not	Logical NOT	Negates a condition, turning true into false and vice versa.

Built-in functions

The functions that are currently supported in Arcscript:

Function	Returns
abs(n)	The absolute value of a number
sqr(n)	The square of a number
sqrt(n)	The square root of a number
min(n1, n2, ...)	The minimum of two or more numbers
max(n1, n2, ...)	The maximum of two or more numbers
random()	A random decimal between (and including) 0 and (excluding) 1, i.e. in [0, 1)
reset(v1, v2, ...)	Has no return value; resets one or more given variables to their initial value
resetAll(v1, v2, ...)	Has no return value; resets all variables, except the given ones, to their initial value
resetVisits()	Has no return value; resets all elements' visits to 0
roll(m, n)	The sum of n rolls of an m-sided die (n defaults to 1)
round(n)	The number rounded to the nearest integer
show(e1, e2, ...)	Has no return value; renders the concatenation of its evaluated arguments as text
visits(el)	The number of visits to an element; without an argument, to the current element

reset() and resetAll() apply to global, board, and component variables. Call resetAll() without arguments to reset every variable.

roll

The roll(m, n) function simulates polyhedral die rolls from the classic tabletop RPGs.

Roll takes up to 2 positive integers as its arguments:

• m: the number of sides of the rolled die.
• n: the number of dice rolled.

The function returns a random integer between (and including both) n and n*m, i.e. [n, n*m].

✅ If n = 1, you can omit the second argument and simply type roll(m).

For example, rolling for a number from 1 to 12:

damage = roll(12)

Example of rolling 3d6 (3 six-sided dice) for a character's ability scores in Dungeons & Dragons:

dexterity = roll(6, 3)

Example of a dynamic use, where the player suffers damage from 1 to max_damage:

player_hp = player_hp - roll(max_damage)

But the roll(m, n) function can also be used in a conditional statement:

if roll(max_damage) > player_hp
  Oops... This isn't good...
endif

show

The show(e1, e2, ...) function renders its arguments and concatenates them as one string.

For example, the following:

show("Your score is ", score, "/", max_score, ".")

... for score == 3 and max_score == 256 renders:

Your score is 3/256.

You can use the show(e1, e2, ...) function in combination with text content, in elements. For example:

if roll(max_damage) > player_hp
  Oops... This isn't good...
  You have died. In this game you scored
  show(score, " out of ", max_score, ".")
endif

visits

Call visits() with an element argument

The visits(element) function returns the number of times a specific element has been visited during the current playthrough. The count includes the current visit: while the player is on an element for the first time, its count is 1.

The element argument must be a mention to an element. To mention an element inside visits():

1. Place your cursor within the parentheses of visits().
2. Type @ and begin entering the element's title. You can mention elements from any board.
3. Select the correct element from the autocomplete list.

✅ Mentioning an element in Arcscript works similarly to mentioning a component or board in rich text fields.

Call visits() without an argument

If visits() is called without an argument, it refers to the element the player is currently on:

• When used inside an element's content, it refers to that element itself.
• When used inside a connection label or branch condition, it refers to the element whose options are being prepared: the element where the option's path starts.

✅ To reset the visits of all elements of your project, use the resetVisits() function. It is always called without arguments.

Examples

In the following example, examine_the_painting stands for a mention of the Examine the painting element:

The knight is guarding a mysterious gate. You see a name written above his head:
| "Conrad IV, Count of Exeter"
if visits(examine_the_painting) > 1
  You make a mental note of the knight's name.
endif

And if we are already in the Examine the painting element, we can write:

The knight is guarding a mysterious gate. You see a name written above his head:
| "Conrad IV, Count of Exeter"
if visits() > 1
  You make a mental note of the knight's name.
endif

Errors

Arcweave checks your Arcscript as you write it. When a script has a syntax error, uses a variable that does not exist, calls a function with the wrong number of arguments, or mentions an element that does not exist, an exclamation mark symbol appears at the corner of the element, label, or branch condition that contains it.

✅ Hover your mouse cursor over the symbol to see the error message and the line and column where the error occurs.

Other errors occur only when Play Mode runs the script, such as dividing by zero or passing text to a function that expects a number. Play Mode shows these errors below the element's content or below its options. An option whose label causes an error is not shown, and a branch condition that causes an error counts as not met.