Document controls and input mapping

game/docs/README.md

@@ -7,6 +7,10 @@
 - `planning/game_architecture_board.md`：游戏整体架构白板，包含思维导图、模块划分、数据流和阶段路线。
 - `planning/scene_build_plan.md`：第一关场景搭建计划，包含素材清单、场景分层和验收标准。
 
+## References
+
+- `controls.md`：玩家操作、平台输入映射和开发调试快捷键。
+
 ## Naming
 
 - 文件名使用小写 `snake_case`。

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 和模拟器输入问题。

game/docs/planning/game_architecture_board.md

@@ -155,9 +155,9 @@ mindmap
 
 当前输入映射：
 
-- 移动：键盘 `A/D`、方向键、手柄左摇杆、方向键、Switch 左摇杆/方向键。
+- 详见 `../controls.md`。
-- 跳跃：键盘 `Space/W/Up`、手柄 `A/B`、Switch `A/B`。
+- 当前已覆盖 PC 键盘、SDL GameController 和 Switch `PadState`。
-- 攻击：键盘 `J/K`、手柄 `X/Y`、Switch `X/Y`。
+- 角色逻辑只消费 `InputState`，不直接读取平台输入 API。
 
 下一步：
 
@@ -178,7 +178,7 @@ mindmap
 
 - `scene/whitebox_scene.*`
 - `scene/camera_controller.*`：玩家跟随、dead zone、平滑和世界边界 clamp。
-- `CameraZoneLock`：玩家进入 battle zone 后摄像机平滑切换到 zone camera bounds，可移动锁定范围会防御性保证不小于视口，当前用 `F2` 或离开 zone 做 debug 清场解锁。
+- `CameraZoneLock`：玩家进入 battle zone 后摄像机平滑切换到 zone camera bounds，可移动锁定范围会防御性保证不小于视口，当前通过 debug 清场或离开 zone 解锁。
 
 下一步：
 
@@ -355,8 +355,7 @@ mindmap
 下一步：
 
 - `debug/debug_overlay.*` 已经提供碰撞、玩家包围盒、battle zone、camera lock 和 spawn point 绘制。
-- `F1` 切换 debug overlay 总开关。
+- Debug overlay 已支持总开关和分项开关，具体快捷键记录在 `../controls.md`。
-- `F3-F6` 分别切换碰撞/网格、玩家框、battle zone/camera、spawn point。
 - 绘制 hitbox / hurtbox。
 - 输出当前场景、角色状态、FPS。
 - 增加日志分级和异常状态重置入口。
@@ -587,7 +586,7 @@ mindmap
 1. 已完成：`StageLayerSource` 让 `StageLayer` 同时支持色块占位和 sprite 资源路径。
 2. 已完成：`StageAssetSlots` 建立 `stage_01` 资源槽位和素材来源记录，做到素材可直接落位。
 3. 已完成：`StageProps` 把后景/前景 props 统一到 layer 数据。
-4. `BattleZone`：把 `F2` debug 清场替换为敌人清空自动解锁。
+4. `BattleZone`：把 debug 清场替换为敌人清空自动解锁。
 5. `EnemyActor`：做第一个敌人占位，接入出生点。
 6. `CombatSystem`：把 hitbox/hurtbox 真正跑起来。
 7. `SpriteAnimator`：把玩家动画从硬编码改成组件。

game/docs/planning/scene_build_plan.md

@@ -20,15 +20,15 @@
 - 第一关灰盒宽度已扩展到 3200 像素。
 - `StageRenderer` 已支持远景、中景、地面/平台、后景 props 分层绘制，当前先用色块占位。
 - `DebugOverlay` 已能显示碰撞、玩家框、battle zone、camera lock 范围和 spawn point。
-- `WhiteboxScene` 已支持 `F1` 切换 debug overlay。
+- `WhiteboxScene` 已支持 debug overlay，具体快捷键记录在 `../controls.md`。
 - `CameraController` 已接入：修复场景 `OnUpdate()` 不被调用导致摄像机不动的问题，并提供跟随、dead zone、平滑和世界边界 clamp。
