# Variables

> For the complete documentation index, see [llms.txt](https://docs.arcweave.com/llms.txt). All pages are also available in one file, [llms-full.txt](https://docs.arcweave.com/llms-full.txt).

Source: https://docs.arcweave.com/project-items/variables/overview
Section: Project Items
Description: How to create and use story variables in your Arcweave project

Arcscript examples: Arcscript has no delimiters, so never wrap code in `${ }`, `{{ }}`, `<< >>` or similar markers. An `arcscript` code block contains only code: each line is one segment, and a branch condition is a single expression without `if` or `endif`. An `arcweave-html` code block is element or connection label content as Arcweave stores it, the HTML that the REST API and MCP server accept: `<p>` for text, `<p></p>` for an empty line, and each Arcscript segment in its own `<pre><code>` block, with `<` written as `&lt;`. An element passed to `visits()` is written as element mention markup; replace `ELEMENT_ID` with the element ID.

Arcweave uses **variables** to store data during play. These are the mechanism through which the game can "remember" what happens and progress accordingly.

Variables are used in [branches](https://docs.arcweave.com/project-items/branches), as well as in [Arcscript segments](https://docs.arcweave.com/project-items/arcscript#arcscript-segments) within [elements](https://docs.arcweave.com/project-items/elements) and [labels](https://docs.arcweave.com/project-items/labels).

## Common use cases

Context: Arcweave docs > Project Items > Variables > Common use cases

You can use variables in the following ways.

### Assign values

Context: Arcweave docs > Project Items > Variables > Common use cases > Assign values

Assigning a value to a variable stores that value for later use in the game. You can assign values using any of [Arcscript's assignment statements](https://docs.arcweave.com/project-items/arcscript#assignment-statements).

For example, if the player finds a key, you can store this information in a boolean variable named `has_key` (see [variable types](https://docs.arcweave.com/project-items/variables/overview#variable-types), below), assigning it the value `true` in an [Arcscript segment](https://docs.arcweave.com/project-items/arcscript#arcscript-segments).

Then, the game will remember that the player has found the key.

![Arcweave's project environment, focused on an element's content that says "You found the key!" and an Arcscript segment says "has_key = true".](https://docs.arcweave.com/assets/branch-has-key-true.C3mzxS05.png)

### Evaluate in branches

Context: Arcweave docs > Project Items > Variables > Common use cases > Evaluate in branches

Evaluating a variable allows the game to read and use its value. [Branches](https://docs.arcweave.com/project-items/branches) can evaluate variables using `if`/`elseif`/`else` [conditions](https://docs.arcweave.com/project-items/branches#condition-evaluation) and direct the story flow accordingly.

> ℹ️ For a full guide on Arcscript conditions and their syntax, see [Arcscript](https://docs.arcweave.com/project-items/arcscript) > [Conditional statements](https://docs.arcweave.com/project-items/arcscript#conditional-statements).

In the same example as above, when the player finds the locked drawer, a [branch](https://docs.arcweave.com/project-items/branches) can decide whether they can open it, by evaluating the variable `has_key` in an `if` statement.

![Arcweave's project environment, focused on a branch of which the condition says "if has key". The branch leads to a connection of which the label says "Unlock the drawer".](https://docs.arcweave.com/assets/branch-has-key._4VTzFo3.png)

### Display dynamic text

Context: Arcweave docs > Project Items > Variables > Common use cases > Display dynamic text

Another common use of variables is to **display dynamic text content** in [elements](https://docs.arcweave.com/project-items/elements) and [labels](https://docs.arcweave.com/project-items/labels). In other words, the player gets to see different text output depending on the variables' values.

#### Dynamic text using conditional statements

Context: Arcweave docs > Project Items > Variables > Common use cases > Display dynamic text > Dynamic text using conditional statements

One way of creating dynamic text output is by using conditional statements that output different text.

For example, by using the integer `day` (see [Variable types](https://docs.arcweave.com/project-items/variables/overview#variable-types)), we can display a different message to the player as the weekend approaches. (Week starts from `1` = Monday.)

```arcweave-html
<pre><code>if day >= 6</code></pre>
  <p>It's weekend! You stretch out in bed. No alarm, no rush. Bliss.</p>
<pre><code>elseif day >= 5</code></pre>
  <p>Weekend is almost here. You hum your favourite song all the way to work.</p>
<pre><code>else</code></pre>
  <p>The week is still young. Lots of things to do.</p>
<pre><code>endif</code></pre>
```

> ℹ️ For a full guide on Arcscript conditions and their syntax, see [Arcscript](https://docs.arcweave.com/project-items/arcscript) > [Conditional statements](https://docs.arcweave.com/project-items/arcscript#conditional-statements).

#### Dynamic text using the `show` function

Context: Arcweave docs > Project Items > Variables > Common use cases > Display dynamic text > Dynamic text using the `show` function

Another way to display dynamic text in elements and labels is by using the `show` function, which renders its arguments as text content.

The following example uses the `coins` integer (see [Variable types](https://docs.arcweave.com/project-items/variables/overview#variable-types)) to store the player's riches:

```arcscript
show("You have ", coins, " gold coins.")
```

> ℹ️ See [Arcscript](https://docs.arcweave.com/project-items/arcscript) > [`show`](https://docs.arcweave.com/project-items/arcscript#show) for more on the function's syntax and uses.

## Variable types

Context: Arcweave docs > Project Items > Variables > Variable types

The supported variable types are:

- **Boolean**:
   A `true`/`false` value, useful for tracking flags, e.g. `has_key` or `met_daisy`.
- **String**:
   A sequence of characters, used for names or any other text value, e.g. `happy` or `John Smith`.
- **Integer**:
   A whole number, ideal for stats or counters, e.g. `dexterity` or `score`.
- **Float**:
   A number with a decimal point, suited for precise measurements, e.g. `speed` or `temperature`.

> ⚠️ Arcscript does not enforce strict type checking. When type conversion occurs, it follows JavaScript's type coercion rules.

For board and component variables, the **String** type appears as **String Field** in the attributes menu.

Every variable has an initial value. Play Mode starts with these values, and restarting Play Mode restores them for global, board, and component variables.

## Variable scope

Context: Arcweave docs > Project Items > Variables > Variable scope

Arcweave supports one global variable category and two scoped variable categories:

| Category                                                 | Stored and managed in           | Arcscript reference      |
| -------------------------------------------------------- | ------------------------------- | ------------------------ |
| [Global variable](https://docs.arcweave.com/project-items/variables/global)       | The **Global variable dialog**  | `score`                  |
| [Board variable](https://docs.arcweave.com/project-items/variables/board)         | The **Board attributes dialog** | `castle.drawbridge_open` |
| [Component variable](https://docs.arcweave.com/project-items/variables/component) | The component editor            | `hero.health`            |

All three categories can be read and changed from anywhere in the project. For board and component variables, the scope qualifies the variable's name; it does not restrict where the variable is available. A component variable belongs to the component itself, so attaching that component to multiple elements does not create separate copies of its value.

Board and component variables use the same underlying mechanism. A **String Field**, **Boolean**, **Integer**, or **Float** attribute becomes a scoped variable when both the attribute and its owning board or component have custom IDs. Rich Text, Component List, and Asset List attributes remain metadata and cannot be used as Arcscript variables.

The owner's custom ID is the scope and the attribute's custom ID is the variable name. The attribute label is only a human-readable description and does not affect the Arcscript reference. Unqualified names such as `health` resolve global variables only, so `health`, `castle.health`, and `hero.health` can coexist as three distinct variables.

### Variable names and custom IDs

Context: Arcweave docs > Project Items > Variables > Variable scope > Variable names and custom IDs

Variable names and custom IDs must be valid Arcscript identifiers and cannot be Arcscript keywords or built-in function names.

- A global variable name must start with a letter, `_`, or `$` and must be unique among global variables.
- A board or component custom ID must start with a letter or `$` and must be unique across all regular boards and components.
- A variable attribute custom ID must start with a letter, `_`, or `$` and must be unique among the attributes of its owner.
- After the first character, these identifiers can contain letters, numbers, and underscores.

A global variable name may match a board or component custom ID because unqualified and scoped references are distinct. For example, the global variable `hero` and the component variable `hero.health` can coexist.

Arcweave generates a custom ID when you create a regular board or component. When you name a variable attribute, Arcweave generates its custom ID from its label. Renaming an owner or attribute custom ID updates existing Arcscript references automatically.

## Variables in Debugger

Context: Arcweave docs > Project Items > Variables > Variables in Debugger

When in Play Mode, you can monitor the variables and their values in the Debugger.

<img
  src="https://docs.arcweave.com/assets/play-mode-all-variables.DVIsiO3z.png"
  alt="The Debugger's searchable variable list, grouped into Global, board, and component sections."
  width="360"
  data-zoomable
/>

See [Play Mode](https://docs.arcweave.com/project-tools/play-mode/overview) > [Debugger](https://docs.arcweave.com/project-tools/play-mode/debugger) for full instructions.