Add InputDeviceIconSetSO configuration guide and related documentation

- Created a new markdown file detailing the configuration of InputDeviceIconSetSO. - Included sections on system architecture, field explanations, image specifications, and complete workflow from setup to runtime. - Documented the automatic device recognition logic and provided troubleshooting for common issues. - Added references to relevant files and scripts for easier navigation.
2026-05-23 00:10:23 +08:00
parent b7baf7ad6a
commit e879efaa89
45 changed files with 3469 additions and 63 deletions
--- a/Docs/Standards/AssetFolderSpec.md
+++ b/Docs/Standards/AssetFolderSpec.md
@@ -1,6 +1,6 @@
 # 资源文件夹目录规划与管理规范

-> **版本**：1.2  
+> **版本**：1.3  
 > **创建日期**：2026-05  
 > **适用范围**：`Assets/` 目录下所有非代码资源（美术、数据、预制体、场景等）  
 > **资源管理系统**：Unity Addressables（禁止使用 `Resources.Load`）  
@@ -77,6 +77,14 @@ Assets/
 │   │   ├── Environment/                场景环境（Tilesets、Backgrounds、Props）
 │   │   ├── Effects/                    特效美术（Sprites、Materials、Atlases）
 │   │   ├── UI/                         UI 专用图片（Icons、Frames、Backgrounds、Atlases、Materials）
+│   │   │   ├── Icons/
+│   │   │   │   ├── Skills/             技能图标
+│   │   │   │   ├── Items/              道具 / 护身符图标
+│   │   │   │   ├── Status/             状态效果图标
+│   │   │   │   └── InputKeys/          按键/手柄按键图标（供 InputDeviceIconSetSO 引用）
+│   │   │   ├── Frames/
+│   │   │   ├── Backgrounds/
+│   │   │   └── Atlases/
 │   │   └── Shared/                     跨模块复用基础资产（Palettes、Textures、Materials）
 │   │
 │   ├── Data/                           ScriptableObject 资产（按模块分类）
@@ -88,6 +96,8 @@ Assets/
 │   │   ├── Audio/
 │   │   ├── World/
 │   │   ├── UI/
+│   │   │   ├── Panels/                 UI 面板配置 SO
+│   │   │   └── InputIcons/             按键图标集 SO（InputDeviceIconSetSO，每设备一个文件）
 │   │   └── Settings/
 │   │
 │   ├── Prefabs/                        预制体
@@ -169,7 +179,8 @@ Art/
 │   ├── Icons/                  图标按子类分目录，统一 32x32 或 64x64 规格
 │   │   ├── Skills/             技能图标，用于技能栏 / 技能选择界面 · IC_Skills_{Name}.png
 │   │   ├── Items/              道具 / 护身符图标，用于物品栏 · IC_Items_{Name}.png
-│   │   └── Status/             状态效果图标（中毒、燃烧等），用于角色状态栏 · IC_Status_{Name}.png
+│   │   ├── Status/             状态效果图标（中毒、燃烧等），用于角色状态栏 · IC_Status_{Name}.png
+│   │   └── InputKeys/          按键/手柄按键图标，用于 InputDeviceIconSetSO 绑定路径图标映射 · IC_Key_{DeviceShort}_{KeyName}.png
 │   ├── Frames/                 面板框架、血条框、对话框边框等 (.png) · FRAME_{Description}.png
 │   ├── Backgrounds/            界面背景图、全屏半透明遮罩、渐变填充图 (.png) · UIBG_{Description}.png
 │   └── Atlases/                UI 图标与框架图集 (.spriteatlas)，减少 UI 渲染批次 · Atlas_UI_{Category}.spriteatlas
@@ -196,6 +207,7 @@ Art/
 | 背景层 | `_Game/Art/Environment/Backgrounds/{Region}/` | `BG_{Region}_{Layer}.png` | `BG_Forest_Far.png` |
 | 场景道具 | `_Game/Art/Environment/Props/{Category}/` | `PROP_{Category}_{Name}.png` | `PROP_Furniture_Chest.png` |
 | UI 图标 | `_Game/Art/UI/Icons/{SubType}/` | `IC_{Category}_{Name}.png` | `IC_Skills_SoulBlade.png` |
