AGENT SKILL

10-input-manager

暂无简介

License 许可
MIT
所属仓库
devwinsoft/devian
最近更新
2026-04-12
Stars
★ 0
Forks
0

03 SKILL.md 正文

10-input-manager

Status: ACTIVE AppliesTo: v11 Type: Component Specification

목적

InputManager는 InputActionAsset 기반 입력 수집/정규화/발행 시스템이다.

  • Unity InputSystem의 InputActionAsset을 직접 참조
  • Move/Look은 Vector2로, 버튼은 ulong bitset으로 정규화
  • 매 프레임 등록된 BaseInputController를 Priority 순으로 직접 호출
  • Game / UI 컨텍스트 전환 지원

범위

포함

  • InputManager — CompoSingleton, consumer bootstrap/prefab이 부착하는 입력 관리자
  • InputFrame — 한 프레임의 정규화된 입력 스냅샷 (readonly struct)
  • InputContext — Game / UI 모드 enum
  • IInputManager — InputManager 계약
  • InputButtonMapBuilder — key("Map/Action") → button index 맵 빌드 유틸

제외

  • 오브젝트 부착형 입력 소비 (→ 11-input-controller)
  • InputSpace 전략 (→ 11-input-controller)
  • InputAction 바인딩/리매핑 UI

네임스페이스

namespace Devian

핵심 규약 (Hard Rule)

1. InputSettings 분리

설정 데이터는 InputSettings ScriptableObject로 분리되었다 (→ 12-input-settings). InputManager는 Resources.Load<InputSettings>(InputSettings.ResourcesPath)로 고정 경로에서 로드한다.

InputManager에 남은 SerializedField:

필드 기본값 용도
_outputEnabled true 인스턴스별 런타임 dispatch on/off

InputSettings에 이전된 필드 (기본값):

필드 기본값
_gameplayMapName "Player"
_uiMapName "UI"
_moveKey "Player/Move"
_lookKey "Player/Look"

2. ButtonMap key 포맷

버튼 키는 "Map/Action" 형식이다. 예: "Player/Attack", "Player/Jump".

3. ButtonMap 정렬 및 인덱스

InputButtonMapBuilder.Build()는 expectedKeys를 Ordinal sort 후 0..63 인덱스를 부여한다.

4. 64 버튼 제한

ulong bitset이므로 최대 64개 버튼. 초과 시 InvalidOperationException.

InputFrame.IsDown(int)은 0..63만 유효하며, 범위 밖은 false.

5. Context 전환

SetContext(InputContext) 호출 시:

  • Game → Gameplay ActionMap Enable, UI ActionMap Disable
  • UI → Gameplay ActionMap Disable, UI ActionMap Enable

6. Singleton 등록

  • CompoSingleton<InputManager> — 타입 등록은 base Awake()에서 자동 수행, 초기화 코드는 onInitAwake()에서 처리
  • IInputManager는 OnEnable에서 Singleton.Register<IInputManager> (Compo), OnDisable에서 Unregister
  • BaseApplication은 InputManager를 자동 추가하지 않는다.
  • 입력을 사용하는 소비자 bootstrap/prefab이 InputManager를 미리 부착한다.
  • 런타임 AddComponent<InputManager>()는 패턴 위반이다.

7. Uninitialized Axis Policy

_moveKey/_lookKey가 비어 있거나 해당 Action을 찾지 못하면(_moveAction/_lookAction == null), 해당 축은 "초기화 안 됨"으로 간주하여 NaN을 InputFrame에 담는다. BaseInputController는 NaN 축에 대해 콜백을 발생시키지 않는다.

8. Controller Registry Dispatch

outputEnabled == true일 때만 매 프레임:

  1. Move/Look ReadValue + buttons bitset 합산 → InputFrame 생성
  2. _controllersDirty이면 _controllers를 Priority 내림차순 정렬
  3. 등록된 BaseInputController.__Consume(frame)을 순서대로 호출
  • RegisterController(BaseInputController) / UnregisterController(BaseInputController) — 컨트롤러 등록/해제
  • Bus(IInputBus/InputBus)는 삭제됨 — 직접 호출 방식으로 대체

