Class InputControlAttribute

Mark a field or property as representing/identifying an input control in some form.

Inheritance
Object
Attribute
PropertyAttribute
InputControlAttribute
Inherited Members
Namespace: UnityEngine.InputSystem.Layouts
Syntax
[AttributeUsage(AttributeTargets.Property | AttributeTargets.Field, AllowMultiple = true)]
public sealed class InputControlAttribute : PropertyAttribute, _Attribute
Remarks

This attribute is used in different places for different purposes.

When creating input control layouts (InputControlLayout) in C#, applying the attribute to fields in a state struct (see IInputStateTypeInfo or GamepadState for an example) or to properties in an input device (InputDevice), will cause an InputControl to be created from the field or property at runtime. The attribute can be applied multiple times to create multiple input controls (e.g. when having an int field that represents a bitfield where each bit is a separate button).

public class MyDevice : InputDevice
{
    // Adds an InputControl with name=myButton and layout=Button to the device.
    [InputControl]
    public ButtonControl myButton { get; set; }
}

Another use is for marking string type fields that represent input control paths. Applying the attribute to them will cause them to automatically use a custom inspector similar to the one found in the action editor. For this use, only the layout property is taken into account.

public class MyBehavior : MonoBehaviour
{
    // In the inspector, shows a control selector that is restricted to
    // selecting buttons. As a result, controlPath will be set to path
    // representing the control that was picked (e.g. "<Gamepad>/buttonSouth").
    [InputControl(layout = "Button")]
    public string controlPath;

    protected void OnEnable()
    {
        // Find controls by path.
        var controls = InputSystem.FindControl(controlPath);
        //...
    }
}

Finally, the attribute is also used in composite bindings (InputBindingComposite) to mark fields that reference parts of the composite. An example for this is negative. In this use, also only the layout property is taken into account while other properties are ignored.

public class MyComposite : InputBindingComposite<float>
{
    // Add a part to the composite called 'firstControl' which expects
    // AxisControls.
    [InputControl(layout = "Axis")]
    public int firstControl;

    // Add a part to the composite called 'secondControl' which expects
    // Vector3Controls.
    [InputControl(layout = "Vector3")]
    public int secondControl;

    //...
}

Properties

alias

An alternative name that can be used in place of name to find the control.

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

Alternative name for the control.
Remarks

This property can be used instead of aliases when there is only a single alias for the control.

Aliases, like names, are case-insensitive. Any control may have arbitrary many aliases.

See Also

aliases

A list of alternative names that can be used in place of name to find the control.

Declaration
public string[] aliases { get; set; }
Property Value
Type Description
String[]

Alternative names for the control.
Remarks

This property should be used instead of alias when a control has multiple aliases.

Aliases, like names, are case-insensitive. Any control may have arbitrary many aliases.

See Also

arraySize

Declaration
public int arraySize { get; set; }
Property Value
Type Description
Int32

bit

Declaration
public uint bit { get; set; }
Property Value
Type Description
UInt32

defaultState

Default state to write into the control's memory.

Declaration
public object defaultState { get; set; }
Property Value
Type Description
Object

Default memory state for the control.
Remarks

This is not the default value but rather the default memory state, i.e. the raw memory value read and the processed and returned as a value. By default this is null and result in a control's memory to be initialized with all zeroes.

See Also

displayName

Display name to assign to the control.

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

Display name for the control.
See Also

dontReset

Allows you to specify that a control should not be reset when its device is reset.

Declaration
public bool dontReset { get; set; }
Property Value
Type Description
Boolean

If true, resets of the device will leave the value of the control untouched except if a "hard" reset is explicitly enforced.
See Also

format

Storage format to use for the control. If not set, default storage format for the given layout is used.

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

Memory storage format to use for the control.
See Also

layout

Layout to use for the control.

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

Layout to use for the control.
Remarks

If this is not set, the system tries to infer the layout type from the value type of the field or property. If the value type is itself registered as a layout, that layout will be used (e.g. when you have a property of type ButtonControl, the layout will be inferred to be "Button"). Otherwise, if a layout with the same name as the type is registered, that layout will be used (e.g. when you have a field of type Vector3, the layout will be inferred to be "Vector3").

See Also

maxValue

Declaration
public object maxValue { get; set; }
Property Value
Type Description
Object

minValue

Lower limit for values of the control.

Declaration
public object minValue { get; set; }
Property Value
Type Description
Object

Lower limit for values of the control.
Remarks

This is null by default in which case no lower bound is applied to the TODO

name

Name to give to the name. If null or empty, the name of the property or field the attribute is applied to will be used.

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

Name to give to the control.
See Also

noisy

Whether the control is noisy. Off by default.

Declaration
public bool noisy { get; set; }
Property Value
Type Description
Boolean

Whether control is noisy.
See Also

offset

Offset in bytes to where the memory of the control starts. Relative to the offset of the parent control (which may be the device itself).

Declaration
public uint offset { get; set; }
Property Value
Type Description
UInt32

Byte offset of the control.
Remarks

If the attribute is applied to fields in an InputControlLayout and this property is not set, the offset of the field is used instead.

public struct MyStateStruct : IInputStateTypeInfo
{
    public int buttons;

    [InputControl] // Automatically uses the offset of 'axis'.
    public float axis;
}

[InputControlLayout(stateType = typeof(MyStateStruct))]
public class MyDevice : InputDevice
{
}
See Also

parameters

Optional list of parameters to apply to the control.

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

Parameters to apply to the control.
Remarks

An InputControl may expose public fields which can be set as parameters. An example of this is clamp.

public struct MyStateStruct : IInputStateTypeInfo
{
    [InputControl(parameters = "clamp,clampMin=-0.5,clampMax=0.5")]
    public float axis;
}
See Also

processors

Optional list of processors to add to the control.

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

Processors to apply to the control.
Remarks

Each element in the list is a name of a processor (as registered with RegisterProcessor<T>(String)) followed by an optional list of parameters.

For example, "normalize(min=0,max=256)" is one element that puts a NormalizeProcessor on the control and sets its min field to 0 and its its max field to 256.

Multiple processors can be put on a control by separating them with a comma. For example, "normalize(max=256),scale(factor=2)" puts both a NormalizeProcessor and a ScaleProcessor on the control. Processors are applied in the order they are listed.

See Also

shortDisplayName

Short display name to assign to the control.

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

Short display name for the control.
See Also

sizeInBits

Size of the memory storage for the control in bits.

Declaration
public uint sizeInBits { get; set; }
Property Value
Type Description
UInt32

Size of the control in bits.
Remarks

If the attribute is applied to fields in an InputControlLayout and this property is not set, the size is taken from the field.

public struct MyStateStruct : IInputStateTypeInfo
{
    public int buttons;

    [InputControl] // Automatically uses sizeof(float).
    public float axis;
}

[InputControlLayout(stateType = typeof(MyStateStruct))]
public class MyDevice : InputDevice
{
}
See Also

synthetic

Whether the control is synthetic. Off by default.

Declaration
public bool synthetic { get; set; }
Property Value
Type Description
Boolean

Whether control is synthetic.
See Also

usage

Usage to apply to the control.

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

Usage for the control.
Remarks

This property can be used in place of usages to set just a single usage on the control.

See Also

usages

Usages to apply to the control.

Declaration
public string[] usages { get; set; }
Property Value
Type Description
String[]

Usages for the control.
Remarks

This property should be used instead of usage when a control has multiple usages.

See Also

useStateFrom

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

variants

Layout variant to use for the control.

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

Layout variant to use for the control.

See Also