Home Unity Tutorials

New Unity Input System: Getting Started

In this Unity Input System tutorial, you’ll learn how to convert player input in your existing projects from the old Input Manager to the new Input System.

4.5/5 4 Ratings

Version

  • C# 7.3, Unity 2020.1, Unity

Handling input is a pillar of creating a successful game. Input devices help player characters perform actions inside the game such as walking, jumping and climbing.

Recently, many new platforms have come out, introducing more Unity input devices. These include touch screens, VR controllers and gamepads from different game consoles. If you want your game to support different platforms, you need to write code to handle the logic for different devices. The more platforms you support, the more complex your code will be.

Luckily, there’s a new Unity Input System that helps developers deal with this situation, making input-related code easier to manage.

In this tutorial, you’ll learn:

  • The features of the new Input System.
  • How the new system works.
  • How to migrate apps to the new Input System from the old Input Manager.

The materials for this tutorial were built in Unity version 2020.1. You can get this version of Unity from the Unity website or install it with the Unity Hub.

Note: Although this tutorial is for beginners, you’ll need to have some basic knowledge of Unity development and how to work with Unity Editor to complete it. If you’re new to Unity development, check out our tutorial on Getting Started In Unity.

Getting Started

First, download the starter project for this tutorial using the Download Materials button at the top or bottom of this page. Unzip its contents and open NewUnityInputSystem-Starter in Unity.

After the project loads, you’ll see the RW folder in the Project Window:

RW Project Folder

Take a look at the organization of the folder:

  • Fonts: Fonts used in the scene.
  • Materials: Materials for the scene.
  • Models: 3D meshes for the player character and game environments.
  • Prefabs: Pre-built components composed of Scripts and Models.
  • Scenes: The game scene.
  • Scripts: Scripts with game logic.
  • Settings: The settings file, which is where you’ll put the input settings.
  • Shaders: Shaders for special effects like the player’s shadow.
  • Textures: The graphics used by Materials and UIs.

The starter project is a simple platformer game. You control the player character by moving around and jumping to collect coins.

The game is ready to play. Open GameScene from the Scenes folder and click Play to try the game for yourself!

Platformer gameplay video

Currently, the Move and Jump controls use the old Unity Input Manager. You’ll learn how to use the new Input System to replace the old system later in the tutorial.

What’s New in the Unity Input System

Before diving into the code, take a look at the new Input System’s features.

Simpler Action and Binding Architecture

The old input system checked input from different devices every frame to determine whether players took an action.

The following code, which supports both gamepads and keyboards, is an example of the old way of doing things:

bool isGamepad = Input.GetAxis("Gamepad Fire") != 0f;
if (isGamepad)
{
    return Input.GetAxis("Gamepad Fire") >= triggerAxisThreshold;
}
else
{
    return Input.GetButton("Fire");
}

The code uses if-else branching to handle support for different devices and their associated actions.

The new Input System separates device input from code actions. That means you only have to handle the actions the players trigger. You don’t need to know which device the player is using or which button they’re clicking.

An input event in the new system is called an action, while the mapping between an action and an input device is a binding.

Gathering Information With the Input Debug Tool

The Input System provides you with a new tool called Input Debugger. Open it by selecting Window ▸ Analysis ▸ Input Debugger from the menu.

The Input Debugger helps developers by gathering the following information in one place:

The state of the Input System, including:

  • Device: Information about the connected devices.
  • Layout: Which controls those devices provide.
  • Setting: The configuration of the input system.

It also provides real-time information about a specific device. Open this by double-clicking the device from the device list in the Input Debugger window.

Here’s a demo of the Input Debugger in action:

Input Debugger Demo

Feel free to keep the Input Debugger open while you work through the tutorial.

Support for Multiple Devices and Platforms

With the increased flexibility from the Input System’s new architecture, Unity can support many different input devices, including:

  • Keyboard
  • Mouse
  • Pen
  • TouchScreen
  • Sensor
  • Joystick
  • GamePad
Note: The Input System also supports devices that implement the USB HID specification. For more details, check out Unity’s Supported Devices Documentation.

Understanding the New Input System

The new Input System has four building blocks that funnel events from player devices to your game code:

  • Input Action Assets: A settings file that contains the properties of the actions and their associated bindings.
  • Actions: Actions define the logical meanings of the input. You can find that information in the Input Action Assets.
  • Bindings: Bindings describe the connection between an action and the input device controls. You’ll find this information in the Input Action Assets, too.
  • PlayerInput: PlayerInput is a script that manages and links action events to the corresponding code logic.

Sometimes it’s easier to understand a new workflow if you can visualize it, so take a look at the image below:

New Input System Architecture

Break this down into its simplest steps:

  • First, the Unity Engine collects information from the connected devices and sends corresponding events, like a button click, to the Input System.
  • The Input System then translates those events into actions, based on the action and binding information stored in the Input Action Assets.
  • It then passes the actions to the PlayerInput script, which invokes the corresponding methods.

