Struct InputInteractionContext

Information passed to IInputInteraction when their associated controls trigger.

Inherited Members
Namespace: UnityEngine.InputSystem
Syntax
public struct InputInteractionContext

Properties

action

The action associated with the binding.

Declaration
public readonly InputAction action { get; }
Property Value
Type Description
InputAction
Remarks

If the binding is not associated with an action, this is null.

See Also

control

The bound control that changed its state to trigger the binding associated with the interaction.

Declaration
public readonly InputControl control { get; }
Property Value
Type Description
InputControl
Remarks

In case the binding associated with the interaction is a composite, this is one of the controls that are part of the composite.

See Also

isStarted

True if the interaction has been started.

Declaration
public readonly bool isStarted { get; }
Property Value
Type Description
Boolean
See Also

isWaiting

True if the interaction is waiting for input

Declaration
public readonly bool isWaiting { get; }
Property Value
Type Description
Boolean
Remarks

By default, an interaction will return this this phase after every time it has been performed (Performed). This can be changed by using PerformedAndStayStarted() or PerformedAndStayPerformed().

See Also

phase

The phase the interaction is currently in.

Declaration
public readonly InputActionPhase phase { get; }
Property Value
Type Description
InputActionPhase
Remarks

Each interaction on a binding has its own phase independent of the action the binding is applied to. If an interaction gets to "drive" an action at a particular point in time, its phase will determine the phase of the action.

See Also

startTime

Timestamp of the InputEvent that caused the interaction to transition to Started.

Declaration
public readonly double startTime { get; }
Property Value
Type Description
Double
See Also

time

Time stamp of the input event that caused control to trigger a change in the state of action.

Declaration
public readonly double time { get; }
Property Value
Type Description
Double
See Also

timerHasExpired

Whether the interaction's Process(ref InputInteractionContext) method has been called because a timer set by SetTimeout(Single) has expired.

Declaration
public bool timerHasExpired { get; }
Property Value
Type Description
Boolean
See Also

Methods

Canceled()

Declaration
public void Canceled()

ComputeMagnitude()

Compute the current level of control actuation.

Declaration
public float ComputeMagnitude()
Returns
Type Description
Single

The current level of control actuation (usually [0..1]) or -1 if the control is actuated but does not support computing magnitudes.
See Also

ControlIsActuated(Single)

Return true if the control that triggered the interaction has been actuated beyond the given threshold.

Declaration
public bool ControlIsActuated(float threshold = 0F)
Parameters
Type Name Description
Single threshold

Threshold that must be reached for the control to be considered actuated. If this is zero, the threshold must be exceeded. If it is any positive value, the value must be at least matched.
Returns
Type Description
Boolean

True if the trigger control is actuated.
See Also

Performed()

Declaration
public void Performed()

PerformedAndStayPerformed()

Declaration
public void PerformedAndStayPerformed()

PerformedAndStayStarted()

Declaration
public void PerformedAndStayStarted()

ReadValue<TValue>()

Read the value of the binding that triggered processing of the interaction.

Declaration
public TValue ReadValue<TValue>()
    where TValue : struct
Returns
Type Description
TValue

Value read from the binding.
Type Parameters
Name Description
TValue

Type of value to read from the binding. Must match the value type of the control or composite in effect for the binding.

SetTimeout(Single)

Start a timeout that triggers within seconds.

Declaration
public void SetTimeout(float seconds)
Parameters
Type Name Description
Single seconds

Number of seconds before the timeout is triggered.
Remarks

An interaction might wait a set amount of time for something to happen and then do something depending on whether it did or did not happen. By calling this method, a timeout is installed such that in the input update that the timer expires in, the interaction's Process(ref InputInteractionContext) method is called with timerHasExpired being true.

Changing the phase of the interaction while a timeout is running will implicitly cancel the timeout.

// Let's say we're writing a Process() method for an interaction that,
// after a control has been actuated, waits for 1 second for it to be
// released again. If that happens, the interaction performs. If not,
// it cancels.
public void Process(ref InputInteractionContext context)
{
    // timerHasExpired will be true if we get called when our timeout
    // has expired.
    if (context.timerHasExpired)
    {
        // The user did not release the control quickly enough.
        // Our interaction is not successful, so cancel.
        context.Canceled();
        return;
    }

    if (context.ControlIsActuated())
    {
        if (!context.isStarted)
        {
            // The control has been actuated. We want to give the user a max
            // of 1 second to release it. So we start the interaction now and then
            // set the timeout.
            context.Started();
            context.SetTimeout(1);
        }
    }
    else
    {
        // Control has been released. If we're currently waiting for a release,
        // it has come in time before out timeout expired. In other words, the
        // interaction has been successfully performed. We call Performed()
        // which implicitly removes our ongoing timeout.
        if (context.isStarted)
            context.Performed();
    }
}
See Also

SetTotalTimeoutCompletionTime(Single)

Override the default timeout value used by GetTimeoutCompletionPercentage().

Declaration
public void SetTotalTimeoutCompletionTime(float seconds)
Parameters
Type Name Description
Single seconds

Amount of total successive timeouts TODO
Remarks

By default, timeout completion will be entirely determine by the timeout that is currently running, if any. However, some interactions (such as MultiTapInteraction) will have to run multiple timeouts in succession. Thus, completion of a single timeout is not the same as completion of the interaction.

You can use this method to account for this.

Whenever a timeout completes, the timeout duration will automatically be accumulated towards the total timeout completion time.

// Let's say we're starting our first timeout and we know that we will run three timeouts
// in succession of 2 seconds each. By calling SetTotalTimeoutCompletionTime(), we can account for this.
SetTotalTimeoutCompletionTime(3 * 2);

// Start the first timeout. When this timeout expires, it will automatically
// count one second towards the total timeout completion time.
SetTimeout(2);
Exceptions
Type Condition
ArgumentException
See Also

Started()

Mark the interaction has having begun.

Declaration
public void Started()
Remarks

Note that this affects the current interaction only. There may be multiple interactions on a binding and arbitrary many interactions may concurrently be in started state. However, only one interaction (usually the one that starts first) is allowed to drive the action's state as a whole. If an interaction that is currently driving an action is canceled, however, the next interaction in the list that has been started will take over and continue driving the action.

public class MyInteraction : IInputInteraction<float>
{
    public void Process(ref IInputInteractionContext context)
    {
        if (context.isWaiting && context.ControlIsActuated())
        {
            // We've waited for input and got it. Start the interaction.
            context.Started();
        }
        else if (context.isStarted && !context.ControlIsActuated())
        {
            // Interaction has been completed.
            context.Performed();
        }
    }

    public void Reset()
    {
        // No reset code needed. We're not keeping any state locally in the interaction.
    }
}

Waiting()

Put the interaction back into Waiting state.

Declaration
public void Waiting()
See Also

See Also