From c99388db85f8972b2a46fbf8e143817ffc01555f Mon Sep 17 00:00:00 2001 From: Siobhan Date: Thu, 23 Jan 2025 14:54:36 +0000 Subject: [PATCH 01/15] Phase 1 of content model re-org Split content onto separate pages to apply content model. Removed old placeholder files. --- .../Documentation~/TableOfContents.md | 28 +++++++- .../Documentation~/access-ui-input-module.md | 13 ++++ .../Documentation~/compatibility.md | 1 - .../configure-multiplayer-ui-input.md | 14 ++++ .../configure-ui-input-action-map.md | 23 +++++++ .../configure-virtual-mouse-input.md | 22 +++++++ .../configuring-multiplayer-input.md | 11 ++++ .../create-custom-on-screen-control.md | 30 ++++++++- .../create-on-screen-button-control.md | 11 ++++ .../Documentation~/create-on-screen-button.md | 1 - .../create-on-screen-stick-control.md | 32 +++++++++ .../Documentation~/create-on-screen-stick.md | 1 - .../Documentation~/default-ui-actions.md | 1 - .../distinguish-between-ui-game-input.md | 1 - .../distinguishing-ui-game-input.md | 35 ++++++++++ ...e-ambiguities-for-naviagtion-type-input.md | 1 - ...ndle-ambiguities-for-pointer-type-input.md | 1 - .../Documentation~/immediate-mode-gui.md | 1 - .../introduction-multiplayer-ui-input.md | 11 ++++ .../introduction-on-screen-controls.md | 20 ++++++ .../introduction-ui-input-module.md | 12 ++++ .../introduction-virtual-mouse.md | 11 ++++ .../Documentation~/multiplayer-ui-input.md | 8 +++ .../Documentation~/multiplayer-ui.md | 1 - .../notes-about-ui-input-module.md | 1 - .../Documentation~/on-screen-controls.md | 14 +++- .../Documentation~/send-input-to-ui.md | 1 - .../Documentation~/set-up-ui-actions.md | 1 - .../set-up-virtual-mouse-input.md | 1 - .../supported-ui-input-types-navigation.md | 12 ++++ .../supported-ui-input-types-pointer.md | 34 ++++++++++ .../supported-ui-input-types-tracked.md | 15 +++++ ...upported-ui-input-types-ui-input-module.md | 66 +++++++++++++++++++ .../supported-ui-input-types.md | 9 +++ .../Documentation~/supported-ui-systems.md | 9 +++ .../Documentation~/the-ui-input-module.md | 1 - .../Documentation~/ui-action-map-reference.md | 15 +++++ .../ui-input-module-reference.md | 14 ++++ .../Documentation~/ui-input-types.md | 1 - .../Documentation~/ui-input.md | 13 ++++ .../Documentation~/ui-support.md | 19 ------ .../understand-ui-compatibility.md | 62 +++++++++++++++++ .../use-imgui-alongside-input-system.md | 11 ++++ .../use-navigation-type-input-with-ui.md | 1 - .../use-pointer-type-navigation-with-ui.md | 1 - .../use-tracket-type-input-with-ui.md | 1 - .../Documentation~/using-ui-input-module.md | 12 ++++ .../Documentation~/virtual-mouse-cursor.md | 1 - .../virtual-mouse-ui-cursor-control.md | 13 ++++ 49 files changed, 576 insertions(+), 42 deletions(-) create mode 100644 Packages/com.unity.inputsystem/Documentation~/access-ui-input-module.md delete mode 100644 Packages/com.unity.inputsystem/Documentation~/compatibility.md create mode 100644 Packages/com.unity.inputsystem/Documentation~/configure-multiplayer-ui-input.md create mode 100644 Packages/com.unity.inputsystem/Documentation~/configure-ui-input-action-map.md create mode 100644 Packages/com.unity.inputsystem/Documentation~/configure-virtual-mouse-input.md create mode 100644 Packages/com.unity.inputsystem/Documentation~/configuring-multiplayer-input.md create mode 100644 Packages/com.unity.inputsystem/Documentation~/create-on-screen-button-control.md delete mode 100644 Packages/com.unity.inputsystem/Documentation~/create-on-screen-button.md create mode 100644 Packages/com.unity.inputsystem/Documentation~/create-on-screen-stick-control.md delete mode 100644 Packages/com.unity.inputsystem/Documentation~/create-on-screen-stick.md delete mode 100644 Packages/com.unity.inputsystem/Documentation~/default-ui-actions.md delete mode 100644 Packages/com.unity.inputsystem/Documentation~/distinguish-between-ui-game-input.md create mode 100644 Packages/com.unity.inputsystem/Documentation~/distinguishing-ui-game-input.md delete mode 100644 Packages/com.unity.inputsystem/Documentation~/handle-ambiguities-for-naviagtion-type-input.md delete mode 100644 Packages/com.unity.inputsystem/Documentation~/handle-ambiguities-for-pointer-type-input.md delete mode 100644 Packages/com.unity.inputsystem/Documentation~/immediate-mode-gui.md create mode 100644 Packages/com.unity.inputsystem/Documentation~/introduction-multiplayer-ui-input.md create mode 100644 Packages/com.unity.inputsystem/Documentation~/introduction-on-screen-controls.md create mode 100644 Packages/com.unity.inputsystem/Documentation~/introduction-ui-input-module.md create mode 100644 Packages/com.unity.inputsystem/Documentation~/introduction-virtual-mouse.md create mode 100644 Packages/com.unity.inputsystem/Documentation~/multiplayer-ui-input.md delete mode 100644 Packages/com.unity.inputsystem/Documentation~/multiplayer-ui.md delete mode 100644 Packages/com.unity.inputsystem/Documentation~/notes-about-ui-input-module.md delete mode 100644 Packages/com.unity.inputsystem/Documentation~/send-input-to-ui.md delete mode 100644 Packages/com.unity.inputsystem/Documentation~/set-up-ui-actions.md delete mode 100644 Packages/com.unity.inputsystem/Documentation~/set-up-virtual-mouse-input.md create mode 100644 Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-navigation.md create mode 100644 Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-pointer.md create mode 100644 Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-tracked.md create mode 100644 Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-ui-input-module.md create mode 100644 Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types.md create mode 100644 Packages/com.unity.inputsystem/Documentation~/supported-ui-systems.md delete mode 100644 Packages/com.unity.inputsystem/Documentation~/the-ui-input-module.md create mode 100644 Packages/com.unity.inputsystem/Documentation~/ui-action-map-reference.md create mode 100644 Packages/com.unity.inputsystem/Documentation~/ui-input-module-reference.md delete mode 100644 Packages/com.unity.inputsystem/Documentation~/ui-input-types.md create mode 100644 Packages/com.unity.inputsystem/Documentation~/ui-input.md delete mode 100644 Packages/com.unity.inputsystem/Documentation~/ui-support.md create mode 100644 Packages/com.unity.inputsystem/Documentation~/understand-ui-compatibility.md create mode 100644 Packages/com.unity.inputsystem/Documentation~/use-imgui-alongside-input-system.md delete mode 100644 Packages/com.unity.inputsystem/Documentation~/use-navigation-type-input-with-ui.md delete mode 100644 Packages/com.unity.inputsystem/Documentation~/use-pointer-type-navigation-with-ui.md delete mode 100644 Packages/com.unity.inputsystem/Documentation~/use-tracket-type-input-with-ui.md create mode 100644 Packages/com.unity.inputsystem/Documentation~/using-ui-input-module.md delete mode 100644 Packages/com.unity.inputsystem/Documentation~/virtual-mouse-cursor.md create mode 100644 Packages/com.unity.inputsystem/Documentation~/virtual-mouse-ui-cursor-control.md diff --git a/Packages/com.unity.inputsystem/Documentation~/TableOfContents.md b/Packages/com.unity.inputsystem/Documentation~/TableOfContents.md index 4af1bb1d6f..0e54c41b00 100644 --- a/Packages/com.unity.inputsystem/Documentation~/TableOfContents.md +++ b/Packages/com.unity.inputsystem/Documentation~/TableOfContents.md @@ -69,8 +69,32 @@ * [Joystick support](Joystick.md) * [Sensor support](Sensors.md) * [HID support](HID.md) -* [UI support](UISupport.md) - * [On-screen Controls](OnScreen.md) +* [Input for user interfaces](ui-input.md) + * [Supported UI systems](supported-ui-systems.md) + * [Understand UI system compatibility](understand-ui-compatibility.md) + * [Using UI Input Module for UI support](using-ui-input-module.md) + * [Introduction to the UI Input Module](introduction-ui-input-module.md) + * [Supported input types in the UI Input Module](supported-ui-input-types.md) + * [Pointer input UI support](supported-ui-input-types-pointer.md) + * [Navigation input UI support](supported-ui-input-types-navigation.md) + * [Tracked input UI support](supported-ui-input-types-tracked.md) + * [Access the UI Input Module](access-ui-input-module.md) + * [UI Input Module component reference](ui-input-module-reference.md) + * [Use IMGUI alongside the Input System package](use-imgui-alongside-input-system.md) + * [Configure UI Input Actions](configure-ui-input-action-map.md) + * [UI Action Map reference](ui-action-map-reference.md) + * [Distinguishing between UI input and game input](distinguishing-ui-game-input.md) + * [Virtual Mouse for UI cursor control](virtual-mouse-ui-cursor-control.md) + * [Introduction to Virtual Mouse for UI cursor control](introduction-virtual-mouse.md) + * [Configure a Virtual Mouse for UI input](configure-virtual-mouse-input.md) + * [Multiplayer UI input](multiplayer-ui-input.md) + * [Introduction to multiplayer UI input](introduction-multiplayer-ui-input.md) + * [Configure multiplayer UI input](configure-multiplayer-ui-input.md) + * [On-screen Controls](on-screen-controls.md) + * [Introduction to on-screen Controls](introduction-on-screen-controls.md) + * [Create an on-screen button Control](create-on-screen-button-control.md) + * [Create an on-screen stick Control](create-on-screen-stick-control.md) + * [Create a custom on-screen Control](create-custom-on-screen-control.md) * [Editor Features](EditorFeatures.md) * [Using Input in the Editor](UseInEditor.md) * [Debugging](debugging.md) diff --git a/Packages/com.unity.inputsystem/Documentation~/access-ui-input-module.md b/Packages/com.unity.inputsystem/Documentation~/access-ui-input-module.md new file mode 100644 index 0000000000..5d8fa65242 --- /dev/null +++ b/Packages/com.unity.inputsystem/Documentation~/access-ui-input-module.md @@ -0,0 +1,13 @@ +# Access the UI Input Module component + +The UI Input Module is a component that passes input actions from the Input System to the UI in your scene. + +You must add it to a GameObject in your scene in order for the UI to receive input from the Input System. To do this: + +1. Create a new empty GameObject +2. Click [**Add Component**](https://docs.unity3d.com/Manual/UsingComponents.html) in the Inspector +3. In the search field displayed, type `Input System UI Input Module` +4. Select **Input System UI Input Module** to add it to the GameObject. + + +![InputSystemUIInputModule](Images/InputSystemUIInputModuleAdd.png) \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/compatibility.md b/Packages/com.unity.inputsystem/Documentation~/compatibility.md deleted file mode 100644 index 6176c80a70..0000000000 --- a/Packages/com.unity.inputsystem/Documentation~/compatibility.md +++ /dev/null @@ -1 +0,0 @@ -# Compatibility diff --git a/Packages/com.unity.inputsystem/Documentation~/configure-multiplayer-ui-input.md b/Packages/com.unity.inputsystem/Documentation~/configure-multiplayer-ui-input.md new file mode 100644 index 0000000000..3c2f9c6585 --- /dev/null +++ b/Packages/com.unity.inputsystem/Documentation~/configure-multiplayer-ui-input.md @@ -0,0 +1,14 @@ +# Configure multiplayer UI input + +To enable multiplayer UI input: + +1. Replace the project’s [Event System](https://docs.unity3d.com/Manual/script-EventSystem.html) component with the Input System's [Multiplayer Event System](../api/UnityEngine.InputSystem.UI.MultiplayerEventSystem.html) component. + + +For information on how to automatically configure the player's UI Input Module to use Actions from the [Player Input](player-input-component.md) component, refer to documentation on [Player Input: UI Input](player-input-component.md#ui-input) to learn how. + +To define mouse UI input behaviour for a Multiplayer Event System: + +1. Create an empty GameObject. +1. In the Multiplayer Event System, set **Player Root** to the new GameObject. +1. For any UI selectables that you want the Multiplayer Event System to interact with, move their GameObjects in the hierarchy so that they are child GameObjects of the **Player Root** GameObject. diff --git a/Packages/com.unity.inputsystem/Documentation~/configure-ui-input-action-map.md b/Packages/com.unity.inputsystem/Documentation~/configure-ui-input-action-map.md new file mode 100644 index 0000000000..ff60748cf7 --- /dev/null +++ b/Packages/com.unity.inputsystem/Documentation~/configure-ui-input-action-map.md @@ -0,0 +1,23 @@ +# Configure the UI Input Action Map + +The default [Project-Wide Actions asset](./about-project-wide-actions.md) comes with a "**UI**" Action Map, which contains all the actions required for UI interaction. To configure the bindings for these actions, use the [Actions Editor](./ActionsEditor.md). + +To open the Actions Editor: + +1. Go to **Project Settings > Input System Package** +1. In the **Action Maps** column, select **UI**. + +![ProjectSettingsInputActionsUIActionMap](Images/ProjectSettingsInputActionsUIActionMap.png) + + +The default [Project-Wide Actions asset](./about-project-wide-actions.md) comes with all the required actions to be compatible with UI Toolkit and Unity UI. + +You can modify, add, or remove bindings to the named actions in the UI action map to suit your project, however in order to remain compatible with UI Toolkit, the name of the action map ("**UI**"), the names of the actions it contains, and their respective **Action Types** must remain the same. + +To see the specific actions and types that are expected by the [UI Input Module](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html) class, refer to the [UI Action Map reference](ui-action-map-reference). + +You can also reset the UI action map to its default bindings by selecting **Reset** from the **More (⋮)** menu, at the top right of the actions editor window. However, this resets both the 'Player' and 'UI' action maps to their default bindings. + +To restore functionality to runtime `OnGUI` methods, you can change the **Active Input Handling** setting to "**Both**". Doing this means that Unity processes the input twice which could introduce a small performance impact. + +This only affects runtime (play mode) `OnGUI` methods. Editor GUI code is unaffected and continues to receive input events. \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/configure-virtual-mouse-input.md b/Packages/com.unity.inputsystem/Documentation~/configure-virtual-mouse-input.md new file mode 100644 index 0000000000..9424dd142f --- /dev/null +++ b/Packages/com.unity.inputsystem/Documentation~/configure-virtual-mouse-input.md @@ -0,0 +1,22 @@ +# Configure a Virtual Mouse for UI input +To configure the Virtual Mouse component with the Unity UI system: + +1. Create a UI GameObject with an **Image** component. This GameObject is the mouse pointer. It can help to rename it "_Pointer_". +2. Parent the pointer GameObject as a child of your **Canvas** GameObject that contains the UI which the cursor should operate on. +3. Set the anchor position of the GameObject's `RectTransform` to the bottom left. +4. Ensure your pointer GameObject is the last child of the Canvas so that the cursor draws on top of everything else. +5. Add a **Virtual Mouse** component to the GameObject. +6. Drag the **Image** component of the pointer GameObject into the **Cursor Graphic** field of the Virtual Mouse component. +7. Drag the **Rect Transform** component of the pointer GameObject to the **Cursor Transform** field of the Virtual Mouse component. + +> **Note**: +> Do not set up gamepads and joysticks for [navigation input](#navigation-type-input) while using the Virtual Mouse component. If, for example, the Virtual Mouse component is configured to receive input from gamepads, and `Move`, `Submit`, and `Cancel` on the UI Input Module are also linked to the gamepad, then the UI receives input from the gamepad on two channels, and triggers the input twice. + +If you want the virtual mouse to control the system mouse cursor: +Set [Cursor Mode](../api/UnityEngine.InputSystem.UI.VirtualMouseInput.html#UnityEngine_InputSystem_UI_VirtualMouseInput_cursorMode) to **Hardware Cursor If Available**. In this mode, the **Cursor Graphic** is hidden when a system mouse is present and you use [Mouse.WarpCursorPosition](../api/UnityEngine.InputSystem.Mouse.html#UnityEngine_InputSystem_Mouse_WarpCursorPosition_UnityEngine_Vector2_) to move the system mouse cursor instead of the software cursor. The transform linked through **Cursor Transform** is not updated in that case. + + +To configure the input to drive the virtual mouse, do one of the following: + +* Add bindings on the various actions (such as **Stick Action**). +* Enable **Use Reference** and link existing actions from an Input Actions asset. \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/configuring-multiplayer-input.md b/Packages/com.unity.inputsystem/Documentation~/configuring-multiplayer-input.md new file mode 100644 index 0000000000..68331ddf09 --- /dev/null +++ b/Packages/com.unity.inputsystem/Documentation~/configuring-multiplayer-input.md @@ -0,0 +1,11 @@ +# Configuring multiplayer UI input + +The Input System can handle multiple separate UI instances on the screen controlled separately by different [Input Bindings](ActionBindings.md). This is useful if you want to have multiple local players share a single screen with different controllers, so that every player can control their own UI instance. + +To allow this, you need to replace the [Event System](https://docs.unity3d.com/Manual/script-EventSystem.html) component from Unity with the Input System's [Multiplayer Event System](../api/UnityEngine.InputSystem.UI.MultiplayerEventSystem.html) component. + +![MultiplayerEventSystem](Images/MultiplayerEventSystem.png) + +You can have multiple Multiplayer Event Systems active in the Scene at the same time. This means you can have multiple players, each with their own [UI Input Module](LINK) and Multiplayer Event System components, and each player can have their own set of Actions driving their own UI instance. If you are using the [Player Input](player-input-component.md) component, you can also set it to automatically configure the player's UI Input Module to use the player's Actions. See the documentation on [Player Input](player-input-component.md#ui-input) to learn how. + +The properties of the Multiplayer Event System component are identical to those from the Event System component. However, the Multiplayer Event System component also has a [Player Root](../api/UnityEngine.InputSystem.UI.MultiplayerEventSystem.html#UnityEngine_InputSystem_UI_MultiplayerEventSystem_playerRoot) property, which you can set to a GameObject that contains all the UI [selectables](https://docs.unity3d.com/Manual/script-Selectable.html) this event system should handle in its hierarchy. Mouse input that this event system processes then ignores any UI selectables which are not on any GameObject in the Hierarchy under [Player Root](../api/UnityEngine.InputSystem.UI.MultiplayerEventSystem.html#UnityEngine_InputSystem_UI_MultiplayerEventSystem_playerRoot). \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/create-custom-on-screen-control.md b/Packages/com.unity.inputsystem/Documentation~/create-custom-on-screen-control.md index 0abaa297a8..1200e9e8cb 100644 --- a/Packages/com.unity.inputsystem/Documentation~/create-custom-on-screen-control.md +++ b/Packages/com.unity.inputsystem/Documentation~/create-custom-on-screen-control.md @@ -1 +1,29 @@ -# Create a custom on-screen control +## Create a custom on-screen Control + +You can add support for new types of [Input Controls](Controls.md) by extending [`OnScreenControl`](../api/UnityEngine.InputSystem.OnScreen.OnScreenControl.html). An easy example to follow is [`OnScreenButton`](../api/UnityEngine.InputSystem.OnScreen.OnScreenButton.html). + +```CSharp + [AddComponentMenu("Input/On-Screen Button")] + public class OnScreenButton : OnScreenControl, IPointerDownHandler, IPointerUpHandler + { + public void OnPointerUp(PointerEventData data) + { + SendValueToControl(0.0f); + } + + public void OnPointerDown(PointerEventData data) + { + SendValueToControl(1.0f); + } + + [InputControl(layout = "Button")] + [SerializeField] + private string m_ControlPath; + + protected override string controlPathInternal + { + get => m_ControlPath; + set => m_ControlPath = value; + } + } +``` \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/create-on-screen-button-control.md b/Packages/com.unity.inputsystem/Documentation~/create-on-screen-button-control.md new file mode 100644 index 0000000000..1a907bb7cc --- /dev/null +++ b/Packages/com.unity.inputsystem/Documentation~/create-on-screen-button-control.md @@ -0,0 +1,11 @@ +# Create an on-screen button control + +To create an on-screen button: + +1. Add a UI `Button` object. +2. Add the [`OnScreenButton`](../api/UnityEngine.InputSystem.OnScreen.OnScreenButton.html) component to it. +3. Set the [`Control Path`](../api/UnityEngine.InputSystem.OnScreen.OnScreenControl.html#UnityEngine_InputSystem_OnScreen_OnScreenControl_controlPath) to refer to a [`ButtonControl`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html) (for example, `/buttonSouth`). The type of device referenced by the control path determines the type of virtual device created by the component. + +![OnScreenButton](Images/OnScreenButton.png) + +The [`OnScreenButton`](../api/UnityEngine.InputSystem.OnScreen.OnScreenButton.html) component requires the target Control to be a `Button` Control. [`OnScreenButton`](../api/UnityEngine.InputSystem.OnScreen.OnScreenButton.html) sets the target Control value to 1 when it receives a pointer-down (`IPointerDownHandler.OnPointerDown`) event, or 0 when it receives a pointer-up (`IPointerUpHandler.OnPointerUp`) event. \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/create-on-screen-button.md b/Packages/com.unity.inputsystem/Documentation~/create-on-screen-button.md deleted file mode 100644 index 514b837c85..0000000000 --- a/Packages/com.unity.inputsystem/Documentation~/create-on-screen-button.md +++ /dev/null @@ -1 +0,0 @@ -# Create an on-screen button diff --git a/Packages/com.unity.inputsystem/Documentation~/create-on-screen-stick-control.md b/Packages/com.unity.inputsystem/Documentation~/create-on-screen-stick-control.md new file mode 100644 index 0000000000..6a294944bb --- /dev/null +++ b/Packages/com.unity.inputsystem/Documentation~/create-on-screen-stick-control.md @@ -0,0 +1,32 @@ +# Create an on-screen stick Control + +To create an on-screen stick: + +1. Create a UI `Image` object. +2. Add the [`OnScreenStick`](../api/UnityEngine.InputSystem.OnScreen.OnScreenStick.html) component to it. +3. Set the [`Control Path`](../api/UnityEngine.InputSystem.OnScreen.OnScreenControl.html#UnityEngine_InputSystem_OnScreen_OnScreenControl_controlPath) to refer to a [`Vector2Control`](../api/UnityEngine.InputSystem.Controls.Vector2Control.html) (for example, `/leftStick`). The type of device referenced by the control path determines the type of virtual device created by the component. + +![OnScreenStick](Images/OnScreenStick.png) + +The [`OnScreenStick`](../api/UnityEngine.InputSystem.OnScreen.OnScreenStick.html) component requires the target Control to be a `Vector2` Control. [`OnScreenStick`](../api/UnityEngine.InputSystem.OnScreen.OnScreenStick.html) starts the movement of the stick Control when it receives a pointer-down (`IPointerDownHandler.OnPointerDown`) event, and stops it when it receives a pointer-up (`IPointerUpHandler.OnPointerUp`) event. + +In-between, the stick moves according to the pointer being dragged (`IDragHandler.OnDrag`) within a box centered on the pointer-down screen point, and with an edge length defined in the component's __Movement Range__ property. A movement range of 50, for example, means that the stick's on-screen area is 25 pixels up, down, left, and right of the pointer-down point on screen. + +If you want to be notified when the user starts and/or stops touching the on-screen stick, implement `IPointerDownHandler` and/or `IPointerUpHandler` on a component and add it to the stick `GameObject`. + +### Isolated mode + +The [`OnScreenStick`](../api/UnityEngine.InputSystem.OnScreen.OnScreenStick.html) simulates input events from the device specified in the [`OnScreenControl.control`](../api/UnityEngine.InputSystem.OnScreen.OnScreenControl.html#UnityEngine_InputSystem_OnScreen_OnScreenControl_control) property. To the Input System itself, these are normal events and can cause the paired device to change in games and applications where dynamic device switching is used, for example when the [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) component is used with the [`PlayerInput.neverAutoSwitchControlSchemes`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_neverAutoSwitchControlSchemes)) propety set to false. As the stick is dragged around, the paired device will alternate between the device that owns the pointer (mouse, touch, pen etc) and the device from the control path, which can result in jittery movement of the on-screen stick. + +Use Isolated Input Actions to fix this. This mode uses a local set of Input Action instances to drive interaction with the stick, and not the actions defined in the UI. The downside of this mode is that pointer actions will be duplicated in both the on-screen stick component and any Input Action Assets being used to drive the UI. Note that if a set of bindings is not specified for the Pointer Down Action and Pointer Move Actions, the following defaults will be used: + +* Pointer Down Action + - `/leftButton` + - `/tip` + - `/touch*/press` + - `/trigger` + +* Pointer Move Action + - `/position` + - `/position` + - `/touch*/position` \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/create-on-screen-stick.md b/Packages/com.unity.inputsystem/Documentation~/create-on-screen-stick.md deleted file mode 100644 index 3844e2cb1e..0000000000 --- a/Packages/com.unity.inputsystem/Documentation~/create-on-screen-stick.md +++ /dev/null @@ -1 +0,0 @@ -# Create an on-screen stick diff --git a/Packages/com.unity.inputsystem/Documentation~/default-ui-actions.md b/Packages/com.unity.inputsystem/Documentation~/default-ui-actions.md deleted file mode 100644 index 2962ebadcf..0000000000 --- a/Packages/com.unity.inputsystem/Documentation~/default-ui-actions.md +++ /dev/null @@ -1 +0,0 @@ -# Default UI Actions diff --git a/Packages/com.unity.inputsystem/Documentation~/distinguish-between-ui-game-input.md b/Packages/com.unity.inputsystem/Documentation~/distinguish-between-ui-game-input.md deleted file mode 100644 index 5fca76ba6d..0000000000 --- a/Packages/com.unity.inputsystem/Documentation~/distinguish-between-ui-game-input.md +++ /dev/null @@ -1 +0,0 @@ -# Distinguish between UI and Game Input diff --git a/Packages/com.unity.inputsystem/Documentation~/distinguishing-ui-game-input.md b/Packages/com.unity.inputsystem/Documentation~/distinguishing-ui-game-input.md new file mode 100644 index 0000000000..89a9920218 --- /dev/null +++ b/Packages/com.unity.inputsystem/Documentation~/distinguishing-ui-game-input.md @@ -0,0 +1,35 @@ +# Distinguishing between UI and game input + +UI in Unity receives input through the same mechanisms as the input for the rest of your game or app. There is no automatic mechanism that implicitly ensures that if a certain input (such as a mouse click) is consumed by the UI, it is not also received by your gameplay code. + +This can create ambiguities between, for example, code that responds to [`UI.Button.onClick`](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/api/UnityEngine.UI.Button.html#UnityEngine_UI_Button_onClick) and code that responds to [`InputAction.performed`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_performed) of an Action bound to `/leftButton`. + +Whether such ambiguities exist depends on *how* UIs are used. For example, you can avoid ambiguities by implementing your UI in one of the following ways: + +* Perform all interaction through UI elements. Render a 2D/3D scene in the background, but perform all interaction through UI events (including those such as 'background' clicks on the `Canvas`). +* Place UI over a 2D/3D scene, but don’t let the user directly interact with the UI. +* Place UI over a 2D/3D scene, but create a clear "mode" switch that determines whether interaction applies to the UI or the scene. For example, a first-person game on desktop might employ a [cursor lock](https://docs.unity3d.com/ScriptReference/Cursor-lockState.html) which directs input to the game when it is engaged, and to the UI when it is not engaged. + +There are specific ambiguities that can arise for [pointer input](#pointer-type-input) and [navigation input](#navigation-type-input). + +>[!NOTE] +>The Input System package includes a sample project called "**UI vs Game Input**". The sample demonstrates how to deal with ambiguities between inputs for UI and inputs for the game. + +## Handling pointer input ambiguities + +Input from pointers (mice, touchscreens, pens) can be ambiguous depending on whether or not the pointer is over a UI element when initiating an interaction. For example, if there is a button on screen, then clicking on the button may lead to a different outcome than clicking outside of the button and within the game scene. + +If all pointer input is handled via UI events, no ambiguities arise as the UI will implicitly route input to the respective receiver. If, however, input within the UI is handled via UI events and input in the game is handled via [Actions](./actions.md), pointer input will by default lead to *both* being triggered. + +The easiest way to resolve such ambiguities is to respond to in-game actions by [polling](RespondingToActions.md#polling-actions) from inside [`MonoBehaviour.Update`](https://docs.unity3d.com/ScriptReference/MonoBehaviour.Update.html) methods and using [`EventSystem.IsPointerOverGameObject`](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/api/UnityEngine.EventSystems.EventSystem.html?q=ispointerovergameobject#UnityEngine_EventSystems_EventSystem_IsPointerOverGameObject) to find out whether the pointer is over UI or not. Another way is to use [`EventSystem.RaycastAll`](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/api/UnityEngine.EventSystems.EventSystem.html?q=ispointerovergameobj#UnityEngine_EventSystems_EventSystem_RaycastAll_UnityEngine_EventSystems_PointerEventData_System_Collections_Generic_List_UnityEngine_EventSystems_RaycastResult__) to determine if the pointer is currently over UI. + +>[!NOTE] +>Calling [`EventSystem.IsPointerOverGameObject`](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/api/UnityEngine.EventSystems.EventSystem.html?q=ispointerovergameobject#UnityEngine_EventSystems_EventSystem_IsPointerOverGameObject) from within [`InputAction`](../api/UnityEngine.InputSystem.InputAction.html) callbacks such as [`InputAction.performed`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_performed) lead to a warning. The UI updates separately after input processing, so UI state corresponds to that of the last frame/update while input is being processed. + +## Handling navigation input ambiguities + +Ambiguities for navigation-type Devices such as gamepads and joysticks (but also keyboards) cannot arise the same way that it does for pointers. Instead, your application has to decide explicitly whether to use input for the UI's `Move`, `Submit`, and `Cancel` inputs or for the game. This can be done by either splitting control on a Device or by having an explicit mode switch. + +Splitting input on a Device is done by simply using certain controls for operating the UI while using others to operate the game. For example, you could use the d-pad on gamepads to operate UI selection while using the sticks for in-game character control. This setup requires adjusting the bindings used by the UI Actions accordingly. + +An explicit mode switch is implemented by temporarily switching to UI control while suspending in-game Actions. For example, the left trigger on the gamepad could bring up an item selection wheel which then puts the game in a mode where the sticks are controlling UI selection, the A button confirms the selection, and the B button closes the item selection wheel. No ambiguities arise as in-game actions will not respond while the UI is in the "foreground". \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/handle-ambiguities-for-naviagtion-type-input.md b/Packages/com.unity.inputsystem/Documentation~/handle-ambiguities-for-naviagtion-type-input.md deleted file mode 100644 index 3efc5b5540..0000000000 --- a/Packages/com.unity.inputsystem/Documentation~/handle-ambiguities-for-naviagtion-type-input.md +++ /dev/null @@ -1 +0,0 @@ -# Handle ambiguities for naviagtion-type input diff --git a/Packages/com.unity.inputsystem/Documentation~/handle-ambiguities-for-pointer-type-input.md b/Packages/com.unity.inputsystem/Documentation~/handle-ambiguities-for-pointer-type-input.md deleted file mode 100644 index 6da54fa3d9..0000000000 --- a/Packages/com.unity.inputsystem/Documentation~/handle-ambiguities-for-pointer-type-input.md +++ /dev/null @@ -1 +0,0 @@ -# Handle ambiguities for pointer-type input diff --git a/Packages/com.unity.inputsystem/Documentation~/immediate-mode-gui.md b/Packages/com.unity.inputsystem/Documentation~/immediate-mode-gui.md deleted file mode 100644 index a24686ab01..0000000000 --- a/Packages/com.unity.inputsystem/Documentation~/immediate-mode-gui.md +++ /dev/null @@ -1 +0,0 @@ -# Immediate Mode GUI diff --git a/Packages/com.unity.inputsystem/Documentation~/introduction-multiplayer-ui-input.md b/Packages/com.unity.inputsystem/Documentation~/introduction-multiplayer-ui-input.md new file mode 100644 index 0000000000..cd84c69053 --- /dev/null +++ b/Packages/com.unity.inputsystem/Documentation~/introduction-multiplayer-ui-input.md @@ -0,0 +1,11 @@ +# Introduction to multiplayer UI input + +The Input System can handle multiple separate UI instances on the screen controlled separately by different [Input Bindings](ActionBindings.md). This is useful if you want to have multiple local players share a single screen with different controllers, so that every player can control their own UI instance. + +To implement multiplayer UI, the Input System uses the Multiplayer Event System. + +![MultiplayerEventSystem](Images/MultiplayerEventSystem.png) + +You can have multiple Multiplayer Event Systems active in the Scene at the same time. This means you can have multiple players, each with their own [UI Input Module](using-ui-input-module.md) and Multiplayer Event System components, and each player can have their own set of Actions driving their own UI instance. + +The properties of the Multiplayer Event System component are mostly identical to those in the [Event System](https://docs.unity3d.com/Manual/script-EventSystem.html) component. However, the Multiplayer Event System component also has a [Player Root](../api/UnityEngine.InputSystem.UI.MultiplayerEventSystem.html#UnityEngine_InputSystem_UI_MultiplayerEventSystem_playerRoot) property, which defines a parent GameObject for UI [selectables](https://docs.unity3d.com/Manual/script-Selectable.html). When each player has a Multiplayer Event System with a **Player** Root assigned, UI navigation input for each player is limited to UI selectables that are child GameObjects of the Player Root. \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/introduction-on-screen-controls.md b/Packages/com.unity.inputsystem/Documentation~/introduction-on-screen-controls.md new file mode 100644 index 0000000000..be4151cf18 --- /dev/null +++ b/Packages/com.unity.inputsystem/Documentation~/introduction-on-screen-controls.md @@ -0,0 +1,20 @@ +--- +uid: input-system-on-screen +--- +# Introduction to on-screen Controls + +You can use on-screen Controls to simulate Input Devices with UI widgets that the user interacts with on the screen. The most prominent example is the use of stick and button widgets on touchscreens to emulate a joystick or gamepad. + +There are currently two Control types implemented out of the box: [buttons](#on-screen-buttons) and [sticks](#on-screen-sticks). You can implement custom Controls by extending the base [`OnScreenControl`](../api/UnityEngine.InputSystem.OnScreen.OnScreenControl.html) class (see documentation on [writing custom on screen Controls](#writing-custom-on-screen-controls) to learn more). + +>__Note__: On-screen Controls don't have a predefined visual representation. It's up to you to set up the visual aspect of a Control (for example, by adding a sprite or UI component to the GameObject). On-screen Controls take care of the interaction logic and of setting up and generating input from interactions. + +Each on-screen Control uses a [Control path](Controls.md#control-paths) to reference the Control that it should report input as. For example, the following on-screen button reports input as the right shoulder button of a gamepad: + +![OnScreenButton](Images/OnScreenButton.png) + +The collection of on-screen Controls present in a Scene forms one or more [Input Devices](Devices.md). The Input System creates one Input Device for each distinct type of Device the Controls reference. For example, if one on-screen button references `/buttonSouth` and another on-screen button references `/a`, the Input System creates both a `Gamepad` and a `Keyboard`. This happens automatically when the components are enabled. When disabled, the Input System automatically removes the Devices again. + +To query the Control (and, implicitly, the Device) that an on-screen Control feeds into, you can use the [`OnScreenControl.control`](../api/UnityEngine.InputSystem.OnScreen.OnScreenControl.html#UnityEngine_InputSystem_OnScreen_OnScreenControl_control) property. + +>__Note__: This design allows you to use on-screen Controls to create input for arbitrary Input Devices, in addition to joysticks and gamepads. \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/introduction-ui-input-module.md b/Packages/com.unity.inputsystem/Documentation~/introduction-ui-input-module.md new file mode 100644 index 0000000000..d20eb55066 --- /dev/null +++ b/Packages/com.unity.inputsystem/Documentation~/introduction-ui-input-module.md @@ -0,0 +1,12 @@ +# Introduction to the UI Input Module + +The UI Input Module passes actions from your Input System to your UI, as well as some other UI-related input settings. When working with Unity UI (uGUI), or when using UI Toolkit in versions of Unity prior to Unity 2023.2, you must use the **UI Input Module**. + +You don't need to specify to the UI Input Module which UI system you are using. Input support for both [Unity UI](https://docs.unity3d.com/Manual/com.unity.ugui.html) and [UI Toolkit](https://docs.unity3d.com/Manual/UIElements.html) is based on the same [Event System](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/manual/EventSystem.html) and [BaseInputModule](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/manual/InputModules.html) subsystem. + +The UI Input module is implemented in the class [`InputSystemUIInputModule`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html). + +## Input priority + +If you have an instance of the [Input System UI Input Module](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html) component in your scene, the settings on that component takes priority and are used instead of the UI settings in your project-wide actions. The UI Action Map is enabled, along with the default Action Map specified on any UI Input Module component in the scene. + diff --git a/Packages/com.unity.inputsystem/Documentation~/introduction-virtual-mouse.md b/Packages/com.unity.inputsystem/Documentation~/introduction-virtual-mouse.md new file mode 100644 index 0000000000..eae5cb5623 --- /dev/null +++ b/Packages/com.unity.inputsystem/Documentation~/introduction-virtual-mouse.md @@ -0,0 +1,11 @@ +# Introduction to Virtual Mouse for UI cursor control + +If your application uses gamepads and joysticks as an input, you can use [navigation input actions](supported-ui-input-types-ui-input-module.md#navigation-input) to operate the UI. However, it usually involves extra work to make the UI work well with navigation. + +An alternative way to operate the UI is to allow gamepads and joysticks to drive the cursor from a virtual mouse. The Input System package provides a **Virtual Mouse** component for this purpose. + +At runtime, the component adds a virtual [Mouse](../api/UnityEngine.InputSystem.Mouse.html) device which the [InputSystemUIInputModule](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html) component picks up. The controls of the `Mouse` are fed input based on the actions configured on the [VirtualMouseInput](../api/UnityEngine.InputSystem.UI.VirtualMouseInput.html) component. + +Note that the resulting [Mouse](../api/UnityEngine.InputSystem.Mouse.html) input is visible in all code that picks up input from the mouse device. You can therefore use the component for mouse simulation elsewhere, not just with [InputSystemUIInputModule](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html). + +To see an example of the Virtual Mouse in a project, see the [Gamepad Mouse Cursor sample](Installation.md#installing-samples) included with the Input System package. \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/multiplayer-ui-input.md b/Packages/com.unity.inputsystem/Documentation~/multiplayer-ui-input.md new file mode 100644 index 0000000000..f1a398d953 --- /dev/null +++ b/Packages/com.unity.inputsystem/Documentation~/multiplayer-ui-input.md @@ -0,0 +1,8 @@ +# Multiplayer UI input + +Configure multiple UI instances, so that multiple players can share a single screen and individually interact with the UI. + +|**Topic**|**Description**| +|--------|-----------| +|[Introduction to multiplayer UI input](introduction-multiplayer-ui-input.md)|Assign players a Multiplayer Event System so that each player has their own UI input scheme.| +|[Configure multiplayer UI input](configure-multiplayer-ui-input.md)|Configure the Multiplayer Event System component and set up automatic input detection.| \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/multiplayer-ui.md b/Packages/com.unity.inputsystem/Documentation~/multiplayer-ui.md deleted file mode 100644 index aeb3a45dae..0000000000 --- a/Packages/com.unity.inputsystem/Documentation~/multiplayer-ui.md +++ /dev/null @@ -1 +0,0 @@ -# Multiplayer UI diff --git a/Packages/com.unity.inputsystem/Documentation~/notes-about-ui-input-module.md b/Packages/com.unity.inputsystem/Documentation~/notes-about-ui-input-module.md deleted file mode 100644 index bc5644a3bc..0000000000 --- a/Packages/com.unity.inputsystem/Documentation~/notes-about-ui-input-module.md +++ /dev/null @@ -1 +0,0 @@ -# Notes about UI Input Module diff --git a/Packages/com.unity.inputsystem/Documentation~/on-screen-controls.md b/Packages/com.unity.inputsystem/Documentation~/on-screen-controls.md index 09648d96cb..94e50a06ca 100644 --- a/Packages/com.unity.inputsystem/Documentation~/on-screen-controls.md +++ b/Packages/com.unity.inputsystem/Documentation~/on-screen-controls.md @@ -1 +1,13 @@ -# On-screen Controls +--- +uid: input-system-on-screen +--- +# On-screen Controls + +Simulate input devices with UI widgets that the user interacts with on the screen. + +|**Topic**|**Description**| +|--------|-----------| +|[Introduction to on-screen Controls](introduction-on-screen-controls.md)| Simulate buttons, sticks, and custom inputs with on-screen Controls. | +|[Create an on-screen button Control](create-on-screen-button-control.md)| Create and configure simulated on-screen button Controls.| +|[Create an on-screen stick Control](create-on-screen-stick-control.md)| Create and configure simulated on-screen stick Controls.| +|[Create a custom on-screen Control](create-custom-on-screen-control.md)| Create and configure custom simulated on-screen Controls.| \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/send-input-to-ui.md b/Packages/com.unity.inputsystem/Documentation~/send-input-to-ui.md deleted file mode 100644 index fd18c85b77..0000000000 --- a/Packages/com.unity.inputsystem/Documentation~/send-input-to-ui.md +++ /dev/null @@ -1 +0,0 @@ -# Send input to your UI diff --git a/Packages/com.unity.inputsystem/Documentation~/set-up-ui-actions.md b/Packages/com.unity.inputsystem/Documentation~/set-up-ui-actions.md deleted file mode 100644 index 9cca55386c..0000000000 --- a/Packages/com.unity.inputsystem/Documentation~/set-up-ui-actions.md +++ /dev/null @@ -1 +0,0 @@ -# Set up UI Actions diff --git a/Packages/com.unity.inputsystem/Documentation~/set-up-virtual-mouse-input.md b/Packages/com.unity.inputsystem/Documentation~/set-up-virtual-mouse-input.md deleted file mode 100644 index 0f7e170757..0000000000 --- a/Packages/com.unity.inputsystem/Documentation~/set-up-virtual-mouse-input.md +++ /dev/null @@ -1 +0,0 @@ -# Set up virtual mouse input diff --git a/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-navigation.md b/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-navigation.md new file mode 100644 index 0000000000..958311517d --- /dev/null +++ b/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-navigation.md @@ -0,0 +1,12 @@ +## Navigation input UI support + +Navigation-type input controls the current selection based on motion read from the [move](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_move) action. Additionally, input from +[submit](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_submit) will trigger `ISubmitHandler` on the currently selected object and +[cancel](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_cancel) will trigger `ICancelHandler` on it. + +Unlike with [pointer-type](#pointer-type-input), where multiple pointer inputs may exist concurrently (think two touches or left- and right-hand tracked input), navigation-type input does not have multiple concurrent instances. In other words, only a single [move](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_move) vector and a single [submit](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_submit) and [cancel](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_cancel) input will be processed by the UI module each frame. However, these inputs need not necessarily come from one single Device always. Arbitrary many inputs can be bound to the respective actions. + +While, [move](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_move) should be set to [PassThrough](../api/UnityEngine.InputSystem.InputActionType.html#UnityEngine_InputSystem_InputActionType_PassThrough) Action type, it is important that [submit](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_submit) and +[cancel](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_cancel) be set to the [Button](../api/UnityEngine.InputSystem.InputActionType.html#UnityEngine_InputSystem_InputActionType_Button) Action type. + +Navigation input is non-positional, that is, unlike with pointer-type input, there is no screen position associated with these actions. Rather, navigation actions always operate on the current selection. \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-pointer.md b/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-pointer.md new file mode 100644 index 0000000000..4634b95138 --- /dev/null +++ b/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-pointer.md @@ -0,0 +1,34 @@ +# Pointer input UI support + +To the UI, a pointer is a position from which clicks and scrolls can be triggered to interact with UI elements at the pointer's position. Pointer-type input is sourced from [point](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_point), [leftClick](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_leftClick), [rightClick](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_rightClick), [middleClick](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_middleClick), and [scrollWheel](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_scrollWheel). + +The UI input module does not have an association between pointers and cursors. In general, the UI is oblivious to whether a cursor exists for a particular pointer. However, for mouse and pen input, the UI input module will respect [Cusor.lockState](https://docs.unity3d.com/ScriptReference/Cursor-lockState.html) and pin the pointer position at `(-1,-1)` whenever the cursor is locked. This behavior can be changed through the [Cursor Lock Behavior](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_cursorLockBehavior) property of the [InputSystemUIInputModule](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html). + +Multiple pointer Devices can feed input into a single UI input module. Also, in the case of [Touchscreen](../api/UnityEngine.InputSystem.Touchscreen.html), a single Device can have the ability to have multiple concurrent pointers (each finger contact is one pointer). + +Because multiple pointer Devices can feed into the same set of Actions, it is important to set the [action type](./RespondingToActions.md#action-types) to [PassThrough](../api/UnityEngine.InputSystem.InputActionType.html#UnityEngine_InputSystem_InputActionType_PassThrough). This ensures that no filtering is applied to input on these actions and that instead every input is relayed as is. + +From the perspective of [InputSystemUIInputModule](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html), each [InputDevice](../api/UnityEngine.InputSystem.InputDevice.html) that has one or more controls bound to one of the pointer-type actions is considered a unique pointer. Also, for each [Touchscreen](../api/UnityEngine.InputSystem.Touchscreen.html) devices, each separate [TouchControl](../api/UnityEngine.InputSystem.Controls.TouchControl.html) that has one or more of its controls bound to the those actions is considered its own unique pointer as well. Each pointer receives a unique [pointerId](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/api/UnityEngine.EventSystems.PointerEventData.html#UnityEngine_EventSystems_PointerEventData_pointerId) which generally corresponds to the [deviceId](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_deviceId) of the pointer. However, for touch, this will be a combination of [deviceId](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_deviceId) and [touchId](../api/UnityEngine.InputSystem.Controls.TouchControl.html#UnityEngine_InputSystem_Controls_TouchControl_touchId). Use [ExtendedPointerEventData.touchId](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html#UnityEngine_InputSystem_UI_ExtendedPointerEventData_touchId) to find the ID for a touch event. + +To influence how the input module deals with concurrent input from multiple pointers, use the UI Input Module’s [**Pointer Behavior**](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_pointerBehavior) setting. + +If you bind a device to a pointer-type action such as [Left Click](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_leftClick) without also binding it to [Point](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_point), the UI input module will recognize the device as not being able to point and try to route its input into that of another pointer. For example, if you bind [Left Click](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_leftClick) to the `Space` key and [Point](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_point) to the position of the mouse, then pressing the space bar will result in a left click at the current position of the mouse. + +For pointer-type input (as well as for [tracked-type input](#tracked-type-input)), [InputSystemUIInputModule](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html) will send [ExtendedPointerEventData](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html) instances which are an extended version of the base `PointerEventData`. These events contain additional data such as the [device](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html#UnityEngine_InputSystem_UI_ExtendedPointerEventData_device) and [pointer type](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html#UnityEngine_InputSystem_UI_ExtendedPointerEventData_pointerType) which the event has been generated from. + +## Pointer behavior + +The UI Module's [Pointer Behavior](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_pointerBehavior) property defines how to deal with multiple [pointers](LINK) feeding input into the UI. + +### Unify mouse and pen input but separate touch and track input +[Single Mouse or Pen But Multi Touch And Track](../api/UnityEngine.InputSystem.UI.UIPointerBehavior.html#UnityEngine_InputSystem_UI_UIPointerBehavior_SingleMouseOrPenButMultiTouchAndTrack) behaves like [Single Unified Pointer](../api/UnityEngine.InputSystem.UI.UIPointerBehavior.html#UnityEngine_InputSystem_UI_UIPointerBehavior_SingleUnifiedPointer) for all input that is not classified as touch or tracked input, and behaves like [All Pointers As Is](../api/UnityEngine.InputSystem.UI.UIPointerBehavior.html#UnityEngine_InputSystem_UI_UIPointerBehavior_AllPointersAsIs) for tracked and touch input. + +If concurrent input is received on a [Mouse](../api/UnityEngine.InputSystem.Mouse.html) and [`Pen`](../api/UnityEngine.InputSystem.Pen.html), for example, the input of both is fed into the same UI pointer instance. The position input of one will overwrite the position of the other. + +When input is received from touch or tracked devices, the single unified pointer for mice and pens is removed, including [IPointerExit](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/api/UnityEngine.EventSystems.IPointerExitHandler.html) events being sent in case the mouse/pen cursor is currently hovering over objects. This is the default behavior. + +### Unify all pointer inputs +[Single Unified Pointer](../api/UnityEngine.InputSystem.UI.UIPointerBehavior.html#UnityEngine_InputSystem_UI_UIPointerBehavior_SingleUnifiedPointer) unifies all pointer input so that there is only ever a single pointer. This includes touch and tracked input. This means, for example, that regardless of how many devices feed input into [Point](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_point), only the last input in a frame takes effect and becomes the current UI pointer's position. + +### Treat all pointers as separate +[All Pointers As Is](../api/UnityEngine.InputSystem.UI.UIPointerBehavior.html#UnityEngine_InputSystem_UI_UIPointerBehavior_AllPointersAsIs) treats each input as separate and individual. Any device, including touch and tracked devices that feed input pointer-type actions, is its own pointer (or multiple pointers for touch input). This might mean that there are multiple pointers in the UI, and several objects might be pointed at at the same time. diff --git a/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-tracked.md b/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-tracked.md new file mode 100644 index 0000000000..6779f9faa8 --- /dev/null +++ b/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-tracked.md @@ -0,0 +1,15 @@ +# Tracked input UI support + +Input from [tracked devices](../api/UnityEngine.InputSystem.TrackedDevice.html) such as [XR controllers](../api/UnityEngine.InputSystem.XR.XRController.html) and [HMDs](../api/UnityEngine.InputSystem.XR.XRHMD.html) essentially behaves like [pointer-type input](#pointer-type-input). The main difference is that the world-space device position and orientation sourced from [trackedDevicePosition](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_trackedDevicePosition) and [trackedDeviceOrientation](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_trackedDeviceOrientation) is translated into a screen-space position via raycasting. + + +> **Important:** +>Because multiple tracked Devices can feed into the same set of Actions, it is important to set the [action type](./RespondingToActions.md#action-types) to [PassThrough](../api/UnityEngine.InputSystem.InputActionType.html#UnityEngine_InputSystem_InputActionType_PassThrough). This ensures that no filtering is applied to input on these actions and that instead every input is relayed as is. + +For this raycasting to work, you need to add [TrackedDeviceRaycaster](../api/UnityEngine.InputSystem.UI.TrackedDeviceRaycaster.html) to the `GameObject` that has the UI's `Canvas` component. This `GameObject` will usually have a `GraphicRaycaster` component which, however, only works for 2D screen-space raycasting. You can put [TrackedDeviceRaycaster](../api/UnityEngine.InputSystem.UI.TrackedDeviceRaycaster.html) alongside `GraphicRaycaster` and both can be enabled at the same time without advserse effect. + +![TrackedDeviceRayster Add Component](Images/TrackedDeviceRaycasterComponentMenu.png) + +![TrackedDeviceRayster Properties](Images/TrackedDeviceRaycaster.png) + +Clicks on tracked devices do not differ from other [pointer-type input](#pointer-type-input). Therefore, actions such as [Left Click](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_leftClick) work for tracked devices just like they work for other pointers. \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-ui-input-module.md b/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-ui-input-module.md new file mode 100644 index 0000000000..0f9028a0b7 --- /dev/null +++ b/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-ui-input-module.md @@ -0,0 +1,66 @@ +# Supported input types in the UI Input Module + +The UI Input Module supports three types of input: + +- [Pointer input](#pointer-input) +- [Navigation input](#navigation-input) +- [Tracked input](#tracked-input) + +For each input type, the UI Input Module sources and combines input from a specific set of Actions. + + + +## Pointer input +To the UI, a pointer is a position from which clicks and scrolls can be triggered to interact with UI elements at the pointer's position. Pointer-type input is sourced from [point](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_point), [leftClick](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_leftClick), [rightClick](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_rightClick), [middleClick](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_middleClick), and [scrollWheel](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_scrollWheel). + + +The UI input module does not have an association between pointers and cursors. In general, the UI is oblivious to whether a cursor exists for a particular pointer. However, for mouse and pen input, the UI input module will respect [Cusor.lockState](https://docs.unity3d.com/ScriptReference/Cursor-lockState.html) and pin the pointer position at `(-1,-1)` whenever the cursor is locked. This behavior can be changed through the [Cursor Lock Behavior](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_cursorLockBehavior) property of the [InputSystemUIInputModule](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html). + + +Multiple pointer Devices can feed input into a single UI input module. Also, in the case of [Touchscreen](../api/UnityEngine.InputSystem.Touchscreen.html), a single Device can have the ability to have multiple concurrent pointers (each finger contact is one pointer). + + +Because multiple pointer Devices can feed into the same set of Actions, it is important to set the [action type](./RespondingToActions.md#action-types) to [PassThrough](../api/UnityEngine.InputSystem.InputActionType.html#UnityEngine_InputSystem_InputActionType_PassThrough). This ensures that no filtering is applied to input on these actions and that instead every input is relayed as is. + + +From the perspective of [InputSystemUIInputModule](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html), each [InputDevice](../api/UnityEngine.InputSystem.InputDevice.html) that has one or more controls bound to one of the pointer-type actions is considered a unique pointer. Also, for each [Touchscreen](../api/UnityEngine.InputSystem.Touchscreen.html) devices, each separate [TouchControl](../api/UnityEngine.InputSystem.Controls.TouchControl.html) that has one or more of its controls bound to the those actions is considered its own unique pointer as well. Each pointer receives a unique [pointerId](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/api/UnityEngine.EventSystems.PointerEventData.html#UnityEngine_EventSystems_PointerEventData_pointerId) which generally corresponds to the [deviceId](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_deviceId) of the pointer. However, for touch, this will be a combination of [deviceId](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_deviceId) and [touchId](../api/UnityEngine.InputSystem.Controls.TouchControl.html#UnityEngine_InputSystem_Controls_TouchControl_touchId). Use [ExtendedPointerEventData.touchId](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html#UnityEngine_InputSystem_UI_ExtendedPointerEventData_touchId) to find the ID for a touch event. + +To influence how the input module deals with concurrent input from multiple pointers, use the UI Input Module’s [**Pointer Behavior**](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_pointerBehavior) setting. + +If you bind a device to a pointer-type action such as [Left Click](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_leftClick) without also binding it to [Point](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_point), the UI input module will recognize the device as not being able to point and try to route its input into that of another pointer. For example, if you bind [Left Click](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_leftClick) to the `Space` key and [Point](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_point) to the position of the mouse, then pressing the space bar will result in a left click at the current position of the mouse. + +For pointer-type input (as well as for [tracked-type input](#tracked-type-input)), [InputSystemUIInputModule](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html) will send [ExtendedPointerEventData](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html) instances which are an extended version of the base `PointerEventData`. These events contain additional data such as the [device](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html#UnityEngine_InputSystem_UI_ExtendedPointerEventData_device) and [pointer type](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html#UnityEngine_InputSystem_UI_ExtendedPointerEventData_pointerType) which the event has been generated from. + + + +## Navigation input + +Navigation-type input controls the current selection based on motion read from the [move](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_move) action. Additionally, input from +[submit](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_submit) will trigger `ISubmitHandler` on the currently selected object and +[cancel](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_cancel) will trigger `ICancelHandler` on it. + +Unlike with [pointer-type](#pointer-type-input), where multiple pointer inputs may exist concurrently (think two touches or left- and right-hand tracked input), navigation-type input does not have multiple concurrent instances. In other words, only a single [move](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_move) vector and a single [submit](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_submit) and [cancel](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_cancel) input will be processed by the UI module each frame. However, these inputs need not necessarily come from one single Device always. Arbitrary many inputs can be bound to the respective actions. + +While, [move](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_move) should be set to [PassThrough](../api/UnityEngine.InputSystem.InputActionType.html#UnityEngine_InputSystem_InputActionType_PassThrough) Action type, it is important that [submit](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_submit) and +[cancel](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_cancel) be set to the [Button](../api/UnityEngine.InputSystem.InputActionType.html#UnityEngine_InputSystem_InputActionType_Button) Action type. + +Navigation input is non-positional, that is, unlike with pointer-type input, there is no screen position associcated with these actions. Rather, navigation actions always operate on the current selection. + + + + +## Tracked input + +Input from [tracked devices](../api/UnityEngine.InputSystem.TrackedDevice.html) such as [XR controllers](../api/UnityEngine.InputSystem.XR.XRController.html) and [HMDs](../api/UnityEngine.InputSystem.XR.XRHMD.html) essentially behaves like [pointer-type input](#pointer-type-input). The main difference is that the world-space device position and orientation sourced from [trackedDevicePosition](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_trackedDevicePosition) and [trackedDeviceOrientation](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_trackedDeviceOrientation) is translated into a screen-space position via raycasting. + + +> **Important:** +>Because multiple tracked Devices can feed into the same set of Actions, it is important to set the [action type](./RespondingToActions.md#action-types) to [PassThrough](../api/UnityEngine.InputSystem.InputActionType.html#UnityEngine_InputSystem_InputActionType_PassThrough). This ensures that no filtering is applied to input on these actions and that instead every input is relayed as is. + +For this raycasting to work, you need to add [TrackedDeviceRaycaster](../api/UnityEngine.InputSystem.UI.TrackedDeviceRaycaster.html) to the `GameObject` that has the UI's `Canvas` component. This `GameObject` will usually have a `GraphicRaycaster` component which, however, only works for 2D screen-space raycasting. You can put [TrackedDeviceRaycaster](../api/UnityEngine.InputSystem.UI.TrackedDeviceRaycaster.html) alongside `GraphicRaycaster` and both can be enabled at the same time without advserse effect. + +![TrackedDeviceRayster Add Component](Images/TrackedDeviceRaycasterComponentMenu.png) + +![TrackedDeviceRayster Properties](Images/TrackedDeviceRaycaster.png) + +Clicks on tracked devices do not differ from other [pointer-type input](#pointer-type-input). Therefore, actions such as [Left Click](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_leftClick) work for tracked devices just like they work for other pointers. \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types.md b/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types.md new file mode 100644 index 0000000000..a8f0233c95 --- /dev/null +++ b/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types.md @@ -0,0 +1,9 @@ +# Supported input types in the UI Input Module + +The UI Input Module supports three types of input Action: pointer, navigation, and tracked. For each input type, the UI Input Module sources and combines input from a specific set of Actions. + +|**Topic**|**Description**| +|--------|-----------| +|[Pointer input UI support](supported-ui-input-types-pointer.md)| Configure pointer-type Actions, such as clicking, tapping, and scrolling.| +|[Navigation input UI support](supported-ui-input-types-navigation.md)| Configure navigation-type Actions, such as the `move` Action.| +|[Tracked input UI support](supported-ui-input-types-tracked.md)|Configure input from tracked devices, such as XR controllers and HMDs.| \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/supported-ui-systems.md b/Packages/com.unity.inputsystem/Documentation~/supported-ui-systems.md new file mode 100644 index 0000000000..9be1013c6b --- /dev/null +++ b/Packages/com.unity.inputsystem/Documentation~/supported-ui-systems.md @@ -0,0 +1,9 @@ +# Supported UI systems + +Understand the support and compatibility between the Input System and Unity's UI systems. + +|**Topic**|**Description**| +|--------|-----------| +|[Understand UI system compatibility](understand-ui-compatibility.md)|Understand how the Input System interacts with Unity Toolkit, Unity UI (uGUI), and IMGUI.| +|[Using UI Input Module for UI support](using-ui-input-module.md)|Use the UI Input Module component to add support for specific UI systems.| +|[Use IMGUI alongside the Input System package](use-imgui-alongside-input-system.md)|Use a UI that supports the Input System, while still using IMGUI in other areas of your project.| \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/the-ui-input-module.md b/Packages/com.unity.inputsystem/Documentation~/the-ui-input-module.md deleted file mode 100644 index 05ab1407f9..0000000000 --- a/Packages/com.unity.inputsystem/Documentation~/the-ui-input-module.md +++ /dev/null @@ -1 +0,0 @@ -# The UI Input Module diff --git a/Packages/com.unity.inputsystem/Documentation~/ui-action-map-reference.md b/Packages/com.unity.inputsystem/Documentation~/ui-action-map-reference.md new file mode 100644 index 0000000000..38d5cfe40d --- /dev/null +++ b/Packages/com.unity.inputsystem/Documentation~/ui-action-map-reference.md @@ -0,0 +1,15 @@ +# UI Action Map reference +The default [Project-Wide Actions asset](./about-project-wide-actions.md) has a default configuration for UI input. + +**Action**|**Action Type**|**Control Type**|**Description** +-|-|-|- +Navigate|PassThrough|Vector2|A vector used to select the currently active UI [selectable](https://docs.unity3d.com/Manual/script-Selectable.html) in gamepad or arrow-key [navigation-type input](#navigation-type-input). +Submit|Button|Button|Submits the currently selected UI [selectable](https://docs.unity3d.com/Manual/script-Selectable.html) in [navigation-type input](#navigation-type-input) +Cancel|Button|Button|Exits any interaction with the currently selected UI [selectable](https://docs.unity3d.com/Manual/script-Selectable.html) in [navigation-type input](#navigation-type-input) +Point|PassThrough|Vector2|A 2D screen position. The cursor for [pointer-type](#pointer-type-input) interaction. +Click|PassThrough|Button|The primary button for [pointer-type](#pointer-type-input) interaction. +RightClick|PassThrough|Button|The secondary button for [pointer-type](#pointer-type-input) interaction. +MiddleClick|PassThrough|Button|The middle button for [pointer-type](#pointer-type-input) interaction. +ScrollWheel|PassThrough|Vector2|The scrolling gesture for [pointer-type](#pointer-type-input) interaction. +Tracked Device Position|PassThrough|Vector3|A 3D position of one or multiple spatial tracking devices, such as XR hand controllers. In combination with Tracked Device Orientation, this allows XR-style UI interactions by pointing at UI [selectables](https://docs.unity3d.com/Manual/script-Selectable.html) in space. See [tracked-type input](#tracked-type-input). +Tracked Device Orientation|PassThrough|Quaternion|a `Quaternion` representing the rotation of one or multiple spatial tracking devices, such as XR hand controllers. In combination with [Tracked Device Position](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_trackedDevicePosition), this allows XR-style UI interactions by pointing at UI [selectables](https://docs.unity3d.com/Manual/script-Selectable.html) in space. See [tracked-type input](#tracked-type-input). \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/ui-input-module-reference.md b/Packages/com.unity.inputsystem/Documentation~/ui-input-module-reference.md new file mode 100644 index 0000000000..b6fbabff5a --- /dev/null +++ b/Packages/com.unity.inputsystem/Documentation~/ui-input-module-reference.md @@ -0,0 +1,14 @@ +# UI Input Module component reference + +![InputSystemUIInputModule](Images/InputSystemUIInputModule.png) + +Use the following properties to configure [InputSystemUIInputModule](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html): + +|**Property**|**Description**| +|--------|-----------| +|[Move Repeat Delay](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_moveRepeatDelay)|The initial delay (in seconds) between generating an initial [IMoveHandler.OnMove](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/api/UnityEngine.EventSystems.IMoveHandler.html) navigation event and generating repeated navigation events when the __Move__ Action stays actuated.| +|[Move Repeat Rate](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_moveRepeatDelay)|The interval (in seconds) between generating repeat navigation events when the __Move__ Action stays actuated. Note that this is capped by the frame rate; there will not be more than one move repeat event each frame so if the frame rate dips below the repeat rate, the effective repeat rate will be lower than this setting.| +|[Actions Asset](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_actionsAsset)|An [Input Action Asset](ActionAssets.md) containing all the Actions to control the UI. You can choose which Actions in the Asset correspond to which UI inputs using the following properties.

