Scriptable Tools System

The goal of the Scriptable Tools system is to make it possible for non-C++-programmers to build interactive tools in the Unreal Editor. The main point of reference for what an interactive tool is would be Modeling Mode. However, the Scriptable Tools system has no direct connection to modeling or meshes.

The Scriptable Tools system plugin, ScriptableInteractiveTool, exposes the Interactive Tools Framework to Blueprint (BP), making it possible for creators and technical artists to design tools that behave similarly to the Modeling Mode.

By creating BP subclasses of base classes, custom user-defined tools can be added to Scriptable Tools editor mode. These scriptable tools can be paired with Geometry Scripting to implement complex modeling and asset editing workflows. You can also use the tools for simpler functions not related to modeling or geometry.

What is a Scriptable Tool For?

Using a scriptable tool you can create a sort of mini mode where you can:

• Run arbitrary Blueprint (BP) graphs at tool setup and shutdown, as well as on Tick.
• Draw basic 3D geometry (lines, points) and 2D HUD geometry (text at projected 3D locations).
• Add property sets to a tool, defined via Blueprints, which act as the tool's 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.
• Capture and respond to specific types of mouse interaction, in particular in-viewport click and click-drag interactions, as well as mouse hover and shift, ctrl, and alt modifier keys.

You access all scriptable tools from the Scriptable Tools editor mode, where each tool appears in an automatically-managed Tool Palette, and the property sets for an active tool are exposed in a standard editor mode Details panel. To learn more about editor modes, see Tools and Editors.

The Create a Scriptable Tool section of the page includes a turotial for creating a tool that spawns new dynamic mesh spheres in the level.

Scriptable Tool and Editor Utility Widget

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 being a non-modal dialog comes with various limitations.

An Interactive tool (the basis for Scriptable tools) is modal, meaning that while the tool is active, no other tool can be 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 after you exit the tool. This means many things are safer to do in a tool then they might be otherwise. For example, if you create temporary actors in the level, and destroy them on tool shutdown, then they will not be 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 will then be displayed in a standard Details panel. This is in some ways much simpler than an EUW, but that simplicity of course comes with many limitations. There is currently no way to build a custom UI for a scriptable tool.

Scriptable tools are also technically available at runtime, although some additional infrastructure must be set up to take advantage of this in a UE project.

UInteractiveScriptabletool

UInteractiveScriptabletool is the base class for all scriptable tools. However, for building Editor tools you most likely want to subclass EditorInteractiveScriptabletool, otherwise you will not have access to Editor-only BP functions.

Scriptable Tool Settings

The base class exposes various settings that are primarily for the Scriptable Tool editor mode UI, but also control tool behavior.

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 five standard events that every tool class has, and various additional functions are available in the Base tools described below.

• 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: Runs every frame and allows the tool to draw simple 3D geometry like lines and points.

Tool Rendering

It is quite common in a tool to want to provide visual feedback. This can always be done by, for example, spawning temporary actors (for example spawning temporary dynamic mesh actors with meshes procedurally generated by Geometry Script is quite a simple way to do this). However often a line or a text label would be more effective.

Tools support this kind of rendering by providing API objects that provide a set of UFunction nodes. 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.

There is also a standard library of Debug Draw functions available in BP. These can also be used, as an alternative to the DrawHUD and Render functions, and they can be called at any time. However, they are development only, and the tool Render APIs will (eventually) provide more functionality._

Gizmos

Another functionality of the scriptable tool base class is the ability to create multiple 3D transform gizmos. This is not the standard editor gizmo, but rather Modeling Mode's gizmo. A set of functions is provided to create 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 update a string in the tool Settings panel.

  
• Clear User Messages can be used to clear 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 will be 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, a scriptable tool can also be explicitly shut down via the Request tool Shutdown function, which the tool can also call itself. This function takes a bAccept flag which is only relevant to Accept/Cancel-style tools, as well as an optional user popup message.

