桌面应用【免费下载链接】BetterJoyAllows the Nintendo Switch Pro Controller, Joycons and SNES controller to be used with CEMU, Citra, Dolphin, Yuzu and as generic XInput项目地址https://gitcode.com/gh_mirrors/be/BetterJoy点击查看免费下载本篇指南以 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 ControllerSwitch Pro 手柄Joy-Con左右两只可单独使用或合并使用Switch SNES 手柄其输出目标覆盖主流 PC 模拟器与通用输入体系输出目标说明Cemu配合 Cemuhook通过 DSU 协议获得手柄输入与陀螺仪体感Citra3DS 模拟器DolphinWii/GameCube 模拟器YuzuSwitch 模拟器通用 XInput作为标准 Xbox 360 手柄呈现在系统级可被 Steam 等任意 XInput 程序识别除按键与摇杆输入外BetterJoy 还提供两项颇具特色的附加能力README 明确列出用陀螺仪控制鼠标——手持 Pro 手柄或 Joy-Con 摆动即可移动系统鼠标指针重映射特殊按键——将 SL、SR、Capture截图键等原本难以利用的按键映射为任意键位。从源码角度看BetterJoy 通过 HID 直连方式识别任天堂官方设备。在 Program.cs 中定义了内置设备的 Vendor ID 与 Product IDprivate 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.slnVisual Studio 解决方案文件BetterJoyForCemu/BetterJoy.csproj工程文件目标框架 .NET Framework 4.6.1BetterJoyForCemu/Program.cs程序入口、设备枚举管理JoyconManager、全局钩子BetterJoyForCemu/Joycon.cs单只手柄的对象模型按键解析、摇杆校准、IMU、震动、输出BetterJoyForCemu/UpdServer.csDSU 协议CemuhookUDP 服务器实现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.msi64 位系统或 ViGEmBusSetup_x86.msi32 位系统安装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 / CemuhookREADME 给出的 Cemu 配置步骤如下启动 Cemu确保 Cemuhook 已选中 BetterJoy 提供的控制器若使用Joy-ConCemuhook 会检测到两个控制器每个都能给出全部按键但选择哪一个决定陀螺仪体感使用哪只手——按你惯用手偏好选择即可进入 Cemu 的Input Settings输入设置将输入源选为XInput按常规方式为按键/摇杆指派映射若不想逐一指派按键可建立一份以Wii U Gamepad为控制器的输入配置并在GamePad motion sourceGamePad 体感源下勾选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 连接的手柄序列号固定为000000000001Joycon.cs 据此判定连接类型connection isUSB ? 0x01 : 0x02UDP 服务器会将该信息上报给模拟器。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()决定键名默认值含义ProgressiveScan1是否持续扫描新控制器1 开启 / 0 关闭StartInTray0是否启动时最小化到托盘capturekey_PrintScreenCapture 键映射key_前缀 键盘键joy_前缀 手柄按键mse_前缀 鼠标键home0Home 键映射sl_l/sl_r0左/右 Joy-Con 的 SL 键映射sr_l/sr_r0左/右 Joy-Con 的 SR 键映射shake0摇动输入映射reset_mousejoy_10即摇杆按下 STICK将鼠标指针重置到主屏中央的触发键active_gyro0陀螺仪激活键按住启用 / 切换启用配合GyroHoldToggle映射值支持key_虚拟键码、joy_手柄按键枚举值、mse_鼠标键值三种前缀。主界面通过 Reassign.cs 窗体提供图形化修改入口reset_mouse、active_gyro还能绑定鼠标按键Program.cs 中注册的全局鼠标/键盘事件钩子会在按下这些键时触发重置鼠标指针/激活陀螺仪动作。5.2 App.config全量参数说明App.config 是 BetterJoy 最重要的调参入口按功能分组整理如下默认值以仓库文件为准运动服务器Cemuhook UDP参数默认值说明IP127.0.0.1运动服务器监听地址改0.0.0.0或局域网 IP 可让其他电脑访问Port26760监听端口若冲突需同步修改 PadTest 与cemuhook.iniMotionServertrue是否启用运动服务器false 则纯 XInput 使用震动参数默认值说明LowFreqRumble40HD 震动低频建议不超过约 1200HighFreqRumble120HD 震动高频同上EnableRumbletrue总开关EnableShakeInputfalse摇动手柄触发输入目前仅 DS4 输出生效占用 DirectInput 的 Button 13ShakeInputSensitivity10摇动检测灵敏度ShakeInputDelay200摇动检测间隔毫秒不要低于 15想获得更强的震动README 注释建议将低频/高频设为160/320。按键布局参数默认值说明SwapABfalse交换 A/B按名称而非物理位置模拟 Xbox 布局SwapXYfalse交换 X/Y同上校准参数默认值说明AllowCalibrationfalse启用主界面Calibrate按钮做陀螺仪校准一次只能校一只手柄acc_sensiti/gyr_sensiti16384,16384,16384/18642,18642,18642加速度计/陀螺仪灵敏度默认校准值第三方手柄使用stick_cal/stick2_cal0x780,...摇杆校准数据deadzone/deadzone2200摇杆死区StickScalingFactor/StickScalingFactor21.00摇杆坐标缩放推不满摇杆时调大陀螺仪鼠标/摇杆参数默认值说明GyroAnalogSlidersfalse用陀螺仪倾斜模拟大扳机类拟滑块值Pro 手柄合并扳机双 Joy-Con 各自倾斜GyroAnalogSensitivity400倾斜灵敏度改 -400 可反转倾斜方向GyroToJoyOrMousefalse核心开关joy_left/joy_right把陀螺仪转为左/右摇杆mouse转为鼠标移动none关闭UseFilteredIMUtrue使用滤波后 IMU 数据false 用原始陀螺仪响应更快AHRS_beta0.05Madgwick AHRS 滤波器增益影响滤波发散GyroMouseSensitivityX/Y1200/800陀螺仪→鼠标灵敏度用原始值时需除以约 15GyroStickSensitivityX/Y40.0/10.0陀螺仪→摇杆灵敏度原始值约 2.6 / 0.6GyroStickReduction1.5激活陀螺仪摇杆时摇杆量程缩减系数1 不变1.5 约减半GyroHoldToggletruetrue 按住激活键才启用陀螺仪holdfalse 按一次切换toggleGyroMouseLeftHandedfalse双 Joy-Con 时默认取右 Joy-Con 陀螺仪驱动鼠标true 换为左手DragTogglefalse拖拽行为切换仅作用于被映射的鼠标键HIDGuardian可选隐藏驱动参数默认值说明UseHIDGfalse启用后将 Pro/Joy-Con 对其它程序隐藏防止退出时手柄卡死及部分程序的 DI/XI 冲突PurgeWhitelistfalse启动时清空 HIDGuardian 进程白名单PurgeAffectedDevicesfalse退出时清空受控设备列表HIDGuardian 已不再默认安装官方 Drivers/README.txt 说明它曾给用户带来困扰。只有当你知道自己在做什么例如在 Steam 大屏模式下同时使用 Pro 手柄 2 只 Joy-Con时才需要它相关安装脚本位于 BetterJoyForCemu/Drivers/HIDGuardian。LED 与电源管理参数默认值说明HomeLEDOntrueHome 键 LED 环形灯常亮UseIncrementalLightstrue用多颗 LED 显示当前玩家编号而非单颗AutoPowerOfffalse程序退出时自动关闭手柄电源PowerOffInactivity-1无操作多少分钟后自动关机-1 无限HomeLongPowerOfftrue长按 Home右侧/合并或 Capture仅左侧2 秒关机输出与调试参数默认值说明ShowAsXInputtrue将手柄暴露为 Xbox 360 手柄false 则仅支持 UDP 服务器的程序可用ShowAsDS4false暴露为 DualShock 4 手柄需配合ShowAsXInputfalseChangeOrientationDoubleClicktrue双击摇杆L3/R3切换 Joy-Con 方向DoNotRejoinJoyconsfalse拆分后不自动重新配对允许双摇杆后转竖握模式DebugType0调试输出级别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/PID0x57e0x2006/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 虚拟手柄并提交报告且做了状态去重——状态无变化时跳过SubmitReportIsEqual比较见 OutputControllerXbox360.cs。震动反馈则通过FeedbackReceived事件回传经 Joycon.cs 的 HD 震动编码低频/高频频率与振幅编码下发到手柄。6.3 DSU 协议Cemuhook 的运动与按键数据通道UpdServer.cs 实现了一个兼容 Cemuhook 的DSUDualShock UUDP 服务器默认监听127.0.0.1:26760。它支持四类报文DSUC_VersionReq→ 返回协议版本MaxProtocolVersion 1001DSUC_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字段1Pro、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文件的自定义校准区。七、从源码构建 BetterJoyREADME 提供两条构建路线均以BetterJoy.sln为主入口。工程目标框架为.NET Framework 4.6.1依赖 NuGet 包见 packages.configCrc32.NET 1.2.0、JetBrains.Annotations 2020.1.0、Nefarius.ViGEm.Client 1.17.178、WindowsInput 6.3.0。路线一Visual StudioIDE安装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.exeCLI并在终端验证nuget命令可用获取源码Git 克隆或下载 ZIP打开终端cmd、PowerShell 等进入源码目录还原依赖nuget restore用 MSBuild 构建msbuild .\BetterJoy.sln -p:ConfigurationCONFIGURATION -p:PlatformPLATFORM -t:RebuildCONFIGURATION可选Release或DebugPLATFORM可选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 VigemBusViGEmBus 驱动未安装或未重启重新执行 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 竖握/方向问题默认双击摇杆可切换方向DoNotRejoinJoyconstrue可让拆分后不再自动合体配合图标点击实现竖握模式。九、项目致谢BetterJoy 在 README 中向以下项目与作者致谢DSU UDP 服务器实现参考了 rajkosto 的 ScpToolkitJoy-Con 通信代码源自 Looking-Glass 的 JoyconLib虚拟手柄驱动来自 nefarius 的 ViGEm 项目SPI 校准数据与 IMU 传感器资料参考了 dekuNukem 的 Nintendo Switch 逆向工程文档图标分别由 Chad Remsing、Mark Davis 创作并由 Amy Alexander 修改。作者也在个人说明中提到该项目在其 GitHub 上累计获得近 59 万次官方下载并对其职业发展帮助良多。至此你已掌握 BetterJoy 从安装、连接、配置到源码构建与原理剖析的全部要点。若需获取最新发行版本请关注项目仓库的 Releases 页面更多细节更新日志、设置说明、FAQ 与问题页、Steam 适配技巧可查阅项目 wiki。赞分享桌面应用【免费下载链接】BetterJoyAllows the Nintendo Switch Pro Controller, Joycons and SNES controller to be used with CEMU, Citra, Dolphin, Yuzu and as generic XInput项目地址https://gitcode.com/gh_mirrors/be/BetterJoy点击查看免费下载相关推荐DS4Windows 完整指南在 PC 上用 Xbox 360 手柄模拟畅玩 DualShock 4、DualSense 与 Switch ProDS4Windows 完整指南在 PC 上用 Xbox 360 手柄模拟畅玩 DualShock 4、DualSense 与 Switch Pro DS4Wi游戏开发驱动开发BetterJoy完整使用指南让Switch手柄在PC上完美运行BetterJoy完整使用指南让Switch手柄在PC上完美运行 BetterJoy是一款专为任天堂Switch控制器设计的PC连接工具通过XInput协议桌面应用终极指南5分钟让Switch Joy-Con手柄在PC上完美运行终极指南5分钟让Switch Joy Con手柄在PC上完美运行 还在为Switch Joy Con手柄在PC上无法使用而烦恼吗JoyCon Driver开驱动开发硬件开发上一篇Hugging Face Transformers 安装和配置指南下一篇Reactor Core 实战指南JVM 非阻塞响应式编程基础库的入门与深入创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考