UnityGame/Library/PackageCache/com.unity.inputsystem/Documentation~/Migration.md

uid
input-system-migration

Migrating from the old Input Manager

• Read the introductory documentation first
• Which system is enabled?
• Comparison of API in the old Input Manager and the new Input System package
  • Action-based input
  • Directly reading Gamepad and Joystick controls
  • Keyboard
  • Mouse
  • Touch and Pen
  • Sensors

This page is provided to help you match input-related API from Unity's old, built-in input (known as the Input Manager) to the corresponding API in the new Input System package.

Read the introductory documentation first

If you're new to the Input System package and have landed on this page looking for documentation, it's best to read the QuickStart Guide, and the Concepts and Workflows pages from the introduction section of the documentation, so that you can make sure you're choosing the best workflow for your project's input requirements.

This is because there are a number of different ways to read input using the Input System, and some of the directly corresponding API methods on this page might give you the quickest - but least flexible - solution, and may not be suitable for a project with more complex requirements.

Which system is enabled?

When installing the new Input System, Unity prompts you to enable the new input system and disable the old one. You can change this setting at any time later, by going to Edit > Project Settings > Player > Other Settings > Active Input Handling, as described here.

There are scripting symbols defined which allow you to use conditional compilation based on which system is enabled, as shown in the example below.

#if ENABLE_INPUT_SYSTEM
    // New input system backends are enabled.
#endif

#if ENABLE_LEGACY_INPUT_MANAGER
    // Old input backends are enabled.
#endif

Note: It is possible to have both systems enabled at the same time, in which case both sets of code in the example above above will be active.

Comparison of API in the old Input Manager and the new Input System package

Below is a list comparing the API from the old Input Manager with the corresponding API for the new Input System package. All of the new Input System package APIs listed below are in the UnityEngine.InputSystem namespace. The namespace is omitted here for brevity.

Action-based input

Action-based input refers to reading pre-configured named axes, buttons, or other controls. (Read more about Action-based input)

• In the old Input Manager, these are defined in the Axes list, in the Input Manager section of the Project Settings window. (Below, left)
• In the new Input System, these are defined in the Actions Editor, which can be found in the Input System Package section of the Project Settings window, or by opening an Action Asset. (Below, right)

On the left, the old Input Manager Axes Configuration window, in Project settings. On the right, the new Input System's Actions Editor.

Note: In some cases for named axes and buttons, the new Input System requires slightly more code than the old Input Manager, but this results in better performance. This is because in the new Input System, the logic is separated into two parts: the first is to find and store a reference to the action (usually done once, for example in your Start method), and the second is to read the action (usually done every frame, for example in your Update method). In contrast, the old Input Manager used a string-based API to "find" and "read" the value at the same time, because it was not possible to store a reference to a button or axis. This results in worse performance, because the axis or button is looked up each time the value is read.

To find and store references to actions, which can be axes or buttons use FindAction. For example:

 // A 2D axis action named "Move"
InputAction moveAction = InputSystem.actions.FindAction("Move");

 // A button action named "Jump"
InputAction jumpAction = InputSystem.actions.FindAction("Jump");

Then, to read the action values, use the following:

