Skip to content
NodespellNodespell Docs

GraphBuild a graph

Organize graphs with Levels and Folders

View as MarkdownAsk ChatGPTAsk Claude

A Level in Nodespell is a node that contains its own graph, so a whole section of work can live inside one node. A Folder is a Level set to organise rather than compute: it holds nodes, shows a cover, and cannot be run or connected. Both keep large projects tidy, and you move in and out of them like folders on a computer.

What is the difference between a Level and a Folder?

Section titled “What is the difference between a Level and a Folder?”
Level Folder
Purpose A self-contained part of the graph Organisation, like a folder of files
Sockets in the parent graph Yes; can connect to other nodes No sockets
Can run Yes, as part of the graph No: Folders cannot be run directly.
On the canvas A node A folder card with an item count, optional Cover Image and Title
Convert Convert to Folder Convert to Level

Both are the same kind of node, so you can switch between them. A Level that has connections in its parent graph cannot become a Folder until you remove them: Disconnect parent-level connections before converting this level to a folder.

Create a Level or Folder

Section titled “Create a Level or Folder”
  • Right-click empty canvas and choose Folder.
  • Press Tab and search for Level to add a Level.
  • Right-click a Level node and choose Convert to Folder, or right-click a Folder and choose Convert to Level. The same commands are in the command palette (Cmd/Ctrl+K).

Set a Folder’s Cover Image and Title in Parameters with the Folder selected.

Go into and out of a Level or Folder

Section titled “Go into and out of a Level or Folder”
To Do this
Go in Double-click the node, select it and press Enter, or right-click it and choose Enter Node (Levels) or Open Folder (Folders)
Go up one Level Press U, click the up arrow (Go to parent level) in the Graph Editor bar, or right-click empty canvas and choose Go Up
Jump to any outer Level Click its name in the breadcrumb at the top of the Graph Editor; the first item is Root

Nodespell remembers where you were looking on each Level, so returning to a Level brings back its view.

Stay on one Level while you work

Section titled “Stay on one Level while you work”

By default, selecting a node that lives on another Level, for example from Find in graph, takes the Graph Editor to that node’s Level. Click the lock button, Pin/Unpin current level, next to the up arrow to keep the Graph Editor on the current Level instead. Click it again to unpin.

Set the flow direction for each Level

Section titled “Set the flow direction for each Level”

Flow direction sets which way connections run: Top to bottom, Bottom to top, Left to right or Right to left. It changes which edges sockets sit on, not the order things run in.

  1. Open the Level you want to change.
  2. In the top bar, choose Layout > Flow direction.
  3. Under This level, pick a direction, or pick the inherited option (Project default, Compositor default or Same as parent) to follow the setting above it.
  4. Under Project defaults, set Graphs and Compositors for every Level that does not have its own setting.

Flow direction Applies to everyone in this project, and only editors can change it. A Level with its own direction shows a small arrow next to its name in the breadcrumb. Changing direction leaves node positions as they are; press L to tidy the Level afterwards.

New projects start with the directions set in Preferences, under Node Graph Editor: Graph flow in new projects and Compositor flow in new projects. Both default to Top to bottom, and existing projects keep their own.

Copy and paste Levels and Folders

Section titled “Copy and paste Levels and Folders”

Copy a Level or Folder with Cmd/Ctrl+C and paste it with Cmd/Ctrl+V, like any node. The copy includes every node inside it, however deeply nested.

How do large projects load?

Section titled “How do large projects load?”

Nodespell does not load every node in a large project at once. A project prepares once, then loads each Level as you go into it, so opening the project and moving between Folders stays fast.

Some actions need the whole project. In Find in graph, project-wide search covers names and folder paths straight away; select Load full project to include comments and parameters, or to replace text across every Level.

Frequently asked questions

Section titled “Frequently asked questions”

Can a Folder be part of a run?

Section titled “Can a Folder be part of a run?”

No. Folders are for organisation only and cannot be run directly. Convert it to a Level with Convert to Level if you need it to compute and connect.

Why can’t I convert a Level to a Folder?

Section titled “Why can’t I convert a Level to a Folder?”

A Level with connections in its parent graph cannot become a Folder, because Folders have no sockets. Disconnect those connections first, then choose Convert to Folder.

Does each Level have its own flow direction?

Section titled “Does each Level have its own flow direction?”

Each Level can. By default a Level follows the project default for graphs or compositors; pick a direction under This level in Layout > Flow direction to give it its own.

How do expressions refer to nodes on other Levels?

Section titled “How do expressions refer to nodes on other Levels?”

Use parent. to read from the Level around the current one and root. to start from the top of the project. See Expressions.

Section titled “Related”