Node Editor

In the Node Editor, you define the material and deformations (compiled into the GE’s vertex shader) associated with an object. The material determines the surface of the object. The properties of the material are defined by a node graph built with the Node Editor. The Node Editor compiles the material node graph into fragment shader code, and the deformation node graph into vertex shader code, both of which run natively on the GPU.

Learn it by doing. These lessons walk you through it, step by step, in the editor:

If you would rather be guided, the Build a living shader lesson builds a node graph with you, one idea at a time – see Lessons.

Opening the Node Editor

You open the Node Editor with the 3D/Objects button in the Canvas Top Bar or Drop-Down Menu (see Project Settings), or by double-clicking an object in the Scene Viewer, or by selecting it and pressing E.

It can be shown in two ways: Side by Side with the Scene Viewer, splitting the screen between the two, or Floating on top of it, where it can be dragged by its title bar and resized from its bottom-right corner. Switch between them with the toggle button in the Node Editor’s own title bar – see Object Properties.

In the Node Editor, you add and connect nodes into node graphs. Each node has a specific function that affects the visual appearance of the material. By chaining and connecting nodes, complex animated output is generated.

With the buttons in the menu bar at the top of the Node Editor, you can add new nodes (selected from the Node Menu, create custom nodes, delete nodes, and undo operations. The Scale to Fit button scales the graph of nodes to fit onto the screen, and the background slider allows you to hide/unhide the scene viewer behind the Node Editor.

Keyboard Shortcuts

Nodes in the Node Editor can be copied and pasted using Command-C and Command-V, and deleted with Command-X or the Delete button.

Use Command-+ and Command– to zoom in/out.

Use Command-s to spread the nodes (if they have become too crowded), and Command-a to put them closer together.

Selecting and Moving Around

Select a single node with a single click, and select multiple nodes by holding down the Shift key when clicking on nodes. You can also select multiple nodes by holding down the Shift key when clicking on the background, then dragging the mouse to create a rectangular area, and all nodes in the area will be selected.

Move nodes with a click-and-drag. If you select multiple nodes, they will be moved together.

Move the whole node graph by dragging the background.

If your node graph is becoming too complicated, or you have defined interesting behaviors you want to re-use, select a subset of nodes and save them as a Custom Node that you can re-use for other objects in your project.

Scale to Fit & Snap to Grid

Scale to Fit , in the Node Editor’s own title bar, zooms and pans the node graph so every node is visible on screen – useful after opening a large graph, or once nodes have drifted far apart.

Snap to Grid , next to it, toggles whether nodes snap to a grid as you drag them, making it easier to keep a graph tidy and aligned.

See the Object Properties chapter’s Node Editor Title Bar section for the rest of the title bar’s buttons.

Editing Node Properties

Double-click on a node to edit the properties of that node. Sometimes that means filling in Form Values, sometimes it involves picking a color from a Color Picker, and sometimes it’s assigning an asset from My Files.

Connecting Nodes

The outputs of a node are to the right, and the inputs to the left. Each input/output has a name that describes what it is for, and a color that corresponds to the type of input/output. When you’re connecting nodes, the color for the output should match the color for the input you are connecting it to. Next to the name of the inputs, a default value might be displayed if it is not connected.

Connect by clicking on an output and dragging it to an input of another node. If you drop it on the input, it will become connected.

To remove a connection, simply click the input and drag the connector away from it.

It is possible to connect the same output to many different inputs. But an input can only be connected to one output.

For more information on possible types of connections, see Nodes Information.

Material and Deformations

Nodes that determine the material, i.e., the output color, are outlined with a gray border. These nodes are part of the fragment graph.

Nodes associated with deformation, i.e., the position of vertices, are outlined with a blue border. These nodes are part of the vertex graph.

In other words, if the final node in the node graph is RGBA Output, the nodes will have a gray border, and if the final node is Position Output, they will have a blue border. The two kinds of graphs can not be mixed as they are compiled into different shaders.

Warning and Error Indicators

The color of the border around a node indicates its state.

A gray or blue border indicates that the node is good-to-go. It has all the necessary input values, and it is used to generate output for the node graph.

A white border indicates that the node has the necessary input, but it is not used to generate output.

A red border indicates that the node is not functional, usually because it’s missing input (the texture in the case above).

A dashed red border indicates a circular graph. This is not allowed.

Selection

Selected nodes are highlighted with a yellow frame.

Creating Custom Nodes

By selecting a few nodes and clicking the Create Custom Node button, a custom node will be created, and you will be prompted to give it a name. The Custom Node will then replace all the nodes you selected. Input from nodes outside the selected group will become inputs to the Custom Node, and output from selected nodes to nodes outside will become Custom Node output.

The name of a Custom Node is shown in black, and the inputs and outputs are highlighted with a black center.

Double-clicking on the name of the Custom Node shows its definition.

If the definition changes, it will affect all users of the Custom Node. Inputs and outputs in the Custom Node are shown with a black center. Once the Custom Node has been saved, these inputs and outputs can not be changed (i.e., you cannot remove or add inputs or outputs).

When you are looking at the definition of a custom node, the name of the Custom Node is shown in the title bar of the Node Editor, and you can go back to your main node graph by clicking the back button.

Custom Nodes are saved in the project and can be reused by other objects in the project. Custom Nodes can use other Custom Nodes.

If a node is copied and pasted from one project to another, all custom nodes used by the object will be copied too. This is how Custom Nodes can be copied between projects.

Note: This is experimental functionality.

Technical Background

Vertex Shaders

In a vertex shader, your code runs once per frame (e.g., 60 times per second) for every vertex in your shape (mesh). Each vertex is processed independently.

If you have a cube with eight vertices, the vertex shader runs eight times per frame.

All invocations run in parallel, which makes the GPU fast — but it also means:

• A vertex shader cannot access other vertices
• You cannot store data between frames inside the shader
• You only know the inputs for your current vertex, plus global uniforms (time, camera position, lights, textures, etc.)

Fragment Shaders

In a fragment shader, your code runs once per frame for every pixel you draw. This includes all pixels covered by your shapes on screen. Since pixels lie between vertices, the GPU automatically performs linear interpolation of vertex outputs to give each fragment its correct position.

Fragment shaders are also massively parallel, so they obey the same rules:

• A fragment shader cannot read or modify other pixels
• It cannot remember values across frames
• It only has access to data for its current pixel, plus global uniforms (time, lights, textures, camera position, etc.)
  Both shader stages operate under the same model: massively parallel, stateless functions that work only with the data given to them.

For more information on how shaders work, Open GL provides a good explanation.