/unity-input-system

name: unity-input-system
description: >
  Wires Unity 6.3 LTS player input with the Input System package: .inputactions assets, action
  maps, PlayerInput and control schemes. Use when input does nothing or fires under a menu,
  FindAction returns null, the old Input class throws, or Input.GetAxis code needs porting. Not
  for engine-neutral buffering, remapping or deadzones (`input-systems`) or jump feel
  (`platformer`).

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 `PlayerInput`

component; reading a `Vector2` from a stick or WASD; one set of actions for gamepad, keyboard and touch; the Unity rebinding API.

• `Packages/manifest.json` lists `com.unity.inputsystem`, or the project has an

`*.inputactions` asset.

**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

1. **Read Active Input Handling from the file.** `ProjectSettings/ProjectSettings.asset` has `activeInputHandler: 0` (old Input Manager only), `1` (Input System only) or `2` (both). The package receives nothing at `0`, and any leftover `Input.GetAxis` call throws at `1`. Grep `Assets/` for `Input.Get` before choosing `1`; changing the value restarts the Editor, so tell the user. 2. **Reuse the project-wide actions.** New Unity 6 projects usually ship `Assets/InputSystem_Actions.inputactions`, assigned as project-wide actions, with a `Player` map (`Move`, `Look`, `Attack`, `Interact`, `Crouch`, `Jump`, `Previous`, `Next`, `Sprint`) and a `UI` map. Add to it rather than creating a second asset. 3. **Edit the asset as JSON when the Editor is closed.** An `.inputactions` file is JSON: `maps[].actions[]` (`name`, `type`, `expectedControlType`) and `maps[].bindings[]` (`path` such as `<Keyboard>/space`, `action`, `groups` for control schemes, `isComposite` and `isPartOfComposite` for WASD). Give each new action and binding a fresh `id` GUID like the existing entries, keep the file valid JSON, and re-read it after writing. 4. **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.

• **`PlayerInput` component** when the project already uses it, or for local co-op

(`PlayerInputManager` gives each joining device its own player).

• **An `InputActionReference` or a separate asset** when a tool or system needs its own

actions; you `Enable()` and `Disable()` them yourself. 5. **Switch action maps for context** (gameplay vs menu) instead of guarding every handler. 6. **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 `.inputactions` JSON and confirm every name your code passes

to `FindAction`/`FindActionMap` exists (for `"Player/Jump"`, a map `Player` with an action `Jump`), and that composites have all their parts. Confirm `activeInputHandler` matches the code.

• **Tests:** the package's `InputTestFixture` adds virtual devices and presses controls from

code. List `com.unity.inputsystem` under `"testables"` in `Packages/manifest.json` and add `Unity.InputSystem` and `Unity.InputSystem.TestFramework` to the test `.asmdef` (assembly setup is in `unity-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_key` injects a key

press (for example `Space`) through the Input System into