Setting up the Input System

Scripting Player Movement

Customizing New Input Actions

Taking Advantage of the Input System Scripting API

Debugging and Testing the Input System

Challenge 1: Setting up the Input System

Challenge 2: Configure the Wheel Drive Component’s Handbrake Input

Challenge 3: Configure the Wheel Drive Component’s Acceleration and Steering Angle Inputs

Challenge 4: Setting up for a Gamepad

Recorded Live Session - Using the Input System in Unity

Submissions - Using the Input System in Unity

Live Session - InputSystemAssets.zip

In this project, you'll learn how to take advantage of Unity's new Input System. 

2020.1

2019.4

Using the Input System in Unity

4e46eb74-5dee-50b8-b405-27d6e4bb0b4f:6udFvAlfFjsjj7eis1c7dn

Debugging Devices

Debugging Actions 

Debugging Users and PlayerInput

Debugging Layouts

Debugging Remotely

Input Visualizers 

Input Action Visualizers

Input Testing

Setting Up Test Assemblies

Setting Up Test Fixtures

Next Steps

For this tutorial, you will follow a step by step process of how to debug your inputs. This will show you the various areas you can troubleshoot your input and how to work with them 

Games

To get started, open the Input Debugger by selecting from the top menu dropdown: 
Window > Analysis > Input Debugger.

In the Devices list of the Input Debugger, a list of all Input Devices currently in the system are displayed, along with a list of unsupported/unrecognized devices.

1. Double-click on a Keyboard or Gamepad device displayed in the list of devices. This opens a window that displays information about the device, including real-time state information.

2. The top of the device window displays some information about the device itself, it’s useful to know your device's layout and interface as these can affect the way they need to be handled. For debugging purposes, you might need to check Device ID, Flags, and Keyboard Layout.  

3. Below that is the Controls section, which displays the current Editor’s state. Make sure to verify that the input you’re debugging is what the Input System has paired correctly. For instance, on a UK keyboard, the input “backslash” is paired with the “#” key as they’re swapped on the American layout.

The Value column is useful as it shows the input states in real-time. Press any keys or button on your device and the value associated with it will change to 1 when pressed. Keyboard values are binary; however, with a controller’s D-Pad or analog stick, you’ll see a Vector2 for input.  

4. At the bottom of the keyboard window is the Events section. Here is where you can see your real-time input events generated by your device. If you want to see the frames occurring with your inputs, click Record Frames.

Press two different keys to generate their data to the Events list. Two STAT rows will be created for each. The first is your actual input and the second is resetting the values back to their unpressed state. If you are using Keyboard, a TEXT row will also appear, detailing the key pressed. 

5. Now that you have some input logged, hold CTRL, and select the first STAT row in each pair. Now right-click one of the selected inputs and select Compare on the context menu.

This opens a new Keyboard window which by default has Show Only Differences selected. You can compare your inputs here to see the differences between them.

6. Click Save on the top bar of the Events section to save your recorded input. This will save as a .inputtrace file, which can be loaded in by anyone with the Load button.

The Window menu button has been selected, Analysis on the dropdown menu is opened and Input Debugger is highlighted.

Opening the Input Debugger window.

The Devices list is open in the Input Debugger window.

The Input Debugger’s Devices list

The information on the device is shown in the window displayed when opening a device from the Devices list.

The device’s information

The device’s controls are shown in the Controls section of the window displayed when opening a device from the Device list. 

The Controls section of the device’s window.

Some keys have been pressed to get info on the Events section of the window that displays when opening a device in the Device’s list. The first STAT row of each STAT pair has been selected and right-clicked. Compare is highlighted in the context menu.

The Events section of the device window and the comparable inputs.

The Input Debugger lists all enabled actions in the Actions list. It can be used to debug whether your bindings are set up correctly. Note: Actions that belong to InputUsers won’t appear in the Actions list. Instead, they are listed under Users. The next section of the tutorial shows how to debug users. The Actions section will not appear in the Input Debugger unless two criteria are met: 

To get you set up with the minimum requirements needed to be able to debug actions, follow the instructions below:1. Create an empty GameObject by selecting GameObject > Create Empty, then rename it to “Action Example”.2. In the Project window, make a new script by right-clicking and selecting Create > C# Script and name it “InputDebuggerActionExample”.3. Open the script you just created, delete all lines of code inside and paste in the following code: 

using UnityEngine;
using UnityEngine.InputSystem;

public class InputDebuggerActionExample : MonoBehaviour
{
    public InputAction exampleAction;
    
    void OnEnable()
    {
       exampleAction.Enable();
    }
}