-- `CameraZoneLock` 已接入：玩家进入 battle zone 后摄像机临时锁定到 zone camera bounds，`F2` 临时清场并恢复全关卡跟随。
+- `CameraZoneLock` 已接入：玩家进入 battle zone 后摄像机临时锁定到 zone camera bounds，debug 清场后恢复全关卡跟随。
 - 已修复 zone camera bounds 小于 1280 视口导致摄像机锁死的问题；所有锁镜头范围必须不小于当前视口，debug 阶段玩家离开 zone 会自动清场解锁。
 - 已修复进入 battle zone 时摄像机硬切的问题；zone camera bounds 表示摄像机可移动范围，进入/离开 zone 都通过短过渡平滑切换约束。
 - `StageLayerSource` 已接入：`StageRect` 支持色块占位或 sprite 资源路径，资源不存在时回退色块。
 - `StageAssetSlots` 已建立：`game/assets/stage/stage_01/` 已预留 background、tiles、props、effects、audio 目录和素材来源记录。
 - `StageProps` 已统一：旧 `WhiteboxProp` 已移除，后景/前景 props 都走 `StageLayer`，其中 `props_front` 在角色之后绘制用于遮挡。
-- `SceneDebug` 已扩展：`F1` 控制 debug 总开关，`F3-F6` 分别切换碰撞/网格、玩家框、battle zone/camera、spawn point。
+- `SceneDebug` 已扩展：支持 debug 总开关和碰撞/网格、玩家框、battle zone/camera、spawn point 分项开关，具体快捷键记录在 `../controls.md`。
 
 ## 2. 第一关场景目标
 
@@ -188,7 +188,7 @@ game/assets/stage/stage_01/
 - 敌人出生点。
 - battle zone。
 
-建议先用键盘 `F1` 切换。
+具体 debug 快捷键统一记录在 `../controls.md`。
 
 ## 7. 第一版验收标准
 
@@ -226,7 +226,7 @@ game/assets/stage/stage_01/
 3. 已完成：扩展白盒关卡宽度到 3200 像素，并整理成 3 段推进节奏。
 4. 已完成：加入 3 个 battle zone debug 标记，但暂不做锁镜头和刷敌逻辑。
 5. 已完成：加入 spawn point debug 标记，用于后续接 `EnemyActor`。
-6. 已完成：补 `F1` debug 开关，可切换碰撞、battle zone、spawn point。
+6. 已完成：补 debug 开关，可切换碰撞、battle zone、spawn point。
 
 ### 素材回来后再替换
 
@@ -257,21 +257,16 @@ game/assets/stage/stage_01/
 ### 场景骨架实施顺序
 
 1. 已完成：`CameraController` 修复当前摄像机不会动的问题，实现玩家跟随、边界 clamp、dead zone 和平滑参数。
-2. 已完成：`CameraZoneLock` 让 battle zone 可以锁定摄像机范围，先用 `F2` 做 debug 清场和解锁占位。
+2. 已完成：`CameraZoneLock` 让 battle zone 可以锁定摄像机范围，先用 debug 清场快捷键做解锁占位。
 3. 已完成：`StageLayerSource` 扩展 `StageLayer`，让每个 rect 支持色块占位或 sprite 资源路径。
 4. 已完成：`StageAssetSlots` 创建并记录 `stage_01` 资源槽位，不要求已有最终素材。
 5. 已完成：`StageProps` 把 props 从旧 `WhiteboxProp` 迁移到统一 layer 数据，支持 back/front 两层。
-6. 已完成：`SceneDebug` 补齐 F1 debug 总开关，并预留/接入分项开关。
+6. 已完成：`SceneDebug` 补齐 debug 总开关，并预留/接入分项开关。
 7. `SceneAcceptanceRun`：PC 和 Switch 都构建通过，PC 能从起点移动到终点并看到相机推进。
 
 ### Debug 快捷键
 
-- `F1`：debug overlay 总开关。
+场景 debug 快捷键统一记录在 `../controls.md`。
-- `F2`：debug 清当前 battle zone，占位模拟清场解锁。
-- `F3`：碰撞矩形和场景网格。
-- `F4`：玩家包围盒。
-- `F5`：battle zone 触发框和 camera bounds。
-- `F6`：敌人出生点。
 
 ### 素材落位标准