Struct InputAction.CallbackContext

Information provided to action callbacks about what triggered an action.

Inherited Members
Namespace: UnityEngine.InputSystem
Assembly: Unity.InputSystem.dll
Syntax
public struct InputAction.CallbackContext
Remarks

The callback context represents the current state of an action associated with the callback and provides information associated with the bound control, its value, and its phase.

The callback context provides you with a way to consume events (push-based input) as part of an update when using input action callback notifications. For example, started, performed, canceled rather than relying on pull-based reading. Also see Responding To Actions for additional information on differences between callbacks and polling.

Use this struct to read the current input value through any of the read-method overloads: ReadValue<TValue>(), ReadValueAsButton(), ReadValueAsObject() or ReadValue(void*, int) (unsafe). If you don't know the expected value type, you might need to check valueType before reading the value.

Use the phase property to get the current phase of the associated action or evaluate it directly using any of the convenience methods started, performed, canceled.

To obtain information about the current timestamp of the associated event, or to check when the event started, use time or startTime respectively.

You should not use or keep this struct outside of the callback.

Examples
using UnityEngine;
using UnityEngine.InputSystem;
using UnityEngine.InputSystem.Interactions;

public class MyController : MonoBehaviour
 {
     [SerializeField] InputActionReference move;
     [SerializeField] InputActionReference fire;

     void Awake()
     {
         /// Receive notifications when move or fire actions are performed
         move.action.performed += MovePerformed;
         fire.action.performed += FirePerformed;
     }

     void OnEnable()
     {
         /// Enable actions as part of enabling this behavior.
         move.action.Enable();
         fire.action.Enable();
     }

     void OnDisable()
     {
         /// Disable actions as part of disabling this behavior.
         move.action.Disable();
         fire.action.Disable();
     }

     void MovePerformed(InputAction.CallbackContext context)
     {
         /// Read the current 2D vector value reported by the associated input action.
         var direction = context.ReadValue<Vector2>();
         Debug.Log("Move: " + direction * Time.deltaTime);
     }

     void FirePerformed(InputAction.CallbackContext context)
     {
         /// If underlying interaction is a slow-tap fire charged projectile, otherwise fire regular
         /// projectile.
         if (context.interaction is SlowTapInteraction)
             Debug.Log("Fire charged projectile");
         else
             Debug.Log("Fire projectile");
     }
 }

Properties

action

The associated action that triggered the callback.

Declaration
public InputAction action { get; }
Property Value
Type Description
InputAction
See Also

canceled

Whether the action has just been canceled.

Declaration
public bool canceled { get; }
Property Value
Type Description
bool
Remarks

If true, the action was just canceled.

See Also

control

The control that triggered the action.

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

In case of a composite binding, this is the control of the composite that activated the composite as a whole. For example, in case of a WASD-style binding, it could be the W key.

Note that an action may also change its phase in response to a timeout. For example, a TapInteraction will cancel itself if the button control is not released within a certain time. When this happens, the control property will be the control that last fed input into the action.

See Also

duration

Time difference between time and startTime.

Declaration
public double duration { get; }
Property Value
Type Description
double
Remarks

This property can be used, for example, to determine how long a button was held down.

Examples
// Let's create a button action bound to the A button
// on the gamepad.
var action = new InputAction(
    type: InputActionType.Button,
    binding: "<Gamepad>/buttonSouth");

// When the action is performed (which will happen when the
// button is pressed and then released) we take the duration
// of the press to determine how many projectiles to spawn.
action.performed +=
    context =>
    {
        const float kSpawnRate = 3; // 3 projectiles per second
        var projectileCount = kSpawnRate * context.duration;
        for (var i = 0; i < projectileCount; ++i)
        {
            var projectile = UnityEngine.Object.Instantiate(projectile);
            // Apply other changes to the projectile...
        }
    };
See Also

interaction

The interaction that triggered the action or null if the binding that triggered does not have any particular interaction set on it.

Declaration
public IInputInteraction interaction { get; }
Property Value
Type Description
IInputInteraction
Remarks
using UnityEngine;
using UnityEngine.InputSystem;
using UnityEngine.InputSystem.Interactions;
class Example : MonoBehaviour
{
public InputActionReference fire;
public void Awake()
{
    fire.action.performed += FirePerformed;
}

void OnEnable() => fire.action.Enable();
void OnDisable() => fire.action.Disable();

void FirePerformed(InputAction.CallbackContext context)
{
     /// If SlowTap interaction was performed, perform a charged
     /// firing. Otherwise, fire normally.
     if (context.interaction is SlowTapInteraction)
         Debug.Log("Fire charged projectile");
     else
         Debug.Log("Fire projectile");
}

}
See Also

performed

Whether the action has just been performed.

Declaration
public bool performed { get; }
Property Value
Type Description
bool
Remarks

If true, the action was just performed.

See Also

phase

Current phase of the action. Equivalent to accessing phase on action.

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

Current phase of the action.
See Also

startTime

Time at which the action was started with relation to Time.realtimeSinceStartup.

Declaration
public double startTime { get; }
Property Value
Type Description
double
Remarks

This is only relevant for actions that go through distinct a Started cycle as driven by interactions.

The value of this property is that of time when started was called. See the time property for how the timestamp works.

See Also

started

Whether the action has just been started.

Declaration
public bool started { get; }
Property Value
Type Description
bool
Remarks

If true, the action was just started.

See Also

time

The time at which the action got triggered.

Declaration
public double time { get; }
Property Value
Type Description
double
Remarks

Time is relative to realtimeSinceStartup at which the action got triggered.

This is usually determined by the timestamp of the input event that activated a control bound to the action. What this means is that this is normally not the value of Time.realtimeSinceStartup when the input system calls the callback but rather the time at which the input was generated that triggered the action.

