如何自定义虚拟手柄的按键布局和映射
三种自定义层级
JoiPlay 的虚拟手柄自定义分为三个层级，从"粗"到"细"：
- 布局方案：选择几预定义好的布局（比如经典 PS 风格、Xbox 风格、简化版单摇杆等）
- 可视化编辑：直接拖动、缩放、隐藏按钮
- 按键映射：指定每个按钮按下时向引擎发送什么键位
选择预设布局
进入游戏内设置（顶栏箭头 → 齿轮）→ 找 Gamepad 相关选项 → 一般会有 3~5 个预设方案可选。如果你觉得默认布局手感不好，先试试其他预设——往往一个更合手的预设就能解决大部分问题。
可视化编辑模式
2025 年后的版本加入了完整的可视化编辑：
- 打开游戏内设置 → 进入 Gamepad Mapping 或 Custom Layout 子页面
- 界面上的虚拟手柄按钮会进入编辑模式（按钮边缘会出现控制手柄）
- 移动按钮：按住按钮主体 → 拖到任意位置
- 调整尺寸：按住按钮右下角的小手柄 → 拉大或缩小
- 删除按钮：长按按钮 → 选择删除（注意：至少要保留方向摇杆和一个动作按钮才能正常操作）
- 添加按钮：编辑模式下找 "Add Button" 或 "+" 按钮
编辑时所见即所得——改完立刻退出编辑模式试手感，不满意再回来调。
按键映射（Key Mapping）
这是最细粒度的设置——决定每个虚拟按钮按下时，JoiPlay 往引擎解释器里发送什么信号。
例如，RPG Maker 游戏的 Enter 键通常是确认，Esc 是取消/菜单。如果你的虚拟手柄"○"按钮映射到了 Enter，那按它就是确认；如果映射到 Space，那就是空格。
操作方法
- 编辑模式下，点击某个按钮 → 选择 "Edit Key Mapping"
- 会弹出一个键位选择界面，列出所有可映射的键盘按键和手柄按钮
- 选一个合适的键位，保存
常用键位参考
| 引擎 | 常用操作 | 对应键位 |
|---|---|---|
| RPG Maker | 确认 / 互动 | Enter / Space / Z |
| RPG Maker | 取消 / 菜单 | Esc / X |
| RPG Maker | 方向 | 方向键 ↑↓←→ |
| Ren'Py | 前进 | Enter / Space / 鼠标左键 |
| Ren'Py | 存档菜单 | Esc |
很多 RPG Maker 同人游戏把 Enter 和 Space 都映射为确认键，所以你可以让两个虚拟按钮都绑 Enter——灵活运用，不受"一个按钮一个键位"的束缚。
布局文件的保存与分享
自定义的布局会自动保存在 JoiPlay 的游戏设置中（每个游戏独立保存）。如果你想把某个好用的布局应用到多个游戏，有两种方式：
- 在游戏内设置面板里找 "Import Layout" / "Export Layout"
- 或直接复制文件（JoiPlay 的游戏数据存储在
/data/data/com.joiplay.<plugin>/files/下，找到对应游戏的配置文件里有虚拟手柄布局的 JSON 段）
2025~2026 年的虚拟手柄重构
社区反馈 2025 年后 JoiPlay 对虚拟手柄做了一次完整的底层重构，解决了老版本的几个痛点：
- 之前的按键布局不能跨版本继承（老版本保存的布局在新版本里会错位）
- 编辑模式之前很简陋，只能调位置不能调尺寸
- 新增了按键映射对话框，可以直接看键盘上的哪个键
如果你用的是 1.20.000 之前的版本，建议更新到最新版再调整虚拟手柄——老版本的布局文件在新版里需要重新编辑。