Input Manager (Old)	Input System (New)
Input.GetAxis In the old Input Manager System, all axes are 1D and return float values. For example, to read the horizontal and vertical axes: float h = Input.GetAxis("Horizontal"); float v = Input.GetAxis("Vertical");	Use ReadValue on the reference to the action to read the current value of the axis. In the new Input System, axes can be 1D, 2D or other value types. You must specify the correct value type that corresponds with how the action is set up. This example shows a 2D axis: Vector2 moveVector = moveAction.ReadValue<Vector2>();.
Input.GetButton Example: bool jumpValue = Input.GetButton("Jump");	Use IsPressed on the reference to the action to read the button value. Example: bool jumpValue = jumpAction.IsPressed();.
Input.GetButtonDown Example: bool jump = Input.GetButtonDown("Jump");	Use WasPressedThisFrame on the reference to the action to read if the button was pressed this frame. Example: bool jumpValue = jumpAction.WasPressedThisFrame();.
Input.GetButtonUp Example: bool jump = Input.GetButtonUp("Jump");	Use WasReleasedThisFrame on the reference to the action to read whether the button was released this frame. Example: bool jumpValue = jumpAction.WasReleasedThisFrame();.
Input.GetAxisRaw For example, to read the raw values of the horizontal and vertical axes: float h = Input.GetAxisRaw("Horizontal"); float v = Input.GetAxisRaw("Vertical");	No direct equivalent, but if there are processors associated with the action, you can use InputControl<>.ReadUnprocessedValue() to read unprocessed values. Example: Vector2 moveVector = moveAction.ReadUnprocessedValue(); Note: This returns the same value as ReadValue when there are no processors on the action.

Directly reading Gamepad and Joystick controls

Directly reading hardware controls bypasses the new Input System's action-based workflow, which has some benefits and some drawbacks. (Read more about directly reading devices)

Input Manager (Old)	Input System (New)
Input.GetKey Example: Input.GetKey(KeyCode.JoystickButton0)	Use isPressed on the corresponding Gamepad button. Example: InputSystem.GamePad.current.buttonNorth.isPressed.
Input.GetKeyDown Example: Input.GetKeyDown(KeyCode.JoystickButton0)	Use wasPressedThisFrame on the corresponding Gamepad button. Example: InputSystem.GamePad.current.buttonNorth.WasPressedThisFrame.
Input.GetKeyUp Example: Input.GetKeyUp(KeyCode.JoystickButton0)	Use wasReleasedThisFrame on the corresponding Gamepad button. Example: InputSystem.GamePad.current.buttonNorth.wasReleasedThisFrame.
Input.GetJoystickNames	There is no API that corresponds to this exactly, but there are examples of how to read all connected devices here.
Input.IsJoystickPreconfigured	Not needed. Devices which derive from Gamepad always correctly implement the mapping of axes and buttons to the corresponding InputControl members of the Gamepad class. Input.ResetInputAxes

Keyboard

Input Manager (Old)	Input System (New)
Input.GetKey Example: Input.GetKey(KeyCode.Space)	Use isPressed on the corresponding key. Example: InputSystem.Keyboard.current.spaceKey.isPressed
Input.GetKeyDown Example: Input.GetKeyDown(KeyCode.Space)	Use wasPressedThisFrame on the corresponding key. Example: InputSystem.Keyboard.current.spaceKey.wasPressedThisFrame
Input.GetKeyUp Example: Input.GetKeyUp(KeyCode.Space)	Use wasReleasedThisFrame on the corresponding key. Example: InputSystem.Keyboard.current.spaceKey.wasReleasedThisFrame
Input.anyKey	Use onAnyButtonPress. This also includes controller buttons as well as keyboard keys.
Input.anyKeyDown	Use Keyboard.current.anyKey.wasUpdatedThisFrame
Input.compositionCursorPos	Use Keyboard.current.SetIMECursorPosition(myPosition)
Input.compositionString	Subscribe to the Keyboard.onIMECompositionChange.
Input.imeCompositionMode	Use: Keyboard.current.SetIMEEnabled(true) Also see: Keyboard text input documentation.
Input.imeIsSelected	Use: Keyboard.current.imeSelected
Input.inputString	Subscribe to the Keyboard.onTextInput event: Keyboard.current.onTextInput += character => /* ... */;

Mouse

