Struct InputBinding

A mapping of controls to an action.

Namespace: UnityEngine.InputSystem

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.

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.

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.

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.

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.

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.

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"
    });

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.

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" }

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.

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.

Overrides

ValueType.Equals(Object)

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.

Implements

IEquatable<T>.Equals(T)

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.

Overrides

ValueType.GetHashCode()

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);

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);

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

ValueType.ToString()

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.

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.

Struct InputBinding

Namespace: UnityEngine.InputSystem

Syntax

Remarks

Constructors

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

Declaration

Parameters

Fields

Separator

Declaration

Field Value

Remarks

Properties

action

Declaration

Property Value

Remarks

See Also

effectiveInteractions

Declaration

Property Value

Remarks

effectivePath

Declaration

Property Value

Remarks

effectiveProcessors

Declaration

Property Value

Remarks

groups

Declaration

Property Value

Remarks

See Also

hasOverrides

Declaration

Property Value

id

Declaration

Property Value

Remarks

interactions

Declaration

Property Value

Remarks

See Also

isComposite

Declaration

Property Value

Remarks

See Also

isPartOfComposite

Declaration

Property Value

Remarks

See Also

name

Declaration

Property Value

Remarks

overrideInteractions

Declaration

Property Value

Remarks

See Also

overridePath

Declaration

Property Value

Remarks

See Also

overrideProcessors

Declaration

Property Value

Remarks

See Also

path

Declaration

Property Value