By default, this references a built-in Asset named *DefaultInputActions*, which contains common default Actions for driving UI. If you want to set up your own Actions, [create a custom Input Action Asset](ActionAssets.md#creating-input-action-assets) and assign it here. When you assign a new Asset reference to this field in the Inspector, the Editor attempts to automatically map Actions to UI inputs based on common naming conventions.| +|[Deselect on Background Click](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_deselectOnBackgroundClick)|By default, when the pointer is clicked and does not hit any `GameObject`, the current selection is cleared. This, however, can get in the way of keyboard and gamepad navigation which will want to work off the currently selected object. To prevent automatic deselection, set this property to false.| +|[Pointer Behavior](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_pointerBehavior)|How to deal with multiple pointers feeding input into the UI. See [pointer-type input](#pointer-type-input). The options are:

- **Single Mouse or Pen But Multi Touch And Track**: Behaves like **Single Unified Pointer** for all input that is not classified as touch or tracked input, and behaves like **All Pointers As Is** for tracked and touch input.
- **Single Unified Pointer**: All pointer input is unified such that there is only ever a single pointer. This includes touch and tracked input.
- **All Pointers As Is**: The UI Input Module does not unify any pointer input. Any device, including touch and tracked devices that feed pointer input actions, has its own pointer (or multiple pointers for touch input).| +|[Cursor Lock Behavior](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_cursorLockBehavior)|Controls the origin point of UI raycasts when the cursor is locked. | \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/ui-input-types.md b/Packages/com.unity.inputsystem/Documentation~/ui-input-types.md deleted file mode 100644 index 33b7ad6000..0000000000 --- a/Packages/com.unity.inputsystem/Documentation~/ui-input-types.md +++ /dev/null @@ -1 +0,0 @@ -# UI Input Types diff --git a/Packages/com.unity.inputsystem/Documentation~/ui-input.md b/Packages/com.unity.inputsystem/Documentation~/ui-input.md new file mode 100644 index 0000000000..bd5c1315f4 --- /dev/null +++ b/Packages/com.unity.inputsystem/Documentation~/ui-input.md @@ -0,0 +1,13 @@ +# Input for user interfaces + +The Input System provides support for several UI systems in Unity. This section describes compatibility and configuration for UI input. + +|**Topic**|**Description**| +|--------|-----------| +|[Supported UI systems](supported-ui-systems.md)|Understand the compatibility between the Input System and Unity's UI systems.| +|[Configure UI Input Actions](configure-ui-input-action-map.md)|Configure UI Input Actions in the UI Action Map.| +|[UI Action Map reference](ui-action-map-reference.md)|Reference documentation for the Project-Wide Actions Asset's default UI Action Map.| +|[Distinguishing between UI input and game input](distinguishing-ui-game-input.md)|Understand how the Input System and Unity work together to distinguish which Input Actions are intended for UI, and which are intended for the game.| +|[Virtual mouse for cursor control](virtual-mouse-ui-cursor-control)|Use a virtual mouse to allow gamepads and joysticks to control pointer inputs.| +|[Multiplayer UI input](multiplayer-ui)|Configure multiple UI instances, so that multiple players can share a single screen and individually interact with the UI.| +|[On-screen controls](on-screen-controls)|Simulate input devices with UI widgets that the user interacts with on the screen.| \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/ui-support.md b/Packages/com.unity.inputsystem/Documentation~/ui-support.md deleted file mode 100644 index f1e2f8743a..0000000000 --- a/Packages/com.unity.inputsystem/Documentation~/ui-support.md +++ /dev/null @@ -1,19 +0,0 @@ -# UI Support - -Many Unity projects require that your users be able to navigate some kind of on-screen interface using their chosen input device. For example, pressing up or down on their controller should navigate to the next on-screen button above or below the currently selected one. - -The Input System provides features to help you implement support for controlling your project's UI through input. - -| **Topic** | **Description** | -| :------------------------------ | :------------------------------- | -| **[UI Support](ui-support.md)** | Summary | -| **[Compatibility](compatibility.md)** | Summary | -| **[Default UI Actions](default-ui-actions.md)** | Summary | -| **[Set up UI Actions](set-up-ui-actions.md)** | Summary | -| **[The UI Input Module](the-ui-input-module.md)** | Summary | -| **[Multiplayer UI](multiplayer-ui.md)** | Summary | -| **[Virtual Mouse Cursor](virtual-mouse-cursor.md)** | Summary | -| **[Distinguish between UI and Game Input](distinguish-between-ui-game-input.md)** | Summary | -| **[Immediate Mode GUI](immediate-mode-gui.md)** | Summary | -| **[On-screen Controls](on-screen-controls.md)** | Summary | -| **[Editor UI](editor-ui.md)** | Summary | \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/understand-ui-compatibility.md b/Packages/com.unity.inputsystem/Documentation~/understand-ui-compatibility.md new file mode 100644 index 0000000000..51d7e82b56 --- /dev/null +++ b/Packages/com.unity.inputsystem/Documentation~/understand-ui-compatibility.md @@ -0,0 +1,62 @@ +# Understand UI system compatibility +Unity has [three major UI solutions](https://docs.unity3d.com/Manual/UIToolkits.html). The Input System package's compatibility and workflow with these solutions varies depending on which UI solution you are using, and which version of Unity you are using. + +The three main UI systems are **UI Toolkit**, **Unity UI**, and **IMGUI**. Some systems and versions require that you use the Input System’s [UI Input Module component](using-ui-input-module) to pass actions from the Input System to the UI. + +## Compatibility summary +UI system|Compatible|UI Input Module component +-|-|- +UI Toolkit (2023.2+)|Yes|Not required +UI Toolkit (pre 2023.2)|Yes|Required +Unity UI (uGUI)|Yes|Required +IMGUI|No|n/a + +## UI Toolkit compatibility +[**UI Toolkit**](https://docs.unity3d.com/Manual/UIElements.html), also known as "UI Elements", is an XML/CSS style UI solution. + +- In versions of Unity prior to 2023.2, you must use the [UI Input Module component](using-ui-input-module) to pass actions from the Input System to the UI. +- From Unity 2023.2 and onwards, the UI actions defined in the default [project-wide actions](./about-project-wide-actions.md) directly map to UI Toolkit input.

+ +For more information on how to configure UI Toolkit input, refer to UI Toolkit [Runtime UI event system and input handling](https://docs.unity3d.com/Manual/UIE-Runtime-Event-System.html). + +### UI Toolkit event system + +Internally, UI Toolkit installs the `PanelEventHandler` component as an event listener. The listener intercepts events that `InputSystemUIInputModule` sends, and translates them into events that are specific to UI Toolkit. Those events are then routed into the visual tree. + +If you employ `EventSystem.SetUITookitEventSystemOverride`, this default mechanism is bypassed. + +A pointer click and a gamepad submit action are distinct at the event level in UI Toolkit. For example, the following script does not invoke the handler when the button is "clicked" with the gamepad (a `NavigationSubmitEvent` and not a `ClickEvent`): + + ```CSharp + button.RegisterCallback(_ => ButtonWasClicked()); + ``` + +However, the following script invokes the handler in both cases: + + ```CSharp + button.clicked += () => ButtonWasClicked(); + ``` + +### UI Toolkit XR support +>XR ([tracked-type input](#tracked-type-input)) is not yet supported in combination with UI Toolkit. This means that you cannot use devices such as VR controllers to operate interfaces created with UI Toolkit. + +### UI Toolkit raycasting + +UI Toolkit handles raycasting internally. No separate raycaster component is necessary. This means that UI Toolkit does not support [TrackedDeviceRaycaster](../api/UnityEngine.InputSystem.UI.TrackedDeviceRaycaster.html). + + + +## Unity UI (uGUI) compatibility +[**Unity UI**](https://docs.unity3d.com/Packages/com.unity.ugui@latest), also known as "uGUI", is a GameObject and Component-based UI solution). + +When using uGUI, you always need to use the [UI Input Module component](using-ui-input-module) to pass actions from the Input System to the UI. + +The uGUI package contains an older equivalent module called "**[Standalone Input Module](https://docs.unity3d.com/Manual/script-StandaloneInputModule.html)**" which performs the same kind of integration between the Unity UI and the legacy Input Manager system. + +If you have one of these older Standalone Input Module components on a GameObject in your project, and the Input System is installed, Unity displays a button in the Inspector offering to automatically replace it with the equivalent newer Input System UI Input Module for you. +## IMGUI compatibility +[**IMGUI**](https://docs.unity3d.com/Manual/GUIScriptingGuide.html) is a script-based "Immediate Mode" UI which uses the [`OnGUI`](https://docs.unity3d.com/ScriptReference/MonoBehaviour.OnGUI.html) method. + +The Input System package is not compatible with IMGUI. However you can still use the Input System for other parts of your project, such as gameplay. For more information, refer to [Use IMGUI alongside the Input System package](#immediate-mode-gui). + +## \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/use-imgui-alongside-input-system.md b/Packages/com.unity.inputsystem/Documentation~/use-imgui-alongside-input-system.md new file mode 100644 index 0000000000..bf55ca2c2f --- /dev/null +++ b/Packages/com.unity.inputsystem/Documentation~/use-imgui-alongside-input-system.md @@ -0,0 +1,11 @@ +# Use IMGUI alongside the Input System package +The Input System package does not support [Immediate Mode GUI](https://docs.unity3d.com/Manual/GUIScriptingGuide.html) (IMGUI) methods at runtime. However, if you need to use IMGUI for your UI, you can use legacy Input Manager input for IMGUI, and the Input System package for your in-game input. + + +When the Editor's [**Active Input Handling**](https://docs.unity3d.com/Manual/class-PlayerSettings.html) setting is set to "**Input System Package**" (which is the default, when using the Input System package), the `OnGUI` methods in your player code don't receive any input events. + + +To restore functionality to runtime `OnGUI` methods, you can change the **Active Input Handling** setting to "**Both**". Doing this means that Unity processes the input twice which could introduce a small performance impact. + + +This only affects runtime (play mode) `OnGUI` methods. Editor GUI code is unaffected and continues to receive input events. \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/use-navigation-type-input-with-ui.md b/Packages/com.unity.inputsystem/Documentation~/use-navigation-type-input-with-ui.md deleted file mode 100644 index f12c86b697..0000000000 --- a/Packages/com.unity.inputsystem/Documentation~/use-navigation-type-input-with-ui.md +++ /dev/null @@ -1 +0,0 @@ -# Use Navigation-type input with UI diff --git a/Packages/com.unity.inputsystem/Documentation~/use-pointer-type-navigation-with-ui.md b/Packages/com.unity.inputsystem/Documentation~/use-pointer-type-navigation-with-ui.md deleted file mode 100644 index a6769d69f5..0000000000 --- a/Packages/com.unity.inputsystem/Documentation~/use-pointer-type-navigation-with-ui.md +++ /dev/null @@ -1 +0,0 @@ -# Use Pointer-type navigation with UI diff --git a/Packages/com.unity.inputsystem/Documentation~/use-tracket-type-input-with-ui.md b/Packages/com.unity.inputsystem/Documentation~/use-tracket-type-input-with-ui.md deleted file mode 100644 index 7461949ab2..0000000000 --- a/Packages/com.unity.inputsystem/Documentation~/use-tracket-type-input-with-ui.md +++ /dev/null @@ -1 +0,0 @@ -# Use Tracket-type input with UI diff --git a/Packages/com.unity.inputsystem/Documentation~/using-ui-input-module.md b/Packages/com.unity.inputsystem/Documentation~/using-ui-input-module.md new file mode 100644 index 0000000000..aab2c4ec98 --- /dev/null +++ b/Packages/com.unity.inputsystem/Documentation~/using-ui-input-module.md @@ -0,0 +1,12 @@ +# Using UI Input Module for UI support + +The UI Input Module passes input to the UI in your project. + +You must use the Unity Input System when using Unity UI (uGUI), or when using versions of Unity Toolkit prior to 2023.3. + +|**Topic**|**Description**| +|--------|-----------| +|[Introduction to the UI Input Module](introduction-ui-input-module.md)|Understand the UI Input Module's function and considerations for use. | +|[Supported input types in the UI Input Module](supported-ui-input-types-ui-input-module.md)|Understand the types of input that the UI Input Module can pass to the Editor.| +|[Access the UI Input Module](access-ui-input-module.md)|Access and add the UI Input Module to your scene. | +|[UI Input Module component reference](ui-input-module-reference.md)|Reference for the UI Input Module component.| \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/virtual-mouse-cursor.md b/Packages/com.unity.inputsystem/Documentation~/virtual-mouse-cursor.md deleted file mode 100644 index 700c985152..0000000000 --- a/Packages/com.unity.inputsystem/Documentation~/virtual-mouse-cursor.md +++ /dev/null @@ -1 +0,0 @@ -# Virtual Mouse Cursor diff --git a/Packages/com.unity.inputsystem/Documentation~/virtual-mouse-ui-cursor-control.md b/Packages/com.unity.inputsystem/Documentation~/virtual-mouse-ui-cursor-control.md new file mode 100644 index 0000000000..d799fd3690 --- /dev/null +++ b/Packages/com.unity.inputsystem/Documentation~/virtual-mouse-ui-cursor-control.md @@ -0,0 +1,13 @@ +# Virtual Mouse for UI cursor control + +Use a virtual mouse to allow gamepads and joysticks to control pointer inputs. + +**Note**: The Virtual Mouse component is only compatible with the [Unity UI](https://docs.unity3d.com/Manual/com.unity.ugui.html) (uGUI) system, and not UI Toolkit or IMGUI. + +|**Topic**|**Description**| +|--------|-----------| +|[Introduction to Virtual Mouse for UI cursor control](introduction-virtual-mouse.md)|Use a Virtual Mouse component to set up navigation-based input for the UI. | +|[Configure a Virtual Mouse for UI input](configure-virtual-mouse-input.md)|Add and configure a Virtual Mouse component to your project.| + + + \ No newline at end of file From 3e17f195a8c157e9042259ce8591dcd3a7e73f39 Mon Sep 17 00:00:00 2001 From: Siobhan Date: Tue, 28 Jan 2025 11:02:24 +0000 Subject: [PATCH 02/15] Update TableOfContents.md --- .../Documentation~/TableOfContents.md | 50 +++++++++---------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/Packages/com.unity.inputsystem/Documentation~/TableOfContents.md b/Packages/com.unity.inputsystem/Documentation~/TableOfContents.md index 0e54c41b00..7fc999e8e8 100644 --- a/Packages/com.unity.inputsystem/Documentation~/TableOfContents.md +++ b/Packages/com.unity.inputsystem/Documentation~/TableOfContents.md @@ -70,31 +70,31 @@ * [Sensor support](Sensors.md) * [HID support](HID.md) * [Input for user interfaces](ui-input.md) - * [Supported UI systems](supported-ui-systems.md) - * [Understand UI system compatibility](understand-ui-compatibility.md) - * [Using UI Input Module for UI support](using-ui-input-module.md) - * [Introduction to the UI Input Module](introduction-ui-input-module.md) - * [Supported input types in the UI Input Module](supported-ui-input-types.md) - * [Pointer input UI support](supported-ui-input-types-pointer.md) - * [Navigation input UI support](supported-ui-input-types-navigation.md) - * [Tracked input UI support](supported-ui-input-types-tracked.md) - * [Access the UI Input Module](access-ui-input-module.md) - * [UI Input Module component reference](ui-input-module-reference.md) - * [Use IMGUI alongside the Input System package](use-imgui-alongside-input-system.md) - * [Configure UI Input Actions](configure-ui-input-action-map.md) - * [UI Action Map reference](ui-action-map-reference.md) - * [Distinguishing between UI input and game input](distinguishing-ui-game-input.md) - * [Virtual Mouse for UI cursor control](virtual-mouse-ui-cursor-control.md) - * [Introduction to Virtual Mouse for UI cursor control](introduction-virtual-mouse.md) - * [Configure a Virtual Mouse for UI input](configure-virtual-mouse-input.md) - * [Multiplayer UI input](multiplayer-ui-input.md) - * [Introduction to multiplayer UI input](introduction-multiplayer-ui-input.md) - * [Configure multiplayer UI input](configure-multiplayer-ui-input.md) - * [On-screen Controls](on-screen-controls.md) - * [Introduction to on-screen Controls](introduction-on-screen-controls.md) - * [Create an on-screen button Control](create-on-screen-button-control.md) - * [Create an on-screen stick Control](create-on-screen-stick-control.md) - * [Create a custom on-screen Control](create-custom-on-screen-control.md) + * [Supported UI systems](supported-ui-systems.md) + * [Understand UI system compatibility](understand-ui-compatibility.md) + * [Using UI Input Module for UI support](using-ui-input-module.md) + * [Introduction to the UI Input Module](introduction-ui-input-module.md) + * [Supported input types in the UI Input Module](supported-ui-input-types.md) + * [Pointer input UI support](supported-ui-input-types-pointer.md) + * [Navigation input UI support](supported-ui-input-types-navigation.md) + * [Tracked input UI support](supported-ui-input-types-tracked.md) + * [Access the UI Input Module](access-ui-input-module.md) + * [UI Input Module component reference](ui-input-module-reference.md) + * [Use IMGUI alongside the Input System package](use-imgui-alongside-input-system.md) + * [Configure UI Input Actions](configure-ui-input-action-map.md) + * [UI Action Map reference](ui-action-map-reference.md) + * [Distinguishing between UI input and game input](distinguishing-ui-game-input.md) + * [Virtual Mouse for UI cursor control](virtual-mouse-ui-cursor-control.md) + * [Introduction to Virtual Mouse for UI cursor control](introduction-virtual-mouse.md) + * [Configure a Virtual Mouse for UI input](configure-virtual-mouse-input.md) + * [Multiplayer UI input](multiplayer-ui-input.md) + * [Introduction to multiplayer UI input](introduction-multiplayer-ui-input.md) + * [Configure multiplayer UI input](configure-multiplayer-ui-input.md) + * [On-screen Controls](on-screen-controls.md) + * [Introduction to on-screen Controls](introduction-on-screen-controls.md) + * [Create an on-screen button Control](create-on-screen-button-control.md) + * [Create an on-screen stick Control](create-on-screen-stick-control.md) + * [Create a custom on-screen Control](create-custom-on-screen-control.md) * [Editor Features](EditorFeatures.md) * [Using Input in the Editor](UseInEditor.md) * [Debugging](debugging.md) From 958efe9958b138df764c0ddad391bc461f6b328f Mon Sep 17 00:00:00 2001 From: Siobhan Date: Tue, 28 Jan 2025 11:08:24 +0000 Subject: [PATCH 03/15] Fixed note box formatting --- .../Documentation~/configure-virtual-mouse-input.md | 2 +- .../Documentation~/introduction-on-screen-controls.md | 6 ++++-- .../Documentation~/supported-ui-input-types-tracked.md | 3 +-- .../Documentation~/understand-ui-compatibility.md | 10 +++------- 4 files changed, 9 insertions(+), 12 deletions(-) diff --git a/Packages/com.unity.inputsystem/Documentation~/configure-virtual-mouse-input.md b/Packages/com.unity.inputsystem/Documentation~/configure-virtual-mouse-input.md index 9424dd142f..2b27d11db9 100644 --- a/Packages/com.unity.inputsystem/Documentation~/configure-virtual-mouse-input.md +++ b/Packages/com.unity.inputsystem/Documentation~/configure-virtual-mouse-input.md @@ -9,7 +9,7 @@ To configure the Virtual Mouse component with the Unity UI system: 6. Drag the **Image** component of the pointer GameObject into the **Cursor Graphic** field of the Virtual Mouse component. 7. Drag the **Rect Transform** component of the pointer GameObject to the **Cursor Transform** field of the Virtual Mouse component. -> **Note**: +>[!NOTE] > Do not set up gamepads and joysticks for [navigation input](#navigation-type-input) while using the Virtual Mouse component. If, for example, the Virtual Mouse component is configured to receive input from gamepads, and `Move`, `Submit`, and `Cancel` on the UI Input Module are also linked to the gamepad, then the UI receives input from the gamepad on two channels, and triggers the input twice. If you want the virtual mouse to control the system mouse cursor: diff --git a/Packages/com.unity.inputsystem/Documentation~/introduction-on-screen-controls.md b/Packages/com.unity.inputsystem/Documentation~/introduction-on-screen-controls.md index be4151cf18..109f2925a1 100644 --- a/Packages/com.unity.inputsystem/Documentation~/introduction-on-screen-controls.md +++ b/Packages/com.unity.inputsystem/Documentation~/introduction-on-screen-controls.md @@ -7,7 +7,8 @@ You can use on-screen Controls to simulate Input Devices with UI widgets that th There are currently two Control types implemented out of the box: [buttons](#on-screen-buttons) and [sticks](#on-screen-sticks). You can implement custom Controls by extending the base [`OnScreenControl`](../api/UnityEngine.InputSystem.OnScreen.OnScreenControl.html) class (see documentation on [writing custom on screen Controls](#writing-custom-on-screen-controls) to learn more). ->__Note__: On-screen Controls don't have a predefined visual representation. It's up to you to set up the visual aspect of a Control (for example, by adding a sprite or UI component to the GameObject). On-screen Controls take care of the interaction logic and of setting up and generating input from interactions. +>[!NOTE] +>On-screen Controls don't have a predefined visual representation. It's up to you to set up the visual aspect of a Control (for example, by adding a sprite or UI component to the GameObject). On-screen Controls take care of the interaction logic and of setting up and generating input from interactions. Each on-screen Control uses a [Control path](Controls.md#control-paths) to reference the Control that it should report input as. For example, the following on-screen button reports input as the right shoulder button of a gamepad: @@ -17,4 +18,5 @@ The collection of on-screen Controls present in a Scene forms one or more [Input To query the Control (and, implicitly, the Device) that an on-screen Control feeds into, you can use the [`OnScreenControl.control`](../api/UnityEngine.InputSystem.OnScreen.OnScreenControl.html#UnityEngine_InputSystem_OnScreen_OnScreenControl_control) property. ->__Note__: This design allows you to use on-screen Controls to create input for arbitrary Input Devices, in addition to joysticks and gamepads. \ No newline at end of file +>[!NOTE] +>This design allows you to use on-screen Controls to create input for arbitrary Input Devices, in addition to joysticks and gamepads. \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-tracked.md b/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-tracked.md index 6779f9faa8..1b164bd7ef 100644 --- a/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-tracked.md +++ b/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-tracked.md @@ -2,8 +2,7 @@ Input from [tracked devices](../api/UnityEngine.InputSystem.TrackedDevice.html) such as [XR controllers](../api/UnityEngine.InputSystem.XR.XRController.html) and [HMDs](../api/UnityEngine.InputSystem.XR.XRHMD.html) essentially behaves like [pointer-type input](#pointer-type-input). The main difference is that the world-space device position and orientation sourced from [trackedDevicePosition](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_trackedDevicePosition) and [trackedDeviceOrientation](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_trackedDeviceOrientation) is translated into a screen-space position via raycasting. - -> **Important:** +>[!IMPORTANT] >Because multiple tracked Devices can feed into the same set of Actions, it is important to set the [action type](./RespondingToActions.md#action-types) to [PassThrough](../api/UnityEngine.InputSystem.InputActionType.html#UnityEngine_InputSystem_InputActionType_PassThrough). This ensures that no filtering is applied to input on these actions and that instead every input is relayed as is. For this raycasting to work, you need to add [TrackedDeviceRaycaster](../api/UnityEngine.InputSystem.UI.TrackedDeviceRaycaster.html) to the `GameObject` that has the UI's `Canvas` component. This `GameObject` will usually have a `GraphicRaycaster` component which, however, only works for 2D screen-space raycasting. You can put [TrackedDeviceRaycaster](../api/UnityEngine.InputSystem.UI.TrackedDeviceRaycaster.html) alongside `GraphicRaycaster` and both can be enabled at the same time without advserse effect. diff --git a/Packages/com.unity.inputsystem/Documentation~/understand-ui-compatibility.md b/Packages/com.unity.inputsystem/Documentation~/understand-ui-compatibility.md index 51d7e82b56..f8d838113a 100644 --- a/Packages/com.unity.inputsystem/Documentation~/understand-ui-compatibility.md +++ b/Packages/com.unity.inputsystem/Documentation~/understand-ui-compatibility.md @@ -38,25 +38,21 @@ However, the following script invokes the handler in both cases: ``` ### UI Toolkit XR support ->XR ([tracked-type input](#tracked-type-input)) is not yet supported in combination with UI Toolkit. This means that you cannot use devices such as VR controllers to operate interfaces created with UI Toolkit. +XR ([tracked-type input](#tracked-type-input)) is not yet supported in combination with UI Toolkit. This means that you cannot use devices such as VR controllers to operate interfaces created with UI Toolkit. ### UI Toolkit raycasting - UI Toolkit handles raycasting internally. No separate raycaster component is necessary. This means that UI Toolkit does not support [TrackedDeviceRaycaster](../api/UnityEngine.InputSystem.UI.TrackedDeviceRaycaster.html). - - ## Unity UI (uGUI) compatibility [**Unity UI**](https://docs.unity3d.com/Packages/com.unity.ugui@latest), also known as "uGUI", is a GameObject and Component-based UI solution). When using uGUI, you always need to use the [UI Input Module component](using-ui-input-module) to pass actions from the Input System to the UI. -The uGUI package contains an older equivalent module called "**[Standalone Input Module](https://docs.unity3d.com/Manual/script-StandaloneInputModule.html)**" which performs the same kind of integration between the Unity UI and the legacy Input Manager system. +The uGUI package contains an older equivalent module called **[Standalone Input Module](https://docs.unity3d.com/Manual/script-StandaloneInputModule.html)**, which performs the same kind of integration between the Unity UI and the legacy Input Manager system. If you have one of these older Standalone Input Module components on a GameObject in your project, and the Input System is installed, Unity displays a button in the Inspector offering to automatically replace it with the equivalent newer Input System UI Input Module for you. + ## IMGUI compatibility [**IMGUI**](https://docs.unity3d.com/Manual/GUIScriptingGuide.html) is a script-based "Immediate Mode" UI which uses the [`OnGUI`](https://docs.unity3d.com/ScriptReference/MonoBehaviour.OnGUI.html) method. The Input System package is not compatible with IMGUI. However you can still use the Input System for other parts of your project, such as gameplay. For more information, refer to [Use IMGUI alongside the Input System package](#immediate-mode-gui). - -## \ No newline at end of file From 0469b3935c194a66e81d81a5e92813d7a71574a4 Mon Sep 17 00:00:00 2001 From: Siobhan Date: Tue, 28 Jan 2025 11:40:16 +0000 Subject: [PATCH 04/15] Updated links --- .../configure-ui-input-action-map.md | 2 +- .../configure-virtual-mouse-input.md | 2 +- .../distinguishing-ui-game-input.md | 2 +- .../introduction-multiplayer-ui-input.md | 2 +- .../introduction-on-screen-controls.md | 2 +- .../introduction-virtual-mouse.md | 2 +- .../supported-ui-input-types-navigation.md | 2 +- .../supported-ui-input-types-pointer.md | 2 +- .../supported-ui-input-types-tracked.md | 4 ++-- .../Documentation~/ui-action-map-reference.md | 20 +++++++++---------- .../ui-input-module-reference.md | 2 +- .../understand-ui-compatibility.md | 10 +++++----- 12 files changed, 26 insertions(+), 26 deletions(-) diff --git a/Packages/com.unity.inputsystem/Documentation~/configure-ui-input-action-map.md b/Packages/com.unity.inputsystem/Documentation~/configure-ui-input-action-map.md index ff60748cf7..7a41445368 100644 --- a/Packages/com.unity.inputsystem/Documentation~/configure-ui-input-action-map.md +++ b/Packages/com.unity.inputsystem/Documentation~/configure-ui-input-action-map.md @@ -1,6 +1,6 @@ # Configure the UI Input Action Map -The default [Project-Wide Actions asset](./about-project-wide-actions.md) comes with a "**UI**" Action Map, which contains all the actions required for UI interaction. To configure the bindings for these actions, use the [Actions Editor](./ActionsEditor.md). +The default [Project-Wide Actions asset](./about-project-wide-actions.md) comes with a "**UI**" Action Map, which contains all the actions required for UI interaction. To configure the bindings for these actions, use the [Actions Editor](./actions-editor.md). To open the Actions Editor: diff --git a/Packages/com.unity.inputsystem/Documentation~/configure-virtual-mouse-input.md b/Packages/com.unity.inputsystem/Documentation~/configure-virtual-mouse-input.md index 2b27d11db9..6cde1b55fe 100644 --- a/Packages/com.unity.inputsystem/Documentation~/configure-virtual-mouse-input.md +++ b/Packages/com.unity.inputsystem/Documentation~/configure-virtual-mouse-input.md @@ -10,7 +10,7 @@ To configure the Virtual Mouse component with the Unity UI system: 7. Drag the **Rect Transform** component of the pointer GameObject to the **Cursor Transform** field of the Virtual Mouse component. >[!NOTE] -> Do not set up gamepads and joysticks for [navigation input](#navigation-type-input) while using the Virtual Mouse component. If, for example, the Virtual Mouse component is configured to receive input from gamepads, and `Move`, `Submit`, and `Cancel` on the UI Input Module are also linked to the gamepad, then the UI receives input from the gamepad on two channels, and triggers the input twice. +> Do not set up gamepads and joysticks for [navigation input](supported-ui-input-types-navigation.md) while using the Virtual Mouse component. If, for example, the Virtual Mouse component is configured to receive input from gamepads, and `Move`, `Submit`, and `Cancel` on the UI Input Module are also linked to the gamepad, then the UI receives input from the gamepad on two channels, and triggers the input twice. If you want the virtual mouse to control the system mouse cursor: Set [Cursor Mode](../api/UnityEngine.InputSystem.UI.VirtualMouseInput.html#UnityEngine_InputSystem_UI_VirtualMouseInput_cursorMode) to **Hardware Cursor If Available**. In this mode, the **Cursor Graphic** is hidden when a system mouse is present and you use [Mouse.WarpCursorPosition](../api/UnityEngine.InputSystem.Mouse.html#UnityEngine_InputSystem_Mouse_WarpCursorPosition_UnityEngine_Vector2_) to move the system mouse cursor instead of the software cursor. The transform linked through **Cursor Transform** is not updated in that case. diff --git a/Packages/com.unity.inputsystem/Documentation~/distinguishing-ui-game-input.md b/Packages/com.unity.inputsystem/Documentation~/distinguishing-ui-game-input.md index 89a9920218..43e4e839b4 100644 --- a/Packages/com.unity.inputsystem/Documentation~/distinguishing-ui-game-input.md +++ b/Packages/com.unity.inputsystem/Documentation~/distinguishing-ui-game-input.md @@ -10,7 +10,7 @@ Whether such ambiguities exist depends on *how* UIs are used. For example, you c * Place UI over a 2D/3D scene, but don’t let the user directly interact with the UI. * Place UI over a 2D/3D scene, but create a clear "mode" switch that determines whether interaction applies to the UI or the scene. For example, a first-person game on desktop might employ a [cursor lock](https://docs.unity3d.com/ScriptReference/Cursor-lockState.html) which directs input to the game when it is engaged, and to the UI when it is not engaged. -There are specific ambiguities that can arise for [pointer input](#pointer-type-input) and [navigation input](#navigation-type-input). +There are specific ambiguities that can arise for [pointer input](supported-ui-input-types-pointer.md) and [navigation input](supported-ui-input-types-navigation.md). >[!NOTE] >The Input System package includes a sample project called "**UI vs Game Input**". The sample demonstrates how to deal with ambiguities between inputs for UI and inputs for the game. diff --git a/Packages/com.unity.inputsystem/Documentation~/introduction-multiplayer-ui-input.md b/Packages/com.unity.inputsystem/Documentation~/introduction-multiplayer-ui-input.md index cd84c69053..756cb911ca 100644 --- a/Packages/com.unity.inputsystem/Documentation~/introduction-multiplayer-ui-input.md +++ b/Packages/com.unity.inputsystem/Documentation~/introduction-multiplayer-ui-input.md @@ -1,6 +1,6 @@ # Introduction to multiplayer UI input -The Input System can handle multiple separate UI instances on the screen controlled separately by different [Input Bindings](ActionBindings.md). This is useful if you want to have multiple local players share a single screen with different controllers, so that every player can control their own UI instance. +The Input System can handle multiple separate UI instances on the screen controlled separately by different [Input Bindings](action-bindings.md). This is useful if you want to have multiple local players share a single screen with different controllers, so that every player can control their own UI instance. To implement multiplayer UI, the Input System uses the Multiplayer Event System. diff --git a/Packages/com.unity.inputsystem/Documentation~/introduction-on-screen-controls.md b/Packages/com.unity.inputsystem/Documentation~/introduction-on-screen-controls.md index 109f2925a1..c484c8ad78 100644 --- a/Packages/com.unity.inputsystem/Documentation~/introduction-on-screen-controls.md +++ b/Packages/com.unity.inputsystem/Documentation~/introduction-on-screen-controls.md @@ -5,7 +5,7 @@ uid: input-system-on-screen You can use on-screen Controls to simulate Input Devices with UI widgets that the user interacts with on the screen. The most prominent example is the use of stick and button widgets on touchscreens to emulate a joystick or gamepad. -There are currently two Control types implemented out of the box: [buttons](#on-screen-buttons) and [sticks](#on-screen-sticks). You can implement custom Controls by extending the base [`OnScreenControl`](../api/UnityEngine.InputSystem.OnScreen.OnScreenControl.html) class (see documentation on [writing custom on screen Controls](#writing-custom-on-screen-controls) to learn more). +There are currently two on-screen Control types implemented out of the box: [on-screen buttons](create-on-screen-button-control.md) and [on-screen sticks](create-on-screen-stick-control.md). You can implement custom Controls by extending the base [`OnScreenControl`](../api/UnityEngine.InputSystem.OnScreen.OnScreenControl.html) class (see documentation on [writing custom on screen Controls](create-custom-on-screen-control.md) to learn more). >[!NOTE] >On-screen Controls don't have a predefined visual representation. It's up to you to set up the visual aspect of a Control (for example, by adding a sprite or UI component to the GameObject). On-screen Controls take care of the interaction logic and of setting up and generating input from interactions. diff --git a/Packages/com.unity.inputsystem/Documentation~/introduction-virtual-mouse.md b/Packages/com.unity.inputsystem/Documentation~/introduction-virtual-mouse.md index eae5cb5623..84b04f4684 100644 --- a/Packages/com.unity.inputsystem/Documentation~/introduction-virtual-mouse.md +++ b/Packages/com.unity.inputsystem/Documentation~/introduction-virtual-mouse.md @@ -1,6 +1,6 @@ # Introduction to Virtual Mouse for UI cursor control -If your application uses gamepads and joysticks as an input, you can use [navigation input actions](supported-ui-input-types-ui-input-module.md#navigation-input) to operate the UI. However, it usually involves extra work to make the UI work well with navigation. +If your application uses gamepads and joysticks as an input, you can use [navigation input actions](supported-ui-input-types-navigation.md) to operate the UI. However, it usually involves extra work to make the UI work well with navigation. An alternative way to operate the UI is to allow gamepads and joysticks to drive the cursor from a virtual mouse. The Input System package provides a **Virtual Mouse** component for this purpose. diff --git a/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-navigation.md b/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-navigation.md index 958311517d..3374c1a5dd 100644 --- a/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-navigation.md +++ b/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-navigation.md @@ -4,7 +4,7 @@ Navigation-type input controls the current selection based on motion read from t [submit](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_submit) will trigger `ISubmitHandler` on the currently selected object and [cancel](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_cancel) will trigger `ICancelHandler` on it. -Unlike with [pointer-type](#pointer-type-input), where multiple pointer inputs may exist concurrently (think two touches or left- and right-hand tracked input), navigation-type input does not have multiple concurrent instances. In other words, only a single [move](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_move) vector and a single [submit](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_submit) and [cancel](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_cancel) input will be processed by the UI module each frame. However, these inputs need not necessarily come from one single Device always. Arbitrary many inputs can be bound to the respective actions. +Unlike with [pointer-type](supported-ui-input-types-pointer.md), where multiple pointer inputs may exist concurrently (think two touches or left- and right-hand tracked input), navigation-type input does not have multiple concurrent instances. In other words, only a single [move](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_move) vector and a single [submit](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_submit) and [cancel](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_cancel) input will be processed by the UI module each frame. However, these inputs need not necessarily come from one single Device always. Arbitrary many inputs can be bound to the respective actions. While, [move](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_move) should be set to [PassThrough](../api/UnityEngine.InputSystem.InputActionType.html#UnityEngine_InputSystem_InputActionType_PassThrough) Action type, it is important that [submit](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_submit) and [cancel](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_cancel) be set to the [Button](../api/UnityEngine.InputSystem.InputActionType.html#UnityEngine_InputSystem_InputActionType_Button) Action type. diff --git a/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-pointer.md b/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-pointer.md index 4634b95138..c46d0ebcac 100644 --- a/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-pointer.md +++ b/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-pointer.md @@ -14,7 +14,7 @@ To influence how the input module deals with concurrent input from multiple poin If you bind a device to a pointer-type action such as [Left Click](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_leftClick) without also binding it to [Point](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_point), the UI input module will recognize the device as not being able to point and try to route its input into that of another pointer. For example, if you bind [Left Click](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_leftClick) to the `Space` key and [Point](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_point) to the position of the mouse, then pressing the space bar will result in a left click at the current position of the mouse. -For pointer-type input (as well as for [tracked-type input](#tracked-type-input)), [InputSystemUIInputModule](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html) will send [ExtendedPointerEventData](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html) instances which are an extended version of the base `PointerEventData`. These events contain additional data such as the [device](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html#UnityEngine_InputSystem_UI_ExtendedPointerEventData_device) and [pointer type](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html#UnityEngine_InputSystem_UI_ExtendedPointerEventData_pointerType) which the event has been generated from. +For pointer-type input (as well as for [tracked-type input](supported-ui-input-types-tracked.md)), [InputSystemUIInputModule](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html) sends [ExtendedPointerEventData](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html) instances which are an extended version of the base `PointerEventData`. These events contain additional data such as the [device](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html#UnityEngine_InputSystem_UI_ExtendedPointerEventData_device) and [pointer type](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html#UnityEngine_InputSystem_UI_ExtendedPointerEventData_pointerType) which the event has been generated from. ## Pointer behavior diff --git a/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-tracked.md b/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-tracked.md index 1b164bd7ef..6847cb4094 100644 --- a/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-tracked.md +++ b/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-tracked.md @@ -1,6 +1,6 @@ # Tracked input UI support -Input from [tracked devices](../api/UnityEngine.InputSystem.TrackedDevice.html) such as [XR controllers](../api/UnityEngine.InputSystem.XR.XRController.html) and [HMDs](../api/UnityEngine.InputSystem.XR.XRHMD.html) essentially behaves like [pointer-type input](#pointer-type-input). The main difference is that the world-space device position and orientation sourced from [trackedDevicePosition](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_trackedDevicePosition) and [trackedDeviceOrientation](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_trackedDeviceOrientation) is translated into a screen-space position via raycasting. +Input from [tracked devices](../api/UnityEngine.InputSystem.TrackedDevice.html) such as [XR controllers](../api/UnityEngine.InputSystem.XR.XRController.html) and [HMDs](../api/UnityEngine.InputSystem.XR.XRHMD.html) essentially behaves like [pointer-type input](supported-ui-input-types-pointer.md). The main difference is that the world-space device position and orientation sourced from [trackedDevicePosition](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_trackedDevicePosition) and [trackedDeviceOrientation](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_trackedDeviceOrientation) is translated into a screen-space position via raycasting. >[!IMPORTANT] >Because multiple tracked Devices can feed into the same set of Actions, it is important to set the [action type](./RespondingToActions.md#action-types) to [PassThrough](../api/UnityEngine.InputSystem.InputActionType.html#UnityEngine_InputSystem_InputActionType_PassThrough). This ensures that no filtering is applied to input on these actions and that instead every input is relayed as is. @@ -11,4 +11,4 @@ For this raycasting to work, you need to add [TrackedDeviceRaycaster](../api/Uni ![TrackedDeviceRayster Properties](Images/TrackedDeviceRaycaster.png) -Clicks on tracked devices do not differ from other [pointer-type input](#pointer-type-input). Therefore, actions such as [Left Click](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_leftClick) work for tracked devices just like they work for other pointers. \ No newline at end of file +Clicks on tracked devices do not differ from other [pointer-type input](supported-ui-input-types-pointer.md). Therefore, actions such as [Left Click](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_leftClick) work for tracked devices just like they work for other pointers. \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/ui-action-map-reference.md b/Packages/com.unity.inputsystem/Documentation~/ui-action-map-reference.md index 38d5cfe40d..9d469cd2fe 100644 --- a/Packages/com.unity.inputsystem/Documentation~/ui-action-map-reference.md +++ b/Packages/com.unity.inputsystem/Documentation~/ui-action-map-reference.md @@ -3,13 +3,13 @@ The default [Project-Wide Actions asset](./about-project-wide-actions.md) has a **Action**|**Action Type**|**Control Type**|**Description** -|-|-|- -Navigate|PassThrough|Vector2|A vector used to select the currently active UI [selectable](https://docs.unity3d.com/Manual/script-Selectable.html) in gamepad or arrow-key [navigation-type input](#navigation-type-input). -Submit|Button|Button|Submits the currently selected UI [selectable](https://docs.unity3d.com/Manual/script-Selectable.html) in [navigation-type input](#navigation-type-input) -Cancel|Button|Button|Exits any interaction with the currently selected UI [selectable](https://docs.unity3d.com/Manual/script-Selectable.html) in [navigation-type input](#navigation-type-input) -Point|PassThrough|Vector2|A 2D screen position. The cursor for [pointer-type](#pointer-type-input) interaction. -Click|PassThrough|Button|The primary button for [pointer-type](#pointer-type-input) interaction. -RightClick|PassThrough|Button|The secondary button for [pointer-type](#pointer-type-input) interaction. -MiddleClick|PassThrough|Button|The middle button for [pointer-type](#pointer-type-input) interaction. -ScrollWheel|PassThrough|Vector2|The scrolling gesture for [pointer-type](#pointer-type-input) interaction. -Tracked Device Position|PassThrough|Vector3|A 3D position of one or multiple spatial tracking devices, such as XR hand controllers. In combination with Tracked Device Orientation, this allows XR-style UI interactions by pointing at UI [selectables](https://docs.unity3d.com/Manual/script-Selectable.html) in space. See [tracked-type input](#tracked-type-input). -Tracked Device Orientation|PassThrough|Quaternion|a `Quaternion` representing the rotation of one or multiple spatial tracking devices, such as XR hand controllers. In combination with [Tracked Device Position](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_trackedDevicePosition), this allows XR-style UI interactions by pointing at UI [selectables](https://docs.unity3d.com/Manual/script-Selectable.html) in space. See [tracked-type input](#tracked-type-input). \ No newline at end of file +Navigate|PassThrough|Vector2|A vector used to select the currently active UI [selectable](https://docs.unity3d.com/Manual/script-Selectable.html) in gamepad or arrow-key [navigation-type input](supported-ui-input-types-navigation.md). +Submit|Button|Button|Submits the currently selected UI [selectable](https://docs.unity3d.com/Manual/script-Selectable.html) in [navigation-type input](supported-ui-input-types-navigation.md) +Cancel|Button|Button|Exits any interaction with the currently selected UI [selectable](https://docs.unity3d.com/Manual/script-Selectable.html) in [navigation-type input](supported-ui-input-types-navigation.md) +Point|PassThrough|Vector2|A 2D screen position. The cursor for [pointer-type](supported-ui-input-types-pointer.md) interaction. +Click|PassThrough|Button|The primary button for [pointer-type](supported-ui-input-types-pointer.md) interaction. +RightClick|PassThrough|Button|The secondary button for [pointer-type](supported-ui-input-types-pointer.md) interaction. +MiddleClick|PassThrough|Button|The middle button for [pointer-type](supported-ui-input-types-pointer.md) interaction. +ScrollWheel|PassThrough|Vector2|The scrolling gesture for [pointer-type](supported-ui-input-types-pointer.md) interaction. +Tracked Device Position|PassThrough|Vector3|A 3D position of one or multiple spatial tracking devices, such as XR hand controllers. In combination with Tracked Device Orientation, this allows XR-style UI interactions by pointing at UI [selectables](https://docs.unity3d.com/Manual/script-Selectable.html) in space. See [tracked-type input](supported-ui-input-types-tracked.md). +Tracked Device Orientation|PassThrough|Quaternion|a `Quaternion` representing the rotation of one or multiple spatial tracking devices, such as XR hand controllers. In combination with [Tracked Device Position](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_trackedDevicePosition), this allows XR-style UI interactions by pointing at UI [selectables](https://docs.unity3d.com/Manual/script-Selectable.html) in space. See [tracked-type input](supported-ui-input-types-tracked.md). \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/ui-input-module-reference.md b/Packages/com.unity.inputsystem/Documentation~/ui-input-module-reference.md index b6fbabff5a..a24f6e7863 100644 --- a/Packages/com.unity.inputsystem/Documentation~/ui-input-module-reference.md +++ b/Packages/com.unity.inputsystem/Documentation~/ui-input-module-reference.md @@ -10,5 +10,5 @@ Use the following properties to configure [InputSystemUIInputModule](../api/Unit |[Move Repeat Rate](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_moveRepeatDelay)|The interval (in seconds) between generating repeat navigation events when the __Move__ Action stays actuated. Note that this is capped by the frame rate; there will not be more than one move repeat event each frame so if the frame rate dips below the repeat rate, the effective repeat rate will be lower than this setting.| |[Actions Asset](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_actionsAsset)|An [Input Action Asset](ActionAssets.md) containing all the Actions to control the UI. You can choose which Actions in the Asset correspond to which UI inputs using the following properties.

By default, this references a built-in Asset named *DefaultInputActions*, which contains common default Actions for driving UI. If you want to set up your own Actions, [create a custom Input Action Asset](ActionAssets.md#creating-input-action-assets) and assign it here. When you assign a new Asset reference to this field in the Inspector, the Editor attempts to automatically map Actions to UI inputs based on common naming conventions.| |[Deselect on Background Click](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_deselectOnBackgroundClick)|By default, when the pointer is clicked and does not hit any `GameObject`, the current selection is cleared. This, however, can get in the way of keyboard and gamepad navigation which will want to work off the currently selected object. To prevent automatic deselection, set this property to false.| -|[Pointer Behavior](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_pointerBehavior)|How to deal with multiple pointers feeding input into the UI. See [pointer-type input](#pointer-type-input). The options are:

- **Single Mouse or Pen But Multi Touch And Track**: Behaves like **Single Unified Pointer** for all input that is not classified as touch or tracked input, and behaves like **All Pointers As Is** for tracked and touch input.
- **Single Unified Pointer**: All pointer input is unified such that there is only ever a single pointer. This includes touch and tracked input.
- **All Pointers As Is**: The UI Input Module does not unify any pointer input. Any device, including touch and tracked devices that feed pointer input actions, has its own pointer (or multiple pointers for touch input).| +|[Pointer Behavior](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_pointerBehavior)|How to deal with multiple pointers feeding input into the UI. See [pointer-type input](supported-ui-input-types-pointer.md). The options are:

- **Single Mouse or Pen But Multi Touch And Track**: Behaves like **Single Unified Pointer** for all input that is not classified as touch or tracked input, and behaves like **All Pointers As Is** for tracked and touch input.
- **Single Unified Pointer**: All pointer input is unified such that there is only ever a single pointer. This includes touch and tracked input.
- **All Pointers As Is**: The UI Input Module does not unify any pointer input. Any device, including touch and tracked devices that feed pointer input actions, has its own pointer (or multiple pointers for touch input).| |[Cursor Lock Behavior](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_cursorLockBehavior)|Controls the origin point of UI raycasts when the cursor is locked. | \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/understand-ui-compatibility.md b/Packages/com.unity.inputsystem/Documentation~/understand-ui-compatibility.md index f8d838113a..c2d96405e8 100644 --- a/Packages/com.unity.inputsystem/Documentation~/understand-ui-compatibility.md +++ b/Packages/com.unity.inputsystem/Documentation~/understand-ui-compatibility.md @@ -1,7 +1,7 @@ # Understand UI system compatibility Unity has [three major UI solutions](https://docs.unity3d.com/Manual/UIToolkits.html). The Input System package's compatibility and workflow with these solutions varies depending on which UI solution you are using, and which version of Unity you are using. -The three main UI systems are **UI Toolkit**, **Unity UI**, and **IMGUI**. Some systems and versions require that you use the Input System’s [UI Input Module component](using-ui-input-module) to pass actions from the Input System to the UI. +The three main UI systems are **UI Toolkit**, **Unity UI**, and **IMGUI**. Some systems and versions require that you use the Input System’s [UI Input Module component](using-ui-input-module.md) to pass actions from the Input System to the UI. ## Compatibility summary UI system|Compatible|UI Input Module component @@ -14,7 +14,7 @@ IMGUI|No|n/a ## UI Toolkit compatibility [**UI Toolkit**](https://docs.unity3d.com/Manual/UIElements.html), also known as "UI Elements", is an XML/CSS style UI solution. -- In versions of Unity prior to 2023.2, you must use the [UI Input Module component](using-ui-input-module) to pass actions from the Input System to the UI. +- In versions of Unity prior to 2023.2, you must use the [UI Input Module component](using-ui-input-module.md) to pass actions from the Input System to the UI. - From Unity 2023.2 and onwards, the UI actions defined in the default [project-wide actions](./about-project-wide-actions.md) directly map to UI Toolkit input.

For more information on how to configure UI Toolkit input, refer to UI Toolkit [Runtime UI event system and input handling](https://docs.unity3d.com/Manual/UIE-Runtime-Event-System.html). @@ -38,7 +38,7 @@ However, the following script invokes the handler in both cases: ``` ### UI Toolkit XR support -XR ([tracked-type input](#tracked-type-input)) is not yet supported in combination with UI Toolkit. This means that you cannot use devices such as VR controllers to operate interfaces created with UI Toolkit. +XR ([tracked-type input](supported-ui-input-types-tracked.md)) is not yet supported in combination with UI Toolkit. This means that you cannot use devices such as VR controllers to operate interfaces created with UI Toolkit. ### UI Toolkit raycasting UI Toolkit handles raycasting internally. No separate raycaster component is necessary. This means that UI Toolkit does not support [TrackedDeviceRaycaster](../api/UnityEngine.InputSystem.UI.TrackedDeviceRaycaster.html). @@ -46,7 +46,7 @@ UI Toolkit handles raycasting internally. No separate raycaster component is nec ## Unity UI (uGUI) compatibility [**Unity UI**](https://docs.unity3d.com/Packages/com.unity.ugui@latest), also known as "uGUI", is a GameObject and Component-based UI solution). -When using uGUI, you always need to use the [UI Input Module component](using-ui-input-module) to pass actions from the Input System to the UI. +When using uGUI, you always need to use the [UI Input Module component](using-ui-input-module.md) to pass actions from the Input System to the UI. The uGUI package contains an older equivalent module called **[Standalone Input Module](https://docs.unity3d.com/Manual/script-StandaloneInputModule.html)**, which performs the same kind of integration between the Unity UI and the legacy Input Manager system. @@ -55,4 +55,4 @@ If you have one of these older Standalone Input Module components on a GameObjec ## IMGUI compatibility [**IMGUI**](https://docs.unity3d.com/Manual/GUIScriptingGuide.html) is a script-based "Immediate Mode" UI which uses the [`OnGUI`](https://docs.unity3d.com/ScriptReference/MonoBehaviour.OnGUI.html) method. -The Input System package is not compatible with IMGUI. However you can still use the Input System for other parts of your project, such as gameplay. For more information, refer to [Use IMGUI alongside the Input System package](#immediate-mode-gui). +The Input System package is not compatible with IMGUI. However you can still use the Input System for other parts of your project, such as gameplay. For more information, refer to [Use IMGUI alongside the Input System package](use-imgui-alongside-input-system.md). From b86f6a7f86de2c48f5e4b1c05903442403a85a2b Mon Sep 17 00:00:00 2001 From: Siobhan Date: Tue, 28 Jan 2025 11:43:03 +0000 Subject: [PATCH 05/15] Deleted old files --- .../Documentation~/UISupport.md | 313 ------------------ ...upported-ui-input-types-ui-input-module.md | 66 ---- 2 files changed, 379 deletions(-) delete mode 100644 Packages/com.unity.inputsystem/Documentation~/UISupport.md delete mode 100644 Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-ui-input-module.md diff --git a/Packages/com.unity.inputsystem/Documentation~/UISupport.md b/Packages/com.unity.inputsystem/Documentation~/UISupport.md deleted file mode 100644 index 50faf08ac3..0000000000 --- a/Packages/com.unity.inputsystem/Documentation~/UISupport.md +++ /dev/null @@ -1,313 +0,0 @@ ---- -uid: input-system-ui-support ---- -# UI support - -- [Overview and compatibility](#overview-and-compatibility) -- [Setting up UI input](#setting-up-ui-input) -- [Required Actions for UI](#required-actions-for-ui) -- [The UI Input Module component](#the-ui-input-module-component) - - [Using the UI Input Module](#using-the-ui-input-module) - - [UI Input Module properties](#ui-input-module-properties) - - [How the bindings work](#how-the-bindings-work) - - [Other notes about the UI Input Module](#other-notes-about-the-ui-input-module) -- [Multiplayer UIs](#multiplayer-uis) -- [Virtual mouse cursor control](#virtual-mouse-cursor-control) - - [Using the Virtual Mouse component](#using-the-virtual-mouse-component) -- [Distinguishing between UI and game input](#distinguishing-between-ui-and-game-input) - - [Handling ambiguities for pointer-type input](#handling-ambiguities-for-pointer-type-input) - - [Handling ambiguities for navigation-type input](#handling-ambiguities-for-navigation-type-input) -- [Immediate Mode GUI](#immediate-mode-gui) - - -## Overview and compatibility - -Unity has [various UI solutions](https://docs.unity3d.com/Manual/UIToolkits.html). The Input System package's compatibility and workflow with these solutions varies depending on which UI solution you are using, and which version of Unity you are using. - -In some cases you must use the **UI Input Module** (a component supplied in the Input System package) to define which actions are passed through from the Input System to the UI. - -The three main UI solutions are **UI Toolkit**, **Unity UI**, and **IMGUI**. The compatibility and workflow for each of these are as follows: - -**For [**UI Toolkit**](https://docs.unity3d.com/Manual/UIElements.html), also known as "UI Elements" (an XML/CSS style UI solution):** - -- From Unity 2023.2 and onwards, the UI actions defined in the default [project-wide actions](./about-project-wide-actions.md) directly map to UI Toolkit input. You do not need to use the UI Input Module component.

-- In versions of Unity prior to 2023.2, you must use the UI Input Module component to define which actions are passed through from the Input System to the UI. -- Refer to UI Toolkit [Runtime UI event system and input handling](https://docs.unity3d.com/Manual/UIE-Runtime-Event-System.html) for more information on how to configure UI Toolkit input. - -**For [**Unity UI**](https://docs.unity3d.com/Packages/com.unity.ugui@latest), also known as "uGUI" (a GameObject and Component style UI solution):** - -When using Unity UI (uGUI), you must always use the UI Input Module component to define which actions are passed through from the Input System to the UI. - -**For [**IMGUI**](https://docs.unity3d.com/Manual/GUIScriptingGuide.html) (a script-based "Immediate Mode" UI using the [`OnGUI`](https://docs.unity3d.com/ScriptReference/MonoBehaviour.OnGUI.html) method):** - -The Input System package is **not compatible** with IMGUI, however you can still use the Input System for other parts of your project such as gameplay. See the [Immediate Mode GUI](#immediate-mode-gui) section for more information. - -The compatibility above is summarized in the following table: - -UI Solution|Compatible|UI Input Module component --|-|- -UI Toolkit (2023.2+)|Yes|Not required -UI Toolkit (pre 2023.2)|Yes|Required -Unity UI (uGUI)|Yes|Required -IMGUI|No|n/a - - -## Setting up UI input - -The default [project-wide actions](./about-project-wide-actions.md) comes with a "**UI**" Action Map, that contains all the actions required for UI interaction (shown in the image below). You can configure the bindings for these actions in the [Actions Editor](./ActionsEditor.md). Go to **Project Settings > Input System Package**, then select "**UI**" in the Action Maps column. - -![ProjectSettingsInputActionsUIActionMap](Images/ProjectSettingsInputActionsUIActionMap.png) - -## Required Actions for UI - -The default project-wide actions comes with all the required actions to be compatible with UI Toolkit and Unity UI. - -You can modify, add, or remove bindings to the named actions in the UI action map to suit your project, however in order to remain compatible with UI Toolkit, the name of the action map ("**UI**"), the names of the actions it contains, and their respective **Action Types** must remain the same. - -These specific actions and types, which are expected by the [UI Input Module](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html) class, are as follows: - -**Action**|**Action Type**|**Control Type**|**Description** --|-|-|- -Navigate|PassThrough|Vector2|A vector used to select the currently active UI [selectable](https://docs.unity3d.com/Manual/script-Selectable.html) in gamepad or arrow-key [navigation-type input](#navigation-type-input). -Submit|Button|Button|Submits the currently selected UI [selectable](https://docs.unity3d.com/Manual/script-Selectable.html) in [navigation-type input](#navigation-type-input) -Cancel|Button|Button|Exits any interaction with the currently selected UI [selectable](https://docs.unity3d.com/Manual/script-Selectable.html) in [navigation-type input](#navigation-type-input) -Point|PassThrough|Vector2|A 2D screen position. The cursor for [pointer-type](#pointer-type-input) interaction. -Click|PassThrough|Button|The primary button for [pointer-type](#pointer-type-input) interaction. -RightClick|PassThrough|Button|The secondary button for [pointer-type](#pointer-type-input) interaction. -MiddleClick|PassThrough|Button|The middle button for [pointer-type](#pointer-type-input) interaction. -ScrollWheel|PassThrough|Vector2|The scrolling gesture for [pointer-type](#pointer-type-input) interaction. -Tracked Device Position|PassThrough|Vector3|A 3D position of one or multiple spatial tracking devices, such as XR hand controllers. In combination with Tracked Device Orientation, this allows XR-style UI interactions by pointing at UI [selectables](https://docs.unity3d.com/Manual/script-Selectable.html) in space. See [tracked-type input](#tracked-type-input). -Tracked Device Orientation|PassThrough|Quaternion|a `Quaternion` representing the rotation of one or multiple spatial tracking devices, such as XR hand controllers. In combination with [Tracked Device Position](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_trackedDevicePosition), this allows XR-style UI interactions by pointing at UI [selectables](https://docs.unity3d.com/Manual/script-Selectable.html) in space. See [tracked-type input](#tracked-type-input). - -You can also reset the UI action map to its default bindings by selecting **Reset** from the **More (⋮)** menu, at the top right of the actions editor window. However, this will reset both the 'Player' and 'UI' action maps to their default bindings. - -## The UI Input Module component - -When working with Unity UI (uGUI), or when using UI Toolkit in versions of Unity prior to Unity 2023.2, you must use the **UI Input Module** component which defines which actions are passed through to your UI, as well as some other UI-related input settings. -> **Note:** -> If you have an instance of the [Input System UI Input Module](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html) component in your scene, the settings on that component takes priority and are used instead of the UI settings in your project-wide actions. Also, The UI action map will be enabled, along with the default action map specified on any UI Input Module component in the scene. - -The UI Input module is implemented in the class [`InputSystemUIInputModule`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html). - -### Using the UI Input Module - -The UI Input Module is a component which you must add to a GameObject in your scene in order for your UI to receive input from the Input System. To do this: - -1. Create a new empty GameObject -2. Click [**Add Component**](https://docs.unity3d.com/Manual/UsingComponents.html) in the inspector -3. In the search field displayed, type "Input System UI Input Module" -4. Select **Input System UI Input Module** to add it to the GameObject. - -![InputSystemUIInputModule](Images/InputSystemUIInputModuleAdd.png) - - -### UI Input Module properties - -![InputSystemUIInputModule](Images/InputSystemUIInputModule.png) - -You can use the following properties to configure [InputSystemUIInputModule](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html): - -|**Property**|**Description**| -|--------|-----------| -|[Move Repeat Delay](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_moveRepeatDelay)|The initial delay (in seconds) between generating an initial [IMoveHandler.OnMove](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/api/UnityEngine.EventSystems.IMoveHandler.html) navigation event and generating repeated navigation events when the __Move__ Action stays actuated.| -|[Move Repeat Rate](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_moveRepeatDelay)|The interval (in seconds) between generating repeat navigation events when the __Move__ Action stays actuated. Note that this is capped by the frame rate; there will not be more than one move repeat event each frame so if the frame rate dips below the repeat rate, the effective repeat rate will be lower than this setting.| -|[Actions Asset](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_actionsAsset)|An [Input Action Asset](ActionAssets.md) containing all the Actions to control the UI. You can choose which Actions in the Asset correspond to which UI inputs using the following properties.

By default, this references a built-in Asset named *DefaultInputActions*, which contains common default Actions for driving UI. If you want to set up your own Actions, [create a custom Input Action Asset](ActionAssets.md#creating-input-action-assets) and assign it here. When you assign a new Asset reference to this field in the Inspector, the Editor attempts to automatically map Actions to UI inputs based on common naming conventions.| -|[Deselect on Background Click](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_deselectOnBackgroundClick)|By default, when the pointer is clicked and does not hit any `GameObject`, the current selection is cleared. This, however, can get in the way of keyboard and gamepad navigation which will want to work off the currently selected object. To prevent automatic deselection, set this property to false.| -|[Pointer Behavior](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_pointerBehavior)|How to deal with multiple pointers feeding input into the UI. See [pointer-type input](#pointer-type-input).| -|[Cursor Lock Behavior](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_cursorLockBehavior)|Controls the origin point of UI raycasts when the cursor is locked. | - - -### How the bindings work - -The UI input module can deal with three different types of input: - -- Pointer-type input -- Navigation-type input -- Tracked-type input - -For each of these types of input, input is sourced and combined from a specific set of Actions as detailed below. - -#### Pointer-type input - -To the UI, a pointer is a position from which clicks and scrolls can be triggered to interact with UI elements at the pointer's position. Pointer-type input is sourced from [point](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_point), [leftClick](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_leftClick), [rightClick](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_rightClick), [middleClick](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_middleClick), and [scrollWheel](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_scrollWheel). - -The UI input module does not have an association between pointers and cursors. In general, the UI is oblivious to whether a cursor exists for a particular pointer. However, for mouse and pen input, the UI input module will respect [Cusor.lockState](https://docs.unity3d.com/ScriptReference/Cursor-lockState.html) and pin the pointer position at `(-1,-1)` whenever the cursor is locked. This behavior can be changed through the [Cursor Lock Behavior](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_cursorLockBehavior) property of the [InputSystemUIInputModule](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html). - -Multiple pointer Devices may feed input into a single UI input module. Also, in the case of [Touchscreen](../api/UnityEngine.InputSystem.Touchscreen.html), a single Device can have the ability to have multiple concurrent pointers (each finger contact is one pointer). - -Because multiple pointer Devices can feed into the same set of Actions, it is important to set the [action type](./RespondingToActions.md#action-types) to [PassThrough](../api/UnityEngine.InputSystem.InputActionType.html#UnityEngine_InputSystem_InputActionType_PassThrough). This ensures that no filtering is applied to input on these actions and that instead every input is relayed as is. - -From the perspective of [InputSystemUIInputModule](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html), each [InputDevice](../api/UnityEngine.InputSystem.InputDevice.html) that has one or more controls bound to one of the pointer-type actions is considered a unique pointer. Also, for each [Touchscreen](../api/UnityEngine.InputSystem.Touchscreen.html) devices, each separate [TouchControl](../api/UnityEngine.InputSystem.Controls.TouchControl.html) that has one or more of its controls bound to the those actions is considered its own unique pointer as well. Each pointer receives a unique [pointerId](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/api/UnityEngine.EventSystems.PointerEventData.html#UnityEngine_EventSystems_PointerEventData_pointerId) which generally corresponds to the [deviceId](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_deviceId) of the pointer. However, for touch, this will be a combination of [deviceId](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_deviceId) and [touchId](../api/UnityEngine.InputSystem.Controls.TouchControl.html#UnityEngine_InputSystem_Controls_TouchControl_touchId). Use [ExtendedPointerEventData.touchId](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html#UnityEngine_InputSystem_UI_ExtendedPointerEventData_touchId) to find the ID for a touch event. - -You can influence how the input module deals with concurrent input from multiple pointers using the [Pointer Behavior](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_pointerBehavior) setting. - -|**Pointer Behavior**|**Description**| -|------------------|-----------| -|[Single Mouse or Pen But Multi Touch And Track](../api/UnityEngine.InputSystem.UI.UIPointerBehavior.html#UnityEngine_InputSystem_UI_UIPointerBehavior_SingleMouseOrPenButMultiTouchAndTrack)|Behaves like [Single Unified Pointer](../api/UnityEngine.InputSystem.UI.UIPointerBehavior.html#UnityEngine_InputSystem_UI_UIPointerBehavior_SingleUnifiedPointer) for all input that is not classified as touch or tracked input, and behaves like [All Pointers As Is](../api/UnityEngine.InputSystem.UI.UIPointerBehavior.html#UnityEngine_InputSystem_UI_UIPointerBehavior_AllPointersAsIs) for tracked and touch input.

If concurrent input is received on a [Mouse](../api/UnityEngine.InputSystem.Mouse.html) and [`Pen`](../api/UnityEngine.InputSystem.Pen.html), for example, the input of both is fed into the same UI pointer instance. The position input of one will overwrite the position of the other.

Note that when input is received from touch or tracked devices, the single unified pointer for mice and pens is __removed__ including [IPointerExit](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/api/UnityEngine.EventSystems.IPointerExitHandler.html) events being sent in case the mouse/pen cursor is currently hovering over objects.

This is the default behavior.| -|[Single Unified Pointer](../api/UnityEngine.InputSystem.UI.UIPointerBehavior.html#UnityEngine_InputSystem_UI_UIPointerBehavior_SingleUnifiedPointer)|All pointer input is unified such that there is only ever a single pointer. This includes touch and tracked input. This means, for example, that regardless how many devices feed input into [Point](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_point), only the last such input in a frame will take effect and become the current UI pointer's position.| -|[All Pointers As Is](../api/UnityEngine.InputSystem.UI.UIPointerBehavior.html#UnityEngine_InputSystem_UI_UIPointerBehavior_AllPointersAsIs)|The UI input module will not unify any pointer input. Any device, including touch and tracked devices that feed input pointer-type actions, will be its own pointer (or multiple pointers for touch input).

Note: This might mean that there will be an arbitrary number of pointers in the UI, and several objects might be pointed at concurrently.| - -If you bind a device to a pointer-type action such as [Left Click](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_leftClick) without also binding it to [Point](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_point), the UI input module will recognize the device as not being able to point and try to route its input into that of another pointer. For example, if you bind [Left Click](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_leftClick) to the `Space` key and [Point](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_point) to the position of the mouse, then pressing the space bar will result in a left click at the current position of the mouse. - -For pointer-type input (as well as for [tracked-type input](#tracked-type-input)), [InputSystemUIInputModule](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html) will send [ExtendedPointerEventData](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html) instances which are an extended version of the base `PointerEventData`. These events contain additional data such as the [device](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html#UnityEngine_InputSystem_UI_ExtendedPointerEventData_device) and [pointer type](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html#UnityEngine_InputSystem_UI_ExtendedPointerEventData_pointerType) which the event has been generated from. - -#### Navigation-type input - -Navigation-type input controls the current selection based on motion read from the [move](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_move) action. Additionally, input from -[submit](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_submit) will trigger `ISubmitHandler` on the currently selected object and -[cancel](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_cancel) will trigger `ICancelHandler` on it. - -Unlike with [pointer-type](#pointer-type-input), where multiple pointer inputs may exist concurrently (think two touches or left- and right-hand tracked input), navigation-type input does not have multiple concurrent instances. In other words, only a single [move](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_move) vector and a single [submit](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_submit) and [cancel](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_cancel) input will be processed by the UI module each frame. However, these inputs need not necessarily come from one single Device always. Arbitrary many inputs can be bound to the respective actions. - -While, [move](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_move) should be set to [PassThrough](../api/UnityEngine.InputSystem.InputActionType.html#UnityEngine_InputSystem_InputActionType_PassThrough) Action type, it is important that [submit](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_submit) and -[cancel](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_cancel) be set to the [Button](../api/UnityEngine.InputSystem.InputActionType.html#UnityEngine_InputSystem_InputActionType_Button) Action type. - -Navigation input is non-positional, that is, unlike with pointer-type input, there is no screen position associcated with these actions. Rather, navigation actions always operate on the current selection. - -#### Tracked-type input - -Input from [tracked devices](../api/UnityEngine.InputSystem.TrackedDevice.html) such as [XR controllers](../api/UnityEngine.InputSystem.XR.XRController.html) and [HMDs](../api/UnityEngine.InputSystem.XR.XRHMD.html) essentially behaves like [pointer-type input](#pointer-type-input). The main difference is that the world-space device position and orientation sourced from [trackedDevicePosition](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_trackedDevicePosition) and [trackedDeviceOrientation](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_trackedDeviceOrientation) is translated into a screen-space position via raycasting. - -> **Important:** ->Because multiple tracked Devices can feed into the same set of Actions, it is important to set the [action type](./RespondingToActions.md#action-types) to [PassThrough](../api/UnityEngine.InputSystem.InputActionType.html#UnityEngine_InputSystem_InputActionType_PassThrough). This ensures that no filtering is applied to input on these actions and that instead every input is relayed as is. - -For this raycasting to work, you need to add [TrackedDeviceRaycaster](../api/UnityEngine.InputSystem.UI.TrackedDeviceRaycaster.html) to the `GameObject` that has the UI's `Canvas` component. This `GameObject` will usually have a `GraphicRaycaster` component which, however, only works for 2D screen-space raycasting. You can put [TrackedDeviceRaycaster](../api/UnityEngine.InputSystem.UI.TrackedDeviceRaycaster.html) alongside `GraphicRaycaster` and both can be enabled at the same time without advserse effect. - -![TrackedDeviceRayster Add Component](Images/TrackedDeviceRaycasterComponentMenu.png) - -![TrackedDeviceRayster Properties](Images/TrackedDeviceRaycaster.png) - -Clicks on tracked devices do not differ from other [pointer-type input](#pointer-type-input). Therefore, actions such as [Left Click](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_leftClick) work for tracked devices just like they work for other pointers. - -### Other notes about the UI Input Module - -#### Upgrading from the Input Manager and the older Standalone Input Module - -The Unity UI (uGUI) package contains an older equivalent module called "**[Standalone Input Module](https://docs.unity3d.com/Manual/script-StandaloneInputModule.html)**" which performs the same kind of integration between the Unity UI and the legacy Input Manager system. - -If you have one of these older Standalone Input Module components on a GameObject in your project, and the Input System is installed, Unity displays a button in the Inspector offering to automatically replace it with the equivalent newer Input System UI Input Module for you. - -#### UI Input Module priority - -The UI Input Module component is not required with UI Toolkit in Unity 2023.2 and onwards. However, if you do use it, the settings on that component take priority over the UI settings in your project-wide actions. - -#### Technical details - -Input support for both [Unity UI](https://docs.unity3d.com/Manual/com.unity.ugui.html) and [UI Toolkit](https://docs.unity3d.com/Manual/UIElements.html) is based on the same [EventSystem](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/manual/EventSystem.html) and [BaseInputModule](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/manual/InputModules.html) subsystem. In other words, the same input setup based on [InputSystemUIInputModule](#setting-up-ui-input) supports input in either UI solution and nothing extra needs to be done. - -Internally, UI Toolkit installs an event listener in the form of the `PanelEventHandler` component which intercepts events that `InputSystemUIInputModule` sends and translates them into UI Toolkit-specific events that are then routed into the visual tree. If you employ `EventSystem.SetUITookitEventSystemOverride`, this default mechanism is bypassed. - ->**Note:** ->XR ([tracked-type input](#tracked-type-input)) is not yet supported in combination with UI Toolkit. This means that you cannot use devices such as VR controllers to operate interfaces created with UI Toolkit. - -There are some additional things worth noting: - -* UI Toolkit handles raycasting internally. No separate raycaster component is needed like for uGUI. This means that [TrackedDeviceRaycaster](../api/UnityEngine.InputSystem.UI.TrackedDeviceRaycaster.html) does not work together with UI Toolkit. -* A pointer click and a gamepad submit action are distinct at the event level in UI Toolkit. This means that if you, for example, do - ```CSharp - button.RegisterCallback(_ => ButtonWasClicked()); - ``` - the handler is not invoked when the button is "clicked" with the gamepad (a `NavigationSubmitEvent` and not a `ClickEvent`). If, however, you do - ```CSharp - button.clicked += () => ButtonWasClicked(); - ``` - the handle is invoked in both cases. - - - - -## Multiplayer UIs - -The Input System can also handle multiple separate UI instances on the screen controlled separately from different input Bindings. This is useful if you want to have multiple local players share a single screen with different controllers, so that every player can control their own UI instance. To allow this, you need to replace the [Event System](https://docs.unity3d.com/Manual/script-EventSystem.html) component from Unity with the Input System's [Multiplayer Event System](../api/UnityEngine.InputSystem.UI.MultiplayerEventSystem.html) component. - -![MultiplayerEventSystem](Images/MultiplayerEventSystem.png) - -Unlike the Event System component, you can have multiple Multiplayer Event Systems active in the Scene at the same time. That way, you can have multiple players, each with their own UI Input Module and Multiplayer Event System components, and each player can have their own set of Actions driving their own UI instance. If you are using the [Player Input](player-input-component.md) component, you can also set it to automatically configure the player's UI Input Module to use the player's Actions. See the documentation on [Player Input](player-input-component.md#ui-input) to learn how. - -The properties of the Multiplayer Event System component are identical to those from the Event System component. Additionally, the Multplayer Event System component adds a [Player Root](../api/UnityEngine.InputSystem.UI.MultiplayerEventSystem.html#UnityEngine_InputSystem_UI_MultiplayerEventSystem_playerRoot) property, which you can set to a GameObject that contains all the UI [selectables](https://docs.unity3d.com/Manual/script-Selectable.html) this event system should handle in its hierarchy. Mouse input that this event system processes then ignores any UI selectables which are not on any GameObject in the Hierarchy under [Player Root](../api/UnityEngine.InputSystem.UI.MultiplayerEventSystem.html#UnityEngine_InputSystem_UI_MultiplayerEventSystem_playerRoot). - -## Virtual mouse cursor control - -If your application uses gamepads and joysticks as an input, you can use the [navigation Actions](#navigation-type-input) to operate the UI. However, it usually involves extra work to make the UI work well with navigation. An alternative way to operate the UI is to allow gamepads and joysticks to drive the cursor from a "virtual mouse cursor". - -The Input System package provides a **Virtual Mouse** component for this purpose. - -> **Note**: This component is only compatible with the [Unity UI](https://docs.unity3d.com/Manual/com.unity.ugui.html) (uGUI) system, and not UI Toolkit. - -To see an example of the Virtual Mouse in a project, see the [Gamepad Mouse Cursor sample](Installation.md#installing-samples) included with the Input System package. - -### Using the Virtual Mouse component - -To set up the Virtual Mouse component with the Unity UI system: - -1. Create a UI GameObject with an **Image** component. This GameObject is the mouse pointer. It can help to rename it "_Pointer_". -2. Parent the pointer GameObject as a child of your **Canvas** GameObject that contains the UI which the cursor should operate on. -3. Set the anchor position of the GameObject's `RectTransform` to the bottom left. -4. Ensure your pointer GameObject is the last child of the Canvas so that the cursor draws on top of everything else. -5. Add a **Virtual Mouse** component to the GameObject. -6. Drag the **Image** component of the pointer GameObject into the **Cursor Graphic** field of the Virtual Mouse component. -7. Drag the **Rect Transform** component of the pointer GameObject to the **Cursor Transform** field of the Virtual Mouse component. -8. If you want the virtual mouse to control the system mouse cursor, set [Cursor Mode](../api/UnityEngine.InputSystem.UI.VirtualMouseInput.html#UnityEngine_InputSystem_UI_VirtualMouseInput_cursorMode) to **Hardware Cursor If Available**. In this mode, the **Cursor Graphic** is hidden when a system mouse is present and you use [Mouse.WarpCursorPosition](../api/UnityEngine.InputSystem.Mouse.html#UnityEngine_InputSystem_Mouse_WarpCursorPosition_UnityEngine_Vector2_) to move the system mouse cursor instead of the software cursor. The transform linked through **Cursor Transform** is not updated in that case. -9. To configure the input to drive the virtual mouse, either add bindings on the various actions (such as **Stick Action**), or enable **Use Reference** and link existing actions from an Input Actions asset. - -> **Important:** -> Make sure the UI Input Module component on the UI's **Event System** does not receive navigation input from the same devices that feed into the Virtual Mouse component. If, for example, the Virtual Mouse component is set up to receive input from gamepads, and `Move`, `Submit`, and `Cancel` on the UI Input Module are also linked to the gamepad, then the UI receives input from the gamepad on two channels. - -![VirtualMouseInput](Images/VirtualMouseInput.png) - -At runtime, the component adds a virtual [Mouse](../api/UnityEngine.InputSystem.Mouse.html) device which the [InputSystemUIInputModule](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html) component picks up. The controls of the `Mouse` are fed input based on the actions configured on the [VirtualMouseInput](../api/UnityEngine.InputSystem.UI.VirtualMouseInput.html) component. - -Note that the resulting [Mouse](../api/UnityEngine.InputSystem.Mouse.html) input is visible in all code that picks up input from the mouse device. You can therefore use the component for mouse simulation elsewhere, not just with [InputSystemUIInputModule](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html). - -> **Note**: -> Do not set up gamepads and joysticks for [navigation input](#navigation-type-input) while using the Virtual Mouse component. If both the Virtual Mouse component and navigation are configured, input is triggered twice: once via the pointer input path, and once via the navigation input path. If you encounter problems such as where buttons are pressed twice, this is likely the problem. - -## Distinguishing between UI and game input - -UI in Unity receives input through the same mechanisms as the input for the rest of your game or app. There is no automatic mechanism that implicitly ensures that if a certain input – such as a click – is consumed by the UI, it is not also received by your gameplay code. - -This can create ambiguities between, for example, code that responds to [`UI.Button.onClick`](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/api/UnityEngine.UI.Button.html#UnityEngine_UI_Button_onClick) and code that responds to [`InputAction.performed`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_performed) of an Action bound to `/leftButton`. - -Whether such ambiguities exist depends on *how* UIs are used. For example, you can avoid ambiguities by implementing your UI in one of the following ways: - -* All interaction is performed through UI elements. A 2D/3D scene is rendered in the background but all interaction is performed through UI events (including those such as 'background' clicks on the `Canvas`). -* UI is overlaid over a 2D/3D scene but the UI elements cannot be interacted with directly. -* UI is overlaid over a 2D/3D scene but there is a clear "mode" switch that determines if interaction is picked up by UI or by the game. For example, a first-person game on desktop may employ a [cursor lock](https://docs.unity3d.com/ScriptReference/Cursor-lockState.html) and direct input to the game while it is engaged whereas it may leave all interaction to the UI while the lock is not engaged. - -When ambiguities arise, they do so differently for [pointer-type](#pointer-type-input) and [navigation-type](#navigation-type-input). - ->[!NOTE] ->A sample called "**UI vs Game Input**" is provided with the package and can be installed from the Unity Package Manager UI in the editor. The sample demonstrates how to deal with a situation where ambiguities arise between inputs for UI and inputs for the game. - -### Handling ambiguities for pointer-type input - -Input from pointers (mice, touchscreens, pens) can be ambiguous depending on whether or not the pointer is over a UI element when initiating an interaction. For example, if there is a button on screen, then clicking on the button may lead to a different outcome than clicking outside of the button and within the game scene. - -If all pointer input is handled via UI events, no ambiguities arise as the UI will implicitly route input to the respective receiver. If, however, input within the UI is handled via UI events and input in the game is handled via [Actions](./actions.md), pointer input will by default lead to *both* being triggered. - -The easiest way to resolve such ambiguities is to respond to in-game actions by [polling](RespondingToActions.md#polling-actions) from inside [`MonoBehaviour.Update`](https://docs.unity3d.com/ScriptReference/MonoBehaviour.Update.html) methods and using [`EventSystem.IsPointerOverGameObject`](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/api/UnityEngine.EventSystems.EventSystem.html?q=ispointerovergameobject#UnityEngine_EventSystems_EventSystem_IsPointerOverGameObject) to find out whether the pointer is over UI or not. Another way is to use [`EventSystem.RaycastAll`](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/api/UnityEngine.EventSystems.EventSystem.html?q=ispointerovergameobj#UnityEngine_EventSystems_EventSystem_RaycastAll_UnityEngine_EventSystems_PointerEventData_System_Collections_Generic_List_UnityEngine_EventSystems_RaycastResult__) to determine if the pointer is currently over UI. - ->[!NOTE] ->Calling [`EventSystem.IsPointerOverGameObject`](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/api/UnityEngine.EventSystems.EventSystem.html?q=ispointerovergameobject#UnityEngine_EventSystems_EventSystem_IsPointerOverGameObject) from within [`InputAction`](../api/UnityEngine.InputSystem.InputAction.html) callbacks such as [`InputAction.performed`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_performed) will lead to a warning. The UI updates separately *after* input processing and UI state thus corresponds to that of the *last* frame/update while input is being processed. - -### Handling ambiguities for navigation-type input - -Ambiguities for navigation-type Devices such as gamepads and joysticks (but also keyboards) cannot arise the same way that it does for pointers. Instead, your application has to decide explicitly whether to use input for the UI's `Move`, `Submit`, and `Cancel` inputs or for the game. This can be done by either splitting control on a Device or by having an explicit mode switch. - -Splitting input on a Device is done by simply using certain controls for operating the UI while using others to operate the game. For example, you could use the d-pad on gamepads to operate UI selection while using the sticks for in-game character control. This setup requires adjusting the bindings used by the UI Actions accordingly. - -An explicit mode switch is implemented by temporarily switching to UI control while suspending in-game Actions. For example, the left trigger on the gamepad could bring up an item selection wheel which then puts the game in a mode where the sticks are controlling UI selection, the A button confirms the selection, and the B button closes the item selection wheel. No ambiguities arise as in-game actions will not respond while the UI is in the "foreground". - - - -## Immediate Mode GUI - -The Input System package does not support [Immediate Mode GUI](https://docs.unity3d.com/Manual/GUIScriptingGuide.html) (IMGUI) methods at runtime. - -However, if you need to use IMGUI for your UI, it is possible to use legacy Input Manager input for your IMGUI user interface, while also using the Input System package for your in-game input. - -When the Editor's [**Active Input Handling**](https://docs.unity3d.com/Manual/class-PlayerSettings.html) setting is set to "**Input System Package**" (which is the default, when using the Input System package), the `OnGUI` methods in your player code won't receive any input events. - -To restore functionality to runtime `OnGUI` methods, you can change the **Active Input Handling** setting to "**Both**". Doing this means that Unity processes the input twice which could introduce a small performance impact. - -This only affects runtime (play mode) OnGUI methods. Editor GUI code is unaffected and will receive input events regardless. diff --git a/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-ui-input-module.md b/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-ui-input-module.md deleted file mode 100644 index 0f9028a0b7..0000000000 --- a/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-ui-input-module.md +++ /dev/null @@ -1,66 +0,0 @@ -# Supported input types in the UI Input Module - -The UI Input Module supports three types of input: - -- [Pointer input](#pointer-input) -- [Navigation input](#navigation-input) -- [Tracked input](#tracked-input) - -For each input type, the UI Input Module sources and combines input from a specific set of Actions. - - - -## Pointer input -To the UI, a pointer is a position from which clicks and scrolls can be triggered to interact with UI elements at the pointer's position. Pointer-type input is sourced from [point](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_point), [leftClick](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_leftClick), [rightClick](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_rightClick), [middleClick](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_middleClick), and [scrollWheel](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_scrollWheel). - - -The UI input module does not have an association between pointers and cursors. In general, the UI is oblivious to whether a cursor exists for a particular pointer. However, for mouse and pen input, the UI input module will respect [Cusor.lockState](https://docs.unity3d.com/ScriptReference/Cursor-lockState.html) and pin the pointer position at `(-1,-1)` whenever the cursor is locked. This behavior can be changed through the [Cursor Lock Behavior](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_cursorLockBehavior) property of the [InputSystemUIInputModule](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html). - - -Multiple pointer Devices can feed input into a single UI input module. Also, in the case of [Touchscreen](../api/UnityEngine.InputSystem.Touchscreen.html), a single Device can have the ability to have multiple concurrent pointers (each finger contact is one pointer). - - -Because multiple pointer Devices can feed into the same set of Actions, it is important to set the [action type](./RespondingToActions.md#action-types) to [PassThrough](../api/UnityEngine.InputSystem.InputActionType.html#UnityEngine_InputSystem_InputActionType_PassThrough). This ensures that no filtering is applied to input on these actions and that instead every input is relayed as is. - - -From the perspective of [InputSystemUIInputModule](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html), each [InputDevice](../api/UnityEngine.InputSystem.InputDevice.html) that has one or more controls bound to one of the pointer-type actions is considered a unique pointer. Also, for each [Touchscreen](../api/UnityEngine.InputSystem.Touchscreen.html) devices, each separate [TouchControl](../api/UnityEngine.InputSystem.Controls.TouchControl.html) that has one or more of its controls bound to the those actions is considered its own unique pointer as well. Each pointer receives a unique [pointerId](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/api/UnityEngine.EventSystems.PointerEventData.html#UnityEngine_EventSystems_PointerEventData_pointerId) which generally corresponds to the [deviceId](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_deviceId) of the pointer. However, for touch, this will be a combination of [deviceId](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_deviceId) and [touchId](../api/UnityEngine.InputSystem.Controls.TouchControl.html#UnityEngine_InputSystem_Controls_TouchControl_touchId). Use [ExtendedPointerEventData.touchId](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html#UnityEngine_InputSystem_UI_ExtendedPointerEventData_touchId) to find the ID for a touch event. - -To influence how the input module deals with concurrent input from multiple pointers, use the UI Input Module’s [**Pointer Behavior**](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_pointerBehavior) setting. - -If you bind a device to a pointer-type action such as [Left Click](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_leftClick) without also binding it to [Point](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_point), the UI input module will recognize the device as not being able to point and try to route its input into that of another pointer. For example, if you bind [Left Click](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_leftClick) to the `Space` key and [Point](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_point) to the position of the mouse, then pressing the space bar will result in a left click at the current position of the mouse. - -For pointer-type input (as well as for [tracked-type input](#tracked-type-input)), [InputSystemUIInputModule](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html) will send [ExtendedPointerEventData](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html) instances which are an extended version of the base `PointerEventData`. These events contain additional data such as the [device](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html#UnityEngine_InputSystem_UI_ExtendedPointerEventData_device) and [pointer type](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html#UnityEngine_InputSystem_UI_ExtendedPointerEventData_pointerType) which the event has been generated from. - - - -## Navigation input - -Navigation-type input controls the current selection based on motion read from the [move](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_move) action. Additionally, input from -[submit](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_submit) will trigger `ISubmitHandler` on the currently selected object and -[cancel](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_cancel) will trigger `ICancelHandler` on it. - -Unlike with [pointer-type](#pointer-type-input), where multiple pointer inputs may exist concurrently (think two touches or left- and right-hand tracked input), navigation-type input does not have multiple concurrent instances. In other words, only a single [move](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_move) vector and a single [submit](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_submit) and [cancel](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_cancel) input will be processed by the UI module each frame. However, these inputs need not necessarily come from one single Device always. Arbitrary many inputs can be bound to the respective actions. - -While, [move](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_move) should be set to [PassThrough](../api/UnityEngine.InputSystem.InputActionType.html#UnityEngine_InputSystem_InputActionType_PassThrough) Action type, it is important that [submit](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_submit) and -[cancel](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_cancel) be set to the [Button](../api/UnityEngine.InputSystem.InputActionType.html#UnityEngine_InputSystem_InputActionType_Button) Action type. - -Navigation input is non-positional, that is, unlike with pointer-type input, there is no screen position associcated with these actions. Rather, navigation actions always operate on the current selection. - - - - -## Tracked input - -Input from [tracked devices](../api/UnityEngine.InputSystem.TrackedDevice.html) such as [XR controllers](../api/UnityEngine.InputSystem.XR.XRController.html) and [HMDs](../api/UnityEngine.InputSystem.XR.XRHMD.html) essentially behaves like [pointer-type input](#pointer-type-input). The main difference is that the world-space device position and orientation sourced from [trackedDevicePosition](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_trackedDevicePosition) and [trackedDeviceOrientation](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_trackedDeviceOrientation) is translated into a screen-space position via raycasting. - - -> **Important:** ->Because multiple tracked Devices can feed into the same set of Actions, it is important to set the [action type](./RespondingToActions.md#action-types) to [PassThrough](../api/UnityEngine.InputSystem.InputActionType.html#UnityEngine_InputSystem_InputActionType_PassThrough). This ensures that no filtering is applied to input on these actions and that instead every input is relayed as is. - -For this raycasting to work, you need to add [TrackedDeviceRaycaster](../api/UnityEngine.InputSystem.UI.TrackedDeviceRaycaster.html) to the `GameObject` that has the UI's `Canvas` component. This `GameObject` will usually have a `GraphicRaycaster` component which, however, only works for 2D screen-space raycasting. You can put [TrackedDeviceRaycaster](../api/UnityEngine.InputSystem.UI.TrackedDeviceRaycaster.html) alongside `GraphicRaycaster` and both can be enabled at the same time without advserse effect. - -![TrackedDeviceRayster Add Component](Images/TrackedDeviceRaycasterComponentMenu.png) - -![TrackedDeviceRayster Properties](Images/TrackedDeviceRaycaster.png) - -Clicks on tracked devices do not differ from other [pointer-type input](#pointer-type-input). Therefore, actions such as [Left Click](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_leftClick) work for tracked devices just like they work for other pointers. \ No newline at end of file From a92400796f03167be72f4f7779dcff2ed49c6442 Mon Sep 17 00:00:00 2001 From: Siobhan Date: Tue, 4 Feb 2025 11:08:20 +0000 Subject: [PATCH 06/15] Updates from PR review --- .../configure-ui-input-action-map.md | 23 +++++++++++++++---- .../configure-virtual-mouse-input.md | 15 ++++++++---- .../create-custom-on-screen-control.md | 4 ++-- .../create-on-screen-stick-control.md | 4 ++-- .../distinguishing-ui-game-input.md | 6 ++--- .../introduction-on-screen-controls.md | 7 +++++- .../supported-ui-input-types-navigation.md | 15 ++++++------ .../supported-ui-input-types-pointer.md | 14 +++++------ .../supported-ui-input-types-tracked.md | 2 +- .../ui-input-module-reference.md | 19 ++++++++------- .../virtual-mouse-ui-cursor-control.md | 3 ++- 11 files changed, 70 insertions(+), 42 deletions(-) diff --git a/Packages/com.unity.inputsystem/Documentation~/configure-ui-input-action-map.md b/Packages/com.unity.inputsystem/Documentation~/configure-ui-input-action-map.md index 7a41445368..c589a3a652 100644 --- a/Packages/com.unity.inputsystem/Documentation~/configure-ui-input-action-map.md +++ b/Packages/com.unity.inputsystem/Documentation~/configure-ui-input-action-map.md @@ -9,15 +9,28 @@ To open the Actions Editor: ![ProjectSettingsInputActionsUIActionMap](Images/ProjectSettingsInputActionsUIActionMap.png) - The default [Project-Wide Actions asset](./about-project-wide-actions.md) comes with all the required actions to be compatible with UI Toolkit and Unity UI. -You can modify, add, or remove bindings to the named actions in the UI action map to suit your project, however in order to remain compatible with UI Toolkit, the name of the action map ("**UI**"), the names of the actions it contains, and their respective **Action Types** must remain the same. +## Modify UI input actions + +You can modify, add, or remove bindings to the named actions in the UI action map to suit your project. However, to remain compatible with UI Toolkit, you must not change: + +* The name of the action map (**UI**) +* The names of the actions it contains +* Their respective **Action Types**. + +To see the specific actions and types that the [UI Input Module](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html) class expects, refer to the [UI Action Map reference](ui-action-map-reference). + +## Reset the UI action map + +>[!IMPORTANT] +>These instructions reset both the UI action map and the Player action map to their default bindings. -To see the specific actions and types that are expected by the [UI Input Module](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html) class, refer to the [UI Action Map reference](ui-action-map-reference). +To reset the UI action map to its default bindings: -You can also reset the UI action map to its default bindings by selecting **Reset** from the **More (⋮)** menu, at the top right of the actions editor window. However, this resets both the 'Player' and 'UI' action maps to their default bindings. +1. Open the **More (⋮)** menu, at the top-right of the Input Actions Editor window. +1. Select **Reset**. -To restore functionality to runtime `OnGUI` methods, you can change the **Active Input Handling** setting to "**Both**". Doing this means that Unity processes the input twice which could introduce a small performance impact. +To restore functionality to runtime `OnGUI` methods, you can change the **Active Input Handling** setting to **Both**. Doing this means that Unity processes the input twice, which could introduce a small performance impact. This only affects runtime (play mode) `OnGUI` methods. Editor GUI code is unaffected and continues to receive input events. \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/configure-virtual-mouse-input.md b/Packages/com.unity.inputsystem/Documentation~/configure-virtual-mouse-input.md index 6cde1b55fe..69d771909e 100644 --- a/Packages/com.unity.inputsystem/Documentation~/configure-virtual-mouse-input.md +++ b/Packages/com.unity.inputsystem/Documentation~/configure-virtual-mouse-input.md @@ -10,13 +10,18 @@ To configure the Virtual Mouse component with the Unity UI system: 7. Drag the **Rect Transform** component of the pointer GameObject to the **Cursor Transform** field of the Virtual Mouse component. >[!NOTE] -> Do not set up gamepads and joysticks for [navigation input](supported-ui-input-types-navigation.md) while using the Virtual Mouse component. If, for example, the Virtual Mouse component is configured to receive input from gamepads, and `Move`, `Submit`, and `Cancel` on the UI Input Module are also linked to the gamepad, then the UI receives input from the gamepad on two channels, and triggers the input twice. - -If you want the virtual mouse to control the system mouse cursor: -Set [Cursor Mode](../api/UnityEngine.InputSystem.UI.VirtualMouseInput.html#UnityEngine_InputSystem_UI_VirtualMouseInput_cursorMode) to **Hardware Cursor If Available**. In this mode, the **Cursor Graphic** is hidden when a system mouse is present and you use [Mouse.WarpCursorPosition](../api/UnityEngine.InputSystem.Mouse.html#UnityEngine_InputSystem_Mouse_WarpCursorPosition_UnityEngine_Vector2_) to move the system mouse cursor instead of the software cursor. The transform linked through **Cursor Transform** is not updated in that case. +> Do not set up gamepads and joysticks for [navigation input](supported-ui-input-types-navigation.md) while using the Virtual Mouse component. If, for example, the Virtual Mouse component is configured to receive input from gamepads, and `Move`, `Submit`, and `Cancel` on the UI Input Module are also linked to the gamepad, then the UI receives input from the gamepad on two channels, and triggers the input twice. +## Control the virtual mouse via the Input System To configure the input to drive the virtual mouse, do one of the following: * Add bindings on the various actions (such as **Stick Action**). -* Enable **Use Reference** and link existing actions from an Input Actions asset. \ No newline at end of file +* Enable **Use Reference** and link existing actions from an Input Actions asset. + +## Control the system mouse cursor with the virtual mouse + +To set the virtual mouse to control the system mouse cursor: +1. Set [Cursor Mode](../api/UnityEngine.InputSystem.UI.VirtualMouseInput.html#UnityEngine_InputSystem_UI_VirtualMouseInput_cursorMode) to **Hardware Cursor If Available**. + +In this mode, the **Cursor Graphic** is hidden when a system mouse is present, and you use [Mouse.WarpCursorPosition](../api/UnityEngine.InputSystem.Mouse.html#UnityEngine_InputSystem_Mouse_WarpCursorPosition_UnityEngine_Vector2_) to move the system mouse cursor instead of the software cursor. The transform linked through **Cursor Transform** is not updated. \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/create-custom-on-screen-control.md b/Packages/com.unity.inputsystem/Documentation~/create-custom-on-screen-control.md index 1200e9e8cb..5068c0feb1 100644 --- a/Packages/com.unity.inputsystem/Documentation~/create-custom-on-screen-control.md +++ b/Packages/com.unity.inputsystem/Documentation~/create-custom-on-screen-control.md @@ -1,6 +1,6 @@ -## Create a custom on-screen Control +# Create a custom on-screen Control -You can add support for new types of [Input Controls](Controls.md) by extending [`OnScreenControl`](../api/UnityEngine.InputSystem.OnScreen.OnScreenControl.html). An easy example to follow is [`OnScreenButton`](../api/UnityEngine.InputSystem.OnScreen.OnScreenButton.html). +To create custom [Input Controls](Controls.md), you can extend [`OnScreenControl`](../api/UnityEngine.InputSystem.OnScreen.OnScreenControl.html). ```CSharp [AddComponentMenu("Input/On-Screen Button")] diff --git a/Packages/com.unity.inputsystem/Documentation~/create-on-screen-stick-control.md b/Packages/com.unity.inputsystem/Documentation~/create-on-screen-stick-control.md index 6a294944bb..5627830918 100644 --- a/Packages/com.unity.inputsystem/Documentation~/create-on-screen-stick-control.md +++ b/Packages/com.unity.inputsystem/Documentation~/create-on-screen-stick-control.md @@ -14,9 +14,9 @@ In-between, the stick moves according to the pointer being dragged (`IDragHandle If you want to be notified when the user starts and/or stops touching the on-screen stick, implement `IPointerDownHandler` and/or `IPointerUpHandler` on a component and add it to the stick `GameObject`. -### Isolated mode +## Isolated mode -The [`OnScreenStick`](../api/UnityEngine.InputSystem.OnScreen.OnScreenStick.html) simulates input events from the device specified in the [`OnScreenControl.control`](../api/UnityEngine.InputSystem.OnScreen.OnScreenControl.html#UnityEngine_InputSystem_OnScreen_OnScreenControl_control) property. To the Input System itself, these are normal events and can cause the paired device to change in games and applications where dynamic device switching is used, for example when the [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) component is used with the [`PlayerInput.neverAutoSwitchControlSchemes`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_neverAutoSwitchControlSchemes)) propety set to false. As the stick is dragged around, the paired device will alternate between the device that owns the pointer (mouse, touch, pen etc) and the device from the control path, which can result in jittery movement of the on-screen stick. +The [`OnScreenStick`](../api/UnityEngine.InputSystem.OnScreen.OnScreenStick.html) simulates input events from the device specified in the [`OnScreenControl.control`](../api/UnityEngine.InputSystem.OnScreen.OnScreenControl.html#UnityEngine_InputSystem_OnScreen_OnScreenControl_control) property. To the Input System itself, these are normal events and can cause the paired device to change in games and applications where dynamic device switching is used, for example when the [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) component is used with the [`PlayerInput.neverAutoSwitchControlSchemes`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_neverAutoSwitchControlSchemes) propety set to false. As the stick is dragged around, the paired device will alternate between the device that owns the pointer (mouse, touch, pen etc) and the device from the control path, which can result in jittery movement of the on-screen stick. Use Isolated Input Actions to fix this. This mode uses a local set of Input Action instances to drive interaction with the stick, and not the actions defined in the UI. The downside of this mode is that pointer actions will be duplicated in both the on-screen stick component and any Input Action Assets being used to drive the UI. Note that if a set of bindings is not specified for the Pointer Down Action and Pointer Move Actions, the following defaults will be used: diff --git a/Packages/com.unity.inputsystem/Documentation~/distinguishing-ui-game-input.md b/Packages/com.unity.inputsystem/Documentation~/distinguishing-ui-game-input.md index 43e4e839b4..15bed13ef9 100644 --- a/Packages/com.unity.inputsystem/Documentation~/distinguishing-ui-game-input.md +++ b/Packages/com.unity.inputsystem/Documentation~/distinguishing-ui-game-input.md @@ -4,9 +4,9 @@ UI in Unity receives input through the same mechanisms as the input for the rest This can create ambiguities between, for example, code that responds to [`UI.Button.onClick`](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/api/UnityEngine.UI.Button.html#UnityEngine_UI_Button_onClick) and code that responds to [`InputAction.performed`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_performed) of an Action bound to `/leftButton`. -Whether such ambiguities exist depends on *how* UIs are used. For example, you can avoid ambiguities by implementing your UI in one of the following ways: +Whether such ambiguities exist depends on how UIs are used. For example, you can avoid ambiguities by implementing your UI in one of the following ways: -* Perform all interaction through UI elements. Render a 2D/3D scene in the background, but perform all interaction through UI events (including those such as 'background' clicks on the `Canvas`). +* Perform all interaction through UI elements. Render a scene in the background, but perform all interaction through UI events (including those such as 'background' clicks on the `Canvas`). * Place UI over a 2D/3D scene, but don’t let the user directly interact with the UI. * Place UI over a 2D/3D scene, but create a clear "mode" switch that determines whether interaction applies to the UI or the scene. For example, a first-person game on desktop might employ a [cursor lock](https://docs.unity3d.com/ScriptReference/Cursor-lockState.html) which directs input to the game when it is engaged, and to the UI when it is not engaged. @@ -28,7 +28,7 @@ The easiest way to resolve such ambiguities is to respond to in-game actions by ## Handling navigation input ambiguities -Ambiguities for navigation-type Devices such as gamepads and joysticks (but also keyboards) cannot arise the same way that it does for pointers. Instead, your application has to decide explicitly whether to use input for the UI's `Move`, `Submit`, and `Cancel` inputs or for the game. This can be done by either splitting control on a Device or by having an explicit mode switch. +For navigation-type devices such as gamepads, joysticks, and keyboards, you must decide explicitly whether to use input for the UI's `Move`, `Submit`, and `Cancel` inputs or for the game. This can be done by either splitting control on a Device or by having an explicit mode switch. Splitting input on a Device is done by simply using certain controls for operating the UI while using others to operate the game. For example, you could use the d-pad on gamepads to operate UI selection while using the sticks for in-game character control. This setup requires adjusting the bindings used by the UI Actions accordingly. diff --git a/Packages/com.unity.inputsystem/Documentation~/introduction-on-screen-controls.md b/Packages/com.unity.inputsystem/Documentation~/introduction-on-screen-controls.md index c484c8ad78..3bc6cd7204 100644 --- a/Packages/com.unity.inputsystem/Documentation~/introduction-on-screen-controls.md +++ b/Packages/com.unity.inputsystem/Documentation~/introduction-on-screen-controls.md @@ -5,7 +5,12 @@ uid: input-system-on-screen You can use on-screen Controls to simulate Input Devices with UI widgets that the user interacts with on the screen. The most prominent example is the use of stick and button widgets on touchscreens to emulate a joystick or gamepad. -There are currently two on-screen Control types implemented out of the box: [on-screen buttons](create-on-screen-button-control.md) and [on-screen sticks](create-on-screen-stick-control.md). You can implement custom Controls by extending the base [`OnScreenControl`](../api/UnityEngine.InputSystem.OnScreen.OnScreenControl.html) class (see documentation on [writing custom on screen Controls](create-custom-on-screen-control.md) to learn more). +There are two built-in on-screen Control types: + +* [On-screen buttons](create-on-screen-button-control.md) +* [On-screen sticks](create-on-screen-stick-control.md) + +You can implement custom Controls by extending the base [`OnScreenControl`](../api/UnityEngine.InputSystem.OnScreen.OnScreenControl.html) class (see documentation on [writing custom on screen Controls](create-custom-on-screen-control.md) to learn more). >[!NOTE] >On-screen Controls don't have a predefined visual representation. It's up to you to set up the visual aspect of a Control (for example, by adding a sprite or UI component to the GameObject). On-screen Controls take care of the interaction logic and of setting up and generating input from interactions. diff --git a/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-navigation.md b/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-navigation.md index 3374c1a5dd..9eef31a957 100644 --- a/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-navigation.md +++ b/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-navigation.md @@ -1,12 +1,13 @@ ## Navigation input UI support -Navigation-type input controls the current selection based on motion read from the [move](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_move) action. Additionally, input from -[submit](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_submit) will trigger `ISubmitHandler` on the currently selected object and -[cancel](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_cancel) will trigger `ICancelHandler` on it. +Navigation-type input controls the current selection based on motion read from the [`move`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_move) action. Additionally, input from +[`submit`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_submit) will trigger `ISubmitHandler` on the currently selected object and +[`cancel`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_cancel) will trigger `ICancelHandler` on it. -Unlike with [pointer-type](supported-ui-input-types-pointer.md), where multiple pointer inputs may exist concurrently (think two touches or left- and right-hand tracked input), navigation-type input does not have multiple concurrent instances. In other words, only a single [move](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_move) vector and a single [submit](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_submit) and [cancel](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_cancel) input will be processed by the UI module each frame. However, these inputs need not necessarily come from one single Device always. Arbitrary many inputs can be bound to the respective actions. +Navigation-type input doesn't have multiple concurrent instances. The UI module only processes a single [`move`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_move) vector and a single [`submit`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_submit) and [`cancel`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_cancel) input per frame. However, these inputs don't need to come from one single device. You can bind multiple inputs to each action. -While, [move](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_move) should be set to [PassThrough](../api/UnityEngine.InputSystem.InputActionType.html#UnityEngine_InputSystem_InputActionType_PassThrough) Action type, it is important that [submit](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_submit) and -[cancel](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_cancel) be set to the [Button](../api/UnityEngine.InputSystem.InputActionType.html#UnityEngine_InputSystem_InputActionType_Button) Action type. +>[!IMPORTANT] +>The [`move`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_move) input must be set to the [`PassThrough`](../api/UnityEngine.InputSystem.InputActionType.html#UnityEngine_InputSystem_InputActionType_PassThrough) action type. The [`submit`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_submit) and +[`cancel`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_cancel) inputs must be set to the [`Button`](../api/UnityEngine.InputSystem.InputActionType.html#UnityEngine_InputSystem_InputActionType_Button) Action type. -Navigation input is non-positional, that is, unlike with pointer-type input, there is no screen position associated with these actions. Rather, navigation actions always operate on the current selection. \ No newline at end of file +Navigation input is non-positional. There is no screen position associated with navigation actions. Instead, navigation actions always operate on the current selection. \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-pointer.md b/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-pointer.md index c46d0ebcac..fc4c5aebb8 100644 --- a/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-pointer.md +++ b/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-pointer.md @@ -1,20 +1,20 @@ # Pointer input UI support -To the UI, a pointer is a position from which clicks and scrolls can be triggered to interact with UI elements at the pointer's position. Pointer-type input is sourced from [point](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_point), [leftClick](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_leftClick), [rightClick](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_rightClick), [middleClick](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_middleClick), and [scrollWheel](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_scrollWheel). +To the UI, a pointer is a position from which clicks and scrolls can be triggered to interact with UI elements at the pointer's position. Pointer-type input is sourced from [`point`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_point), [`leftClick`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_leftClick), [`rightClick`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_rightClick), [`middleClick`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_middleClick), and [`scrollWheel`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_scrollWheel). -The UI input module does not have an association between pointers and cursors. In general, the UI is oblivious to whether a cursor exists for a particular pointer. However, for mouse and pen input, the UI input module will respect [Cusor.lockState](https://docs.unity3d.com/ScriptReference/Cursor-lockState.html) and pin the pointer position at `(-1,-1)` whenever the cursor is locked. This behavior can be changed through the [Cursor Lock Behavior](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_cursorLockBehavior) property of the [InputSystemUIInputModule](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html). +The UI input model doesn't associate pointers and cursors together. However, it pins the pointer for mouse and pen input at `1,1` depending on the state of `Cursor.lockState`. To adjust the cursor lock behavior, use the Cursor lock behavior property of [`InputSystemUIInputModule`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html). -Multiple pointer Devices can feed input into a single UI input module. Also, in the case of [Touchscreen](../api/UnityEngine.InputSystem.Touchscreen.html), a single Device can have the ability to have multiple concurrent pointers (each finger contact is one pointer). +Multiple pointer Devices can feed input into a single UI input module. Also, in the case of [`Touchscreen`](../api/UnityEngine.InputSystem.Touchscreen.html), a single Device can have the ability to have multiple concurrent pointers (each finger contact is one pointer). Because multiple pointer Devices can feed into the same set of Actions, it is important to set the [action type](./RespondingToActions.md#action-types) to [PassThrough](../api/UnityEngine.InputSystem.InputActionType.html#UnityEngine_InputSystem_InputActionType_PassThrough). This ensures that no filtering is applied to input on these actions and that instead every input is relayed as is. -From the perspective of [InputSystemUIInputModule](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html), each [InputDevice](../api/UnityEngine.InputSystem.InputDevice.html) that has one or more controls bound to one of the pointer-type actions is considered a unique pointer. Also, for each [Touchscreen](../api/UnityEngine.InputSystem.Touchscreen.html) devices, each separate [TouchControl](../api/UnityEngine.InputSystem.Controls.TouchControl.html) that has one or more of its controls bound to the those actions is considered its own unique pointer as well. Each pointer receives a unique [pointerId](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/api/UnityEngine.EventSystems.PointerEventData.html#UnityEngine_EventSystems_PointerEventData_pointerId) which generally corresponds to the [deviceId](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_deviceId) of the pointer. However, for touch, this will be a combination of [deviceId](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_deviceId) and [touchId](../api/UnityEngine.InputSystem.Controls.TouchControl.html#UnityEngine_InputSystem_Controls_TouchControl_touchId). Use [ExtendedPointerEventData.touchId](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html#UnityEngine_InputSystem_UI_ExtendedPointerEventData_touchId) to find the ID for a touch event. +From the perspective of [`InputSystemUIInputModule`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html), each [`InputDevice`](../api/UnityEngine.InputSystem.InputDevice.html) that has one or more controls bound to one of the pointer-type actions is considered a unique pointer. Also, for each [`Touchscreen`](../api/UnityEngine.InputSystem.Touchscreen.html) devices, each separate [`TouchControl`](../api/UnityEngine.InputSystem.Controls.TouchControl.html) that has one or more of its controls bound to the those actions is considered its own unique pointer as well. Each pointer receives a unique [`pointerId`](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/api/UnityEngine.EventSystems.PointerEventData.html#UnityEngine_EventSystems_PointerEventData_pointerId) which generally corresponds to the [`deviceId`](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_deviceId) of the pointer. However, for touch, this will be a combination of [deviceId](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_deviceId) and [`touchId`](../api/UnityEngine.InputSystem.Controls.TouchControl.html#UnityEngine_InputSystem_Controls_TouchControl_touchId). Use [`ExtendedPointerEventData.touchId`](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html#UnityEngine_InputSystem_UI_ExtendedPointerEventData_touchId) to find the ID for a touch event. To influence how the input module deals with concurrent input from multiple pointers, use the UI Input Module’s [**Pointer Behavior**](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_pointerBehavior) setting. If you bind a device to a pointer-type action such as [Left Click](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_leftClick) without also binding it to [Point](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_point), the UI input module will recognize the device as not being able to point and try to route its input into that of another pointer. For example, if you bind [Left Click](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_leftClick) to the `Space` key and [Point](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_point) to the position of the mouse, then pressing the space bar will result in a left click at the current position of the mouse. -For pointer-type input (as well as for [tracked-type input](supported-ui-input-types-tracked.md)), [InputSystemUIInputModule](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html) sends [ExtendedPointerEventData](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html) instances which are an extended version of the base `PointerEventData`. These events contain additional data such as the [device](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html#UnityEngine_InputSystem_UI_ExtendedPointerEventData_device) and [pointer type](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html#UnityEngine_InputSystem_UI_ExtendedPointerEventData_pointerType) which the event has been generated from. +For pointer-type input (as well as for [tracked-type input](supported-ui-input-types-tracked.md)), [`InputSystemUIInputModule`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html) sends [`ExtendedPointerEventData`](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html) instances which are an extended version of the base `PointerEventData`. These events contain additional data such as the [device](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html#UnityEngine_InputSystem_UI_ExtendedPointerEventData_device) and [pointer type](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html#UnityEngine_InputSystem_UI_ExtendedPointerEventData_pointerType) which the event has been generated from. ## Pointer behavior @@ -23,9 +23,9 @@ The UI Module's [Pointer Behavior](../api/UnityEngine.InputSystem.UI.InputSystem ### Unify mouse and pen input but separate touch and track input [Single Mouse or Pen But Multi Touch And Track](../api/UnityEngine.InputSystem.UI.UIPointerBehavior.html#UnityEngine_InputSystem_UI_UIPointerBehavior_SingleMouseOrPenButMultiTouchAndTrack) behaves like [Single Unified Pointer](../api/UnityEngine.InputSystem.UI.UIPointerBehavior.html#UnityEngine_InputSystem_UI_UIPointerBehavior_SingleUnifiedPointer) for all input that is not classified as touch or tracked input, and behaves like [All Pointers As Is](../api/UnityEngine.InputSystem.UI.UIPointerBehavior.html#UnityEngine_InputSystem_UI_UIPointerBehavior_AllPointersAsIs) for tracked and touch input. -If concurrent input is received on a [Mouse](../api/UnityEngine.InputSystem.Mouse.html) and [`Pen`](../api/UnityEngine.InputSystem.Pen.html), for example, the input of both is fed into the same UI pointer instance. The position input of one will overwrite the position of the other. +If concurrent input is received on a [`Mouse`](../api/UnityEngine.InputSystem.Mouse.html) and [`Pen`](../api/UnityEngine.InputSystem.Pen.html), for example, the input of both is fed into the same UI pointer instance. The position input of one will overwrite the position of the other. -When input is received from touch or tracked devices, the single unified pointer for mice and pens is removed, including [IPointerExit](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/api/UnityEngine.EventSystems.IPointerExitHandler.html) events being sent in case the mouse/pen cursor is currently hovering over objects. This is the default behavior. +When input is received from touch or tracked devices, the single unified pointer for mice and pens is removed, including [`IPointerExit`](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/api/UnityEngine.EventSystems.IPointerExitHandler.html) events being sent in case the mouse/pen cursor is currently hovering over objects. This is the default behavior. ### Unify all pointer inputs [Single Unified Pointer](../api/UnityEngine.InputSystem.UI.UIPointerBehavior.html#UnityEngine_InputSystem_UI_UIPointerBehavior_SingleUnifiedPointer) unifies all pointer input so that there is only ever a single pointer. This includes touch and tracked input. This means, for example, that regardless of how many devices feed input into [Point](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_point), only the last input in a frame takes effect and becomes the current UI pointer's position. diff --git a/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-tracked.md b/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-tracked.md index 6847cb4094..c56f19f456 100644 --- a/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-tracked.md +++ b/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-tracked.md @@ -1,6 +1,6 @@ # Tracked input UI support -Input from [tracked devices](../api/UnityEngine.InputSystem.TrackedDevice.html) such as [XR controllers](../api/UnityEngine.InputSystem.XR.XRController.html) and [HMDs](../api/UnityEngine.InputSystem.XR.XRHMD.html) essentially behaves like [pointer-type input](supported-ui-input-types-pointer.md). The main difference is that the world-space device position and orientation sourced from [trackedDevicePosition](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_trackedDevicePosition) and [trackedDeviceOrientation](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_trackedDeviceOrientation) is translated into a screen-space position via raycasting. +Input from [tracked devices](../api/UnityEngine.InputSystem.TrackedDevice.html) such as [XR controllers](../api/UnityEngine.InputSystem.XR.XRController.html) and [HMDs](../api/UnityEngine.InputSystem.XR.XRHMD.html) behaves like [pointer-type input](supported-ui-input-types-pointer.md), but the Input System uses raycasting to translate the world-space device position and orientation sourced from [`trackedDevicePosition`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_trackedDevicePosition) and [`trackedDeviceOrientation`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_trackedDeviceOrientation) into a screen-space position. >[!IMPORTANT] >Because multiple tracked Devices can feed into the same set of Actions, it is important to set the [action type](./RespondingToActions.md#action-types) to [PassThrough](../api/UnityEngine.InputSystem.InputActionType.html#UnityEngine_InputSystem_InputActionType_PassThrough). This ensures that no filtering is applied to input on these actions and that instead every input is relayed as is. diff --git a/Packages/com.unity.inputsystem/Documentation~/ui-input-module-reference.md b/Packages/com.unity.inputsystem/Documentation~/ui-input-module-reference.md index a24f6e7863..422fd6e43a 100644 --- a/Packages/com.unity.inputsystem/Documentation~/ui-input-module-reference.md +++ b/Packages/com.unity.inputsystem/Documentation~/ui-input-module-reference.md @@ -1,14 +1,17 @@ # UI Input Module component reference -![InputSystemUIInputModule](Images/InputSystemUIInputModule.png) + Use the UI Input Module to configure UI-specific actions and inputs. To view the UI Input Module, refer to [Access the UI Input Module](access-ui-input-module). -Use the following properties to configure [InputSystemUIInputModule](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html): +The properties on the UI Input Module correspond to the [`InputSystemUIInputModule`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html) class. |**Property**|**Description**| |--------|-----------| -|[Move Repeat Delay](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_moveRepeatDelay)|The initial delay (in seconds) between generating an initial [IMoveHandler.OnMove](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/api/UnityEngine.EventSystems.IMoveHandler.html) navigation event and generating repeated navigation events when the __Move__ Action stays actuated.| -|[Move Repeat Rate](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_moveRepeatDelay)|The interval (in seconds) between generating repeat navigation events when the __Move__ Action stays actuated. Note that this is capped by the frame rate; there will not be more than one move repeat event each frame so if the frame rate dips below the repeat rate, the effective repeat rate will be lower than this setting.| -|[Actions Asset](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_actionsAsset)|An [Input Action Asset](ActionAssets.md) containing all the Actions to control the UI. You can choose which Actions in the Asset correspond to which UI inputs using the following properties.

By default, this references a built-in Asset named *DefaultInputActions*, which contains common default Actions for driving UI. If you want to set up your own Actions, [create a custom Input Action Asset](ActionAssets.md#creating-input-action-assets) and assign it here. When you assign a new Asset reference to this field in the Inspector, the Editor attempts to automatically map Actions to UI inputs based on common naming conventions.| -|[Deselect on Background Click](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_deselectOnBackgroundClick)|By default, when the pointer is clicked and does not hit any `GameObject`, the current selection is cleared. This, however, can get in the way of keyboard and gamepad navigation which will want to work off the currently selected object. To prevent automatic deselection, set this property to false.| -|[Pointer Behavior](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_pointerBehavior)|How to deal with multiple pointers feeding input into the UI. See [pointer-type input](supported-ui-input-types-pointer.md). The options are:

- **Single Mouse or Pen But Multi Touch And Track**: Behaves like **Single Unified Pointer** for all input that is not classified as touch or tracked input, and behaves like **All Pointers As Is** for tracked and touch input.
- **Single Unified Pointer**: All pointer input is unified such that there is only ever a single pointer. This includes touch and tracked input.
- **All Pointers As Is**: The UI Input Module does not unify any pointer input. Any device, including touch and tracked devices that feed pointer input actions, has its own pointer (or multiple pointers for touch input).| -|[Cursor Lock Behavior](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_cursorLockBehavior)|Controls the origin point of UI raycasts when the cursor is locked. | \ No newline at end of file +|Send Pointer Hover to Parent | | +|**Move Repeat Delay**|The initial delay (in seconds) between generating an initial [IMoveHandler.OnMove](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/api/UnityEngine.EventSystems.IMoveHandler.html) navigation event and generating repeated navigation events when the __Move__ Action stays actuated.| +|**Move Repeat Rate**|The interval (in seconds) between generating repeat navigation events when the __Move__ Action stays actuated. Note that this is capped by the frame rate; there will not be more than one move repeat event each frame so if the frame rate dips below the repeat rate, the effective repeat rate will be lower than this setting.| +|**XR Tracking Origin** | Define the transform that represents the real-world transform for tracking devices. | +|**Deselect on Background Click**|Clear the current selection when the pointer is clicked and does not hit any `GameObject`. To prevent automatic deselection, deactivate this property.| +|**Pointer Behavior**|How to deal with multiple pointers feeding input into the UI. See [pointer-type input](supported-ui-input-types-pointer.md). The options are:

- **Single Mouse or Pen But Multi Touch And Track**: Behaves like **Single Unified Pointer** for all input that is not classified as touch or tracked input, and behaves like **All Pointers As Is** for tracked and touch input.
- **Single Unified Pointer**: All pointer input is unified such that there is only ever a single pointer. This includes touch and tracked input.
- **All Pointers As Is**: The UI Input Module does not unify any pointer input. Any device, including touch and tracked devices that feed pointer input actions, has its own pointer (or multiple pointers for touch input).

For more details on these pointer behaviors, refer to [Pointer input UI support: Pointer behavior](supported-ui-input-types-pointer.md#pointer-behavior).| +|**Scroll Delta Per Tick** | Define the scroll wheel speed sent to Unity UI (uGUI) components. The value in this field is a multiplier of the `PointerEventData.scrollDelta` value. | +|**Actions Asset**|An [Input Action Asset](ActionAssets.md) containing all the Actions to control the UI. You can choose which Actions in the Asset correspond to which UI inputs using the following properties.

By default, this references a built-in Asset named `DefaultInputActions`, which contains common default Actions for driving UI. If you want to set up your own Actions, [create a custom Input Action Asset](ActionAssets.md#creating-input-action-assets) and assign it here.

When you assign a new asset reference to this field in the Inspector, the Editor attempts to automatically map actions to UI inputs based on common naming conventions, and lists the actions underneath the **Actions Asset** property.

| +|**Cursor Lock Behavior**|Controls the origin point of UI raycasts when the cursor is locked. By default, the available options are:

- **Outside Screen**
- **Screen Center** | \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/virtual-mouse-ui-cursor-control.md b/Packages/com.unity.inputsystem/Documentation~/virtual-mouse-ui-cursor-control.md index d799fd3690..a34fc0624f 100644 --- a/Packages/com.unity.inputsystem/Documentation~/virtual-mouse-ui-cursor-control.md +++ b/Packages/com.unity.inputsystem/Documentation~/virtual-mouse-ui-cursor-control.md @@ -2,7 +2,8 @@ Use a virtual mouse to allow gamepads and joysticks to control pointer inputs. -**Note**: The Virtual Mouse component is only compatible with the [Unity UI](https://docs.unity3d.com/Manual/com.unity.ugui.html) (uGUI) system, and not UI Toolkit or IMGUI. +>[!NOTE] +>The Virtual Mouse component is only compatible with the [Unity UI](https://docs.unity3d.com/Manual/com.unity.ugui.html) (uGUI) system, and not UI Toolkit or IMGUI. |**Topic**|**Description**| |--------|-----------| From bed9f00c74282166e5c00fbbd69babe2b06d8631 Mon Sep 17 00:00:00 2001 From: Siobhan Date: Tue, 4 Feb 2025 12:20:11 +0000 Subject: [PATCH 07/15] Applied consistent capitalization throughout --- .../configure-multiplayer-ui-input.md | 2 +- .../configure-ui-input-action-map.md | 6 ++--- .../configure-virtual-mouse-input.md | 2 +- .../create-custom-on-screen-control.md | 2 +- .../create-on-screen-button-control.md | 4 ++-- .../create-on-screen-stick-control.md | 14 ++++++------ .../distinguishing-ui-game-input.md | 8 +++---- .../introduction-multiplayer-ui-input.md | 4 ++-- .../introduction-on-screen-controls.md | 18 +++++++-------- .../introduction-ui-input-module.md | 2 +- .../Documentation~/on-screen-controls.md | 10 ++++----- .../Documentation~/ui-action-map-reference.md | 22 +++++++++---------- .../ui-input-module-reference.md | 6 ++--- .../Documentation~/ui-input.md | 6 ++--- 14 files changed, 53 insertions(+), 53 deletions(-) diff --git a/Packages/com.unity.inputsystem/Documentation~/configure-multiplayer-ui-input.md b/Packages/com.unity.inputsystem/Documentation~/configure-multiplayer-ui-input.md index 3c2f9c6585..a00c42425d 100644 --- a/Packages/com.unity.inputsystem/Documentation~/configure-multiplayer-ui-input.md +++ b/Packages/com.unity.inputsystem/Documentation~/configure-multiplayer-ui-input.md @@ -5,7 +5,7 @@ To enable multiplayer UI input: 1. Replace the project’s [Event System](https://docs.unity3d.com/Manual/script-EventSystem.html) component with the Input System's [Multiplayer Event System](../api/UnityEngine.InputSystem.UI.MultiplayerEventSystem.html) component. -For information on how to automatically configure the player's UI Input Module to use Actions from the [Player Input](player-input-component.md) component, refer to documentation on [Player Input: UI Input](player-input-component.md#ui-input) to learn how. +For information on how to automatically configure the player's UI Input Module to use actions from the [Player Input](player-input-component.md) component, refer to documentation on [Player Input: UI Input](player-input-component.md#ui-input) to learn how. To define mouse UI input behaviour for a Multiplayer Event System: diff --git a/Packages/com.unity.inputsystem/Documentation~/configure-ui-input-action-map.md b/Packages/com.unity.inputsystem/Documentation~/configure-ui-input-action-map.md index c589a3a652..8db8ef4cb2 100644 --- a/Packages/com.unity.inputsystem/Documentation~/configure-ui-input-action-map.md +++ b/Packages/com.unity.inputsystem/Documentation~/configure-ui-input-action-map.md @@ -1,6 +1,6 @@ # Configure the UI Input Action Map -The default [Project-Wide Actions asset](./about-project-wide-actions.md) comes with a "**UI**" Action Map, which contains all the actions required for UI interaction. To configure the bindings for these actions, use the [Actions Editor](./actions-editor.md). +The default [project-wide actions asset](./about-project-wide-actions.md) comes with a built-in action map named **UI**, which contains all the actions required for UI interaction. To configure the bindings for these actions, use the [Actions Editor](./actions-editor.md). To open the Actions Editor: @@ -9,7 +9,7 @@ To open the Actions Editor: ![ProjectSettingsInputActionsUIActionMap](Images/ProjectSettingsInputActionsUIActionMap.png) -The default [Project-Wide Actions asset](./about-project-wide-actions.md) comes with all the required actions to be compatible with UI Toolkit and Unity UI. +The default [project-wide actions asset](./about-project-wide-actions.md) comes with all the required actions to be compatible with UI Toolkit and Unity UI. ## Modify UI input actions @@ -19,7 +19,7 @@ You can modify, add, or remove bindings to the named actions in the UI action ma * The names of the actions it contains * Their respective **Action Types**. -To see the specific actions and types that the [UI Input Module](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html) class expects, refer to the [UI Action Map reference](ui-action-map-reference). +To see the specific actions and types that the [UI Input Module](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html) class expects, refer to the [UI action map reference](ui-action-map-reference). ## Reset the UI action map diff --git a/Packages/com.unity.inputsystem/Documentation~/configure-virtual-mouse-input.md b/Packages/com.unity.inputsystem/Documentation~/configure-virtual-mouse-input.md index 69d771909e..082ac08c7d 100644 --- a/Packages/com.unity.inputsystem/Documentation~/configure-virtual-mouse-input.md +++ b/Packages/com.unity.inputsystem/Documentation~/configure-virtual-mouse-input.md @@ -17,7 +17,7 @@ To configure the Virtual Mouse component with the Unity UI system: To configure the input to drive the virtual mouse, do one of the following: * Add bindings on the various actions (such as **Stick Action**). -* Enable **Use Reference** and link existing actions from an Input Actions asset. +* Enable **Use Reference** and link existing actions from an input actions asset. ## Control the system mouse cursor with the virtual mouse diff --git a/Packages/com.unity.inputsystem/Documentation~/create-custom-on-screen-control.md b/Packages/com.unity.inputsystem/Documentation~/create-custom-on-screen-control.md index 5068c0feb1..cd9a241c18 100644 --- a/Packages/com.unity.inputsystem/Documentation~/create-custom-on-screen-control.md +++ b/Packages/com.unity.inputsystem/Documentation~/create-custom-on-screen-control.md @@ -1,6 +1,6 @@ # Create a custom on-screen Control -To create custom [Input Controls](Controls.md), you can extend [`OnScreenControl`](../api/UnityEngine.InputSystem.OnScreen.OnScreenControl.html). +To create custom [input controls](Controls.md), you can extend [`OnScreenControl`](../api/UnityEngine.InputSystem.OnScreen.OnScreenControl.html). ```CSharp [AddComponentMenu("Input/On-Screen Button")] diff --git a/Packages/com.unity.inputsystem/Documentation~/create-on-screen-button-control.md b/Packages/com.unity.inputsystem/Documentation~/create-on-screen-button-control.md index 1a907bb7cc..23a66b736b 100644 --- a/Packages/com.unity.inputsystem/Documentation~/create-on-screen-button-control.md +++ b/Packages/com.unity.inputsystem/Documentation~/create-on-screen-button-control.md @@ -4,8 +4,8 @@ To create an on-screen button: 1. Add a UI `Button` object. 2. Add the [`OnScreenButton`](../api/UnityEngine.InputSystem.OnScreen.OnScreenButton.html) component to it. -3. Set the [`Control Path`](../api/UnityEngine.InputSystem.OnScreen.OnScreenControl.html#UnityEngine_InputSystem_OnScreen_OnScreenControl_controlPath) to refer to a [`ButtonControl`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html) (for example, `/buttonSouth`). The type of device referenced by the control path determines the type of virtual device created by the component. +3. Set the [controlPath](../api/UnityEngine.InputSystem.OnScreen.OnScreenControl.html#UnityEngine_InputSystem_OnScreen_OnScreenControl_controlPath) to refer to a [`ButtonControl`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html) (for example, `/buttonSouth`). The type of device referenced by the control path determines the type of virtual device created by the component. ![OnScreenButton](Images/OnScreenButton.png) -The [`OnScreenButton`](../api/UnityEngine.InputSystem.OnScreen.OnScreenButton.html) component requires the target Control to be a `Button` Control. [`OnScreenButton`](../api/UnityEngine.InputSystem.OnScreen.OnScreenButton.html) sets the target Control value to 1 when it receives a pointer-down (`IPointerDownHandler.OnPointerDown`) event, or 0 when it receives a pointer-up (`IPointerUpHandler.OnPointerUp`) event. \ No newline at end of file +The [`OnScreenButton`](../api/UnityEngine.InputSystem.OnScreen.OnScreenButton.html) component requires the target control to be a `Button` control. [`OnScreenButton`](../api/UnityEngine.InputSystem.OnScreen.OnScreenButton.html) sets the target control value to 1 when it receives a pointer-down (`IPointerDownHandler.OnPointerDown`) event, or 0 when it receives a pointer-up (`IPointerUpHandler.OnPointerUp`) event. \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/create-on-screen-stick-control.md b/Packages/com.unity.inputsystem/Documentation~/create-on-screen-stick-control.md index 5627830918..be73a5356f 100644 --- a/Packages/com.unity.inputsystem/Documentation~/create-on-screen-stick-control.md +++ b/Packages/com.unity.inputsystem/Documentation~/create-on-screen-stick-control.md @@ -1,32 +1,32 @@ -# Create an on-screen stick Control +# Create an on-screen stick control To create an on-screen stick: 1. Create a UI `Image` object. 2. Add the [`OnScreenStick`](../api/UnityEngine.InputSystem.OnScreen.OnScreenStick.html) component to it. -3. Set the [`Control Path`](../api/UnityEngine.InputSystem.OnScreen.OnScreenControl.html#UnityEngine_InputSystem_OnScreen_OnScreenControl_controlPath) to refer to a [`Vector2Control`](../api/UnityEngine.InputSystem.Controls.Vector2Control.html) (for example, `/leftStick`). The type of device referenced by the control path determines the type of virtual device created by the component. +3. Set the [`controlPath`](../api/UnityEngine.InputSystem.OnScreen.OnScreenControl.html#UnityEngine_InputSystem_OnScreen_OnScreenControl_controlPath) to refer to a [`Vector2Control`](../api/UnityEngine.InputSystem.Controls.Vector2Control.html) (for example, `/leftStick`). The type of device referenced by the control path determines the type of virtual device created by the component. ![OnScreenStick](Images/OnScreenStick.png) -The [`OnScreenStick`](../api/UnityEngine.InputSystem.OnScreen.OnScreenStick.html) component requires the target Control to be a `Vector2` Control. [`OnScreenStick`](../api/UnityEngine.InputSystem.OnScreen.OnScreenStick.html) starts the movement of the stick Control when it receives a pointer-down (`IPointerDownHandler.OnPointerDown`) event, and stops it when it receives a pointer-up (`IPointerUpHandler.OnPointerUp`) event. +The [`OnScreenStick`](../api/UnityEngine.InputSystem.OnScreen.OnScreenStick.html) component requires the target control to be a `Vector2` control. [`OnScreenStick`](../api/UnityEngine.InputSystem.OnScreen.OnScreenStick.html) starts the movement of the stick control when it receives a pointer-down (`IPointerDownHandler.OnPointerDown`) event, and stops it when it receives a pointer-up (`IPointerUpHandler.OnPointerUp`) event. In-between, the stick moves according to the pointer being dragged (`IDragHandler.OnDrag`) within a box centered on the pointer-down screen point, and with an edge length defined in the component's __Movement Range__ property. A movement range of 50, for example, means that the stick's on-screen area is 25 pixels up, down, left, and right of the pointer-down point on screen. If you want to be notified when the user starts and/or stops touching the on-screen stick, implement `IPointerDownHandler` and/or `IPointerUpHandler` on a component and add it to the stick `GameObject`. -## Isolated mode +## Isolate stick controls The [`OnScreenStick`](../api/UnityEngine.InputSystem.OnScreen.OnScreenStick.html) simulates input events from the device specified in the [`OnScreenControl.control`](../api/UnityEngine.InputSystem.OnScreen.OnScreenControl.html#UnityEngine_InputSystem_OnScreen_OnScreenControl_control) property. To the Input System itself, these are normal events and can cause the paired device to change in games and applications where dynamic device switching is used, for example when the [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) component is used with the [`PlayerInput.neverAutoSwitchControlSchemes`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_neverAutoSwitchControlSchemes) propety set to false. As the stick is dragged around, the paired device will alternate between the device that owns the pointer (mouse, touch, pen etc) and the device from the control path, which can result in jittery movement of the on-screen stick. -Use Isolated Input Actions to fix this. This mode uses a local set of Input Action instances to drive interaction with the stick, and not the actions defined in the UI. The downside of this mode is that pointer actions will be duplicated in both the on-screen stick component and any Input Action Assets being used to drive the UI. Note that if a set of bindings is not specified for the Pointer Down Action and Pointer Move Actions, the following defaults will be used: +To fix this, enable **Use Isolated Input Actions**. This mode uses a local set of input action instances to drive interaction with the stick, and not the actions defined in the UI. The downside of this mode is that pointer actions will be duplicated in both the on-screen stick component and any input action assets being used to drive the UI. Note that if a set of bindings is not specified for the Pointer Down action and Pointer Move actions, the following defaults will be used: -* Pointer Down Action +* Pointer Down action - `/leftButton` - `/tip` - `/touch*/press` - `/trigger` -* Pointer Move Action +* Pointer Move action - `/position` - `/position` - `/touch*/position` \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/distinguishing-ui-game-input.md b/Packages/com.unity.inputsystem/Documentation~/distinguishing-ui-game-input.md index 15bed13ef9..84d75d8f4e 100644 --- a/Packages/com.unity.inputsystem/Documentation~/distinguishing-ui-game-input.md +++ b/Packages/com.unity.inputsystem/Documentation~/distinguishing-ui-game-input.md @@ -19,7 +19,7 @@ There are specific ambiguities that can arise for [pointer input](supported-ui-i Input from pointers (mice, touchscreens, pens) can be ambiguous depending on whether or not the pointer is over a UI element when initiating an interaction. For example, if there is a button on screen, then clicking on the button may lead to a different outcome than clicking outside of the button and within the game scene. -If all pointer input is handled via UI events, no ambiguities arise as the UI will implicitly route input to the respective receiver. If, however, input within the UI is handled via UI events and input in the game is handled via [Actions](./actions.md), pointer input will by default lead to *both* being triggered. +If all pointer input is handled via UI events, no ambiguities arise as the UI will implicitly route input to the respective receiver. If, however, input within the UI is handled via UI events and input in the game is handled via [actions](./actions.md), pointer input will by default lead to *both* being triggered. The easiest way to resolve such ambiguities is to respond to in-game actions by [polling](RespondingToActions.md#polling-actions) from inside [`MonoBehaviour.Update`](https://docs.unity3d.com/ScriptReference/MonoBehaviour.Update.html) methods and using [`EventSystem.IsPointerOverGameObject`](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/api/UnityEngine.EventSystems.EventSystem.html?q=ispointerovergameobject#UnityEngine_EventSystems_EventSystem_IsPointerOverGameObject) to find out whether the pointer is over UI or not. Another way is to use [`EventSystem.RaycastAll`](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/api/UnityEngine.EventSystems.EventSystem.html?q=ispointerovergameobj#UnityEngine_EventSystems_EventSystem_RaycastAll_UnityEngine_EventSystems_PointerEventData_System_Collections_Generic_List_UnityEngine_EventSystems_RaycastResult__) to determine if the pointer is currently over UI. @@ -28,8 +28,8 @@ The easiest way to resolve such ambiguities is to respond to in-game actions by ## Handling navigation input ambiguities -For navigation-type devices such as gamepads, joysticks, and keyboards, you must decide explicitly whether to use input for the UI's `Move`, `Submit`, and `Cancel` inputs or for the game. This can be done by either splitting control on a Device or by having an explicit mode switch. +For navigation-type devices such as gamepads, joysticks, and keyboards, you must decide explicitly whether to use input for the UI's `Move`, `Submit`, and `Cancel` inputs or for the game. This can be done by either splitting control on a device or by having an explicit mode switch. -Splitting input on a Device is done by simply using certain controls for operating the UI while using others to operate the game. For example, you could use the d-pad on gamepads to operate UI selection while using the sticks for in-game character control. This setup requires adjusting the bindings used by the UI Actions accordingly. +Splitting input on a device is done by simply using certain controls for operating the UI while using others to operate the game. For example, you could use the d-pad on gamepads to operate UI selection while using the sticks for in-game character control. This setup requires adjusting the bindings used by the UI actions accordingly. -An explicit mode switch is implemented by temporarily switching to UI control while suspending in-game Actions. For example, the left trigger on the gamepad could bring up an item selection wheel which then puts the game in a mode where the sticks are controlling UI selection, the A button confirms the selection, and the B button closes the item selection wheel. No ambiguities arise as in-game actions will not respond while the UI is in the "foreground". \ No newline at end of file +An explicit mode switch is implemented by temporarily switching to UI control while suspending in-game actions. For example, the left trigger on the gamepad could bring up an item selection wheel which then puts the game in a mode where the sticks are controlling UI selection, the A button confirms the selection, and the B button closes the item selection wheel. No ambiguities arise as in-game actions will not respond while the UI is in the "foreground". \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/introduction-multiplayer-ui-input.md b/Packages/com.unity.inputsystem/Documentation~/introduction-multiplayer-ui-input.md index 756cb911ca..4137fbc3cb 100644 --- a/Packages/com.unity.inputsystem/Documentation~/introduction-multiplayer-ui-input.md +++ b/Packages/com.unity.inputsystem/Documentation~/introduction-multiplayer-ui-input.md @@ -1,11 +1,11 @@ # Introduction to multiplayer UI input -The Input System can handle multiple separate UI instances on the screen controlled separately by different [Input Bindings](action-bindings.md). This is useful if you want to have multiple local players share a single screen with different controllers, so that every player can control their own UI instance. +The Input System can handle multiple separate UI instances on the screen controlled separately by different [bindings](action-bindings.md). This is useful if you want to have multiple local players share a single screen with different controllers, so that every player can control their own UI instance. To implement multiplayer UI, the Input System uses the Multiplayer Event System. ![MultiplayerEventSystem](Images/MultiplayerEventSystem.png) -You can have multiple Multiplayer Event Systems active in the Scene at the same time. This means you can have multiple players, each with their own [UI Input Module](using-ui-input-module.md) and Multiplayer Event System components, and each player can have their own set of Actions driving their own UI instance. +You can have multiple Multiplayer Event Systems active in the Scene at the same time. This means you can have multiple players, each with their own [UI Input Module](using-ui-input-module.md) and Multiplayer Event System components, and each player can have their own set of actions driving their own UI instance. The properties of the Multiplayer Event System component are mostly identical to those in the [Event System](https://docs.unity3d.com/Manual/script-EventSystem.html) component. However, the Multiplayer Event System component also has a [Player Root](../api/UnityEngine.InputSystem.UI.MultiplayerEventSystem.html#UnityEngine_InputSystem_UI_MultiplayerEventSystem_playerRoot) property, which defines a parent GameObject for UI [selectables](https://docs.unity3d.com/Manual/script-Selectable.html). When each player has a Multiplayer Event System with a **Player** Root assigned, UI navigation input for each player is limited to UI selectables that are child GameObjects of the Player Root. \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/introduction-on-screen-controls.md b/Packages/com.unity.inputsystem/Documentation~/introduction-on-screen-controls.md index 3bc6cd7204..6e29af12c7 100644 --- a/Packages/com.unity.inputsystem/Documentation~/introduction-on-screen-controls.md +++ b/Packages/com.unity.inputsystem/Documentation~/introduction-on-screen-controls.md @@ -1,27 +1,27 @@ --- uid: input-system-on-screen --- -# Introduction to on-screen Controls +# Introduction to on-screen controls -You can use on-screen Controls to simulate Input Devices with UI widgets that the user interacts with on the screen. The most prominent example is the use of stick and button widgets on touchscreens to emulate a joystick or gamepad. +You can use on-screen controls to simulate Input Devices with UI widgets that the user interacts with on the screen. The most prominent example is the use of stick and button widgets on touchscreens to emulate a joystick or gamepad. -There are two built-in on-screen Control types: +There are two built-in on-screen control types: * [On-screen buttons](create-on-screen-button-control.md) * [On-screen sticks](create-on-screen-stick-control.md) -You can implement custom Controls by extending the base [`OnScreenControl`](../api/UnityEngine.InputSystem.OnScreen.OnScreenControl.html) class (see documentation on [writing custom on screen Controls](create-custom-on-screen-control.md) to learn more). +You can implement custom controls by extending the base [`OnScreenControl`](../api/UnityEngine.InputSystem.OnScreen.OnScreenControl.html) class (see documentation on [writing custom on screen controls](create-custom-on-screen-control.md) to learn more). >[!NOTE] ->On-screen Controls don't have a predefined visual representation. It's up to you to set up the visual aspect of a Control (for example, by adding a sprite or UI component to the GameObject). On-screen Controls take care of the interaction logic and of setting up and generating input from interactions. +>On-screen controls don't have a predefined visual representation. It's up to you to set up the visual aspect of a control (for example, by adding a sprite or UI component to the GameObject). On-screen controls take care of the interaction logic and of setting up and generating input from interactions. -Each on-screen Control uses a [Control path](Controls.md#control-paths) to reference the Control that it should report input as. For example, the following on-screen button reports input as the right shoulder button of a gamepad: +Each on-screen control uses a [control path](Controls.md#control-paths) to reference the control that it should report input as. For example, the following on-screen button reports input as the right shoulder button of a gamepad: ![OnScreenButton](Images/OnScreenButton.png) -The collection of on-screen Controls present in a Scene forms one or more [Input Devices](Devices.md). The Input System creates one Input Device for each distinct type of Device the Controls reference. For example, if one on-screen button references `/buttonSouth` and another on-screen button references `/a`, the Input System creates both a `Gamepad` and a `Keyboard`. This happens automatically when the components are enabled. When disabled, the Input System automatically removes the Devices again. +The collection of on-screen controls present in a Scene forms one or more [input devices](Devices.md). The Input System creates one input Device for each distinct type of device the controls reference. For example, if one on-screen button references `/buttonSouth` and another on-screen button references `/a`, the Input System creates both a `Gamepad` and a `Keyboard`. This happens automatically when the components are enabled. When disabled, the Input System automatically removes the devices again. -To query the Control (and, implicitly, the Device) that an on-screen Control feeds into, you can use the [`OnScreenControl.control`](../api/UnityEngine.InputSystem.OnScreen.OnScreenControl.html#UnityEngine_InputSystem_OnScreen_OnScreenControl_control) property. +To query the control (and, implicitly, the device) that an on-screen control feeds into, you can use the [`OnScreenControl.control`](../api/UnityEngine.InputSystem.OnScreen.OnScreenControl.html#UnityEngine_InputSystem_OnScreen_OnScreenControl_control) property. >[!NOTE] ->This design allows you to use on-screen Controls to create input for arbitrary Input Devices, in addition to joysticks and gamepads. \ No newline at end of file +>This design allows you to use on-screen controls to create input for arbitrary input devices, in addition to joysticks and gamepads. \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/introduction-ui-input-module.md b/Packages/com.unity.inputsystem/Documentation~/introduction-ui-input-module.md index d20eb55066..55f49fa13c 100644 --- a/Packages/com.unity.inputsystem/Documentation~/introduction-ui-input-module.md +++ b/Packages/com.unity.inputsystem/Documentation~/introduction-ui-input-module.md @@ -8,5 +8,5 @@ The UI Input module is implemented in the class [`InputSystemUIInputModule`](../ ## Input priority -If you have an instance of the [Input System UI Input Module](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html) component in your scene, the settings on that component takes priority and are used instead of the UI settings in your project-wide actions. The UI Action Map is enabled, along with the default Action Map specified on any UI Input Module component in the scene. +If you have an instance of the [Input System UI Input Module](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html) component in your scene, the settings on that component takes priority and are used instead of the UI settings in your project-wide actions. The UI action map is enabled, along with the default action map specified on any UI Input Module component in the scene. diff --git a/Packages/com.unity.inputsystem/Documentation~/on-screen-controls.md b/Packages/com.unity.inputsystem/Documentation~/on-screen-controls.md index 94e50a06ca..b1bb934de9 100644 --- a/Packages/com.unity.inputsystem/Documentation~/on-screen-controls.md +++ b/Packages/com.unity.inputsystem/Documentation~/on-screen-controls.md @@ -1,13 +1,13 @@ --- uid: input-system-on-screen --- -# On-screen Controls +# On-screen controls Simulate input devices with UI widgets that the user interacts with on the screen. |**Topic**|**Description**| |--------|-----------| -|[Introduction to on-screen Controls](introduction-on-screen-controls.md)| Simulate buttons, sticks, and custom inputs with on-screen Controls. | -|[Create an on-screen button Control](create-on-screen-button-control.md)| Create and configure simulated on-screen button Controls.| -|[Create an on-screen stick Control](create-on-screen-stick-control.md)| Create and configure simulated on-screen stick Controls.| -|[Create a custom on-screen Control](create-custom-on-screen-control.md)| Create and configure custom simulated on-screen Controls.| \ No newline at end of file +|[Introduction to on-screen controls](introduction-on-screen-controls.md)| Simulate buttons, sticks, and custom inputs with on-screen controls. | +|[Create an on-screen button control](create-on-screen-button-control.md)| Create and configure simulated on-screen button controls.| +|[Create an on-screen stick control](create-on-screen-stick-control.md)| Create and configure simulated on-screen stick controls.| +|[Create a custom on-screen control](create-custom-on-screen-control.md)| Create and configure custom simulated on-screen controls.| \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/ui-action-map-reference.md b/Packages/com.unity.inputsystem/Documentation~/ui-action-map-reference.md index 9d469cd2fe..e78364936c 100644 --- a/Packages/com.unity.inputsystem/Documentation~/ui-action-map-reference.md +++ b/Packages/com.unity.inputsystem/Documentation~/ui-action-map-reference.md @@ -1,15 +1,15 @@ # UI Action Map reference -The default [Project-Wide Actions asset](./about-project-wide-actions.md) has a default configuration for UI input. +The default [project-wide actions asset](./about-project-wide-actions.md) has a default configuration for UI input. **Action**|**Action Type**|**Control Type**|**Description** -|-|-|- -Navigate|PassThrough|Vector2|A vector used to select the currently active UI [selectable](https://docs.unity3d.com/Manual/script-Selectable.html) in gamepad or arrow-key [navigation-type input](supported-ui-input-types-navigation.md). -Submit|Button|Button|Submits the currently selected UI [selectable](https://docs.unity3d.com/Manual/script-Selectable.html) in [navigation-type input](supported-ui-input-types-navigation.md) -Cancel|Button|Button|Exits any interaction with the currently selected UI [selectable](https://docs.unity3d.com/Manual/script-Selectable.html) in [navigation-type input](supported-ui-input-types-navigation.md) -Point|PassThrough|Vector2|A 2D screen position. The cursor for [pointer-type](supported-ui-input-types-pointer.md) interaction. -Click|PassThrough|Button|The primary button for [pointer-type](supported-ui-input-types-pointer.md) interaction. -RightClick|PassThrough|Button|The secondary button for [pointer-type](supported-ui-input-types-pointer.md) interaction. -MiddleClick|PassThrough|Button|The middle button for [pointer-type](supported-ui-input-types-pointer.md) interaction. -ScrollWheel|PassThrough|Vector2|The scrolling gesture for [pointer-type](supported-ui-input-types-pointer.md) interaction. -Tracked Device Position|PassThrough|Vector3|A 3D position of one or multiple spatial tracking devices, such as XR hand controllers. In combination with Tracked Device Orientation, this allows XR-style UI interactions by pointing at UI [selectables](https://docs.unity3d.com/Manual/script-Selectable.html) in space. See [tracked-type input](supported-ui-input-types-tracked.md). -Tracked Device Orientation|PassThrough|Quaternion|a `Quaternion` representing the rotation of one or multiple spatial tracking devices, such as XR hand controllers. In combination with [Tracked Device Position](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_trackedDevicePosition), this allows XR-style UI interactions by pointing at UI [selectables](https://docs.unity3d.com/Manual/script-Selectable.html) in space. See [tracked-type input](supported-ui-input-types-tracked.md). \ No newline at end of file +**Navigate**|PassThrough|Vector2|A vector used to select the currently active UI [selectable](https://docs.unity3d.com/Manual/script-Selectable.html) in gamepad or arrow-key [navigation-type input](supported-ui-input-types-navigation.md). +**Submit**|Button|Button|Submits the currently selected UI [selectable](https://docs.unity3d.com/Manual/script-Selectable.html) in [navigation-type input](supported-ui-input-types-navigation.md) +**Cancel**|Button|Button|Exits any interaction with the currently selected UI [selectable](https://docs.unity3d.com/Manual/script-Selectable.html) in [navigation-type input](supported-ui-input-types-navigation.md) +**Point**|PassThrough|Vector2|A 2D screen position. The cursor for [pointer-type](supported-ui-input-types-pointer.md) interaction. +**Click**|PassThrough|Button|The primary button for [pointer-type](supported-ui-input-types-pointer.md) interaction. +**RightClick**|PassThrough|Button|The secondary button for [pointer-type](supported-ui-input-types-pointer.md) interaction. +**MiddleClick**|PassThrough|Button|The middle button for [pointer-type](supported-ui-input-types-pointer.md) interaction. +**ScrollWheel**|PassThrough|Vector2|The scrolling gesture for [pointer-type](supported-ui-input-types-pointer.md) interaction. +**Tracked Device Position**|PassThrough|Vector3|A 3D position of one or multiple spatial tracking devices, such as XR hand controllers. In combination with **Tracked Device Orientation**, this allows XR-style UI interactions by pointing at UI [selectables](https://docs.unity3d.com/Manual/script-Selectable.html) in space. See [tracked-type input](supported-ui-input-types-tracked.md). +**Tracked Device Orientation**|PassThrough|Quaternion|a `Quaternion` representing the rotation of one or multiple spatial tracking devices, such as XR hand controllers. In combination with [Tracked Device Position](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_trackedDevicePosition), this allows XR-style UI interactions by pointing at UI [selectables](https://docs.unity3d.com/Manual/script-Selectable.html) in space. See [tracked-type input](supported-ui-input-types-tracked.md). \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/ui-input-module-reference.md b/Packages/com.unity.inputsystem/Documentation~/ui-input-module-reference.md index 422fd6e43a..18cfcbf4ae 100644 --- a/Packages/com.unity.inputsystem/Documentation~/ui-input-module-reference.md +++ b/Packages/com.unity.inputsystem/Documentation~/ui-input-module-reference.md @@ -7,11 +7,11 @@ The properties on the UI Input Module correspond to the [`InputSystemUIInputModu |**Property**|**Description**| |--------|-----------| |Send Pointer Hover to Parent | | -|**Move Repeat Delay**|The initial delay (in seconds) between generating an initial [IMoveHandler.OnMove](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/api/UnityEngine.EventSystems.IMoveHandler.html) navigation event and generating repeated navigation events when the __Move__ Action stays actuated.| -|**Move Repeat Rate**|The interval (in seconds) between generating repeat navigation events when the __Move__ Action stays actuated. Note that this is capped by the frame rate; there will not be more than one move repeat event each frame so if the frame rate dips below the repeat rate, the effective repeat rate will be lower than this setting.| +|**Move Repeat Delay**|The initial delay (in seconds) between generating an initial [IMoveHandler.OnMove](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/api/UnityEngine.EventSystems.IMoveHandler.html) navigation event and generating repeated navigation events when the __Move__ action stays actuated.| +|**Move Repeat Rate**|The interval (in seconds) between generating repeat navigation events when the __Move__ action stays actuated. Note that this is capped by the frame rate; there will not be more than one move repeat event each frame so if the frame rate dips below the repeat rate, the effective repeat rate will be lower than this setting.| |**XR Tracking Origin** | Define the transform that represents the real-world transform for tracking devices. | |**Deselect on Background Click**|Clear the current selection when the pointer is clicked and does not hit any `GameObject`. To prevent automatic deselection, deactivate this property.| |**Pointer Behavior**|How to deal with multiple pointers feeding input into the UI. See [pointer-type input](supported-ui-input-types-pointer.md). The options are:

- **Single Mouse or Pen But Multi Touch And Track**: Behaves like **Single Unified Pointer** for all input that is not classified as touch or tracked input, and behaves like **All Pointers As Is** for tracked and touch input.
- **Single Unified Pointer**: All pointer input is unified such that there is only ever a single pointer. This includes touch and tracked input.
- **All Pointers As Is**: The UI Input Module does not unify any pointer input. Any device, including touch and tracked devices that feed pointer input actions, has its own pointer (or multiple pointers for touch input).

For more details on these pointer behaviors, refer to [Pointer input UI support: Pointer behavior](supported-ui-input-types-pointer.md#pointer-behavior).| |**Scroll Delta Per Tick** | Define the scroll wheel speed sent to Unity UI (uGUI) components. The value in this field is a multiplier of the `PointerEventData.scrollDelta` value. | -|**Actions Asset**|An [Input Action Asset](ActionAssets.md) containing all the Actions to control the UI. You can choose which Actions in the Asset correspond to which UI inputs using the following properties.

By default, this references a built-in Asset named `DefaultInputActions`, which contains common default Actions for driving UI. If you want to set up your own Actions, [create a custom Input Action Asset](ActionAssets.md#creating-input-action-assets) and assign it here.

When you assign a new asset reference to this field in the Inspector, the Editor attempts to automatically map actions to UI inputs based on common naming conventions, and lists the actions underneath the **Actions Asset** property.

| +|**Actions Asset**|An [action asset](ActionAssets.md) containing all the actions to control the UI. You can choose which actions in the Asset correspond to which UI inputs using the following properties.

By default, this references a built-in asset named `DefaultInputActions`, which contains common default actions for driving UI. If you want to set up your own actions, [create a custom input action asset](ActionAssets.md#creating-input-action-assets) and assign it here.

When you assign a new asset reference to this field in the Inspector, the Editor attempts to automatically map actions to UI inputs based on common naming conventions, and lists the actions underneath the **Actions Asset** property.

| |**Cursor Lock Behavior**|Controls the origin point of UI raycasts when the cursor is locked. By default, the available options are:

- **Outside Screen**
- **Screen Center** | \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/ui-input.md b/Packages/com.unity.inputsystem/Documentation~/ui-input.md index bd5c1315f4..755f8e9742 100644 --- a/Packages/com.unity.inputsystem/Documentation~/ui-input.md +++ b/Packages/com.unity.inputsystem/Documentation~/ui-input.md @@ -5,9 +5,9 @@ The Input System provides support for several UI systems in Unity. This section |**Topic**|**Description**| |--------|-----------| |[Supported UI systems](supported-ui-systems.md)|Understand the compatibility between the Input System and Unity's UI systems.| -|[Configure UI Input Actions](configure-ui-input-action-map.md)|Configure UI Input Actions in the UI Action Map.| -|[UI Action Map reference](ui-action-map-reference.md)|Reference documentation for the Project-Wide Actions Asset's default UI Action Map.| -|[Distinguishing between UI input and game input](distinguishing-ui-game-input.md)|Understand how the Input System and Unity work together to distinguish which Input Actions are intended for UI, and which are intended for the game.| +|[Configure UI input actions](configure-ui-input-action-map.md)|Configure UI input actions in the UI action map.| +|[UI action map reference](ui-action-map-reference.md)|Reference documentation for the default UI action map on the project-wide actions asset.| +|[Distinguishing between UI input and game input](distinguishing-ui-game-input.md)|Understand how the Input System and Unity work together to distinguish which input actions are intended for UI, and which are intended for the game.| |[Virtual mouse for cursor control](virtual-mouse-ui-cursor-control)|Use a virtual mouse to allow gamepads and joysticks to control pointer inputs.| |[Multiplayer UI input](multiplayer-ui)|Configure multiple UI instances, so that multiple players can share a single screen and individually interact with the UI.| |[On-screen controls](on-screen-controls)|Simulate input devices with UI widgets that the user interacts with on the screen.| \ No newline at end of file From c3314888b776d7e13d12dd2fd5adb814eadb8f85 Mon Sep 17 00:00:00 2001 From: Siobhan Date: Tue, 4 Feb 2025 15:50:40 +0000 Subject: [PATCH 08/15] PR review updates, and created virtual mouse component ref --- .../Documentation~/TableOfContents.md | 4 +- .../Documentation~/access-ui-input-module.md | 2 +- ....md => handling-input-target-ambiguity.md} | 22 +++++---- .../introduction-ui-input-module.md | 4 +- .../Documentation~/multiplayer-ui-input.md | 8 ++-- .../Documentation~/on-screen-controls.md | 12 ++--- .../supported-ui-input-types-navigation.md | 3 +- .../supported-ui-input-types-pointer.md | 32 ++++++++----- .../supported-ui-input-types-tracked.md | 4 +- .../supported-ui-input-types.md | 12 ++--- .../Documentation~/supported-ui-systems.md | 10 ++-- .../Documentation~/ui-action-map-reference.md | 24 +++++----- .../ui-input-module-reference.md | 2 +- .../Documentation~/ui-input.md | 20 ++++---- .../understand-ui-compatibility.md | 8 +++- .../use-imgui-alongside-input-system.md | 9 ++-- .../Documentation~/using-ui-input-module.md | 12 ++--- .../virtual-mouse-component-reference.md | 48 +++++++++++++++++++ .../virtual-mouse-ui-cursor-control.md | 8 ++-- 19 files changed, 156 insertions(+), 88 deletions(-) rename Packages/com.unity.inputsystem/Documentation~/{distinguishing-ui-game-input.md => handling-input-target-ambiguity.md} (77%) create mode 100644 Packages/com.unity.inputsystem/Documentation~/virtual-mouse-component-reference.md diff --git a/Packages/com.unity.inputsystem/Documentation~/TableOfContents.md b/Packages/com.unity.inputsystem/Documentation~/TableOfContents.md index 7fc999e8e8..f285f7e8a8 100644 --- a/Packages/com.unity.inputsystem/Documentation~/TableOfContents.md +++ b/Packages/com.unity.inputsystem/Documentation~/TableOfContents.md @@ -69,7 +69,7 @@ * [Joystick support](Joystick.md) * [Sensor support](Sensors.md) * [HID support](HID.md) -* [Input for user interfaces](ui-input.md) +* [UI input](ui-input.md) * [Supported UI systems](supported-ui-systems.md) * [Understand UI system compatibility](understand-ui-compatibility.md) * [Using UI Input Module for UI support](using-ui-input-module.md) @@ -83,7 +83,7 @@ * [Use IMGUI alongside the Input System package](use-imgui-alongside-input-system.md) * [Configure UI Input Actions](configure-ui-input-action-map.md) * [UI Action Map reference](ui-action-map-reference.md) - * [Distinguishing between UI input and game input](distinguishing-ui-game-input.md) + * [Handling input target ambiguity](handling-input-target-ambiguity.md) * [Virtual Mouse for UI cursor control](virtual-mouse-ui-cursor-control.md) * [Introduction to Virtual Mouse for UI cursor control](introduction-virtual-mouse.md) * [Configure a Virtual Mouse for UI input](configure-virtual-mouse-input.md) diff --git a/Packages/com.unity.inputsystem/Documentation~/access-ui-input-module.md b/Packages/com.unity.inputsystem/Documentation~/access-ui-input-module.md index 5d8fa65242..61480114ea 100644 --- a/Packages/com.unity.inputsystem/Documentation~/access-ui-input-module.md +++ b/Packages/com.unity.inputsystem/Documentation~/access-ui-input-module.md @@ -2,7 +2,7 @@ The UI Input Module is a component that passes input actions from the Input System to the UI in your scene. -You must add it to a GameObject in your scene in order for the UI to receive input from the Input System. To do this: +You must add the UI Input Module to a GameObject in your scene, so that the UI can receive input from the Input System. To do this: 1. Create a new empty GameObject 2. Click [**Add Component**](https://docs.unity3d.com/Manual/UsingComponents.html) in the Inspector diff --git a/Packages/com.unity.inputsystem/Documentation~/distinguishing-ui-game-input.md b/Packages/com.unity.inputsystem/Documentation~/handling-input-target-ambiguity.md similarity index 77% rename from Packages/com.unity.inputsystem/Documentation~/distinguishing-ui-game-input.md rename to Packages/com.unity.inputsystem/Documentation~/handling-input-target-ambiguity.md index 84d75d8f4e..768d87fcc4 100644 --- a/Packages/com.unity.inputsystem/Documentation~/distinguishing-ui-game-input.md +++ b/Packages/com.unity.inputsystem/Documentation~/handling-input-target-ambiguity.md @@ -1,19 +1,25 @@ -# Distinguishing between UI and game input +# Handling input target ambiguity -UI in Unity receives input through the same mechanisms as the input for the rest of your game or app. There is no automatic mechanism that implicitly ensures that if a certain input (such as a mouse click) is consumed by the UI, it is not also received by your gameplay code. +Understand how to manage ambiguities between input for your application's user interface (UI), and input for other parts of your application. -This can create ambiguities between, for example, code that responds to [`UI.Button.onClick`](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/api/UnityEngine.UI.Button.html#UnityEngine_UI_Button_onClick) and code that responds to [`InputAction.performed`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_performed) of an Action bound to `/leftButton`. +>[!NOTE] +>The Input System package includes a sample project called "**UI vs Game Input**". The sample demonstrates how to deal with ambiguities between inputs for UI and inputs for the game. + +## How Unity processes UI input + +Unity processes UI input through the same mechanisms as the input for the rest of your application. There's no automatic mechanism that prevents the UI and the rest of your code from consuming the same input (such as a mouse click). + +## Strategies for avoiding ambiguity -Whether such ambiguities exist depends on how UIs are used. For example, you can avoid ambiguities by implementing your UI in one of the following ways: +Ambiguities can appear between, for example, code that responds to [`UI.Button.onClick`](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/api/UnityEngine.UI.Button.html#UnityEngine_UI_Button_onClick) and code that responds to [`InputAction.performed`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_performed) for an action bound to `/leftButton`. + +Whether such ambiguities exist depends on you implement the UI and the UI input. The following UI implementation strategies are examples of how you can avoid these ambiguities: * Perform all interaction through UI elements. Render a scene in the background, but perform all interaction through UI events (including those such as 'background' clicks on the `Canvas`). * Place UI over a 2D/3D scene, but don’t let the user directly interact with the UI. * Place UI over a 2D/3D scene, but create a clear "mode" switch that determines whether interaction applies to the UI or the scene. For example, a first-person game on desktop might employ a [cursor lock](https://docs.unity3d.com/ScriptReference/Cursor-lockState.html) which directs input to the game when it is engaged, and to the UI when it is not engaged. -There are specific ambiguities that can arise for [pointer input](supported-ui-input-types-pointer.md) and [navigation input](supported-ui-input-types-navigation.md). - ->[!NOTE] ->The Input System package includes a sample project called "**UI vs Game Input**". The sample demonstrates how to deal with ambiguities between inputs for UI and inputs for the game. +There are also specific ambiguities that can arise for [pointer input](supported-ui-input-types-pointer.md) and [navigation input](supported-ui-input-types-navigation.md). ## Handling pointer input ambiguities diff --git a/Packages/com.unity.inputsystem/Documentation~/introduction-ui-input-module.md b/Packages/com.unity.inputsystem/Documentation~/introduction-ui-input-module.md index 55f49fa13c..9b93a83680 100644 --- a/Packages/com.unity.inputsystem/Documentation~/introduction-ui-input-module.md +++ b/Packages/com.unity.inputsystem/Documentation~/introduction-ui-input-module.md @@ -1,6 +1,8 @@ # Introduction to the UI Input Module -The UI Input Module passes actions from your Input System to your UI, as well as some other UI-related input settings. When working with Unity UI (uGUI), or when using UI Toolkit in versions of Unity prior to Unity 2023.2, you must use the **UI Input Module**. +The UI Input Module passes actions from your Input System to your UI, alongside some other UI-related input settings. + +You must use the **UI Input Module** when working with Unity UI (uGUI), or when using UI Toolkit in versions of Unity prior to Unity 2023.2. You don't need to specify to the UI Input Module which UI system you are using. Input support for both [Unity UI](https://docs.unity3d.com/Manual/com.unity.ugui.html) and [UI Toolkit](https://docs.unity3d.com/Manual/UIElements.html) is based on the same [Event System](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/manual/EventSystem.html) and [BaseInputModule](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/manual/InputModules.html) subsystem. diff --git a/Packages/com.unity.inputsystem/Documentation~/multiplayer-ui-input.md b/Packages/com.unity.inputsystem/Documentation~/multiplayer-ui-input.md index f1a398d953..b10d917bd2 100644 --- a/Packages/com.unity.inputsystem/Documentation~/multiplayer-ui-input.md +++ b/Packages/com.unity.inputsystem/Documentation~/multiplayer-ui-input.md @@ -2,7 +2,7 @@ Configure multiple UI instances, so that multiple players can share a single screen and individually interact with the UI. -|**Topic**|**Description**| -|--------|-----------| -|[Introduction to multiplayer UI input](introduction-multiplayer-ui-input.md)|Assign players a Multiplayer Event System so that each player has their own UI input scheme.| -|[Configure multiplayer UI input](configure-multiplayer-ui-input.md)|Configure the Multiplayer Event System component and set up automatic input detection.| \ No newline at end of file +| **Topic** | **Description** | +| :------------------------------ | :------------------------------- | +|**[Introduction to multiplayer UI input](introduction-multiplayer-ui-input.md)**|Assign players a Multiplayer Event System so that each player has their own UI input scheme.| +|**[Configure multiplayer UI input](configure-multiplayer-ui-input.md)**|Configure the Multiplayer Event System component and set up automatic input detection.| \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/on-screen-controls.md b/Packages/com.unity.inputsystem/Documentation~/on-screen-controls.md index b1bb934de9..1b6b43e813 100644 --- a/Packages/com.unity.inputsystem/Documentation~/on-screen-controls.md +++ b/Packages/com.unity.inputsystem/Documentation~/on-screen-controls.md @@ -5,9 +5,9 @@ uid: input-system-on-screen Simulate input devices with UI widgets that the user interacts with on the screen. -|**Topic**|**Description**| -|--------|-----------| -|[Introduction to on-screen controls](introduction-on-screen-controls.md)| Simulate buttons, sticks, and custom inputs with on-screen controls. | -|[Create an on-screen button control](create-on-screen-button-control.md)| Create and configure simulated on-screen button controls.| -|[Create an on-screen stick control](create-on-screen-stick-control.md)| Create and configure simulated on-screen stick controls.| -|[Create a custom on-screen control](create-custom-on-screen-control.md)| Create and configure custom simulated on-screen controls.| \ No newline at end of file +| **Topic** | **Description** | +| :------------------------------ | :------------------------------- | +|**[Introduction to on-screen controls](introduction-on-screen-controls.md)**| Simulate buttons, sticks, and custom inputs with on-screen controls. | +|**[Create an on-screen button control](create-on-screen-button-control.md)**| Create and configure simulated on-screen button controls.| +|**[Create an on-screen stick control](create-on-screen-stick-control.md)**| Create and configure simulated on-screen stick controls.| +|**[Create a custom on-screen control](create-custom-on-screen-control.md)**| Create and configure custom simulated on-screen controls.| \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-navigation.md b/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-navigation.md index 9eef31a957..19be3b791b 100644 --- a/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-navigation.md +++ b/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-navigation.md @@ -6,8 +6,7 @@ Navigation-type input controls the current selection based on motion read from t Navigation-type input doesn't have multiple concurrent instances. The UI module only processes a single [`move`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_move) vector and a single [`submit`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_submit) and [`cancel`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_cancel) input per frame. However, these inputs don't need to come from one single device. You can bind multiple inputs to each action. ->[!IMPORTANT] ->The [`move`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_move) input must be set to the [`PassThrough`](../api/UnityEngine.InputSystem.InputActionType.html#UnityEngine_InputSystem_InputActionType_PassThrough) action type. The [`submit`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_submit) and +The [`move`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_move) input must be set to the [`PassThrough`](../api/UnityEngine.InputSystem.InputActionType.html#UnityEngine_InputSystem_InputActionType_PassThrough) action type. The [`submit`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_submit) and [`cancel`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_cancel) inputs must be set to the [`Button`](../api/UnityEngine.InputSystem.InputActionType.html#UnityEngine_InputSystem_InputActionType_Button) Action type. Navigation input is non-positional. There is no screen position associated with navigation actions. Instead, navigation actions always operate on the current selection. \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-pointer.md b/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-pointer.md index fc4c5aebb8..721d47d64d 100644 --- a/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-pointer.md +++ b/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-pointer.md @@ -1,34 +1,40 @@ # Pointer input UI support -To the UI, a pointer is a position from which clicks and scrolls can be triggered to interact with UI elements at the pointer's position. Pointer-type input is sourced from [`point`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_point), [`leftClick`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_leftClick), [`rightClick`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_rightClick), [`middleClick`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_middleClick), and [`scrollWheel`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_scrollWheel). +A pointer is a position from which clicks and scrolls can trigger to interact with UI elements at the pointer's position. Pointer-type input comes from the following actions: -The UI input model doesn't associate pointers and cursors together. However, it pins the pointer for mouse and pen input at `1,1` depending on the state of `Cursor.lockState`. To adjust the cursor lock behavior, use the Cursor lock behavior property of [`InputSystemUIInputModule`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html). +* [`point`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_point) +* [`leftClick`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_leftClick) +* [`rightClick`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_rightClick) +* [`middleClick`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_middleClick) +* [`scrollWheel`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_scrollWheel) -Multiple pointer Devices can feed input into a single UI input module. Also, in the case of [`Touchscreen`](../api/UnityEngine.InputSystem.Touchscreen.html), a single Device can have the ability to have multiple concurrent pointers (each finger contact is one pointer). +The UI input model doesn't associate pointers and cursors together. However, it pins the pointer for both mouse and pen input at `1,1` depending on the state of `Cursor.lockState`. The cursor lock behavior is defined by the **Cursor Lock Behavior** property of the [UI Input Module](using-ui-input-module.md). -Because multiple pointer Devices can feed into the same set of Actions, it is important to set the [action type](./RespondingToActions.md#action-types) to [PassThrough](../api/UnityEngine.InputSystem.InputActionType.html#UnityEngine_InputSystem_InputActionType_PassThrough). This ensures that no filtering is applied to input on these actions and that instead every input is relayed as is. +## Multiple pointer devices -From the perspective of [`InputSystemUIInputModule`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html), each [`InputDevice`](../api/UnityEngine.InputSystem.InputDevice.html) that has one or more controls bound to one of the pointer-type actions is considered a unique pointer. Also, for each [`Touchscreen`](../api/UnityEngine.InputSystem.Touchscreen.html) devices, each separate [`TouchControl`](../api/UnityEngine.InputSystem.Controls.TouchControl.html) that has one or more of its controls bound to the those actions is considered its own unique pointer as well. Each pointer receives a unique [`pointerId`](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/api/UnityEngine.EventSystems.PointerEventData.html#UnityEngine_EventSystems_PointerEventData_pointerId) which generally corresponds to the [`deviceId`](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_deviceId) of the pointer. However, for touch, this will be a combination of [deviceId](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_deviceId) and [`touchId`](../api/UnityEngine.InputSystem.Controls.TouchControl.html#UnityEngine_InputSystem_Controls_TouchControl_touchId). Use [`ExtendedPointerEventData.touchId`](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html#UnityEngine_InputSystem_UI_ExtendedPointerEventData_touchId) to find the ID for a touch event. +Multiple pointer devices can feed input into a single UI Input Module. [`Touchscreen`](../api/UnityEngine.InputSystem.Touchscreen.html) devices can have multiple concurrent pointers (each finger contact is one pointer) on a single device. -To influence how the input module deals with concurrent input from multiple pointers, use the UI Input Module’s [**Pointer Behavior**](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_pointerBehavior) setting. +Because multiple pointer devices can feed into the same set of actions, it's important to set the [action type](./RespondingToActions.md#action-types) to [PassThrough](../api/UnityEngine.InputSystem.InputActionType.html#UnityEngine_InputSystem_InputActionType_PassThrough). This ensures that no filtering is applied to input on these actions and that instead every input is relayed as is. -If you bind a device to a pointer-type action such as [Left Click](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_leftClick) without also binding it to [Point](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_point), the UI input module will recognize the device as not being able to point and try to route its input into that of another pointer. For example, if you bind [Left Click](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_leftClick) to the `Space` key and [Point](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_point) to the position of the mouse, then pressing the space bar will result in a left click at the current position of the mouse. +From the perspective of [`InputSystemUIInputModule`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html), each [`InputDevice`](../api/UnityEngine.InputSystem.InputDevice.html) that has one or more controls bound to one of the pointer-type actions is a unique pointer. Also, for each [`Touchscreen`](../api/UnityEngine.InputSystem.Touchscreen.html) devices, each separate [`TouchControl`](../api/UnityEngine.InputSystem.Controls.TouchControl.html) that has one or more of its controls bound to the those actions is its own unique pointer as well. Each pointer receives a unique [`pointerId`](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/api/UnityEngine.EventSystems.PointerEventData.html#UnityEngine_EventSystems_PointerEventData_pointerId) which generally corresponds to the [`deviceId`](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_deviceId) of the pointer. However, for touch, this will be a combination of [deviceId](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_deviceId) and [`touchId`](../api/UnityEngine.InputSystem.Controls.TouchControl.html#UnityEngine_InputSystem_Controls_TouchControl_touchId). Use [`ExtendedPointerEventData.touchId`](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html#UnityEngine_InputSystem_UI_ExtendedPointerEventData_touchId) to find the ID for a touch event. -For pointer-type input (as well as for [tracked-type input](supported-ui-input-types-tracked.md)), [`InputSystemUIInputModule`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html) sends [`ExtendedPointerEventData`](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html) instances which are an extended version of the base `PointerEventData`. These events contain additional data such as the [device](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html#UnityEngine_InputSystem_UI_ExtendedPointerEventData_device) and [pointer type](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html#UnityEngine_InputSystem_UI_ExtendedPointerEventData_pointerType) which the event has been generated from. +If you bind a device to a pointer-type action such as [Left Click](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_leftClick) without also binding it to [Point](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_point), the UI Input Module recognizes the device as not able to point, and attempts to route its input into another pointer. For example, if you bind [Left Click](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_leftClick) to the `Space` key and [Point](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_point) to the position of the mouse, then pressing the space bar results in a left-click at the current position of the mouse. -## Pointer behavior +For pointer-type input (and [tracked-type input](supported-ui-input-types-tracked.md)), [`InputSystemUIInputModule`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html) sends [`ExtendedPointerEventData`](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html) instances, which are an extended version of the base `PointerEventData`. These events contain additional data such as the [device](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html#UnityEngine_InputSystem_UI_ExtendedPointerEventData_device) and [pointer type](../api/UnityEngine.InputSystem.UI.ExtendedPointerEventData.html#UnityEngine_InputSystem_UI_ExtendedPointerEventData_pointerType) that the Input System has used to generate the event. -The UI Module's [Pointer Behavior](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_pointerBehavior) property defines how to deal with multiple [pointers](LINK) feeding input into the UI. +### Pointer behavior for multiple devices -### Unify mouse and pen input but separate touch and track input +The UI Module's [Pointer Behavior](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_pointerBehavior) property defines how to deal with concurrent input from multiple pointers. + +#### Unify mouse and pen input but separate touch and track input [Single Mouse or Pen But Multi Touch And Track](../api/UnityEngine.InputSystem.UI.UIPointerBehavior.html#UnityEngine_InputSystem_UI_UIPointerBehavior_SingleMouseOrPenButMultiTouchAndTrack) behaves like [Single Unified Pointer](../api/UnityEngine.InputSystem.UI.UIPointerBehavior.html#UnityEngine_InputSystem_UI_UIPointerBehavior_SingleUnifiedPointer) for all input that is not classified as touch or tracked input, and behaves like [All Pointers As Is](../api/UnityEngine.InputSystem.UI.UIPointerBehavior.html#UnityEngine_InputSystem_UI_UIPointerBehavior_AllPointersAsIs) for tracked and touch input. If concurrent input is received on a [`Mouse`](../api/UnityEngine.InputSystem.Mouse.html) and [`Pen`](../api/UnityEngine.InputSystem.Pen.html), for example, the input of both is fed into the same UI pointer instance. The position input of one will overwrite the position of the other. When input is received from touch or tracked devices, the single unified pointer for mice and pens is removed, including [`IPointerExit`](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/api/UnityEngine.EventSystems.IPointerExitHandler.html) events being sent in case the mouse/pen cursor is currently hovering over objects. This is the default behavior. -### Unify all pointer inputs +#### Unify all pointer inputs [Single Unified Pointer](../api/UnityEngine.InputSystem.UI.UIPointerBehavior.html#UnityEngine_InputSystem_UI_UIPointerBehavior_SingleUnifiedPointer) unifies all pointer input so that there is only ever a single pointer. This includes touch and tracked input. This means, for example, that regardless of how many devices feed input into [Point](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_point), only the last input in a frame takes effect and becomes the current UI pointer's position. -### Treat all pointers as separate +#### Treat all pointers as separate [All Pointers As Is](../api/UnityEngine.InputSystem.UI.UIPointerBehavior.html#UnityEngine_InputSystem_UI_UIPointerBehavior_AllPointersAsIs) treats each input as separate and individual. Any device, including touch and tracked devices that feed input pointer-type actions, is its own pointer (or multiple pointers for touch input). This might mean that there are multiple pointers in the UI, and several objects might be pointed at at the same time. diff --git a/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-tracked.md b/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-tracked.md index c56f19f456..704f5bf660 100644 --- a/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-tracked.md +++ b/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types-tracked.md @@ -3,7 +3,7 @@ Input from [tracked devices](../api/UnityEngine.InputSystem.TrackedDevice.html) such as [XR controllers](../api/UnityEngine.InputSystem.XR.XRController.html) and [HMDs](../api/UnityEngine.InputSystem.XR.XRHMD.html) behaves like [pointer-type input](supported-ui-input-types-pointer.md), but the Input System uses raycasting to translate the world-space device position and orientation sourced from [`trackedDevicePosition`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_trackedDevicePosition) and [`trackedDeviceOrientation`](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_trackedDeviceOrientation) into a screen-space position. >[!IMPORTANT] ->Because multiple tracked Devices can feed into the same set of Actions, it is important to set the [action type](./RespondingToActions.md#action-types) to [PassThrough](../api/UnityEngine.InputSystem.InputActionType.html#UnityEngine_InputSystem_InputActionType_PassThrough). This ensures that no filtering is applied to input on these actions and that instead every input is relayed as is. +>Because multiple tracked devices can feed into the same set of actions, it is important to set the [action type](./RespondingToActions.md#action-types) to [PassThrough](../api/UnityEngine.InputSystem.InputActionType.html#UnityEngine_InputSystem_InputActionType_PassThrough). This ensures that the Input System applies no filtering on these input actions, and relays inputs correctly. For this raycasting to work, you need to add [TrackedDeviceRaycaster](../api/UnityEngine.InputSystem.UI.TrackedDeviceRaycaster.html) to the `GameObject` that has the UI's `Canvas` component. This `GameObject` will usually have a `GraphicRaycaster` component which, however, only works for 2D screen-space raycasting. You can put [TrackedDeviceRaycaster](../api/UnityEngine.InputSystem.UI.TrackedDeviceRaycaster.html) alongside `GraphicRaycaster` and both can be enabled at the same time without advserse effect. @@ -11,4 +11,4 @@ For this raycasting to work, you need to add [TrackedDeviceRaycaster](../api/Uni ![TrackedDeviceRayster Properties](Images/TrackedDeviceRaycaster.png) -Clicks on tracked devices do not differ from other [pointer-type input](supported-ui-input-types-pointer.md). Therefore, actions such as [Left Click](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_leftClick) work for tracked devices just like they work for other pointers. \ No newline at end of file +Clicks on tracked devices do not differ from other [pointer-type input](supported-ui-input-types-pointer.md). Therefore, actions such as [leftClick](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_leftClick) work for tracked devices just like they work for other pointers. \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types.md b/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types.md index a8f0233c95..8a4a80f4f4 100644 --- a/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types.md +++ b/Packages/com.unity.inputsystem/Documentation~/supported-ui-input-types.md @@ -1,9 +1,9 @@ # Supported input types in the UI Input Module -The UI Input Module supports three types of input Action: pointer, navigation, and tracked. For each input type, the UI Input Module sources and combines input from a specific set of Actions. +The UI Input Module supports three types of input action: pointer, navigation, and tracked. For each input type, the UI Input Module sources and combines input from a specific set of actions. -|**Topic**|**Description**| -|--------|-----------| -|[Pointer input UI support](supported-ui-input-types-pointer.md)| Configure pointer-type Actions, such as clicking, tapping, and scrolling.| -|[Navigation input UI support](supported-ui-input-types-navigation.md)| Configure navigation-type Actions, such as the `move` Action.| -|[Tracked input UI support](supported-ui-input-types-tracked.md)|Configure input from tracked devices, such as XR controllers and HMDs.| \ No newline at end of file +| **Topic** | **Description** | +| :------------------------------ | :------------------------------- | +|**[Pointer input UI support](supported-ui-input-types-pointer.md)**| Configure pointer-type actions, such as clicking, tapping, and scrolling.| +|**[Navigation input UI support](supported-ui-input-types-navigation.md)**| Configure navigation-type actions, such as the `move` action.| +|**[Tracked input UI support](supported-ui-input-types-tracked.md)**|Configure input from tracked devices, such as XR controllers and HMDs.| \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/supported-ui-systems.md b/Packages/com.unity.inputsystem/Documentation~/supported-ui-systems.md index 9be1013c6b..3348866da1 100644 --- a/Packages/com.unity.inputsystem/Documentation~/supported-ui-systems.md +++ b/Packages/com.unity.inputsystem/Documentation~/supported-ui-systems.md @@ -2,8 +2,8 @@ Understand the support and compatibility between the Input System and Unity's UI systems. -|**Topic**|**Description**| -|--------|-----------| -|[Understand UI system compatibility](understand-ui-compatibility.md)|Understand how the Input System interacts with Unity Toolkit, Unity UI (uGUI), and IMGUI.| -|[Using UI Input Module for UI support](using-ui-input-module.md)|Use the UI Input Module component to add support for specific UI systems.| -|[Use IMGUI alongside the Input System package](use-imgui-alongside-input-system.md)|Use a UI that supports the Input System, while still using IMGUI in other areas of your project.| \ No newline at end of file +| **Topic** | **Description** | +| :------------------------------ | :------------------------------- | +|**[Understand UI system compatibility](understand-ui-compatibility.md)**|Understand how the Input System interacts with Unity Toolkit, Unity UI (uGUI), and IMGUI.| +|**[Using UI Input Module for UI support](using-ui-input-module.md)**|Use the UI Input Module component to add support for specific UI systems.| +|**[Use IMGUI alongside the Input System package](use-imgui-alongside-input-system.md)**|Use a UI that supports the Input System, while still using IMGUI in other areas of your project.| \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/ui-action-map-reference.md b/Packages/com.unity.inputsystem/Documentation~/ui-action-map-reference.md index e78364936c..10dda022a0 100644 --- a/Packages/com.unity.inputsystem/Documentation~/ui-action-map-reference.md +++ b/Packages/com.unity.inputsystem/Documentation~/ui-action-map-reference.md @@ -1,15 +1,15 @@ # UI Action Map reference The default [project-wide actions asset](./about-project-wide-actions.md) has a default configuration for UI input. -**Action**|**Action Type**|**Control Type**|**Description** --|-|-|- -**Navigate**|PassThrough|Vector2|A vector used to select the currently active UI [selectable](https://docs.unity3d.com/Manual/script-Selectable.html) in gamepad or arrow-key [navigation-type input](supported-ui-input-types-navigation.md). -**Submit**|Button|Button|Submits the currently selected UI [selectable](https://docs.unity3d.com/Manual/script-Selectable.html) in [navigation-type input](supported-ui-input-types-navigation.md) -**Cancel**|Button|Button|Exits any interaction with the currently selected UI [selectable](https://docs.unity3d.com/Manual/script-Selectable.html) in [navigation-type input](supported-ui-input-types-navigation.md) -**Point**|PassThrough|Vector2|A 2D screen position. The cursor for [pointer-type](supported-ui-input-types-pointer.md) interaction. -**Click**|PassThrough|Button|The primary button for [pointer-type](supported-ui-input-types-pointer.md) interaction. -**RightClick**|PassThrough|Button|The secondary button for [pointer-type](supported-ui-input-types-pointer.md) interaction. -**MiddleClick**|PassThrough|Button|The middle button for [pointer-type](supported-ui-input-types-pointer.md) interaction. -**ScrollWheel**|PassThrough|Vector2|The scrolling gesture for [pointer-type](supported-ui-input-types-pointer.md) interaction. -**Tracked Device Position**|PassThrough|Vector3|A 3D position of one or multiple spatial tracking devices, such as XR hand controllers. In combination with **Tracked Device Orientation**, this allows XR-style UI interactions by pointing at UI [selectables](https://docs.unity3d.com/Manual/script-Selectable.html) in space. See [tracked-type input](supported-ui-input-types-tracked.md). -**Tracked Device Orientation**|PassThrough|Quaternion|a `Quaternion` representing the rotation of one or multiple spatial tracking devices, such as XR hand controllers. In combination with [Tracked Device Position](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_trackedDevicePosition), this allows XR-style UI interactions by pointing at UI [selectables](https://docs.unity3d.com/Manual/script-Selectable.html) in space. See [tracked-type input](supported-ui-input-types-tracked.md). \ No newline at end of file +|**Action**|**Action Type**|**Control Type**|**Description**| +|:-|:-|:-|:-| +|**Navigate**|PassThrough|Vector2|A vector used to select the currently active UI [selectable](https://docs.unity3d.com/Manual/script-Selectable.html) in gamepad or arrow-key [navigation-type input](supported-ui-input-types-navigation.md).| +|**Submit**|Button|Button|Submits the currently selected UI [selectable](https://docs.unity3d.com/Manual/script-Selectable.html) in [navigation-type input](supported-ui-input-types-navigation.md)| +|**Cancel**|Button|Button|Exits any interaction with the currently selected UI [selectable](https://docs.unity3d.com/Manual/script-Selectable.html) in [navigation-type input](supported-ui-input-types-navigation.md)| +|**Point**|PassThrough|Vector2|A 2D screen position. The cursor for [pointer-type](supported-ui-input-types-pointer.md) interaction.| +|**Click**|PassThrough|Button|The primary button for [pointer-type](supported-ui-input-types-pointer.md) interaction.| +|**RightClick**|PassThrough|Button|The secondary button for [pointer-type](supported-ui-input-types-pointer.md) interaction.| +|**MiddleClick**|PassThrough|Button|The middle button for [pointer-type](supported-ui-input-types-pointer.md) interaction.| +|**ScrollWheel**|PassThrough|Vector2|The scrolling gesture for [pointer-type](supported-ui-input-types-pointer.md) interaction.| +|**Tracked Device Position**|PassThrough|Vector3|A 3D position of one or multiple spatial tracking devices, such as XR hand controllers. In combination with **Tracked Device Orientation**, this allows XR-style UI interactions by pointing at UI [selectables](https://docs.unity3d.com/Manual/script-Selectable.html) in space. See [tracked-type input](supported-ui-input-types-tracked.md).| +|**Tracked Device Orientation**|PassThrough|Quaternion|a `Quaternion` representing the rotation of one or multiple spatial tracking devices, such as XR hand controllers. In combination with [Tracked Device Position](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.|html#UnityEngine_InputSystem_UI_InputSystemUIInputModule_trackedDevicePosition), this allows XR-style UI interactions by pointing at UI [selectables](https://docs.unity3d.com/Manual/script-Selectable.html) in space. See [tracked-type input](supported-ui-input-types-tracked.md).| \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/ui-input-module-reference.md b/Packages/com.unity.inputsystem/Documentation~/ui-input-module-reference.md index 18cfcbf4ae..9049fadd70 100644 --- a/Packages/com.unity.inputsystem/Documentation~/ui-input-module-reference.md +++ b/Packages/com.unity.inputsystem/Documentation~/ui-input-module-reference.md @@ -6,7 +6,7 @@ The properties on the UI Input Module correspond to the [`InputSystemUIInputModu |**Property**|**Description**| |--------|-----------| -|Send Pointer Hover to Parent | | + |**Move Repeat Delay**|The initial delay (in seconds) between generating an initial [IMoveHandler.OnMove](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/api/UnityEngine.EventSystems.IMoveHandler.html) navigation event and generating repeated navigation events when the __Move__ action stays actuated.| |**Move Repeat Rate**|The interval (in seconds) between generating repeat navigation events when the __Move__ action stays actuated. Note that this is capped by the frame rate; there will not be more than one move repeat event each frame so if the frame rate dips below the repeat rate, the effective repeat rate will be lower than this setting.| |**XR Tracking Origin** | Define the transform that represents the real-world transform for tracking devices. | diff --git a/Packages/com.unity.inputsystem/Documentation~/ui-input.md b/Packages/com.unity.inputsystem/Documentation~/ui-input.md index 755f8e9742..c21b36d4da 100644 --- a/Packages/com.unity.inputsystem/Documentation~/ui-input.md +++ b/Packages/com.unity.inputsystem/Documentation~/ui-input.md @@ -1,13 +1,13 @@ -# Input for user interfaces +# UI input The Input System provides support for several UI systems in Unity. This section describes compatibility and configuration for UI input. -|**Topic**|**Description**| -|--------|-----------| -|[Supported UI systems](supported-ui-systems.md)|Understand the compatibility between the Input System and Unity's UI systems.| -|[Configure UI input actions](configure-ui-input-action-map.md)|Configure UI input actions in the UI action map.| -|[UI action map reference](ui-action-map-reference.md)|Reference documentation for the default UI action map on the project-wide actions asset.| -|[Distinguishing between UI input and game input](distinguishing-ui-game-input.md)|Understand how the Input System and Unity work together to distinguish which input actions are intended for UI, and which are intended for the game.| -|[Virtual mouse for cursor control](virtual-mouse-ui-cursor-control)|Use a virtual mouse to allow gamepads and joysticks to control pointer inputs.| -|[Multiplayer UI input](multiplayer-ui)|Configure multiple UI instances, so that multiple players can share a single screen and individually interact with the UI.| -|[On-screen controls](on-screen-controls)|Simulate input devices with UI widgets that the user interacts with on the screen.| \ No newline at end of file +| **Topic** | **Description** | +| :------------------------------ | :------------------------------- | +|**[Supported UI systems](supported-ui-systems.md)**|Understand the compatibility between the Input System and Unity's UI systems.| +|**[Configure UI input actions](configure-ui-input-action-map.md)**|Configure UI input actions in the UI action map.| +|**[UI action map reference](ui-action-map-reference.md)**|Reference documentation for the default UI action map on the project-wide actions asset.| +|**[Handling input target ambiguity](handling-input-target-ambiguity.md)**|Understand how the Input System and Unity work together to distinguish which input actions are intended for UI, and which are intended for the game.| +|**[Virtual mouse for cursor control](virtual-mouse-ui-cursor-control)**|Use a virtual mouse to allow gamepads and joysticks to control pointer inputs.| +|**[Multiplayer UI input](multiplayer-ui)**|Configure multiple UI instances, so that multiple players can share a single screen and individually interact with the UI.| +|**[On-screen controls](on-screen-controls)**|Simulate input devices with UI widgets that the user interacts with on the screen.| \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/understand-ui-compatibility.md b/Packages/com.unity.inputsystem/Documentation~/understand-ui-compatibility.md index c2d96405e8..1179a2bf2f 100644 --- a/Packages/com.unity.inputsystem/Documentation~/understand-ui-compatibility.md +++ b/Packages/com.unity.inputsystem/Documentation~/understand-ui-compatibility.md @@ -1,7 +1,13 @@ # Understand UI system compatibility Unity has [three major UI solutions](https://docs.unity3d.com/Manual/UIToolkits.html). The Input System package's compatibility and workflow with these solutions varies depending on which UI solution you are using, and which version of Unity you are using. -The three main UI systems are **UI Toolkit**, **Unity UI**, and **IMGUI**. Some systems and versions require that you use the Input System’s [UI Input Module component](using-ui-input-module.md) to pass actions from the Input System to the UI. +The three main UI systems are: + +* **UI Toolkit** +* **Unity UI** +* **IMGUI** + +Some systems and versions require that you use the Input System’s [UI Input Module component](using-ui-input-module.md) to pass actions from the Input System to the UI. ## Compatibility summary UI system|Compatible|UI Input Module component diff --git a/Packages/com.unity.inputsystem/Documentation~/use-imgui-alongside-input-system.md b/Packages/com.unity.inputsystem/Documentation~/use-imgui-alongside-input-system.md index bf55ca2c2f..5c94388367 100644 --- a/Packages/com.unity.inputsystem/Documentation~/use-imgui-alongside-input-system.md +++ b/Packages/com.unity.inputsystem/Documentation~/use-imgui-alongside-input-system.md @@ -1,11 +1,12 @@ # Use IMGUI alongside the Input System package -The Input System package does not support [Immediate Mode GUI](https://docs.unity3d.com/Manual/GUIScriptingGuide.html) (IMGUI) methods at runtime. However, if you need to use IMGUI for your UI, you can use legacy Input Manager input for IMGUI, and the Input System package for your in-game input. +The Input System package doesn't support [Immediate Mode GUI](https://docs.unity3d.com/Manual/GUIScriptingGuide.html) (IMGUI) methods at runtime. However, if you need to use IMGUI for your UI, you can use legacy Input Manager input for IMGUI, and the Input System package for your in-game input. -When the Editor's [**Active Input Handling**](https://docs.unity3d.com/Manual/class-PlayerSettings.html) setting is set to "**Input System Package**" (which is the default, when using the Input System package), the `OnGUI` methods in your player code don't receive any input events. +When the Unity Editor's [**Active Input Handling**](https://docs.unity3d.com/Manual/class-PlayerSettings.html) setting is set to **Input System Package** (which is the default, when using the Input System package), the `OnGUI` methods in your player code don't receive any input events. -To restore functionality to runtime `OnGUI` methods, you can change the **Active Input Handling** setting to "**Both**". Doing this means that Unity processes the input twice which could introduce a small performance impact. +To restore functionality to runtime `OnGUI` methods, you can change the **Active Input Handling** setting to **Both**. Doing this means that Unity processes the input twice, which might introduce a small performance impact. -This only affects runtime (play mode) `OnGUI` methods. Editor GUI code is unaffected and continues to receive input events. \ No newline at end of file + +This only affects runtime (Play mode) `OnGUI` methods. Editor GUI code is unaffected and continues to receive input events. \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/using-ui-input-module.md b/Packages/com.unity.inputsystem/Documentation~/using-ui-input-module.md index aab2c4ec98..2ca94ac60a 100644 --- a/Packages/com.unity.inputsystem/Documentation~/using-ui-input-module.md +++ b/Packages/com.unity.inputsystem/Documentation~/using-ui-input-module.md @@ -4,9 +4,9 @@ The UI Input Module passes input to the UI in your project. You must use the Unity Input System when using Unity UI (uGUI), or when using versions of Unity Toolkit prior to 2023.3. -|**Topic**|**Description**| -|--------|-----------| -|[Introduction to the UI Input Module](introduction-ui-input-module.md)|Understand the UI Input Module's function and considerations for use. | -|[Supported input types in the UI Input Module](supported-ui-input-types-ui-input-module.md)|Understand the types of input that the UI Input Module can pass to the Editor.| -|[Access the UI Input Module](access-ui-input-module.md)|Access and add the UI Input Module to your scene. | -|[UI Input Module component reference](ui-input-module-reference.md)|Reference for the UI Input Module component.| \ No newline at end of file +| **Topic** | **Description** | +| :------------------------------ | :------------------------------- | +|**[Introduction to the UI Input Module](introduction-ui-input-module.md)**|Understand the UI Input Module's function and considerations for use. | +|**[Supported input types in the UI Input Module](supported-ui-input-types-ui-input-module.md)**|Understand the types of input that the UI Input Module can pass to the Editor.| +|**[Access the UI Input Module](access-ui-input-module.md)**|Access and add the UI Input Module to your scene. | +|**[UI Input Module component reference](ui-input-module-reference.md)**|Reference for the UI Input Module component.| \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/virtual-mouse-component-reference.md b/Packages/com.unity.inputsystem/Documentation~/virtual-mouse-component-reference.md new file mode 100644 index 0000000000..7403a4ad9c --- /dev/null +++ b/Packages/com.unity.inputsystem/Documentation~/virtual-mouse-component-reference.md @@ -0,0 +1,48 @@ +# Virtual Mouse component reference + +Use the Virtual Mouse component to create a simulated mouse device in your application. + + +## Cursor + +Use the **Cursor** properties to configure a virtual software cursor, and define when to use it. + +|**Property**|**Description**| +|--------|-----------| +|**Cursor Mode**| Determine whether the virtual mouse should always use the cursor that it defines via the **Cursor Graphic** and **Cursor Transform** values, or whether it should use hardware cursors instead if it detects them. The options are:
- **Software Cursor**: Use only the cursor that this Virtual Mouse component creates.
- **Hardware Cursor If Available**: Use a hardware cursor if the Input System detects a `Mouse` device. If it does not detect a `Mouse` device, the virtual mouse uses the software cursor as a fallback. | +|**Cursor Graphic**| Select a UI graphic element for the software cursor's appearance.

The virtual mouse only uses this graphic for the software cursor, and not for hardware cursors. | +|**Cursor Transform**| Set the starting transform for the software cursor. Moving the cursor updates the anchored position of the transform.

The virtual mouse only uses this transform for the software cursor, and not for hardware cursors. | + +## Motion + +Use the **Motion** properties to configure the speed of movement and scrolling on the virtual mouse. + +|**Property**|**Description**| +|--------|-----------| +|**Cursor Speed**| Set the speed at which the cursor should move, in pixels per second. This value multiplies the **Stick Action** value. | +|**Scroll Speed**| Set the speed at which the virtual mouse scroll should move. This value multiplies the **Scroll Wheel Action** value.| + +## Action assignment + +Use the action-related properties on the component to define which action triggers each virtual mouse input. + +By default, the following inputs are available in the Virtual Mouse component: + +|**Property**|**Description**| +|--------|-----------| +|**Stick Action** | Select the Vector2 action that moves the cursor left/right on the x-axis, and up/down on the y-axis. The input value from **Cursor Speed** multiplies this value. | +|**Left button action** | Select the button action that triggers a left-click on the virtual mouse.| +|**Middle button action** |Select the button action that triggers a middle-click on the virtual mouse. | +|**Right Button Action** |Select the button action that triggers a right-click on the virtual mouse. | +|**Forward Button Action** |Select the button action that triggers a forward-button (button 4) click on the virtual mouse. | +|**Back Button Action** |Select the button action that triggers a back-button (button 5) click on the virtual mouse. | +|**Scroll Wheel Action** | Select a Vector2 action that feeds into the virtual mouse's `scrollWheel` action. The input value from **Scroll Speed** multiplies this value. | + +Each action-related property has identical settings to define actions and controls: + +|**Setting**|**Description**| +|--------|-----------| +|Menu drop-down (**⋮**) | Options:
- **Action**: Create a new action on the virtual mouse component.
- **Reference**: Use a reference to an existing action. | +|Action Properties (**cog** icon) | Open an Action Properties window. Refer to [Action Properties panel reference](action-properties-panel-reference) for details on the properties available.

This setting only appears if you selected **Action** in the drop-down menu. | +|Add Binding (**+**)| Add a binding to the new action.

This setting only appears if you selected **Action** in the drop-down menu.| +|Delete Selection (**-**)|Delete the selected binding.

This setting only appears if you selected **Action** in the drop-down menu.| \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/Documentation~/virtual-mouse-ui-cursor-control.md b/Packages/com.unity.inputsystem/Documentation~/virtual-mouse-ui-cursor-control.md index a34fc0624f..38e7feb96d 100644 --- a/Packages/com.unity.inputsystem/Documentation~/virtual-mouse-ui-cursor-control.md +++ b/Packages/com.unity.inputsystem/Documentation~/virtual-mouse-ui-cursor-control.md @@ -5,10 +5,10 @@ Use a virtual mouse to allow gamepads and joysticks to control pointer inputs. >[!NOTE] >The Virtual Mouse component is only compatible with the [Unity UI](https://docs.unity3d.com/Manual/com.unity.ugui.html) (uGUI) system, and not UI Toolkit or IMGUI. -|**Topic**|**Description**| -|--------|-----------| -|[Introduction to Virtual Mouse for UI cursor control](introduction-virtual-mouse.md)|Use a Virtual Mouse component to set up navigation-based input for the UI. | -|[Configure a Virtual Mouse for UI input](configure-virtual-mouse-input.md)|Add and configure a Virtual Mouse component to your project.| +| **Topic** | **Description** | +| :------------------------------ | :------------------------------- | +|**[Introduction to Virtual Mouse for UI cursor control](introduction-virtual-mouse.md)**|Use a Virtual Mouse component to set up navigation-based input for the UI. | +|**[Configure a Virtual Mouse for UI input](configure-virtual-mouse-input.md)**|Add and configure a Virtual Mouse component to your project.| \ No newline at end of file From 46f6ad41e92d80cd811d1cafd94e7df0065c9784 Mon Sep 17 00:00:00 2001 From: Siobhan Date: Tue, 4 Feb 2025 16:18:36 +0000 Subject: [PATCH 09/15] Create multiplayer-event-system-component-input.md --- .../multiplayer-event-system-component-input.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 Packages/com.unity.inputsystem/Documentation~/multiplayer-event-system-component-input.md diff --git a/Packages/com.unity.inputsystem/Documentation~/multiplayer-event-system-component-input.md b/Packages/com.unity.inputsystem/Documentation~/multiplayer-event-system-component-input.md new file mode 100644 index 0000000000..53ee6cc608 --- /dev/null +++ b/Packages/com.unity.inputsystem/Documentation~/multiplayer-event-system-component-input.md @@ -0,0 +1,13 @@ +## Multiplayer Event System component reference + +Use the Multiplayer Event System component to configure input for a specific user in a multiplayer application. + + + +|**Property**|**Description**| +|--------|-----------| +**First Selected**| The GameObject that was selected first. | +|**Send Navigation Events**| Should the EventSystem allow navigation events (move / submit / cancel). | +|**Drag Threshold**| The soft area for dragging in pixels. | +|**Player Root**|Specify which part of the hierarchy belongs to the current user. | +|**Add Default Input Modules**| Add the default Input System components to the same GameObject as this Multiplayer Event System component.| \ No newline at end of file From 2d1c8159f4467be08c995a1d8aa2293958c16e93 Mon Sep 17 00:00:00 2001 From: Siobhan Date: Tue, 4 Feb 2025 16:32:14 +0000 Subject: [PATCH 10/15] Update multiplayer-event-system-component-input.md --- .../multiplayer-event-system-component-input.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Packages/com.unity.inputsystem/Documentation~/multiplayer-event-system-component-input.md b/Packages/com.unity.inputsystem/Documentation~/multiplayer-event-system-component-input.md index 53ee6cc608..a4b5450daf 100644 --- a/Packages/com.unity.inputsystem/Documentation~/multiplayer-event-system-component-input.md +++ b/Packages/com.unity.inputsystem/Documentation~/multiplayer-event-system-component-input.md @@ -6,8 +6,8 @@ Use the Multiplayer Event System component to configure input for a specific use |**Property**|**Description**| |--------|-----------| -**First Selected**| The GameObject that was selected first. | -|**Send Navigation Events**| Should the EventSystem allow navigation events (move / submit / cancel). | -|**Drag Threshold**| The soft area for dragging in pixels. | -|**Player Root**|Specify which part of the hierarchy belongs to the current user. | +**First Selected**| Define which GameObject is selected first. | +|**Send Navigation Events**| Define whether the Event System should send navigation events such as move, submit, and cancel. | +|**Drag Threshold**| Define the soft area for dragging in pixels. | +|**Player Root**| Define which part of the hierarchy belongs to the current user. | |**Add Default Input Modules**| Add the default Input System components to the same GameObject as this Multiplayer Event System component.| \ No newline at end of file From 1d5686a5323ebfef37b0308fc778400ef9f34c1c Mon Sep 17 00:00:00 2001 From: Siobhan Date: Mon, 10 Feb 2025 10:22:54 +0000 Subject: [PATCH 11/15] Delete configuring-multiplayer-input.md --- .../Documentation~/configuring-multiplayer-input.md | 11 ----------- 1 file changed, 11 deletions(-) delete mode 100644 Packages/com.unity.inputsystem/Documentation~/configuring-multiplayer-input.md diff --git a/Packages/com.unity.inputsystem/Documentation~/configuring-multiplayer-input.md b/Packages/com.unity.inputsystem/Documentation~/configuring-multiplayer-input.md deleted file mode 100644 index 68331ddf09..0000000000 --- a/Packages/com.unity.inputsystem/Documentation~/configuring-multiplayer-input.md +++ /dev/null @@ -1,11 +0,0 @@ -# Configuring multiplayer UI input - -The Input System can handle multiple separate UI instances on the screen controlled separately by different [Input Bindings](ActionBindings.md). This is useful if you want to have multiple local players share a single screen with different controllers, so that every player can control their own UI instance. - -To allow this, you need to replace the [Event System](https://docs.unity3d.com/Manual/script-EventSystem.html) component from Unity with the Input System's [Multiplayer Event System](../api/UnityEngine.InputSystem.UI.MultiplayerEventSystem.html) component. - -![MultiplayerEventSystem](Images/MultiplayerEventSystem.png) - -You can have multiple Multiplayer Event Systems active in the Scene at the same time. This means you can have multiple players, each with their own [UI Input Module](LINK) and Multiplayer Event System components, and each player can have their own set of Actions driving their own UI instance. If you are using the [Player Input](player-input-component.md) component, you can also set it to automatically configure the player's UI Input Module to use the player's Actions. See the documentation on [Player Input](player-input-component.md#ui-input) to learn how. - -The properties of the Multiplayer Event System component are identical to those from the Event System component. However, the Multiplayer Event System component also has a [Player Root](../api/UnityEngine.InputSystem.UI.MultiplayerEventSystem.html#UnityEngine_InputSystem_UI_MultiplayerEventSystem_playerRoot) property, which you can set to a GameObject that contains all the UI [selectables](https://docs.unity3d.com/Manual/script-Selectable.html) this event system should handle in its hierarchy. Mouse input that this event system processes then ignores any UI selectables which are not on any GameObject in the Hierarchy under [Player Root](../api/UnityEngine.InputSystem.UI.MultiplayerEventSystem.html#UnityEngine_InputSystem_UI_MultiplayerEventSystem_playerRoot). \ No newline at end of file From 0e11ff31c253d293545a34e3d3144408473d0e83 Mon Sep 17 00:00:00 2001 From: Siobhan Fitzgerald-Gibson <52451117+siobhan-unity@users.noreply.github.com> Date: Mon, 10 Feb 2025 11:04:30 +0000 Subject: [PATCH 12/15] Apply suggestions from code review Co-authored-by: Ben Pitt --- .../Documentation~/handling-input-target-ambiguity.md | 2 +- .../Documentation~/understand-ui-compatibility.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/Packages/com.unity.inputsystem/Documentation~/handling-input-target-ambiguity.md b/Packages/com.unity.inputsystem/Documentation~/handling-input-target-ambiguity.md index 768d87fcc4..d0ce95ea5f 100644 --- a/Packages/com.unity.inputsystem/Documentation~/handling-input-target-ambiguity.md +++ b/Packages/com.unity.inputsystem/Documentation~/handling-input-target-ambiguity.md @@ -13,7 +13,7 @@ Unity processes UI input through the same mechanisms as the input for the rest o Ambiguities can appear between, for example, code that responds to [`UI.Button.onClick`](https://docs.unity3d.com/Packages/com.unity.ugui@1.0/api/UnityEngine.UI.Button.html#UnityEngine_UI_Button_onClick) and code that responds to [`InputAction.performed`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_performed) for an action bound to `/leftButton`. -Whether such ambiguities exist depends on you implement the UI and the UI input. The following UI implementation strategies are examples of how you can avoid these ambiguities: +Whether such ambiguities exist depends on how you implement the UI and the UI input. The following UI implementation strategies are examples of how you can avoid these ambiguities: * Perform all interaction through UI elements. Render a scene in the background, but perform all interaction through UI events (including those such as 'background' clicks on the `Canvas`). * Place UI over a 2D/3D scene, but don’t let the user directly interact with the UI. diff --git a/Packages/com.unity.inputsystem/Documentation~/understand-ui-compatibility.md b/Packages/com.unity.inputsystem/Documentation~/understand-ui-compatibility.md index 1179a2bf2f..8843cb1cef 100644 --- a/Packages/com.unity.inputsystem/Documentation~/understand-ui-compatibility.md +++ b/Packages/com.unity.inputsystem/Documentation~/understand-ui-compatibility.md @@ -3,9 +3,9 @@ Unity has [three major UI solutions](https://docs.unity3d.com/Manual/UIToolkits. The three main UI systems are: -* **UI Toolkit** -* **Unity UI** -* **IMGUI** +* [**UI Toolkit**](https://docs.unity3d.com/Manual/UIElements.html) +* [**Unity UI**](https://docs.unity3d.com/Packages/com.unity.ugui@latest) +* [**IMGUI**](https://docs.unity3d.com/Manual/GUIScriptingGuide.html) Some systems and versions require that you use the Input System’s [UI Input Module component](using-ui-input-module.md) to pass actions from the Input System to the UI. From 61125a7af5f75163c54971eefaea59b69ce1f028 Mon Sep 17 00:00:00 2001 From: Siobhan Date: Mon, 10 Feb 2025 11:21:19 +0000 Subject: [PATCH 13/15] Fixed capitalization in titles --- .../Documentation~/configure-ui-input-action-map.md | 2 +- .../Documentation~/create-custom-on-screen-control.md | 4 +++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/Packages/com.unity.inputsystem/Documentation~/configure-ui-input-action-map.md b/Packages/com.unity.inputsystem/Documentation~/configure-ui-input-action-map.md index 8db8ef4cb2..5ed2f9ea31 100644 --- a/Packages/com.unity.inputsystem/Documentation~/configure-ui-input-action-map.md +++ b/Packages/com.unity.inputsystem/Documentation~/configure-ui-input-action-map.md @@ -1,4 +1,4 @@ -# Configure the UI Input Action Map +# Configure the UI input action map The default [project-wide actions asset](./about-project-wide-actions.md) comes with a built-in action map named **UI**, which contains all the actions required for UI interaction. To configure the bindings for these actions, use the [Actions Editor](./actions-editor.md). diff --git a/Packages/com.unity.inputsystem/Documentation~/create-custom-on-screen-control.md b/Packages/com.unity.inputsystem/Documentation~/create-custom-on-screen-control.md index cd9a241c18..e381036a08 100644 --- a/Packages/com.unity.inputsystem/Documentation~/create-custom-on-screen-control.md +++ b/Packages/com.unity.inputsystem/Documentation~/create-custom-on-screen-control.md @@ -1,7 +1,9 @@ -# Create a custom on-screen Control +# Create a custom on-screen control To create custom [input controls](Controls.md), you can extend [`OnScreenControl`](../api/UnityEngine.InputSystem.OnScreen.OnScreenControl.html). +The following sample demonstrates one way to do this: + ```CSharp [AddComponentMenu("Input/On-Screen Button")] public class OnScreenButton : OnScreenControl, IPointerDownHandler, IPointerUpHandler From 472d17adf69e075f0d4b4ef3fcde7473338fb489 Mon Sep 17 00:00:00 2001 From: Jo Dawes <49957016+jo-unity@users.noreply.github.com> Date: Thu, 13 Mar 2025 11:06:53 +0000 Subject: [PATCH 14/15] Update Packages/com.unity.inputsystem/Documentation~/configure-ui-input-action-map.md Co-authored-by: Ben Pitt --- .../Documentation~/configure-ui-input-action-map.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Packages/com.unity.inputsystem/Documentation~/configure-ui-input-action-map.md b/Packages/com.unity.inputsystem/Documentation~/configure-ui-input-action-map.md index 5ed2f9ea31..858f71d450 100644 --- a/Packages/com.unity.inputsystem/Documentation~/configure-ui-input-action-map.md +++ b/Packages/com.unity.inputsystem/Documentation~/configure-ui-input-action-map.md @@ -2,7 +2,7 @@ The default [project-wide actions asset](./about-project-wide-actions.md) comes with a built-in action map named **UI**, which contains all the actions required for UI interaction. To configure the bindings for these actions, use the [Actions Editor](./actions-editor.md). -To open the Actions Editor: +To open the UI action map: 1. Go to **Project Settings > Input System Package** 1. In the **Action Maps** column, select **UI**. From 4e94f0444ff246baaa03480ce5975f395ea6b694 Mon Sep 17 00:00:00 2001 From: Jo Dawes Date: Thu, 13 Mar 2025 11:08:54 +0000 Subject: [PATCH 15/15] Update TableOfContents.md --- .../Documentation~/TableOfContents.md | 28 +++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/Packages/com.unity.inputsystem/Documentation~/TableOfContents.md b/Packages/com.unity.inputsystem/Documentation~/TableOfContents.md index 07b6ef53be..0790a48b0a 100644 --- a/Packages/com.unity.inputsystem/Documentation~/TableOfContents.md +++ b/Packages/com.unity.inputsystem/Documentation~/TableOfContents.md @@ -133,8 +133,32 @@ * [Use an existing input device to create a layout](hid-create-custom-layout-existing.md) * [Use a custom class to create a layout](hid-create-custom-layout-class.md) * [Supported devices reference](supported-devices-reference.md) -* [UI support](UISupport.md) - * [On-screen Controls](OnScreen.md) +* [UI input](ui-input.md) + * [Supported UI systems](supported-ui-systems.md) + * [Understand UI system compatibility](understand-ui-compatibility.md) + * [Using UI Input Module for UI support](using-ui-input-module.md) + * [Introduction to the UI Input Module](introduction-ui-input-module.md) + * [Supported input types in the UI Input Module](supported-ui-input-types.md) + * [Pointer input UI support](supported-ui-input-types-pointer.md) + * [Navigation input UI support](supported-ui-input-types-navigation.md) + * [Tracked input UI support](supported-ui-input-types-tracked.md) + * [Access the UI Input Module](access-ui-input-module.md) + * [UI Input Module component reference](ui-input-module-reference.md) + * [Use IMGUI alongside the Input System package](use-imgui-alongside-input-system.md) + * [Configure UI Input Actions](configure-ui-input-action-map.md) + * [UI Action Map reference](ui-action-map-reference.md) + * [Handling input target ambiguity](handling-input-target-ambiguity.md) + * [Virtual Mouse for UI cursor control](virtual-mouse-ui-cursor-control.md) + * [Introduction to Virtual Mouse for UI cursor control](introduction-virtual-mouse.md) + * [Configure a Virtual Mouse for UI input](configure-virtual-mouse-input.md) + * [Multiplayer UI input](multiplayer-ui-input.md) + * [Introduction to multiplayer UI input](introduction-multiplayer-ui-input.md) + * [Configure multiplayer UI input](configure-multiplayer-ui-input.md) + * [On-screen Controls](on-screen-controls.md) + * [Introduction to on-screen Controls](introduction-on-screen-controls.md) + * [Create an on-screen button Control](create-on-screen-button-control.md) + * [Create an on-screen stick Control](create-on-screen-stick-control.md) + * [Create a custom on-screen Control](create-custom-on-screen-control.md) * [Editor Features](EditorFeatures.md) * [Using Input in the Editor](UseInEditor.md) * [Debugging](debugging.md)