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 Input
Normal bindings directly bind to control(s) by means of path which is a "control path"
(see Input
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.
Axis
The action that is triggered by a binding is determined by its action property.
The resolution to an Input
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(Input
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 override
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 override
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 override
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 |
Remarks
This is used, for example, to divide bindings into Input
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 Input
See Also
hasOverrides
True if any of the override properties, that is, overridenull
).
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
Register
For example, "slowTap(duration=1.2,pressPoint=0.123)"
is one element
that puts a Slow
Multiple interactions can be put on a binding by separating them with a comma.
For example, "tap,slowTap(duration=1.2)"
puts both a
Tap
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 is
See Input
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 isisPartOfComposite
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 is
overrideInteractions
Interaction settings to override interactions with.
Declaration
public string overrideInteractions { get; set; }
Property Value
Type | Description |
---|---|
string | Override string for interactions or |
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
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 effective
This property can be set to an empty string to disable the binding. During resolution,
bindings with an empty effective
To set the override on an existing binding, use the methods supplied by Input
// 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 |
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 Input
If the binding is a composite (is"Vector2(normalize=false)"
.
The path of a binding may be non-destructively override at runtime using override
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 |
Returns
Type | Description |
---|---|
bool | True if the given object is an |
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 |
---|---|---|
Input |
other | Another binding. |
Returns
Type | Description |
---|---|
bool | True if the two bindings are equivalent. |
Remarks
Bindings are equivalent if their effective
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 |
---|---|
Input |
MaskByGroups(params string[])
Declaration
public static InputBinding MaskByGroups(params string[] groups)
Parameters
Type | Name | Description |
---|---|---|
string[] | groups |
Returns
Type | Description |
---|---|
Input |
Matches(InputBinding)
Check whether binding
matches the mask
represented by the current binding.
Declaration
public bool Matches(InputBinding binding)
Parameters
Type | Name | Description |
---|---|---|
Input |
binding | An input binding. |
Returns
Type | Description |
---|---|
bool | True if |
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 | |
Input |
options | Optional set of formatting options. |
Input |
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 To
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 |
---|---|---|
Input |
options | Optional set of formatting options. |
Input |
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 (is
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 |
---|---|---|
Input |
left | The first binding. |
Input |
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 |
---|---|---|
Input |
left | The first binding. |
Input |
right | The second binding. |
Returns
Type | Description |
---|---|
bool | True if the two bindings are not equal. |