FooTinderPad — 遊戲控制器 → macOS 鍵鼠

// 系統需求

Requirements

🍎 macOS 13 Ventura 以上最低系統版本

⚙️ Swift 5.9 / Xcode 15+ 建置工具

🕹️ Xbox / PlayStation Controller 已配對的遊戲控制器

♿ 輔助使用 (Accessibility) 權限系統設定中授予

// 安裝

Install

Terminal

$ make clean  && make install

// 預設設定

預設設定

控制器正面

控制器背面

config.json

{
  "deadzone": 0.15,
  "mouseSpeed": 15,
  "scrollSpeed": 2,
  "leftStick": "mouse",
  "rightStick": "scroll",
  "bindings": {
    "buttonA":               { "type": "key",         "key": "Space",          "repeat": true },
    "buttonB":               { "type": "key",         "key": "Return" },
    "buttonX":               { "type": "mouseButton", "button": "left" },
    "buttonY":               { "type": "key",         "key": "Backspace",      "repeat": true },
    "leftShoulder":          { "type": "key",         "key": "Escape" },
    "rightShoulder":         { "type": "mouseButton", "button": "right" },
    "leftTrigger":           { "type": "key",         "key": "RightShift" },
    "rightTrigger":          { "type": "key",         "key": "Alt+Return" },
    "leftThumbstickButton":  { "type": "key",         "key": "Cmd+C" },
    "rightThumbstickButton": { "type": "key",         "key": "Cmd+V" },
    "dpadUp":                { "type": "key",         "key": "Up",             "repeat": true },
    "dpadDown":              { "type": "key",         "key": "Down",           "repeat": true },
    "dpadLeft":              { "type": "key",         "key": "Left",           "repeat": true },
    "dpadRight":             { "type": "key",         "key": "Right",          "repeat": true },
    "createButton":          { "type": "key",         "key": "Fn+Ctrl+Left" },
    "optionsButton":         { "type": "key",         "key": "Fn+Ctrl+Right" }
  }
}

// 示範設定

PS5 示範設定 (易上手版)

下載後直接覆蓋到 ~/Library/Application Support/FooTinderPad/config.json 即可。

⬇ docs/examples/easy-preset.json

設計重點：善用 PS 慣例（Cross 確認 / Circle 取消）、讓三角 / 方塊 / 觸控板邊上的小鈕都各司其職、L2/R2 直接給最常用的複製貼上。

按鈕	對應	說明
左搖桿	`mouse`	滑鼠移動 · `mouseSpeed: 25`
右搖桿	`scroll`	滾輪捲動 · `scrollSpeed: 5`
× Cross	滑鼠左鍵	PS 慣例「主要動作」
○ Circle	`Escape`	PS 慣例「取消/返回」
■ Square	`Backspace` (repeat)	文字編輯刪除，按住連續刪
△ Triangle	`Space`	影片播放 / 瀏覽器捲頁
L1	`LeftShift`	跟方向鍵搭配選文字，也跟 R1 (Return) 組成 Shift+Enter
R1	`Return`	確認 / 換行
L2	`LeftCmd`	按住搭配實體鍵盤組合 Cmd 快捷鍵
R2	`RightCmd`	同上，食指搆得到的位置，適合右手切換 app
L3	`/` Slash	常用於搜尋啟動
R3	滑鼠右鍵	Context menu
D-pad ↑↓←→	滑鼠微移動	`dpad: "mouse"` · `dpadMouseSpeed: 3`，原始碼內建線性曲線
Create（左上小鈕）	`Cmd+V`	貼上
Options（右上小鈕）	`Cmd+C`	複製（拇指容易按到，比扳機順）
觸控板按下	`Fn+Ctrl+Up`	呼叫 Mission Control（macOS 內建快捷鍵）

// 功能

Battery Indicator

🔋 Menu Bar 電量顯示

當控制器連線且回報電量時，menu bar 圖示右側會顯示百分比。

🎮 82%

🎮 ⚡82%

🎮 ⚡100%

🎮 15%

充電中加上 ⚡ 前綴；充滿時顯示 ⚡100%。放電時若降到 20% 或以下，數字轉為紅色提醒充電（充電中的低電量不轉紅，因為已在充電）。

DualSense over Bluetooth 和 Xbox Wireless Controller over BLE 都有 fallback reader：macOS GameController 沒提供電量時，app 會改走控制器專用讀取路徑。控制器未提供電量資訊（有線通用 HID、部分第三方型號）時不顯示百分比，只留 icon。

// 功能

Launch at Login

🚀 登入自動啟動

從選單列點 FooTinderPad 圖示 → Launch at Login 切換開關。打開後 macOS 會在使用者登入時自動啟動 app，同樣的開關也會出現在「系統設定 → 一般 → 登入項目」。

第一次開啟時 macOS 可能要求核可：選單上的項目旁邊會出現黃色三角警示，點下去會帶你到「系統設定 → 一般 → 登入項目」，在那邊把 FooTinderPad 切到開即可。

