[API Proposal] Basic input slice of the new high level API

[andrew-oc]

Background and Motivation

This API is an effort to simplify using the Input System for new users, small projects, and/or experienced users/teams starting new projects. It should be possible for all users to implement basic input functionality in a zero-configuration, everything-just-works, environment. New users should have to learn a minimum number of new concepts to get started, without having to read any documentation, but existing users of the legacy input manager should feel some level of familiarity with the interface. The intent is also that it is possible to transition with minimum effort from this high level API into the lower level APIs piecemeal as a game progresses.

This slice of the high level API includes methods for users to get basic input only (read: no actions, maps, processors, interactions, bindings, assets, control schemes, action types, disambiguation, callbacks, composites, or any other low level concepts are involved).

Proposed API

namespace UnityEngine.InputSystem
{
  public static partial class Input
  {
    public static IReadOnlyList<Gamepad> gamepads { get; }
    public static IReadOnlyList<Joystick> joysticks { get; }
    public static ReadOnlyArray<InputSlot> gamepadSlotEnums { get; }
    public static int maxGamepadSlots { get; }

    public static bool IsPressed(Inputs input, InputSlot slot = InputSlot.All);
    public static bool WasPressedThisFrame(Inputs input, InputSlot slot = InputSlot.All);
    public static bool WasReleasedThisFrame(Inputs input, InputSlot slot = InputSlot.All);

    public static bool IsPressed(GamepadButton button, InputSlot slot = InputSlot.All);
    public static bool WasPressedThisFrame(GamepadButton button, InputSlot slot = InputSlot.All);
    public static bool WasReleasedThisFrame(GamepadButton button, InputSlot slot = InputSlot.All);

    public static bool IsPressed(JoystickButton button, InputSlot slot = InputSlot.All);
    public static bool WasPressedThisFrame(JoystickButton button, InputSlot slot = InputSlot.All);
    public static bool WasReleasedThisFrame(JoystickButton button, InputSlot  slot = InputSlot.All);

    public static float GetAxis(Inputs input, InputSlot slot = InputSlot.All);
    public static float GetAxis(Inputs negativeAxis, Inputs positiveAxis);

    public static Vector2 GetAxis(Inputs left, Inputs right, Inputs up, Inputs down);
    public static Vector2 GetAxisRaw(Inputs left, Inputs right, Inputs up, Inputs down);
    public static Vector2 GetAxis(GamepadAxis stick, InputSlot inputSlot= InputSlot.All);
    public static Vector2 GetAxis(InputSlot joystickSlot, float deadzone = kDefaultJoystickDeadzone);

    public static void SetGamepadTriggerPressPoint(float pressPoint, InputSlot gamepadSlot = InputSlot.All);
    public static void SetGamepadStickDeadzone(float deadzone, InputSlot gamepadSlot = InputSlot.All);

    public static bool IsGamepadConnected(InputSlot gamepadSlot);
    public static bool DidGamepadConnectThisFrame(InputSlot gamepadSlot);
    public static bool DidGamepadDisconnectThisFrame(InputSlot gamepadSlot);

    public static Vector2 pointerPosition { get; }
    public static bool pointerPresent { get; }
    public static Vector2 scrollDelta { get; }

    public enum GamepadAxis
    {
        LeftStick,
        RightStick
    }

    public enum GamepadButton
    {
      DpadUp,
      DpadDown,
      DpadLeft,
      DpadRight,
      North,
      East,
      South,
      West,
      LeftStickButton,
      RightStickButton,
      LeftShoulder,
      RightShoulder,
      LeftTrigger,
      RightTrigger,
      Start,
      Select,
      X = West,
      Y = North,
      A = South,
      B = East,
      Cross = South,
      Square = West,
      Triangle = North,
      Circle = East
    }

    public enum JoystickButton
    {
        Trigger,
        Button2,
        Button3,
        Button4,
        Button5,
        Button6,
        Button7,
        Button8
    }

    public enum GamepadSlot
    {
        Slot1 = 0,
        Slot2,
        Slot3,
        Slot4,
        Slot5,
        Slot6,
        Slot7,
        Slot8,
        Slot9,
        Slot10,
        Slot11,
        Slot12,
        All = Int32.MaxValue,
        Any = Int32.MaxValue
    }