See Also

valueSizeInBytes

Size of values returned by ReadValue(void*, int) in bytes.

Declaration
public int valueSizeInBytes { get; }
Property Value
Type Description
int
Remarks

All input values passed around by the system are required to be "blittable", i.e. they cannot contain references, cannot be heap objects themselves, and must be trivially mem-copyable. This means that any value can be read out and retained in a raw byte buffer.

The value of this property determines how many bytes will be written by ReadValue(void*, int).

This property indirectly maps to the value of valueSizeInBytes or valueSizeInBytes.

See Also

valueType

Type of value returned by ReadValueAsObject() and expected by ReadValue<TValue>().

Declaration
public Type valueType { get; }
Property Value
Type Description
Type
Remarks

The type of value returned by an action is usually determined by the InputControl that triggered the action, i.e. by the control referenced from control. However, if the binding that triggered is a composite, then the composite will determine values and not the individual control that triggered (that one just feeds values into the composite).

See Also

Methods

ReadValue(void*, int)

Read the value of the action as a raw byte buffer.

Declaration
public void ReadValue(void* buffer, int bufferSize)
Parameters
Type Name Description
void* buffer

Memory buffer to read the value into.
int bufferSize

Size of buffer allocated at buffer. Must be at least valueSizeInBytes.
Remarks

This allows reading values without having to know value types but also, unlike ReadValueAsObject(), without allocating GC heap memory.

Examples
// Read a Vector2 using the raw memory ReadValue API.
// Here we just read into a local variable which we could
// just as well (and more easily) do using ReadValue<Vector2>.
// Still, it serves as a demonstration for how the API
// operates in general.
unsafe
{
    var value = default(Vector2);
    var valuePtr = UnsafeUtility.AddressOf(ref value);
    context.ReadValue(buffer, UnsafeUtility.SizeOf<Vector2>());
}
Exceptions
Type Condition
ArgumentNullException

buffer is null.
ArgumentException

bufferSize is too small.
See Also
ReadValue<TValue>()

ReadValueAsButton()

Read the current value of the action as a float and return true if it is equal to or greater than the button press threshold.

Declaration
public bool ReadValueAsButton()
Returns
Type Description
bool

True if the action is considered in "pressed" state, false otherwise.
Remarks

If the currently active control is a ButtonControl, the pressPoint of the button will be taken into account (if set). If there is no custom button press point, the global defaultButtonPressPoint will be used.

Examples
using UnityEngine;
using UnityEngine.InputSystem;

public class Example : MonoBehaviour
{
    public InputActionReference fire;

    void Awake()
    {
        if (fire.action != null)
        {
            fire.action.performed += context =>
            {
                // ReadValueAsButton attempts to interpret the value as a button.
                Debug.Log($"Is firing: {context.ReadValueAsButton()}");
            };
        }
    }

    void OnEnable()
    {
        fire.action.Enable();
    }

    void OnDisable()
    {
        fire.action.Disable();
    }
}
See Also

ReadValueAsObject()

Same as ReadValue<TValue>() except that it is not necessary to know the type of the value at compile time.

Declaration
public object ReadValueAsObject()
Returns
Type Description
object

The current value from the binding that triggered the action or null if the action is not currently in progress.
Remarks

This method allocates GC heap memory due to boxing. Using it during normal gameplay will lead to frame-rate instabilities.

Examples
using UnityEngine;
using UnityEngine.InputSystem;

public class Example : MonoBehaviour
{
    public InputActionReference move;

    void Awake()
    {
        if (move.action != null)
        {
            move.action.performed += context =>
            {
                // ReadValueAsObject allows reading the associated value as a boxed reference type.
                object obj = context.ReadValueAsObject();
                if (obj is Vector2)
                    Debug.Log($"Current value is Vector2 type: {obj}");
                else
                    Debug.Log($"Current value is of another type: {context.valueType}");
            };
        }
    }

    void OnEnable()
    {
        move.action.Enable();
    }

    void OnDisable()
    {
        move.action.Disable();
    }
}
See Also

ReadValue<TValue>()

Read the current value of the associated action.

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

The current value of type TValue associated with the action.
Type Parameters
Name Description
TValue

Type of value to read. This must correspond to the expected by either control or, if it is a composite, by the InputBindingComposite in use.
Remarks

The following example shows how to read the current value of a specific type:

Examples
using UnityEngine;
using UnityEngine.InputSystem;

public class Example : MonoBehaviour
{
    public InputActionReference move;

    void Awake()
    {
        if (move.action != null)
        {
            move.action.performed += context =>
            {
                // Note: Assumes the underlying value type is Vector2.
                Debug.Log($"Value is: {context.ReadValue<Vector2>()}");
            };
        }
    }

    void OnEnable()
    {
        move.action.Enable();
    }

    void OnDisable()
    {
        move.action.Disable();
    }
}
Exceptions
Type Condition
InvalidOperationException

The given type TValue does not match the value type expected by the control or binding composite.
See Also
ReadValue<TValue>()

ToString()

Return a string representation of the context useful for debugging.

Declaration
public override string ToString()
Returns
Type Description
string

String representation of the context.
Overrides
Remarks

The following example illustrates how to log callback context to console when a callback is received for debugging purposes:

Examples
using UnityEngine;
using UnityEngine.InputSystem;

public class Example : MonoBehaviour
{
    public InputActionReference move;

    void Awake()
    {
        if (move.action != null)
        {
            move.action.performed += context =>
            {
                // Outputs the associated callback context in its textual representation which may
                // be useful for debugging purposes.
                Debug.Log(context.ToString());
            };
        }
    }

    void OnEnable() => move.action.Enable();
    void OnDisable() => move.action.Disable();
}
See Also

See Also

Did you find this page useful? Please give it a rating: