Class InputActionTrace

Records the triggering of actions into a sequence of events that can be replayed at will.

Inheritance
System.Object
InputActionTrace
Namespace: UnityEngine.InputSystem.Utilities
Syntax
public sealed class InputActionTrace : IEnumerable<InputActionTrace.ActionEventPtr>, IEnumerable, IDisposable
Remarks

This is an alternate way to the callback-based responses (such as performed) of InputAction. Instead of executing response code right away whenever an action triggers, an RecordAction(InputAction.CallbackContext) which can then be queried on demand.

The recorded data will stay valid even if the bindings on the actions are changed (e.g. by enabling a different set of bindings through altering bindingMask or devices or when modifying the paths of bindings altogether). Note, however, that when this happens, a trace will have to make a private copy of the data that stores the binding resolution state. This means that there can be GC allocation spike when reconfiguring actions that have recorded data in traces.

var trace = new InputActionTrace();

// Subscribe trace to single action.
// (Use UnsubscribeFrom to unsubscribe)
trace.SubscribeTo(myAction);

// Subscribe trace to entire action map.
// (Use UnsubscribeFrom to unsubscribe)
trace.SubscribeTo(myActionMap);

// Subscribe trace to all actions in the system.
trace.SubscribeToAll();

// Record a single triggering of an action.
myAction.performed +=
    ctx =>
    {
        if (ctx.ReadValue<float>() > 0.5f)
            trace.RecordAction(ctx);
    };

// Output trace to console.
Debug.Log(string.Join(",\n", trace));

// Walk through all recorded actions and then clear trace.
foreach (var record in trace)
{
    Debug.Log($"{record.action} was {record.phase} by control {record.control} at {record.time}");

    // To read out the value, you either have to know the value type or read the
    // value out as a generic byte buffer. Here we assume that the value type is
    // float.

    Debug.Log("Value: " + record.ReadValue<float>());

    // An alternative is read the value as an object. In this case, you don't have
    // to know the value type but there will be a boxed object allocation.
    Debug.Log("Value: " + record.ReadValueAsObject());
}
trace.Clear();

// Unsubscribe trace from everything.
trace.UnsubscribeFromAll();

// Release memory held by trace.
trace.Dispose();

Constructors

InputActionTrace()

Declaration
public InputActionTrace()

InputActionTrace(InputAction)

Declaration
public InputActionTrace(InputAction action)
Parameters
Type Name Description
InputAction action

InputActionTrace(InputActionMap)

Declaration
public InputActionTrace(InputActionMap actionMap)
Parameters
Type Name Description
InputActionMap actionMap

Properties

buffer

Directly access the underlying raw memory queue.

Declaration
public InputEventBuffer buffer { get; }
Property Value
Type Description
InputEventBuffer

count

Declaration
public int count { get; }
Property Value
Type Description
System.Int32

Methods

Clear()

Declaration
public void Clear()

Dispose()

Declaration
public void Dispose()

Finalize()

Declaration
protected void Finalize()

GetEnumerator()

Declaration
public IEnumerator<InputActionTrace.ActionEventPtr> GetEnumerator()
Returns
Type Description
System.Collections.Generic.IEnumerator<InputActionTrace.ActionEventPtr>

RecordAction(InputAction.CallbackContext)

Record the triggering of an action as an InputActionTrace.ActionEventPtr.

Declaration
public void RecordAction(InputAction.CallbackContext context)
Parameters
Type Name Description
InputAction.CallbackContext context

SubscribeTo(InputAction)

Declaration
public void SubscribeTo(InputAction action)
Parameters
Type Name Description
InputAction action

SubscribeTo(InputActionMap)

Declaration
public void SubscribeTo(InputActionMap actionMap)
Parameters
Type Name Description
InputActionMap actionMap

SubscribeToAll()

Record any action getting triggered anywhere.

Declaration
public void SubscribeToAll()
Remarks

This does not require the trace to actually hook into every single action or action map in the system. Instead, the trace will listen to onActionChange and automatically record every triggered action.

ToString()

Declaration
public override string ToString()
Returns
Type Description
System.String
Overrides
System.Object.ToString()

UnsubscribeFrom(InputAction)

Declaration
public void UnsubscribeFrom(InputAction action)
Parameters
Type Name Description
InputAction action

UnsubscribeFrom(InputActionMap)

Declaration
public void UnsubscribeFrom(InputActionMap actionMap)
Parameters
Type Name Description
InputActionMap actionMap

UnsubscribeFromAll()

Declaration
public void UnsubscribeFromAll()

See Also