unity-input-correctness

name	unity-input-correctness
description	Unity New Input System correctness patterns. Catches common mistakes with action reading (triggered vs IsPressed vs WasPressedThisFrame), action map switching, rebinding persistence, InputValue lifetime, PassThrough vs Value, local multiplayer device assignment, and control scheme auto-switching. PATTERN format: WHEN/WRONG/RIGHT/GOTCHA. Based on Unity 6.3 LTS.
globs	["**/*.cs","**/*.inputactions"]

Input System (New) -- Correctness Patterns

Prerequisite skills: unity-input (Input System API, actions, bindings, PlayerInput component)

These patterns target the most common Input System bugs: wrong reading method for the action type, mixing old/new APIs, losing rebindings, and mishandling multiplayer device assignment.

---

PATTERN: Reading Input -- triggered vs IsPressed vs WasPressedThisFrame

WHEN: Reading button/action state at runtime

WRONG (Claude default):

// Using .triggered for continuous input (only fires once per press)
if (fireAction.triggered)
    rb.AddForce(Vector3.forward * force); // Only fires one frame, not while held

// Using .IsPressed() for one-shot actions (fires every frame while held)
if (jumpAction.IsPressed())
    Jump(); // Jumps every frame the button is held!

RIGHT:

// One-shot actions (jump, interact, fire single bullet):
if (jumpAction.WasPressedThisFrame())  // True for exactly ONE frame
    Jump();

// Or use .triggered (same as WasPressedThisFrame for Button actions with default interaction)
if (jumpAction.triggered)
    Jump();

// Continuous actions (sprint, aim, hold to charge):
if (sprintAction.IsPressed())  // True every frame while held
    moveSpeed = sprintSpeed;

// Value reading (stick, mouse delta):
Vector2 moveInput = moveAction.ReadValue<Vector2>();  // Continuous value

GOTCHA: .triggered respects Interactions (Hold, Tap, etc.) -- it fires when the interaction completes. .WasPressedThisFrame() fires on raw press regardless of interactions. .IsPressed() returns true every frame while actuated above the press threshold. For Button type actions without interactions, .triggered == .WasPressedThisFrame(). For Value type actions, .triggered fires when the value changes from zero to non-zero.

---

PATTERN: Action Map Switching

WHEN: Switching between action maps (e.g., Gameplay -> UI -> Vehicle)

WRONG (Claude default):

// Forgetting that SwitchCurrentActionMap disables the previous map
playerInput.SwitchCurrentActionMap("UI");
// All "Gameplay" actions are now DISABLED -- callbacks won't fire
// If you cached Gameplay actions, they silently stop working

RIGHT:

// Option 1: Via PlayerInput (handles enable/disable automatically)
playerInput.SwitchCurrentActionMap("UI");
// Previous map disabled, new map enabled

// Option 2: Manual enable/disable (more control)
gameplayActions.Disable();
uiActions.Enable();

// Option 3: Keep both maps active simultaneously
// (useful for universal actions like Pause)
gameplayActions.Enable();
pauseActions.Enable(); // Both active at once

GOTCHA: When using PlayerInput.SwitchCurrentActionMap, the previous map is fully disabled. Any cached InputAction references from the previous map stop firing callbacks until re-enabled. If you need certain actions (like Pause) to work across all maps, put them in a separate map that stays enabled, or use the manual enable/disable approach.

---

PATTERN: Processor vs Interaction Confusion

WHEN: Applying deadzones or modifying input values

WRONG (Claude default):

// Adding a deadzone as an Interaction (Interactions modify TIMING, not values)
// In .inputactions: Action > Interactions > "Deadzone" -- this doesn't exist as an interaction

RIGHT:

// Deadzones are PROCESSORS -- they modify the input VALUE
// Set in .inputactions: Binding > Processors > "Stick Deadzone" or "Axis Deadzone"

// Processors modify the value stream: Raw Input -> Processor Chain -> Final Value
// Common processors:
//   StickDeadzone   -- applies radial deadzone to Vector2 (sticks)
//   AxisDeadzone    -- applies linear deadzone to float (triggers)
//   Normalize       -- normalizes Vector2 to 0-1 range
//   Invert          -- negates the value
//   Scale           -- multiplies by a factor
//   Clamp           -- clamps to min/max range

// Runtime processor override (if needed):
moveAction.ApplyBindingOverride(new InputBinding { overrideProcessors = "StickDeadzone(min=0.2,max=0.9)" });

