docs.unity3d.com
    Show / Hide Table of Contents

    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 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
    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.WithDevice(InputControlScheme, String, Boolean)
    InputActionSetupExtensions.WithRequiredDevice(InputControlScheme, String)
    InputActionSetupExtensions.WithOptionalDevice(InputControlScheme, String)
    InputActionSetupExtensions.OrWithRequiredDevice(InputControlScheme, String)
    InputActionSetupExtensions.OrWithOptionalDevice(InputControlScheme, String)

    See Also

    controlSchemes
    AddControlScheme(InputActionAsset, String)

    Did you find this page useful? Please give it a rating:

    Thanks for rating this page!

    Report a problem on this page

    What kind of problem would you like to report?

    • This page needs code samples
    • Code samples do not work
    • Information is missing
    • Information is incorrect
    • Information is unclear or confusing
    • There is a spelling/grammar error on this page
    • Something else

    Thanks for letting us know! This page has been marked for review based on your feedback.

    If you have time, you can provide more information to help us fix the problem faster.

    Provide more information

    You've told us this page needs code samples. If you'd like to help us further, you could provide a code sample, or tell us about what kind of code sample you'd like to see:

    You've told us there are code samples on this page which don't work. If you know how to fix it, or have something better we could use instead, please let us know:

    You've told us there is information missing from this page. Please tell us more about what's missing:

    You've told us there is incorrect information on this page. If you know what we should change to make it correct, please tell us:

    You've told us this page has unclear or confusing information. Please tell us more about what you found unclear or confusing, or let us know how we could make it clearer:

    You've told us there is a spelling or grammar error on this page. Please tell us what's wrong:

    You've told us this page has a problem. Please tell us more about what's wrong:

    Thank you for helping to make the Unity documentation better!

    Your feedback has been submitted as a ticket for our documentation team to review.

    We are not able to reply to every ticket submitted.

    In This Article
    • Constructors
      • InputControlScheme(String, IEnumerable<InputControlScheme.DeviceRequirement>, String)
    • Properties
      • bindingGroup
      • deviceRequirements
      • name
    • Methods
      • Equals(Object)
      • Equals(InputControlScheme)
      • FindControlSchemeForDevice<TSchemes>(InputDevice, TSchemes)
      • FindControlSchemeForDevices<TDevices, TSchemes>(TDevices, TSchemes, out InputControlScheme, out InputControlScheme.MatchResult, InputDevice, Boolean)
      • FindControlSchemeForDevices<TDevices, TSchemes>(TDevices, TSchemes, InputDevice, Boolean)
      • GetHashCode()
      • PickDevicesFrom<TDevices>(TDevices, InputDevice)
      • SupportsDevice(InputDevice)
      • ToString()
    • Operators
      • Equality(InputControlScheme, InputControlScheme)
      • Inequality(InputControlScheme, InputControlScheme)
    • Extension Methods
    • See Also
    Back to top
    Copyright © 2023 Unity Technologies — Terms of use
    • Legal
    • Privacy Policy
    • Cookies
    • Do Not Sell or Share My Personal Information
    • Your Privacy Choices (Cookie Settings)
    "Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere (more info here). Other names or brands are trademarks of their respective owners.
    Generated by DocFX on 18 October 2023