Orchestrator 2.1 is here!

At the beginning of this year, we embarked on an exciting journey to bring visual scripting back to Godot 4, culminating in the release of Orchestrator 2.0 at the end of March. Over the past four months, our team has focused on a variety of enhancements, many aimed at improving user experience, while also introducing new features requested by our community.

We are thrilled to announce the general availability of Orchestrator 2.1, our latest and most advanced offering for Godot users who want to design games using visual tools.

In these four months, we have added over 250 improvements, made possible by the community's ongoing support and feedback. Many of you have dedicated countless hours testing changes, providing feedback, suggestions, and ideas, as well as contributing code and documentation, all of which have shaped this release. Thank you all!

This release includes a mix of bug fixes and exciting new features, making Orchestrator an even more polished and user-friendly plugin for Godot 4. We have many more improvements planned for Orchestrator and will discuss our future roadmap in another blog post later this month.

Please read on to learn about all the new features, changes, and critical announcements regarding Orchestrator 2.1, or jump to our downloads section to get started. You can also use the update button in your editor to automatically download and install the new release.

Critical and Breaking Changes

Orchestrator adheres to the semantic versioning system, but due to the scale of our project and our dependencies on components like Godot, implementing changes that impact compatibility with previous versions is sometimes unavoidable. We believe that for most users, the migration process will be seamless, with most critical steps handled automatically by our plugin's migration process.

Here are some important points to consider before upgrading to Orchestrator 2.1.

Godot 4.3 is mandatory

Orchestrator 2.1 requires Godot 4.3.stable or later to function.

The Orchestrator plug-in is built using GDExtension, a C++ framework that integrates directly with the Godot Engine. This technology relies on public APIs provided by Godot, allowing engine developers to create plugins, tools, and extensions for use within the Godot Editor or as features in their games. Each minor release of Godot typically includes changes to the GDExtension interface, as this technology is continually evolving and improving. To ensure the best user experience with Orchestrator, we must keep updating to the latest version of Godot's API to incorporate these enhancements and bug fixes.

If updating to Godot 4.3.stable is not feasible for you, don't worry. We will be releasing Orchestrator 2.0.2.stable later this week, which will include many of the new features mentioned here but will be compatible with Godot 4.2.stable. Stay tuned for that announcement.

Orchestration File Format Changes

In Orchestrator 2.0, we used a binary-based format for the plug-in. While this wasn't a major issue, we received feedback from the community that it felt too rigid, especially for those wanting to commit orchestrations to version control and easily track changes.

We're pleased to announce that Orchestrator 2.1 now uses a text-based file format automatically. This new format, with the extension .torch, represents text-based orchestrations. It utilizes a modified Godot text-based resource format, so if you're familiar with .tres or .tscn files, the .torch format will look similar.

All existing orchestrations using the old binary format and the .os extension remain compatible. You can still open, modify, and save files in the binary format if you prefer. To set the Create New Script default to the old binary format, go to Project Settings and change the Orchestrator > Settings > Storage Format option, then restart the editor.

To convert existing .os binary orchestrations to the new .torch text-based format, open the old file in the editor and use File > Save As to save it with the .torch extension. The new file will use the text-based format. Update any scene nodes that reference the .os script by detaching and reattaching the .torch script. Afterward, you can safely delete the .os file as it will no longer be needed.

Script Migrations

In Orchestrator 2.1, we not only changed the script format but also enhanced several nodes and their operations. To ensure compatibility with older orchestrations, we introduced a migration step to align them with the script engine's expectations. These migration steps will be displayed as yellow warnings in the Godot editor's Output panel, as shown here:

We felt it was not appropriate to apply these changes directly to your orchestration files during the save operation, primarily to avoid confusion for users who may not be using version control. Therefore, Orchestrator makes these changes in-memory so the orchestrations run correctly.

If you see such warnings and want to eliminate them, open the orchestration in the editor and save it to disk. This will make the migration steps permanent, and you will no longer receive these warnings for that file in the future.

Highlights

