504 lines
17 KiB
Markdown
504 lines
17 KiB
Markdown
# 04 · 输入模块
|
||
|
||
> **命名空间** `BaseGames.Input`
|
||
> **程序集** `BaseGames.Input`
|
||
> **路径** `Assets/Scripts/Input/`
|
||
> **依赖** `BaseGames.Core.Events`、`Unity.InputSystem`
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [InputReaderSO](#1-inputreaderso)
|
||
2. [InputReaderSO 字段与事件完整列表](#2-inputreaderso-字段与事件完整列表)
|
||
3. [Input Actions 资产结构](#3-input-actions-资产结构)
|
||
4. [InputBuffer — 输入缓冲](#4-inputbuffer--输入缓冲)
|
||
5. [Action Map 切换规则](#5-action-map-切换规则)
|
||
6. [按键重绑定接口](#6-按键重绑定接口)
|
||
7. [Persistent 场景挂载](#7-persistent-场景挂载)
|
||
|
||
---
|
||
|
||
## 1. InputReaderSO
|
||
|
||
```
|
||
路径: Assets/Scripts/Input/InputReaderSO.cs
|
||
资产: Assets/Data/Player/PLY_InputReader.asset（全局单例 SO）
|
||
程序集: BaseGames.Input
|
||
```
|
||
|
||
`InputReaderSO` 是输入系统的**唯一门面**。内部持有生成的 `PlayerInputActions` C# 类，向外暴露纯 C# `event Action` 委托，各游戏系统通过订阅这些事件获取输入，**不直接持有 `PlayerInput` 组件引用**。
|
||
|
||
```csharp
|
||
[CreateAssetMenu(menuName = "Input/InputReader")]
|
||
public class InputReaderSO : ScriptableObject, IInputActionCollection2
|
||
{
|
||
// 内部持有生成的 Input Actions
|
||
private PlayerInputActions _actions;
|
||
|
||
// EventChannel 引用（SO→SO 注入，供无法直接订阅 C# 事件的全局系统使用）
|
||
[SerializeField] private VoidEventChannelSO _onPauseRequested; // → EVT_PauseRequested（GameManager 订阅）
|
||
|
||
// 在首次访问时懒初始化（OnEnable 兜底）
|
||
private void OnEnable() => _actions ??= new PlayerInputActions();
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 2. InputReaderSO 字段与事件完整列表
|
||
|
||
### 移动
|
||
|
||
```csharp
|
||
public event Action<Vector2> MoveEvent; // 持续：方向向量
|
||
public Vector2 MoveInput { get; } // 当前帧值（Polling 用）
|
||
```
|
||
|
||
### 跳跃
|
||
|
||
```csharp
|
||
public event Action JumpStartedEvent; // 按下（触发跳跃）
|
||
public event Action JumpCancelledEvent; // 松开（可变跳跃高度 CutJump）
|
||
```
|
||
|
||
### 攻击
|
||
|
||
```csharp
|
||
public event Action AttackEvent; // 普通攻击按下
|
||
public event Action DownAttackEvent; // 下劈（按住下+攻击，或独立键位）
|
||
public event Action UpAttackEvent; // 上劈（按住上+攻击，或独立键位）
|
||
```
|
||
|
||
### 弹反
|
||
|
||
```csharp
|
||
public event Action ParryEvent; // 弹反按下
|
||
```
|
||
|
||
### 冲刺
|
||
|
||
```csharp
|
||
public event Action DashEvent; // 冲刺按下
|
||
```
|
||
|
||
### 灵泉
|
||
|
||
```csharp
|
||
public event Action UseSpringEvent; // 使用灵泉（消耗 SpringCharges）
|
||
```
|
||
|
||
### 形态切换
|
||
|
||
```csharp
|
||
public event Action SwitchSkyFormEvent; // 天魂形态
|
||
public event Action SwitchEarthFormEvent; // 地魂形态
|
||
public event Action SwitchDeathFormEvent; // 命魂形态
|
||
```
|
||
|
||
### 技能
|
||
|
||
```csharp
|
||
public event Action SoulSkillEvent; // 当前形态魂技能（消耗灵力）
|
||
public event Action SpiritSkill1StartedEvent; // 魄技能 1 按下
|
||
public event Action SpiritSkill1CancelledEvent; // 魄技能 1 松开（蓄力型）
|
||
public event Action SpiritSkill2StartedEvent; // 魄技能 2 按下
|
||
public event Action SpiritSkill2CancelledEvent; // 魄技能 2 松开（蓄力型）
|
||
```
|
||
|
||
### 交互
|
||
|
||
```csharp
|
||
public event Action InteractEvent; // 与 NPC/物件交互
|
||
```
|
||
|
||
### UI
|
||
|
||
```csharp
|
||
public event Action PauseEvent; // 暂停键：同时 Raise _onPauseRequested（→ EVT_PauseRequested）
|
||
public event Action<Vector2> NavigateEvent; // UI 导航
|
||
public event Action SubmitEvent; // 确认
|
||
public event Action CancelEvent; // 取消
|
||
public event Action<Vector2> PointEvent; // 鼠标/触摸位置（UI Action Map Point）
|
||
```
|
||
|
||
### Action Map 切换
|
||
|
||
```csharp
|
||
public void EnableGameplayInput(); // 启用 Gameplay Map，禁用 UI Map
|
||
public void EnableUIInput(); // 启用 UI Map，禁用 Gameplay Map
|
||
public void DisableAllInput(); // 全部禁用（过场/加载中）
|
||
```
|
||
|
||
---
|
||
|
||
## 3. Input Actions 资产结构
|
||
|
||
```
|
||
资产路径: Assets/Settings/PlayerInputActions.inputactions
|
||
```
|
||
|
||
### Gameplay Action Map
|
||
|
||
| Action 名 | 类型 | 绑定（键盘/手柄） |
|
||
|-----------|------|----------------|
|
||
| `Move` | Value Vector2 | WASD / 左摇杆 |
|
||
| `Jump` | Button | Space / 南键（×/A） |
|
||
| `Attack` | Button | J / 西键（□/X） |
|
||
| `Parry` | Button | K / 北键（△/Y） |
|
||
| `Dash` | Button | L / 东键（○/B） |
|
||
| `UseSpring` | Button | H / R1 |
|
||
| `SwitchSkyForm` | Button | 1 / D-Pad Up |
|
||
| `SwitchEarthForm` | Button | 2 / D-Pad Down |
|
||
| `SwitchDeathForm` | Button | 3 / D-Pad Right |
|
||
| `SoulSkill` | Button | U / L2 |
|
||
| `SpiritSkill1` | Button | I / R2（带 hold 取消事件）|
|
||
| `SpiritSkill2` | Button | O / L1（带 hold 取消事件）|
|
||
| `Interact` | Button | F / D-Pad Left |
|
||
| `Pause` | Button | Esc / Start |
|
||
|
||
### UI Action Map
|
||
|
||
| Action 名 | Value 类型 | 绑定 |
|
||
|-----------|-----------|------|
|
||
| `Navigate` | Vector2 | 方向键 / 左摇杆 |
|
||
| `Submit` | Button | Enter / 南键 |
|
||
| `Cancel` | Button | Esc / 东键 |
|
||
| `Pause` | Button | Esc / Start |
|
||
| `Point` | Value (Vector2) | 鼠标/触摸位置（UI 点击坐标） |
|
||
|
||
---
|
||
|
||
## 4. InputBuffer — 输入缓冲
|
||
|
||
`InputBuffer` 是挂在 `PlayerController` 同一 GameObject 上的组件，不独立存在。
|
||
|
||
```csharp
|
||
// 路径: Assets/Scripts/Input/InputBuffer.cs
|
||
public class InputBuffer : MonoBehaviour
|
||
{
|
||
// 各动作独立缓冲时长（与 Design/01 §4 缓冲时长配置表一致）
|
||
[SerializeField] private float _jumpBufferDuration = 0.15f; // 跳跃：宽容窗口
|
||
[SerializeField] private float _attackBufferDuration = 0.12f; // 攻击：接续连段
|
||
[SerializeField] private float _dashBufferDuration = 0.10f; // 冲刺：小量容错
|
||
// 弹反 / UseSpring / SoulSkill / SpiritSkill 缓冲时长为 0s（不缓冲）
|
||
[SerializeField] private InputReaderSO _inputReader;
|
||
|
||
// 各动作的缓冲计时器
|
||
private float _jumpBuffer;
|
||
private float _attackBuffer;
|
||
private float _dashBuffer;
|
||
|
||
private void Update()
|
||
{
|
||
// 每帧倒计时
|
||
_jumpBuffer = Mathf.Max(0, _jumpBuffer - Time.deltaTime);
|
||
_attackBuffer = Mathf.Max(0, _attackBuffer - Time.deltaTime);
|
||
_dashBuffer = Mathf.Max(0, _dashBuffer - Time.deltaTime);
|
||
}
|
||
|
||
// 检测（各 State 在 OnStateEnter 调用）
|
||
public bool ConsumeJump() { if (_jumpBuffer > 0) { _jumpBuffer = 0; return true; } return false; }
|
||
public bool ConsumeAttack() { if (_attackBuffer > 0) { _attackBuffer = 0; return true; } return false; }
|
||
public bool ConsumeDash() { if (_dashBuffer > 0) { _dashBuffer = 0; return true; } return false; }
|
||
|
||
// 写入（订阅 InputReaderSO 事件）
|
||
private void OnEnable()
|
||
{
|
||
_inputReader.JumpStartedEvent += () => _jumpBuffer = _jumpBufferDuration;
|
||
_inputReader.AttackEvent += () => _attackBuffer = _attackBufferDuration;
|
||
_inputReader.DashEvent += () => _dashBuffer = _dashBufferDuration;
|
||
}
|
||
|
||
private void OnDisable()
|
||
{
|
||
_inputReader.JumpStartedEvent -= () => _jumpBuffer = _jumpBufferDuration;
|
||
_inputReader.AttackEvent -= () => _attackBuffer = _attackBufferDuration;
|
||
_inputReader.DashEvent -= () => _dashBuffer = _dashBufferDuration;
|
||
}
|
||
}
|
||
```
|
||
|
||
**Coyote Time** 实现位于 `PlayerMovement`（不在此模块），见[05_PlayerModule.md](./05_PlayerModule.md)。
|
||
|
||
---
|
||
|
||
## 5. Action Map 切换规则
|
||
|
||
| 游戏状态（GameState） | 输入 Map | 调用方 |
|
||
|----------------------|---------|--------|
|
||
| `Initializing` / `LoadingScene` | `DisableAllInput()` | `GameManager`（订阅 EVT_GameStateChanged） |
|
||
| `MainMenu` | `EnableUIInput()` | `GameManager` |
|
||
| `Gameplay` / `BossFight` | `EnableGameplayInput()` | `GameManager` |
|
||
| `Paused` | `EnableUIInput()` | `GameManager` |
|
||
| `Dead` | `DisableAllInput()`，然后 DeathScreen 出现后 `EnableUIInput()` | `GameManager` |
|
||
| `Cutscene` | `DisableAllInput()` | `GameManager` / `CutsceneManager` |
|
||
| 对话（Dialogue）中 | `EnableUIInput()` | `DialogueManager`（对话开始/结束时调用）|
|
||
|
||
---
|
||
|
||
## 6. 按键重绑定接口
|
||
|
||
```csharp
|
||
// InputReaderSO 提供的重绑定 API（供 SettingsPanel 调用）
|
||
public class InputReaderSO : ScriptableObject
|
||
{
|
||
// 开始交互式重绑定（返回 RebindOperation，调用方负责 Dispose）
|
||
public InputActionRebindingExtensions.RebindingOperation
|
||
StartRebinding(string actionName, int bindingIndex, Action onComplete, Action onCancel);
|
||
|
||
// 保存当前绑定覆盖（JSON）→ PlayerPrefs
|
||
public void SaveBindingOverrides();
|
||
|
||
// 从 PlayerPrefs 加载并应用绑定覆盖
|
||
public void LoadBindingOverrides();
|
||
|
||
// 重置为默认绑定
|
||
public void ResetBindings();
|
||
}
|
||
```
|
||
|
||
### RebindPanel — 完整重绑定 UI
|
||
|
||
```csharp
|
||
// 路径: Assets/Scripts/UI/Settings/RebindPanel.cs
|
||
// 设置界面中的完整按键重绑定面板
|
||
// 每个可绑定 Action 对应一行 RebindActionRow
|
||
public class RebindPanel : MonoBehaviour
|
||
{
|
||
[SerializeField] private InputReaderSO _inputReader;
|
||
[SerializeField] private RebindActionRow[] _rows; // Inspector 配置，顺序对应 HUD 布局
|
||
[SerializeField] private Button _resetAllButton;
|
||
[SerializeField] private ConflictDetector _conflictDetector;
|
||
|
||
private void Awake()
|
||
{
|
||
_resetAllButton.onClick.AddListener(OnResetAll);
|
||
foreach (var row in _rows)
|
||
row.Initialize(_inputReader, _conflictDetector, OnRebindRequested);
|
||
}
|
||
|
||
private void OnRebindRequested(RebindActionRow row)
|
||
{
|
||
// 禁用其他行的交互，防止同时启动多个重绑定操作
|
||
foreach (var r in _rows) r.SetInteractable(r == row);
|
||
row.StartRebind(onFinished: () =>
|
||
{
|
||
foreach (var r in _rows) r.SetInteractable(true);
|
||
_inputReader.SaveBindingOverrides();
|
||
});
|
||
}
|
||
|
||
private void OnResetAll()
|
||
{
|
||
_inputReader.ResetBindings();
|
||
_inputReader.SaveBindingOverrides();
|
||
foreach (var row in _rows) row.RefreshDisplay();
|
||
}
|
||
}
|
||
|
||
// 路径: Assets/Scripts/UI/Settings/RebindActionRow.cs
|
||
// 单行：Action 名 + 当前绑定显示 + 点击启动重绑定
|
||
public class RebindActionRow : MonoBehaviour
|
||
{
|
||
[SerializeField] private string _actionName; // Input Action 名称
|
||
[SerializeField] private int _bindingIndex; // 0 = 主绑定，1 = 副绑定
|
||
[SerializeField] private TMP_Text _actionLabel;
|
||
[SerializeField] private Button _bindButton;
|
||
[SerializeField] private TMP_Text _currentBindingText;
|
||
|
||
private InputReaderSO _inputReader;
|
||
private ConflictDetector _conflictDetector;
|
||
private Action<RebindActionRow> _onRebindRequested;
|
||
|
||
public void Initialize(
|
||
InputReaderSO reader,
|
||
ConflictDetector detector,
|
||
Action<RebindActionRow> onRequest)
|
||
{
|
||
_inputReader = reader;
|
||
_conflictDetector = detector;
|
||
_onRebindRequested = onRequest;
|
||
_bindButton.onClick.AddListener(() => _onRebindRequested?.Invoke(this));
|
||
RefreshDisplay();
|
||
}
|
||
|
||
public void StartRebind(Action onFinished)
|
||
{
|
||
_currentBindingText.text = "按下新按键…";
|
||
_inputReader.StartRebinding(_actionName, _bindingIndex,
|
||
onComplete: () => { RefreshDisplay(); CheckConflicts(); onFinished?.Invoke(); },
|
||
onCancel: () => { RefreshDisplay(); onFinished?.Invoke(); });
|
||
}
|
||
|
||
public void RefreshDisplay()
|
||
{
|
||
var action = _inputReader.FindAction(_actionName);
|
||
_currentBindingText.text = action != null
|
||
? InputControlPath.ToHumanReadableString(
|
||
action.bindings[_bindingIndex].effectivePath,
|
||
InputControlPath.HumanReadableStringOptions.OmitDevice)
|
||
: "—";
|
||
}
|
||
|
||
public void SetInteractable(bool interactable) => _bindButton.interactable = interactable;
|
||
|
||
private void CheckConflicts()
|
||
{
|
||
var conflicts = _conflictDetector.FindConflicts(_inputReader.GetAllActionMap());
|
||
// 高亮冲突行（通过 ConflictDetector 回调）
|
||
foreach (var row in FindObjectsOfType<RebindActionRow>())
|
||
row.SetConflictHighlight(conflicts.Contains(row._actionName));
|
||
}
|
||
|
||
public void SetConflictHighlight(bool conflict)
|
||
=> _currentBindingText.color = conflict ? Color.red : Color.white;
|
||
}
|
||
```
|
||
|
||
### ConflictDetector — 冲突检测
|
||
|
||
```csharp
|
||
// 路径: Assets/Scripts/Input/ConflictDetector.cs
|
||
// 检测两个 Action 是否绑定了相同的按键路径
|
||
public class ConflictDetector : MonoBehaviour
|
||
{
|
||
// 返回存在冲突的 Action 名称集合
|
||
public HashSet<string> FindConflicts(IEnumerable<InputAction> actions)
|
||
{
|
||
var pathToActions = new Dictionary<string, List<string>>();
|
||
|
||
foreach (var action in actions)
|
||
{
|
||
foreach (var binding in action.bindings)
|
||
{
|
||
if (binding.isComposite || string.IsNullOrEmpty(binding.effectivePath)) continue;
|
||
|
||
if (!pathToActions.ContainsKey(binding.effectivePath))
|
||
pathToActions[binding.effectivePath] = new List<string>();
|
||
pathToActions[binding.effectivePath].Add(action.name);
|
||
}
|
||
}
|
||
|
||
var conflicted = new HashSet<string>();
|
||
foreach (var kv in pathToActions)
|
||
if (kv.Value.Count > 1)
|
||
foreach (var name in kv.Value)
|
||
conflicted.Add(name);
|
||
|
||
return conflicted;
|
||
}
|
||
}
|
||
```
|
||
|
||
### RebindPersistence — 持久化绑定
|
||
|
||
```csharp
|
||
// InputReaderSO 内部的持久化实现（扩展上方 SaveBindingOverrides/LoadBindingOverrides）
|
||
// 序列化格式: PlayerPrefs key = "InputBindings", value = JSON 覆盖字符串
|
||
|
||
public partial class InputReaderSO : ScriptableObject
|
||
{
|
||
private const string PrefKey = "InputBindings";
|
||
|
||
public void SaveBindingOverrides()
|
||
{
|
||
string json = _actions.asset.SaveBindingOverridesAsJson();
|
||
PlayerPrefs.SetString(PrefKey, json);
|
||
PlayerPrefs.Save();
|
||
}
|
||
|
||
public void LoadBindingOverrides()
|
||
{
|
||
if (PlayerPrefs.HasKey(PrefKey))
|
||
{
|
||
string json = PlayerPrefs.GetString(PrefKey);
|
||
_actions.asset.LoadBindingOverridesFromJson(json);
|
||
}
|
||
}
|
||
|
||
public void ResetBindings()
|
||
{
|
||
_actions.asset.RemoveAllBindingOverrides();
|
||
PlayerPrefs.DeleteKey(PrefKey);
|
||
}
|
||
|
||
// 辅助：获取当前 Gameplay map 所有 InputAction（供 ConflictDetector 使用）
|
||
public IEnumerable<InputAction> GetAllActionMap()
|
||
=> _actions.asset.FindActionMap("Gameplay").actions;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 7. Persistent 场景挂载
|
||
|
||
`InputReaderSO` 本身是 ScriptableObject（Asset），不需要 GameObject 挂载。
|
||
但 Unity InputSystem 的 `PlayerInput` 组件可选（InputReaderSO 直接 `new PlayerInputActions()` 即可，无需 `PlayerInput` 组件）。
|
||
|
||
```
|
||
Scene: Persistent
|
||
└── InputReader (GameObject)
|
||
└── InputReaderInitializer.cs
|
||
├── [SerializeField] InputReaderSO _inputReader
|
||
└── Awake():
|
||
_inputReader.Initialize(); // 创建 PlayerInputActions 实例
|
||
_inputReader.LoadBindingOverrides(); // 加载用户重映射
|
||
_inputReader.EnableGameplayInput(); // 默认游戏play输入
|
||
```
|
||
|
||
---
|
||
|
||
## 8. KeyDisplayNameResolver — 按键名本地化
|
||
|
||
`KeyDisplayNameResolver` 将 InputSystem 返回的英文按键路径名转换为本地化显示字符串，供 `RebindActionRow` 渲染到 UI。
|
||
|
||
```csharp
|
||
// 路径: Assets/Scripts/Input/KeyDisplayNameResolver.cs
|
||
public static class KeyDisplayNameResolver
|
||
{
|
||
// 中文覆盖字典（键 = InputControlPath 的 Human-Readable 片段，值 = 中文显示名）
|
||
private static readonly Dictionary<string, string> _overrides = new Dictionary<string, string>
|
||
{
|
||
{ "Space", "空格" },
|
||
{ "Enter", "回车" },
|
||
{ "Backspace", "退格" },
|
||
{ "Escape", "退出" },
|
||
{ "Left Arrow","←" },
|
||
{ "Right Arrow","→" },
|
||
{ "Up Arrow", "↑" },
|
||
{ "Down Arrow","↓" },
|
||
{ "Left Shift","左 Shift" },
|
||
{ "Right Shift","右 Shift" },
|
||
{ "Left Ctrl", "左 Ctrl" },
|
||
{ "Right Ctrl","右 Ctrl" },
|
||
{ "Left Alt", "左 Alt" },
|
||
{ "Right Alt", "右 Alt" },
|
||
{ "Tab", "Tab" },
|
||
{ "Caps Lock", "大写锁定" },
|
||
};
|
||
|
||
/// <summary>
|
||
/// 将 effectivePath 转换为本地化显示字符串。
|
||
/// 中文覆盖优先；未找到覆盖时回落到 InputControlPath.ToHumanReadableString。
|
||
/// </summary>
|
||
public static string Resolve(string effectivePath)
|
||
{
|
||
if (string.IsNullOrEmpty(effectivePath)) return "—";
|
||
|
||
string human = InputControlPath.ToHumanReadableString(
|
||
effectivePath,
|
||
InputControlPath.HumanReadableStringOptions.OmitDevice);
|
||
|
||
return _overrides.TryGetValue(human, out string localized) ? localized : human;
|
||
}
|
||
}
|
||
```
|
||
|
||
`RebindActionRow.RefreshDisplay()` 改为调用 `KeyDisplayNameResolver.Resolve()` 替代直接的 `ToHumanReadableString`：
|
||
|
||
```csharp
|
||
_currentBindingText.text = KeyDisplayNameResolver.Resolve(
|
||
action.bindings[_bindingIndex].effectivePath);
|
||
```
|