Tool Property Sets

A scriptable tool can expose UI widgets to the user via Property Set UObjects, which are displayed in a standard Details 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, first 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 use the property set in a particular scriptable tool, the function Add Property Set of Type is used. This function is generally used in the Event On Script Setup, however it can be used at any point. You must select the correct class type for the Property Set Type parameter - select the type name of your BP Subclass you created above. In addition you must set a unique Identifier for each different property set (you can combine multiple property sets in a single tool). Finally as you will likely need access to this Property Set object later, it is recommended to cast the output of Add Property Set Of Type to your BP subclass type and store it in a local variable.

Now when the user creates an instance of your scriptable tool, the public member variables of your Property Set will be 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

One of the most common things you will likely want to do with a Property Set is react to changes in the property values. This can be tricky and 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 provides utility Property Watcher functions that can do this kind of polling automatically.

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, so you must:

• Make sure you 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 a simple type (Int, Float, Bool, String, FName, Enum, or Object Property) then the general-purpose Watch Property version can be used, however its callback event is more limited.

Below is an example usage of the Watch Enum Property function. This is the most complex of the simple types, as the Enum type is not known. The New Value parameter that will be 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 do any error checking here, the function will cast to any Enum type.

Finally, for more complex parameters (for example, a nested UStruct like an FVector member variable) the Watch Property function can be used. 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. However, if you created a member variable for the Property Set in your tool, you can directly fetch the Property value in the Event. This type of Watcher is also more computationally expensive and should only be used when necessary.

Base tools

Base tools are C++ subclasses of Scriptable Interactive Tool Framework that provide additional built-in functionality to handle common cases and/or expose additional functionality such as input device handling and capture.

Scriptable Single Click Tool

Mouse Click support:

• TestIfHitByClick: Must return valid FInputRayHit indicating hit-depth to capture mouse clicks.

• OnHitByClick: Called when click occurs on both mouse-down and mouse-up.

Hover support:

• OnHoverHitTest: Must return valid FInputRayHit indicating hit-depth to capture hover.

• OnHoverBegin: Called when hover sequence starts, after passing OnHoverHitTest.

• OnHoverUpdate: Called each time the cursor moves during hover state.

• OnHoverEnd: Called when hover ends.

Scriptable Click Drag Tool

Mouse Drag support:

• TestIfCanBeginClickDrag: Must return valid FInputRayHit indicating hit-depth to begin drag sequence.

• OnDragBegin: Called when drag sequence begins, after passing TestIfCanBeginClickDrag

• OnDragUpdatePosition: Called during drag sequence when cursor moves.

• OnDragEnd: Called when drag sequence terminates due to mouse-up.

• OnDragSequenceCancelled: Called when drag sequence terminates due to various such as escape key and window losing focus.

Hover support:

• OnHoverHitTest: Must return valid FInputRayHit indicating hit-depth to capture hover.

• OnHoverBegin: Called when hover sequence starts, after passing OnHoverHitTest.

• OnHoverUpdate: Called each time the cursor moves during hover state.

• OnHoverEnd: Called when hover ends.

Enabling Plugins for Editor-Only

Configure the TargetAllowList section to only include Editor in uproject and uplugin files that only require ScriptabletoolsFramework or ScriptabletoolsEditorMode for in-editor usage:

		{

			"Name": "ScriptabletoolsEditorMode",

			"Enabled": true,

			"TargetAllowList": [

				"Editor"

			]

		},	
Copy full snippet

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

Create a Scriptable Tool

This guide shows you how to create a new tool Blueprint that spawns new dynamic mesh spheres in the level, on click, with a radius property exposed in the tool's UI.

Enabling Plugins

Using Scriptable Tools editor mode requires having the associated plugin enabled.

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, it is automatically included by the Editor Mode.
4. Several functions in the steps below also require the Geometry Scripting plugin, so enable that if you haven't already.
5. Restart the editor, then switch to the new mode from the Selection Mode dropdown, Scriptable Tools mode.

