# Controls and Input

本文档记录当前游戏层操作输入和开发调试快捷键。后续如果增加键位配置、手柄配置或 Switch 专用映射，以本文档作为唯一同步位置。

## 玩家操作

| 行为 | PC 键盘 | SDL 手柄 | Switch |
| --- | --- | --- | --- |
| 左右移动 | `A` / `D`，方向键左/右 | 左摇杆，方向键左/右 | 左摇杆，方向键左/右 |
| 跳跃 | `Space`，`W`，方向键上 | `A` / `B` | `A` / `B` |
| 攻击 | `J` / `K` | `X` / `Y` | `X` / `Y` |

当前 `InputState` 只暴露：

- `moveX`：水平输入，范围 `-1.0` 到 `1.0`。
- `jumpPressed`：跳跃按下瞬间，只在从未按到按下的那一帧为 true。
- `attackPressed`：攻击按下瞬间，只在从未按到按下的那一帧为 true。

## 调试快捷键

这些快捷键用于白盒/灰盒开发阶段，后续可以迁移到调试面板。

| 快捷键 | 功能 |
| --- | --- |
| `F1` | Debug overlay 总开关。 |
| `F2` | Debug 清当前 battle zone，占位模拟清场解锁。 |
| `F3` | 切换碰撞矩形和场景网格。 |
| `F4` | 切换玩家包围盒。 |
| `F5` | 切换 battle zone 触发框和 camera bounds。 |
| `F6` | 切换敌人出生点。 |

## 输入实现约束

- 角色逻辑只消费 `InputState`，不直接读取 SDL、Switch 或平台 API。
- `InputStateProvider` 负责聚合 PC 键盘、SDL GameController 和 Switch `PadState`。
- PC 和 Switch 的游戏逻辑必须共用同一套 `InputState` 语义。
- 动作输入当前按“按下瞬间”触发，避免按住跳跃/攻击每帧重复触发。
- 后续新增冲刺、防御、交互、菜单操作时，先扩展 `InputState`，再补平台映射。

## 后续计划

1. 增加 `InputConfig`，把默认键位/手柄映射迁移到可配置数据。
2. 区分 gameplay 输入和 debug 输入，避免正式版本保留开发快捷键。
3. 增加输入状态 debug 显示，用于排查手柄、Switch Joy-Con 和模拟器输入问题。