Quick Reference

• 기준은 Unity 6.5 (6000.5), Input System 1.14.2입니다. Action Asset은 전체 입력 정의, Action Map은 함께 켜고 끄는 상태 묶음, Action은 Move·Jump 같은 하나의 게임 행동입니다.
• Gameplay, UI, Vehicle처럼 동시 활성화 여부가 다른 행동을 map으로 나눕니다. map을 단순 폴더처럼 쓰지 말고 “이 상태에서 어떤 입력이 유효한가”를 기준으로 자릅니다.
• PlayerInput은 asset을 한 player와 device pairing, control scheme, notification 방식에 연결합니다. local multiplayer 또는 여러 PlayerInput에서는 원본 asset이 아니라 playerInput.actions가 가리키는 해당 player의 action instance를 사용합니다.

Game.inputactions
  Gameplay: Move (Value/Vector2), Jump (Button)
  UI: Navigate (Value/Vector2), Submit (Button)

PlayerInput
  Actions = Game.inputactions
  Default Action Map = Gameplay

Action Asset과 PlayerInput Inspector

• Input Action editor에서 Action Type은 보통 Button, Value, Pass Through입니다. Button은 press state와 WasPressedThisFrame에, Value는 ReadValue<Vector2>() 같은 대표 값 선택에, Pass Through는 각 control의 변화가 별도로 필요할 때 맞습니다. Move를 Button으로 만들면 Vector2를 읽는 쪽이 기대한 값을 받지 못합니다.
• Control Type은 action이 받는 값의 기대 형태입니다. Move에는 Vector2, Look에는 보통 Vector2, Jump에는 Button을 둡니다. binding path와 control type이 맞지 않으면 Inspector 경고 또는 0/default 값부터 확인합니다.
• Action Map은 명시적으로 Enable()/Disable()하거나 PlayerInput의 Default Action Map으로 첫 활성 map을 정합니다. Default Action Map을 비워 두면 PlayerInput이 자동으로 켤 map이 없습니다. 메뉴가 열렸는데 Gameplay map을 계속 켜 두면 이동과 UI 조작이 겹칩니다.
• PlayerInput의 Actions는 연결할 Input Action Asset입니다. local multiplayer에서 PlayerInput은 device를 player에 pair하고, 각 player가 독립된 action 상태를 유지하도록 action instance를 관리합니다. 공유 asset field를 직접 읽어 player 상태를 섞지 말고 playerInput.actions에서 찾습니다.
• Default Control Scheme은 enable 시 우선 시도할 scheme입니다. 비워 두면 호환되는 장치를 자동으로 찾고, 지정한 scheme의 필수 장치가 이미 다른 player에 pair되어 있으면 다른 scheme으로 fallback하거나 입력이 기대대로 붙지 않을 수 있습니다.
• Behavior / Notification Behavior는 Send Messages, Broadcast Messages, Invoke Unity Events, Invoke C# Events 중 하나입니다. Send Messages는 OnMove(InputValue) 같은 이름 기반 method를 호출하고, Unity Events는 Inspector listener를, C# Events는 onActionTriggered를 사용합니다. 하나를 정해 같은 player에서 혼용하지 않습니다.

스크립트 연결

using UnityEngine;
using UnityEngine.InputSystem;

public sealed class PlayerMovementInput : MonoBehaviour
{
    [SerializeField] private PlayerInput playerInput;

    private InputAction move;

    private void OnEnable()
    {
        move = playerInput.actions.FindAction("Gameplay/Move", throwIfNotFound: true);
        playerInput.onActionTriggered += OnActionTriggered;
    }

    private void OnDisable()
    {
        playerInput.onActionTriggered -= OnActionTriggered;
    }

    private void Update()
    {
        Vector2 direction = move.ReadValue<Vector2>();
        // direction을 movement controller에 전달합니다.
    }

    private void OnActionTriggered(InputAction.CallbackContext context)
    {
        if (context.action.name == "Jump" && context.performed)
        {
            // 한 번의 점프 입력을 buffer에 기록합니다.
        }
    }
}

• 이 예제는 PlayerInput Behavior를 Invoke C# Events로 둔 경우입니다. 다른 Behavior에서는 onActionTriggered를 구독해도 이벤트가 오지 않습니다. Inspector setting과 코드 경로를 한 쌍으로 바꾸세요.
• InputAction.ReadValue<T>()의 T는 Action의 Control Type과 맞아야 합니다. Vector2 action을 float로 읽거나 Button을 Vector2로 읽으면 오류 또는 default 값이 나옵니다.
• SwitchCurrentActionMap("UI")는 state 전환의 한 지점에만 둡니다. map을 직접 여러 곳에서 Enable()하면 PlayerInput이 어떤 map을 current로 보는지와 callback 범위가 흐려집니다. gameplay와 UI를 동시에 의도적으로 켜는 경우에는 두 동작이 같은 binding을 소비하지 않는지 검증합니다.
• DeactivateInput()은 현재 player 입력을 막을 때, ActivateInput()은 다시 받을 때 씁니다. pause popup에서 map을 바꿀지 전체 player 입력을 비활성화할지는 UI가 어떤 입력을 계속 받아야 하는지로 고릅니다.

자주 틀리는 부분