Actions

A class is associated with each tool action. You can instantiate this class to run a process on a data stream.

Actions are the base foundation of the Toolbox and the Rule Engine. Each Action corresponds to an entry in the Toolbox and/or the Rule Engine.

Each action defines an input type and an output type:

Class Description
ActionOut<OutputType> Use this class to create a start point, that is, to return results without input.
ActionIn<InputType> Use this class to create an end point, that is, to prompt input without returning results.
ActionInOut<InputType, OutputType> Use this class to create an action to prompt input, and then return results.
This type of action is the most commonly used.

The OutputType Run(InputType) defines the Action execution steps.

Asset Transformer Actions

Asset Transformer Actions inherit from PixyzAction which itself inherit from ActionInOut<IList<GameObject>, IList<GameObject>>. They are special actions for processing GameObjects directly inside Asset Transformer framework.

Any Asset Transformer API function, except IO ones (forbidden by EULA), can be called from the OccurrenceList Run(OccurrenceList) method. Input GameObjects are automatically converted to Asset Transformer occurrences before running this function, and input GameObjects are updated after.

Custom Actions

Asset Transformer provides a set of default Toolbox/Rule Engine Actions but you can create and define your own actions which will be available in the Asset Transformer Toolkit UI along the default ones. These actions are called Custom Actions.

Toolbox Actions must inherit from ActionInOut<IList<GameObject>, IList<GameObject>> or PixyzAction.

Input and output types must correspond in order to link actions in the Rule Engine. For example, an action inheriting from ActionOut<IList<GameObject>> cannot be chained with an action inherting from ActionInOut<IList<Texture2D>, IList<GameObject>> but can be chained with an action inheriting from ActionInOut<IList<GameObject>, IList<Texture2D>>.

Note

Default Actions sources are available! Go check them in the com.unity.industry.toolkit/Editor/Actions folder. It is very practical if you want to create a slight variation for an existing Action.

Create a Custom Action

To create a new custom action from a script template, right-click in your Assets and use one of these alternatives depending on whether you want to leverage Asset Transformer API or not:

  • Create > Asset Transformer > C# Custom Action
  • Create > Asset Transformer > C# Custom Asset Transformer Action
Warning

Script names must match class names.

Warning

Scripts must be placed in an Editor folder.

Add parameters

To add parameters, add fields and mark them with the UserParameter attribute.

A parameter can be of these types:

  • class
  • struct
  • list
  • enum
  • A base type, such as string or int

For each parameter, the Toolbox or Rule Engine displays the proper input.

Add helper methods

Helper methods are parameterless methods that you can run through the Rule Engine.

To create a helper method, mark your method with the HelperMethod attribute.

To use helper methods, select the More button (…) in the Action section of the Rule Engine.

Display messages

You can display error messages, warning messages, and information messages.

You can override methods, such as the GetErrors() method, for various purposes. For example, you might want to implement a parameter checking method to display an error message when a user enters an incorrect value.

The NativeProgress class

When creating a new C# Custom Asset Transformer Action, the default template uses an instance of NativeProgress with a using statement to report progress of the current action. It can be useful to wrap all Asset Transformer SDK API calls in a custom actions to have a visual representation of their progress in the Background Tasks window.

Create a customized UI

Sometimes it can be useful to create widgets with more advanced functionality, e.g. when the modification of one parameter has an impact on other parameters. To handle this case, we provide an interface ICustomWidget, which can be used to personalize action parameter widgets. Let's imagine a custom parameter that is a class composed of multiple values:

public class NewCustomAction : ActionInOut<IList<GameObject>, IList<GameObject>> 
{
    public class MyCustomParameter
    {
        public bool myBool;
        public int myInt;
        public MyCustomParameter() { }
    }

    [UserParameter]
    public MyCustomParameter aCustomParameter = new MyCustomParameter();

    ...
}

Then you can create a customized widget for that parameter by creating a new class that inherits from ICustomWidget and has the CustomWidget attribute:

[CustomWidget(typeof(NewCustomAction.MyCustomParameter))]
public class MyCustomParameterWidget : ICustomWidget
{
    IntegerField intField;

    public VisualElement GetVisualElement(object obj)
    {
        if (obj is not NewCustomAction.MyCustomParameter customParameter)
            throw new Exception("Passed object is not of type MyCustomParameter");

        VisualElement container = new VisualElement();
        container.Add(new Label("My Custom Parameter Widget"));
        Toggle toggle = new Toggle("MyBool")
        {
            value = customParameter.myBool
        };
        toggle.RegisterValueChangedCallback(evt =>
        {
            customParameter.myBool = evt.newValue;
        });
        container.Add(toggle);

        VisualElement intContainer = new VisualElement();
        intContainer.style.flexDirection = FlexDirection.Row;
        intField = new IntegerField("MyInt: ");
        intField.value = customParameter.myInt;
        intField.RegisterValueChangedCallback(evt =>
        {
            customParameter.myInt = evt.newValue;
        });
        intContainer.Add(intField);

        // interaction between widgets
        Button button = new Button(() =>
        {
            customParameter.myInt++;
            intField.value = customParameter.myInt;
        })
        {
            text = "Increment MyInt"
        };
        intContainer.Add(button);
        container.Add(intContainer);
        return container;
    }
}

Results in the following widget, here inside the Rule Engine:

Personalized parameter widgets can also be used in combination with the automatically generated widgets from the previous sections. For example, we could add other parameters to the action that carry the UserParameter attribute.

Warning

Make sure that parameter class (here: MyCustomParameter) variables are public and do not use autogenerated getters/setters in it. That might cause problems with our serialization system during metadata readout.

Gizmos (Toolbox)

You can override the ActionBase.OnEnable and ActionBase.OnDisable methods to register or unregister from SceneView.duringSceneGui events, allowing you to draw gizmos in the Scene view:

public override void OnEnable()
{
    SceneView.duringSceneGui += OnSceneGUI;
}

public override void OnDisable()
{
    SceneView.duringSceneGui -= OnSceneGUI;
}

void OnSceneGUI(SceneView view) 
{
    Handles.DrawWireCube(Vector3.zero, Vector3.one);
}

This approach can be useful for visualizing or interacting with Action input parameters directly within the Scene view.