GOTCHA: Processors transform the value (deadzone, normalize, scale, invert). Interactions change the timing of when started/performed/canceled fire (Press, Hold, Tap, SlowTap, MultiTap). Confusing them results in either no deadzone (processor missing) or wrong callback timing (interaction added where not needed).

---

PATTERN: InputValue Lifetime in SendMessages/BroadcastMessages

WHEN: Using PlayerInput in SendMessages or BroadcastMessages behavior mode

WRONG (Claude default):

private InputValue _cachedInput; // Storing the reference

void OnMove(InputValue value)
{
    _cachedInput = value; // WRONG: InputValue is pooled and recycled
}

void Update()
{
    Vector2 dir = _cachedInput.Get<Vector2>(); // May return stale or corrupt data
}

RIGHT:

private Vector2 _moveInput;

void OnMove(InputValue value)
{
    // Copy the value immediately -- InputValue is only valid during the callback
    _moveInput = value.Get<Vector2>();
}

void Update()
{
    transform.Translate(_moveInput * speed * Time.deltaTime);
}

GOTCHA: InputValue is a wrapper that is reused between callbacks. Its internal data is only valid during the callback invocation. Always copy with .Get<T>() in the callback and store the result. This applies to SendMessages and BroadcastMessages modes. UnityEvents and C# Events modes don't use InputValue -- they pass InputAction.CallbackContext which has the same lifetime constraint.

---

PATTERN: PassThrough vs Value for Multi-Source Input

WHEN: Handling input from multiple simultaneous sources (multi-touch, multiple gamepads)

WRONG (Claude default):

// Using "Value" action type for multi-touch
// Value type performs disambiguation -- picks the input with highest magnitude
// You only see ONE touch, even if multiple fingers are on screen

RIGHT:

// Use "PassThrough" action type for all-source input
// PassThrough does NOT disambiguate -- every input source triggers the action

// In .inputactions file: Set Action Type = "Pass Through"
// This is essential for:
//   - Multi-touch (each finger fires separately)
//   - Multiple gamepads sending the same action
//   - Combining keyboard + mouse simultaneously

// Read which device triggered it:
void OnAction(InputAction.CallbackContext ctx)
{
    var device = ctx.control.device;
    var value = ctx.ReadValue<float>();
}

GOTCHA: Button: fires on press/release, returns float 0 or 1. Value: fires when value changes, picks highest-magnitude source (disambiguation). PassThrough: fires on every change from every source, no disambiguation. For most gameplay input, Value is correct. Use PassThrough only when you need per-device or per-finger tracking.

---

PATTERN: Action Enable/Disable Scope

WHEN: Enabling/disabling individual actions vs entire action maps

WRONG (Claude default):

// Enabling an action without enabling its map
fireAction.Enable(); // Works, BUT...
// If the map was disabled, this implicitly enables JUST this action
// Other actions in the same map remain disabled

RIGHT:

// Preferred: Enable/disable at the MAP level
playerActions.Enable();  // Enables all actions in the map
playerActions.Disable(); // Disables all actions

// Individual action enable/disable (advanced use only):
fireAction.Enable();  // Enables this action even if map is disabled
fireAction.Disable(); // Disables only this action

// Check state:
bool mapEnabled = playerActions.enabled;
bool actionEnabled = fireAction.enabled;

GOTCHA: An action can be enabled while its containing map is "disabled" -- the action still works. But this creates confusing state: map.enabled returns false while action.enabled returns true. Best practice: always enable/disable at the map level. Only use per-action enable/disable for special cases like temporarily disabling fire while reloading.

---

PATTERN: Device-Specific Button Prompts

WHEN: Displaying control hints to the player (e.g., "Press X to interact")

WRONG (Claude default):

// Hardcoded button names
promptText.text = "Press A to Jump";
// Wrong on keyboard (should be "Space"), PS5 (should be "Cross"), etc.

RIGHT:

// Get the display name for the current binding
InputAction jumpAction = inputActions.FindAction("Jump");

// Get display string for the active control scheme
string displayName = jumpAction.GetBindingDisplayString(
    InputBinding.DisplayStringOptions.DontOmitDevice);
promptText.text = $"Press {displayName} to Jump";

// For a specific control scheme:
int bindingIndex = jumpAction.GetBindingIndex(
    InputBinding.MaskByGroup("Gamepad"));
if (bindingIndex >= 0)
{
    string gamepadPrompt = jumpAction.GetBindingDisplayString(bindingIndex);
    // Returns "Button South" or device-specific name
}