This is the minimum amount of code you need to get an action to display in the Input Debugger. Add this script to your Action Example GameObject. Now when you click Play, the Actions section will appear in the Input Debugger, and an Example is listed inside of it.

Note: The word Action is removed from the end of Action names in the Input Debugger.

4. Exit Play Mode. On the Action Example GameObject, you created and added the InputDebuggerActionExample script to, your InputAction is displayed as it’s set to Public in code. Select the + button on the right of it and select the Add Binding option. A <No Binding> row will appear in the ExampleAction section.

5. Double-click on the <No Binding> row to open its set-up menu. In the path section, add a Keyboard or Gamepad input. For the sake of this tutorial, it doesn’t matter what you choose as it’s just an example.

6. Repeat Steps 4 and 5 but use a different device’s binding path.

 7. Now when you click Play, the Actions list will display both of your Actions.  

Using the Actions list in the Input Debugger makes it easy to check what Actions are enabled and what inputs are bound to the actions.  

The Input Debugger Action Example script has been attached to Action Example GameObject and has two bindings listed in its Example Action variable, Enter on the Keyboard and Button South on the Gamepad.

The Input Debugger Action Example script in the Inspector.

The Editor is in Play mode and the Actions list is now visible in the Input Debugger window. Listed inside the Actions list is our Example Action object which the Input Debugger has shorted to the name Example. The two bindings are listed under Example.

The Actions list is now visible when the Editor is in Play mode.

When you create InputUser instances the Users list will display them in the Input Debugger when the Editor is in Play mode. If you use PlayerInput components, they each will implicitly create an InputUser instance. Inside each User listed is their Control Scheme along with Paired Devices and Actions. These work the same as the general Devices and Actions lists, except the User versions are specific to the User. This allows you to debug input per specific players, who might be using different methods of input, such as different Gamepads. The Users list will not appear in the Input Debugger unless two criteria are met:  

There is at least one Input User instance.

To get some InputUser instances so you can see them in the Input Debugger, follow these steps:

1. Create an empty GameObject with GameObject > Create Empty, and then rename it to “Player 1”.

2. Select Add Component at the bottom of the Inspector on Player 1 and then navigate to Input > Player Input.

3. Select Create Actions… on the PlayerInput component and save the .inputactions file to your Assets folder. 

4. Insert your new Input Actions Asset into the Actions field.

5. In Default Scheme select Gamepad. If you don’t have a Gamepad or any other alternatives to Keyboard&Mouse, select Keyboard&Mouse in this step and skip to Step 8. 

6. Right-click your Player 1 GameObject in the hierarchy and select Duplicate in the context menu. 

7. Rename your duplicate to “Player 2”

8. In Player 2’s PlayerInput component, change the Default Scheme to Keyboard&Mouse.

9. Click Play, in Input Debugger you’ll now see the Users list which displays two users with separate Control Schemes. They have different Paired Devices and Actions. You can double-click on a User’s Paired Device to open up the device window, just like in the Devices list.

The Player Input component is attached to the Player 1 GameObject and has an Input Action Asset in its Actions field. The Default Scheme is set to Gamepad. 

The Player Input component in the Inspector.

The Users list is expanded in the Input Debugger and inside are two users, one has a Keyboard&Mouse for their Control Scheme and Paired Device while the other has a Gamepad for their Control Scheme and Paired Device.

The Users list in the Input Debugger.

The Layouts list in the Input Debugger window displays a breakdown of all registered Controls and Devices layouts. 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 and see how the Input System represents it. 

The Layouts list expanded in the Input Debugger window.

The Layouts list in the Input Debugger.

The Input Debugger can remotely connect to a Player that is running a build of the project. This makes it possible to observe input activity from the Player in the Editor. This connection uses the PlayerConnection mechanism, which is also used in the Profiler and Console. 

Debugging remotely is limited to seeing Player Devices and subsequently Player Input Events.  

To see Input remotely, follow these steps:

1. In File > Build Settings, make sure you have Development Build enabled. This feature is only for development builds.

2. Build and Run a project that has the Input System package installed.

3. Open the Editor side-by-side with the running application.

4. In Input Debugger, open the Remote Devices… dropdown and select your device on the list.

 5. Devices are now split into two lists, Local and Remote. In Remote, your device is listed. 

6. Open the Remote Keyboard’s device window by double-clicking it.

7. Click on the running application to focus it and press any keys on your keyboard. The Events window displays real-time the input events occurring from the remote input on the external build.

Remote Devices has been selected in the Input Debugger top bar, a remote device is highlighted in the menu. 

A remote device in the Remote Devices menu.

The Devices list has been expanded and inside is now split into two lists, Local and Remote. Remote is expanded to show a remote device with its remote input devices listed inside.

