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

This struct should not be held on to past the duration of the callback.

Properties

action

The action that got triggered.

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

Action that got triggered.
See Also

canceled

Whether the action has just been canceled.

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

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

Control that triggered the action.
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

Difference between time and startTime.
Remarks

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

// 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

Interaction that triggered the callback.
Remarks
void FirePerformed(InputAction.CallbackContext context)
{
    // If SlowTap interaction was performed, perform a charged
    // firing. Otherwise, fire normally.
    if (context.interaction is SlowTapInteraction)
        FireChargedProjectile();
    else
        FireNormalProjectile();
}
See Also

performed

Whether the action has just been performed.

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

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.

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

Value relative to Time.realtimeSinceStartup when the action changed to started.
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

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

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

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).

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

Size of value returned when reading.
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).

See Also

valueType

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

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

Type of object returned when reading a value.
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. This allows reading values without having to know value types but also, unlike ReadValueAsObject(), without allocating GC heap memory.

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
// 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.

See Also

ReadValueAsObject()

Same as ReadValue<TValue>() except that it is not necessary to know the type of 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. Using it during normal gameplay will lead to frame-rate instabilities.

See Also

ReadValue<TValue>()

Read the value of the action.

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

The value read from 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.
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
See Also

See Also