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] Relative Path to a custom Icon Image for this Tool. The Image file format must be png or svg.

    The Image file must reside in the same Content folder hierarchy as contains the Tool Class (ie Blueprint asset), i.e. either the Project Content folder or a Plugin Content folder.

    So for example if the Tool BP is in a plugin named MyCustomTools, the icon must be in

    MyProject/Plugins/MyCustomTools/Content/<SubFolders>/MyToolIcon.png,

    and the relative path to use here would be <SubFolders>/MyToolIcon.png

  • 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_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_tooltip (Text): [Read-Write] Tooltip used for this Tool in (eg) icons/etc

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_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

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] Relative Path to a custom Icon Image for this Tool. The Image file format must be png or svg.

The Image file must reside in the same Content folder hierarchy as contains the Tool Class (ie Blueprint asset), i.e. either the Project Content folder or a Plugin Content folder.

So for example if the Tool BP is in a plugin named MyCustomTools, the icon must be in

MyProject/Plugins/MyCustomTools/Content/<SubFolders>/MyToolIcon.png,

and the relative path to use here would be <SubFolders>/MyToolIcon.png

Type:

(str)

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_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_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_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:

  • identifier (str) –

  • visible (bool) –

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:

  • identifier (str) –

  • visible (bool) –

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_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