10-input-manager
暂无简介
- License 许可
- MIT
- 最近更新
- 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 모드 enumIInputManager— 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 DisableUI→ Gameplay ActionMap Disable, UI ActionMap Enable
6. Singleton 등록
CompoSingleton<InputManager>— 타입 등록은 baseAwake()에서 자동 수행, 초기화 코드는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일 때만 매 프레임:
- Move/Look ReadValue + buttons bitset 합산 →
InputFrame생성 _controllersDirty이면_controllers를Priority내림차순 정렬- 등록된
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