unreal.ScriptableInteractiveTool

class unreal.ScriptableInteractiveTool(outer: Object | None = None, name: Name | str = 'None')

Bases: InteractiveTool

UScriptableInteractiveTool is an extension of UInteractiveTool that allows the Tool functionality to be defined via Blueprints.

C++ Source:

  • Plugin: ScriptableToolsFramework

  • Module: ScriptableToolsFramework

  • File: ScriptableInteractiveTool.h

Editor Properties: (see get_editor_property/set_editor_property)

  • custom_icon_path (str): [Read-Write] deprecated: Use ToolIconTexture instead.

  • custom_tool_builder_class (type(Class)): [Read-Write]

  • group_tags (ScriptableToolGroupSet): [Read-Write] Tool Tagging Support

  • show_tool_in_editor (bool): [Read-Write] A generic flag to indicate whether this Tool should be shown in the UE Editor. This may be interpreted in different ways

  • tool_category (Text): [Read-Write] Category of this Tool, will be used in (eg) Tool Palette Section headers

  • tool_icon_texture (Texture2D): [Read-Write]

  • tool_long_name (Text): [Read-Write] Long Name of this Tool, will be used in (eg) longer labels like the Accept/Cancel toolbar

  • tool_name (Text): [Read-Write] Name of this Tool, will be used in (eg) Toolbars

  • tool_shutdown_type (ScriptableToolShutdownType): [Read-Write] Specifies how the user exits this Tool, either Accept/Cancel-style or Complete-style

  • tool_startup_requirements (ScriptableToolStartupRequirements): [Read-Write]

  • tool_target_tool_builder_class (type(Class)): [Read-Write]

  • tool_tooltip (Text): [Read-Write] Tooltip used for this Tool in (eg) icons/etc

add_line_set() → ScriptableToolLineSet

Create and return a new, independent line set, used for drawing persistent line objects in the scene. Users must save a reference to the created object for future access.

Returns:

A reference to a new line set object

Return type:

ScriptableToolLineSet

add_log_message(message, highlighted=False) → None

Append a Message to the UE Editor Log.

Parameters:

  • message (Text)

  • highlighted (bool) – if true, the message is emitted as a Warning, otherwise as a Log (normal)

add_point_set() → ScriptableToolPointSet

Create and return a new, independent point set, used for drawing persistent point objects in the scene. Users must save a reference to the created object for future access.

Returns:

A reference to a new point set object

Return type:

ScriptableToolPointSet

add_property_set_of_type(property_set_type, identifier="Settings") -> (ScriptableInteractiveToolPropertySet, outcome=ToolsFrameworkOutcomePins)

Create a new Tool Property Set (ie BP subclass of UScriptableInteractiveToolPropertySet) with the given string Identifier and attach it to the Tool. The public variables of this Property Set object will appear in (eg) Mode Details Panels, etc. Multiple Property Sets of the same Type can be attached to a Tool, but each must have a unique Identifier.

Parameters:
Returns:

outcome (ToolsFrameworkOutcomePins):

Return type:

ToolsFrameworkOutcomePins

add_triangle_set() → ScriptableToolTriangleSet

Create and return a new, independent triangle set, used for drawing persistent triangle and quad objects in the scene. Users must save a reference to the created object for future access.

Returns:

A reference to a new triangle set object

Return type:

ScriptableToolTriangleSet

clear_overlay_widget() → None

Clear Overlay Widget

clear_user_messages(help_message=True, warning_message=True) → None

Clear any active message shown via DisplayUserHelpMessage and/or DisplayUserWarningMessage

Parameters:

  • help_message (bool)

  • warning_message (bool)

create_trs_gizmo(identifier="Gizmo1", initial_transform, gizmo_options) → ToolsFrameworkOutcomePins

Create a Translate/Rotate/Scale Gizmo with the given Options at the specified InitialTransform. The Gizmo must be given a unique Identifier, which will be used to access it in other functions. The Gizmo can be explicitly destroyed with DestroyTRSGizmo(), or it will be automatically destroyed when the Tool exits

Parameters:
Returns:

outcome (ToolsFrameworkOutcomePins):

Return type:

ToolsFrameworkOutcomePins

property custom_icon_path: str

[Read-Write] deprecated: Use ToolIconTexture instead.

Type:

(str)

property custom_tool_builder_class: Class

[Read-Write]

Type:

(type(Class))

destroy_trs_gizmo(identifier='Gizmo1') → ToolsFrameworkOutcomePins

Destroy a created Gizmo by name Identifier

Parameters:

identifier (str)

Returns:

outcome (ToolsFrameworkOutcomePins):

Return type:

ToolsFrameworkOutcomePins

display_user_help_message(message) → None

Display a short Help message for the user, ie to guide them in Tool usage. In the UE5 Editor this message appears in the bottom bar of the window.

Parameters:

message (Text)

display_user_warning_message(message) → None

