tacstudios.tngl.sh
A game about forced loneliness, made by TACStudios
1---
2uid: input-system-debugging
3---
4# Debugging
5
6- [Debugging](#debugging)
7 - [Input Debugger](#input-debugger)
8 - [Debugging Devices](#debugging-devices)
9 - [Debugging Actions](#debugging-actions)
10 - [Debugging users and PlayerInput](#debugging-users-and-playerinput)
11 - [Debugging layouts](#debugging-layouts)
12 - [Debugging remotely](#debugging-remotely)
13 - [Input visualizers](#input-visualizers)
14 - [`InputControlVisualizer`](#inputcontrolvisualizer)
15 - [`InputActionVisualizer`](#inputactionvisualizer)
16 - [Device Simulator](#device-simulator)
17 - [Unity Remote (iOS, Android)](#unity-remote)
18 - [Other tips:](#other-tips)
19
20When something isn't working as expected, the quickest way to troubleshoot what's wrong is the Input Debugger in the Unity Editor. The Input Debugger provides access to the activity of the Input System in both the Editor and the connected Players.
21
22To open the Input Debugger, go to __Window > Analysis > Input Debugger__ from Unity's main menu.
23
24## Input Debugger
25
26
27
28The Input Debugger displays a tree breakdown of the state of the Input System.
29
30|Item|Description|
31|----|-----------|
32|Devices|A list of all [Input Devices](Devices.md) that are currently in the system, and a list of unsupported/unrecognized Devices.|
33|Layouts|A list of all registered Control and Device layouts. This is the database of supported hardware, and information on how to represent a given piece of input hardware.|
34|Actions|Only visible in Play mode, and only if at least one [Action](Actions.md) is enabled.<br><br>A list of all currently enabled Actions, and the Controls they are bound to.<br><br>See [Debugging Actions](#debugging-actions).|
35|Users|Only visible when one or more `InputUser` instances exist. See documentation on [user management](UserManagement.md).<br><br>A list of all currently active users, along with their active Control Schemes and Devices, all their associated Actions, and the Controls these Actions are bound to.<br><br>Note that `PlayerInput` uses `InputUser` to run. When using `PlayerInput` components, each player has an entry in this list.<br><br>See [Debugging users and PlayerInput](#debugging-users-and-playerinput).|
36|Settings|The currently active Input System [settings](Settings.md).|
37|Metrics|Statistics about Input System resource usage.|
38
39### Debugging Devices
40
41In the Input Debugger window, navigate to the __Devices__ list and double-click any [Input Device](Devices.md). This opens a window that displays information about the Device, including real-time state information for its Controls.
42
43
44
45The top of the Device window displays general information about the specific Device, such as name, manufacturer, and serial number.
46
47The __Controls__ section lists the Device's Controls and their individual states. This is useful when debugging input issues, because you can verify whether the data that the Input System receives from the Input Device is what you expect it to be. There are two buttons at the top of this panel:
48
49* __HID Descriptor__: Only displayed for devices that use the HID protocol to connect. This opens a window that displays the detailed [HID](HID.md) specifications for the Device and each of it's logical controls.
50
51* __State__: Display the current state of the Device in a new window. This is identical to the information displayed in this view, but doesn't update in real time, so you can take a snapshot of input state data and take the time to inspect it as needed.
52
53The __Events__ section lists all [input events](Events.md) generated by the Device. You can double-click any event in the list to inspect the full Device state at the time the event occurred. To get a side-by-side difference between the state of the Device at different points in time, select multiple events, right-click them, and click __Compare__ from the context menu.
54
55### Debugging Actions
56
57The Input Debugger window lists all enabled [Actions](Actions.md) in the __Actions__ list. This list only appears if at least one Action is active and the Editor is in Play mode. If an Action has actively bound Controls, you can click the arrow next to the Action to see a list of the Controls. This is useful to debug whether your Bindings correctly map to the Controls you want them to bind to. See documentation on [Binding resolution](ActionBindings.md#binding-resolution) for more information about how Unity maps Bindings to Controls.
58
59>__Note__: Actions that belong to [`InputUsers`](UserManagement.md) don't appear here. They appear in the [__Users__](#debugging-users-and-playerinput) list instead.
60
61### Debugging users and PlayerInput
62
63When there are [`InputUser`](UserManagement.md) instances (if you use `PlayerInput`, each `PlayerInput` instance implicitly creates one), the Input Debugger's __Users__ list displays each instance along with its paired Devices and active Actions. The listed Devices and Actions work the same way as those displayed in the [__Devices__](#debugging-devices) and [__Actions__](#debugging-actions) lists in the debugging window.
64
65
66
67### Debugging layouts
68
69The [__Layouts__](Layouts.md) list in the Input Debugger window displays a breakdown of all registered [Control and Device layouts](Layouts.md). This is the database of supported hardware and the knowledge of how to represent a given piece of input hardware. It's useful when you want to [create a new Device mapping](HID.md#creating-a-custom-device-layout) and see how the Input System represents it.
70
71
72
73### Debugging remotely
74
75You can connect the Input Debugger to a Player that runs on a remote computer or device. This makes it possible to observe input activity from the Player in the Editor. This connection uses the `PlayerConnection` mechanism, which is the same one the Unity profiler uses to connect to a Player.
76
77>__Note__: At the moment, debugging input in Players is restricted to seeing Devices and events from connected Players. There is no support for seeing other input-related data such as Actions and input users from Players.
78
79To see remote Devices from built Players, open the Input Debugger window's __Remote Devices__ drop-down list. This list displays the remote Player instance you can connect to (if there are any). The same list appears in the Profiler and Console windows, and any connections are shared between those windows. If any Player(s) are connected, you can enable __Show remote devices__ in the same drop-down list. If Players are connected, and __Show remote devices__ is enabled, the [__Devices__](#debugging-devices) list in the Input Debugger window splits into a __Local__ section and a __Remote__ section. The __Remote__ section displays any Input Device from any connected Player, and lets you inspect Device state and events in real time, as if it were a local Device.
80
81## Input visualizers
82
83The Input System package comes with a __Visualizers__ sample, which provides various components which let you monitor the state of various Input System elements in real time using on-screen visualizers.
84
85To install the sample, navigate to the Input System package in the Package Manager window (see [Installation](Installation.md)), and next to the __Visualizers__ sample, click __Import in project__.
86
87The sample provides two visualizer components:
88
89### `InputControlVisualizer`
90
91Visualizes the current state of a single Control in real time. You can have multiple Control visualizers to visualize the state of multiple Controls. Check the `GamepadVisualizer`, `MouseVisualizer`, or `PenVisualizer` Scenes in the sample for examples.
92
93
94
95### `InputActionVisualizer`
96
97Visualizes the current state of a single Action in real time. You can have multiple Action visualizers to visualize the state of multiple Actions. This can also display the current value of the Action and the Control currently driving the Action, and track the state of [Interactions](Interactions.md) over time. Check the `SimpleControlsVisualizer` Scene in the sample for examples.
98
99
100
101## Device Simulator
102
103When Device Simulator window is in use, mouse and pen inputs on the simulated device screen are turned into touchscreen inputs. Device Simulator uses its own touchscreen device, which it creates and destroys together with the Device Simulator window.
104
105To prevent conflicts between simulated touchscreen inputs and native mouse and pen inputs, Device Simulator disables all native mouse and pen devices.
106
107## Unity Remote
108
109The Unity Remote is an app available for iOS and Android which allows using a mobile device for input while running in the Unity Editor. You can find details about the app and how to install it in the [Unity manual](https://docs.unity3d.com/Manual/UnityRemote5.html).
110
111If you would like to try out the Unity Remote app, you can [install](Installation.md#installing-samples) the "Unity Remote" sample that is provided with the Input System package.
112
113>__Note__: Joysticks/gamepads are not yet supported over the Unity Remote. No joystick/gamepad input from the mobile device will come through in the editor.
114
115>__Note__: This requires Unity 2021.2.18 or later.
116
117When in play mode in the Editor and connected to the Unity Remote app, you will see a number of Devices have been added with the [`InputDevice.remote`](../api/UnityEngine.InputSystem.InputDevice.html#UnityEngine_InputSystem_InputDevice_remote) flag set to true:
118
119- [`Touchscreen`](../api/UnityEngine.InputSystem.Touchscreen.html)
120- [`Accelerometer`](../api/UnityEngine.InputSystem.Accelerometer.html)
121
122If a gyro is present on the mobile device:
123
124- [`Gyroscope`](../api/UnityEngine.InputSystem.Gyroscope.html)
125- [`AttitudeSensor`](../api/UnityEngine.InputSystem.AttitudeSensor.html)
126- [`LinearAccelerationSensor`](../api/UnityEngine.InputSystem.LinearAccelerationSensor.html)
127- [`GravitySensor`](../api/UnityEngine.InputSystem.GravitySensor.html)
128
129These Devices can be used just like local Devices. They will receive input from the connected mobile device which in turn will receive the rendered output of the game running in the editor.
130
131The [`Accelerometer`](../api/UnityEngine.InputSystem.Accelerometer.html) device will automatically be enabled and will not need you to call [`InputSystem.EnableDevice`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_EnableDevice_UnityEngine_InputSystem_InputDevice_) explicitly. Setting the sampling frequency on the accelerometer from the Unity Remote using [`Sensor.samplingFrequency`](../api/UnityEngine.InputSystem.Sensor.html#UnityEngine_InputSystem_Sensor_samplingFrequency) has no effect.
132
133The remaining sensors listed above will need to be explicitly enabled via [`InputSystem.EnableDevice`](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_EnableDevice_UnityEngine_InputSystem_InputDevice_) just like local sensors. Setting the sampling frequency on these sensors from the Unity Remote using [`Sensor.samplingFrequency`](../api/UnityEngine.InputSystem.Sensor.html#UnityEngine_InputSystem_Sensor_samplingFrequency) will be relayed to the device but note that setting the frequency on one of them will set it for all of them.
134
135Touch coordinates from the device will be translated to the screen coordinates of the Game View inside the Editor.
136
137## Other tips:
138
139To record events flowing through the system, use this code:
140
141```C#
142
143 // You can also provide a device ID to only
144 // trace events for a specific device.
145 var trace = new InputEventTrace();
146
147 trace.Enable();
148
149 var current = new InputEventPtr();
150 while (trace.GetNextEvent(ref current))
151 {
152 Debug.Log("Got some event: " + current);
153 }
154
155 // Also supports IEnumerable.
156 foreach (var eventPtr in trace)
157 Debug.Log("Got some event: " + eventPtr);
158
159 // Trace consumes unmanaged resources. Make sure you dispose it correctly to avoid memory leaks.
160 trace.Dispose();
161
162```
163
164To see events as they're processed, use this code:
165
166```C#
167
168 InputSystem.onEvent +=
169 (eventPtr, device) =>
170 {
171 // Can handle events yourself, for example, and then stop them
172 // from further processing by marking them as handled.
173 eventPtr.handled = true;
174 };
175
176```