Unity Input System
Read input through the Input System package (com.unity.inputsystem; Unity 6.3 LTS projects
use 1.20.x), which replaces the legacy Input.GetAxis/Input.GetKey Input Manager. Targets
Unity 6.3 LTS (6000.3).
When to use
- Movement, jump and fire input; action maps and control schemes; a
PlayerInputcomponent; reading aVector2from a stick or WASD; one set of actions for gamepad, keyboard and touch; the Unity rebinding API. Packages/manifest.jsonlistscom.unity.inputsystem, or the project has an*.inputactionsasset.
When not to use: input architecture across engines (buffering, remapping screens,
dead-zone design) → input-systems; moving the character once you have the vector →
unity-physics / unity-csharp-scripting.
Workflow
- Read Active Input Handling from the file.
ProjectSettings/ProjectSettings.assethasactiveInputHandler: 0(old Input Manager only),1(Input System only) or2(both). The package receives nothing at0, and any leftoverInput.GetAxiscall throws at1. GrepAssets/forInput.Getbefore choosing1; changing the value restarts the Editor, so tell the user. - Reuse the project-wide actions. New Unity 6 projects usually ship
Assets/InputSystem_Actions.inputactions, assigned as project-wide actions, with aPlayermap (Move,Look,Attack,Interact,Crouch,Jump,Previous,Next,Sprint) and aUImap. Add to it rather than creating a second asset. - Edit the asset as JSON when the Editor is closed. An
.inputactionsfile is JSON:maps[].actions[](name,type,expectedControlType) andmaps[].bindings[](pathsuch as<Keyboard>/space,action,groupsfor control schemes,isCompositeandisPartOfCompositefor WASD). Give each new action and binding a freshidGUID like the existing entries, keep the file valid JSON, and re-read it after writing. - Choose one way to read it:
- Project-wide actions in code,
InputSystem.actions.FindAction("Player/Move"): no asset reference to wire and the actions start enabled. The default for new code. PlayerInputcomponent when the project already uses it, or for local co-op (PlayerInputManagergives each joining device its own player).- An
InputActionReferenceor a separate asset when a tool or system needs its own actions; youEnable()andDisable()them yourself.
- Project-wide actions in code,
- Switch action maps for context (gameplay vs menu) instead of guarding every handler.
- Verify with the checks below.
Patterns
1. Project-wide actions, polled
using UnityEngine;
using UnityEngine.InputSystem;
public class PlayerControls : MonoBehaviour
{
private InputAction _move, _jump;
private void Awake()
{
_move = InputSystem.actions.FindAction("Player/Move");
_jump = InputSystem.actions.FindAction("Player/Jump");
}
private void Update()
{
Vector2 move = _move.ReadValue<Vector2>(); // continuous value
if (_jump.WasPressedThisFrame()) { /* jump */ } // edge, true for one frame
}
}2. Callbacks and map switching
private InputActionMap _player, _ui;
private void Awake()
{
_player = InputSystem.actions.FindActionMap("Player");
_ui = InputSystem.actions.FindActionMap("UI");
}
private void Start() => _ui.Disable(); // project-wide actions enable every map at startup
private void OnEnable() => _player.FindAction("Attack").performed += OnAttack;
private void OnDisable() => _player.FindAction("Attack").performed -= OnAttack;
private void OnAttack(InputAction.CallbackContext ctx) { /* attack once per press */ }
public void OpenMenu() { _player.Disable(); _ui.Enable(); }
public void CloseMenu() { _ui.Disable(); _player.Enable(); }3. PlayerInput with Send Messages
PlayerInput with Behavior = Send Messages calls On<ActionName>(InputValue) on scripts on
the same GameObject: void OnMove(InputValue v) => _move = v.Get<Vector2>();,
void OnJump(InputValue v) { if (v.isPressed) Jump(); }. Broadcast Messages also reaches
children; Invoke Unity Events and Invoke C# Events need no naming convention.
Verify
No Editor needed: parse the
.inputactionsJSON and confirm every name your code passes toFindAction/FindActionMapexists (for"Player/Jump", a mapPlayerwith an actionJump), and that composites have all their parts. ConfirmactiveInputHandlermatches the code.Tests: the package's
InputTestFixtureadds virtual devices and presses controls from code. Listcom.unity.inputsystemunder"testables"inPackages/manifest.jsonand addUnity.InputSystemandUnity.InputSystem.TestFrameworkto the test.asmdef(assembly setup is inunity-csharp-scripting):using NUnit.Framework; using UnityEngine.InputSystem; public class JumpInputTests : InputTestFixture { [Test] public void SpaceTriggersJump() { var keyboard = InputSystem.AddDevice<Keyboard>(); var jump = new InputAction("Jump", InputActionType.Button, "<Keyboard>/space"); int performed = 0; jump.performed += _ => performed++; jump.Enable(); Press(keyboard.spaceKey); Assert.That(performed, Is.EqualTo(1)); } }Unity CLI with the game running:
unity command runtime simulate_keyinjects a key press (for exampleSpace) through the Input System into the running app, ifunity command --query simulatelists it for your target. Read the effect back withunity command script eval, and check the flags with--help.Hardware: ask the user to press the control and report what the Input Debugger (Window > Analysis > Input Debugger) shows for the device and action.
Gotchas
- No input at all.
activeInputHandleris0, or the action or map was never enabled. Project-wide actions andPlayerInput's default map start enabled; actions from any other asset do not. - Gameplay actions fire while a menu is open. Project-wide actions enable every map at
startup, including when
PlayerInputuses that asset. Disable the maps you do not want inStart(pattern 2). FindActionreturns null. The name orMap/Actionpath does not exist in that asset, or you edited a different asset than the one assigned as project-wide actions (Project Settings > Input System Package).InvalidOperationExceptionabout theUnityEngine.Inputclass. OldInput.GetAxis/GetKeycode runs whileactiveInputHandleris1. Port it, or set2while you migrate.- Buttons read 0 with
ReadValue. Presses are edges. UseperformedorWasPressedThisFrame(), and read actions inUpdate:WasPressedThisFrameinFixedUpdatemisses presses or sees them twice. - Send Messages handlers never fire. The script must be on the same GameObject as the
PlayerInput; Broadcast Messages reaches children. - Handlers run twice.
OnEnablesubscribed again without anOnDisableunsubscribe. - Touch or gamepad not detected. The device is not in any control scheme the
PlayerInputallows, or a 2D Vector composite is missing a part.
References
- Read
references/rebinding.mdwhen adding "press a key to rebind", saving and loading binding overrides, or split-screen local multiplayer withPlayerInputManager.
Related skills
input-systems: engine-neutral input architecture, buffering and remapping design.unity-csharp-scripting: the MonoBehaviour around these handlers and test assemblies.unity-physics: applying the input vector to a rigidbody.
Version notes
Last verified: 2026-11-11.
com.unity.inputsystem1.20.1 (released 2026-10-05, minimum Unity 6000.0) is the latest version in the Unity package registry (https://packages.unity.com/com.unity.inputsystem). The project-wide actions template,activeInputHandlervalues 0/1/2 andInputTestFixturewere checked in the 1.20.1 package source and itsDocumentation~pages (Testing, set-up-test-assemblies, write-tests).- Manual: https://docs.unity3d.com/Packages/com.unity.inputsystem@1.20/manual/index.html
runtime simulate_keyis acom.unity.pipeline1.0.0-pre.1 command (pre-release): https://docs.unity3d.com/Packages/com.unity.pipeline@1.0/manual/index.html