Now that you know a little more about how the Input System works, you’ll use it to control the game character in the coming sections.

Installing the New Input System

The first thing you’ll do is install the new Input System package. The standard Unity installation doesn’t include it.

Open Window ▸ Package Manager in the menu bar. Make sure that you select Unity Registry in the Packages dropdown, if you haven’t already.

Opening Package Manager

Find Input System on the list. Select it and click Install.

How to Install New Input System

Creating an Input Action Asset

Once you’ve installed the Input System package, you’ll create an Input Action Asset to store the settings for your actions and bindings.

Open the Project window and select Settings from RW. Right-click, select Create ▸ Input Actions and rename it to MyControl.

Creating a new input asset

Setting up the Action Editor

Double-click MyControl in Settings to open the Action Editor, which helps you manipulate actions and control bindings.

Action Editor Window

Since this is a new window, take a look at the sections:

  1. Action Maps: Groups of actions that occur in the game. You can group actions for different purposes, like player, gameplay or UI.
  2. Actions: The list of actions and bindings associated with the selected Action Map. In this panel, you create, modify or delete actions and bindings.
  3. Properties: Edit the action or binding properties in this panel, such the type of action and the controls you associated with the binding.
  4. Save Assets: This is a very important function: You must click Save Asset after making any changes to the Input Action Asset. If you forget to save, the setting won’t work. Thus, you won’t see the expected result and may think there’s a bug in the code.

    You can switch on Auto Save to prevent the problem, but it’s quite slow.

Now you’re ready to create your first action, the Jump action.

Creating a Jump Action

First, open the Action Editor and click the + icon in the ActionMap to create a new Action Map. Rename it from the default, New Action Map, to Player.

Then, in the Action panel, double-click New Action and rename it to a meaningful name: Jump.

Create Action Map

Finally, you need to add a binding to the Jump action. You’ll bind the Spacebar and Left Mouse Button to this action by following these steps:

  1. Select the Jump action, click the + icon and select Add Binding.
  2. Click the new binding item, <No binding>.
  3. Click the Path field in the Binding properties panel.
  4. Type Spacebar Keyboard and select Space [Keyboard] to create the binding for the Spacebar.
  5. Repeat steps 1–3 to create another binding for the Left Mouse Button.
  6. Type Left Button in the Path field and select Left Button [Mouse] to create the binding.

Congratulations, you’ve now associated the Jump action with the Spacebar on the keyboard and the left button on the mouse.

Jump Binding

Now to hook up those actions with your code!

Implementing the Jump Logic

First of all, you need to remove the old input logic from the project. Open Player.cs and navigate to the Update() method.

void Update()
{
    UpdateAnimation();

    if (!jumping && Input.GetKeyDown(KeyCode.Space))
    {
	HandleJump();
    }
}

As you can see, the current code triggers the animation updates, then it checks if the player has pressed the space bar in order to start a jump.

Now that the Jump action and its control bindings are ready, the next thing to do is link the action to the code.

Linking the Jump Action to the Code

Start by deleting the code in Update to remove the implementation of the old Input Manager so you can add Jump logic using the new Input System. Update will now only control the animations.

void Update()
{
    UpdateAnimation();
}

Save the script and go back to the editor. Select the Player object in the Hierarchy and add a PlayerInput component from the Inspector.

Next, you’ll drag MyControl to PlayerInput’s Actions. Make sure to set the Default Map to Player.

Adding

Finally, open Player.cs and add a new method called OnJump() with the following code:

public void OnJump()
{
    HandleJump();
}

You’ve associated this method with the Jump action by using this pattern to name it: public void On[Action Name Goes Here]().

For example, the Jump action invokes OnJump(), while the Attack action invokes OnAttack().

Click Save Asset in the Action Editor and run the game. Now you can use the SpaceBar or the left mouse button to make the player character jump. It’s really that easy!

New Jump Ready

Creating the Move Action

You’ve learned how to use the Input System to create a Jump action. Next up is the Move action! Move is similar to Jump, but it has a few key differences.

For example, the Jump action is a simple trigger event, while the Move action is an event that carries values: the movement direction, which comes from user input.

Again, you need to create the action and its binding. Start by going to Action Editor (double click MyControl if you lost the window) and click the + icon in the Actions panel to create a new action. Rename it to Move.

Next, open the Action properties panel, change Action Type to Value and Control Type to Vector 2.

Finally, remove <No Binding> by right-clicking and selecting Delete.

How to create a Move action

Now, you need to create the Move action’s bindings.

First, you’ll click the + icon in the header of the Move action. Then, select Add 2D Vector Composite, which will create four binding items corresponding to the up, down, left and right directions.

Now, you’ll set the path of each binding as follows:

  • Up: Up Arrow [Keyboard]
  • Down: Down Arrow [Keyboard]
  • Left: Left Arrow [Keyboard]
  • Right: Right Arrow [Keyboard]

Don’t forget to save the asset in the Action Editor!

Creating the Move binding

Implementing the Move Logic

Before adding new movement logic, you need to remove the implementation of the old Unity input.