In the sections below, we will cover the most impactful changes with Orchestrator 2. You can refer to our change log, if you want a complete list of the changes.

Godot 4.3 Features

Orchestrator 2.1 is designed exclusively for Godot 4.3 and requires Godot 4.3.stable or later. With the release of Godot 4.3, several new features were introduced by the Godot team and are supported by Orchestrator. These include new scripting APIs such as case-insensitive string operations, numerous new vector math functions like float-based snapping, clamp, min, and max functions, and the new PackedVector4Array data type.

Customization improvements

A key focus in Orchestrator 2.1 is on enhancing usability. We've listened to the community's feedback about wanting more ways to customize and control the plugin to better fit your preferences and workflows. To meet these needs, we've added nearly a dozen new customization and configuration options in the plugin's Project Settings section within the editor.

These updates include:

• Customizing the corner/border radius of graph nodes
• Toggling the Arrange Nodes button in the graph toolbar
• Using user-friendly names for event graph and function items
• Replacing control flow connections when dragging starts rather than when it ends
• Dimming connection wires when highlight selected connections is enabled
• New title bar colors for orchestration, script, and built-in function calls
• Choosing between Lines or Dots grid patterns by default (requires Godot 4.3)
• Toggling the visibility of the grid pattern by default
• Toggling the use of grid snapping by default

All of these options can be found in Project > Project Settings > Orchestrator > UI:

Android support

Orchestrator 2.1 comes equipped with a brand-new arm32 and arm64 Android-compatible build, significantly expanding its versatility. This means you can now harness the power of Orchestrator while developing and creating mobile games. Whether you're building for smartphones or tablets, Orchestrator's enhanced compatibility ensures a seamless development experience, bringing your game design visions to life on Android devices. This addition empowers developers to create rich, interactive mobile gaming experiences with the same robust toolset they rely on for desktop.

Named GDScript / C# script support

While visual scripting is beneficial for many scenarios, there are times when using GDScript or C# might be more appropriate. In these cases, it's crucial for Orchestrator to integrate seamlessly with these other scripting languages, allowing you to leverage their full range of features.

A key feature of these scripting languages is the ability to define new class types, known as script Global Class types. In GDScript, this is done using the class_name keyword to create custom class types. Similarly, in C#, you can define custom class types using the [GlobalClass] annotation.

With Orchestrator 2.1, you can now define variables or function arguments that utilize Global Class types. Furthermore, you can create new instances of your custom Global Class types using the New Object node. This enhancement ensures that you can fully exploit the power and flexibility of GDScript and C# within Orchestrator.

Debugging improvements

One of the most powerful features of GDScript is its integration with the editor's debugger. We are excited to announce that we have made changes to Godot that expose the built-in editor debugger to GDExtension, enabling Orchestrator 2.1 to leverage this powerful tool.

Now, while running your orchestrations, if a node encounters an error, the editor will correctly trigger a breakpoint. This allows you to inspect the input and output states of the node that caused the error, providing a more efficient debugging process.

Additionally, we've refined many of the error messages returned by the runtime when a node encounters an issue. These messages are now clearer and easier to understand, helping you quickly identify what went wrong when an error occurs.

Orchestration function improvements

Orchestration functions have undergone a significant overhaul in 2.1. One of the most noticeable changes is the new Inputs/Outputs user interface in the Godot inspector. This new widget offers a more streamlined approach to defining function arguments and return values, making the process more intuitive and efficient.

Additionally, when you add a new output to the function definition, a return node is automatically created and can optionally be connected to the function entry node. As you modify the function declaration in the inspector, the return node will dynamically update to reflect those changes.

To simplify large function graphs, you can now add multiple return nodes. This greatly reduces complexity when wiring multiple nodes to a single return node.

Additionally, when connecting to a signal and programmatically registering a function, you need to create a Callable. For this purpose, when you drag a function from the component panel, you can now choose between creating a Call Function or a Create Callable. The latter option automatically spawns the necessary nodes to represent a Callable for the given function, as shown below:

