Scriptable Tools System

The Scriptable Tools system provides functions and an editor mode to create custom interactive tools. The goal of the system is to make it possible for non-C++ programmers to build interactive tools in Unreal Engine.

The main point of reference for an interactive tool is the Modeling editor mode. However, the Scriptable Tools system has no direct connection to Modeling Mode or Geometry Scripting.

The Scriptable Tools system plugin exposes the Interactive Tools Framework to Blueprint (BP), providing creators and technical artists the means to design tools that behave similarly to Modeling Mode.

We recommend understanding the fundamentals of Blueprints to get started with Scriptable Tools. To learn more, see Introduction to Blueprints.

By creating Blueprint (BP) subclasses of base classes, you can add custom-defined tools to the Scriptable Tools editor mode. With the editor mode, artists can access these custom tools for their projects.

What is a Scriptable Tool For

You can use a scriptable tool to:

• Run arbitrary Blueprint (BP) graphs at tool setup and shutdown, as well as on tick.
• Draw basic 3D geometry (for example, lines and points) and 2D HUD geometry (for example, text at projected 3D locations)
• Add property sets to a tool, defined through Blueprints, which act as user-visible tool settings.
• Listen for and respond to changes to those property set parameters.
• Create one or more 3D gizmos, control their positions, and respond to transform changes.
• Provide feedback messages to the user.
• Add input device behaviors, like mouse click, mouse hover, and keyboard watchers, and run Blueprint graphs on their key events.
• Integrate with Blueprint Slate Widgets (UMG) to provide custom user interface (UI) as in viewport widgets.
• Define custom conditions for the tool to start based on current scene selections.

You can pair Scriptable Tools with other features of the engine, such as Procedural Content Generation (PCG) and Motion Design.

For an overview of the system and how developers used it with other features to build a dungeon, see the Geometry Scripting and Scriptable Tools | Unreal Fest 2024 video.

Access Scriptable Tools Editor Mode and Nodes

Enable Plugin

To use the Scriptable Tools editor mode and access the nodes, you must enable the associated plugin.

To enable the plugin or verify that it is already enabled, follow these steps:

1. In the menu bar, select Edit > Plugins.

2. In the search bar, type "scriptable tools".

3. Enable Scriptable Tools Editor Mode plugin, and select Yes in the dialog popup.

You do not need to enable the Scriptable Tools Framework module. The editor mode automatically includes it.

Editor Mode

You access all scriptable tools from the Scriptable Tools editor mode. To open the editor mode, click the Selection Mode dropdown in the Level Editor.

Each tool appears in an automatically-managed tool palette in the editor mode, and the property sets for an active tool appear in the settings panel. To learn more about editor modes, see Level Editor Modes.

The tool palette includes a filter option that displays tools based on a group tag. The feature provides the means to group tools together and select which groups of tools to load in the editor mode. The grouping helps organize a project with many tools, which can reduce the cognitive load of seeing all the tools.

Blueprint Nodes

To create tools that appear in the editor mode, use the Scriptable Tool functions exposed in Blueprints. You can use either a Blueprint Class or Editor Utility Blueprint to access the scriptable tool base class. To learn more about the base class and subclass, see the Scriptable Tool Classes section on this page.

In the Blueprint Editor, all the Scriptable Tool nodes live under the Scriptable Tool sub-menu.

Scriptable Tool sub-menu in the Blueprint Editor.

For a full list of functions, see the Blueprint and Python API documentation.

Scriptable Tool and Editor Utility Widget Differences

An Editor Utility Widget (EUW) is a non-modal dialog window, containing a custom UI built with a visual GUI builder, where you can do any kind of editor scripting. This is an extremely powerful facility, but as a non-modal dialog there are various limitations.

An interactive tool (the basis for Scriptable Tools) is modal. Modal means that no other tool can be active while the tool is active, and the editor state is more strictly managed. For example, the tool automatically shuts down before saving, changing levels, or starting Play In Editor (PIE), and autosave is deferred until you exit the tool. This functionality means many things are safer to do in a tool than otherwise. For example, if you create temporary actors in a level and destroy them during tool shutdown, then they are not accidentally saved.

Similarly, as a modal state, a tool can capture the mouse more efficiently.

In terms of UI, a scriptable tool is more structured than an EUW. You can define property sets as separate BP objects with public variables. Those public variables are then displayed in a standard editor mode settings panel.

Scriptable Tools are available at runtime, however some additional infrastructure must be set up to take advantage of this in a UE project.

Additionally, Scriptable Tools provide a more central location to discover and access all tools found in the project, whereas EUWs are primarily accessed from the Content Browser, leaving it up to the user to manage discoverability and organization.

Scriptable Tool Classes

UScriptableInteractiveTool is the base class for all scriptable tools. The class includes events, general settings such as tool name, rendering options, gizmos, messaging, tool shutdown options, and more for the subclasses. You can use its editor-variant, UEditorScriptableInteractiveTool, to provide access to editor-only BP functions.

