Scripted Actions

Scripted Actions are Editor Utility Blueprints that you launch in the Unreal Editor by right-clicking Assets in the Content Browser, or by right-clicking Actors either in the Level Viewport (shown above) or in the World Outliner.

This kind of workflow is especially useful any time you need your Blueprint logic to have contextual awareness about a certain set of Assets or Actors. Typically, a Scripted Action gets the list of Assets or Actors that are selected at the time you run the action, then modifies those objects or otherwise takes them into consideration in its graph.

The instructions on this page show you how to create and launch these kinds of Editor Utility Blueprints, and how you can customize them to apply only to specific types of Assets or Actors.

Steps

In this procedure, we'll create a new Editor Utility Blueprint class from one of the parent classes that support Scripted Actions, and we'll set up a new event graph for that class that will show up as a Scripted Action.

1. In the Content Browser, right-click the folder where you want to create your new class, and choose Editor Utilities > Editor Utility Blueprint from the context menu.

   

2. Decide whether you want your Scripted Action to operate on Assets that you select in the Content Browser, or on Actors that you select in the Level Viewport or World Outliner.

   • If you want your Scripted Action to operate on Assets, choose AssetActionUtility as the parent class, then press Select.

   • If you want your Scripted Action to operate on Actors, choose ActorActionUtility as the parent class, then press Select.

   

3. Give your new class a descriptive name in the Content Browser.

   

   You won't see this class name when you run its Scripted Actions. You'll need it only to distinguish this class from the other Blueprint classes in your Project if you need to modify your Scripted Actions or add new ones later.

4. Double-click your new class to open it in the Blueprint Editor.

5. To create a Scripted Action for this class, you can either create a new function, or create a new Custom Event node in the Event Graph for the class.

   Make sure that the Call In Editor box is checked on the function entry node or the Custom Event node. This is automatically done for you when you create a new function, but you'll have to do it yourself if you choose to use a Custom Event.

   For example, this new function on an AssetActionUtility iterates through the list of Assets that are selected in the Content Browser, and prints the name of each one in the Level Viewport.

   The image below shows a similar function implemented on an ActorActionUtility.

   You'll find some useful Blueprint nodes for your Scripted Actions under the Development > Editor category, including the nodes shown in the examples above that return a list of the objects selected at the time your Scripted Action is run: Get Selected Assets, which returns an array of references to all the Assets selected in the Content Browser, and Get Selection Set, which returns an array of Actors that are currently selected in the Level.

   You also will want to install the Editor Scripting Utilities Plugin, if you haven't already, to get access to additional function libraries for working with Assets and Level Actors. See Scripting and Automating the Editor.

6. Save and Compile your Blueprint class.

End Result

Once your Blueprint class is saved and compiled, you should see a new Scripted Actions sub-menu in the context menu for either Assets or Actors, depending on the parent class you chose for your Blueprint class. This sub-menu contains each of the functions or Custom Events that you set up in your Blueprint class.

For example, when you right-click one or more Assets in the Content Browser:

Or when you right-click one or more Actors in the Level Viewport or World Outliner:

Each function and Custom Event that you set up on your AssetActionUtility or ActorActionUtility class becomes available as a separate option in the context menu. You can create as many different Scripted Actions as you need within a single Blueprint class, or you can create multiple Blueprint classes and distribute your Scripted Actions across those classes.

Restricting an Action to a Specific Class

Depending on the work you need your Scripted Actions to carry out, you may want them to appear in the context menu only for specific types of objects.

For example, say you create a Scripted Action that changes Materials on selected Actors. In this case, you might want that action to only appear when the user right-clicks on Static Mesh Actors, but not when the user right-clicks on Light Actors or Blueprints.

The AssetActionUtility and ActorAssetUtility base classes both offer a built-in function named GetSupportedClass. This function determines the class of objects that need to be selected in order for the Scripted Actions in your Blueprint class to appear in the context menu. Each time the user right-clicks on a set of Assets or Actors, this function is called to get the class type supported by the AssetActionUtility or ActorAssetUtility class. If it returns a class type, that return value is compared against the set of Assets or Actors that the user currently has selected. If at least one of those Assets or Actors has a class that matches the class returned by GetSupportedClass, then the Scripted Actions will appear in the context menu. By default, the GetSupportedClass function returns nothing. This makes all Scripted Actions appear regardless of the classes of Assets or Actors you have selected.

If you want to change this default behavior, you can override the GetSupportedClass function in your class to return a specific class type:

For example, this implementation within an ActorAssetUtility returns the StaticMeshActor class:

With this implementation, the Scripted Actions in this class will appear in the context menu when the user has at least one Static Mesh Actor selected at the time they open the context menu:

But the Scripted Actions do not appear when the user only has other kinds of Actors selected:

If you have multiple Assets or Actors selected, the behavior is permissive: as long as at least one of the selected items matches the class returned by GetSupportedClass, your Scripted Actions will appear in the context menu. Even if you override GetSupportedClass to restrict the classes handled by your actions, you're not guaranteed to only have instances of that class selected when the action gets run. Keep this in mind when you implement your Blueprint graphs.

Dynamic Inputs

You can set up your Scripted Actions to require information from the user who invokes them. If you add one or more Inputs to your function entry node or Custom Event node, you'll be prompted to supply that input each time you run the Scripted Action in the editor. This can be useful any time your script needs some extra information that may be different each time you call the action.

For example, this function has three inputs: a string, an Actor Object Reference, and a Material Object Reference:

When you run the Scripted Action for this function, the editor pops up a small window for you to set these input values:

The editor validates that each input matches the type of value it is supposed to be. However, it doesn't guarantee that the inputs will have values at all, or that those values will make sense in any particular context. Keep in mind that your script should handle unspecified input values and validate the input values the user does provide.