KeyMod ▾

8. 手柄

将手机变成虚拟游戏控制器，用于游戏、复古模拟与游戏测试。

布局

手柄提供完整控制器布局：方向键、动作键、肩键、模拟摇杆与 Start/Select。

控件 操作
方向键 点击方向箭头
动作键 (A, B, X, Y) 点击
肩键 点击顶部 L1、L2、R1、R2
模拟摇杆 触摸并拖动摇杆圆区
Start / Select 点击按钮

预设系统 (v7)

KeyMod 0.15 引入 基于预设的手柄系统。不再使用固定内置布局，手柄配置保存为可循环、导入、导出的 预设。

管理预设

  • 点击工具栏 Preset 芯片 在可用布局间循环
  • 长按 Preset 芯片 打开完整预设列表，含导入、添加模块、导出
  • 捆绑的 emu-6 布局作为起始预设 (preset_default)
  • 预设为可共享 JSON，布局 schema v7

添加模块

从预设菜单可向任意布局添加新模块：

  • D-Pad / Stick — 添加左拇指模块 (stick_left, stick_left_2 等)
  • Touchpad — 添加触控板 (touchpad_1, touchpad_2 等)，捆绑 L/M/R 鼠标键
  • Buttons — 添加面键、肩键或扳机

自定义

  • 配置任意模块 — 点击模块打开配置对话框调整行为
  • 模拟 vs 按键模式 — 摇杆可设为 STICK_KEY（数字方向键）或 STICK_MOUSE（相对指针/鼠标移动）
  • WASD 映射 — 为左摇杆分配 WASD，用于 PC 游戏
  • 按钮/摇杆尺寸缩放 — 按触摸区域调整大小
  • 背景图 — 自定义手柄背景（共享预设中以 base64 嵌入，最大 6 MiB）
  • 触觉反馈 — 按键振动（仅面键，非鼠标点击）
  • 陀螺仪 — 在手柄界面激活时，用设备陀螺仪移动主机指针

模块模型

每个屏幕控件为三层 模块：

层 定义内容
Slot / identity 画布上的控件（如 stick_left, stick_right, touchpad_1）
Behavior (type) 主机接收内容：STICK_KEY, STICK_MOUSE, DPAD, BUTTON, TOUCHPAD
Parameters 同模块调参：dpadVariant, stickMouseSensitivity, stickVisualVariant, 大小、颜色

模拟摇杆

  • 左摇杆 → 键盘键： 映射方向键，支持对角。可在模块配置中设为 WASD。
  • 右摇杆 → 鼠标移动： STICK_MOUSE 模式，可配置灵敏度 (stickMouseSensitivity)，死区防止漂移。
  • 迟滞： 激活 (0.6) 与释放 (0.4) 阈值减少边界按键抖动。

触控板

  • 多触控板支持：单布局可添加多个触控板 (touchpad_1, touchpad_2 等)
  • 默认 方形区域，长按可调整大小
  • 捆绑鼠标键 (L/M/R) 在所有触控板间共享
  • 鼠标键尺寸：长按触控板调整 Mouse button size，或长按单个鼠标键调整 This button size

说明： 手柄 HID 协议仍在积极开发。基本按键可用；模拟摇杆精度可能因设备而异。

故障排除

模拟摇杆无响应

现象 解决方案
摇杆无动作 检查模块配置。确认摇杆未卡在死区（中心区域）。检查迟滞阈值 — 需移过 0.6 激活才触发。
按键发送错误键 打开模块配置检查按键分配。点击按键打开配置弹窗修正映射。
触控板鼠标键不点击 确认预设有捆绑 L/M/R 键。添加触控板会自动添加共享鼠标键。检查模块配置中的 HID 键分配。

下一步