Display a Warning message to the user, ie to indicate a problem/issue occurred.

Parameters:

message (Text)

force_property_set_update_by_name(identifier='Settings') → None

Force the Property Set associated with the given Identifier to be updated. This may be necessary if you change the Property Set values directly via Blueprints, and want to see your changes reflected in (eg) a Details Panel showing the Tool Property values. Currently these changes cannot be detected automatically, necessitating this function.

Parameters:

identifier (str)

get_default_line_set() → ScriptableToolLineSet

Retrieve the default line set object for the tool, used for drawing persistent line objects in the scene.

Returns:

A reference to the tool’s default line set object

Return type:

ScriptableToolLineSet

get_default_point_set() → ScriptableToolPointSet

Retrieve the default point set object for the tool, used for drawing persistent point objects in the scene.

Returns:

A reference to the tool’s default point set object

Return type:

ScriptableToolPointSet

get_default_triangle_set() → ScriptableToolTriangleSet

Retrieve the default triangle set object for the tool, used for drawing persistent triangle and quad objects in the scene.

Returns:

A reference to the tool’s default triangle set object

Return type:

ScriptableToolTriangleSet

get_drawable_geometry_actor() → Actor

Return the actor that owns any line, point and triangle sets added to this tool.

Returns:

A reference to the actor object that owns drawable geometry sets.

Return type:

Actor

get_gizmo_transform(identifier='Gizmo1') → Transform

Get the current Transform on the Gizmo specified by the name Identifier

Parameters:

identifier (str)

Return type:

Transform

get_tool_targets() → Array[ToolTarget]

Get Tool Targets

Return type:

Array[ToolTarget]

get_tool_world() → World

Access the World this Tool is currently operating on.

Return type:

World

on_gizmo_transform_changed(gizmo_identifier, new_transform) → None

The OnGizmoTransformChanged event fires whenever the transform on any Gizmo created by CreateTRSGizmo() is modified. The GizmoIdentifier can be used to disambiguate multiple active Gizmos.

Parameters:
on_gizmo_transform_state_change(gizmo_identifier, current_transform, change_type) → None

The OnGizmoTransformStateChange event fires whenever the user start/ends a Gizmo transform, or when an Undo/Redo event occurs. Note that when Undo/Redo occurs, OnGizmoTransformChanged will also fire. The GizmoIdentifier can be used to disambiguate multiple active Gizmos.

Parameters:
on_script_can_accept() → bool

CanAccept function. Implement this function for AcceptCancel Tools, and return true when it is valid for the Tool Accept button to be active. Defaults to always true.

Return type:

bool

on_script_draw_hud(draw_hudapi) → None

OnScriptDrawHUD is called every frame. Use the DrawHUDAPI to draw various simple HUD elements like text. This drawing is not very efficient but is useful for basic Tool visualization/feedback.

Parameters:

draw_hudapi (ScriptableTool_HUDAPI)

on_script_render(render_api) → None

OnScriptRender is called every frame. Use the RenderAPI object to draw various simple geometric elements like lines and points. This drawing is not very efficient but is useful for basic Tool visualization/feedback.

Parameters:

render_api (ScriptableTool_RenderAPI)

on_script_setup() → None

Implement OnScriptSetup to do initial setup/configuration of the Tool, such as adding Property Sets, creating Gizmos, etc

on_script_shutdown(shutdown_type) → None

OnScriptShutdown is called when the Tool is shutting down. The ShutdownType defines what the Tool should do. For Complete-style Tools, there is no difference, but for Accept/Cancel-style Tools, on Accept the Tool should “commit” whatever it is previewing/etc, and on Cancel it should roll back / do-nothing. Which of these occurs is based on the ToolShutdownType property.

Tool Shutdown cannot be interrupted/aborted

Parameters:

shutdown_type (ToolShutdownType)

on_script_tick(delta_time) → None

OnScriptTick is called every Editor Tick, ie basically every frame. Implement per-frame processing here.

Parameters:

delta_time (float)

remove_property_set_by_name(identifier='Settings') → ToolsFrameworkOutcomePins

Remove a Property Set from the current Tool, found via it’s unique Identifier. Unless the Property Set absolutely needs to stop existing, it is likely preferable to use SetPropertySetVisibleByName() to simply hide it.

Parameters:

identifier (str)

Returns:

outcome (ToolsFrameworkOutcomePins):

Return type:

ToolsFrameworkOutcomePins

request_tool_shutdown(accept, show_user_popup_message, user_message) → None

Request that the active Tool be shut down. The Tool can post this to shut itself down (eg in a Tool where the interaction paradigm is “click to do something and exit”).

Parameters:

  • accept (bool) – if this is an Accept/Cancel Tool, Accept it, otherwise Cancel. Ignored for Complete-type Tools.

  • show_user_popup_message (bool)

  • user_message (Text)

restore_property_set_settings(property_set, save_key) → ScriptableInteractiveToolPropertySet

