unity-input-correctness
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.
Nice-Wolf-Studio · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add Nice-Wolf-Studio/unity-claude-skills --skill 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 lifeti