API 시그니처

// --- InputContext ---
public enum InputContext : byte { Game = 0, UI = 1 }

// --- InputFrame ---
public readonly struct InputFrame
{
    public readonly Vector2 Move;
    public readonly Vector2 Look;
    public readonly ulong ButtonBits;
    public readonly InputContext Context;
    public readonly float Timestamp;

    public InputFrame(Vector2 move, Vector2 look, ulong buttonBits, InputContext context, float timestamp);
    public bool IsDown(int buttonIndex);
}

// --- IInputManager ---
public interface IInputManager
{
    InputActionAsset Asset { get; }
    InputContext Context { get; }
    int GetButtonIndex(string key);
    IReadOnlyList<string> ButtonKeys { get; }
    void SetContext(InputContext context);
}

// --- InputManager ---
public sealed class InputManager : CompoSingleton<InputManager>, IInputManager
{
    public void RegisterController(BaseInputController controller);
    public void UnregisterController(BaseInputController controller);
}

// --- InputButtonMapBuilder ---
public static class InputButtonMapBuilder
{
    public static Dictionary<string, int> Build(InputActionAsset asset, string[] expectedKeys);
    public static InputAction TryFindActionByKey(InputActionAsset asset, string key);
}

Editor 기능

InputManagerInspector는 DrawDefaultInspector()만 제공한다 (_settings, _outputEnabled 표시).

내부 버튼 맵 재빌드는 OnEnable() 초기화 시 자동 수행된다.

Refresh Expected Button Keys, Install/Ensure VirtualGamepad Bindings 버튼은 InputSettingsInspector에서 제공한다 (→ 12-input-settings).

Editor 파일: com.devian.foundation/Samples~/MobilePackage/Editor/Input/InputManagerInspector.cs


파일 경로

타입 경로
InputContext com.devian.foundation/Samples~/MobilePackage/Runtime/Input/InputContext.cs
InputFrame com.devian.foundation/Samples~/MobilePackage/Runtime/Input/InputFrame.cs
IInputManager com.devian.foundation/Samples~/MobilePackage/Runtime/Input/IInputManager.cs
InputButtonMapBuilder com.devian.foundation/Samples~/MobilePackage/Runtime/Input/InputButtonMapBuilder.cs
InputSettings com.devian.foundation/Samples~/MobilePackage/Runtime/Input/InputSettings.cs
InputManager com.devian.foundation/Samples~/MobilePackage/Runtime/Input/InputManager.cs
InputManagerInspector com.devian.foundation/Samples~/MobilePackage/Editor/Input/InputManagerInspector.cs
InputSettingsInspector com.devian.foundation/Samples~/MobilePackage/Editor/Input/InputSettingsInspector.cs

DoD (Definition of Done)

  • [ ] 모든 파일이 namespace Devian 사용
  • [ ] Devian.Unity.asmdef에 Unity.InputSystem 참조 포함
  • [ ] UPM ↔ UnityExample 동일
  • [ ] ButtonMap key 64개 이하 검증
  • [ ] InputSettings ScriptableObject 분리 (→ 12-input-settings)
  • [ ] InputManager는 Resources.Load<InputSettings>(InputSettings.ResourcesPath)로 설정 접근
  • [ ] InputSettings 기본값: "Player", "Player/Move", "Player/Look"
  • [ ] InputSettingsInspector: Refresh / VirtualGamepad 버튼 동작 (→ 12-input-settings)
  • [ ] Devian.Unity.Editor.asmdef에 Unity.InputSystem 참조 포함
  • [ ] InputManager: CompoSingleton + onInitAwake() 훅 사용
  • [ ] 입력을 사용하는 consumer bootstrap/prefab이 InputManager를 미리 부착
  • [ ] IInputBus / InputBus 파일 삭제됨
  • [ ] Update에서 Controller registry dispatch (Priority 순 직접 호출)

Reference

  • Parent: ../00-overview/SKILL.md
  • 입력 설정: ../12-input-settings/SKILL.md
  • 입력 소비: ../11-input-controller/SKILL.md

04 同仓库更多 Skills