Overview

Orchestrator is a Godot Engine GDExtension plug-in that runs within the Godot Editor to design and implement a game logic using a graph-node visual-script-like system.

Example
Figure 1. An example orchestration

The entire node graph is called an Orchestration and stored as a Godot resource within your project. An orchestration can be loaded in the Editor to make changes to the flow and logic, and attached to scene nodes much in the same way that GDScript or CSharp scripts can be attached to scene nodes.

An Orchestration, or also referred to as an OScript, is made up of nodes called OScriptNode resources. These nodes can represent specific functionality, access to specific Godot utility functions, may call user-defined functions, or simply aid in documentation, as with comment nodes.

Orchestrator v1 allowed for custom node implementations to add existing behavior to the plug-in. At this time, adding custom nodes is not available in the new GDExtension implementation, but will be added in a future patch when we include support for Macro and Function libraries.

Editor configuration

The Godot engine provides functionality for editor plug-ins to directly integrate with many of its internal components, such as the Project Settings dialog available on the Project menu.

With the project settings dialog open, click the General tab and navigate near the bottom of the options left panel or simply using the filter settings widget and begin typing Orchestrator. The plug-in allows you to define a number of features in this window including:

  • Default script class type

  • Numerous UI customizations for colors of nodes, connection lines, and icons.

Plugin Settings 1
Figure 2. Plugin General Settings
Plugin Settings 2
Figure 3. Plugin User Interface Settings

If you have any suggestions for what other settings should be customizable, we welcome the feedback. Please provide your suggestions on the project’s GitHub issues as a feature/suggestion.

Editor integration

Orchestrator provides an in-editor interface, allowing you to quickly create and modify Orchestration resources using a drag-and-drop node visual-scripting-like interface. To use the Orchestrator plugin, select the "Orchestrator" interface icon at the top of the Godot Editor, as shown below:

Editor Main View Selector
Figure 4. Godot Editor Main View Selector

Once you have selected the Orchestrator main view, you will see a similar view as shown below. The editor does not initially show the editor graph. You must create a new or open an existing orchestration using the File menu first.

Editor Main View
Figure 5. Orchestrator main view

File list

To the left of the graph area is the Orchestration Files list view. This list view provides access to all open orchestration script files inside the editor. You cn manage and open as many orchestrations concurrently and freely navigate between them.

Orchestration File List View
Figure 6. File List View

To change between each opened orchestration, click on the orchestration file name in this list, and the orchestration graph panel to the right will update accordingly.

If several orchestrations are open concurrently, you can use the "Filter orchestrations" search box to limit the entries in the files list view to those that match the filter argument. This can quickly help isolate a specific orchestration of interest without manually finding it within the list view.

Component view

To the right of the graph area is the Orchestration Component view. This view displays several accordion controls and tree lists of the graphs, functions, variables, etc. contained with the Orchestration. This is essentially an outline of the Orchestration that lets you quickly navigate to specific sub-elements of the Orchestration, as well as create new ones.

Orchestrator Component View
Figure 7. Component View

For example, a standard Orchestration will always have a default EventGraph. In addition, any functions created within the Orchestration will be displayed.

Graphs

The graph component view maintains a list of all node graphs stored within the Orchestration script. Graphs allow for better organization of logic and to avoid having large, complex graph workspaces.

New graphs can be created by using the + icon at the right of the panel header.

Functions

The function component view maintains a list of all user-defined functions within the Orchestration script. A user-defined function allows you to organize re-usable bits of logic within the Orchestration so that you can call that functionality from different points without having to duplicate the node graph. A function graph is very much modeled after a Godot function, where you can pass multiple input arguments into the function, and you can optionally return a value but you are limited to only one.

New functions can be created by using the + icon at the right of the panel header. Additionally, Godot virtual functions such as _ready or _physics_process can be overwritten in an Orchestration by using the Lock button to the far right of the panel header. This opens a context menu to select overridable functions that will be directly placed onto the EventGraph.

