Nodes and Visibility

In StoryBonsai, everything you author sits on a node, and a rule called Visible when decides whether that node shows up as a choice in any given moment. Once those two ideas click, the rest of the manual is mostly consequences.

To write the Visible when rule itself, see Expressions. For what happens after the player picks a visible node, see Evaluation cycle.

Everything is a node

In StoryBonsai, the node is the unit of authoring. A line of dialogue belongs to a node. So does a choice the player can pick. So does a hidden flow step that mutates a variable, advances time, or jumps somewhere else. Nodes are the things you place in the Node Graph; the dialogue, the jumps, the mutations are events that live on nodes.

There’s no separate type for choices, branches, or decisions. Everything is a node. The same node can be a choice the player sees in one moment and an invisible flow step in the next.

What separates the two is whether the node is currently visible. The player only ever picks from the visible nodes. Anything else the manual covers about node behavior (exclusive selection, scene activation, the simulator’s choice panel) is some flavor of the same question: which nodes are visible right now?

1. Node A at the top. A plain node, no condition. The player plays it to drive the demo.
2. Dependency between Node A and Node B. Node B’s Visible when references node_a, so the editor draws a dependency line from A to B. Node B becomes visible once Node A has been played.
3. Inverse dependency between Node A and Node C. Node C’s Visible when references node_a negatively (!Played(node_a)), true when Node A has not been played. The dependency is drawn in a different color to mark the negated reference; Node C is visible before Node A is played and vanishes after.

Visible when

Every node has a Visible when field in its inspector. What you write there is a condition: an expression that returns true or false, used to gate something. “Condition” means exactly that throughout the manual. The grammar for writing one lives on the Expressions page.

Visible when has two regimes:

• Empty Visible when. The node is always hidden. The player never sees it as a choice; it only runs if another node jumps to it. Use this for logic nodes.
• Non-empty Visible when. The node becomes a choice exactly when the condition is true. Write the condition in terms of variables, what’s been played, what the player has selected, the active scene, and whatever else the editor’s expression helpers offer.

Node B’s Visibility section. Visible when is Played(node_a), so Node B becomes a choice once the player has played Node A.

When the project runs (in the simulator, in a path test, or in the game itself), every eligible node’s condition is evaluated together, and the ones whose condition is true become the player’s choices.

Before: the player hasn’t yet played node_a. Node B’s condition (Played(node_a)) is false, so Node B is hidden. Node C’s condition (!Played(node_a)) is true, so Node C is offered. Node A is offered too, since it has no gating condition.

After: the player has played node_a. Node B’s condition is now true and Node C’s is now false, so the choices swap. Node A itself has gone too, because it’s a once-per-visit node and has just been played. The graph hasn’t changed; only the player’s history has, and the visible set follows from it.

Hidden nodes you reach by jump

A node with an empty Visible when can’t appear to the player directly, but it can still run when another node jumps to it. Hidden nodes are the invisible steps you string between the player’s visible choices, doing work the player shouldn’t see directly: mutating variables, opening or closing audio scopes, deciding a follow-up. The player only ever picks visible nodes; hidden nodes are how you shape what happens between the picks.

One clarification: empty Visible when means “never visible,” not “visible by default.” If you want a node that’s always visible, write true in its Visible when field.

For the authoring gestures (the Jump event, dragging Connections, Return vs non-return), see Branching dialogue. Re-evaluation only fires where an expression depends on what changed; see State for why.

See also

• Expressions: how to write the rule that goes inside Visible when.
• Branching dialogue: the authoring side of the picture, covering Dialogue events, Jump events, and how visible and hidden nodes wire together into a scene’s flow.
• Evaluation cycle: what happens when the player picks one of the visible nodes; the order events fire, state updates, and a new visible set is computed.
• Scenes and visit state: how scenes gate which nodes are eligible to be visible at all.
• Common pitfalls: I don’t see my node as a choice: what an empty Visible when means for a node that was meant to be picked.
• Error messages: Nodes: panel messages about duplicate ids, orphan nodes, and unreachable events after a jump.