Struct InputControlScheme

A named set of zero or more device requirements along with an associated binding group.

Namespace: UnityEngine.InputSystem
Syntax
[Serializable]
public struct InputControlScheme : IEquatable<InputControlScheme>
Remarks

Control schemes provide an additional layer on top of binding groups. While binding groups allow differentiating sets of bindings (e.g. a "Keyboard&Mouse" group versus a "Gamepad" group), control schemes impose a set of devices requirements that must be met in order for a specific set of bindings to be usable.

Note that control schemes can only be defined at the InputActionAsset level.

Constructors

InputControlScheme(String, IEnumerable<InputControlScheme.DeviceRequirement>, String)

Initialize the control scheme with the given name, device requirements, and binding group.

Declaration
public InputControlScheme(string name, IEnumerable<InputControlScheme.DeviceRequirement> devices = null, string bindingGroup = null)
Parameters
Type Name Description
String name

Name to use for the scheme. Required.
IEnumerable<InputControlScheme.DeviceRequirement> devices

List of device requirements.
String bindingGroup

Name to use for the binding group (see groups) associated with the control scheme. If this is null or empty, name is used instead (with Separator characters stripped from the name).
Exceptions
Type Condition
ArgumentNullException

name is null or empty.

Properties

bindingGroup

Binding group that is associated with the control scheme. Not null or empty except if InputControlScheme is invalid (i.e. default-initialized).

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

Binding group for the scheme.
Remarks

All bindings in this group are considered to be part of the control scheme.

See Also

deviceRequirements

Devices used by the control scheme.

Declaration
public readonly ReadOnlyArray<InputControlScheme.DeviceRequirement> deviceRequirements { get; }
Property Value
Type Description
ReadOnlyArray<InputControlScheme.DeviceRequirement>

Device requirements of the scheme.
Remarks

No two entries will be allowed to match the same control or device at runtime in order for the requirements of the control scheme to be considered satisfied. If, for example, one entry requires a "<Gamepad>" and another entry requires a "<Gamepad>", then at runtime two gamepads will be required even though a single one will match both requirements individually. However, if, for example, one entry requires "<Gamepad>/leftStick" and another requires "<Gamepad>, the same device can match both requirements as each one resolves to a different control.

It it allowed to define control schemes without device requirements, i.e. for which this property will be an empty array. Note, however, that features such as automatic control scheme switching in PlayerInput will not work with such control schemes.

name

Name of the control scheme. Not null or empty except if InputControlScheme instance is invalid (i.e. default-initialized).

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

Name of the scheme.
Remarks

May be empty or null except if the control scheme is part of an InputActionAsset.

See Also

Methods

Equals(Object)

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

Equals(InputControlScheme)

Declaration
public bool Equals(InputControlScheme other)
Parameters
Type Name Description
InputControlScheme other
Returns
Type Description
Boolean
Implements

FindControlSchemeForDevice<TSchemes>(InputDevice, TSchemes)

Return the first control schemes from the given list that supports the given device (see SupportsDevice(InputDevice)).

Declaration
public static InputControlScheme? FindControlSchemeForDevice<TSchemes>(InputDevice device, TSchemes schemes)
    where TSchemes : IEnumerable<InputControlScheme>
Parameters
Type Name Description
InputDevice device

An input device.
TSchemes schemes

A list of control schemes. Can be empty.
Returns
Type Description
Nullable<InputControlScheme>

The first schemes from schemes that supports device or null if none of the schemes is usable with the device.
Type Parameters
Name Description
TSchemes

Collection type to use for the list of schemes.
Exceptions
Type Condition
ArgumentNullException

device is null -or- schemes is null.

FindControlSchemeForDevices<TDevices, TSchemes>(TDevices, TSchemes, out InputControlScheme, out InputControlScheme.MatchResult, InputDevice, Boolean)

Declaration
public static bool FindControlSchemeForDevices<TDevices, TSchemes>(TDevices devices, TSchemes schemes, out InputControlScheme controlScheme, out InputControlScheme.MatchResult matchResult, InputDevice mustIncludeDevice = null, bool allowUnsuccessfulMatch = false)
    where TDevices : IReadOnlyList<InputDevice> where TSchemes : IEnumerable<InputControlScheme>
Parameters
Type Name Description
TDevices devices
TSchemes schemes
InputControlScheme controlScheme
InputControlScheme.MatchResult matchResult
InputDevice mustIncludeDevice
Boolean allowUnsuccessfulMatch
Returns
Type Description
Boolean
Type Parameters
Name Description
TDevices
TSchemes

FindControlSchemeForDevices<TDevices, TSchemes>(TDevices, TSchemes, InputDevice, Boolean)

Given a list of devices and a list of control schemes, find the most suitable control scheme to use with the devices.

Declaration
public static InputControlScheme? FindControlSchemeForDevices<TDevices, TSchemes>(TDevices devices, TSchemes schemes, InputDevice mustIncludeDevice = null, bool allowUnsuccesfulMatch = false)
    where TDevices : IReadOnlyList<InputDevice> where TSchemes : IEnumerable<InputControlScheme>