    public enum JoystickSlot
    {
        Slot1 = 0,
        Slot2,
        Slot3,
        Slot4,
        All = Int32.MaxValue,
        Any = Int32.MaxValue
    }

    public enum Inputs
    {
        Key_Space,
        Key_Enter,
        Key_Tab,
        Key_Backquote,
        Key_Quote,
        Key_Semicolon,
        Key_Comma,
        Key_Period,
        Key_Slash,
        Key_Backslash,
        Key_LeftBracket,
        Key_RightBracket,
        Key_Minus,
        Key_Equals,
        Key_A,
        Key_B,
        Key_C,
        Key_D,
        Key_E,
        Key_F,
        Key_G,
        Key_H,
        Key_I,
        Key_J,
        Key_K,
        Key_L,
        Key_M,
        Key_N,
        Key_O,
        Key_P,
        Key_Q,
        Key_R,
        Key_S,
        Key_T,
        Key_U,
        Key_V,
        Key_W,
        Key_X,
        Key_Y,
        Key_Z,
        Key_Digit1,
        Key_Digit2,
        Key_Digit3,
        Key_Digit4,
        Key_Digit5,
        Key_Digit6,
        Key_Digit7,
        Key_Digit8,
        Key_Digit9,
        Key_Digit0,
        Key_LeftShift,
        Key_RightShift,
        Key_LeftAlt,
        Key_RightAlt,
        Key_AltGr = Key_RightAlt,
        Key_LeftCtrl,
        Key_RightCtrl,
        Key_LeftMeta,
        Key_RightMeta,
        Key_LeftWindows = Key_LeftMeta,
        Key_RightWindows = Key_RightMeta,
        Key_LeftApple = Key_LeftMeta,
        Key_RightApple = Key_RightMeta,
        Key_LeftCommand = Key_LeftMeta,
        Key_RightCommand = Key_RightMeta,
        Key_ContextMenu,
        Key_Escape,
        Key_LeftArrow,
        Key_RightArrow,
        Key_UpArrow,
        Key_DownArrow,
        Key_Backspace,
        Key_PageDown,
        Key_PageUp,
        Key_Home,
        Key_End,
        Key_Insert,
        Key_Delete,
        Key_CapsLock,
        Key_NumLock,
        Key_PrintScreen,
        Key_ScrollLock,
        Key_Pause,
        Key_NumpadEnter,
        Key_NumpadDivide,
        Key_NumpadMultiply,
        Key_NumpadPlus,
        Key_NumpadMinus,
        Key_NumpadPeriod,
        Key_NumpadEquals,
        Key_Numpad0,
        Key_Numpad1,
        Key_Numpad2,
        Key_Numpad3,
        Key_Numpad4,
        Key_Numpad5,
        Key_Numpad6,
        Key_Numpad7,
        Key_Numpad8,
        Key_Numpad9,
        Key_F1,
        Key_F2,
        Key_F3,
        Key_F4,
        Key_F5,
        Key_F6,
        Key_F7,
        Key_F8,
        Key_F9,
        Key_F10,
        Key_F11,
        Key_F12,
        Key_OEM1,
        Key_OEM2,
        Key_OEM3,
        Key_OEM4,
        Key_OEM5,


        Mouse_Left,
        Mouse_Right,
        Mouse_Middle,
        Mouse_Forward,
        Mouse_Back,


        Gamepad_DpadUp,
        Gamepad_DpadDown,
        Gamepad_DpadLeft,
        Gamepad_DpadRight,
        Gamepad_North,
        Gamepad_East,
        Gamepad_South,
        Gamepad_West,