The UScriptableModularBehaviorTool and UEditorScriptableModularBehaviorTool are the subclasses for supporting mouse and keyboard interactions within the tool. These two are the common classes to use, unless mouse and keyboard behavior are not needed.

UScriptableClickDragTool is deprecated. However, tools you previously created from the class will function in the latest editor version.

When you create a Blueprint Class or Utility Widget Blueprint you must select one of the classes above to access the Scriptable Tools nodes. To learn more about these classes, see the Modular Base Tool section on this page.

Scriptable Tool Settings

The base class exposes various settings that are primarily for the Scriptable Tool editor mode UI, but also controls tool behavior. When you open your Blueprint, the Details panel for the tool contains the following options.

Scriptable Tool Events

The Scriptable Tool class provides a set of standard events for your tool to do different things at different times. There are standard events that every tool class has, and various additional functions are available in the base tools.

• Event On Script Setup: Runs a single time when the tool is launched. This is generally where you would add Property Sets, create any preview objects, and more.

• Event On Script Tick: Runs every Editor tick, just like other ticks.

• Event On Script Shutdown: Runs when the tool is shut down. For example, when the user explicitly closes the tool, the mode forces it to shut down, or the tool shuts itself down.

• Event On Script Draw HUD: Runs every frame and where the tool can draw a 2D HUD from a HUD API object. For more information, see the section below.

Event On Script Render is a legacy drawing method. The event runs every frame and allows the tool to draw simple 3D geometry like lines and points. You can use the legacy feature but should note the following:

• The event is real-time, so the lines are redrawn each and every time Render is called.

• There aren't any persistent references held to the geometry, so you must manage the manipulations of the primitives in the Blueprint.

Custom Conditions

You can add custom conditions based on current scene selections to start the tool. Define the custom conditions in Class Defaults > Details panel > Scriptable Tool Settings > Tool Setup Requirements > Custom.

The custom class contains the following functions:

• OnCanBuildTool: Has to be run on tick.

• OnSetupTool: Runs after user clicks and before tool runs.

The tool builder graph is run every tick, so complex conditions here can risk slowing the editor's performance.

Tool Rendering

It is common for a tool to provide visual feedback. One way to define this feedback is by spawning temporary actors. For example, you can spawn temporary dynamic mesh actors with meshes procedurally generated by Geometry Scripting. However, a line or a text label is often more effective.

Scriptable Tools support this rendering by providing API objects with a set of UFunction nodes.

Rendering Options

The Drawing API of Scriptable Tools includes render option sets for lines, points, and triangles. Each set then includes additional relative options in the Drawing category.

These drawing options are allocated by the tool and contain the geometry. With these sets, you can add and remove the respective geometry at any point during the tool's lifetime and update them as needed.

The Add Triangle Set node includes options for quads.

Legacy Options

You execute the legacy rendering commands in the Event On Script Render event node.

As noted earlier with this event:

• You can override with the rendering API.

• Draw lines and points.

• It runs on the tick and goes away on the next tick.

• No persistence.

The 2D Draw HUD and 3D Render events are called with DrawHUDAPI and RenderAPI objects, respectively. The tool creates and manages these API objects internally. The only place you can access them is from these events, as they depend on per-frame temporary state information provided by the tool.

BP also has a standard library of Debug Draw functions. You can use these as an alternative to the DrawHUD and Render functions and call them at any time. However, they are development only, and the tool Render APIs will provide more functionality.

Gizmos

Another functionality of the Scriptable Tool base class is the option to create multiple 3D transform gizmos. This widget is not the standard editor gizmo but rather Modeling Mode's gizmo. A set of functions is provided to develop and manage gizmos and an event to respond to gizmo changes.

Gizmo objects are not directly exposed to Blueprints. Instead, you spawn a gizmo with a string Identifier, and the various gizmo functions and events work from this Identifier.

The basic TRS gizmo combines translation, rotation, and scale elements for all axes. However, by customizing the Gizmo Options you can create simpler gizmos for specific tasks. For example, only enabling translation and rotation in the XY plane, by disabling the other gizmo sub-elements.

Tool Messaging

The standard scriptable tool BP API provides various functions for messaging to the user.

• Display User Help Message: Updates a help string at the bottom of the Editor UI.

  

• Display User Warning Message: Updates a string in the tool Settings panel.

  
• Clear User Messages: Clears current help or warning messages.
• Add Log Message: Currently prints a message to the editor's log.

The messages above are FText strings, and so are localizable. Currently only a single Warning can be displayed, this may be improved in future.

Miscellaneous

A scriptable tool always runs in the context of a current world. For example, in the Level Editor, it is the standard level world. You can use the Get Tool World function to access this world in the context of a tool.

Tool Shutdown

