GamepadMapper：用手柄掌控 Mac 的开源映射工具

GamepadMapper：用手柄掌控 Mac 的开源映射工具

· json · rss
Subscribe:
RSS
RSS
JSON
JSON
Github
Github

About

作为一名 Mac 用户，你是否曾想过用手柄来控制游戏之外的应用？或者你是否需要在某些不支持手柄的 Mac 游戏中使用手柄替代键鼠？GamepadMapper 就是为此而生的开源 macOS 工具。

什么是 GamepadMapper？

GamepadMapper 是一款 macOS 菜单栏应用，可以将手柄的按键和摇杆实时映射为键盘按键和鼠标操作。它基于 Swift 6 + SwiftUI 构建，纯 Swift Package Manager 管理，无任何第三方依赖，支持 Apple Silicon 和 Intel Mac。

主界面：权限状态、手柄连接状态、方案管理和映射编辑入口一目了然

核心特性

1. 可靠的底层输入读取

GamepadMapper 采用了 双输入机制 确保手柄输入稳定可靠：

  • HID 层读取（IOHIDManager）：在独立后台线程运行，直接从硬件层读取手柄输入，即使应用切到后台也能持续响应。这是映射引擎的主要输入源。
  • GameController 框架（GCController）：用于手柄连接/断开通知和实时状态可视化展示。

实时手柄状态可视化：D-pad、摇杆、肩键、扳机键、ABXY 功能键的状态一目了然

2. 高性能映射引擎

映射引擎运行在 qos: .userInteractive 的高优先级后台队列上：

  • 8ms 轮询间隔（约 125Hz），带来低延迟的响应体验
  • 支持多种映射类型：
  • 按键 → 键盘键 / 鼠标键
  • 摇杆 → 键盘键（方向感知，可配死区）
  • 摇杆 → 鼠标移动（可调灵敏度）
  • 摇杆 → 鼠标拖拽
  • 每个映射最多支持 2 个组合目标（Combo Targets），实现一键多操
  • 内置软件按键重复（Key Repeat）机制，模拟原生键盘长按效果

映射编辑器：为每个按键或摇杆配置映射目标、死区、灵敏度和组合键

3. 拖拽边界系统

对于鼠标拖拽映射，GamepadMapper 提供了独特的圆形拖拽边界功能：光标被限制在以指定中心点和半径的圆形区域内，摇杆回中时自动回到边界中心。配合可视化叠加窗口，可以直观地调整边界位置和大小。

拖拽边界可视化：圆形叠加窗口支持拖拽移动和边缘缩放

4. 多方案管理

方案以 JSON 文件存储在 ~/Library/Application Support/GamepadMapper/Profiles/，支持创建、重命名、复制、删除和重置。不同方案可以有不同的映射配置、灵敏度和拖拽边界，方便在不同场景间快速切换。

5. 多语言支持

内置 6 种语言界面：英文、简体中文、日文、韩文、俄文、西班牙文，可在设置中实时切换。

6. 便捷的菜单栏入口

菜单栏图标和下拉菜单：快速开始/停止映射、切换方案、查看引擎日志

快速上手

  1. 启动应用 — 菜单栏出现手柄图标
  2. 通过蓝牙或 USB 连接手柄
  3. 点击菜单栏图标，打开设置
  4. 授予辅助功能权限（用于发送键盘/鼠标事件）
  5. 编辑映射配置，点击开始映射
  6. 切换到目标应用，映射在后台持续生效

技术架构

语言Swift 6.0 UI 框架SwiftUI + @Observable 最低系统macOS 14 (Sonoma) 输入层IOHIDManager + GameController.framework 输出层CGEvent（键盘 + 鼠标模拟） 构建系统Swift Package Manager 许可协议GPL v3 获取源码

GamepadMapper 是开源项目，源码托管在 GitHub：

github.com/huangyebiaoke/GamepadMapper

git clone https://github.com/huangyebiaoke/GamepadMapper.git
cd GamepadMapper
swift build

如果你有任何问题或建议，欢迎在 GitHub 提交 Issue 或 PR！