Graph UI/UX Improvements

The Orchestration graph viewport has undergone several user interface and experience improvements.

First, the graph toolbar and nodes have been updated in styles, fonts, and colors to match the Godot Visual Shader plugin. One of Orchestrator's goals is to seamlessly integrate into the Godot editor, and the best way to achieve this is by remaining consistent with Godot's editor layout and design strategies. Additionally, all nodes have been realigned to prevent the left (inputs) and right (outputs) from overlapping into each other's space. This was a particular issue with several nodes, such as the Switch node, which has now been fixed.

Furthermore, a new reroute (knot) node feature has been implemented in the graph viewport. Reroute nodes allow you to place points that control where a connection between two nodes is drawn, helping to organize and simplify your graphs. You can place these reroute nodes by pressing the CTRL+LMB keybind while hovering over a connection.

Once placed, you can select and move the reroute node like any other graph element. Here's an example of what a graph with reroutes can look like:

Additionally, many input default value widgets have been enhanced. Numeric default value widgets now validate their input and prevent any non-numeric entries. Bitfield and Enumeration inputs have new user interfaces, making it easier and more user-friendly to select various values.

Graph nodes now include new alignment options in the node's context menu. These options allow you to align a group of nodes to a specific node's left, top, right, bottom, horizontal center, or vertical center axis, providing greater customization and better organization. Additionally, nodes can be moved using the arrow keys on your keyboard, rather than just by dragging with the mouse.

Finally, auto-wiring nodes have been improved. When a node has multiple pins eligible for auto-wiring, a dialog will appear, allowing you to choose which pin to apply the auto-wire to. You can also opt to skip the auto-wire, and this dialog can be disabled in the plugin's configuration settings if desired.

Validation improvements

A major overhaul in Orchestrator 2.1 focuses on helping users avoid mistakes when constructing their graphs. A validation subsystem now runs automatically when you press F5 to run your game or F6 to run the current scene. This validation step checks any open orchestration and alerts you to any mistakes found before the game runs.

To support this new validation subsystem, a new Orchestration Build panel has been added to the bottom of the Godot editor. This panel displays any build problems detected when playing your game or scene, as shown below:

The errors are hyperlinked, allowing you to click on them and be taken directly to the node that needs attention. These errors also provide helpful information about what might be wrong, such as a missing connection or an unspecified value.

New connection combinations

We have also enhanced the compatibility of connections between different node pins.

Any pin output can now be connected to a boolean input pin. This enables validation of whether strings are empty, objects are invalid, or whether a value is zero or non-zero. For specific struct types like Vector2 and Vector3, the boolean operator checks if each axis value is zero. For other types, such as Basis or Quaternion, the boolean operator verifies if the value is the default "identity" value or a non-identity value.

Additionally, since String and StringName are interchangeable in GDScript, C#, and C++, you can now connect a String-based output pin to StringName-based input pins.

These improvements aim to reduce the number of nodes needed in graphs and simplify validity checks.

New graph nodes

Orchestrator 2.1 introduces several new graph nodes, with the New Object and Free Object nodes being the most notable additions.

The New Object node allows you to create a new instance of a given Godot class type, similar to using the .new() operator in GDScript. This feature is particularly powerful when combined with the new script global-class support mentioned earlier.

The Free Object node simplifies the process of freeing objects by automatically determining whether to use .free() or queue_free(), ensuring the optimal method is applied.

Additionally, this release includes the new Static Function Call node, which enables orchestrations to access types such as FileAccess, DirAccess, and others. Previously, these features were unavailable in Orchestrator, requiring users to resort to GDScript to access them. Now, you can easily incorporate these functions directly into your orchestration graphs using Orchestrator.

Finally, a new simple Dictionary Set node has been added to support inserting values into a Dictionary data type.

Existing node improvements

Several existing graph nodes have also been enhanced to improve their functionality and usability.

