Arcscript


Overview

Arcweave has its own scripting language, arcscript, with basic scripting capabilities. You can use arcscript as segments (inside element content and connection labels) and as if/elseif/else conditions (in branches). In this chapter, we will discuss the syntax of arcscript segments only.

{primary} Any variable you use in arcscript segments or branches must first be declared in Global variables.

Arcscript segments currently support only assignment and conditional statements.

Assignment statements

Assignment statements are of the form: variable = expression.

Examples:

  x = 5

  x = y + 5

  name = "Tim"

  has_key = true

Arcscript also supports addition, subtraction, multiplication and division assignments using the operators: +=, -=, *=, /= respectively.

Example:

  x += 2

Conditional Statements

Conditional statements are of the form: if.../elseif.../else/endif. Inside conditional statements, you may have:

  • other statements (assignments or conditionals).
  • text content.

Example of a conditional statement containing an assignment:

  if x == 5
  y = 4
  endif

Examples of a conditional statement containing text:

  if wielding_shield
  
The knight is wielding a large shield.
endif
  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 haven't been born yet?
type = "unborn" endif

Expressions

Arcsript supports the creation of expressions using the following arithmetic operators: +, -, *, / and (, ). Expressions may combine literals, function calls and variables.

Conditions

Conditions in Arcscript may be formed by using the following conditional operators: == (or is), != (or is not), >, >=, <, <=.

Combining conditions may be achieved by using the following logical operators: && (or and), || (or or), ! (or not).

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 a series of numbers
max(n1, n2, ...) ... the maximum of a series of 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 the given variables to their initial value
resetAll(v1, v2, ...) ... has no return value - resets all variables, except the given ones, to their initial value
roll(m, n) ... a roll of an (n) number of (m)-sided dice (see below)
round(n) ... the number rounded to the nearest integer
show(e1, e2, ...) ... the evaluation and concatenation of its argument expressions (see below)
visits(el) ... the number of visits in a certain element

The roll(m, n) function

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

Roll takes 2 integer numbers 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].

{success} 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 ability scores in D&D:

  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

The show(e1, e2, ...) function

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 returns:

  > 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

The visits(el) function

The visits(el) function returns the number of visits in a certain element.

The el parameter is a mention to an element and you can add it by typing @ and continue typing the element's title, as you would in a Component or Board mention.

You can also call visits() without an argument, inside an element, and this will return the number of visits in the element itself.

  
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

When a script has a compile-time error, this is denoted by an exclamation mark symbol, at the lower right corner of the container element.

{success} Hover your mouse cursor over the symbol to get more info on what the error is about.