Remote devices in the Devices list.

A remote keyboard has been opened from the Devices list. It shows real-time information on the devices Controls and Events.

A remote keyboard

The Input System package comes with a Visualizers sample. It provides various components which let you monitor the state of various Input System elements in real time using on-screen visualizers.

To install and add the Visualizers sample, follow these steps:

1. Open the Input System in the Package Manager by selecting from the top menu dropdown: Window > Package Manager > Input System.

2. In the Samples section of the Package’s page, select Import for the Visualizers sample.

 Once this is installed, you’ll have the Visualizers sample installed in your project. There’s two components which can connect input to visualizers. This section of the tutorial will cover both. 

The InputControlVisualizer connects to input bindings directly and doesn’t require any Actions.

1. In your Project scene, select GameObject > Create Empty to create an empty GameObject.

2. Rename your empty GameObject to “Input Control Visualizer”.

3. Select Add Component and select Input > Debug > Input Control Visualizer.

6. In the Control Path dropdown menu, select a button from a Gamepad or key on a Keyboard you’d like to visualize.

7. In the Label field, add a label that is appropriate with the control you’re testing.

 8. Click Play and click on the Game window to focus it.

9. Press your Control Path’s assigned button or key, this will cause the visualizer to light up with a 1 next to it.

10. While the Editor is still in Play mode, change the X and Y variables to move the visualizer around the screen. Also change the W and H variables to increase and decrease the width and height of the visualizer.

11. Finally, change the Control Path to different bindings. Some interesting visualizations you can try out are Gamepad’s Left or Right Stick and the Left or Right Trigger. You can also try the mouse’s Click Count, Delta and Position.

With this knowledge, you can now create a Visualizer for any Control Path. These are good for quick troubleshooting or small projects, but for longer term solutions, you might choose to create Visualizers for your Actions, which can reduce a lot of the work. This can be done with the InputActionVisualizer component.

The Input System has been opened in the Package Manager. Inside the samples section, the Visualizers sample can be found.

The Visualizers sample inside the Input System’s Package Manager page.

The Input Control Visualizer component has been attached to the Input Action Visualizer GameObject. The Visualization is set to Value and Control Path is set to Button South on the Gamepad. The Rect W is at 30. The Label field has the letter A typed in.

The Input Control Visualizer in the Inspector.

The Editor is in Play mode. The Visualizer is in the Game window and is displayed green with a 1 beside it, representing that the Gamepad’s South Button is being held down.

The Visualizer displays the Gamepad’s Button South input.

The InputActionVisualizer is very similar to the InputControlVisualizer but requires Actions instead of Control Paths. The benefit of this is that referencing an Action allows for the Visualizer to represent multiple types of inputs, as Actions can be assigned multiple controls and inputs. For instance, a movement Action could be set up for both a gamepad and keyboard. With the InputControlVisualizer, you’d have to manually configure a Visualizer for the gamepad’s left stick and also for each keyboard arrow key or WASD key. With an InputActionVisualizer, the Input Action Asset could have the gamepad’s left stick and both the keyboard’s arrow keys and WASD keys all binded to one action. This way you can have your Visualizer connected to multiple sources of input. 

Follow these steps to set up your Actions with Visualizers:

1. You’ll need an Input Action Asset, if you don’t have one, you can create one by following this tutorial.

2. In your Project window, right-click to select: GameObject > Create Empty to create an empty GameObject.

3. Rename your empty GameObject to “Input Action Visualizer”.

4. Select the Add Component button in the Inspector, and select: Input > Debug > Input Action Visualizer.

7. For the Action Reference, add an Action from your Input Action Asset. If you are using the Input Action Asset from Step 1, add the Player/Move Action. Alternatively, you can type the Action’s name into the Action Name field (“Player/Move”).

8. Fill the Label field appropriately. if you chose the Action Player/Move then label the visualizer “Player/Move”.

9. Click Play and click on the Game window to focus it.

10. Press the controls assigned to your Action. If you chose the Player/Move Action, use the Gamepad Left Stick or the W A S D / Arrow Keys on the keyboard. If you have a Gamepad you’ll notice that you can go between the Gamepad and Keyboard, the Visualizer is only listening to the Action. 

11. Finally, change the Action Reference/Action Name to different Actions. If you don’t have a Gamepad, you can test out mouse and keyboard inputs bound to the same Action (eg. copy and paste the WASD keyboard controls for Player/Move into Player/Look).

Now that both types of Visualizers have been covered, you can now connect both Control Paths and Actions to Visualizers. 

The Input Action Visualizer component has been attached to the Input Action Visualizer GameObject. The Visualization is set to Value and Action Reference references the Player/Move Action from an Input Action Asset. The Rect W and H are at 100. The Label field has the Player/Move typed in.

