docs.unity.cn
    Show / Hide Table of Contents

    Struct InputBinding

    A mapping of controls to an action.

    Namespace: UnityEngine.InputSystem
    Syntax
    public struct InputBinding : IEquatable<InputBinding>
    Remarks

    Each binding represents a value received from controls (see InputControl). There are two main types of bindings: "normal" bindings and "composite" bindings.

    Normal bindings directly bind to control(s) by means of path which is a "control path" (see InputControlPath for details about how to form paths). At runtime, the path of such a binding may match none, one, or multiple controls. Each control matched by the path will feed input into the binding.

    Composite bindings do not bind to controls themselves. Instead, they receive their input from their "part" bindings and then return a value representing a "composition" of those inputs. What composition specifically is performed depends on the type of the composite. AxisComposite, for example, will return a floating-point axis value computed from the state of two buttons.

    The action that is triggered by a binding is determined by its action property. The resolution to an InputAction depends on where the binding is used. For example, bindings that are part of bindings will resolve action names to actions in the same InputActionMap.

    A binding can also be used as a form of search mask or filter. In this use, path, action, and groups become search criteria that are matched against other bindings. See Matches(InputBinding) for details. This use is employed in places such as InputActionRebindingExtensions as well as in binding masks on actions (bindingMask), action maps (bindingMask), and assets (bindingMask).

    Constructors

    InputBinding(String, String, String, String, String, String)

    Initialize a new binding.

    Declaration
    public InputBinding(string path, string action = null, string groups = null, string processors = null, string interactions = null, string name = null)
    Parameters
    Type Name Description
    String path

    Path for the binding.

    String action

    Action to trigger from the binding.

    String groups

    Semicolon-separated list of binding groups the binding is associated with.

    String processors

    Comma-separated list of processors to apply to the binding.

    String interactions

    Comma-separated list of interactions to apply to the binding.

    String name

    Optional name for the binding.

    Fields

    Separator

    Character that is used to separate elements in places such as groups, interactions, and processors.

    Declaration
    public const char Separator = null
    Field Value
    Type Description
    Char
    Remarks
    // A binding that belongs to the "Keyboard&Mouse" and "Gamepad" group.
    new InputBinding
    {
        path = "*/{PrimaryAction},
        groups = "Keyboard&Mouse;Gamepad"
    };

    Properties

    action

    Name or ID of the action triggered by the binding.

    Declaration
    public string action { get; set; }
    Property Value
    Type Description
    String
    Remarks

    This is null if the binding does not trigger an action.

    For InputBindings that are used as masks, this can be a "mapName/actionName" combination or "mapName/*" to match all actions in the given map.

    See Also
    name
    id

    effectiveInteractions

    This is the interaction config which is effectively being used.

    Declaration
    public readonly string effectiveInteractions { get; }
    Property Value
    Type Description
    String
    Remarks

    This is either overrideInteractions if that is set, or interactions otherwise.

    effectivePath

    This is the bindings path which is effectively being used.

    Declaration
    public readonly string effectivePath { get; }
    Property Value
    Type Description
    String
    Remarks

    This is either overridePath if that is set, or path otherwise.

    effectiveProcessors

    This is the processor config which is effectively being used.

    Declaration
    public readonly string effectiveProcessors { get; }
    Property Value
    Type Description
    String
    Remarks

    This is either overrideProcessors if that is set, or processors otherwise.

    groups

    Optional list of binding groups that the binding belongs to.

    Declaration
    public string groups { get; set; }
    Property Value
    Type Description
    String

    List of binding groups or null.

    Remarks

    This is used, for example, to divide bindings into InputControlSchemes. Each control scheme is associated with a unique binding group through bindingGroup.

    A binding may be associated with multiple groups by listing each group name separate by a semicolon (Separator).

    new InputBinding
    {
        path = "*/{PrimaryAction},
        // Associate the binding both with the "KeyboardMouse" and
        // the "Gamepad" group.
        groups = "KeyboardMouse;Gamepad",
    }

    Note that the system places no restriction on what binding groups are used for in practice. Their use by InputControlScheme is only one possible one, but which groups to apply and how to use them is ultimately up to you.

    See Also
    bindingGroup

    hasOverrides

    True if any of the override properties, that is, overridePath, overrideProcessors, and/or overrideInteractions, are set (not null).

    Declaration
    public readonly bool hasOverrides { get; }
    Property Value
    Type Description
    Boolean

    id

    Unique ID of the binding.

    Declaration
    public Guid id { get; set; }
    Property Value
    Type Description
    Guid

    Unique ID of the binding.

    Remarks

    This can be used, for example, when storing binding overrides in local user configurations. Using the binding ID, an override can remain associated with one specific binding.

    interactions

    Optional list of interactions and their parameters.

    Declaration
    public string interactions { get; set; }
    Property Value
    Type Description
    String

    Interactions to put on the binding.

    Remarks

    Each element in the list is a name of an interaction (as registered with RegisterInteraction<T>(String)) followed by an optional list of parameters.

    For example, "slowTap(duration=1.2,pressPoint=0.123)" is one element that puts a SlowTapInteraction on the binding and sets duration to 1.2 and pressPoint to 0.123.

    Multiple interactions can be put on a binding by separating them with a comma. For example, "tap,slowTap(duration=1.2)" puts both a TapInteraction and SlowTapInteraction on the binding. See IInputInteraction for why the order matters.

    See Also
    IInputInteraction
    overrideInteractions
    hasOverrides
    SaveBindingOverridesAsJson(IInputActionCollection2)
    LoadBindingOverridesFromJson(IInputActionCollection2, String, Boolean)
    ApplyBindingOverride(InputAction, Int32, InputBinding)

    isComposite

    Whether the binding is a composite.

    Declaration
    public bool isComposite { get; set; }
    Property Value
    Type Description
    Boolean

    True if the binding is a composite.

    Remarks

    Composite bindings to not bind to controls to themselves but rather source their input from one or more "part binding" (see isPartOfComposite).

    See InputBindingComposite<TValue> for more details.

    See Also
    InputBindingComposite<TValue>

    isPartOfComposite

    Whether the binding is a "part binding" of a composite.

    Declaration
    public bool isPartOfComposite { get; set; }
    Property Value
    Type Description
    Boolean

    True if the binding is part of a composite.

    Remarks

    The bindings that make up a composite are laid out sequentially in bindings. First comes the composite itself which is flagged with isComposite. It mentions the composite and its parameters in its path property. After the composite itself come the part bindings. All subsequent bindings marked as isPartOfComposite will be associated with the composite.

    See Also
    isComposite
    InputBindingComposite<TValue>

    name

    Optional name for the binding.

    Declaration
    public string name { get; set; }
    Property Value
    Type Description
    String

    Name of the binding.

    Remarks

    For bindings that are part of composites (see isPartOfComposite), this is the name of the field on the binding composite object that should be initialized with the control target of the binding.

    overrideInteractions

    Interaction settings to override interactions with.

    Declaration
    public string overrideInteractions { get; set; }
    Property Value
    Type Description
    String

    Override string for interactions or null.

    Remarks

    If this is not null, it replaces the value of interactions.

    See Also
    effectiveInteractions
    interactions
    overridePath
    overrideProcessors
    hasOverrides
    SaveBindingOverridesAsJson(IInputActionCollection2)
    LoadBindingOverridesFromJson(IInputActionCollection2, String, Boolean)
    ApplyBindingOverride(InputAction, Int32, InputBinding)

    overridePath

    If the binding is overridden, this is the overriding path. Otherwise it is null.

    Declaration
    public string overridePath { get; set; }
    Property Value
    Type Description
    String

    Path to override the path property with.

    Remarks

    Unlike the path property, the value of the override path is not serialized. If set, it will take precedence and determine the result of effectivePath.

    This property can be set to an empty string to disable the binding. During resolution, bindings with an empty effectivePath will get skipped.

    To set the override on an existing binding, use the methods supplied by InputActionRebindingExtensions such as ApplyBindingOverride(InputAction, String, String, String).

    // Override the binding to <Gamepad>/buttonSouth on
    // myAction with a binding to <Gamepad>/buttonNorth.
    myAction.ApplyBindingOverride(
        new InputBinding
        {
            path = "<Gamepad>/buttonSouth",
            overridePath = "<Gamepad>/buttonNorth"
        });
    See Also
    path
    overrideInteractions
    overrideProcessors
    hasOverrides
    SaveBindingOverridesAsJson(IInputActionCollection2)
    LoadBindingOverridesFromJson(IInputActionCollection2, String, Boolean)
    ApplyBindingOverride(InputAction, Int32, InputBinding)

    overrideProcessors

    Processor settings to override processors with.

    Declaration
    public string overrideProcessors { get; set; }
    Property Value
    Type Description
    String

    Override string for processors or null.

    Remarks

    If this is not null, it replaces the value of processors.

    See Also
    effectiveProcessors
    processors
    overridePath
    overrideInteractions
    hasOverrides

    path

    Control path being bound to.

    Declaration
    public string path { get; set; }
    Property Value
    Type Description
    String

    Path of control(s) to source input from.

    Remarks

    Bindings reference InputControls using a regular expression-like language. See InputControlPath for details.

    If the binding is a composite (isComposite), the path is the composite string instead. For example, for a Vector2Composite, the path could be something like "Vector2(normalize=false)".

    The path of a binding may be non-destructively override at runtime using overridePath which unlike this property is not serialized. effectivePath represents the final, effective path.

    Examples
    // A binding that references the left mouse button.
    new InputBinding { path = "<Mouse>/leftButton" }
    See Also
    overridePath
    InputControlPath
    Parse(String)
    path
    FindControl(String)

    processors

    Optional list of processors to apply to control values.

    Declaration
    public string processors { get; set; }
    Property Value
    Type Description
    String

    Value processors to apply to the binding.

    Remarks

    This string has the same format as processors.

    See Also
    InputProcessor<TValue>
    overrideProcessors

    Methods

    Equals(Object)

    Compare the binding to the given object.

    Declaration
    public override bool Equals(object obj)
    Parameters
    Type Name Description
    Object obj

    An object. May be null.

    Returns
    Type Description
    Boolean

    True if the given object is an InputBinding that equals this one.

    See Also
    Equals(InputBinding)

    Equals(InputBinding)

    Check whether the binding is equivalent to the given binding.

    Declaration
    public bool Equals(InputBinding other)
    Parameters
    Type Name Description
    InputBinding other

    Another binding.

    Returns
    Type Description
    Boolean

    True if the two bindings are equivalent.

    Remarks

    Bindings are equivalent if their effectivePath, effectiveInteractions, and effectiveProcessors, plus their action and groups properties are the same. Note that the string comparisons ignore both case and culture.

    GetHashCode()

    Compute a hash code for the binding.

    Declaration
    public override int GetHashCode()
    Returns
    Type Description
    Int32

    A hash code.

    GetNameOfComposite()

    Declaration
    public string GetNameOfComposite()
    Returns
    Type Description
    String

    MaskByGroup(String)

    Declaration
    public static InputBinding MaskByGroup(string group)
    Parameters
    Type Name Description
    String group
    Returns
    Type Description
    InputBinding

    MaskByGroups(String[])

    Declaration
    public static InputBinding MaskByGroups(params string[] groups)
    Parameters
    Type Name Description
    String[] groups
    Returns
    Type Description
    InputBinding

    Matches(InputBinding)

    Check whether binding matches the mask represented by the current binding.

    Declaration
    public bool Matches(InputBinding binding)
    Parameters
    Type Name Description
    InputBinding binding

    An input binding.

    Returns
    Type Description
    Boolean

    True if binding is matched by the mask represented by this.

    Remarks

    In this method, the current binding acts as a "mask". When used this way, only three properties of the binding are taken into account: path, groups, and action.

    For each of these properties, the method checks whether they are set on the current binding and, if so, matches them against the respective property in binding.

    The way this matching works is that the value of the property in the current binding is allowed to be a semicolon-separated list where each element specifies one possible value that will produce a match.

    Note that all comparisons are case-insensitive.

    // Create a couple bindings which we can test against.
    var keyboardBinding = new InputBinding
    {
        path = "<Keyboard>/space",
        groups = "Keyboard",
        action = "Fire"
    };
    var gamepadBinding = new InputBinding
    {
        path = "<Gamepad>/buttonSouth",
        groups = "Gamepad",
        action = "Jump"
    };
    var touchBinding = new InputBinding
    {
        path = "<Touchscreen>/*/tap",
        groups = "Touch",
        action = "Jump"
    };
    
    // Example 1: Match any binding in the "Keyboard" or "Gamepad" group.
    var mask1 = new InputBinding
    {
        // We put two elements in the list here and separate them with a semicolon.
        groups = "Keyboard;Gamepad"
    };
    
    mask1.Matches(keyboardBinding); // True
    mask1.Matches(gamepadBinding); // True
    mask1.Matches(touchBinding); // False
    
    // Example 2: Match any binding to the "Jump" or the "Roll" action
    //            (the latter we don't actually have a binding for)
    var mask2 = new InputBinding
    {
        action = "Jump;Roll"
    };
    
    mask2.Matches(keyboardBinding); // False
    mask2.Matches(gamepadBinding); // True
    mask2.Matches(touchBinding); // True
    
    // Example: Match any binding to the space or enter key in the
    //          "Keyboard" group.
    var mask3 = new InputBinding
    {
        path = "<Keyboard>/space;<Keyboard>/enter",
        groups = "Keyboard"
    };
    
    mask3.Matches(keyboardBinding); // True
    mask3.Matches(gamepadBinding); // False
    mask3.Matches(touchBinding); // False

    ToDisplayString(out String, out String, InputBinding.DisplayStringOptions, InputControl)

    Turn the binding into a string suitable for display in a UI.

    Declaration
    public string ToDisplayString(out string deviceLayoutName, out string controlPath, InputBinding.DisplayStringOptions options = (InputBinding.DisplayStringOptions)0, InputControl control = null)
    Parameters
    Type Name Description
    String deviceLayoutName
    String controlPath
    InputBinding.DisplayStringOptions options

    Optional set of formatting options.

    InputControl control

    Optional control to which the binding has been resolved. If this is supplied, the resulting string can reflect things such as the current keyboard layout or hardware/platform-specific naming of controls (e.g. Xbox vs PS4 controllers as opposed to naming things generically based on the Gamepad layout).

    Returns
    Type Description
    String

    A string representation of the binding suitable for display in a UI.

    Remarks

    This method is the same as ToDisplayString(InputBinding.DisplayStringOptions, InputControl) except that it will also return the name of the device layout and path of the control, if applicable to the binding. This is useful when needing more context on the resulting display string, for example to decide on an icon to display instead of the textual display string.

    var displayString = new InputBinding("<Gamepad>/dpad/up")
        .ToDisplayString(out deviceLayout, out controlPath);
    
    // Will print "D-Pad Up".
    Debug.Log(displayString);
    
    // Will print "Gamepad".
    Debug.Log(deviceLayout);
    
    // Will print "dpad/up".
    Debug.Log(controlPath);
    See Also
    ToHumanReadableString(String, out String, out String, InputControlPath.HumanReadableStringOptions, InputControl)
    GetBindingDisplayString(InputAction, Int32, String, String, InputBinding.DisplayStringOptions)

    ToDisplayString(InputBinding.DisplayStringOptions, InputControl)

    Turn the binding into a string suitable for display in a UI.

    Declaration
    public string ToDisplayString(InputBinding.DisplayStringOptions options = (InputBinding.DisplayStringOptions)0, InputControl control = null)
    Parameters
    Type Name Description
    InputBinding.DisplayStringOptions options

    Optional set of formatting options.

    InputControl control

    Optional control to which the binding has been resolved. If this is supplied, the resulting string can reflect things such as the current keyboard layout or hardware/platform-specific naming of controls (e.g. Xbox vs PS4 controllers as opposed to naming things generically based on the Gamepad layout).

    Returns
    Type Description
    String

    A string representation of the binding suitable for display in a UI.

    Remarks

    This method works only for bindings that are not composites. If the method is called on a binding that is a composite (isComposite is true), an empty string will be returned. To automatically handle composites, use GetBindingDisplayString(InputAction, InputBinding.DisplayStringOptions, String) instead.

    var gamepadBinding = new InputBinding("<Gamepad>/buttonSouth");
    var mouseBinding = new InputBinding("<Mouse>/leftButton");
    var keyboardBinding = new InputBinding("<Keyboard>/a");
    
    // Prints "A" except on PS4 where it prints "Cross".
    Debug.Log(gamepadBinding.ToDisplayString());
    
    // Prints "LMB".
    Debug.Log(mouseBinding.ToDisplayString());
    
    // Print "Left Button".
    Debug.Log(mouseBinding.ToDisplayString(DisplayStringOptions.DontUseShortDisplayNames));
    
    // Prints the character associated with the "A" key on the current keyboard layout.
    Debug.Log(keyboardBinding, control: Keyboard.current);
    See Also
    ToHumanReadableString(String, InputControlPath.HumanReadableStringOptions, InputControl)
    GetBindingDisplayString(InputAction, Int32, InputBinding.DisplayStringOptions)

    ToString()

    Return a string representation of the binding useful for debugging.

    Declaration
    public override string ToString()
    Returns
    Type Description
    String

    A string representation of the binding.

    Examples
    var binding = new InputBinding
    {
        action = "fire",
        path = "<Gamepad>/buttonSouth",
        groups = "Gamepad"
    };
    
    // Returns "fire: <Gamepad>/buttonSouth [Gamepad]".
    binding.ToString();

    Operators

    Equality(InputBinding, InputBinding)

    Compare the two bindings for equality.

    Declaration
    public static bool operator ==(InputBinding left, InputBinding right)
    Parameters
    Type Name Description
    InputBinding left

    The first binding.

    InputBinding right

    The second binding.

    Returns
    Type Description
    Boolean

    True if the two bindings are equal.

    See Also
    Equals(InputBinding)

    Inequality(InputBinding, InputBinding)

    Compare the two bindings for inequality.

    Declaration
    public static bool operator !=(InputBinding left, InputBinding right)
    Parameters
    Type Name Description
    InputBinding left

    The first binding.

    InputBinding right

    The second binding.

    Returns
    Type Description
    Boolean

    True if the two bindings are not equal.

    See Also
    Equals(InputBinding)
    Back to top Copyright © 2022 Unity Technologies
    Generated by DocFX
    on Wednesday, January 5, 2022
    Terms of use