GOTCHA: GetBindingDisplayString() returns human-readable names. Without parameters, it returns the string for the first binding. Use binding masks or indices to target specific control schemes. For full icon support, you need a custom InputBindingComposite or asset that maps control paths to sprite/icon references -- Unity does not provide built-in icon mapping.

---

PATTERN: Local Multiplayer Device Assignment

WHEN: Supporting multiple players on the same machine with separate controllers

WRONG (Claude default):

// Both players reading from the same static device reference
Vector2 p1Move = Gamepad.current.leftStick.ReadValue();
Vector2 p2Move = Gamepad.current.leftStick.ReadValue(); // Same gamepad!

RIGHT:

// Use PlayerInputManager for automatic device assignment
// 1. Add PlayerInputManager component to a manager object
// 2. Set Join Behavior (e.g., JoinPlayersWhenButtonIsPressed)
// 3. Set Player Prefab (must have PlayerInput component)
// PlayerInputManager automatically assigns unique devices to each player

// In the player script:
public class PlayerController : MonoBehaviour
{
    private PlayerInput _playerInput;
    private InputAction _moveAction;

    void Awake()
    {
        _playerInput = GetComponent<PlayerInput>();
        _moveAction = _playerInput.actions["Move"];
    }

    void Update()
    {
        // Each PlayerInput instance reads from its ASSIGNED device only
        Vector2 move = _moveAction.ReadValue<Vector2>();
        transform.Translate(move * speed * Time.deltaTime);
    }
}

// Listen for join/leave events:
void OnEnable()
{
    PlayerInputManager.instance.onPlayerJoined += OnPlayerJoined;
    PlayerInputManager.instance.onPlayerLeft += OnPlayerLeft;
}

GOTCHA: Gamepad.current returns the most recently used gamepad -- NOT a specific player's gamepad. For multiplayer, always read input through the PlayerInput component which manages device assignment. PlayerInputManager.instance.maxPlayerCount limits players. Split-screen is handled via PlayerInput.camera assignment -- each player gets a camera with a different viewport rect.

---

PATTERN: Control Scheme Auto-Switching

WHEN: Players switch between keyboard and gamepad mid-game

WRONG (Claude default):

// Assuming the control scheme is fixed after startup
// UI shows keyboard prompts even after player picks up a gamepad

RIGHT:

public class ControlSchemeHandler : MonoBehaviour
{
    private PlayerInput _playerInput;

    void OnEnable()
    {
        _playerInput = GetComponent<PlayerInput>();
        _playerInput.controlsChangedEvent.AddListener(OnControlsChanged);
        // Initialize with current scheme
        UpdatePrompts(_playerInput.currentControlScheme);
    }

    void OnDisable()
    {
        _playerInput.controlsChangedEvent.RemoveListener(OnControlsChanged);
    }

    void OnControlsChanged(PlayerInput input)
    {
        UpdatePrompts(input.currentControlScheme);
    }

    void UpdatePrompts(string schemeName)
    {
        bool isGamepad = schemeName == "Gamepad";
        // Update UI prompts, button icons, etc.
        promptIcon.sprite = isGamepad ? gamepadSprite : keyboardSprite;
    }
}

GOTCHA: PlayerInput auto-switches control schemes when it detects input from a different device type. controlsChangedEvent fires on every switch. currentControlScheme returns the name string matching your .inputactions control scheme names. The switch happens on the next input event, not immediately on device connection. Test with both devices plugged in simultaneously.

---

Anti-Patterns Quick Reference

Anti-Pattern	Problem	Fix
Input.GetKey mixed with new Input System	Old and new API conflict; may require both backends active	Fully migrate to new Input System; remove using UnityEngine.Input
Not calling action.Enable()	Action does nothing; no errors	Enable action map or individual action before reading
Reading .ReadValue<T>() with wrong type T	Returns default value silently	Match T to action's Control Type (Vector2 for Stick, float for Button)
Forgetting to dispose PerformInteractiveRebinding	Memory leak	Always call .Dispose() after .Start() completes or is cancelled
Using legacy OnGUI for input	Mixes IMGUI with Input System	Use UI Toolkit or Input System callbacks
Not saving rebind overrides	Players lose custom bindings on restart	Save with SaveBindingOverridesAsJson, load in Awake

Related Skills

• unity-input -- Input System API reference, action types, binding syntax, device access
• unity-ui -- UI Toolkit input handling, navigation events
• unity-multiplayer -- Netcode input authority, client prediction

Additional Resources

• Input System Manual
• InputAction API
• PlayerInput API
• PlayerInputManager
• Interactive Rebinding