The Input Action Visualizer in the Inspector.

The Editor is in Play mode. The Visualizer is in the Game window and displays a graph showing the current location of the Vector2 that is created by Player/Move.

The Visualizer displays the Action Player/Move input in Vector2 form.

The Input System has built-in support for writing automated input tests. You can create input tests entirely from code, without any dependencies or platform backends and physical hardware devices. The system considers the generated input from the automated input tests you write to be the same as input generated at runtime by actual platform code.  

In the Packages/manifest.json file of your project, com.unity.inputsystem must be listed in testables. This is necessary for test code that comes with the package to be included with test builds of your project. 

To start, check that you have this included.

1. Select the Packages drop down in the Project window.

3. Select Show in Explorer in the context menu.

4. Inside Packages, open the manifest.json file.

5. Ensure that under dependencies you have a “testables” section which includes “com.unity.inputsystem”. If you don’t, copy and paste it in with the following code:

{
    "dependencies": {
        // A list of your dependencies
    },
    "testables": [ "com.unity.inputsystem" ]
}

6. Open the Test Runner window by selecting Window > General > Test Runner

7. In EditMode in the Test Runner window, select Create EditMode Assembly Folder.

8. Inside your new folder there is an Assembly Definition, select it.

9. In the Inspector, add two new references to the Assembly Definition References, add Unity.InputSystem and Unity.InputSystem.TestFramework.

10. When finished, select Apply to apply the changes. The apply button can be found at the bottom of the Assembly Definition. 

Packages on the Project sidebar have been selected and right-clicked and the mouse is hovering over Show in Explorer in the context menu.

Selecting Show in Explorer

The Assembly Definition is in the Inspector and Unity.InputSystem and Unity.InputSystem.Framework have been added to the Assembly Definition References

The Assembly Definition with the Input System added to the Assembly Definition References

Use InputTestFixture to create an isolated version of the Input System for tests. The fixture sets up a blank, default-initialized version of the Input System for each test, and restores the Input System to its original state after the test completes. The default-initialized version has all built-in registrations (such as layout and processors), but doesn't have any pre-existing Input Devices.

To start, the following will set you up with a test that adds a device and presses a button on it. 

1. With a Test Assembly set up, open your Test Assembly’s Folder and select Create Test Script in current folder.

3. Add the following using statement at the top of the script: 

 4. Inherit your class from InputTestFixture. Your script should look something like this now: 

using NUnit.Framework;
//Your using statements
using UnityEngine.InputSystem;

namespace Tests
{
    public class NewTestScript : InputTestFixture
    {
       //Your tests
    }
}

5. Inside your method with “[Test]” in the line before it, add the two following lines of code as seen inside this method: 

[Test]
public void NewTestScriptSimplePasses()
{
        var gamepad = InputSystem.AddDevice<Gamepad>();
        Press(gamepad.buttonSouth);
}

 You won’t need a Gamepad for a test on the Gamepad’s input to run. You can choose any device and input you want to test with this code by changing parameters.

Use InputSystem.AddDevice<T>() to add devices easily and to feed input, the easiest way is to use the Press(button), Release(button), PressAndRelease(button), Set(control,value), and Trigger(action) helper methods provided by InputTestFixture.

6. Return to Unity and select Run All in the Test Runner window.

7. Open up the dropdown menus and check if your test succeeded.

With this knowledge, you can further develop more Input Testing and automate your input. Without the need of physical devices, testing the Input System is quick and accessible. You can check out more advanced Input Testing code examples here. 

The Test Runner window is open and the EditMode tab is selected. The Create Test Script in current folder button is highlighted. 

The Test Runner’s EditMode

All dropdowns have been opened and Run All has been selected. There is a green tick beside every dropdown signifying their item succeeded in the test. 

All tests succeeded after pressing Run All

With the completion of this tutorial, you’re ready to progress your debugging skills with the Input System. For starters, a lot more can be done with the input visualizers and input testing. You could create full layouts of your control schemes on-screen with the input visualizers to make a great development build interface. Additionally, you might develop some advanced tests with the input testing, such as simulating players changing between devices while playing. Finally, you will have seen lots of inspector fields that weren’t used in the tutorials, feel free to go back to these, experiment and read into them! 

Debugging and Testing the Input System

1. Debugging Devices

2. Debugging Actions

3. Debugging Users and PlayerInput

4. Debugging Layouts

5. Debugging Remotely

6. Input Visualizers

7. Input Action Visualizers

8. Input Testing

9. Setting Up Test Assemblies

10. Setting Up Test Fixtures

11. Next Steps

Complete this tutorial