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

groups

deviceRequirements

Devices used by the control scheme.

Declaration

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

AddControlScheme(InputActionAsset, String)

Methods

Equals(Object)

Declaration

public override bool Equals(object obj)

Parameters

Type	Name	Description
Object	obj

Returns

Type	Description
Boolean

Overrides

ValueType.Equals(Object)

Equals(InputControlScheme)

Declaration

public bool Equals(InputControlScheme other)

Parameters

Type	Name	Description
InputControlScheme	other

Returns

Type	Description
Boolean

Implements

IEquatable<T>.Equals(T)

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

ValueType.GetHashCode()

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

ValueType.ToString()

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

InputActionSetupExtensions.WithBindingGroup(InputControlScheme, String)

InputActionSetupExtensions.WithRequiredDevice(InputControlScheme, String)

InputActionSetupExtensions.WithOptionalDevice(InputControlScheme, String)

InputActionSetupExtensions.OrWithRequiredDevice(InputControlScheme, String)

InputActionSetupExtensions.OrWithOptionalDevice(InputControlScheme, String)

See Also

controlSchemes

AddControlScheme(InputActionAsset, String)