Struct InputInteractionContext

Information passed to interactions when their associated controls trigger.

Inherited Members
Namespace: UnityEngine.InputSystem
Assembly: Unity.InputSystem.dll
Syntax
public struct InputInteractionContext

Properties

action

The action associated with the binding.

Declaration
public 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 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 bool isStarted { get; }
Property Value
Type Description
bool
See Also

isWaiting

True if the interaction is waiting for input

Declaration
public bool isWaiting { get; }
Property Value
Type Description
bool
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 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 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 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(float) has expired.

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

Methods

Canceled()

Marks the interaction as being interrupted or aborted. This is relevant to signal that the interaction pattern was not completed, for example, the user pressed and then released a button before the minimum time required for a HoldInteraction to complete.

Declaration
public void Canceled()
Remarks

This is used by most existing interactions to cancel the transitions in the interaction state machine when a condition required to proceed turned false or other indirect requirements were not met, such as time-based conditions.

See Also

ComputeMagnitude()

Compute the current level of control actuation.

Declaration
public float ComputeMagnitude()
Returns
Type Description
float

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(float)

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

Declaration
public bool ControlIsActuated(float threshold = 0)
Parameters
Type Name Description
float 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
bool

True if the trigger control is actuated.
See Also

Performed()

Marks the interaction as being performed and then transitions back to Waiting to wait for input. This behavior is desirable for interaction events that are instant and reflect a transitional interaction pattern such as PressInteraction or TapInteraction.

Declaration
public void Performed()
Remarks

Note that this affects the current interaction only. There might be multiple interactions on a binding and arbitrary many interactions might 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.

See Also

PerformedAndStayPerformed()

Marks the interaction as being performed and then stays in that state waiting for an input to cancel the interactions active state. This behavior is desirable for interaction events that are active for a duration until a cancellation condition is true, such as HoldInteraction or TapInteraction where releasing the associated button cancels the interaction..

Declaration
public void PerformedAndStayPerformed()
See Also

PerformedAndStayStarted()

Marks the interaction as being performed and then transitions into I Started to wait for an initial trigger condition to be true before being performed again. This behavior may be desirable for interaction events that reflect transitional interaction patterns but should be considered as started until a cancellation condition is true, such as releasing a button.

Declaration
public void PerformedAndStayStarted()
See Also

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.
See Also

SetTimeout(float)

Start a timeout that triggers within seconds.

Declaration
public void SetTimeout(float seconds)
Parameters
Type Name Description
float 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(float)

Override the default timeout value used by GetTimeoutCompletionPercentage().

Declaration
public void SetTotalTimeoutCompletionTime(float seconds)
Parameters
Type Name Description
float 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

This affects the current interaction only. There might be multiple interactions on a binding and arbitrary many interactions might 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.
}



}
See Also

Waiting()

Put the interaction back into Waiting state.

Declaration
public void Waiting()
See Also

See Also