        Gamepad_LeftStickButton,
        Gamepad_RightStickButton, 
        Gamepad_LeftStickUp,
        Gamepad_LeftStickDown,
        Gamepad_LeftStickLeft,
        Gamepad_LeftStickRight,
        Gamepad_RightStickUp,
        Gamepad_RightStickDown,
        Gamepad_RightStickLeft,
        Gamepad_RightStickRight,
        Gamepad_LeftShoulder,
        Gamepad_RightShoulder,
        Gamepad_LeftTrigger,
        Gamepad_RightTrigger,
        Gamepad_Start,
        Gamepad_Select,
        Gamepad_X = Gamepad_West,
        Gamepad_Y = Gamepad_North,
        Gamepad_A = Gamepad_South,
        Gamepad_B = Gamepad_East,
        Gamepad_Cross = Gamepad_South,
        Gamepad_Square = Gamepad_West,
        Gamepad_Triangle = Gamepad_North,
        Gamepad_Circle = Gamepad_East,

        Joystick_Trigger,
        Joystick_Button2,
        Joystick_Button3,
        Joystick_Button4,
        Joystick_Button5,
        Joystick_Button6,
        Joystick_Button7,
        Joystick_Button8,
    }

  }
}

API Usage

Perform some gameplay action when both the left keyboard Control key and left mouse button are pressed.

  if (Input.IsPressed(Inputs.Key_LeftCtrl) && Input.IsPressed(Inputs.Mouse_Left))
  {
    DoTheThing();
  }

Start a timer when a control is pressed and perform some action on release.

  public class ChargedFire : MonoBehaviour
  {
    private float m_StartTime = 0;

    public void Update()
    {
      if (Input.WasPressedThisFrame(Inputs.Mouse_Left))
      {
        m_StartTime = Time.time;
      }

      if (Input.WasReleasedThisFrame(Inputs.Mouse_Left))
      {
        Fire(Time.time - m_StartTime);
        m_StartTime = 0;
      }
    }

    private IEnumerator Fire(float chargeTime)
    {
      ...
      yield return null;
    }
  }

Use the left and right triggers of any gamepad as a one-dimensional axis.

  public class SteerWithGamepadTriggers : MonoBehaviour
  {
    [SerializeField] private float m_MaxDegreesPerSecond;

    public void Update()
    {
      // GetAxis returns a value in the range [-1, 1]
      float steering = Input.GetAxis(Inputs.Gamepad_LeftTrigger, Inputs.Gamepad_RightTrigger);
      transform.Rotate(Vector2.up, steering * m_MaxDegreesPerSecond * Time.deltaTime);
    }
  }

Use the WASD keys to move in a plane at the same speed in any direction.

  public class Move2DWithWASD : MonoBehaviour
  {
    [SerializeField] private float m_MaxVelocity;

    public void Update()
    {
      Vector2 directionVector = Input.GetAxis(Inputs.Key_A, Inputs.Key_D, Inputs.Key_W, Inputs.Key_S);
      transform.Translate(directionVector * m_MaxVelocity * Time.deltaTime);
    }
  }

Use the right analogue stick on any gamepad to move a game object in a plane.

  public class Move2DWithGamepadRightStick : MonoBehaviour
  {
    [SerializeField] private float m_MaxVelocity;

    public void Update()
    {
      Vector2 directionVector = Input.GetAxis(GamepadAxis.RightStick);
      transform.Translate(directionVector * m_MaxVelocity * Time.deltaTime);
    }
  }

If any joysticks are connected, get the axis value of the first one and use it to move a game object.

  public class Move2DWithJoystick : MonoBehaviour
  {
    [SerializeField] private float m_MaxVelocity;

    public void Update()
    {
      if (Input.joysticks.Count > 0)
      {
        Vector2 directionVector = Input.GetAxis(0);
        transform.Translate(directionVector * m_MaxVelocity * Time.deltaTime);
      }
    }
  }

Spawn prefabs continuously while the south button on any gamepad is pressed.

  public class FireProjectiles : MonoBehaviour
  {
    [SerializeField] private float m_FireInterval;
    [SerializeField] private GameObject m_Projectile;
    private float m_LastFireTime;

    public void Update()
    {
      if (Input.IsGamepadButtonPressed(GamepadButton.South) && Time.time - m_LastFireTime > m_FireInterval)
      {
        Instantiate(m_Projectile);
        m_LastFireTime = Time.time;
      }
    }
  }

