Struct InputAction.CallbackContext
Information provided to action callbacks about what triggered an action.
Namespace: UnityEngine.InputSystem
Syntax
public struct 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. |
canceled
Whether the action has just been canceled.
Declaration
public bool canceled { get; }
Property Value
Type | Description |
---|---|
Boolean | 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
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.
// 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...
}
};
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 |
---|---|
Boolean | If true, the action was just performed. |
See Also
phase
Declaration
public InputActionPhase phase { get; }
Property Value
Type | Description |
---|---|
InputActionPhase | Current phase of the action. |
See Also
started
Whether the action has just been started.
Declaration
public bool started { get; }
Property Value
Type | Description |
---|---|
Boolean | If true, the action was just started. |
See Also
startTime
Time at which the action was started.
Declaration
public double startTime { get; }
Property Value
Type | Description |
---|---|
Double | Value relative to |
Remarks
This is only relevant for actions that go through distinct a Started cycle as driven by IInputInteraction.
The value of this property is that of time when started was called. See the time property for how the timestamp works.
time
The time at which the action got triggered.
Declaration
public double time { get; }
Property Value
Type | Description |
---|---|
Double | Time relative to |
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*, Int32).
Declaration
public int valueSizeInBytes { get; }
Property Value
Type | Description |
---|---|
Int32 | 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*, Int32).
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*, Int32)
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. |
Int32 | bufferSize | Size of buffer allocated at |
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>());
}
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. |
See Also
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 |
---|---|
Boolean | 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 |
Remarks
This method allocates GC heap memory. Using it during normal gameplay will lead to frame-rate instabilities.
See Also
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. |