Skip to main content

Subgraphs

Subgraphs allow you to encapsulate a section of your node graph into a reusable module. This is especially useful when you have a sequence of nodes that appears in multiple places in your story, such as a recurring mini-scene, a shared conversation pattern, or a common branching structure. Instead of duplicating nodes, you create a subgraph once and invoke it wherever it is needed.

Creating a Subgraph​

To create a subgraph, select a group of nodes on the canvas, right-click, and choose "Convert to Subgraph." The selected nodes are moved into a new subgraph and replaced on the main canvas with a single Subgraph node. You can also create an empty subgraph from the "Utility" section of the context menu and build its contents from scratch. Double-click a Subgraph node to open it and view or edit the nodes inside.

Every subgraph has at least one Entry node and one Exit node. The Entry node is where execution begins when the subgraph is called. The Exit node is where execution returns to the calling graph. You can have multiple Exit nodes with different labels, allowing the subgraph to return different results. For example, a combat subgraph might have a "victory" exit and a "defeat" exit.

Parameters​

Subgraphs can accept parameters, which are values passed in from the calling context. Parameters are defined in the subgraph's property panel and behave like local variables within the subgraph. When you place a Call node that invokes the subgraph, you configure the argument values for each parameter in the Call node's properties.

Parameters are useful for making subgraphs flexible. For example, a subgraph that runs a shop interaction might accept a parameter called shopName that changes the displayed shop title, and a parameter called inventory that determines which items are available. This way, a single subgraph can power multiple different shops throughout your story.

The Call Node​

The Call node is how you invoke a subgraph from your main graph or from another subgraph. Place a Call node, then select which subgraph it should invoke from the dropdown in its properties. The Call node's input port receives execution, the subgraph runs, and when the subgraph reaches an Exit node, execution returns to the Call node and continues along the corresponding output port.

The Call node has one output port for each Exit node defined in the subgraph. If the subgraph has a single Exit node, the Call node has one output. If the subgraph has exits labeled "victory" and "defeat," the Call node will have two outputs with those labels. This makes it easy to handle the subgraph's result in the calling context.

Entry and Exit Nodes​

The Entry node inside a subgraph works similarly to the Start node in the main graph: it is where execution begins. Unlike Start, the Entry node receives parameter values from the Call node. The Exit node works similarly to the End node but instead of terminating the story, it returns execution to the calling graph. Each Exit node has a label that maps to an output port on the Call node.

Best Practices​

Use subgraphs for any logic that you find yourself duplicating. Common candidates include combat encounters, shop menus, mini-games, save checkpoints, and recurring dialog patterns. Keep subgraphs focused on a single responsibility. A subgraph should do one thing well rather than trying to handle many unrelated tasks. Name your subgraphs descriptively so they are easy to find in the subgraph list. Document the purpose of each parameter with the description field so that anyone using the subgraph knows what values to provide.