Set some state to true in the frame the gamepad Square button is pressed on any PlayStation gamepad, and false when it is released.

  public class Jump : MonoBehaviour
  {
    private bool m_IsJumping;

    public void Update()
    {
      if (Input.IsGamepadButtonDown(GamepadButton.Square))
      {
        m_IsJumping = true;
      }

      if (Input.IsGamepadButtonUp(GamepadButton.Square))
      {
        m_IsJumping = false;
      }
    }
  }

Set the gamepad trigger press point to 0.9 for the gamepad connected to slot 1.

  Input.SetGamepadTriggerPressPoint(0.9f, GamepadSlot.Slot1);

Set the gamepad stick deadzone to 0.3 for all gamepads.

  Input.SetGamepadStickDeadzone(0.3f);

Simple local multiplayer using gamepad slots

  public class SimpleLocalMultiplayer : MonoBehaviour
  {
    public struct Player
    {
      public GameObject gameObject;
      public GamepadSlot slot;
    }

    [SerializeField] private GameObject m_PlayerPrefab;
    private List<Player> m_Players;

    public void Start()
    {
      m_Players = new List<Player>();

      for (var i = 0; i < 4; i++)
      {
        if (Input.IsGamepadConnected((GamepadSlot)i))
          m_Players.Add(new Player
          {
            gameObject = Instantiate(m_PlayerPrefab),
            slot = (GamepadSlot)i
          });
      }
    }

    public void Update()
    {
      foreach (Player player in m_Players)
      {
        var movement = Input.GetAxis(GamepadAxis.LeftStick, player.slot);
        player.gameObject.GetComponent<PlayerController>().Move(movement);

        if (Input.IsGamepadButtonDown(GamepadButton.West, player.slot))
          player.gameObject.GetComponent<PlayerController>().Shoot();
      }
    }
  }

Notes

• The IsPressed/WasPressed/WasReleased and GetAxis methods look at all connected devices of the type represented by the argument. If the corresponding controls of any are actuated, the actuation values of those controls will be returned.
• The keyboard constants in the Inputs enum should represent physical key locations based on one consistent (US?) keyboard layout, so things like W, A, S, and D keys will still work on any OS layout.
• Some important features that might be considered part of basic input will come in the next few API proposals, such as the lastInput property, which is a way to easily query whether any input occurred in the current frame and what device type was last used by the player. This will come later because it is considered part of the high level event system.
• The device arrays exposed by the Input class (keyboards, mice, gamepads) are stable, that is, if a device disconnects, the index that it was occupying remains empty until either the same device or another device of the same type connects. That device will fill the hole left by the previous one. This is to abstract gameplay logic from having to track devices across disconnects and reconnects. A game can simply target a slot index for each player and not have to be concerned when players change devices.

Risks

Namespace issues

The most obvious name for the static class wrapping all of this functionality is Input, but that name is already taken by legacy input. We can work around it by using

using Input = UnityEngine.InputSystem.HighLevelAPI.Input;

in our using declarations, but that's not great. I think we could include a code analyzer to detect when users are using the wrong type and display it as a compilation error or warning to help mitigate this, but maybe a different name is better. InputMgr?

The infernal 'Was pressed this frame' issue

WasPressedThisFrame/WasReleasedThisFame i.e. was pressed this frame functionality, isn't particularly robust at the device layer right now because controls don't have any concept of a frame. So a press and release within a frame won't cause WasPressedThisFrame calls to return true because they only look at the current state, not the state over the whole frame. Since this API funnels users towards the polling approach, this flaw might become more obvious and should be fixed.

[jimon]

Question, so let's say users use this API earlier in development of their game, satisfied with it, and then later in the development they need to support control rebinding, how would that look like?

[jimon]