6. You should see a UI similar to below, with an empty Tool Palette on the left.

   

Core Setup

1. Right-click in the Content Browser, select the Editor Utilities submenu in the popup, and create a new Editor Utility Blueprint. Type "Scriptable" into the search box and select EditorScriptableSingleClicktool

   

   It is not strictly necessary to use an 'Editor Utility Blueprint', you can also create a regular Blueprint Class. However if you are creating an Editor tool, and you use Blueprint Class instead of Editor Utility Blueprint, then you will not have access to Editor Subsystems and various other Editor-only functionality (even inside an EditorScriptabletool).

2. Name the new BP Asset tool_MakeSphere, and then right-click and select Edit, or double-click the asset, to open the Blueprint. In the Details panel on the right of the BP Editor, you can give the tool a name, "Sphere" is used for this example. Also fill in the Category name with a string.

   

3. Compile (Ctrl + Alt) and Save (Ctrl + S). Switch back to the Scriptable Tools Mode. The Sphere tool should now appear in the Tool Palette in a section with the corresponding category name.

   

4. You can run the Sphere tool now, of course it won't do anything, but you are able to start the tool. Use the Complete button at the bottom-center of the viewport to exit the tool.

   

5. Go back to the BP Editor. In the left panel, hover over the end of the Functions section. An Override dropdown will appear. Select Test If Hit By Click to create a new event for mouse hit-testing. The functions in the dropdown list are the available tool API functions you can implement.

6. Connect the functions as below.

   

7. Add a second Override for the On Hit By Click event

8. Right-click on the Click Pos pin in Event On Hit By Click and select Split Struct Pin. Then wire up the Click event as shown below. Essentially here, you are repeating the same line-trace as the Hit Test event, then on hit, spawning a Dynamic Mesh actor (the node here is initially "Spawn actor from Class", and then once you select Dynamic Mesh actor in the dropdown, it will change names), and then setting the mesh in that actor to a Sphere, using Geometry Scripting.

   

   The Split Struct Pin option is used by right-clicking on some Pins in the BP Nodes, to simplify the graph.

9. Compile and return to the main Viewport, and run the Sphere tool. Click in the viewport, and a new sphere should be placed at the click location.

   

Add a Radius Property

You now have the base of your tool created. To expand functionality, you can add a radius setting for the spheres.

1. Go back to the Content Browser, right-click, create a new Blueprint Class, and type "propertyset" into the search box, then select ScriptableInteractivetoolPropertySet. Give the new BP Asset a name (I used "MakeSphere_Settings"), and then open it to Edit.

   

2. In the Variables section on the left, click the + in the circle to add a new variable. Name it Radius, change the type to Float, and make it Public by clicking the eye icon to be open (if you do not make the variable public, it will not appear in the Details panel). Compile (Ctrl + Alt) and Save (Ctrl + S).

3. In the right panel, find the Slider Range field and set it to values 10 and 200, and then set the Default Value to 50. Compile a second time.

   

4. Now return the tool Blueprint and add an Override for the On Script Setup function.

5. In the Event On Script Setup, call the Add Property Set Of Type node, and select your property set BP class in the type dropdown (the same name as you used above, MakeSphere_Settings).

   

6. Create a variable for the Property Set, this will simplify things later. Add a Cast To node, where is your BP settings class name (for example, MakeSphere_Settings).

7. Right-click on the As Make Sphere Settings pin and select Promote to Variable. This automatically adds a new variable. Rename the variable to "Settings".

8. Return to the graph for the On Hit By Click event, and wire up the public Radius field from the Settings variable to the Radius pin of the Append Sphere Box node, and then Compile.

   

9. Return to the Viewport and run the Sphere tool again. In the Details panel you should now see a slider for the Radius field. If you change this value, the sphere that is placed will change size.

   

You have created a tool with custom settings and handled mouse clicks all in Blueprints.