+| 按键图标 | `_Game/Art/UI/Icons/InputKeys/` | `IC_Key_{DeviceShort}_{KeyName}.png` | `IC_Key_KBM_Space.png`、`IC_Key_Xbox_A.png` |
 | UI 框架 | `_Game/Art/UI/Frames/` | `FRAME_{Description}.png` | `FRAME_HealthBar.png` |
 | UI 背景 | `_Game/Art/UI/Backgrounds/` | `UIBG_{Description}.png` | `UIBG_PauseMenu.png` |
 | 色板参考 | `_Game/Art/Shared/Palettes/` | `PAL_{Name}.png` | `PAL_Forest.png` |
@@ -230,8 +242,8 @@ Data/
 │   ├── Player/                 玩家相关事件
 │   ├── Combat/                 战斗相关事件
 │   ├── Enemies/                敌人相关事件
-│   ├── World/                  世界交互事件
-│   ├── UI/                     UI 显隐事件
+│   ├── World/                  世界交互事件（含 EVT_ShowInteractPrompt、EVT_HideInteractPrompt）
+│   ├── UI/                     UI 显隐事件（含 EVT_InputDeviceChanged）
 │   ├── Audio/                  音频播放事件
 │   ├── Progression/            进度成长事件
 │   ├── Dialogue/               对话事件
@@ -258,7 +270,8 @@ Data/
 │   ├── Map/                    地图与房间配置
 │   └── Shop/                   商店配置
 ├── UI/
-│   └── Panels/                 UI 面板配置
+│   ├── Panels/                 UI 面板配置
+│   └── InputIcons/             按键图标集 SO（每设备一个文件，通过 Inspector 直接引用，不走 Addressables）
 └── Settings/                   全局设置与难度配置
 ```

@@ -282,6 +295,7 @@ Data/
 | `UI_` | UI 配置 | `UI_PanelConfig_HUD.asset` |
 | `SET_` | 设置 | `SET_GlobalSettings.asset` |
 | `ABL_` | 能力 | `ABL_DoubleJump.asset` |
+| `ICN_` | 按键图标集 | `ICN_KeyboardMouse.asset`、`ICN_Xbox.asset` |

 ### 3.3 事件频道 SO 特别规则

@@ -755,6 +769,58 @@ var (prefab, _) = await AssetLoader.LoadAsync<GameObject>(AddressKeys.PrefabPlay
 4. 在 _Game/Data/World/Map/ 下创建 MAP_RoomData_{Region}_{Index:D2}.asset
 ```