Have you had thoughts about making enum Inputs a partial enum? (doesn't exist in C# but still)

Thinking if we could achieve stability of constants of that enum (e.g. adding new key should change value of Key_U) we could achieve better things down the line (native->managed api transition stability)

[jimon]

Have you tried going with method overloads? E.g.

    public static bool IsButtonPressed(Inputs input);
    public static bool IsButtonDown(Inputs input);
    public static bool IsButtonUp(Inputs input);

    public static bool IsButtonPressed(GamepadButton button, GamepadSlot gamepadSlot = GamepadSlot.Any);
    public static bool IsButtonDown(GamepadButton button, GamepadSlot gamepadSlot = GamepadSlot.Any);
    public static bool IsButtonUp(GamepadButton input, GamepadSlot gamepadSlot = GamepadSlot.Any);

    ... etc ...

Seems like if we do GamepadButton-esque enums for every sub-type we could provide overloads for each and rely on type safety for API UX

[jimon]

Why there is no public static Vector2 GetAxis(Inputs stick); and no public static Vector2 GetAxis(Inputs horizontal, Inputs vertical);? Feels like providing multiple enum values for same control could work given that copies will point to different type

That way in the enum we would have Up, Down, Left, Right, Horizonal, Vertical, 2D. Imho will provide better API UX if we can leverage autocomplete to do the right thing.

[andrew-oc]

Question, so let's say users use this API earlier in development of their game, satisfied with it, and then later in the development they need to support control rebinding, how would that look like?

This part of the API doesn't support control rebinding. The action part, coming next, does though. But the path would be to replace the Input.IsControlxxx method calls with the equivalent Input.[action].

Have you had thoughts about making enum Inputs a partial enum? (doesn't exist in C# but still)

Thinking if we could achieve stability of constants of that enum (e.g. adding new key should change value of Key_U) we could achieve better things down the line (native->managed api transition stability)

Can you elaborate? What would that look like if the concept of partial enum doesn't exist in C#? What would be the motivation to add another enum there? It should already cover all inputs on the standard devices that this API supports.

Have you tried going with method overloads? E.g.

    public static bool IsButtonPressed(Inputs input);
    public static bool IsButtonDown(Inputs input);
    public static bool IsButtonUp(Inputs input);

    public static bool IsButtonPressed(GamepadButton button, GamepadSlot gamepadSlot = GamepadSlot.Any);
    public static bool IsButtonDown(GamepadButton button, GamepadSlot gamepadSlot = GamepadSlot.Any);
    public static bool IsButtonUp(GamepadButton input, GamepadSlot gamepadSlot = GamepadSlot.Any);

    ... etc ...

Seems like if we do GamepadButton-esque enums for every sub-type we could provide overloads for each and rely on type safety for API UX

I did look at that, but I felt that it implied that you couldn't use IsControlPressed/Up/Down for gamepad buttons, which you can, and in a completely type safe way.

Why there is no public static Vector2 GetAxis(Inputs stick); and no public static Vector2 GetAxis(Inputs horizontal, Inputs vertical);? Feels like providing multiple enum values for same control could work given that copies will point to different type

That way in the enum we would have Up, Down, Left, Right, Horizonal, Vertical, 2D. Imho will provide better API UX if we can leverage autocomplete to do the right thing.

Because those wouldn't be entirely type safe. It would be possible to pass the wrong enum in both cases, and I feel like we should avoid runtime errors where possible.

[jimon]

Existence of both Inputs.Gamepad_DpadUp and GamepadButton.DpadUp at a same time is a bit of a deal breaker for me tbh. Can we work around so there is always only one definition for a control?

[ekcoh]

Regarding Pressed, Released, Down, Up. I think its key to keep consistency in these. E.g. Pressed is an event/transition so is Released right? Down/Up are absolute state evaluations right? - It feels IsPressed is confusing since nothing is constantly transitioning into pressed? IsDown/IsUp makes sense though. Noticed this in, e.g.

  public class FireProjectiles : MonoBehaviour
  {
    [SerializeField] private float m_FireInterval;
    [SerializeField] private GameObject m_Projectile;
    private float m_LastFireTime;

    public void Update()
    {
      if (Input.IsGamepadButtonPressed(GamepadButton.South) && Time.time - m_LastFireTime > m_FireInterval)
      {
        Instantiate(m_Projectile);
        m_LastFireTime = Time.time;
      }
    }
  }

Or is this implying everytime the button is pressed as in down, up sequence and one such event happened during a frame one projectile is spawned. If two such events happened during a frame one projectile is spawned?

[lyndon-unity]

What does this property represent? It was the only one that wasn't intuitive to me.
public static Vector2 mousePresent { get; }

[andrew-oc]

@ekcoh The intent was that Pressed means this control is currently held down. Maybe IsHeld is better? Down and up are the actual state transitions. Those methods are intended to return true in the frame that the control is pressed or released, and they're named for familiarity with the legacy API.

@lyndon-unity It's meant to represent whether a mouse is connected or not, but should have had a bool return type.

[lyndon-unity]

@lyndon-unity It's meant to represent whether a mouse is connected or not, but should have had a bool return type.

It would be good to be consistent with the pad function naming which uses the phrase 'connected'
public static bool IsGamepadConnected(GamepadSlot slot);

I momentarily wondered then if it should be moved to a function and take a parameter but I see is a convenience for the common case with a single mouse (or first mouse). Do we need both?

Do we need a IsJoystickConnected(int joystickIndex);

I'm also wondering why we have an enum for gamepad but just int for joystick.
I see its because we have the 'all/any' cases. Do we need that for Joysticks too though?

Or am I confused with what joystickIndex is? Is this parameter a device index or for multiple sticks on a single device
public static Vector2 GetJoystickAxis(int joystickIndex);

[andrew-oc]

It would be good to be consistent with the pad function naming which uses the phrase 'connected' public static bool IsGamepadConnected(GamepadSlot slot);

Initially it was called mouseConnected but it ended up as mousePresent for two reasons. One, familiarity with the legacy API which also calls it mousePresent, and two, a 'mouse' can be any device that allows a cursor to be moved, like a trackpad in a laptop or gamepad, so it feels wrong calling it "connected". What do you think?

I momentarily wondered then if it should be moved to a function and take a parameter but I see is a convenience for the common case with a single mouse (or first mouse). Do we need both?

Yeah, it's a toss up between keeping the API surface as small as possible (bearing in mind it will grow a bit over the next few proposals) and providing convenience methods for every device. It is still possible to check if a mouse is present even without this convenience method by checking the mice collection for a non-null device in any slot but my thoughts on this is that it's not a common enough use case to have it's own API method.

Do we need a IsJoystickConnected(int joystickIndex);

I'm also wondering why we have an enum for gamepad but just int for joystick. I see its because we have the 'all/any' cases. Do we need that for Joysticks too though?

Same as previous argument.

Or am I confused with what joystickIndex is? Is this parameter a device index or for multiple sticks on a single device
public static Vector2 GetJoystickAxis(int joystickIndex);

Nope, you're correct. It's a slot index for a device. Maybe we could rename GamepadSlot to DeviceSlot and use that for all APIs that take a slot index. Would that make things better?

[lyndon-unity]

Initially it was called mouseConnected but it ended up as mousePresent for two reasons. One, familiarity with the legacy API which also calls it mousePresent, and two, a 'mouse' can be any device that allows a cursor to be moved, like a trackpad in a laptop or gamepad, so it feels wrong calling it "connected". What do you think?

Thank you I wasn't aware of those aspects. Your reasoning seems fair to me. Perhaps we simply need to add a comment on this property to make it a little clearer. E.g.

public static Vector2 mousePresent { get; } // True if a mouse, trackpad or similar is present/connected.

(I was then wondering if IsGamepadConnected should be renamed IsGamepadPresent for consistency, but I still prefer the phrase connected so I'm I've mixed feelings.)

Maybe we could rename GamepadSlot to DeviceSlot and use that for all APIs that take a slot index. Would that make things better?

I like that proposal and feel it would make it more consistent and allow for the All/Any case for Joysticks.

[ekcoh]

Regarding previous comment/feedback

@ekcoh The intent was that Pressed means this control is currently held down. Maybe IsHeld is better? Down and up are the actual state transitions. Those methods are intended to return true in the frame that the control is pressed or released, and they're named for familiarity with the legacy API.

This was also discussed in other review thread, IsHeld is better I think but also reflects assumption about push button which might be fine. IsHeld is definately a contender, other options include I guess IsActuated/IsActive/IsTriggered/IsOn. Maybe it would be helpful to try to define whether we want to model the physical action in the names or the logical. On a physical model (class) it makes more sense to use e.g. Held, Down, Up etc if it models a physical entity, for a logical entity is feels like it makes more sense with e.g. On, Off, High, Low, Active etc. Naming is hard, but I think it might be good if we avoid mixing physical and logical modeling/representation.