Struct InputControlScheme.MatchResult

The result of matching a list of InputDevice against a list of InputControlScheme.DeviceRequirement in an InputControlScheme.

Namespace: UnityEngine.InputSystem
Syntax
public struct MatchResult : IEnumerable<InputControlScheme.MatchResult.Match>, IDisposable
Remarks

This struct uses InputControlList<TControl> which allocates unmanaged memory and thus must be disposed in order to not leak unmanaged heap memory.

Properties

devices

The devices that got picked from the available devices.

Declaration
public readonly InputControlList<InputDevice> devices { get; }
Property Value
Type Description
InputControlList<InputDevice>

hasMissingOptionalDevices

Whether there are missing optional devices. This does not prevent a successful match.

Declaration
public readonly bool hasMissingOptionalDevices { get; }
Property Value
Type Description
Boolean

True if there are missing optional devices.
See Also

hasMissingRequiredDevices

Whether there are missing required devices.

Declaration
public readonly bool hasMissingRequiredDevices { get; }
Property Value
Type Description
Boolean

True if there are missing, non-optional devices.
See Also

isSuccessfulMatch

Whether the device requirements got successfully matched.

Declaration
public readonly bool isSuccessfulMatch { get; }
Property Value
Type Description
Boolean

True if the scheme's device requirements were satisfied.

Item[Int32]

Declaration
public readonly InputControlScheme.MatchResult.Match this[int index] { get; }
Parameters
Type Name Description
Int32 index
Property Value
Type Description
InputControlScheme.MatchResult.Match

score

Overall, relative measure for how well the control scheme matches.

Declaration
public readonly float score { get; }
Property Value
Type Description
Single

Scoring value for the control scheme match.
Remarks

Two control schemes may, for example, both support gamepads but one may be tailored to a specific gamepad whereas the other one is a generic gamepad control scheme. To differentiate the two, we need to know not only that a control schemes but how well it matches relative to other schemes. This is what the score value is used for.

Scores are computed primarily based on layouts referenced from device requirements. To start with, each matching device requirement (whether optional or mandatory) will add 1 to the score. This the base score of a match. Then, for each requirement a delta is computed from the device layout referenced by the requirement to the device layout used by the matching control. For example, if the requirement is "<Gamepad> and the matching control uses the DualShock4GamepadHID layout, the delta is 2 as the latter layout is derived from Gamepad via the intermediate DualShockGamepad layout, i.e. two steps in the inheritance hierarchy. The inverse of the delta plus one, i.e. 1/(delta+1) is then added to the score. This means that an exact match will add an additional 1 to the score and less exact matches will add progressively smaller values to the score (proportional to the distance of the actual layout to the one used in the requirement).

What this leads to is that, for example, a control scheme with a "<Gamepad>" requirement will match a DualShock4GamepadHID with a lower score than a control scheme with a "<DualShockGamepad>" requirement as the Gamepad layout is further removed (i.e. smaller inverse delta) from DualShock4GamepadHID than DualShockGamepad.

Methods

Dispose()

Discard the list of devices.

Declaration
public void Dispose()

GetEnumerator()

Enumerate the match for each individual InputControlScheme.DeviceRequirement in the control scheme.

Declaration
public IEnumerator<InputControlScheme.MatchResult.Match> GetEnumerator()
Returns
Type Description
IEnumerator<InputControlScheme.MatchResult.Match>

An enumerate going over each individual match.

See Also