docs.unity3d.com
    Show / Hide Table of Contents

    Class InputActionTrace

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

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

    Constructs a new default initialized InputActionTrace.

    Declaration
    public InputActionTrace()
    Remarks

    When you use this constructor, the new InputActionTrace object does not start recording any actions. To record actions, you must explicitly set them up after creating the object. Alternatively, you can use one of the other constructor overloads which begin recording actions immediately.

    See Also
    SubscribeTo(InputAction)
    SubscribeTo(InputActionMap)
    SubscribeToAll()

    InputActionTrace(InputAction)

    Constructs a new InputActionTrace that records action.

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

    The action to be recorded.

    Exceptions
    Type Condition
    ArgumentNullException

    Thrown if action is null.

    InputActionTrace(InputActionMap)

    Constructs a new InputActionTrace that records all actions in actionMap.

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

    The action-map containing actions to be recorded.

    Exceptions
    Type Condition
    ArgumentNullException

    Thrown if action is null.

    Properties

    buffer

    Directly access the underlying raw memory queue.

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

    count

    Returns the number of events in the associated event buffer.

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

    Methods

    Clear()

    Clears all recorded data.

    Declaration
    public void Clear()
    Remarks

    Note: This method does not unsubscribe any actions that the instance is listening to, so after clearing the recorded data, new input on those subscribed actions will continue to be recorded.

    Dispose()

    Declaration
    public void Dispose()
    Implements
    IDisposable.Dispose()

    Finalize()

    Declaration
    protected void Finalize()

    GetEnumerator()

    Returns an enumerator that enumerates all action events recorded for this instance.

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

    Enumerator instance, never null.

    Implements
    IEnumerable<T>.GetEnumerator()
    See Also
    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)

    Subscribes to action.

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

    The action to be recorded.

    Remarks

    Note: This method does not prevent you from subscribing to the same action multiple times. If you subscribe to the same action multiple times, your event buffer will contain duplicate entries.

    Exceptions
    Type Condition
    ArgumentNullException

    If action is null.

    See Also
    SubscribeTo(InputActionMap)
    SubscribeToAll()

    SubscribeTo(InputActionMap)

    Subscribes to all actions contained within actionMap.

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

    The action-map containing all actions to be recorded.

    Remarks

    Note: This method does not prevent you from subscribing to the same action multiple times. If you subscribe to the same action multiple times, your event buffer will contain duplicate entries.

    Exceptions
    Type Condition
    ArgumentNullException

    Thrown if actionMap is null.

    See Also
    SubscribeTo(InputAction)
    SubscribeToAll()

    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.

    See Also
    SubscribeTo(InputAction)
    SubscribeTo(InputActionMap)

    ToString()

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

    UnsubscribeFrom(InputAction)

    Unsubscribes from an action, if that action was previously subscribed to.

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

    The action to unsubscribe from.

    Remarks

    Note: This method has no side effects if you attempt to unsubscribe from an action that you have not previously subscribed to.

    Exceptions
    Type Condition
    ArgumentNullException

    Thrown if action is null.

    See Also
    UnsubscribeFrom(InputActionMap)
    UnsubscribeFromAll()

    UnsubscribeFrom(InputActionMap)

    Unsubscribes from all actions included in actionMap.

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

    The action-map containing actions to unsubscribe from.

    Remarks

    Note: This method has no side effects if you attempt to unsubscribe from an action-map that you have not previously subscribed to.

    Exceptions
    Type Condition
    ArgumentNullException

    Thrown if actionMap is null.

    See Also
    UnsubscribeFrom(InputAction)
    UnsubscribeFromAll()

    UnsubscribeFromAll()

    Unsubscribes from all actions currently being recorded.

    Declaration
    public void UnsubscribeFromAll()
    See Also
    UnsubscribeFrom(InputAction)
    UnsubscribeFrom(InputActionMap)

    Explicit Interface Implementations

    IEnumerable.GetEnumerator()

    Declaration
    IEnumerator IEnumerable.GetEnumerator()
    Returns
    Type Description
    IEnumerator
    Implements
    IEnumerable.GetEnumerator()

    See Also

    started
    performed
    canceled
    onActionChange
    Back to top
    Terms of use
    Copyright © 2023 Unity Technologies — Terms of use
    • Legal
    • Privacy Policy
    • Cookies
    • Do Not Sell or Share My Personal Information
    • Your Privacy Choices (Cookie Settings)
    "Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere (more info here). Other names or brands are trademarks of their respective owners.
    Generated by DocFX on 18 October 2023