BetterJoy：全能游戏控制器映射工具

一、核心功能与优势概述

BetterJoy 是一款开源游戏控制器映射工具，专为任天堂Switch系列控制器（Pro手柄/Joy-Con/SNES手柄）设计，通过XInput模拟技术实现跨平台兼容。其核心价值在于解决三大痛点：

• 多设备适配：同时支持蓝牙/USB连接的Pro手柄、分离式Joy-Con及经典SNES手柄
• 跨模拟器兼容：完美对接Cemu/Wii U模拟器、Citra/3DS模拟器、Dolphin/GameCube模拟器等主流平台
• 低延迟体验：采用MadgwickAHRS算法优化陀螺仪精度，手柄动作响应延迟<10ms

🔍 实用小贴士：项目持续更新，建议通过BetterJoyForCemu/UpdServer.cs模块开启自动更新检测

二、零基础启动指南

2.1 环境准备

必装组件	作用说明	检查方法
ViGEmBus驱动	虚拟XInput设备核心	设备管理器查看"ViGEm Bus Driver"
.NET Framework 4.7.2	运行时依赖	%windir%\Microsoft.NET\Framework\v4.0.30319是否存在
蓝牙4.0以上适配器	无线连接支持	控制面板>设备和打印机>蓝牙设置

驱动安装步骤：

1. 运行BetterJoyForCemu/Drivers/ViGEmBusSetup_x64.msi（64位系统）或ViGEmBusSetup_x86.msi（32位系统）
2. 安装完成后必须重启电脑（⚠️ 跳过此步会导致设备无法识别）

2.2 关键配置

启动程序BetterJoyForCemu.exe后，通过主界面完成三项核心设置：

1. 连接模式选择

   • 蓝牙模式：长按手柄Sync键5秒至指示灯闪烁，在系统蓝牙设置中配对
   • USB模式：直接连接数据线，程序自动识别（推荐充电时使用）

2. 功能开关配置

   • 陀螺仪控制：勾选"Enable Gyro"（适用于体感游戏如塞尔达传说）
   • 震动强度：建议设置70-80%（路径：设置>高级>Rumble Strength）
   • XInput模式：默认开启，支持Steam等平台原生识别

💡 配置文件路径：BetterJoyForCemu/Properties/Resources.resx（建议定期备份）

三、架构原理与定制技巧

3.1 工作原理

程序核心流程分为三层：

1. 设备通信层：通过HIDapi.cs实现与控制器的USB/HID协议通信
2. 数据处理层：MadgwickAHRS.cs处理陀螺仪数据，实现姿态角计算
3. 输出模拟层：OutputControllerXbox360.cs将手柄输入转换为XInput信号

3.2 高级定制

按键重映射：

1. 打开"Reassign"窗口（快捷键F2）
2. 点击目标按键图标，按手柄对应按键完成映射
3. 保存配置至BetterJoyForCemu/Config.cs

多手柄管理：

• Joy-Con分离模式：程序会识别为两个独立控制器，在Cemu模拟器中需分别配置左右手柄偏好
• 同时连接上限：支持4台设备（通过修改Collections/ConcurrentList.cs可扩展至8台）

四、常见问题速查

问题现象	解决方案
控制器无法识别	→ 检查ViGEmBus驱动是否正常运行；尝试重新插拔USB/重启蓝牙
陀螺仪漂移	→ 执行"校准"（工具>传感器校准）；确保手柄放置水平
震动无响应	→ 检查Rumble Strength是否>0；更新ViGEmBus至1.16+版本
XInput模式失效	→ 以管理员身份运行程序；检查BetterJoyForCemu/App.config中EnableXInput值是否为true

🔍 实用小贴士：驱动相关问题可查看BetterJoyForCemu/Drivers/README.txt，包含详细排错流程

五、项目参与与贡献

该项目采用C#开发，核心代码位于BetterJoyForCemu/Joycon.cs（手柄通信）和MainForm.cs（UI交互）。如需提交PR：

1. Fork仓库并克隆至本地：git clone https://gitcode.com/gh_mirrors/be/BetterJoy
2. 使用Visual Studio 2019+打开BetterJoy.sln
3. 遵循原项目代码风格（采用Allman缩进，方法名使用PascalCase）

💡 贡献方向：目前亟需优化的模块包括MacOS兼容性（当前仅支持Windows）和Joy-Con握把模式自动识别功能

通过上述指南，您已掌握BetterJoy的核心使用方法与定制技巧。无论是新手玩家还是进阶开发者，都能通过这款工具充分释放Switch控制器的跨平台潜力。项目持续维护中，遇到问题可通过BetterJoyForCemu/Program.cs中预留的反馈渠道提交Issue。