diff --git a/Packages/com.unity.inputsystem/Documentation~/Gamepad.md b/Packages/com.unity.inputsystem/Documentation~/Gamepad.md index 163849e918..ad4acf19cf 100644 --- a/Packages/com.unity.inputsystem/Documentation~/Gamepad.md +++ b/Packages/com.unity.inputsystem/Documentation~/Gamepad.md @@ -3,16 +3,16 @@ uid: input-system-gamepad --- # Gamepad Support -- [Gamepad Support](#gamepad-support) - - [Controls](#controls) - - [Deadzones](#deadzones) - - [Polling](#polling) - - [Rumble](#rumble) - - [Pausing, resuming, and stopping haptics](#pausing-resuming-and-stopping-haptics) - - [PlayStation controllers](#playstation-controllers) - - [Xbox controllers](#xbox-controllers) - - [Switch controllers](#switch-controllers) - - [Cursor Control](#cursor-control) +- [Controls](#controls) + - [Deadzones](#deadzones) +- [Polling](#polling) +- [Rumble](#rumble) + - [Pausing, resuming, and stopping haptics](#pausing-resuming-and-stopping-haptics) +- [PlayStation controllers](#playstation-controllers) +- [Xbox controllers](#xbox-controllers) +- [Switch controllers](#switch-controllers) +- [Cursor Control](#cursor-control) +- [Discover all connected devices](#discover-all-connected-devices) A [`Gamepad`](../api/UnityEngine.InputSystem.Gamepad.html) is narrowly defined as a Device with two thumbsticks, a D-pad, and four face buttons. Additionally, gamepads usually have two shoulder and two trigger buttons. Most gamepads also have two buttons in the middle. @@ -198,3 +198,37 @@ The Input System support Switch Pro controllers on desktop computers via the [`S ## Cursor Control To give gamepads and joysticks control over a hardware or software cursor, you can use the [`VirtualMouseInput`](../api/UnityEngine.InputSystem.UI.VirtualMouseInput.html) component. See [`VirtualMouseInput` component](UISupport.md#virtual-mouse-cursor-control) in the UI section of the manual. + +## Discover all connected devices + +There are various ways to discover the currently connected devices, as shown in the code samples below. + +To query a list of all connected devices (does not allocate; read-only access): +``` +InputSystem.devices +``` + +To get notified when a device is added or removed: +``` +InputSystem.onDeviceChange += + (device, change) => + { + if (change == InputDeviceChange.Added || change == InputDeviceChange.Removed) + { + Debug.Log($"Device '{device}' was {change}"); + } + } +``` + +To find all gamepads and joysticks: +``` +var devices = InputSystem.devices; +for (var i = 0; i < devices.Count; ++i) +{ + var device = devices[i]; + if (device is Joystick || device is Gamepad) + { + Debug.Log("Found " + device); + } +} +``` diff --git a/Packages/com.unity.inputsystem/Documentation~/Images/InputManagerVsInputActions.png b/Packages/com.unity.inputsystem/Documentation~/Images/InputManagerVsInputActions.png new file mode 100644 index 0000000000..30b44d7f78 Binary files /dev/null and b/Packages/com.unity.inputsystem/Documentation~/Images/InputManagerVsInputActions.png differ diff --git a/Packages/com.unity.inputsystem/Documentation~/Migration.md b/Packages/com.unity.inputsystem/Documentation~/Migration.md index 67a6fd01f2..8f313acd08 100644 --- a/Packages/com.unity.inputsystem/Documentation~/Migration.md +++ b/Packages/com.unity.inputsystem/Documentation~/Migration.md @@ -3,15 +3,25 @@ uid: input-system-migration --- # Migrating from the old Input Manager +- [Read the introductory documentation first](#read-the-introductory-documentation-first) +- [Which system is enabled?](#which-system-is-enabled) +- [Comparison of API in the old Input Manager and the new Input System package](#comparison-of-api-in-the-old-input-manager-and-the-new-input-system-package) + - [Action-based input](#action-based-input) + - [Directly reading Gamepad and Joystick controls](#directly-reading-gamepad-and-joystick-controls) + - [Keyboard](#keyboard) + - [Mouse](#mouse) + - [Touch and Pen](#touch-and-pen) + - [Sensors](#sensors) + This page is provided to help you match input-related API from Unity's old, built-in input (known as the [Input Manager](https://docs.unity3d.com/Manual/class-InputManager.html)) 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](QuickStartGuide.md), and the [Concepts](Concepts.md) and [Workflows](Workflows.md) 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 many 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. +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? +## 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](./Installation.md#enabling-the-new-input-backends). @@ -29,207 +39,116 @@ There are scripting symbols defined which allow you to use conditional compilati > **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. -## List of corresponding API in the old Input Manager new Input System package +## Comparison of API in the old Input Manager and the new Input System package -All of the new APIs listed below are in the `UnityEngine.InputSystem` namespace. The namespace is omitted here for brevity. `UnityEngine.InputSystem` is referenced in full for easy disambiguation. +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 -|Input Manager (Old)|Input System (New)| -|--|--| -[`Input.acceleration`](https://docs.unity3d.com/ScriptReference/Input-acceleration.html)|[`Accelerometer.current.acceleration.ReadValue()`](../api/UnityEngine.InputSystem.Accelerometer.html). -[`Input.accelerationEventCount`](https://docs.unity3d.com/ScriptReference/Input-accelerationEventCount.html)
[`Input.accelerationEvents`](https://docs.unity3d.com/ScriptReference/Input-accelerationEvents.html)|Acceleration events aren't made available separately from other input events. The following code traces all input events on the [`Accelerometer.current`](../api/UnityEngine.InputSystem.Accelerometer.html) device. -```CSharp - private InputEventTrace trace; - - void StartTrace() - { - InputSystem.EnableDevice(Accelerometer.current); - - trace = new InputEventTrace(Accelerometer.current); - trace.Enable(); - } - - void Update() - { - foreach (var e in trace) - { - //... - } - trace.Clear(); - } -``` -|Input Manager (Old)|Input System (New)| -|--|--| -[`Input.anyKey`](https://docs.unity3d.com/ScriptReference/Input-anyKey.html)|[`InputSystem.onAnyButtonPress`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_onAnyButtonPress)
Example:
`InputSystem.onAnyButtonPress.CallOnce(ctrl => Debug.Log($"Button {ctrl} pressed!"));` -|Input Manager (Old)|Input System (New)| -|--|--| -[`Input.anyKeyDown`](https://docs.unity3d.com/ScriptReference/Input-anyKeyDown.html)|[`Keyboard.current.anyKey.wasUpdatedThisFrame`](../api/UnityEngine.InputSystem.Keyboard.html) -[`Input.backButtonLeavesApp`](https://docs.unity3d.com/ScriptReference/Input-backButtonLeavesApp.html)|No corresponding API yet. -[`Input.compass`](https://docs.unity3d.com/ScriptReference/Input-compass.html)|No corresponding API yet. -[`Input.compensateSensors`](https://docs.unity3d.com/ScriptReference/Input-compensateSensors.html)|[`InputSystem.settings.compensateForScreenOrientation`](../api/UnityEngine.InputSystem.InputSettings.html#UnityEngine_InputSystem_InputSettings_compensateForScreenOrientation). -[`Input.compositionCursorPos`](https://docs.unity3d.com/ScriptReference/Input-compositionCursorPos.html)|[`Keyboard.current.SetIMECursorPosition(myPosition)`](../api/UnityEngine.InputSystem.Keyboard.html#UnityEngine_InputSystem_Keyboard_SetIMECursorPosition_UnityEngine_Vector2_) -[`Input.compositionString`](https://docs.unity3d.com/ScriptReference/Input-compositionString.html)|Subscribe to the [`Keyboard.onIMECompositionChange`](../api/UnityEngine.InputSystem.Keyboard.html#UnityEngine_InputSystem_Keyboard_onIMECompositionChange) event: +Action-based input refers to reading pre-configured named axes, buttons, or other controls. ([Read more about Action-based input](./Workflow-Actions.md)) -```CSharp - var compositionString = ""; - Keyboard.current.onIMECompositionChange += composition => - { - compositionString = composition.ToString(); - }; -``` -|Input Manager (Old)|Input System (New)| -|--|--| -[`Input.deviceOrientation`](https://docs.unity3d.com/ScriptReference/Input-deviceOrientation.html)|No corresponding API yet. -[`Input.gyro`](https://docs.unity3d.com/ScriptReference/Input-gyro.html)|The `UnityEngine.Gyroscope` class is replaced by multiple separate sensor Devices in the new Input System:
[`Gyroscope`](../api/UnityEngine.InputSystem.Gyroscope.html) to measure angular velocity.
[`GravitySensor`](../api/UnityEngine.InputSystem.GravitySensor.html) to measure the direction of gravity.
[`AttitudeSensor`](../api/UnityEngine.InputSystem.AttitudeSensor.html) to measure the orientation of the device.
[`Accelerometer`](../api/UnityEngine.InputSystem.Accelerometer.html) to measure the total acceleration applied to the device.
[`LinearAccelerationSensor`](../api/UnityEngine.InputSystem.LinearAccelerationSensor.html) to measure acceleration applied to the device, compensating for gravity. -[`Input.gyro.attitude`](https://docs.unity3d.com/ScriptReference/Gyroscope-attitude.html)|[`AttitudeSensor.current.orientation.ReadValue()`](../api/UnityEngine.InputSystem.AttitudeSensor.html). -[`Input.gyro.enabled`](https://docs.unity3d.com/ScriptReference/Gyroscope-enabled.html)|Get: `Gyroscope.current.enabled`
Set:
`InputSystem.EnableDevice(Gyroscope.current);`
`InputSystem.DisableDevice(Gyroscope.current);`

__Note__: The new Input System replaces `UnityEngine.Gyroscope` with multiple separate sensor devices. Substitute [`Gyroscope`](../api/UnityEngine.InputSystem.Gyroscope.html) with other sensors in the sample as needed. See the notes for `Input.gyro` above for details. -[`Input.gyro.gravity`](https://docs.unity3d.com/ScriptReference/Gyroscope-gravity.html)|[`GravitySensor.current.gravity.ReadValue()`](../api/UnityEngine.InputSystem.GravitySensor.html) -[`Input.gyro.rotationRate`](https://docs.unity3d.com/ScriptReference/Gyroscope-rotationRate.html)|[`Gyroscope.current.angularVelocity.ReadValue()`](../api/UnityEngine.InputSystem.Gyroscope.html). -[`Input.gyro.rotationRateUnbiased`](https://docs.unity3d.com/ScriptReference/Gyroscope-rotationRateUnbiased.html)|No corresponding API yet. -[`Input.gyro.updateInterval`](https://docs.unity3d.com/ScriptReference/Gyroscope-updateInterval.html)|[`Sensor.samplingFrequency`](../api/UnityEngine.InputSystem.Sensor.html#UnityEngine_InputSystem_Sensor_samplingFrequency)
Example:
`Gyroscope.current.samplingFrequency = 1.0f / updateInterval;`

__Notes__:
[`samplingFrequency`](../api/UnityEngine.InputSystem.Sensor.html#UnityEngine_InputSystem_Sensor_samplingFrequency) is in Hz, not in seconds as [`updateInterval`](https://docs.unity3d.com/ScriptReference/Gyroscope-updateInterval.html), so you need to divide 1 by the value.

The new Input System replaces `UnityEngine.Gyroscope` with multiple separate sensor devices. Substitute [`Gyroscope`](../api/UnityEngine.InputSystem.Gyroscope.html) with other sensors in the sample as needed. See the notes for `Input.gyro` above for details. -[`Input.gyro.userAcceleration`](https://docs.unity3d.com/ScriptReference/Gyroscope-userAcceleration.html)|[`LinearAccelerationSensor.current.acceleration.acceleration.ReadValue()`](../api/UnityEngine.InputSystem.LinearAccelerationSensor.html) -[`Input.imeCompositionMode`](https://docs.unity3d.com/ScriptReference/Input-imeCompositionMode.html)|No corresponding API yet. -[`Input.imeIsSelected`](https://docs.unity3d.com/ScriptReference/Input-imeIsSelected.html)|Get: `Keyboard.current.imeSelected`
Set: `Keyboard.current.SetIMEEnabled(true);` -[`Input.inputString`](https://docs.unity3d.com/ScriptReference/Input-inputString.html)|Subscribe to the [`Keyboard.onTextInput`](../api/UnityEngine.InputSystem.Keyboard.html#UnityEngine_InputSystem_Keyboard_onTextInput) event:
`Keyboard.current.onTextInput += character => /* ... */;` -[`Input.location`](https://docs.unity3d.com/ScriptReference/Input-location.html)|No corresponding API yet. -[`Input.mousePosition`](https://docs.unity3d.com/ScriptReference/Input-mousePosition.html)|[`Mouse.current.position.ReadValue()`](../api/UnityEngine.InputSystem.Mouse.html)
__Note__: Mouse simulation from touch isn't implemented yet. -[`Input.mousePresent`](https://docs.unity3d.com/ScriptReference/Input-mousePresent.html)|[`Mouse.current != null`](../api/UnityEngine.InputSystem.Mouse.html#UnityEngine_InputSystem_Mouse_current). -[`Input.multiTouchEnabled`](https://docs.unity3d.com/ScriptReference/Input-multiTouchEnabled.html)|No corresponding API yet. -[`Input.simulateMouseWithTouches`](https://docs.unity3d.com/ScriptReference/Input-multiTouchEnabled.html)|No corresponding API yet. -[`Input.stylusTouchSupported`](https://docs.unity3d.com/ScriptReference/Input-stylusTouchSupported.html)|No corresponding API yet. -[`Input.touchCount`](https://docs.unity3d.com/ScriptReference/Input-touchCount.html)|[`InputSystem.EnhancedTouch.Touch.activeTouches.Count`](../api/UnityEngine.InputSystem.EnhancedTouch.Touch.html#UnityEngine_InputSystem_EnhancedTouch_Touch_activeTouches)
__Note__: Enable enhanced touch support first by calling [`InputSystem.EnhancedTouchSupport.Enable()`](../api/UnityEngine.InputSystem.EnhancedTouch.EnhancedTouchSupport.html#UnityEngine_InputSystem_EnhancedTouch_EnhancedTouchSupport_Enable) -[`Input.touches`](https://docs.unity3d.com/ScriptReference/Input-touches.html)|[`InputSystem.EnhancedTouch.Touch.activeTouches`](../api/UnityEngine.InputSystem.EnhancedTouch.Touch.html#UnityEngine_InputSystem_EnhancedTouch_Touch_activeTouches)
__Note__: Enable enhanced touch support first by calling [`InputSystem.EnhancedTouch.Enable()`](../api/UnityEngine.InputSystem.EnhancedTouch.EnhancedTouchSupport.html#UnityEngine_InputSystem_EnhancedTouch_EnhancedTouchSupport_Enable) -[`Input.touchPressureSupported`](https://docs.unity3d.com/ScriptReference/Input-touchPressureSupported.html)|No corresponding API yet. -[`Input.touchSupported`](https://docs.unity3d.com/ScriptReference/Input-touchSupported.html)|[`Touchscreen.current != null`](../api/UnityEngine.InputSystem.Touchscreen.html#UnityEngine_InputSystem_Touchscreen_current) -[`Input.GetAccelerationEvent`](https://docs.unity3d.com/ScriptReference/Input.GetAccelerationEvent.html)|See notes for `Input.accelerationEvents` above. -[`Input.GetAxis`](https://docs.unity3d.com/ScriptReference/Input.GetAxis.html)|Set up an action as a 1D or 2D axis in the Actions Editor, then use [`InputAction.ReadValue`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_ReadValue__1) to read the value or 2D vector from the axis. There are some default built-in axis actions. See the [Quickstart Guide](QuickStartGuide.md) to get started quickly. -[`Input.GetAxisRaw`](https://docs.unity3d.com/ScriptReference/Input.GetAxisRaw.html)|Not directly applicable. You can use [`InputControl<>.ReadUnprocessedValue()`](../api/UnityEngine.InputSystem.InputControl-1.html#UnityEngine_InputSystem_InputControl_1_ReadUnprocessedValue) to read unprocessed values from any control. -[`Input.GetButton`](https://docs.unity3d.com/ScriptReference/Input.GetButton.html)|[`InputAction.IsPressed`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_IsPressed_) -|[`Input.GetButtonDown`](https://docs.unity3d.com/ScriptReference/Input.GetButtonDown.html)|[`InputAction.WasPressedThisFrame`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_WasPressedThisFrame_) -[`Input.GetButtonUp`](https://docs.unity3d.com/ScriptReference/Input.GetButtonUp.html)|[`InputAction.WasReleasedThisFrame`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_WasReleasedThisFrame_) -[`Input.GetJoystickNames`](https://docs.unity3d.com/ScriptReference/Input.GetJoystickNames.html)|There is no API that corresponds to this exactly. Here are various ways to discover connected Devices: +- 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](ActionsEditor.md), which can be found in the **Input System Package** section of the **Project Settings** window, or by opening an [Action Asset](ActionAssets.md). _(Below, right)_ -``` -// Query a list of all connected Devices (does not allocate; read-only access). -InputSystem.devices - -// Get notified when a Device is added or removed. -InputSystem.onDeviceChange += - (device, change) => - { - if (change == InputDeviceChange.Added || change == InputDeviceChange.Removed) - { - Debug.Log($"Device '{device}' was {change}"); - } - } - -// Find all gamepads and joysticks. -var devices = InputSystem.devices; -for (var i = 0; i < devices.Count; ++i) -{ - var device = devices[i]; - if (device is Joystick || device is Gamepad) - { - Debug.Log("Found " + device); - } -} -``` -|Input Manager (Old)|Input System (New)| -|--|--| -[`Input.GetKey`](https://docs.unity3d.com/ScriptReference/Input.GetKey.html)|[`ButtonControl.isPressed`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html#UnityEngine_InputSystem_Controls_ButtonControl_isPressed) on the corresponding key: +![](Images/InputManagerVsInputActions.png)
_On the left, the old Input Manager Axes Configuration window, in Project settings. On the right, the new Input System's [Actions Editor](ActionsEditor.md)._ -``` -// Using KeyControl property directly. -Keyboard.current.spaceKey.isPressed -Keyboard.current.aKey.isPressed // etc. +__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. -// Using Key enum. -Keyboard.current[Key.Space].isPressed +To find and store references to actions, which can be axes or buttons use [`FindAction`](../api/UnityEngine.InputSystem.InputActionAsset.html#UnityEngine_InputSystem_InputActionAsset_FindAction_System_String_System_Boolean_). For example: +``` + // A 2D axis action named "Move" +InputAction moveAction = InputSystem.actions.FindAction("Move"); -// Using key name. -((KeyControl)Keyboard.current["space"]).isPressed + // A button action named "Jump" +InputAction jumpAction = InputSystem.actions.FindAction("Jump"); ``` ->__Note__: The Input System identifies keys by physical layout, not according to the current language mapping of the keyboard. To query the name of the key according to the language mapping, use [`KeyControl.displayName`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_displayName). +Then, to read the action values, use the following: |Input Manager (Old)|Input System (New)| |--|--| -[`Input.GetKeyDown`](https://docs.unity3d.com/ScriptReference/Input.GetKeyDown.html)|Use [`ButtonControl.wasPressedThisFrame`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html#UnityEngine_InputSystem_Controls_ButtonControl_wasPressedThisFrame) on the corresponding key: +[`Input.GetAxis`](https://docs.unity3d.com/ScriptReference/Input.GetAxis.html)
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`](../api/UnityEngine.InputSystem.InputBindingComposite-1.html#UnityEngine_InputSystem_InputBindingComposite_1_ReadValue_UnityEngine_InputSystem_InputBindingCompositeContext__) 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();`.

+[`Input.GetButton`](https://docs.unity3d.com/ScriptReference/Input.GetButton.html)
Example:
`bool jumpValue = Input.GetButton("Jump");`

|Use [`IsPressed`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_IsPressed_) on the reference to the action to read the button value.
Example:
`bool jumpValue = jumpAction.IsPressed();`.

+[`Input.GetButtonDown`](https://docs.unity3d.com/ScriptReference/Input.GetButtonDown.html)
Example: `bool jump = Input.GetButtonDown("Jump");`

|Use [`WasPressedThisFrame`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_WasPressedThisFrame_) on the reference to the action to read if the button was pressed this frame.
Example: `bool jumpValue = jumpAction.WasPressedThisFrame();`.

+[`Input.GetButtonUp`](https://docs.unity3d.com/ScriptReference/Input.GetButtonUp.html)
Example: `bool jump = Input.GetButtonUp("Jump");`

|Use [`WasReleasedThisFrame`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_WasReleasedThisFrame_) on the reference to the action to read whether the button was released this frame.
Example: `bool jumpValue = jumpAction.WasReleasedThisFrame();`.

+[`Input.GetAxisRaw`](https://docs.unity3d.com/ScriptReference/Input.GetAxisRaw.html)
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](Processors.md) associated with the action, you can use [`InputControl<>.ReadUnprocessedValue()`](../api/UnityEngine.InputSystem.InputControl-1.html#UnityEngine_InputSystem_InputControl_1_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. -``` -// Using KeyControl property directly. -Keyboard.current.spaceKey.wasPressedThisFrame -Keyboard.current.aKey.wasPressedThisFrame // etc. -// Using Key enum. -Keyboard.current[Key.Space].wasPressedThisFrame -// Using key name. -((KeyControl)Keyboard.current["space"]).wasPressedThisFrame -``` +### 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](./Workflow-Direct.md)) ->__Note__: The Input System identifies keys by physical layout, not according to the current language mapping of the keyboard. To query the name of the key according to the language mapping, use [`KeyControl.displayName`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_displayName). |Input Manager (Old)|Input System (New)| |--|--| -[`Input.GetKeyUp`](https://docs.unity3d.com/ScriptReference/Input.GetKeyUp.html)|Use [`ButtonControl.wasReleasedThisFrame`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html#UnityEngine_InputSystem_Controls_ButtonControl_wasReleasedThisFrame) on the corresponding key: +[`Input.GetKey`](https://docs.unity3d.com/ScriptReference/Input.GetKey.html)
Example: `Input.GetKey(KeyCode.JoystickButton0)`

|Use [`isPressed`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html#UnityEngine_InputSystem_Controls_ButtonControl_isPressed) on the corresponding Gamepad button.
Example: `InputSystem.GamePad.current.buttonNorth.isPressed`.
+[`Input.GetKeyDown`](https://docs.unity3d.com/ScriptReference/Input.GetKeyDown.html)
Example: `Input.GetKeyDown(KeyCode.JoystickButton0)`

|Use [`wasPressedThisFrame`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html#UnityEngine_InputSystem_Controls_ButtonControl_wasPressedThisFrame) on the corresponding Gamepad button.
Example: `InputSystem.GamePad.current.buttonNorth.WasPressedThisFrame`.
+[`Input.GetKeyUp`](https://docs.unity3d.com/ScriptReference/Input.GetKeyUp.html)
Example: `Input.GetKeyUp(KeyCode.JoystickButton0)`

|Use [`wasReleasedThisFrame`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html#UnityEngine_InputSystem_Controls_ButtonControl_wasReleasedThisFrame) on the corresponding Gamepad button.
Example: `InputSystem.GamePad.current.buttonNorth.wasReleasedThisFrame`.
+[`Input.GetJoystickNames`](https://docs.unity3d.com/ScriptReference/Input.GetJoystickNames.html)|There is no API that corresponds to this exactly, but there are examples of [how to read all connected devices here](Gamepad.html#discover-all-connected-devices). +[`Input.IsJoystickPreconfigured`](https://docs.unity3d.com/ScriptReference/Input.IsJoystickPreconfigured.html)|Not needed. Devices which derive from [`Gamepad`](../api/UnityEngine.InputSystem.Gamepad.html) always correctly implement the mapping of axes and buttons to the corresponding [`InputControl`](../api/UnityEngine.InputSystem.InputControl.html) members of the [`Gamepad`](../api/UnityEngine.InputSystem.Gamepad.html) class. [`Input.ResetInputAxes`](https://docs.unity3d.com/ScriptReference/Input.ResetInputAxes.html) -``` -// Using KeyControl property directly. -Keyboard.current.spaceKey.wasReleasedThisFrame -Keyboard.current.aKey.wasReleasedThisFrame // etc. -// Using Key enum. -Keyboard.current[Key.Space].wasReleasedThisFrame - -// Using key name. -((KeyControl)Keyboard.current["space"]).wasReleasedThisFrame -``` - ->__Note__: The Input System identifies keys by physical layout, not according to the current language mapping of the keyboard. To query the name of the key according to the language mapping, use [`KeyControl.displayName`](../api/UnityEngine.InputSystem.InputControl.html#UnityEngine_InputSystem_InputControl_displayName). +### Keyboard |Input Manager (Old)|Input System (New)| |--|--| -[`Input.GetMouseButton`](https://docs.unity3d.com/ScriptReference/Input.GetMouseButton.html)|Use [`ButtonControl.isPressed`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html#UnityEngine_InputSystem_Controls_ButtonControl_isPressed) on the corresponding mouse button: +[`Input.GetKey`](https://docs.unity3d.com/ScriptReference/Input.GetKey.html)
Example: `Input.GetKey(KeyCode.Space)`

|Use [`isPressed`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html#UnityEngine_InputSystem_Controls_ButtonControl_isPressed) on the corresponding key.
Example: `InputSystem.Keyboard.current.spaceKey.isPressed`

+[`Input.GetKeyDown`](https://docs.unity3d.com/ScriptReference/Input.GetKeyDown.html)
Example: `Input.GetKeyDown(KeyCode.Space)`

|Use [`wasPressedThisFrame`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html#UnityEngine_InputSystem_Controls_ButtonControl_wasPressedThisFrame) on the corresponding key.
Example: `InputSystem.Keyboard.current.spaceKey.wasPressedThisFrame`

+[`Input.GetKeyUp`](https://docs.unity3d.com/ScriptReference/Input.GetKeyUp.html)
Example: `Input.GetKeyUp(KeyCode.Space)`

|Use [`wasReleasedThisFrame`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html#UnityEngine_InputSystem_Controls_ButtonControl_wasReleasedThisFrame) on the corresponding key.
Example: `InputSystem.Keyboard.current.spaceKey.wasReleasedThisFrame`

+[`Input.anyKey`](https://docs.unity3d.com/ScriptReference/Input-anyKey.html)|Use [`onAnyButtonPress`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_onAnyButtonPress).
This also includes controller buttons as well as keyboard keys. +[`Input.anyKeyDown`](https://docs.unity3d.com/ScriptReference/Input-anyKeyDown.html)|Use [`Keyboard.current.anyKey.wasUpdatedThisFrame`](../api/UnityEngine.InputSystem.Keyboard.html#UnityEngine_InputSystem_Keyboard_anyKey) +[`Input.compositionCursorPos`](https://docs.unity3d.com/ScriptReference/Input-compositionCursorPos.html)|Use [`Keyboard.current.SetIMECursorPosition(myPosition)`](../api/UnityEngine.InputSystem.Keyboard.html#UnityEngine_InputSystem_Keyboard_SetIMECursorPosition_UnityEngine_Vector2_) +[`Input.compositionString`](https://docs.unity3d.com/ScriptReference/Input-compositionString.html)|Subscribe to the [`Keyboard.onIMECompositionChange`](../api/UnityEngine.InputSystem.Keyboard.html#UnityEngine_InputSystem_Keyboard_onIMECompositionChange). +[`Input.imeCompositionMode`](https://docs.unity3d.com/ScriptReference/Input-imeCompositionMode.html)|Use: [`Keyboard.current.SetIMEEnabled(true)`](../api/UnityEngine.InputSystem.Keyboard.html#UnityEngine_InputSystem_Keyboard_SetIMEEnabled_System_Boolean_)
Also see: [Keyboard text input documentation](Keyboard.html#ime). +[`Input.imeIsSelected`](https://docs.unity3d.com/ScriptReference/Input-imeIsSelected.html)|Use: [`Keyboard.current.imeSelected`](../api/UnityEngine.InputSystem.Keyboard.html#UnityEngine_InputSystem_Keyboard_imeSelected) +[`Input.inputString`](https://docs.unity3d.com/ScriptReference/Input-inputString.html)|Subscribe to the [`Keyboard.onTextInput`](../api/UnityEngine.InputSystem.Keyboard.html#UnityEngine_InputSystem_Keyboard_onTextInput) event:
`Keyboard.current.onTextInput += character => /* ... */;` -``` -Mouse.current.leftButton.isPressed -Mouse.current.rightButton.isPressed -Mouse.current.middleButton.isPressed - -// You can also go through all buttons on the mouse (does not allocate). -var controls = Mouse.current.allControls; -for (var i = 0; i < controls.Count; ++i) -{ - var button = controls[i] as ButtonControl; - if (button != null && button.isPressed) - /* ... */; -} - -// Or look up controls by name. -((ButtonControl)Mouse.current["leftButton"]).isPressed -``` +### Mouse |Input Manager (Old)|Input System (New)| |--|--| -[`Input.GetMouseButtonDown`](https://docs.unity3d.com/ScriptReference/Input.GetMouseButtonDown.html)|Use [`ButtonControl.wasPressedThisFrame`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html#UnityEngine_InputSystem_Controls_ButtonControl_wasPressedThisFrame) on the corresponding mouse button: +[`Input.GetMouseButton`](https://docs.unity3d.com/ScriptReference/Input.GetMouseButton.html)
Example: `Input.GetMouseButton(0)`|Use [`isPressed`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html#UnityEngine_InputSystem_Controls_ButtonControl_isPressed) on the corresponding mouse button.
Example: `InputSystem.Mouse.current.leftButton.isPressed` +[`Input.GetMouseButtonDown`](https://docs.unity3d.com/ScriptReference/Input.GetMouseButtonDown.html)
Example: `Input.GetMouseButtonDown(0)`|Use [`wasPressedThisFrame`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html#UnityEngine_InputSystem_Controls_ButtonControl_wasPressedThisFrame) on the corresponding mouse button.
Example: `InputSystem.Mouse.current.leftButton.wasPressedThisFrame` +[`Input.GetMouseButtonUp`](https://docs.unity3d.com/ScriptReference/Input.GetMouseButtonUp.html)
Example: `Input.GetMouseButtonUp(0)`|Use [`wasReleasedThisFrame`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html#UnityEngine_InputSystem_Controls_ButtonControl_wasReleasedThisFrame) on the corresponding mouse button.
Example: `InputSystem.Mouse.current.leftButton.wasReleasedThisFrame` +[`Input.mousePosition`](https://docs.unity3d.com/ScriptReference/Input-mousePosition.html)|Use [`Mouse.current.position.ReadValue()`](../api/UnityEngine.InputSystem.Mouse.html)
Example: `Vector2 position = Mouse.current.position.ReadValue();`
__Note__: Mouse simulation from touch isn't implemented yet. +[`Input.mousePresent`](https://docs.unity3d.com/ScriptReference/Input-mousePresent.html)|No corresponding API yet. + +### Touch and Pen -``` -Mouse.current.leftButton.wasPressedThisFrame -Mouse.current.rightButton.wasPressedThisFrame -Mouse.current.middleButton.wasPressedThisFrame -``` |Input Manager (Old)|Input System (New)| |--|--| -[`Input.GetMouseButtonUp`](https://docs.unity3d.com/ScriptReference/Input.GetMouseButtonUp.html)|Use [`ButtonControl.wasReleasedThisFrame`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html#UnityEngine_InputSystem_Controls_ButtonControl_wasReleasedThisFrame) on the corresponding mouse button: +[`Input.GetTouch`](https://docs.unity3d.com/ScriptReference/Input.GetTouch.html)
For example:
`Touch touch = Input.GetTouch(0);`
`Vector2 touchPos = touch.position;`|Use [`EnhancedTouch.Touch.activeTouches[i]`](../api/UnityEngine.InputSystem.EnhancedTouch.Touch.html#UnityEngine_InputSystem_EnhancedTouch_Touch_activeTouches)
Example: `Vector2 touchPos = EnhancedTouch.Touch.activeTouches[0].position;`
__Note__: Enable enhanced touch support first by calling [`EnhancedTouch.Enable()`](../api/UnityEngine.InputSystem.EnhancedTouch.EnhancedTouchSupport.html#UnityEngine_InputSystem_EnhancedTouch_EnhancedTouchSupport_Enable). +[`Input.multiTouchEnabled`](https://docs.unity3d.com/ScriptReference/Input-multiTouchEnabled.html)|No corresponding API yet. +[`Input.simulateMouseWithTouches`](https://docs.unity3d.com/ScriptReference/Input-multiTouchEnabled.html)|No corresponding API yet. +[`Input.stylusTouchSupported`](https://docs.unity3d.com/ScriptReference/Input-stylusTouchSupported.html)|No corresponding API yet. +[`Input.touchCount`](https://docs.unity3d.com/ScriptReference/Input-touchCount.html)|[`EnhancedTouch.Touch.activeTouches.Count`](../api/UnityEngine.InputSystem.EnhancedTouch.Touch.html#UnityEngine_InputSystem_EnhancedTouch_Touch_activeTouches)
__Note__: Enable enhanced touch support first by calling [`EnhancedTouchSupport.Enable()`](../api/UnityEngine.InputSystem.EnhancedTouch.EnhancedTouchSupport.html#UnityEngine_InputSystem_EnhancedTouch_EnhancedTouchSupport_Enable) +[`Input.touches`](https://docs.unity3d.com/ScriptReference/Input-touches.html)|[`EnhancedTouch.Touch.activeTouches`](../api/UnityEngine.InputSystem.EnhancedTouch.Touch.html#UnityEngine_InputSystem_EnhancedTouch_Touch_activeTouches)
__Note__: Enable enhanced touch support first by calling [`EnhancedTouch.Enable()`](../api/UnityEngine.InputSystem.EnhancedTouch.EnhancedTouchSupport.html#UnityEngine_InputSystem_EnhancedTouch_EnhancedTouchSupport_Enable) +[`Input.touchPressureSupported`](https://docs.unity3d.com/ScriptReference/Input-touchPressureSupported.html)|No corresponding API yet. +[`Input.touchSupported`](https://docs.unity3d.com/ScriptReference/Input-touchSupported.html)|[`Touchscreen.current != null`](../api/UnityEngine.InputSystem.Touchscreen.html#UnityEngine_InputSystem_Touchscreen_current) +[`Input.backButtonLeavesApp`](https://docs.unity3d.com/ScriptReference/Input-backButtonLeavesApp.html)|No corresponding API yet. +[`GetPenEvent`](https://docs.unity3d.com/ScriptReference/Input.GetPenEvent.html)
[`GetLastPenContactEvent`](https://docs.unity3d.com/ScriptReference/Input.GetLastPenContactEvent.html)
[`ResetPenEvents`](https://docs.unity3d.com/ScriptReference/Input.ResetPenEvents.html)
[`ClearLastPenContactEvent`](https://docs.unity3d.com/ScriptReference/Input.ClearLastPenContactEvent.html)|Use: [`Pen.current`](../api/UnityEngine.InputSystem.Pen.html#UnityEngine_InputSystem_Pen_current)
See the [Pen, tablet and stylus support](Pen.md) docs for more information. +
+ -``` -Mouse.current.leftButton.wasReleasedThisFrame -Mouse.current.rightButton.wasReleasedThisFrame -Mouse.current.middleButton.wasReleasedThisFrame -``` +Note: [`UnityEngine.TouchScreenKeyboard`](https://docs.unity3d.com/ScriptReference/TouchScreenKeyboard.html) 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.GetTouch`](https://docs.unity3d.com/ScriptReference/Input.GetTouch.html)|Use [`InputSystem.EnhancedTouch.Touch.activeTouches[i]`](../api/UnityEngine.InputSystem.EnhancedTouch.Touch.html#UnityEngine_InputSystem_EnhancedTouch_Touch_activeTouches)
__Note__: Enable enhanced touch support first by calling [`InputSystem.EnhancedTouch.Enable()`](../api/UnityEngine.InputSystem.EnhancedTouch.EnhancedTouchSupport.html#UnityEngine_InputSystem_EnhancedTouch_EnhancedTouchSupport_Enable). -[`Input.IsJoystickPreconfigured`](https://docs.unity3d.com/ScriptReference/Input.IsJoystickPreconfigured.html)|Not needed. Devices which derive from [`Gamepad`](../api/UnityEngine.InputSystem.Gamepad.html) always correctly implement the mapping of axes and buttons to the corresponding [`InputControl`](../api/UnityEngine.InputSystem.InputControl.html) members of the [`Gamepad`](../api/UnityEngine.InputSystem.Gamepad.html) class. [`Input.ResetInputAxes`](https://docs.unity3d.com/ScriptReference/Input.ResetInputAxes.html)|Not directly applicable. -[`UnityEngine.TouchScreenKeyboard`](https://docs.unity3d.com/ScriptReference/TouchScreenKeyboard.html)|No corresponding API yet. Use `TouchScreenKeyboard` for now. +[`Input.acceleration`](https://docs.unity3d.com/ScriptReference/Input-acceleration.html)|[`Accelerometer.current.acceleration.ReadValue()`](../api/UnityEngine.InputSystem.Accelerometer.html). +[`Input.accelerationEventCount`](https://docs.unity3d.com/ScriptReference/Input-accelerationEventCount.html)
[`Input.accelerationEvents`](https://docs.unity3d.com/ScriptReference/Input-accelerationEvents.html)|Acceleration events aren't made available separately from other input events. See the [accelerometer code sample on the Sensors page](Sensors.html#accelerometer). +[`Input.compass`](https://docs.unity3d.com/ScriptReference/Input-compass.html)|No corresponding API yet. +[`Input.compensateSensors`](https://docs.unity3d.com/ScriptReference/Input-compensateSensors.html)|[`InputSettings.compensateForScreenOrientation`](../api/UnityEngine.InputSystem.InputSettings.html#UnityEngine_InputSystem_InputSettings_compensateForScreenOrientation). +[`Input.deviceOrientation`](https://docs.unity3d.com/ScriptReference/Input-deviceOrientation.html)|No corresponding API yet. +[`Input.gyro`](https://docs.unity3d.com/ScriptReference/Input-gyro.html)|The `UnityEngine.Gyroscope` class is replaced by multiple separate sensor Devices in the new Input System:
[`Gyroscope`](../api/UnityEngine.InputSystem.Gyroscope.html) to measure angular velocity.
[`GravitySensor`](../api/UnityEngine.InputSystem.GravitySensor.html) to measure the direction of gravity.
[`AttitudeSensor`](../api/UnityEngine.InputSystem.AttitudeSensor.html) to measure the orientation of the device.
[`Accelerometer`](../api/UnityEngine.InputSystem.Accelerometer.html) to measure the total acceleration applied to the device.
[`LinearAccelerationSensor`](../api/UnityEngine.InputSystem.LinearAccelerationSensor.html) to measure acceleration applied to the device, compensating for gravity. +[`Input.gyro.attitude`](https://docs.unity3d.com/ScriptReference/Gyroscope-attitude.html)|[`AttitudeSensor.current.orientation.ReadValue()`](../api/UnityEngine.InputSystem.AttitudeSensor.html). +[`Input.gyro.enabled`](https://docs.unity3d.com/ScriptReference/Gyroscope-enabled.html)|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`](../api/UnityEngine.InputSystem.Gyroscope.html) with other sensors in the sample as needed. See the notes for `Input.gyro` above for details. +[`Input.gyro.gravity`](https://docs.unity3d.com/ScriptReference/Gyroscope-gravity.html)|[`GravitySensor.current.gravity.ReadValue()`](../api/UnityEngine.InputSystem.GravitySensor.html) +[`Input.gyro.rotationRate`](https://docs.unity3d.com/ScriptReference/Gyroscope-rotationRate.html)|[`Gyroscope.current.angularVelocity.ReadValue()`](../api/UnityEngine.InputSystem.Gyroscope.html). +[`Input.gyro.rotationRateUnbiased`](https://docs.unity3d.com/ScriptReference/Gyroscope-rotationRateUnbiased.html)|No corresponding API yet. +[`Input.gyro.updateInterval`](https://docs.unity3d.com/ScriptReference/Gyroscope-updateInterval.html)|[`Sensor.samplingFrequency`](../api/UnityEngine.InputSystem.Sensor.html#UnityEngine_InputSystem_Sensor_samplingFrequency)
Example:
`Gyroscope.current.samplingFrequency = 1.0f / updateInterval;`

__Notes__:
[`samplingFrequency`](../api/UnityEngine.InputSystem.Sensor.html#UnityEngine_InputSystem_Sensor_samplingFrequency) is in Hz, not in seconds as [`updateInterval`](https://docs.unity3d.com/ScriptReference/Gyroscope-updateInterval.html), so you need to divide 1 by the value.

The new Input System replaces `UnityEngine.Gyroscope` with multiple separate sensor devices. Substitute [`Gyroscope`](../api/UnityEngine.InputSystem.Gyroscope.html) with other sensors in the sample as needed. See the notes for `Input.gyro` above for details. +[`Input.gyro.userAcceleration`](https://docs.unity3d.com/ScriptReference/Gyroscope-userAcceleration.html)|[`LinearAccelerationSensor.current.acceleration.acceleration.ReadValue()`](../api/UnityEngine.InputSystem.LinearAccelerationSensor.html) +[`Input.location`](https://docs.unity3d.com/ScriptReference/Input-location.html)|No corresponding API yet. +[`Input.GetAccelerationEvent`](https://docs.unity3d.com/ScriptReference/Input.GetAccelerationEvent.html)|See notes for `Input.accelerationEvents` above. diff --git a/Packages/com.unity.inputsystem/Documentation~/Sensors.md b/Packages/com.unity.inputsystem/Documentation~/Sensors.md index f869a4d671..23a628c606 100644 --- a/Packages/com.unity.inputsystem/Documentation~/Sensors.md +++ b/Packages/com.unity.inputsystem/Documentation~/Sensors.md @@ -3,19 +3,19 @@ uid: input-system-sensors --- # Sensor support -* [Sampling Frequency](#sampling-frequency) -* [Accelerometer](#accelerometer) -* [Gyroscope](#gyroscope) -* [GravitySensor](#gravitysensor) -* [AttitudeSensor](#attitudesensor) -* [LinearAccelerationSensor](#linearaccelerationsensor) -* [MagneticFieldSensor](#magneticfieldsensor) -* [LightSensor](#lightsensor) -* [PressureSensor](#pressuresensor) -* [ProximitySensor](#proximitysensor) -* [HumiditySensor](#humiditysensor) -* [AmbientTemperatureSensor](#ambienttemperaturesensor) -* [StepCounter](#stepcounter) +- [Sampling frequency](#sampling-frequency) +- [`Accelerometer`](#accelerometer) +- [`Gyroscope`](#gyroscope) +- [`GravitySensor`](#gravitysensor) +- [`AttitudeSensor`](#attitudesensor) +- [`LinearAccelerationSensor`](#linearaccelerationsensor) +- [`MagneticFieldSensor`](#magneticfieldsensor) +- [`LightSensor`](#lightsensor) +- [`PressureSensor`](#pressuresensor) +- [`ProximitySensor`](#proximitysensor) +- [`HumiditySensor`](#humiditysensor) +- [`AmbientTemperatureSensor`](#ambienttemperaturesensor) +- [`StepCounter`](#stepcounter) Sensors are [`InputDevices`](Devices.md) that measure environmental characteristics of the device that the content is running on. Unity currently supports sensors on iOS and Android. Android supports a wider range of sensors than iOS. @@ -84,6 +84,28 @@ Gyroscope.current.samplingFrequency = 16; Use the accelerometer to measure the acceleration of a device. This is useful to control content by moving a device around. It reports the acceleration measured on a device both due to moving the device around, and due to gravity pulling the device down. You can use `GravitySensor` and `LinearAccelerationSensor` to get separate values for these. Values are affected by the [__Compensate Orientation__](Settings.md#compensate-orientation) setting. + The following code traces all input events on the [`Accelerometer.current`](../api/UnityEngine.InputSystem.Accelerometer.html) device. +```CSharp + private InputEventTrace trace; + + void StartTrace() + { + InputSystem.EnableDevice(Accelerometer.current); + + trace = new InputEventTrace(Accelerometer.current); + trace.Enable(); + } + + void Update() + { + foreach (var e in trace) + { + //... + } + trace.Clear(); + } +``` + ## [`Gyroscope`](../api/UnityEngine.InputSystem.Gyroscope.html) Use the gyroscope to measure the angular velocity of a device. This is useful to control content by rotating a device. Values are affected by the [__Compensate Orientation__](Settings.md#compensate-orientation) setting. diff --git a/Packages/com.unity.inputsystem/Documentation~/TableOfContents.md b/Packages/com.unity.inputsystem/Documentation~/TableOfContents.md index b292f2c1b0..305e0dfa9f 100644 --- a/Packages/com.unity.inputsystem/Documentation~/TableOfContents.md +++ b/Packages/com.unity.inputsystem/Documentation~/TableOfContents.md @@ -43,6 +43,6 @@ * [Input testing](Testing.md) * [How do I...?](HowDoI.md) * [Architecture](Architecture.md) -* [Migrating from the old input system](Migration.md) +* [Migrating from the old Input Manager](Migration.md) * [Contributing](Contributing.md) * [Known Limitations](KnownLimitations.md) diff --git a/Packages/com.unity.inputsystem/InputSystem/Controls/ButtonControl.cs b/Packages/com.unity.inputsystem/InputSystem/Controls/ButtonControl.cs index 92c67c588e..fe28ffe352 100644 --- a/Packages/com.unity.inputsystem/InputSystem/Controls/ButtonControl.cs +++ b/Packages/com.unity.inputsystem/InputSystem/Controls/ButtonControl.cs @@ -100,9 +100,55 @@ public ButtonControl() /// /// True if button is currently pressed. /// - /// A button is considered press if it's value is equal to or greater + /// A button is considered pressed if its value is equal to or greater /// than its button press threshold (). /// + /// + /// You can use this to read whether specific keys are currently pressed by using isPressed on keys, as shown in the following examples: + /// + /// + /// + /// Note: The Input System identifies keys by physical layout, not according to the current language mapping of the keyboard. To query the name of the key according to the language mapping, use . + /// + /// You can also use this to read mouse buttons, as shown in the following examples: + /// + /// + /// + /// You can also check through all numbered buttons on the mouse: (this example does not cause allocations) + /// + /// + /// + /// Or you can look up controls by name, like this: + /// + /// + /// + /// /// /// /// @@ -177,6 +223,19 @@ private void BeginTestingForFramePresses(bool currentlyPressed, bool pressedLast /// } /// /// + /// _Note_: The Input System identifies keys by physical layout, not according to the current language mapping of the keyboard. To query the name of the key according to the language mapping, use . + /// + /// You can also use this property to read mouse buttons. For example: + /// + /// + /// + /// Mouse.current.leftButton.wasPressedThisFrame + /// Mouse.current.rightButton.wasPressedThisFrame + /// Mouse.current.middleButton.wasPressedThisFrame + /// + /// + /// + /// /// public bool wasPressedThisFrame { @@ -200,6 +259,29 @@ public bool wasPressedThisFrame } } + /// + /// Whether the press ended this frame. + /// + /// True if the current press of the button ended this frame. + /// + /// _Note_: The Input System identifies keys by physical layout, not according to the current language mapping of the keyboard. To query the name of the key according to the language mapping, use . + /// + /// + /// An example showing the use of this property on a gamepad button and a keyboard key: + /// + /// using UnityEngine; + /// using UnityEngine.InputSystem; + /// + /// public class ExampleScript : MonoBehaviour + /// { + /// void Update() + /// { + /// bool buttonPressed = Gamepad.current.aButton.wasReleasedThisFrame; + /// bool spaceKeyPressed = Keyboard.current.spaceKey.wasReleasedThisFrame; + /// } + /// } + /// + /// public bool wasReleasedThisFrame { get @@ -214,7 +296,7 @@ public bool wasReleasedThisFrame return device.wasUpdatedThisFrame && !currentlyPressed && pressedLastFrame; } -#if UNITY_EDITOR + #if UNITY_EDITOR if (InputUpdate.s_LatestUpdateType.IsEditorUpdate()) return InputUpdate.s_UpdateStepCount == m_UpdateCountLastReleasedEditor; #endif diff --git a/Packages/com.unity.inputsystem/InputSystem/Devices/Keyboard.cs b/Packages/com.unity.inputsystem/InputSystem/Devices/Keyboard.cs index e400589a7d..20b8e0ecb3 100644 --- a/Packages/com.unity.inputsystem/InputSystem/Devices/Keyboard.cs +++ b/Packages/com.unity.inputsystem/InputSystem/Devices/Keyboard.cs @@ -972,6 +972,16 @@ public event Action onTextInput /// /// See for turning IME on/off /// + /// + /// To subscribe to the onIMECompositionChange event, use the following sample code: + /// + /// var compositionString = ""; + /// Keyboard.current.onIMECompositionChange += composition => + /// { + /// compositionString = composition.ToString(); + /// }; + /// + /// public event Action onIMECompositionChange { add