Parameters
Type Name Description
TDevices devices

A list of devices. If the list is empty, only schemes with empty deviceRequirements lists will get matched.
TSchemes schemes

A list of control schemes.
InputDevice mustIncludeDevice

If not null, a successful match has to include the given device.
Boolean allowUnsuccesfulMatch

If true, then allow returning a match that has unsatisfied requirements but still matched at least some requirement. If there are several unsuccessful matches, the returned scheme is still the highest scoring one among those.
Returns
Type Description
Nullable<InputControlScheme>

The control scheme that best matched the given devices or null if no scheme was found suitable.
Type Parameters
Name Description
TDevices

Collection type to use for the list of devices.
TSchemes

Collection type to use for the list of schemes.
Remarks

Any successful match (see isSuccessfulMatch) will be considered. The one that matches the most amount of devices (see devices) will be returned. If more than one schemes matches equally well, the first one encountered in the list is returned.

Note that schemes are not required to match all devices available in the list. The result will simply be the scheme that matched the most devices of what was devices. Use PickDevicesFrom<TDevices>(TDevices, InputDevice) to find the devices that a control scheme selects.

This method is parameterized over TDevices and TSchemes to allow avoiding GC heap allocations from boxing of structs such as ReadOnlyArray<TValue>.

// Create an .inputactions asset.
var asset = ScriptableObject.CreateInstance<InputActionAsset>();

// Add some control schemes to the asset.
asset.AddControlScheme("KeyboardMouse")
    .WithRequiredDevice<Keyboard>()
    .WithRequiredDevice<Mouse>());
asset.AddControlScheme("Gamepad")
    .WithRequiredDevice<Gamepad>());
asset.AddControlScheme("DualGamepad")
    .WithRequiredDevice<Gamepad>())
    .WithOptionalGamepad<Gamepad>());

// Add some devices that we can test with.
var keyboard = InputSystem.AddDevice<Keyboard>();
var mouse = InputSystem.AddDevice<Mouse>();
var gamepad1 = InputSystem.AddDevice<Gamepad>();
var gamepad2 = InputSystem.AddDevice<Gamepad>();

// Matching with just a keyboard won't match any scheme.
InputControlScheme.FindControlSchemeForDevices(
    new InputDevice[] { keyboard }, asset.controlSchemes);

// Matching with a keyboard and mouse with match the "KeyboardMouse" scheme.
InputControlScheme.FindControlSchemeForDevices(
    new InputDevice[] { keyboard, mouse }, asset.controlSchemes);

// Matching with a single gamepad will match the "Gamepad" scheme.
// Note that since the second gamepad is optional in "DualGamepad" could
// match the same set of devices but it doesn't match any better than
// "Gamepad" and that one comes first in the list.
InputControlScheme.FindControlSchemeForDevices(
    new InputDevice[] { gamepad1 }, asset.controlSchemes);

// Matching with two gamepads will match the "DualGamepad" scheme.
// Note that "Gamepad" will match this device list as well. If "DualGamepad"
// didn't exist, "Gamepad" would be the result here. However, "DualGamepad"
// matches the list better than "Gamepad" so that's what gets returned here.
InputControlScheme.FindControlSchemeForDevices(
    new InputDevice[] { gamepad1, gamepad2 }, asset.controlSchemes);
Exceptions
Type Condition
ArgumentNullException

devices is null -or- schemes is null.

GetHashCode()

Declaration
public override int GetHashCode()
Returns
Type Description
Int32
Overrides

PickDevicesFrom<TDevices>(TDevices, InputDevice)

Based on a list of devices, make a selection that matches the deviceRequirements imposed by the control scheme.

Declaration
public InputControlScheme.MatchResult PickDevicesFrom<TDevices>(TDevices devices, InputDevice favorDevice = null)
    where TDevices : IReadOnlyList<InputDevice>
Parameters
Type Name Description
TDevices devices

A list of devices to choose from.
InputDevice favorDevice

If not null, the device will be favored over other devices in devices. Note that the device must be present in the list also.
Returns
Type Description
InputControlScheme.MatchResult

A InputControlScheme.MatchResult structure containing the result of the pick. Note that this structure must be manually Dispose() or unmanaged memory will be leaked.
Type Parameters
Name Description
TDevices
Remarks

Does not allocate managed memory.

SupportsDevice(InputDevice)

Whether the control scheme has a requirement in deviceRequirements that targets the given device.

Declaration
public bool SupportsDevice(InputDevice device)
Parameters
Type Name Description
InputDevice device

An input device.
Returns
Type Description
Boolean

True if the control scheme has a device requirement matching the device.
Remarks

Note that both optional (see isOptional) and non-optional device requirements are taken into account.

Exceptions
Type Condition
ArgumentNullException

device is null.

ToString()

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

Operators

Equality(InputControlScheme, InputControlScheme)

Declaration
public static bool operator ==(InputControlScheme left, InputControlScheme right)
Parameters
Type Name Description
InputControlScheme left
InputControlScheme right
Returns
Type Description
Boolean

Inequality(InputControlScheme, InputControlScheme)

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

Extension Methods

See Also