BetterJoy v7.0 使用与构建完全指南:让 Switch Pro 手柄、Joy-Con 与 SNES 手柄畅玩 PC 模拟器

原创2026-10-14 13:20:542,247 阅读
文章标签:桌面应用驱动开发游戏开发

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 v7.0 项目横幅标题图

一、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 明确列出):

  1. 用陀螺仪控制鼠标——手持 Pro 手柄或 Joy-Con 摆动即可移动系统鼠标指针;
  2. 重映射特殊按键——将 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"。

  1. 阅读 BetterJoyForCemu/Drivers/README.txt 了解驱动说明;
  2. 运行 ViGEmBusSetup_x64.msi(64 位系统)或 ViGEmBusSetup_x86.msi(32 位系统)安装 ViGEmBus 虚拟手柄总线驱动;
  3. 重启计算机。

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 配置步骤如下:

  1. 启动 Cemu,确保 Cemuhook 已选中 BetterJoy 提供的控制器;
  2. 若使用 Joy-Con:Cemuhook 会检测到两个控制器,每个都能给出全部按键,但选择哪一个决定陀螺仪体感使用哪只手——按你惯用手偏好选择即可;
  3. 进入 Cemu 的 Input Settings(输入设置),将输入源选为 XInput,按常规方式为按键/摇杆指派映射;
  4. 若不想逐一指派按键:可建立一份以 Wii U Gamepad 为控制器的输入配置,并在 GamePad motion source(GamePad 体感源)下勾选 "Also use for buttons/axes"(同时用于按键/摇杆)。注意:README 注明自版本 3 起这不再是必需步骤;
  5. 想要震动反馈的话,将 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 提供了手动移除方法:

  1. 打开"蓝牙和其他设备设置"(Bluetooth and other devices settings);
  2. 在第一个分类"鼠标、键盘和笔"(Mouse, keyboard, & pen)下找到 Pro 手柄;
  3. 点击它,会浮现"Remove(移除)"按钮;
  4. 点击"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() 是核心入口:

  1. 通过 HIDapi.hid_enumerate 枚举全部 HID 设备,与内置 VID/PID(0x57e + 0x2006/0x2007/0x2009/0x2017)匹配,或与用户自定义的第三方设备匹配;
  2. 命中后打开设备路径、设为非阻塞读取,创建 Joycon 对象并分配 PadId;
  3. 自动配对:新接入左右 Joy-Con 会自动"合体"为一只手柄(temp.other = v),两个虚拟手柄输出会被断开重建,图标同步更新;
  4. 每 2 秒扫描一次并清理掉线(DROPPED)的控制器(Program.cs);
  5. 已连接手柄若处于 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)

  1. 安装 Visual Studio Community 2019(官方安装指南),工作负载务必勾选 .NET Desktop Development(.NET 桌面开发);
  2. 通过 Git 克隆本仓库(git clone 仓库地址),或直接下载 ZIP 解压;
  3. 打开解决方案文件 BetterJoy.sln;
  4. 进入 Tools > NuGet Package Manager > Package Manager Settings(工具 → NuGet 包管理器 → 包管理器设置);
  5. 出现"还原程序包"提示时点击 Restore(还原) 按钮恢复 NuGet 依赖;
  6. 现在即可直接运行和构建 BetterJoy。

路线二:Visual Studio Build Tools(命令行)

  1. 下载安装 Visual Studio Build Tools;
  2. 按官方指南安装 nuget.exe CLI,并在终端验证 nuget 命令可用;
  3. 获取源码(Git 克隆或下载 ZIP);
  4. 打开终端(cmd、PowerShell 等),进入源码目录;
  5. 还原依赖:
    nuget restore
    
  6. 用 MSBuild 构建:
    msbuild .\BetterJoy.sln -p:Configuration=CONFIGURATION -p:Platform=PLATFORM -t:Rebuild
    
    • CONFIGURATION 可选 Release 或 Debug;
    • PLATFORM 可选 x86 或 x64——README 明确建议 99.99% 的情况下选 x64。

构建产物位置

构建完成后,二进制文件位于:

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。

登录后查看全文
BetterJoy