virtual_gamepad_linux

Linux 桌面上的虚拟手柄控制面板。

当前版本：0.4.0

功能

• 使用 SDL2 + Dear ImGui 显示 UI
• 通过 uinput 创建虚拟手柄
• 支持标准 Xbox 风格输入：
  • A/B/X/Y
  • LB/RB
  • Back/Start/Guide
  • LS/RS
  • 十字键
  • 双摇杆
  • 双扳机
• 支持摇杆锁定
• 支持全局 Hold Mode

依赖

• libsdl2-dev
• libimgui-dev
• cmake
• g++
• /dev/uinput 可访问

安装（推荐）

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j"$(nproc)"
cpack --config build/CPackConfig.cmake -B dist
sudo apt install ./dist/virtual-gamepad-linux_0.4.0_amd64.deb

安装后可以在任意目录直接启动：

virtual-gamepad

.deb 包会让 APT 自动处理运行时依赖，同时安装：

• virtual-gamepad 命令
• Bash、Zsh 和 Fish 参数补全
• uinput 自动加载配置
• 当前桌面用户访问 /dev/uinput 的 udev 规则

卸载：

sudo apt remove virtual-gamepad-linux

包名中的架构由当前构建机器决定，常见 x86-64 系统为 amd64。也可用 sudo apt install ./dist/*.deb 安装生成的包。

GitHub Release

推送与项目版本一致的标签会自动构建 amd64 .deb、生成 SHA-256 校验文件， 并发布到 GitHub Releases。例如当前版本：

git tag v0.4.0
git push origin v0.4.0

标签版本必须与 CMakeLists.txt 中的项目版本一致，否则工作流会停止发布。 也可以在 GitHub Actions 页面手动运行 Build and release Debian package； 手动运行只生成 Actions artifact，不创建 Release。

源码构建与直接运行

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j"$(nproc)"
./build/virtual-gamepad

运行不需要图形界面的命令行测试：

ctest --test-dir build --output-on-failure

命令行选项可通过 virtual-gamepad --help 查看。安装后输入 virtual-gamepad -- 再按 Tab 可补全参数；新安装补全后可能需要重新打开终端。

源码结构

• src/main.cpp：SDL、OpenGL 和 ImGui 生命周期及主事件循环
• src/cli.cpp：命令行参数解析和帮助文本
• src/controller_ui.cpp：控制面板状态、绘制与缩放设置
• src/virtual_gamepad.cpp：Linux uinput 虚拟手柄设备

UI 操作

• 使用系统窗口栏移动和关闭窗口；窗口默认置顶；底部工具栏的 - / + 按固定比例缩放窗口，最小 50%，并在下次启动恢复上次缩放。
• 状态屏顶部显示 STATUS、设备路径、fd 和 VID:PID 诊断信息。
• 如果虚拟手柄创建或写入失败，状态屏会显示红色 ERROR、errno 符号和完整原始错误文本。

缩放配置保存在 $XDG_CONFIG_HOME/virtual_gamepad_linux/settings.conf，未设置 XDG_CONFIG_HOME 时使用 ~/.config/virtual_gamepad_linux/settings.conf。

权限

如果安装 .deb 后仍提示无法打开 /dev/uinput，请重新登录桌面会话，让 uaccess 权限重新应用。不要使用 sudo 启动图形界面。

验证

可用 jstest 或 evtest 检查系统是否识别到虚拟手柄。