The standard flow for exiting a scriptable tool is clicking an Accept, Cancel, or Complete button presented in the UI. However, you can explicitly shut down a scriptable tool from the Request tool Shutdown function, which the tool can call itself. This function takes a bAccept flag, which is only relevant to tools with the accept or cancel shutdown option and an optional user popup message.

Tool Property Sets

A scriptable tool can expose UI widgets to the user from Property Set UObjects, which are displayed in a standard tool settings panel. Currently, there is no way to customize this UI in Blueprints, so only standard property settings ( similar to what can be done for a parameter in an actor BP) are available.

To create a property set, create a BP subclass of the type ScriptableInteractivetoolPropertySet, as shown below.

You can then open the property set subclass BP for editing and add public member variables. Below a boolean, integer, and enum type is added.

To create the property set in a particular scriptable tool, use the Add Property Set of Type function. This function is generally used in the Event On Script Setup. However, you can use it at any point.

You must select the correct class type for the Property Set Type parameter. Choose the type name of your BP subclass you created above. In addition, you must set a unique Identifier for each property set (you can combine multiple property sets in a single tool). You will likely need access to this property set object later. We recommend you cast the output of Add Property Set Of Type to your BP subclass type and store it in a local variable.

When the user creates an instance of your scriptable tool, the public member variables of your property set are shown in the Scriptable Tools settings panel on the left, next to the tool palette.

The Scriptable Tool class has various helper functions for working with Property Sets. You can use Remove Property Set by Name to remove a property set, however note that this is not necessary to do in most cases. If you simply want to hide or show a Property Set based on some criteria or other parameter change, use Set Property Set Visible by Name.

In addition, you can use Save Property Set Settings on tool shutdown to store the current values of a property set, and Restore Property Set Settings can recover those saved values on tool setup. By default, the same values are restored in any tool using the Property Set class. However, an optional Save Key can be provided to save or restore different values in different tools, or even within the same tool.

Property Watchers

A common function you will likely want to do with a Property Set is react to changes in the property values. The only fully reliable solution is to poll for value changes in the tick function. However, since this is a common pattern, the Scriptable Tool system provides utility Property Watcher functions that can automatically do this polling.

You can use the functions below in a scriptable tool to watch for changes in a specific property of a Property Set and call an event when the value is modified.

In BP, it is currently not possible to automatically detect a UProperty Type from a variable reference. To set up the detection, ensure the following:

• Make sure to use the function that matches the type of the public variable in the property set.
• Pass the correct Property Name (the name of the public variable in the property set).

If the type is not simple (Int, Float, Bool, String, FName, Enum, or Object Property), use the general-purpose Watch Property version. However, its callback event is more limited.

Below is an example of the Watch Enum Property function. This is the most complex of the simple types, as the Enum type is unknown. The New Value parameter that is passed to the callback event is a uint8 and must be explicitly cast to the correct UEnum type (in this case, EGeometryScriptAxis). It is currently not possible to check any errors here. The editor will cast the function to any Enum type.

For complex parameters, such as a nested UStruct like an FVector member variable, you can use the Watch Property function. This function can detect changes in nearly any UProperty variable. However, the callback event will not receive a New Value parameter like the other fields. If you create a member variable for the property set in your tool, you can directly fetch the property value in the event. This watcher type is also more computationally expensive, and you should only use it when necessary.

Modular Base Tool

Base tools are C++ subclasses of Scriptable Interactive Tool Framework that provide additional built-in functionality to handle common cases and expose additional functionality such as input device handling and capture. You choose a base tool based on what type of tool you want to create. The editor version of the base tool provides access to editor-only BP functions.

The Scriptable Modular Behavior Tool class and its editor instance provide access to behavior functions, which are parameterized by a list of callbacks. This system replaces the built-in events and provides the means to mix and match behaviors, potentially even with duplication. This replacement is helpful because you can create multiple click behaviors within a single tool that triggers different conditions. For example, one click with the left mouse button, another with the right, and another with left + ctrl.

The exposed behaviors include the following:

• Click and drag
• Hover
• Mousewheel
• Multi-click
• Click or drag
• Single and multi keyboard inputs

Scriptable Tools behavior inputs.

Enable Plugins for Editor-Only

In Unreal Engine, you can define plugin dependencies for project modules and plugins.

In the .uproject and .uplugin files that require UScriptabletoolsFramework or UScriptabletoolsEditorMode for in-editor usage, configure the TargetAllowList section to Editor. To learn more about plugins and file configuration, see Plugins.

		{

			"Name": "ScriptabletoolsEditorMode",

			"Enabled": true,

			"TargetAllowList": [

				"Editor"

			]

		},	
Copy full snippet

{ "Name": "ScriptabletoolsEditorMode", "Enabled": true, "TargetAllowList": [ "Editor" ] },

Next Steps

With a base understanding of the Scriptable Tools system, you can get started making your tools with the Creating a Scriptable Tool tutorial.