Finally in order to call user-defined functions, simply drag the function onto the graph area or right-click the graph area to open the context node action menu, searching for the keywords "call" and the name of your function.

Macros

The macro component view maintains a list of local macros that are defined in the Orchestration script. A macro is essentially a custom node type, where you implement your node logic using visual scripting building blocks and then within a user-defined function or event graph, the macro node would be used.

Macros different from functions because they accept zero or more input values and can return zero or more output values. Additionally, macros can support multiple execution pins both into and out of the macro, where-as a function only supports a singular execution input and output pin.

Macros can be defined at two different levels, one is inside an Orchestration script and the other is inside an Orchestration macro library. When a macro is defined inside the script, it’s local to that script and other scripts aren’t able to access or use that macro node. When a macro is defined inside a library, it is global and any Orchestration script will be able to use that macro node.

Macros are not a feature that is currently included in this release, but is planned in a future release.

Variables

The variable component view maintains a list of variables that are defined in the Orchestration script. A variable is a logical name with a given data type that is used to store some arbitrary state at runtime.

Variable
Figure 8. Variable component view and Inspector details

In addition to a logical name and type, variables also can be categorized. By default, variables have an empty category, which means they’ll be listed at the top-level of the variable tree. Specifying a variable category can be useful to organize like variables together based on some theme.

Finally, Orchestrator script variables can be exported, just like GDScript variables. This means that those variables can be accessed by outside objects in your scene and manipulated as though they’re public. It also means those properties will be visible in the InspectorDock for the scene tree node that the Orchestration script is attached.

To add a new variable, use the + icon at the right of the panel header. Once a variable has been defined, it can be edited through a combination of the InspectorDock and right-clicking the variable in the component view.

To use the variable, simply drag the variable from the component view to the graph area, and a popup menu will then allow you to select whether you want to read the variable value (Get) or write to the variable (Set).

Specifying a variable category not only groups variables by category within the Variable view, but it also groups the variables under a collapsable section in the InspectorDock on the scene node if the variable is exported.

Signals

The signal component view maintains a list of all user-defined custom signals in the Orchestration script. A signal is a Godot concept that supports the Subject / Observer pattern.

Any interested party, a scene node, resource, or Editor component can subscribe to the signal by connecting to it. Then as the Orchestrator script’s logic executes each frame, the script can raise or emit the signal and any connected party will be informed. In addition, signals can have zero or more arguments, so it’s a great way to pass data in a de-coupled way from the observed subject to the observer.

Variable
Figure 9. Signal component view and Inspector details

To add a new signal, use the + icon at the right of the panel header. Once a signal has been defined, it can be edited through a combination of the InspectorDock and right-clicking the signal in the component view.

To emit the signal, simply drag the signal from the component view to the graph area to create an emitter node.

Grid / Graph editor

The graph area in the main portion of the Editor window is where you will spend the vast majority of your time interacting with Orchestrations. This is the area where nodes will be created, dragged, configured, and connected together to create game logic and behaviors.

To get started with adding nodes to the graph area, right click anywhere in the graph area space to open the context-sensitive action menu. This will provide access to all Orchestrator Script nodes and Godot class functions and properties based on the base type of the script. You can use the search box at the top to quickly filter the list of actions.

Once nodes are placed, you’ll notice that most have two different types of ports along the edges of the node. The ports that look like white triangles facing right are called execution pins, and these define the control flow for your logic. The ports that are various color dots are called data pins, and these are what pass data between nodes.

Ports on the left side of a node are called input pins while ports on the right are called output pins. These pins can be connected by using the left mouse button to click on a port to start creating a connection line to another port.

We will discuss each node and its functionality in the Nodes section.

Running/Using orchestrations

An Orchestration is a script resource that must be attached to a scene node for it to execute. This works much in the same way that a CSharp script or a GDScript are attached to scene nodes.

Once you’ve made changes to an Orchestration, pressing the F5 key in the Editor will start debugging the main scene. It’s here you can test your Orchestration logic and verify that it works as intended.