Labels

Connections can include labels: text fields that render as option text in Play Mode.

Labels support the following powerful features:

• Rich text formatting: Create option text that includes bold, italics, underline, strikethrough, and links.
• Mentions of components and boards.
• Arcscript:
  • Write dynamic option text that changes based on the story state.
  • Apply variable changes when the option is selected.

Create labels

You can add a label to a connection in either of the following ways:

• Double-click the connection.
• Right-click the connection and choose Add label.

Type your text directly using rich text.

Press Esc or Tab to exit.

Edit labels

To edit a label, do either of the following:

• Double-click the label or its connection.
• Right-click the label or its connection and choose Edit label.

Format the label's content using rich text.

✅ Project owners and editors can also edit labels in Play Mode while playtesting the story. Enable Edit content, then edit the option buttons for the current element.

Copy a link to a label's connection

With only the connection selected, right-click its label and select Copy link. The link opens the connection's area on its board. See Copy a connection link.

Resize labels

To manually resize a label's width:

1. Click the label to select it.
2. Drag the label's left or right border and release at the desired width.

Reposition labels

To change the position of a label on the same connection, click and drag the label along the connection and release it at the desirable point.

Delete labels

To delete a label, do any of the following:

• Click the label to select it and press Backspace or Delete.
• Right-click the label and choose Remove label.
• Clear the text and press Esc or Tab.

No labels?

Labels are not required for your story to run in Play Mode, but they give you greater control and flexibility in shaping the player's experience.

If an available option has no label text after Arcscript is evaluated, Arcweave uses the target element's title for its button text. If the target has no title, it uses the beginning of its content instead.

When only one option is available and its labels produce no text, Play Mode shows a blinking arrow instead of an option button. Click the element's content area to continue. Arcweave checks this after evaluating branches and label Arcscript, so multiple outgoing connections can still lead to a single available option.

A label containing only variable assignments, or conditional text that produces nothing in the current playthrough, can still result in the arrow. To show a button for a single option, give its path a label that produces text, such as Continue. See labels across branches for paths with several labels.

Arcscript in labels

Connection labels support Arcscript segments, which allow the following features:

• Dynamic option text: The option text changes based on conditions and variable values.
• Variable changes: When the player selects an option, the variable changes calculated from its label Arcscript are applied to the playthrough.

Add Arcscript

To add an Arcscript segment while editing a label:

1. Press Enter to start a new line.
2. Convert the new line into an Arcscript segment: click the Arcscript icon (<>) in the toolbar or press Ctrl/Cmd + Shift + C.
3. Type your Arcscript expression.
4. Press Enter to exit the Arcscript segment and start a new rich text line.
5. Repeat step 2 if you need to convert the new line into a consecutive Arcscript segment.

Evaluation & execution

Play Mode evaluates label Arcscript while preparing the available options:

• The result determines the option text. Any variable changes calculated along the path are also available to later labels and branch conditions on that path.
• Those variable changes are applied to the playthrough only when the player selects the option, before the target element's content is evaluated. Changes from options the player does not select are not applied.

This allows for dynamic option text, as in the following example:

Talk to
if name_known
  Jefferson.
else
  the moustached man.
endif

Labels across branches

An option can follow several connections through branches before reaching its target element, so one option can carry several labels. The board shows all of them, but Play Mode displays only one as the option text. The rest still run their Arcscript.

Play Mode applies the following rules to every label on an option's path:

• Option text: The option displays the text of the last label on the path that produces text. The text of earlier labels is not displayed.
• Arcscript: Every label on the path is evaluated, in path order, including labels whose text is not displayed. Their variable changes are calculated and carried along the path.
• Branch conditions: Each branch checks its conditions using the values calculated by the labels before it.
• Applying changes: The variable changes calculated by all labels on the path are applied to the playthrough only when the player selects the option, before the target element's content is evaluated.

A label produces no text when it is empty after evaluation: for example, when it contains only variable assignments, or conditional text whose condition is not met in the current playthrough. Such a label does not replace the earlier text. Because labels are evaluated every time options are prepared, the same path can display a different label's text in different playthroughs.

If no label on the path produces text, the option uses the target element's title. See No labels?.

How Play Mode prepares an option across branches

For each path leaving the current element, Play Mode does the following:

1. Starts from the playthrough's current variable values.
2. Evaluates the label of the first connection, calculating its variable changes and its text.
3. At a branch, checks the conditions from top to bottom, using the values calculated so far, and follows the connection of the first condition that is met. If no condition is met, or the first met condition has no outgoing connection, the path ends at the branch and produces no option.
4. Evaluates the label of the next connection, continuing from the values calculated so far. If the label produces text, that text replaces the option's text.
5. Repeats steps 3 and 4 until the path reaches its target element.

When the player selects the option, Play Mode applies the calculated variable changes to the playthrough and then loads the target element. If the player selects a different option, these changes are discarded.

ℹ️ Option text that uses show() or conditional text reflects the values calculated along the path, even though they have not yet been applied to the playthrough. See the chain of branches example.

Example: labels before and after a branch

Create a global variable named score, with type Integer and initial value 0. Connect an element named Gate to a branch, and connect the branch's if output to an element named Garden. Set the if condition to score >= 1, and start Play Mode from Gate.

On the connection from Gate to the branch, add this label:

Try the gate
score = score + 1

On the connection from the branch to Garden, add:

Enter the garden
score = score + 2

While preparing the option, Arcweave calculates score = 1 from the first label. The branch uses that value, so its condition is met. The second label then calculates score = 3 and replaces Try the gate with Enter the garden as the option text.

The playthrough's score remains 0 until the player selects Enter the garden. It then becomes 3 before Garden loads. If you remove Enter the garden from the second label but keep its Arcscript, the option displays Try the gate and still changes score to 3 when selected.

Example: a chain of branches

This example follows the same rules through three branches. Create a global score variable of type Integer, with initial value 0. Connect an element named Start to a chain of three branches, each with the condition if true, and connect the last branch to an element named Target.

The finished path consists of the following items, in order. Each connection's label holds text, an Arcscript segment, or both:

1. Element: Start
2. Connection
   • Text: Count to two
3. Branch: if true
4. Connection
   • Arcscript: score += 1
5. Branch: if true
6. Connection
   • Arcscript: score += 1
7. Branch: if true
8. Connection
   • Text: Your score:
   • Arcscript: show(score)
9. Element: Target

In Play Mode, Start shows a single option: Your score: 2.

• Count to two is not displayed, because a later label on the path produces text.
• The two middle labels produce no text, but their assignments are evaluated. The last label shows the calculated value, 2.
• The playthrough's score remains 0 while the option is displayed, and becomes 2 when the player selects it, before Target loads.