Unity Input System (new)
Read input through Unity's Input System package (com.unity.inputsystem 1.x; Unity 6.3 LTS
ships 1.20) — action-based, device-agnostic, rebindable. Targets Unity 6.3 LTS. This is the modern
replacement for the legacy Input.GetAxis/Input.GetKey Input Manager.
When to use
- Use when setting up movement/jump/fire input, defining an
.inputactions asset with
action maps and control schemes, wiring a PlayerInput component, reading a Vector2
stick/WASD value, or handling gamepad + keyboard + touch from one set of actions.
- Use when
Packages/manifest.json contains com.unity.inputsystem or the project has an
*.inputactions asset.
When not to use: rebindable-control architecture across engines → input-systems
(this skill is the Unity-specific API). Moving the character once you have the input vector
→ unity-physics / unity-csharp-scripting.
Core workflow
- Check Active Input Handling (Project Settings → Player). The package only receives
input when this is
Input System Package (New) or Both. Both is required if any old
Input.GetAxis code remains.
- Find or create the
.inputactions asset. New Unity 6 projects usually already have one
assigned as the project-wide actions (Project Settings → Input System Package; the
template file is InputSystem_Actions.inputactions) — reuse it rather than adding a
second asset. Add an action map (e.g. Gameplay), add actions
(Move = Value/Vector2, Jump = Button, Fire = Button), and bind them to controls and
composite bindings (WASD = 2D Vector composite).
- Choose how to read it:
PlayerInput component (designer-friendly) — drop it on the player, point it at the
asset, pick a Behavior (Send Messages / Broadcast / Invoke Unity Events / Invoke C#
Events). Best for single/local-coop players.
- Project-wide actions in code (
InputSystem.actions.FindAction("Move")) — no asset
reference to wire up, and the actions are already enabled.
- Direct in code (
InputActionReference / InputActionAsset) — most control; you
Enable() actions and read them. Best for systems and tools.
- Enable the actions/maps you read.
PlayerInput enables its default map automatically
and project-wide actions start enabled; actions from any other asset must be .Enable()d
(and disabled on teardown).
- Switch action maps for context (gameplay ↔ UI/menu) instead of guarding every handler.
- Verify with the Input Debugger (Window → Analysis → Input Debugger) to confirm devices
and that actions fire.
Patterns
1. PlayerInput with "Send Messages" (handlers on the same GameObject)
using UnityEngine;
using UnityEngine.InputSystem;
// PlayerInput (Behavior = Send Messages) calls On<ActionName>(InputValue) by name.
public class PlayerInputReceiver : MonoBehaviour
{
private Vector2 _move;
private void OnMove(InputValue value) => _move = value.Get<Vector2>(); // Move action
private void OnJump(InputValue value) { if (value.isPressed) Jump(); } // Button action
private void Update() { /* drive movement from _move */ }
private void Jump() { }
}
2. Reading an action directly in code (polling a value)
using UnityEngine;
using UnityEngine.InputSystem;
public class DirectMover : MonoBehaviour
{
[SerializeField] private InputActionReference moveAction; // assign the Move action
private void OnEnable() => moveAction.action.Enable(); // REQUIRED or it reads zero
private void OnDisable() => moveAction.action.Disable();
private void Update()
{
Vector2 move = moveAction.action.ReadValue<Vector2>(); // continuous value
transform.Translate(new Vector3(move.x, 0, move.y) * (5f * Time.deltaTime));
}
}
3. Project-wide actions (no asset reference)
using UnityEngine;
using UnityEngine.InputSystem;
public class ProjectWideMover : MonoBehaviour
{
private InputAction _move, _jump;
private void Awake()
{
// Looked up once; project-wide actions are preloaded and enabled by default.
_move = InputSystem.actions.FindAction("Move");
_jump = InputSystem.actions.FindAction("Jump");
}
private void Update()
{
Vector2 move = _move.ReadValue<Vector2>();
if (_jump.WasPressedThisFrame()) { /* jump */ }
}
}
4. Event callbacks + switching action maps (gameplay ↔ UI)
[SerializeField] private InputActionAsset actions;
private void OnEnable()
{
actions.FindAction("Gameplay/Fire").performed += OnFire; // edge event: fires once
actions.FindActionMap("Gameplay").Enable();
}
private void OnDisable() => actions.FindAction("Gameplay/Fire").performed -= OnFire;
private void OnFire(InputAction.CallbackContext ctx) => Shoot(); // ctx.ReadValue<T>() if needed
private void OpenPauseMenu() // change context, don't sprinkle if-checks
{
actions.FindActionMap("Gameplay").Disable();
actions.FindActionMap("UI").Enable();
}
private void Shoot() { }
Pitfalls
- No input at all → either Active Input Handling is still
Input Manager (Old), or you
forgot to Enable() the action/map. PlayerInput and project-wide actions start enabled;
actions from other assets do not.
- Gameplay actions fire while a menu is open → project-wide actions enable every action
map at startup, including when
PlayerInput uses that asset. In Start, disable the maps
you do not want (InputSystem.actions.FindActionMap("UI").Disable()) and enable only the
current one.
FindAction returns null → the name (or Map/Action path) does not exist in that
asset. Check the spelling in the Actions Editor; with project-wide actions, make sure the
asset you edited is the one assigned in Project Settings → Input System Package.
InvalidOperationException about the old input backend → some script still calls
Input.GetAxis/Input.GetKey while Active Input Handling is New. Port it or set Both.
- Buttons read as 0 with
ReadValue → button presses are edge events; use the
performed callback (or WasPressedThisFrame()), not per-frame ReadValue for triggers.
Send Messages handlers never fire → the receiving script must be on the same
GameObject as the PlayerInput; Broadcast Messages reaches children too.
- Leaking subscriptions → unsubscribe (
-=) in OnDisable; re-subscribing in OnEnable
without unsubscribing doubles up handlers.
- Touch/gamepad not detected → enable the matching control scheme and confirm the device
in the Input Debugger; the Vector2 composite needs all four bindings set.
References
- For interactive control rebinding (
PerformInteractiveRebinding), saving/loading
bindings as JSON, and local multiplayer with PlayerInputManager, read
references/rebinding.md.
- Primary docs: Unity Manual "Input System"
(
https://docs.unity3d.com/Manual/com.unity.inputsystem.html) and the package manual
(https://docs.unity3d.com/Packages/com.unity.inputsystem@1.20/manual/index.html),
including "About project-wide actions".
Related skills
input-systems — engine-agnostic input architecture (rebinding, buffering, multi-device).
unity-csharp-scripting — the MonoBehaviour these handlers live in.
unity-physics — applying the input vector to a Rigidbody.
1---2name: unity-input-system3description: >4 Wire player input in Unity 6.3 LTS with the Input System package: Input Actions, action maps,5 the PlayerInput component, and reading values via callbacks or polling. Use when the6 project has a .inputactions asset or com.unity.inputsystem, or when the user mentions the7 Unity Input System, InputAction, action maps, PlayerInput, control schemes, or rebinding.8metadata:9 source: https://skillmd.com/skills/junmystery/unity-input-system10---1112# Unity Input System (new)1314Read input through Unity's **Input System package** (`com.unity.inputsystem` 1.x; Unity 6.3 LTS15ships 1.20) — action-based, device-agnostic, rebindable. Targets **Unity 6.3 LTS**. This is the modern16replacement for the legacy `Input.GetAxis`/`Input.GetKey` Input Manager.1718## When to use1920- Use when setting up movement/jump/fire input, defining an `.inputactions` asset with21 action maps and control schemes, wiring a `PlayerInput` component, reading a `Vector2`22 stick/WASD value, or handling gamepad + keyboard + touch from one set of actions.23- Use when `Packages/manifest.json` contains `com.unity.inputsystem` or the project has an24 `*.inputactions` asset.2526**When *not* to use:** rebindable-control *architecture* across engines → `input-systems`27(this skill is the Unity-specific API). Moving the character once you have the input vector28→ `unity-physics` / `unity-csharp-scripting`.2930## Core workflow31321. **Check Active Input Handling** (Project Settings → Player). The package only receives33 input when this is `Input System Package (New)` or `Both`. `Both` is required if any old34 `Input.GetAxis` code remains.352. **Find or create the `.inputactions` asset.** New Unity 6 projects usually already have one36 assigned as the **project-wide actions** (Project Settings → Input System Package; the37 template file is `InputSystem_Actions.inputactions`) — reuse it rather than adding a38 second asset. Add an *action map* (e.g. `Gameplay`), add *actions*39 (`Move` = Value/Vector2, `Jump` = Button, `Fire` = Button), and bind them to controls and40 composite bindings (WASD = 2D Vector composite).413. **Choose how to read it:**42 - **`PlayerInput` component** (designer-friendly) — drop it on the player, point it at the43 asset, pick a *Behavior* (Send Messages / Broadcast / Invoke Unity Events / Invoke C#44 Events). Best for single/local-coop players.45 - **Project-wide actions in code** (`InputSystem.actions.FindAction("Move")`) — no asset46 reference to wire up, and the actions are already enabled.47 - **Direct in code** (`InputActionReference` / `InputActionAsset`) — most control; you48 `Enable()` actions and read them. Best for systems and tools.494. **Enable the actions/maps you read.** `PlayerInput` enables its default map automatically50 and project-wide actions start enabled; actions from any other asset must be `.Enable()`d51 (and disabled on teardown).525. **Switch action maps** for context (gameplay ↔ UI/menu) instead of guarding every handler.536. **Verify** with the Input Debugger (Window → Analysis → Input Debugger) to confirm devices54 and that actions fire.5556## Patterns5758### 1. `PlayerInput` with "Send Messages" (handlers on the same GameObject)5960```csharp61using UnityEngine;62using UnityEngine.InputSystem;6364// PlayerInput (Behavior = Send Messages) calls On<ActionName>(InputValue) by name.65public class PlayerInputReceiver : MonoBehaviour66{67 private Vector2 _move;6869 private void OnMove(InputValue value) => _move = value.Get<Vector2>(); // Move action70 private void OnJump(InputValue value) { if (value.isPressed) Jump(); } // Button action7172 private void Update() { /* drive movement from _move */ }73 private void Jump() { }74}75```7677### 2. Reading an action directly in code (polling a value)7879```csharp80using UnityEngine;81using UnityEngine.InputSystem;8283public class DirectMover : MonoBehaviour84{85 [SerializeField] private InputActionReference moveAction; // assign the Move action8687 private void OnEnable() => moveAction.action.Enable(); // REQUIRED or it reads zero88 private void OnDisable() => moveAction.action.Disable();8990 private void Update()91 {92 Vector2 move = moveAction.action.ReadValue<Vector2>(); // continuous value93 transform.Translate(new Vector3(move.x, 0, move.y) * (5f * Time.deltaTime));94 }95}96```9798### 3. Project-wide actions (no asset reference)99100```csharp101using UnityEngine;102using UnityEngine.InputSystem;103104public class ProjectWideMover : MonoBehaviour105{106 private InputAction _move, _jump;107108 private void Awake()109 {110 // Looked up once; project-wide actions are preloaded and enabled by default.111 _move = InputSystem.actions.FindAction("Move");112 _jump = InputSystem.actions.FindAction("Jump");113 }114115 private void Update()116 {117 Vector2 move = _move.ReadValue<Vector2>();118 if (_jump.WasPressedThisFrame()) { /* jump */ }119 }120}121```122123### 4. Event callbacks + switching action maps (gameplay ↔ UI)124125```csharp126[SerializeField] private InputActionAsset actions;127128private void OnEnable()129{130 actions.FindAction("Gameplay/Fire").performed += OnFire; // edge event: fires once131 actions.FindActionMap("Gameplay").Enable();132}133private void OnDisable() => actions.FindAction("Gameplay/Fire").performed -= OnFire;134135private void OnFire(InputAction.CallbackContext ctx) => Shoot(); // ctx.ReadValue<T>() if needed136137private void OpenPauseMenu() // change context, don't sprinkle if-checks138{139 actions.FindActionMap("Gameplay").Disable();140 actions.FindActionMap("UI").Enable();141}142private void Shoot() { }143```144145## Pitfalls146147- **No input at all** → either Active Input Handling is still `Input Manager (Old)`, or you148 forgot to `Enable()` the action/map. `PlayerInput` and project-wide actions start enabled;149 actions from other assets do not.150- **Gameplay actions fire while a menu is open** → project-wide actions enable *every* action151 map at startup, including when `PlayerInput` uses that asset. In `Start`, disable the maps152 you do not want (`InputSystem.actions.FindActionMap("UI").Disable()`) and enable only the153 current one.154- **`FindAction` returns null** → the name (or `Map/Action` path) does not exist in that155 asset. Check the spelling in the Actions Editor; with project-wide actions, make sure the156 asset you edited is the one assigned in Project Settings → Input System Package.157- **`InvalidOperationException` about the old input backend** → some script still calls158 `Input.GetAxis`/`Input.GetKey` while Active Input Handling is `New`. Port it or set `Both`.159- **Buttons read as 0 with `ReadValue`** → button *presses* are edge events; use the160 `performed` callback (or `WasPressedThisFrame()`), not per-frame `ReadValue` for triggers.161- **`Send Messages` handlers never fire** → the receiving script must be on the *same*162 GameObject as the `PlayerInput`; `Broadcast Messages` reaches children too.163- **Leaking subscriptions** → unsubscribe (`-=`) in `OnDisable`; re-subscribing in `OnEnable`164 without unsubscribing doubles up handlers.165- **Touch/gamepad not detected** → enable the matching control scheme and confirm the device166 in the Input Debugger; the Vector2 composite needs all four bindings set.167168## References169170- For interactive control **rebinding** (`PerformInteractiveRebinding`), saving/loading171 bindings as JSON, and **local multiplayer** with `PlayerInputManager`, read172 `references/rebinding.md`.173- Primary docs: Unity Manual "Input System"174 (`https://docs.unity3d.com/Manual/com.unity.inputsystem.html`) and the package manual175 (`https://docs.unity3d.com/Packages/com.unity.inputsystem@1.20/manual/index.html`),176 including "About project-wide actions".177178## Related skills179180- `input-systems` — engine-agnostic input architecture (rebinding, buffering, multi-device).181- `unity-csharp-scripting` — the MonoBehaviour these handlers live in.182- `unity-physics` — applying the input vector to a Rigidbody.