Document controls and input mapping

game/docs/controls.md

@@ -0,0 +1,44 @@
+# 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 和模拟器输入问题。