You can try out this Experimental feature, but we do not recommend shipping projects with it.
This feature is Experimental.
Features are sometimes made available in an Experimental state so you can try them out, provide feedback, and see what we are planning. We do not recommend shipping projects with Experimental features. Please keep in mind that we do not guarantee backward compatibility for assets created at the experimental stage, the APIs for these features are subject to change, and we may remove entire Experimental features or specific functionality at our discretion.

Scripted Actions

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

This kind of workflow is especially useful any time you need your Blueprint utility 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 Blueprint utilities, and how you can customize them to apply only to specific types of Assets or Actors.

Prerequisite: You must have enabled the experimental Blutility feature, as described under Blueprint Utilities (Blutilities).

Steps

In this procedure, we'll create a new 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 Blueprint utility class, and choose Blueprints > Blutility from the contextual menu.
    Create Blutility
  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.
    Choose ActorActionUtility or AssetActionUtility
  3. Give your new class a descriptive name in the Content Browser.
    Name your new class
    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. Right-click your new class, and choose Edit Blueprint from the contextual menu.
    Edit Blueprint
  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 EventGraph 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 simply 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.
  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 contextual 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:

Run a Scripted Action on selected Assets

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

Run a Scripted Action on selected Actors

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

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

Override GetSupportedClass

For example, this implementation within an ActorAssetUtility returns the StaticMeshActor class, so the Scripted Actions in this class will appear in the contextual menu when the user has at least one Static Mesh Actor selected at the time they open the contextual menu:

Scripted Actions appear for the supported class

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

Scripted Actions do not appear for other classes

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

Unlike other kinds of Editor Blueprint utilities, Scripted Actions can have inputs. 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:

A function with inputs

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

Set 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.