Restore the values of the specified PropertySet, optionally with a specific SaveKey string. This will have no effect unless SavePropertySetSettings() has been called on a compatible Property Set in the same Engine session (ie in a previous invocation of the Tool, or another Tool that uses the same Property Set)

Parameters:
Return type:

ScriptableInteractiveToolPropertySet

save_property_set_settings(property_set, save_key) → ScriptableInteractiveToolPropertySet

Save the values of the specified PropertySet, optionally with a specific SaveKey string. These saved values can be restored in future Tool invocations based on the SaveKey.

Parameters:
Return type:

ScriptableInteractiveToolPropertySet

set_focus_in_viewport() → None

Viewport Focus API

set_gizmo_transform(identifier="Gizmo1", new_transform, undoable) → None

Update the Transform on the Gizmo specified by the name Identifier

Parameters:

  • identifier (str)

  • new_transform (Transform)

  • undoable (bool) – if true, this transform change will be transacted into the undo/redo history, ie undoable

set_gizmo_visible(identifier="Gizmo1", visible) → None

Set an existing Gizmo visible/hidden based on its name Identifier

Parameters:
set_overlay_widget(widget, make_draggable=True) → None

Widget Overlay API

Parameters:
set_property_set_visible_by_name(identifier="Settings", visible) → None

Set the visibility of a Property Set that is paired with the given unique Identifier.

Parameters:
set_tool_panel_tool_header_widget(widget) → None

Set a UUserWidget to display at the head of the Scriptable Tool panel details view. Will only take effect when set during OnScriptSetup.

Parameters:

widget (UserWidget) – The UUserWidget to set.

property show_tool_in_editor: bool

[Read-Write] A generic flag to indicate whether this Tool should be shown in the UE Editor. This may be interpreted in different ways

Type:

(bool)

property tool_category: Text

[Read-Write] Category of this Tool, will be used in (eg) Tool Palette Section headers

Type:

(Text)

property tool_long_name: Text

[Read-Write] Long Name of this Tool, will be used in (eg) longer labels like the Accept/Cancel toolbar

Type:

(Text)

property tool_name: Text

[Read-Write] Name of this Tool, will be used in (eg) Toolbars

Type:

(Text)

property tool_shutdown_type: ScriptableToolShutdownType

[Read-Write] Specifies how the user exits this Tool, either Accept/Cancel-style or Complete-style

Type:

(ScriptableToolShutdownType)

property tool_startup_requirements: ScriptableToolStartupRequirements

[Read-Write]

Type:

(ScriptableToolStartupRequirements)

property tool_target_tool_builder_class: Class

[Read-Write]

Type:

(type(Class))

property tool_tooltip: Text

[Read-Write] Tooltip used for this Tool in (eg) icons/etc

Type:

(Text)

watch_bool_property(property_set, property_name, on_modified) → ScriptableInteractiveToolPropertySet

Watch a Bool-valued Property for changes

Parameters:
Return type:

ScriptableInteractiveToolPropertySet

watch_enum_property(property_set, property_name, on_modified) → ScriptableInteractiveToolPropertySet

Watch an Enum-valued Property for changes. Note that in this case the OnModified delegate will be called with a uint8 integer, which can be cast back to the original Enum type.

Parameters:
Return type:

ScriptableInteractiveToolPropertySet

watch_float_property(property_set, property_name, on_modified) → ScriptableInteractiveToolPropertySet

Watch a Float-valued Property for changes (double precision)

Parameters:
Return type:

ScriptableInteractiveToolPropertySet

watch_int_property(property_set, property_name, on_modified) → ScriptableInteractiveToolPropertySet

Watch an Integer-valued Property for changes

Parameters:
Return type:

ScriptableInteractiveToolPropertySet

watch_name_property(property_set, property_name, on_modified) → ScriptableInteractiveToolPropertySet

Watch an (F)Name-valued Property for changes

Parameters:
Return type:

ScriptableInteractiveToolPropertySet

watch_object_property(property_set, property_name, on_modified) → ScriptableInteractiveToolPropertySet

Watch an Object-valued Property for changes (ie UObject, UClass, etc)

Parameters:
Return type:

ScriptableInteractiveToolPropertySet

watch_property(property_set, property_name, on_modified) → ScriptableInteractiveToolPropertySet

Watch any Property in a PropertySet for changes. This function handles most basic properties, as well as Struct and Array properties, at some cost. The OnModified delegate cannot be passed the new property value, it must be fetched from the PropertySet.

Note also that in the case of Structs and Arrays, changes are currently detected by hashes, and there is always a small chance of hash collision.

Parameters:
Return type:

ScriptableInteractiveToolPropertySet

watch_string_property(property_set, property_name, on_modified) → ScriptableInteractiveToolPropertySet

Watch a String-valued Property for changes

Parameters:
Return type:

ScriptableInteractiveToolPropertySet