The For with Break and For Each with Break nodes now feature a new output pin called Aborted. This pin receives the output impulse when the Break input pin is triggered, instead of the Completed pin. This allows your logic to distinguish whether the loop was terminated early or iterated through all items. By default, orchestrations will wire the Aborted pin to the same target as Completed, ensuring that existing orchestrations will not experience any change in behavior.

The Call Member Function node now features a new inspector property called Chain. In many text-based programming languages, method chaining is a common practice for calling multiple methods on the same object. This technique is particularly useful in Godot, for example, when creating Tweens. When the Chain property is enabled in the inspector, a new output pin is added to the node. This pin passes the input target object as an output value, allowing you to call multiple methods on the same object without cluttering the graph.

Additionally, all Call Function node types (including built-in, member, and static functions) now support methods with variable arguments. These methods allow you to add as many arguments to the function call as needed. You can easily identify such functions by the plus-button in the bottom-right corner, as shown here:

Finally, there are two additional improvements to existing nodes. First, any built-in, member function, or static function call node now respects Godot's default values when created, eliminating the need to manually set these default values. Second, the await signal node now triggers on signals that emit values.

Variable improvements

Similar to functions, Orchestration variables have received a small update in Orchestrator 2.1. Previously, variable types were quite limited. We have expanded variable classification to allow setting variables to explicit class types and enumerations. This improvement enhances their usability and reduces the need for excessive Type Cast nodes.

Additionally, variables can now be defined as const, representing a constant value. When a variable is marked as a constant, you can set its default value in the inspector panel, but you cannot change its value in the orchestration graph. Attempting to use a set node on a constant variable will result in a runtime exception.

Finally, variables can now be used with validation. This feature applies to variables typed to a Script or Godot native class type that extends Object. Validated get nodes simplify reading the variable, allowing you to easily determine actions based on whether the variable is set to a valid value or is null. Here's an example of what a validated variable get node looks like:

Godot editor integration improvements

There have been numerous improvements and bug fixes related to editor integration.

Firstly, Orchestrator now properly responds to all rename and remove operations for files and folders in the file system dock. In previous releases, this could lead to inconsistent behavior when files were renamed or removed. The editor viewports should now update accordingly, similar to how the Script tab handles these events.

Secondly, we received significant feedback from users who utilize custom themes like the godot-minimal theme. Previously, Orchestrator created new styles for some of its UI controls, which often conflicted with custom themes and caused editor crashes. In Orchestrator 2.1, we have relaxed Orchestrator's styles and expectations, allowing custom themes and plugins to work seamlessly with Orchestrator.

Another improvement you'll likely appreciate is the integrated help feature available through the View Documentation option in the node context menu. This new documentation option will either direct you to the Godot method's internal documentation (for instance, when using a method like set_visible) or display the Orchestrator node's documentation if no Godot contextual help is required (such as with the Variable Set or Variable Get nodes). While the documentation is still a work in progress, we welcome your feedback.

Lastly, the plugin updater UI has been completely overhauled. Users of Godot 4.2 and Orchestrator 2.0.x reported that it wasn't clear when a new 2.1 release was published that it wasn't compatible with their Godot version. The new user interface addresses this issue by allowing you to select the desired version to install and informing you whether the chosen version is compatible with your Godot editor version.

All actions dialog improvements

At the heart of Orchestrator is the All Actions dialog window, where you select the nodes to add to your orchestration. This window has been significantly overhauled to enhance its usability and effectiveness.

Firstly, all menu items are now organized into descriptive top-level categories, such as Methods, Properties, and Types. This new classification aims to help users find what they're looking for more easily when browsing through the options.

Secondly, the search algorithm has been redesigned and now uses a new scoring system to more accurately predict and select the right actions based on your keyword entries. Additionally, many nodes have been given extra keywords to make them easier to find, such as separate or split for the Break nodes and create, combine, or make for the Make nodes.

Lastly, all Godot engine singletons and project-level autoloads are now automatically included in the list of actions. While you can still place an Engine Singleton node or a Get Autoload node directly into the graph, selecting the specific engine singleton or project autoload from the list eliminates the need to interact with the inspector, saving you time.