Interface IInputInteraction

Interface for interaction patterns that drive actions.

Namespace: UnityEngine.InputSystem
Syntax
[Preserve]
public interface IInputInteraction
Remarks

Actions have a built-in interaction pattern that to some extent depends on their type (InputActionType, type). What this means is that when controls bound to an action are actuated, the action will initiate an interaction that in turn determines when started, performed, and canceled are called.

The default interaction (i.e. when no interaction has been added to a binding or the action that the binding targets) will generally start and perform an action as soon as a control is actuated, then perform the action whenever the value of the control changes except if the value changes back to the default in which case the action is cancelled.

By writing custom interactions, it is possible to implement different interactions. For example, HoldInteraction will only start when a control is being actuated but will only perform the action if the control is held for a minimum amount of time.

Interactions can be stateful and mutate state over time. In fact, interactions will usually represent miniature state machines driven directly by input.

Multiple interactions can be applied to the same binding. The interactions will be processed in sequence. However, the first interaction that starts the action will get to drive the state of the action. If it performs the action, all interactions are reset. If it cancels, the first interaction in the list that is in started state will get to take over and drive the action.

This makes it possible to have several interaction patterns on the same action. For example, to have a "fire" action that allows for charging, one can have a "Hold" and a "Press" interaction in sequence on the action.

// Create a fire action with two interactions:
// 1. Hold. Triggers charged firing. Has to come first as otherwise "Press" will immediately perform the action.
// 2. Press. Triggers instant firing.
// NOTE: An alternative is to use "Tap;Hold", i.e. a "Tap" first and then a "Hold". The difference
//       is relatively minor. In this setup, the "Tap" turns into a "Hold" if the button is held for
//       longer than the tap time whereas in the setup below, the "Hold" turns into a "Press" if the
//       button is released before the hold time has been reached.
var fireAction = new InputAction(type: InputActionType.Button, interactions: "Hold;Press");
fireAction.AddBinding("<Gamepad>/buttonSouth");

Custom interactions can be registered using RegisterInteraction(Type, String). This can be done at any point during or after startup but has to be done before actions that reference the interaction are enabled or have their controls queried. A good point is usually to do it during loading like so:

#if UNITY_EDITOR
[InitializeOnLoad]
#endif
public class MyInteraction : IInputInteraction
{
    public void Process(ref InputInteractionContext context)
    {
        // ...
    }

    public void Reset()
    {
    }

    static MyInteraction()
    {
        InputSystem.RegisterInteraction<MyInteraction>();
    }

    [RuntimeInitializeOnLoad]
    private static void Initialize()
    {
        // Will execute the static constructor as a side effect.
    }
}

If your interaction will only work with a specific type of value (e.g. float), it is better to base the implementation on IInputInteraction<TValue> instead. While the interface is the same, the type parameter communicates to the input system that only controls that have compatible value types should be used with your interaction.

Interactions, like processors (InputProcessor) and binding composites (InputBindingComposite) may define their own parameters which can then be configured through the editor UI or set programmatically in code. To define a parameter, add a public field to your class that has either a bool, an int, a float, or an enum type. To set defaults for the parameters, assign default values to the fields.

public class MyInteraction : IInputInteraction
{
    public bool boolParameter;
    public int intParameter;
    public float floatParameter;
    public MyEnum enumParameter = MyEnum.C; // Custom default.

    public enum MyEnum
    {
        A,
        B,
        C
    }

    public void Process(ref InputInteractionContext context)
    {
        // ...
    }

    public void Reset()
    {
    }
}

// The parameters can be configured graphically in the editor or set programmatically in code.
// NOTE: Enum parameters are represented by their integer values. However, when setting enum parameters
//       graphically in the UI, they will be presented as a dropdown using the available enum values.
var action = new InputAction(interactions: "MyInteraction(boolParameter=true,intParameter=1,floatParameter=1.2,enumParameter=1);

A default UI will be presented in the editor UI to configure the parameters of your interaction. You can customize this by replacing the default UI with a custom implementation using InputParameterEditor. This mechanism is the same as for processors and binding composites.

#if UNITY_EDITOR
public class MyCustomInteractionEditor : InputParameterEditor<MyCustomInteraction>
{
    protected override void OnEnable()
    {
        // Do any setup work you need.
    }

    protected override void OnGUI()
    {
        // Use standard Unity UI calls do create your own parameter editor UI.
    }
}
#endif

Methods

Process(ref InputInteractionContext)

Perform processing of the interaction in response to input.

Declaration
void Process(ref InputInteractionContext context)
Parameters
Type Name Description
InputInteractionContext context
Remarks

This method is called whenever a control referenced in the binding that the interaction sits on changes value. The interaction is expected to process the value change and, if applicable, call Started() and/or its related methods to initiate a state change.

Note that if "control disambiguation" (i.e. the process where if multiple controls are bound to the same action, the system decides which control gets to drive the action at any one point) is in effect -- i.e. when either Button or Value are used but not if PassThrough is used -- inputs that the disambiguation chooses to ignore will cause this method to not be called.

Note that this method is called on the interaction even when there are multiple interactions and the interaction is not the one currently in control of the action (because another interaction that comes before it in the list had already started the action). Each interaction will get processed independently and the action will decide when to use which interaction to drive the action as a whole.

    // Processing for an interaction that will perform the action only if a control
    // is held at least at 3/4 actuation for at least 1 second.
    public void Process(ref InputInteractionContext context)
    {
        var control = context.control;

        // See if we're currently tracking a control.
        if (m_Control != null)
        {
            // Ignore any input on a control we're not currently tracking.
            if (m_Control != control)
                return;

            // Check if the control is currently actuated past our 3/4 threshold.
            var isStillActuated = context.ControlIsActuated(0.75f);

            // See for how long the control has been held.
            var actuationTime = context.time - context.startTime;

            if (!isStillActuated)
            {
                // Control is no longer actuated above 3/4 threshold. If it was held
                // for at least a second, perform the action. Otherwise cancel it.

                if (actuationTime >= 1)
                    context.Performed();
                else
                    context.Cancelled();
            }

            // Control changed value somewhere above 3/4 of its actuation. Doesn't
            // matter to us so no change.
        }
        else
        {
            // We're not already tracking a control. See if the control that just triggered
            // is actuated at least 3/4th of its way. If so, start tracking it.

            var isActuated = context.ControlIsActuated(0.75f);
            if (isActuated)
            {
                m_Control = context.control;
                context.Started();
            }
        }
    }

    InputControl m_Control;

    public void Reset()
    {
        m_Control = null;
    }

Reset()

Reset state that the interaction may hold. This should put the interaction back in its original state equivalent to no input yet having been received.

Declaration
void Reset()

See Also