An editor for graph-like structures, using GraphNodes.
GraphEdit provides tools for creation, manipulation, and display of various graphs. Its main purpose in the engine is to power the visual programming systems, such as visual shaders, but it is also available for use in user projects.
GraphEdit by itself is only an empty container, representing an infinite grid where GraphNodes can be placed. Each GraphNode represents a node in the graph, a single unit of data in the connected scheme. GraphEdit, in turn, helps to control various interactions with nodes and between nodes. When the user attempts to connect, disconnect, or delete a GraphNode, a signal is emitted in the GraphEdit, but no action is taken by default. It is the responsibility of the programmer utilizing this control to implement the necessary logic to determine how each request should be handled.
Performance: It is greatly advised to enable low-processor usage mode (see OS.low_processor_usage_mode) when using GraphEdits.
Note: Keep in mind that Node.get_children() will also return the connection layer node named _connection_layer due to technical limitations. This behavior may change in future releases.
The connections between GraphNodes.
A connection is represented as a Dictionary in the form of:
{
from_node: StringName,
from_port: int,
to_node: StringName,
to_port: int,
keep_alive: bool
}Connections with keep_alive set to false may be deleted automatically if invalid during a redraw.
The size of the minimap rectangle. The map itself is based on the size of the grid area and is scaled to fit this rectangle.
Returns whether the mouse_position is in the input hot zone.
By default, a hot zone is a Rect2 positioned such that its center is at in_node.GraphNode.get_input_port_position()(in_port) (For output's case, call GraphNode.get_output_port_position() instead). The hot zone's width is twice the Theme Property port_grab_distance_horizontal, and its height is twice the port_grab_distance_vertical.
Below is a sample code to help get started:
func _is_in_input_hotzone(in_node, in_port, mouse_position):
var port_size = Vector2(get_theme_constant("port_grab_distance_horizontal"), get_theme_constant("port_grab_distance_vertical"))
var port_pos = in_node.get_position() + in_node.get_input_port_position(in_port) - port_size / 2
var rect = Rect2(port_pos, port_size)
return rect.has_point(mouse_position)Returns whether the mouse_position is in the output hot zone. For more information on hot zones, see _is_in_input_hotzone().
Below is a sample code to help get started:
func _is_in_output_hotzone(in_node, in_port, mouse_position):
var port_size = Vector2(get_theme_constant("port_grab_distance_horizontal"), get_theme_constant("port_grab_distance_vertical"))
var port_pos = in_node.get_position() + in_node.get_output_port_position(in_port) - port_size / 2
var rect = Rect2(port_pos, port_size)
return rect.has_point(mouse_position)This virtual method can be used to insert additional error detection while the user is dragging a connection over a valid port.
Return true if the connection is indeed valid or return false if the connection is impossible. If the connection is impossible, no snapping to the port and thus no connection request to that port will happen.
In this example a connection to same node is suppressed:
func _is_node_hover_valid(from, from_port, to, to_port):
return from != toAllows the connection between two different port types. The port type is defined individually for the left and the right port of each slot with the GraphNode.set_slot() method.
See also is_valid_connection_type() and remove_valid_connection_type().
Allows to disconnect nodes when dragging from the left port of the GraphNode's slot if it has the specified type. See also remove_valid_left_disconnect_type().
Allows to disconnect nodes when dragging from the right port of the GraphNode's slot if it has the specified type. See also remove_valid_right_disconnect_type().
Rearranges selected nodes in a layout with minimum crossings between connections and uniform horizontal and vertical gap between nodes.
Attaches the element GraphElement to the frame GraphFrame.
Detaches the element GraphElement from the GraphFrame it is currently attached to.
Ends the creation of the current connection. In other words, if you are dragging a connection you can use this method to abort the process and remove the line that followed your cursor.
This is best used together with connection_drag_started and connection_drag_ended to add custom behavior like node addition through shortcuts.
Note: This method suppresses any other connection request signals apart from connection_drag_ended.
Returns an array of node names that are attached to the GraphFrame with the given name.
Returns the closest connection to the given point in screen space. If no connection is found within max_distance pixels, an empty Dictionary is returned.
A connection is represented as a Dictionary in the form of:
{
from_node: StringName,
from_port: int,
to_node: StringName,
to_port: int,
keep_alive: bool
}For example, getting a connection at a given mouse position can be achieved like this:
var connection = get_closest_connection_at_point(mouse_event.get_position())Returns an Array containing a list of all connections for node.
A connection is represented as a Dictionary in the form of:
{
from_node: StringName,
from_port: int,
to_node: StringName,
to_port: int,
keep_alive: bool
}Example: Get all connections on a specific port:
func get_connection_list_from_port(node, port):
var connections = get_connection_list_from_node(node)
var result = []
for connection in connections:
var dict = {}
if connection["from_node"] == node and connection["from_port"] == port:
dict["node"] = connection["to_node"]
dict["port"] = connection["to_port"]
dict["type"] = "left"
result.push_back(dict)
elif connection["to_node"] == node and connection["to_port"] == port:
dict["node"] = connection["from_node"]
dict["port"] = connection["from_port"]
dict["type"] = "right"
result.push_back(dict)
return resultReturns an Array containing the list of connections that intersect with the given Rect2.
A connection is represented as a Dictionary in the form of:
{
from_node: StringName,
from_port: int,
to_node: StringName,
to_port: int,
keep_alive: bool
}Returns the GraphFrame that contains the GraphElement with the given name.
Returns whether it's possible to make a connection between two different port types. The port type is defined individually for the left and the right port of each slot with the GraphNode.set_slot() method.
See also add_valid_connection_type() and remove_valid_connection_type().
Disallows the connection between two different port types previously allowed by add_valid_connection_type(). The port type is defined individually for the left and the right port of each slot with the GraphNode.set_slot() method.
See also is_valid_connection_type().
Disallows to disconnect nodes when dragging from the left port of the GraphNode's slot if it has the specified type. Use this to disable a disconnection previously allowed with add_valid_left_disconnect_type().
Disallows to disconnect nodes when dragging from the right port of the GraphNode's slot if it has the specified type. Use this to disable a disconnection previously allowed with add_valid_right_disconnect_type().
Sets the coloration of the connection between from_node's from_port and to_node's to_port with the color provided in the activity theme property. The color is linearly interpolated between the connection color and the activity color using amount as weight.
Emitted when this GraphEdit captures a ui_copy action (Ctrl + C by default). In general, this signal indicates that the selected GraphElements should be copied.
Emitted when this GraphEdit captures a ui_cut action (Ctrl + X by default). In general, this signal indicates that the selected GraphElements should be cut.
Emitted when this GraphEdit captures a ui_graph_delete action (Delete by default).
nodes is an array of node names that should be removed. These usually include all selected nodes.
Emitted when this GraphEdit captures a ui_graph_duplicate action (Ctrl + D by default). In general, this signal indicates that the selected GraphElements should be duplicated.
Emitted when the GraphFrame frame is resized to new_rect.
Emitted when one or more GraphElements are dropped onto the GraphFrame named frame, when they were not previously attached to any other one.
elements is an array of GraphElements to be attached.
Emitted when this GraphEdit captures a ui_paste action (Ctrl + V by default). In general, this signal indicates that previously copied GraphElements should be pasted.
Emitted when a popup is requested. Happens on right-clicking in the GraphEdit. at_position is the position of the mouse pointer when the signal is sent.