Branch
Picks one of its output branches at random each time it runs.
Purpose
Varies behaviour so automation is less uniform — alternate routes, randomise which strategy runs, or split work between two paths.
The branches you wire on the canvas are the candidate list. There is no separate configuration of what can be chosen.
When to use it
- Alternating between several equivalent routines so runs are not identical.
- Splitting traffic between two strategies to compare them.
- Choosing a starting direction, target, or order at random.
When not to use it
- To decide based on data — use If.
- When one path must always run first — Branch gives no ordering guarantee (except that
noRepeatcycles). - To retry — use a Loop or a retry policy.
Requirements
Every branch port must be wired. Validation enforces it, because an unconnected branch would randomly dead-end the run.
How it runs
- Build the candidate list from the node's wired branch ports (
branch1…branchN). - Pick one using the chosen Mode.
- Route down the selected branch and record which one was chosen (output:
selectedBranch,mode,branchCount).
Settings
| Setting | Type | Range | Notes |
|---|---|---|---|
| Mode | choice | random, noRepeat, weighted | Required |
| Branch count | integer | 2–8 | Required. Each adds a port on the canvas |
| Weights | map | 1–100 per branch | Weighted mode; a missing entry defaults to 1 |
The three modes
| Mode | Behaviour |
|---|---|
random | Uniform. Can repeat the same branch consecutively |
noRepeat | A shuffled bag — every branch is used before any repeats |
weighted | Higher weight is chosen more often |
noRepeat is usually what people mean by "random". Uniform random will happily pick the same branch three times running; the no-repeat bag will not.
The no-repeat bag spans loop iterations within one run and resets between runs.
Ports
| Port | Taken when | Required |
|---|---|---|
| branch1…branchN | That branch was selected | All required |
| Fatal | The mode or branch count is invalid | Never followed |
Branch is the strictest node in the product for wiring: every single branch port must be connected.
Basic example
A 50/50 split between two routes:
- Mode: Random
- Branch count:
2
Realistic example — vary the scan order
Scanning the same direction first on every run is a recognisable pattern. Rotating it is one node:
Branch chooses; a variable records the choice; a switch acts on it. Separating "choose" from "act" keeps the graph readable and lets later nodes know which route was taken.
Advanced example — weighted strategies
Run an expensive thorough routine one time in five, and a fast routine the rest:
- Mode: Weighted
- Branch count:
2 - Weights:
branch1 = 4(fast),branch2 = 1(thorough)
Best practices
- Wire every branch. It is required, and an unwired one would dead-end the run.
- Prefer
noRepeatfor variety. Uniform random clusters. - Record the choice in a variable so later nodes and the run log can tell what happened.
- Keep branches equivalent in outcome. Random selection should vary how, not whether, the work gets done.
- Use weights instead of nesting Branch nodes to express uneven odds.
Performance notes
- Selection is a pure computation — effectively free.
- The cost is entirely in what the branches do. If one branch is much slower, your average run time is the weighted average, not the fast path.
Memory notes
- The no-repeat bag is a small per-run structure; negligible.
- Nothing persists between runs — the bag resets each run.
Common mistakes
| Mistake | What happens | Fix |
|---|---|---|
| Leaving a branch unwired | Validation error; would dead-end at run time | Wire all of them |
| Expecting Random to alternate | Uniform random repeats | Use noRepeat |
| Using Branch for a data decision | Non-deterministic behaviour | Use If |
| Weights that do not sum to 100 | Not a problem — they are relative | No fix needed |
| Branches with different outcomes | Runs succeed or fail at random | Make branches equivalent |
Troubleshooting
The same branch keeps being chosen.
Mode is random. Switch to noRepeat.
Validation fails on the node. One or more branch ports is unwired.
A branch never seems to run. In weighted mode its weight may be very low relative to the others.
Lowering the branch count removed an edge. Expected — trailing ports are dropped and orphaned edges pruned.
FAQ
How many branches can I have? 2 to 8.
Does no-repeat reset between runs? Yes. It spans loop iterations within a run only.
What weight does a branch get if I omit it? 1.
Can I see which branch was chosen?
Yes — the output records selectedBranch, and it appears in the run log.
Related nodes
- If — decide on data instead of chance
- Variable — record the choice
- Loop — repetition, where no-repeat spans iterations
- Wait — random durations, the other source of variation