# Branches

Source: https://docs.arcweave.com/project-items/branches
Section: Project Items
Description: Branches add conditional logic to flowcharts with if, elseif, and else conditions in Arcscript; create, edit, and connect them

Branches are board items that carry **conditional logic**. By evaluating one or more conditions written in [Arcscript](https://docs.arcweave.com/project-items/arcscript), a branch determines which outgoing connection the game flow follows at runtime.

![A branch with the conditions "if items.bronze_key", "else-if items.potion_strength", "else" directs the flow to three possible output connections with the respective options: "Unlock the door", "Drink potion of strength and bash in", and "Sob inconsolably".](https://docs.arcweave.com/assets/branch-intro.Df5oSQNe.png)

> ℹ️ The above example uses [board variables](https://docs.arcweave.com/project-items/variables/board): variable attributes on a board with the custom ID `items`, such as `bronze_key` and `potion_strength`.

In [Play Mode](https://docs.arcweave.com/project-tools/play-mode/overview), a branch evaluates its conditions in order and sends the game flow down the connection that corresponds to the first condition satisfied. You can use this behavior to control precisely which options are presented to the player.

## Conditions and connections

Context: Arcweave docs > Project Items > Branches > Conditions and connections

### Number of connections

Context: Arcweave docs > Project Items > Branches > Conditions and connections > Number of connections

A branch can have any number of incoming connections. Its outgoing connections correspond one-to-one with its conditions, structured as:

- `if condition 1` → Connection 1
- `elseif condition 2` → Connection 2
- ...
- `elseif condition n` → Connection n
- `else` → Connection n+1

### Number of conditions

Context: Arcweave docs > Project Items > Branches > Conditions and connections > Number of conditions

Logic dictates that a branch must have exactly one `if` condition, may have any number of `elseif` conditions, and may have at most one `else` condition.

### Condition evaluation

Context: Arcweave docs > Project Items > Branches > Conditions and connections > Condition evaluation

Conditions are evaluated in order from top to bottom. In the example below, the `elseif` expression is redundant and will always be skipped:

- `if score < 1000`...
- `elseif score < 10`...
- `else`

The `else` condition applies to all cases not covered by the previous `if`/`elseif` conditions, therefore it does not take custom expressions.

> ✅ Play-test your branch logic in [Play Mode](https://docs.arcweave.com/project-tools/play-mode/overview).

## Branch usage

Context: Arcweave docs > Project Items > Branches > Branch usage

Branches connect with [elements](https://docs.arcweave.com/project-items/elements), [jumpers](https://docs.arcweave.com/project-items/jumpers), and other branches, permitting or blocking the narrative flow depending on their conditions and the current game state.

### Labels along a branch path

Context: Arcweave docs > Project Items > Branches > Branch usage > Labels along a branch path

Connections entering and leaving a branch can both have labels. When a path passes through one or more branches, the option displays the **last label that produces text** after Arcscript is evaluated.

> ✅ A later label that produces no text keeps the earlier label's text.

Every label on a branch path has **its Arcscript evaluated**, including labels whose text is replaced by a later label. Variable changes from all labels accumulate along the path, and a branch checks its conditions using the values calculated by the labels before it.

These variable changes are applied to the playthrough **only when the player selects that option**, before its target element loads.

See [Labels across branches](https://docs.arcweave.com/project-items/labels#labels-across-branches) for the rules, [How Play Mode prepares an option across branches](https://docs.arcweave.com/project-items/labels#how-play-mode-prepares-an-option-across-branches) for the evaluation order, and the [chain of branches example](https://docs.arcweave.com/project-items/labels#example-a-chain-of-branches).

### `if` branches

Context: Arcweave docs > Project Items > Branches > Branch usage > `if` branches

An `if`-only branch renders its connected option only when its condition is met. Otherwise, it blocks the story flow, providing no output.

![Arcweave project environment with an orange rectangle emphasizing a branch that only has an if condition: if item.bronze_key.](https://docs.arcweave.com/assets/branches-if.BU3TkMSy.png)

In the above example, the branch evaluates the board variable `items.bronze_key`. If `true`, the option to unlock the door is presented. If `false`, no option appears instead.

You can add multiple `if`-only branches to offer several independent conditional options. If the player satisfies more than one condition, they receive all corresponding options.

![Arcweave project environment with orange rectangles emphasizing 3 branches that only have if conditions. Each branch evaluates a variable relative to an item: the bronze key, the potion of strength, and the battle axe.](https://docs.arcweave.com/assets/branches-if-multiple.nOqK28oW.png)

Below, you can see how the example above renders in Play Mode, if the player has all three items:

![Arcweave Play Mode environment. The Debugger is open and we can see that all three item variables are `true`. Each branch is evaluated and all 3 options appear as buttons.](https://docs.arcweave.com/assets/branches-if-multiple-play-mode.2b69blfU.png)

### elseif conditions

Context: Arcweave docs > Project Items > Branches > Branch usage > elseif conditions

To ensure the player receives **at most one** option from a set of possibilities, use a single branch with `elseif` conditions rather than multiple separate branches. In the following example, the options of using the key or the potion are bundled in the same branch, so only one option can be provided, even if the player has both items:

![Arcweave project environment. Two orange rectangles emphasize two branches. The first branch has an if condition (evaluating the bronze key) and an elseif condition (evaluating the potion of strength). The second branch only has an if condition (evaluating the battle axe).](https://docs.arcweave.com/assets/branches-if-elseif-multiple.u3_5Y6ge.png)

Even if the player has the potion of strength, only using the bronze key will be available as an option. The bronze key takes priority, due to its higher position in the branch.

![Arcweave Play Mode environment with the Debugger visible. We can see that the values of all three items bronze key, potion of strength, and battle axe are true. Two option buttons are visible, though: the option to use the bronze key and the battle axe.](https://docs.arcweave.com/assets/branches-if-elseif-multiple-play-mode.BPxnMndr.png)

The battle axe appears independently, since it is evaluated by its own branch.

### Fallback options

Context: Arcweave docs > Project Items > Branches > Branch usage > Fallback options

When using conditional options, get in the good habit of including at least one unconditional option (that is one without a branch). This can work as a fallback option, making sure the flow can continue regardless of the game state.

In this example, the flow continues even if the player has none of the three items:

![Arcweave project environment where an orange rectangle emphasizes the fallback option of "walking away", compared to two more options that lead to branches.](https://docs.arcweave.com/assets/branches-if-elseif-multiple-safety.JvYksFEx.png)

In Play Mode, only the fallback option is visible:

![Arcweave Play Mode environment with the Debugger visible. We can see that the values of all three items bronze key, potion of strength, and battle axe are false and only the fallback option "Walk away" is visible.](https://docs.arcweave.com/assets/branches-if-elseif-multiple-play-mode-safety.1cbUAYVu.png)

### else conditions

Context: Arcweave docs > Project Items > Branches > Branch usage > else conditions

Adding an `else` condition guarantees the branch always provides exactly one option, regardless of which conditions are met.

![Arcweave project environment showing a branch that includes `if`, `elseif`, and `else` conditions evaluating board variables.](https://docs.arcweave.com/assets/branches-if-elseif-else.DssujV9V.png)

In this example, the branch provides the option to use only one object, even if the player has all three of them.

![Arcweave Play Mode environment with the Debugger visible. We can see that the values of all three items bronze key, potion of strength, and battle axe are true. Besides the fallback option "Walk away", the only other option visible is the one about the bronze key.](https://docs.arcweave.com/assets/branches-if-elseif-else-play-mode.oZzQwiZ8.png)

> ✅ Read more about [variables](https://docs.arcweave.com/project-items/variables/overview) and [Arcscript](https://docs.arcweave.com/project-items/arcscript) on their respective pages.

## Create branches

Context: Arcweave docs > Project Items > Branches > Create branches

To create a branch, do any of the following:

- Right-click on an empty board area and select **Create > Branch** from the menu.
- Drag and drop the **New branch icon** (at the left of the [bottom menu](https://docs.arcweave.com/project-tools/interface/bottom-menu)) onto an empty board area.
- Drag a connection from an element or another branch and drop it on an empty board area, then select **Create branch here**. The new branch is created as the connection's target. See [Create connections](https://docs.arcweave.com/project-items/connections#with-drag-and-drop).

When you create a new branch, it contains only its required `if` condition.

## Select branches

Context: Arcweave docs > Project Items > Branches > Select branches

Click a branch to select it. To select multiple items, see [Select board items](https://docs.arcweave.com/project-tools/interface/mouse-actions#select-board-items).

## Copy a branch link

Context: Arcweave docs > Project Items > Branches > Copy a branch link

With only the branch selected, right-click it on the board and select **Copy link**. Opening the link centers the branch on its board in the language active when you copied it.

See [Share an item or board position](https://docs.arcweave.com/project-tools/share#share-an-item-or-board-position) for access requirements.

## Delete branches

Context: Arcweave docs > Project Items > Branches > Delete branches

To delete a branch, do either of the following:

- Select it and press **Delete** or **Backspace**.
- Right-click on it and select **Delete selection** from the menu.

## Edit branches

Context: Arcweave docs > Project Items > Branches > Edit branches

### `if` conditions

Context: Arcweave docs > Project Items > Branches > Edit branches > `if` conditions

#### Edit `if` conditions

Context: Arcweave docs > Project Items > Branches > Edit branches > `if` conditions > Edit `if` conditions

To edit the `if` condition, double-click it. Press **Esc** to exit editing.

> ⚠️ The `if` condition is required and cannot be added or removed.

### `elseif` conditions

Context: Arcweave docs > Project Items > Branches > Edit branches > `elseif` conditions

#### Add `elseif` conditions

Context: Arcweave docs > Project Items > Branches > Edit branches > `elseif` conditions > Add `elseif` conditions

To add an `elseif` condition, do either of the following:

- Right-click the branch and choose **Add elseif**.
- Press **Ctrl+Enter** or **Cmd+Enter** while editing another condition. The new `elseif` condition appears below the one you are editing.

#### Remove `elseif` conditions

Context: Arcweave docs > Project Items > Branches > Edit branches > `elseif` conditions > Remove `elseif` conditions

To remove an `elseif` condition:

1. Double-click the `elseif` condition to enter editing mode.
2. Click the **(x) icon** that appears on the right side of the condition.

#### Edit `elseif` conditions

Context: Arcweave docs > Project Items > Branches > Edit branches > `elseif` conditions > Edit `elseif` conditions

To edit an `elseif` condition, double-click it. Press **Esc** to exit editing.

### `else` conditions

Context: Arcweave docs > Project Items > Branches > Edit branches > `else` conditions

#### Add `else` conditions

Context: Arcweave docs > Project Items > Branches > Edit branches > `else` conditions > Add `else` conditions

To add an `else` condition, do either of the following:

- Right-click the branch and choose **Add else**.
- Press **Enter** while editing another condition, if the branch has no `else` condition yet.

#### Remove `else` conditions

Context: Arcweave docs > Project Items > Branches > Edit branches > `else` conditions > Remove `else` conditions

To remove the `else` condition, right-click the branch and select **Remove else**.

> ℹ️ A branch can have only one `else` condition.

> ℹ️ The `else` condition matches all cases not covered by the preceding `if`/`elseif` conditions, therefore it takes no custom expression and cannot be edited.

## Change color theme

Context: Arcweave docs > Project Items > Branches > Change color theme

To change the color theme of a branch, right-click on it and select one of the available colors from the menu.