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 鍵分配。

下一步