BetterJoy v7.0 使用与构建完全指南:让 Switch Pro 手柄、Joy-Con 与 SNES 手柄畅玩 PC 模拟器
BetterJoy v7.0 使用与构建完全指南:让 Switch Pro 手柄、Joy-Con 与 SNES 手柄畅玩 PC 模拟器
本篇指南以 BetterJoy 项目官方 README 为主线,完整讲解从驱动安装、手柄蓝牙/USB 连接、Cemu/Cemuhook 与通用 XInput 配置,到陀螺仪鼠标控制、特殊按键重映射以及从源码构建的每一步,并结合仓库源码(Program.cs、Config.cs、App.config、UpdServer.cs 等)剖析其底层实现原理。读完本文,你将掌握 BetterJoy 的完整使用流程、全部可调配置项,以及它在设备枚举、虚拟手柄输出与 DSU 协议服务器上的工作机制。
一、BetterJoy 是什么:核心功能与适用场景
BetterJoy 是一款面向 Windows 的开源工具,核心目标是把任天堂 Switch 系手柄带到 PC 平台。根据 README.md 的定位,它支持以下设备:
- Switch Pro Controller(Switch Pro 手柄)
- Joy-Con(左右两只,可单独使用或合并使用)
- Switch SNES 手柄
其输出目标覆盖主流 PC 模拟器与通用输入体系:
| 输出目标 | 说明 |
|---|---|
| Cemu(配合 Cemuhook) | 通过 DSU 协议获得手柄输入与陀螺仪体感 |
| Citra | 3DS 模拟器 |
| Dolphin | Wii/GameCube 模拟器 |
| Yuzu | Switch 模拟器 |
| 通用 XInput | 作为标准 Xbox 360 手柄呈现在系统级,可被 Steam 等任意 XInput 程序识别 |
除按键与摇杆输入外,BetterJoy 还提供两项颇具特色的附加能力(README 明确列出):
- 用陀螺仪控制鼠标——手持 Pro 手柄或 Joy-Con 摆动即可移动系统鼠标指针;
- 重映射特殊按键——将 SL、SR、Capture(截图键)等原本难以利用的按键映射为任意键位。
从源码角度看,BetterJoy 通过 HID 直连方式识别任天堂官方设备。在 Program.cs 中定义了内置设备的 Vendor ID 与 Product ID:
private const ushort vendor_id = 0x57e; // Nintendo
private const ushort product_l = 0x2006; // 左 Joy-Con
private const ushort product_r = 0x2007; // 右 Joy-Con
private const ushort product_pro = 0x2009; // Pro 手柄
private const ushort product_snes = 0x2017; // SNES 手柄
这意味着只要 HID 设备枚举结果命中上述 ID 组合,程序就会自动接管并驱动它。
二、仓库结构速览
BetterJoy 的主工程位于仓库根目录下的 BetterJoyForCemu 目录,关键文件如下:
| 路径 | 作用 |
|---|---|
| README.md | 项目主文档(本文基础) |
| BetterJoy.sln | Visual Studio 解决方案文件 |
| BetterJoyForCemu/BetterJoy.csproj | 工程文件,目标框架 .NET Framework 4.6.1 |
| BetterJoyForCemu/Program.cs | 程序入口、设备枚举管理(JoyconManager)、全局钩子 |
| BetterJoyForCemu/Joycon.cs | 单只手柄的对象模型:按键解析、摇杆校准、IMU、震动、输出 |
| BetterJoyForCemu/UpdServer.cs | DSU 协议(Cemuhook)UDP 服务器实现 |
| BetterJoyForCemu/Config.cs | 动态配置(settings 文件)读写 |
| BetterJoyForCemu/App.config | 全部可调参数(IP/端口、震动、陀螺仪、HIDGuardian 等) |
| BetterJoyForCemu/MainForm.cs | 主窗体:按钮映射、校准、Joy-Con 配对/拆分 |
| BetterJoyForCemu/3rdPartyControllers.cs | 第三方手柄支持(自定义 VID/PID/序列号) |
| BetterJoyForCemu/Controller/OutputControllerXbox360.cs | 通过 ViGEm 虚拟 Xbox 360 手柄输出 |
| BetterJoyForCemu/Controller/OutputControllerDualShock4.cs | 通过 ViGEm 虚拟 DualShock 4 手柄输出 |
| BetterJoyForCemu/Drivers | 驱动安装包(ViGEmBus、HIDGuardian)及说明 |
| BetterJoyForCemu/x64、BetterJoyForCemu/x86 | 对应架构的 hidapi.dll |
三、快速上手:从驱动安装到模拟器内配置
README 给出的标准使用流程共 5 步,下面结合仓库实物逐一展开。
1. 安装驱动
驱动是整个方案的地基,README 特别强调"先读 Drivers 目录下的 README"。
- 阅读 BetterJoyForCemu/Drivers/README.txt 了解驱动说明;
- 运行 ViGEmBusSetup_x64.msi(64 位系统)或 ViGEmBusSetup_x86.msi(32 位系统)安装 ViGEmBus 虚拟手柄总线驱动;
- 重启计算机。
ViGEmBus 是 BetterJoy 将任天堂手柄"伪装"成 Xbox/DS4 手柄的关键。程序在启动时通过 Nefarius.ViGEm.Client 库创建虚拟手柄实例,若该驱动缺失,Program.cs 会捕获 VigemBusNotFoundException 并在控制台提示 "Could not start VigemBus. Make sure drivers are installed correctly."。
提示:仓库内 packages.config 记录依赖
Nefarius.ViGEm.Client 1.17.178。此外,Drivers 目录还附带可选的 HIDGuardian 驱动(用于 Steam 大屏模式等场景),详见下文"进阶配置"。
2. 运行 BetterJoyForCemu.exe
- 直接运行
BetterJoyForCemu.exe; - 若你的键盘/鼠标按键映射不生效,请以管理员身份运行(README 明确提示)。
程序启动后会自动枚举 HID 设备、启动 UDP 运动服务器并注册全局键盘/鼠标钩子(用于按键重映射与陀螺仪控制鼠标),控制台输出 "All systems go" 表示就绪(见 Program.cs)。
3. 连接控制器
按下一节"手柄的连接与断开"操作,将手柄以蓝牙或 USB 方式接入 PC 即可。程序每 2 秒自动扫描一次新接入的手柄(Program.cs 中的 controllerCheck 定时器),主界面会为每个手柄分配一个带图标的按钮,并显示连接日志。
4. 配置 Cemu / Cemuhook
README 给出的 Cemu 配置步骤如下:
- 启动 Cemu,确保 Cemuhook 已选中 BetterJoy 提供的控制器;
- 若使用 Joy-Con:Cemuhook 会检测到两个控制器,每个都能给出全部按键,但选择哪一个决定陀螺仪体感使用哪只手——按你惯用手偏好选择即可;
- 进入 Cemu 的 Input Settings(输入设置),将输入源选为 XInput,按常规方式为按键/摇杆指派映射;
- 若不想逐一指派按键:可建立一份以 Wii U Gamepad 为控制器的输入配置,并在 GamePad motion source(GamePad 体感源)下勾选 "Also use for buttons/axes"(同时用于按键/摇杆)。注意:README 注明自版本 3 起这不再是必需步骤;
- 想要震动反馈的话,将 Cemu 中的震动强度调到 70%–80%。
5. 作为通用 XInput 手柄使用
README 特别说明:自版本 3 起,Pro 手柄和 Joy-Con 可以直接作为标准 Xbox 手柄出现在 Windows 系统中,例如直接在 Steam 中使用。这是因为 BetterJoy 通过 ViGEm 创建了虚拟 Xbox 360 手柄(详见下文"XInput 输出"一节)。
四、手柄的连接与断开
蓝牙模式
- 进入配对(广播)模式:按住手柄顶部的小按钮(sync/同步键)5 秒,手柄开始广播;
- 配对:在 Windows 蓝牙设置中搜索设备并按常规流程配对;
- 断开:按住 Home 键(或 Capture 键)2 秒,或按一下 sync 按钮;
- 重连:按下手柄上的任意按钮即可重新连接。
USB 模式
将手柄用 USB 线直接插入电脑即可,即插即用。从源码看,USB 连接的手柄序列号固定为 000000000001,Joycon.cs 据此判定连接类型(connection = isUSB ? 0x01 : 0x02),UDP 服务器会将该信息上报给模拟器。
Windows 10 下移除(断开)设备
如果设备没有正常移除,README 提供了手动移除方法:
- 打开"蓝牙和其他设备设置"(Bluetooth and other devices settings);
- 在第一个分类"鼠标、键盘和笔"(Mouse, keyboard, & pen)下找到 Pro 手柄;
- 点击它,会浮现"Remove(移除)"按钮;
- 点击"Remove"完成移除。
五、进阶功能与全部配置项
BetterJoy 的配置分为两部分:程序目录下的 settings 文件(由 Config.cs 管理)与 BetterJoyForCemu.exe.config(源自 App.config)。
5.1 settings 文件:动态配置与按键重映射
settings 文件存放在可执行文件同目录,采用"键 值"逐行格式,共 11 个基本项(源码中 settingsNum = 11)。初始化时 Config.cs 会写入以下键,其默认值由 GetDefaultValue() 决定:
| 键名 | 默认值 | 含义 |
|---|---|---|
ProgressiveScan |
1 |
是否持续扫描新控制器(1 开启 / 0 关闭) |
StartInTray |
0 |
是否启动时最小化到托盘 |
capture |
key_<PrintScreen> |
Capture 键映射(key_ 前缀 = 键盘键,joy_ 前缀 = 手柄按键,mse_ 前缀 = 鼠标键) |
home |
0 |
Home 键映射 |
sl_l / sl_r |
0 |
左/右 Joy-Con 的 SL 键映射 |
sr_l / sr_r |
0 |
左/右 Joy-Con 的 SR 键映射 |
shake |
0 |
摇动输入映射 |
reset_mouse |
joy_10(即摇杆按下 STICK) |
将鼠标指针重置到主屏中央的触发键 |
active_gyro |
0 |
陀螺仪激活键(按住启用 / 切换启用,配合 GyroHoldToggle) |
映射值支持 key_<虚拟键码>、joy_<手柄按键枚举值>、mse_<鼠标键值> 三种前缀。主界面通过 Reassign.cs 窗体提供图形化修改入口;reset_mouse、active_gyro 还能绑定鼠标按键,Program.cs 中注册的全局鼠标/键盘事件钩子会在按下这些键时触发"重置鼠标指针/激活陀螺仪"动作。
5.2 App.config:全量参数说明
App.config 是 BetterJoy 最重要的调参入口,按功能分组整理如下(默认值以仓库文件为准):
运动服务器(Cemuhook UDP)
| 参数 | 默认值 | 说明 |
|---|---|---|
IP |
127.0.0.1 |
运动服务器监听地址;改 0.0.0.0 或局域网 IP 可让其他电脑访问 |
Port |
26760 |
监听端口;若冲突需同步修改 PadTest 与 cemuhook.ini |
MotionServer |
true |
是否启用运动服务器(false 则纯 XInput 使用) |
震动
| 参数 | 默认值 | 说明 |
|---|---|---|
LowFreqRumble |
40 |
HD 震动低频,建议不超过约 1200 |
HighFreqRumble |
120 |
HD 震动高频,同上 |
EnableRumble |
true |
总开关 |
EnableShakeInput |
false |
摇动手柄触发输入(目前仅 DS4 输出生效,占用 DirectInput 的 Button 13) |
ShakeInputSensitivity |
10 |
摇动检测灵敏度 |
ShakeInputDelay |
200 |
摇动检测间隔(毫秒,不要低于 15) |
想获得"更强"的震动,README 注释建议将低频/高频设为
160/320。
按键布局
| 参数 | 默认值 | 说明 |
|---|---|---|
SwapAB |
false |
交换 A/B,按"名称"而非物理位置模拟 Xbox 布局 |
SwapXY |
false |
交换 X/Y,同上 |
校准
| 参数 | 默认值 | 说明 |
|---|---|---|
AllowCalibration |
false |
启用主界面"Calibrate"按钮做陀螺仪校准(一次只能校一只手柄) |
acc_sensiti / gyr_sensiti |
16384,16384,16384 / 18642,18642,18642 |
加速度计/陀螺仪灵敏度默认校准值(第三方手柄使用) |
stick_cal / stick2_cal |
0x780,... |
摇杆校准数据 |
deadzone / deadzone2 |
200 |
摇杆死区 |
StickScalingFactor / StickScalingFactor2 |
1.00 |
摇杆坐标缩放;推不满摇杆时调大 |
陀螺仪(鼠标/摇杆)
| 参数 | 默认值 | 说明 |
|---|---|---|
GyroAnalogSliders |
false |
用陀螺仪倾斜模拟大扳机(类拟滑块)值;Pro 手柄合并扳机,双 Joy-Con 各自倾斜 |
GyroAnalogSensitivity |
400 |
倾斜灵敏度(改 -400 可反转倾斜方向) |
GyroToJoyOrMouse |
false |
核心开关:joy_left/joy_right 把陀螺仪转为左/右摇杆,mouse 转为鼠标移动,none 关闭 |
UseFilteredIMU |
true |
使用滤波后 IMU 数据(false 用原始陀螺仪,响应更快) |
AHRS_beta |
0.05 |
Madgwick AHRS 滤波器增益,影响滤波发散 |
GyroMouseSensitivityX/Y |
1200 / 800 |
陀螺仪→鼠标灵敏度(用原始值时需除以约 15) |
GyroStickSensitivityX/Y |
40.0 / 10.0 |
陀螺仪→摇杆灵敏度(原始值约 2.6 / 0.6) |
GyroStickReduction |
1.5 |
激活陀螺仪摇杆时摇杆量程缩减系数(1 不变,1.5 约减半) |
GyroHoldToggle |
true |
true = 按住激活键才启用陀螺仪(hold),false = 按一次切换(toggle) |
GyroMouseLeftHanded |
false |
双 Joy-Con 时默认取右 Joy-Con 陀螺仪驱动鼠标,true 换为左手 |
DragToggle |
false |
拖拽行为切换(仅作用于被映射的鼠标键) |
HIDGuardian(可选隐藏驱动)
| 参数 | 默认值 | 说明 |
|---|---|---|
UseHIDG |
false |
启用后将 Pro/Joy-Con 对其它程序隐藏,防止退出时手柄"卡死"及部分程序的 DI/XI 冲突 |
PurgeWhitelist |
false |
启动时清空 HIDGuardian 进程白名单 |
PurgeAffectedDevices |
false |
退出时清空受控设备列表 |
HIDGuardian 已不再默认安装(官方 Drivers/README.txt 说明它曾给用户带来困扰)。只有当你知道自己在做什么(例如在 Steam 大屏模式下同时使用 Pro 手柄 + 2 只 Joy-Con)时才需要它;相关安装脚本位于 BetterJoyForCemu/Drivers/HIDGuardian。
LED 与电源管理
| 参数 | 默认值 | 说明 |
|---|---|---|
HomeLEDOn |
true |
Home 键 LED 环形灯常亮 |
UseIncrementalLights |
true |
用多颗 LED 显示当前玩家编号(而非单颗) |
AutoPowerOff |
false |
程序退出时自动关闭手柄电源 |
PowerOffInactivity |
-1 |
无操作多少分钟后自动关机(-1 = 无限) |
HomeLongPowerOff |
true |
长按 Home(右侧/合并)或 Capture(仅左侧)2 秒关机 |
输出与调试
| 参数 | 默认值 | 说明 |
|---|---|---|
ShowAsXInput |
true |
将手柄暴露为 Xbox 360 手柄(false 则仅支持 UDP 服务器的程序可用) |
ShowAsDS4 |
false |
暴露为 DualShock 4 手柄(需配合 ShowAsXInput=false) |
ChangeOrientationDoubleClick |
true |
双击摇杆(L3/R3)切换 Joy-Con 方向 |
DoNotRejoinJoycons |
false |
拆分后不自动重新配对(允许双摇杆后转竖握模式) |
DebugType |
0 |
调试输出级别:0 无 / 1 全部 / 2 通信 / 3 线程 / 4 IMU / 5 震动 / 6 摇动输入 |
5.3 陀螺仪控制鼠标/摇杆的实际效果
当 GyroToJoyOrMouse 设为 mouse 时,Joycon.cs 会按滤波后的欧拉角增量计算 dx/dy 并调用 WindowsInput.Simulate.Events().MoveBy(dx, dy) 移动鼠标;按下 reset_mouse 绑定的按键则把指针重置回主屏中央。设为 joy_left/joy_right 时,陀螺仪偏航(yaw)/俯仰(pitch)会叠加到对应摇杆上,并受 GyroStickReduction 缩减量程、由 active_gyro 绑定的按键决定是否激活。
六、工作原理:源码级剖析
6.1 设备枚举与自动连接
Program.cs 中的 CheckForNewControllers() 是核心入口:
- 通过
HIDapi.hid_enumerate枚举全部 HID 设备,与内置 VID/PID(0x57e+0x2006/0x2007/0x2009/0x2017)匹配,或与用户自定义的第三方设备匹配; - 命中后打开设备路径、设为非阻塞读取,创建
Joycon对象并分配 PadId; - 自动配对:新接入左右 Joy-Con 会自动"合体"为一只手柄(
temp.other = v),两个虚拟手柄输出会被断开重建,图标同步更新; - 每 2 秒扫描一次并清理掉线(
DROPPED)的控制器(Program.cs); - 已连接手柄若处于
NOT_ATTACHED状态,会立即连接 ViGEm 输出、点亮 Home LED 并启动数据轮询线程。
6.2 XInput / DS4 虚拟输出
每个 Joycon 在构造时根据 ShowAsXInput / ShowAsDS4 创建 OutputControllerXbox360 或 OutputControllerDualShock4 实例。Xbox 输出实现将按键/摇杆/扳机逐项写入 ViGEm 虚拟手柄并提交报告,且做了状态去重——状态无变化时跳过 SubmitReport(IsEqual 比较,见 OutputControllerXbox360.cs)。震动反馈则通过 FeedbackReceived 事件回传,经 Joycon.cs 的 HD 震动编码(低频/高频频率与振幅编码)下发到手柄。
6.3 DSU 协议:Cemuhook 的运动与按键数据通道
UpdServer.cs 实现了一个兼容 Cemuhook 的 DSU(DualShock U)UDP 服务器,默认监听 127.0.0.1:26760。它支持四类报文:
DSUC_VersionReq→ 返回协议版本(MaxProtocolVersion = 1001);DSUC_ListPorts→ 返回各 PadId 的 MAC 地址、连接状态、型号、电量;DSUC_PadDataReq→ 客户端注册感兴趣的手柄(按 PadId 或 MAC 地址);- 主动推送
DSUS_PadDataRsp→ 将按键、摇杆、扳机、加速度计、陀螺仪与时间戳打包(含 CRC32 校验)推送给在 5 秒内活跃的客户端。
数据方向转换上,服务器先把 Joycon 报告映射为 DS4 输入(MapToDualShock4Input),再按 DSU 布局填充报文(UpdServer.cs)。这正是 Cemuhook 能"看到"手柄并获得体感数据的原因。
6.4 第三方控制器支持
通过 3rdPartyControllers.cs 窗体,用户可以枚举系统里任意 HID 设备,将其"伪装"成 Pro 手柄/左 Joy-Con/右 Joy-Con 之一(type 字段:1=Pro、2=左、3=右),配置以 名称|VID|PID|类型|序列号 格式存入可执行文件同目录的 3rdPartyControllers 文件。之后 CheckForNewControllers() 在枚举时会按 VID/PID/序列号识别这些自定义设备。
6.5 IMU 数据与姿态滤波
手柄原始加速度/角速度经 GetAccel()/GetGyro() 读取后,由 MadgwickAHRS.cs(开源 Madgwick 算法实现,采样周期 5ms、增益由 AHRS_beta 控制)融合为欧拉角(cur_rotation),供陀螺仪鼠标/摇杆、GyroAnalogSliders 等功能使用。AllowCalibration 开启后,主界面 MainForm.cs 会引导用户将手柄平放、倒计时采集 3 秒陀螺仪/加速度数据并取中位数,按序列号存入 settings 文件的自定义校准区。
七、从源码构建 BetterJoy
README 提供两条构建路线,均以 BetterJoy.sln 为主入口。工程目标框架为 .NET Framework 4.6.1,依赖 NuGet 包(见 packages.config:Crc32.NET 1.2.0、JetBrains.Annotations 2020.1.0、Nefarius.ViGEm.Client 1.17.178、WindowsInput 6.3.0)。
路线一:Visual Studio(IDE)
- 安装 Visual Studio Community 2019(官方安装指南),工作负载务必勾选 .NET Desktop Development(.NET 桌面开发);
- 通过 Git 克隆本仓库(
git clone仓库地址),或直接下载 ZIP 解压; - 打开解决方案文件 BetterJoy.sln;
- 进入 Tools > NuGet Package Manager > Package Manager Settings(工具 → NuGet 包管理器 → 包管理器设置);
- 出现"还原程序包"提示时点击 Restore(还原) 按钮恢复 NuGet 依赖;
- 现在即可直接运行和构建 BetterJoy。
路线二:Visual Studio Build Tools(命令行)
- 下载安装 Visual Studio Build Tools;
- 按官方指南安装 nuget.exe CLI,并在终端验证
nuget命令可用; - 获取源码(Git 克隆或下载 ZIP);
- 打开终端(cmd、PowerShell 等),进入源码目录;
- 还原依赖:
nuget restore - 用 MSBuild 构建:
msbuild .\BetterJoy.sln -p:Configuration=CONFIGURATION -p:Platform=PLATFORM -t:Rebuild- CONFIGURATION 可选
Release或Debug; - PLATFORM 可选
x86或x64——README 明确建议 99.99% 的情况下选x64。
- CONFIGURATION 可选
构建产物位置
构建完成后,二进制文件位于:
BetterJoyForCemu\bin\PLATFORM\CONFIGURATION
其中 PLATFORM 与 CONFIGURATION 对应构建时传入的值(例如 bin\x64\Release)。工程会将 ViGEmBus 安装包、HIDGuardian 脚本、hidapi.dll(按架构自动选 x64/x86,见 Program.cs)等随构建一并复制到输出目录。
八、常见问题与排查提示
- 提示 "Could not start VigemBus":ViGEmBus 驱动未安装或未重启,重新执行 ViGEmBusSetup_x64.msi 并重启;
- "Unable to open path to device":程序提示检查是否使用了与系统位数匹配(64 位 vs 32 位)的版本(Program.cs);
- 键盘/鼠标按键映射不生效:以管理员身份运行程序;
- 启动 UDP 服务器失败:通常是因为已运行了另一个 BetterJoy 实例或其他占用 26760 端口的 Cemuhook 程序(UpdServer.cs);
- 退出后手柄"失灵":可在
App.config打开PurgeAffectedDevices与UseHIDG,或参考 Windows 10 移除设备流程手动清理; - Joy-Con 竖握/方向问题:默认双击摇杆可切换方向;
DoNotRejoinJoycons=true可让拆分后不再自动合体,配合图标点击实现竖握模式。
九、项目致谢
BetterJoy 在 README 中向以下项目与作者致谢:DSU UDP 服务器实现参考了 rajkosto 的 ScpToolkit;Joy-Con 通信代码源自 Looking-Glass 的 JoyconLib;虚拟手柄驱动来自 nefarius 的 ViGEm 项目;SPI 校准数据与 IMU 传感器资料参考了 dekuNukem 的 Nintendo Switch 逆向工程文档;图标分别由 Chad Remsing、Mark Davis 创作并由 Amy Alexander 修改。作者也在个人说明中提到,该项目在其 GitHub 上累计获得近 59 万次官方下载,并对其职业发展帮助良多。
至此,你已掌握 BetterJoy 从安装、连接、配置到源码构建与原理剖析的全部要点。若需获取最新发行版本,请关注项目仓库的 Releases 页面;更多细节(更新日志、设置说明、FAQ 与问题页、Steam 适配技巧)可查阅项目 wiki。