若 app 是用本機 self-signed 簽章（例如預設的 FooTinderPadDev cert，沒有 Apple Developer Team Identifier），SMAppService 沒辦法登錄 login item。這時會自動 fallback：寫一份 LaunchAgent plist 到 ~/Library/LaunchAgents/com.purefuncinc.FooTinderPad.plist，下次登入由 launchd 啟動。要關掉一樣從選單按一次 Launch at Login 即可。注意這條路線下「系統設定 → 一般 → 登入項目」清單不會列出 FooTinderPad — 選單上的 toggle 才是真實狀態。

// 參考

支援的控制器按鈕

下表的 key 用於 bindings 物件的 JSON 屬性名。沒列在 config 裡的按鈕會被當成 none。

JSON key	PlayStation	Xbox	說明
`buttonA`	× Cross	A	下方面鈕
`buttonB`	○ Circle	B	右方面鈕
`buttonX`	■ Square	X	左方面鈕
`buttonY`	△ Triangle	Y	上方面鈕
`leftShoulder` / `rightShoulder`	L1 / R1	LB / RB	上肩鍵
`leftTrigger` / `rightTrigger`	L2 / R2	LT / RT	下扳機（類比，觸發點 0.55 / 釋放點 0.45）
`leftThumbstickButton` / `rightThumbstickButton`	L3 / R3	LS / RS	按下搖桿
`dpadUp` / `dpadDown` / `dpadLeft` / `dpadRight`	方向鍵		D-pad 四向
`createButton`	Create（左上小鈕）	View	觸控板左上方
`optionsButton`	Options（右上小鈕）	Menu	觸控板右上方
`touchpadButton`	按下整片觸控板	—	僅 PS4 (DualShock4) / PS5 (DualSense)，Xbox 無

搖桿與 D-pad 角色

搖桿與 D-pad 的移動曲線寫在原始碼中，不從 JSON config 調整。

leftStick / rightStick 接受 "mouse" "scroll" "none" 三種角色。

dpad 接受 "bindings" "mouse" "scroll" "none" 四種角色。
預設設定使用 "bindings" 搭配方向鍵綁定；若想改成線性滑鼠微移動，設為 "mouse" 並加入 dpadMouseSpeed。

config.json（dpad mouse 範例）

{
  "deadzone": 0.15,
  "mouseSpeed": 64,
  "scrollSpeed": 2,
  "leftStick": "mouse",
  "rightStick": "scroll",
  "dpad": "mouse",
  "dpadMouseSpeed": 4,
  "dpadScrollSpeed": 2,
  "bindings": {
    "buttonA":               { "type": "key",         "key": "Space",          "repeat": true },
    "buttonB":               { "type": "key",         "key": "Return" },
    "buttonX":               { "type": "mouseButton", "button": "left" },
    "buttonY":               { "type": "key",         "key": "Backspace",      "repeat": true },
    "leftShoulder":          { "type": "key",         "key": "Escape" },
    "rightShoulder":         { "type": "mouseButton", "button": "right" },
    "leftTrigger":           { "type": "key",         "key": "RightShift" },
    "rightTrigger":          { "type": "key",         "key": "Alt+Return" },
    "leftThumbstickButton":  { "type": "key",         "key": "Cmd+C" },
    "rightThumbstickButton": { "type": "key",         "key": "Cmd+V" },
    "createButton":          { "type": "key",         "key": "Fn+Ctrl+Left" },
    "optionsButton":         { "type": "key",         "key": "Fn+Ctrl+Right" }
  }
}

// 參考

支援的按鍵

bindings 中使用的 key 字串由 KeyParser 解析。Token 大小寫不敏感，以 + 串接組合鍵（例：Ctrl+Shift+A）。

修飾鍵 (Modifiers)

修飾鍵	可用別名
Control	`ctrl` · `control` · `leftctrl` · `leftcontrol` · `rightctrl` · `rightcontrol`
Option / Alt	`alt` · `option` · `leftalt` · `leftoption` · `rightalt` · `rightoption`
Shift	`shift` · `leftshift` · `rightshift`
Command / Win	`cmd` · `command` · `win` · `leftcmd` · `leftcommand` · `leftwin` · `rightcmd` · `rightcommand` · `rightwin`
Function	`fn`

主鍵 (Main Keys)

a – z 0 – 9 f1 – f20 up down left right space return tab escape backspace delete home end pageup pagedown minus equal leftbracket rightbracket backslash semicolon quote comma period slash grave

組合規則

單一 token 可以是「主鍵」（例：a、space）或「純修飾鍵綁定」（例：ctrl、fn）
多 token 時，最後一個必須是主鍵，前面全部必須是修飾鍵，例如 Ctrl+Shift+A、Cmd+Space、Alt+Return
重複的修飾鍵會自動去重
結尾若是修飾鍵（例：Ctrl+Shift）會丟出 modifierInMainKeyPosition 錯誤
空 token（開頭、結尾或連續的 +）會丟出 emptySeparatorComponent 錯誤

自動重複 (auto-repeat)

加入 "repeat": true，按住按鈕時對應鍵會以 ~30 Hz 連續重發（400 ms 初始延遲後），類似實體鍵盤按住 Backspace 連刪。預設為 false。寫了 "repeat": true 但綁定是純修飾鍵 / mouseButton / none 的話會被忽略並產生 warning。

config.json 範例

"buttonX": { "type": "key", "key": "Backspace", "repeat": true }