Input Manager (Old)	Input System (New)
Input.GetMouseButton Example: Input.GetMouseButton(0)	Use isPressed on the corresponding mouse button. Example: InputSystem.Mouse.current.leftButton.isPressed
Input.GetMouseButtonDown Example: Input.GetMouseButtonDown(0)	Use wasPressedThisFrame on the corresponding mouse button. Example: InputSystem.Mouse.current.leftButton.wasPressedThisFrame
Input.GetMouseButtonUp Example: Input.GetMouseButtonUp(0)	Use wasReleasedThisFrame on the corresponding mouse button. Example: InputSystem.Mouse.current.leftButton.wasReleasedThisFrame
Input.mousePosition	Use Mouse.current.position.ReadValue() Example: Vector2 position = Mouse.current.position.ReadValue(); Note: Mouse simulation from touch isn't implemented yet.
Input.mousePresent	No corresponding API yet.

Touch and Pen

Input Manager (Old)	Input System (New)
Input.GetTouch For example: Touch touch = Input.GetTouch(0); Vector2 touchPos = touch.position;	Use EnhancedTouch.Touch.activeTouches[i] Example: Vector2 touchPos = EnhancedTouch.Touch.activeTouches[0].position; Note: Enable enhanced touch support first by calling EnhancedTouch.Enable().
Input.multiTouchEnabled	No corresponding API yet.
Input.simulateMouseWithTouches	No corresponding API yet.
Input.stylusTouchSupported	No corresponding API yet.
Input.touchCount	EnhancedTouch.Touch.activeTouches.Count Note: Enable enhanced touch support first by calling EnhancedTouchSupport.Enable()
Input.touches	EnhancedTouch.Touch.activeTouches Note: Enable enhanced touch support first by calling EnhancedTouch.Enable()
Input.touchPressureSupported	No corresponding API yet.
Input.touchSupported	Touchscreen.current != null
Input.backButtonLeavesApp	No corresponding API yet.
GetPenEvent GetLastPenContactEvent ResetPenEvents ClearLastPenContactEvent	Use: Pen.current See the Pen, tablet and stylus support docs for more information.

---

Note: UnityEngine.TouchScreenKeyboard is not part of the old Input Manager API, so you can continue to use it when migrating to the new Input System package.

Sensors

Input Manager (Old)	Input System (New)
Input.acceleration	Accelerometer.current.acceleration.ReadValue().
Input.accelerationEventCount Input.accelerationEvents	Acceleration events aren't made available separately from other input events. See the accelerometer code sample on the Sensors page.
Input.compass	No corresponding API yet.
Input.compensateSensors	InputSettings.compensateForScreenOrientation.
Input.deviceOrientation	No corresponding API yet.
Input.gyro	The UnityEngine.Gyroscope class is replaced by multiple separate sensor Devices in the new Input System: Gyroscope to measure angular velocity. GravitySensor to measure the direction of gravity. AttitudeSensor to measure the orientation of the device. Accelerometer to measure the total acceleration applied to the device. LinearAccelerationSensor to measure acceleration applied to the device, compensating for gravity.
Input.gyro.attitude	AttitudeSensor.current.orientation.ReadValue().
Input.gyro.enabled	Get: Gyroscope.current.enabled Set: EnableDevice(Gyroscope.current); DisableDevice(Gyroscope.current); Note: The new Input System replaces UnityEngine.Gyroscope with multiple separate sensor devices. Substitute Gyroscope with other sensors in the sample as needed. See the notes for Input.gyro above for details.
Input.gyro.gravity	GravitySensor.current.gravity.ReadValue()
Input.gyro.rotationRate	Gyroscope.current.angularVelocity.ReadValue().
Input.gyro.rotationRateUnbiased	No corresponding API yet.
Input.gyro.updateInterval	Sensor.samplingFrequency Example: Gyroscope.current.samplingFrequency = 1.0f / updateInterval; Notes: samplingFrequency is in Hz, not in seconds as updateInterval, so you need to divide 1 by the value. The new Input System replaces UnityEngine.Gyroscope with multiple separate sensor devices. Substitute Gyroscope with other sensors in the sample as needed. See the notes for Input.gyro above for details.
Input.gyro.userAcceleration	LinearAccelerationSensor.current.acceleration.acceleration.ReadValue()
Input.location	No corresponding API yet.
Input.GetAccelerationEvent	See notes for Input.accelerationEvents above.