Open Player.cs and go to FixedUpdate():

private void FixedUpdate()
{
    // 1
    float speedX = Input.GetAxisRaw("Horizontal");  // Left, Right
    float speedY = Input.GetAxisRaw("Vertical");  // Back, Forward
    moveVec = new Vector3(speedX, 0, speedY);

    if (jumping == false)
    {
        // 2
        UpdateWhenGrounded();
    }
    else
    {
        // 3
        UpdateWhenJumping();
    }
}

Note that FixedUpdate() is called in every fixed frame-rate frame.

Now, break this down:

  1. Input.GetAxisRaw returns the value of Axis. Input.GetAxisRaw("Horizontal") gives the value of the X-Axis, while Input.GetAxisRaw("Vertical") gives the value of Y-Axis.

    These two values define the movement vector moveVec, which you use to control the direction of the player movement.

  2. The logic of the player character’s behavior while it’s on the ground.
  3. The logic of the player character’s behavior while it’s jumping.

Now, delete all the code prior to the if statement to remove the old input logic. Add the following code above the class definition:

using UnityEngine.InputSystem;

This allows you to access values from the new Input System.

Then, add OnMove(), which the Move action invokes.

public void OnMove(InputValue input)
{
    Vector2 inputVec = input.Get<Vector2>();

    moveVec = new Vector3(inputVec.x, 0, inputVec.y);
}

When a player presses the Up, Down, Left or Right keys, it passes a Move action to this method, along with the values. Here’s how the key presses affect the values:

  • Up: (0, 1)
  • Down: (0, -1)
  • Left: (-1, 0)
  • Right: (1, 0)
  • No Key: (0, 0)
  • Up and Left: (1, -1)

InputValue is a new type you may not know. This class has a Get\() method that you can use to access its values. In this instance, you want the 2D Vector Composite you set in the binding to calculate the movement vector.

Click Play to test the logic.

Move Ready

Handling Actions

The new Input System provides four ways to handle action events.

In this tutorial, you used the SendMessages approach. You can change this option in the Behavior field in the PlayerInput component.

Input Behavior

SendMessage and BroadcastMessage are the simplest ways to handle actions. When you use these two options, the system invokes the method with a name matching the name of the action.

For example, in this tutorial, the Jump action invokes OnJump() and the Move action invokes OnMove().

BroadcastMessage is similar to SendMessage, except it can invoke the methods on any child GameObject. These two options are easy to use because you don’t need to configure anything to use them.

Using Invoke Unity Events

When using Invoke Unity Events, you configure the action much as you’d configure a button click in Unity UI.

This approach is more flexible, letting you use different methods in different objects. Those GameObjects don’t even need to have the PlayerInput component.

Using Invoke C# Events

This approach is as flexible as Invoke Unity Events. You can define the methods you want to use instead of using methods with a specific name. However, if you use this approach, you need to write code to control which methods to invoke.

Here is a sample of how this looks:

private void Awake()
{
    animator = GetComponentInChildren<Animator>();
    rigidbody = GetComponent<Rigidbody>();

    // 1
    GetComponent<PlayerInput>().onActionTriggered += HandleAction;
}

private void HandleAction(InputAction.CallbackContext context)
{
    // 2
    if(context.action.name == "Jump")
    {
        HandleJump();
    }
}

Here’s what this code does:

  1. Gets the PlayerInput component and registers the method to onActionTriggered.
  2. Controls which method to call for different actions.

Using the Update Cycle of the New Input System

In the old Unity Input Manager, you checked the input in every frame using Update(). In the new Input System, you may wonder when actions are being sent, and if they’re sent before every Update().

The new Input System uses a different update cycle that’s independent of MonoBehaviour‘s lifecycle. You can read more about it in Unity’s Execution Order documentation.

The system offers three Update Modes to control the update cycle. You can configure them in Project Settings ▸ Input System Package ▸ Update Mode.

Different update methods

Take a look at each of these nodes:

  • Dynamic Update: Processes events at irregular intervals determined by the current frame rate. This is the default setting.
  • Fixed Update: Processes events at fixed-length intervals. Time.fixedDeltaTime determines the length of the interval.
  • Manually: Events aren’t processed automatically; you process them when you call InputSystem.Update(). If you want a check similar to the old system, you can call InputSystem.Update() in Update().

These new options, as part of the new Input System, give you a lot more control over input, whilst also making it easier to support multiple input devices :]

Where to Go from Here?

Download the completed project using the Download Materials button at the top or bottom of this tutorial.

In this Unity Input tutorial, you’ve learned:

  • The basic layout of the new Input System.
  • How to use actions and bindings.
  • How to handle different kinds of player input efficiently.

To test your skill, try to add a Pause action to the game!

To learn more about the new Input System, you can read the Unity Input System manual.

I hope you have enjoyed this tutorial! If you have any questions or comments, please join the forum discussion below.

Average Rating

4.5/5

Add a rating for this content

4 ratings

More like this

Contributors

Comments