Class AxisComposite

A single axis value computed from a "negative" and a "positive" button.

Inheritance
Object
InputBindingComposite
InputBindingComposite<Single>
AxisComposite
Inherited Members
Namespace: UnityEngine.InputSystem.Composites
Syntax
[Preserve]
[DisplayStringFormat("{negative}/{positive}")]
public class AxisComposite : InputBindingComposite<float>
Remarks

This composite allows to arrange any arbitrary two buttons from a device in an axis configuration such that one button pushes in one direction and the other pushes in the opposite direction.

The limits of the axis are determined by minValue and maxValue. By default, they are set to [-1..1]. The values can be set as parameters.

var action = new InputAction();
action.AddCompositeBinding("Axis(minValue=0,maxValue=2")
    .With("Negative", "<Keyboard>/a")
    .With("Positive", "<Keyboard>/d");

If both buttons are pressed at the same time, the behavior depends on whichSideWins. By default, neither side will win (Neither) and the result will be 0 (or, more precisely, the midpoint between minValue and maxValue). This can be customized to make the positive side win (Positive) or the negative one (Negative).

This is useful, for example, in a driving game where break should cancel out accelerate. By binding negative to the break control(s) and positive to the acceleration control(s), and setting whichSideWins to Negative, if the break button is pressed, it will always cause the acceleration button to be ignored.

The values returned are the actual actuation values of the buttons, unaltered for positive and inverted for negative. This means that if the buttons are actual axes (e.g. the triggers on gamepads), then the values correspond to how much the axis is actuated.

Fields

maxValue

The upper bound that the axis is limited to. 1 by default.

Declaration
[Tooltip("Value to return when the positive side is fully actuated.")]
public float maxValue
Field Value
Type Description
Single
Remarks

This value corresponds to the full actuation of the control(s) bound to positive.

var action = new InputAction();
action.AddCompositeBinding("Axis(minValue=0,maxValue=2")
    .With("Negative", "<Keyboard>/a")
    .With("Positive", "<Keyboard>/d");
See Also

minValue

The lower bound that the axis is limited to. -1 by default.

Declaration
[Tooltip("Value to return when the negative side is fully actuated.")]
public float minValue
Field Value
Type Description
Single
Remarks

This value corresponds to the full actuation of the control(s) bound to negative.

var action = new InputAction();
action.AddCompositeBinding("Axis(minValue=0,maxValue=2")
    .With("Negative", "<Keyboard>/a")
    .With("Positive", "<Keyboard>/d");
See Also

negative

Binding for the button that controls the positive direction of the axis.

Declaration
public int negative
Field Value
Type Description
Int32
Remarks

This property is automatically assigned by the input system.

positive

Binding for the button that controls the negative direction of the axis.

Declaration
public int positive
Field Value
Type Description
Int32
Remarks

This property is automatically assigned by the input system.

whichSideWins

If both the positive and negative button are actuated, this determines which value is returned from the composite.

Declaration
[Tooltip("If both the positive and negative side are actuated, decides what value to return. 'Neither' (default) means that the resulting value is the midpoint between min and max. 'Positive' means that max will be returned. 'Negative' means that min will be returned.")]
public AxisComposite.WhichSideWins whichSideWins
Field Value
Type Description
AxisComposite.WhichSideWins

Properties

midPoint

The value that is returned if the composite is in a neutral position, i.e. if neither positive nor negative are actuated or if whichSideWins is set to Neither and both positive and negative are actuated.

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

Methods

EvaluateMagnitude(ref InputBindingCompositeContext)

Determine the current level of actuation of the composite.

Declaration
public override float EvaluateMagnitude(ref InputBindingCompositeContext context)
Parameters
Type Name Description
InputBindingCompositeContext context

Callback context for the binding composite. Use this to access the values supplied by part bindings.
Returns
Type Description
Single
Overrides
Remarks

This method by default returns -1, meaning that the composite does not support magnitudes. You can override the method to add support for magnitudes.

See EvaluateMagnitude() for details of how magnitudes work.

See Also

ReadValue(ref InputBindingCompositeContext)

Read a value for the composite given the supplied context.

Declaration
public override float ReadValue(ref InputBindingCompositeContext context)
Parameters
Type Name Description
InputBindingCompositeContext context

Callback context for the binding composite. Use this to access the values supplied by part bindings.
Returns
Type Description
Single

The current value of the composite according to the state made accessible through context.
Overrides
UnityEngine.InputSystem.InputBindingComposite<System.Single>.ReadValue(UnityEngine.InputSystem.InputBindingCompositeContext)
Remarks

This is the main method to implement in custom composites.

public class CustomComposite : InputBindingComposite<float>
{
    [InputControl(layout = "Button")]
    public int button;

    public float scaleFactor = 1;

    public override float ReadValue(ref InputBindingComposite context)
    {
        return context.ReadValue<float>(button) * scaleFactor;
    }
}

The other method to consider overriding is EvaluateMagnitude(ref InputBindingCompositeContext).

See Also