Struct InputBinding

A mapping of controls to an action.

Implements
Namespace: UnityEngine.InputSystem
Assembly: Unity.InputSystem.dll
Syntax
[Serializable]
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 = ';'
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

effectiveInteractions

This is the interaction config which is effectively being used.

Declaration
public 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 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 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

hasOverrides

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

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

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

isComposite

Whether the binding is a composite.

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

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

isPartOfComposite

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

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

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

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

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

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

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

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

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
bool

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

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
bool

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
int

A hash code.
Overrides

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(params 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
bool

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, 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(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

ToDisplayString(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, 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

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.
Overrides
Examples
var binding = new InputBinding
{
    action = "fire",
    path = "<Gamepad>/buttonSouth",
    groups = "Gamepad"
};

// Returns "fire: <Gamepad>/buttonSouth [Gamepad]".
binding.ToString();

Operators

operator ==(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
bool

True if the two bindings are equal.
See Also

operator !=(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
bool

True if the two bindings are not equal.
See Also

Implements