+### 10.9 新增输入设备图标集（Input Device Icon Set）
+
+> **推荐工具**：`BaseGames/Input Icon Studio`（`InputIconStudioWindow`）——可视化管理所有设备的按键图标，自动写入对应 SO。
+
+**⚠ Addressable 决策：不需要 Addressable。**  
+`InputDeviceIconSetSO` 由 `InputIconService`（挂载在 UIRoot 上）通过 `SerializeField` 直接引用，随常驻场景加载，无需运行时动态加载。
+
+```
+1. 美术导入
+   a. 在 _Game/Art/UI/Icons/InputKeys/ 下放置按键图标 Sprite Sheet 或单张 PNG
+   b. Import Settings：Texture Type = Sprite, Filter=Point, PPU=32（像素图）或 PPU=1（矢量/高分辨率图）
+   c. 命名格式：IC_Key_{DeviceShort}_{KeyName}.png
+      DeviceShort：KBM（键鼠）/ Xbox / PS / Switch
+      示例：IC_Key_KBM_Space.png、IC_Key_Xbox_A.png、IC_Key_PS_Cross.png
+
+2. 创建图标集 SO
+   a. 菜单 BaseGames/Input Icon Studio → 点击对应设备行的「+ 新建」按钮
+   b. 选择保存路径（推荐 _Game/Data/UI/InputIcons/）
+   c. 命名：ICN_{DeviceType}.asset（例：ICN_KeyboardMouse.asset、ICN_Xbox.asset）
+
+3. 填充图标映射
+   a. 在 Input Icon Studio 左列选择 Action，右列指定 Sprite（或在 Inspector 的 InputDeviceIconSetSOEditor 中操作）
+   b. 可使用 Inspector 顶部「从 Action Asset 填充路径」按钮批量生成条目，再逐一拖入 Sprite
+   c. 覆盖率芯片变为绿色（100%）表示该设备全部 Action 已配置
+
+4. 绑定到 InputIconService
+   a. 在 Persistent 场景的 UIRoot → InputIconService 组件 Inspector 中
+   b. 将 4 个 ICN_*.asset 拖入对应 SerializeField 字段（_kbMouseSet / _xboxSet / _playStationSet / _switchSet）
+
+5. 验证
+   a. 进入 PlayMode，切换输入设备，观察 HUD 交互提示图标是否正确切换
+   b. 在 Input Icon Studio 的「交互提示预览」中模拟检查各设备外观
+```
+
+**ICN_ SO 命名与路径规则：**
+
+| SO 名称 | 路径 | 对应设备 |
+|---------|------|---------|
+| `ICN_KeyboardMouse.asset` | `_Game/Data/UI/InputIcons/` | 键鼠（`InputDeviceType.KeyboardMouse`） |
+| `ICN_Xbox.asset` | `_Game/Data/UI/InputIcons/` | Xbox 手柄（`InputDeviceType.XboxController`） |
+| `ICN_PlayStation.asset` | `_Game/Data/UI/InputIcons/` | PS4/PS5（`InputDeviceType.PlayStationController`） |
+| `ICN_Switch.asset` | `_Game/Data/UI/InputIcons/` | Switch Pro/Joy-Con（`InputDeviceType.SwitchController`） |
+
+**按键图标命名规范（`IC_Key_{DeviceShort}_{KeyName}.png`）：**
+
+| 设备简称 | 适用范围 | 示例 |
+|---------|---------|------|
+| `KBM` | 键盘按键 / 鼠标按键 | `IC_Key_KBM_Space.png`、`IC_Key_KBM_E.png`、`IC_Key_KBM_LMB.png` |
+| `Xbox` | Xbox 面板按钮 / 摇杆 / 扳机 | `IC_Key_Xbox_A.png`、`IC_Key_Xbox_RT.png`、`IC_Key_Xbox_LStick.png` |
+| `PS` | PlayStation 按钮 / 摇杆 / 扳机 | `IC_Key_PS_Cross.png`、`IC_Key_PS_R2.png`、`IC_Key_PS_L1.png` |
+| `Switch` | Switch 面板按钮 / Joy-Con | `IC_Key_Switch_A.png`、`IC_Key_Switch_ZR.png`、`IC_Key_Switch_DPad.png` |
+
 ---

 ## 11. 禁止行为清单
@@ -793,6 +859,7 @@ var (prefab, _) = await AssetLoader.LoadAsync<GameObject>(AddressKeys.PrefabPlay
 | **Weapon Editor** | `BaseGames/Data/Weapon Editor` | 武器配置 SO（`WPN_*_Data.asset`） | 双面板列表，右栏全属性 + HitBox Prefab 验证 + 快捷操作 |
 | **Weapon HitBox Wizard** | `BaseGames/Create/Weapon HitBox Prefab` | 武器 HitBox Prefab（4 方向 Ground/Up/Down/Air） | 自动生成 `WPN_{ID}_HitBox.prefab`，支持各方向碰撞体形状配置 |
 | **Skill HitBox Wizard** | `BaseGames/Create/Skill HitBox Prefab` | 技能 HitBox Prefab（多段伤害支持） | 自动生成 `SKL_{ID}_HitBox.prefab`，可配置 1–4 段 hitBoxCount |
+| **Input Icon Studio** | `BaseGames/Input Icon Studio` | 按键图标集 SO（`ICN_*.asset`）+ 按键图标 Sprite 映射 | 设备标签栏 + Action 列表覆盖率指示 + 实时编辑 + 交互提示模拟预览 |

 ### 12.2 场景搭建工具