feat(input): update libvirtualhid integration (#5563)

Author: ReenigneArcher

.github/workflows/ci-archlinux.yml

@@ -149,6 +149,15 @@ jobs:
             _support_headless_testing="${_support_headless_testing}" \
             makepkg -si --noconfirm
 
+          # Native packages must install the host rule used by dynamically
+          # created libvirtualhid hidraw and input event nodes.
+          test -f /usr/lib/udev/rules.d/60-sunshine.rules
+          grep -Fq 'IMPORT{parent}="HID_*"' \
+            /usr/lib/udev/rules.d/60-sunshine.rules
+          grep -Fq 'ENV{HID_PHYS}=="libvirtualhid/uhid/*"' \
+            /usr/lib/udev/rules.d/60-sunshine.rules
+          udevadm verify /usr/lib/udev/rules.d/60-sunshine.rules
+
           # Remove debug package
           rm -f sunshine-debug*.pkg.tar.zst
 

.github/workflows/ci-linux.yml

@@ -103,6 +103,11 @@ jobs:
         run: |
           # install sunshine to the DESTDIR
           DESTDIR=AppDir ninja install
+          test -f AppDir/usr/share/sunshine/udev/rules.d/60-sunshine.rules
+          grep -Fq 'IMPORT{parent}="HID_*"' \
+            AppDir/usr/share/sunshine/udev/rules.d/60-sunshine.rules
+          grep -Fq 'ENV{HID_PHYS}=="libvirtualhid/uhid/*"' \
+            AppDir/usr/share/sunshine/udev/rules.d/60-sunshine.rules
 
           # custom AppRun file
           cp -f ../packaging/linux/AppImage/AppRun ./AppDir/

.github/workflows/ci-macos.yml

@@ -58,9 +58,11 @@ jobs:
           - os: "macos-14"
             name: "macOS-arm64"
             arch: "arm64"
+            build_docs: "ON"
           - os: "macos-15-intel"
             name: "macOS-x86_64"
             arch: "x86_64"
+            build_docs: "OFF"
     steps:
       - name: Install Apple certificate
         uses: apple-actions/import-codesign-certs@5142e029c445c10ffc7149d172e540235a065466  # v7.0.0
@@ -121,6 +123,7 @@ jobs:
           cmake \
             -B build \
             -S . \
+            -DBUILD_DOCS="${{ matrix.build_docs }}" \
             -DBUILD_WERROR=ON \
             -DCMAKE_BUILD_TYPE=Release \
             -DICU_ROOT="$(brew --prefix icu4c@78 2>/dev/null)" \

cmake/packaging/linux.cmake

@@ -30,9 +30,15 @@ else()
     find_package(Udev)
 
     if(UDEV_FOUND)
-        install(FILES "${SUNSHINE_SOURCE_ASSETS_DIR}/linux/misc/60-sunshine.rules"
-                DESTINATION "${UDEV_RULES_INSTALL_DIR}")
+        set(SUNSHINE_UDEV_RULES_INSTALL_DIR "${UDEV_RULES_INSTALL_DIR}")
+    else()
+        set(SUNSHINE_UDEV_RULES_INSTALL_DIR "${CMAKE_INSTALL_LIBDIR}/udev/rules.d")
+        message(WARNING
+                "Could not determine the host udev rules directory; "
+                "installing Sunshine rules to ${SUNSHINE_UDEV_RULES_INSTALL_DIR}")
     endif()
+    install(FILES "${SUNSHINE_SOURCE_ASSETS_DIR}/linux/misc/60-sunshine.rules"
+            DESTINATION "${SUNSHINE_UDEV_RULES_INSTALL_DIR}")
     if(SYSTEMD_FOUND)
         install(FILES "${CMAKE_CURRENT_BINARY_DIR}/app-${PROJECT_FQDN}.service"
                 DESTINATION "${SYSTEMD_USER_UNIT_INSTALL_DIR}")

docs/getting_started.md

@@ -265,6 +265,9 @@ flatpak install --user ./sunshine_{arch}.flatpak
 ```
 
 ##### Additional installation (required)
+Run this command after installing or updating the Flatpak so the privileged host
+udev rules stay synchronized with Sunshine:
+
 ```bash
 flatpak run --command=additional-install.sh dev.lizardbyte.app.Sunshine
 ```
@@ -293,6 +296,7 @@ brew update
 brew upgrade
 brew tap LizardByte/homebrew
 brew install sunshine
+sudo "$(brew --prefix sunshine)/bin/postinst"
 ```
 
 ##### Uninstall
@@ -476,10 +480,10 @@ and enter its device name in the [audio_sink](configuration.md#audio_sink) field
 ### Windows
 Sunshine uses libvirtualhid for virtual input on Windows. You must install the
 [Virtual HID Driver](https://github.com/LizardByte/libvirtualhid/releases/latest) separately for a driver-backed Raw
-Input mouse and full virtual gamepad support. ViGEmBus is detected only as a limited fallback for Xbox 360 and
-DualShock 4 gamepads when libvirtualhid is unavailable.
+Input keyboard and mouse plus full virtual gamepad support. ViGEmBus is detected only as a limited fallback for Xbox
+360 and DualShock 4 gamepads when libvirtualhid is unavailable.
 
-Sunshine requires Virtual HID Driver version `2026.823.352.3` or newer. Earlier releases use incompatible Windows
+Sunshine requires Virtual HID Driver version `2026.829.2338.54` or newer. Earlier releases use incompatible Windows
 control and broker protocols and must be upgraded together with Sunshine's embedded libvirtualhid library. Local
 development driver builds using a `0.0.0.*` version remain supported.
 
@@ -488,15 +492,21 @@ Pro, and Generic gamepads in addition to Xbox 360 and DualShock 4. It can also e
 as motion, touchpads, LEDs, and adaptive triggers when supported. Virtual HID Driver is actively developed and
 supported by the LizardByte team.
 
-With a compatible driver and active license, relative mouse movement, buttons, and scrolling are exposed as a real HID
+With a compatible driver and active license, normal key transitions are exposed through a real HID keyboard so
+applications using Raw Input can receive them. Unicode text input and keys outside the supported HID keyboard page
+continue to use Windows input injection. When the driver-backed keyboard cannot be created because the driver,
+broker, or license is unavailable, libvirtualhid retains its legacy SendInput fallback.
+
+Relative mouse movement, buttons, and scrolling are exposed as a real HID
 mouse so applications using Raw Input can receive them. Absolute mouse positioning continues to use Windows input
 injection. When the driver-backed mouse cannot be created, libvirtualhid retains its legacy SendInput fallback.
 
 The Virtual HID Driver requires an active machine license for driver-backed devices, including gamepads and the Raw
-Input mouse. Sunshine shows the current license status and actions on the Web UI Troubleshooting page and in the
-**Virtual HID Driver** system tray submenu. When Sunshine starts on an unactivated machine, select its tray notification
-to open the activation and purchase options in the Web UI. Sunshine recreates the shared mouse after a successful
-license action, so switching between the HID and SendInput paths does not require restarting Sunshine.
+Input keyboard and mouse. Sunshine shows the current license status and actions on the Web UI Troubleshooting page and
+in the **Virtual HID Driver** system tray submenu. When Sunshine starts on an unactivated machine, select its tray
+notification to open the activation and purchase options in the Web UI. Sunshine recreates the shared keyboard and
+mouse after a successful license action, so switching between the HID and SendInput paths does not require restarting
+Sunshine.
 
 After installing or updating virtual input drivers, it is recommended to restart your computer.
 

docs/troubleshooting.md

@@ -188,6 +188,18 @@ flatpak permission-set kde-authorized remote-desktop dev.lizardbyte.app.Sunshine
 After installation, the `udev` rules need to be reloaded. Our post-install script tries to do this for you
 automatically, but if it fails, you may need to restart your system.
 
+Sunshine recreates virtual gamepad device nodes for each streaming session. Manual `chmod` or `setfacl`
+changes therefore disappear when the client reconnects. Confirm that the installed Sunshine rule contains the
+parent-property import and `libvirtualhid/uhid/*` match, then reload it and reapply it to existing gamepad nodes:
+
+```bash
+grep -R -E 'IMPORT\{parent\}="HID_\*"|ENV\{HID_PHYS\}=="libvirtualhid/uhid/\*"' \
+  /etc/udev/rules.d /usr/lib/udev/rules.d /lib/udev/rules.d 2>/dev/null
+sudo udevadm control --reload-rules
+sudo udevadm trigger --subsystem-match=hidraw
+sudo udevadm trigger --subsystem-match=input
+```
+
 If the input is still not working, you may need to add your user to the `input` group.
 
 ```bash
@@ -292,11 +304,11 @@ launchctl load -w /Library/LaunchAgents/org.freedesktop.dbus-session.plist
 ### No gamepad detected
 Sunshine uses libvirtualhid for virtual input on Windows. Install the
 [Virtual HID Driver](https://github.com/LizardByte/libvirtualhid/releases/latest) separately for a driver-backed Raw
-Input mouse and full virtual gamepad support. ViGEmBus is detected only as a limited fallback for Xbox 360 and
-DualShock 4 gamepads when libvirtualhid is unavailable. If you use the
+Input keyboard and mouse plus full virtual gamepad support. ViGEmBus is detected only as a limited fallback for Xbox
+360 and DualShock 4 gamepads when libvirtualhid is unavailable. If you use the
 [ViGEmBus fallback](https://github.com/nefarius/ViGEmBus/releases/latest), you must use version 1.17 or newer.
 
-Sunshine requires Virtual HID Driver version `2026.823.352.3` or newer. Earlier releases use incompatible Windows
+Sunshine requires Virtual HID Driver version `2026.829.2338.54` or newer. Earlier releases use incompatible Windows
 control and broker protocols. The Troubleshooting page reports an older installed package as unsupported and links
 to the current driver release. Local development driver builds using a `0.0.0.*` version remain supported.
 
@@ -305,21 +317,31 @@ controller features such as motion, touchpads, LEDs, and adaptive triggers when
 ViGEmBus project, Virtual HID Driver is actively developed and supported by the LizardByte team.
 
 An active Virtual HID Driver machine license is required before Sunshine can create driver-backed libvirtualhid
-devices, including gamepads and the Raw Input mouse. Follow the warning on the Web UI home page, the startup tray
-notification, or the **Virtual HID Driver** tray submenu to open the license section on the Troubleshooting page, where
-you can activate a key or follow the purchase link.
+devices, including gamepads and the Raw Input keyboard and mouse. Follow the warning on the Web UI home page, the
+startup tray notification, or the **Virtual HID Driver** tray submenu to open the license section on the
+Troubleshooting page, where you can activate a key or follow the purchase link.
 
 After installation, it is recommended to restart your computer.
 
+### Games do not detect keyboard input
+With a compatible Virtual HID Driver and active license, Sunshine sends normal key transitions through a real HID
+keyboard so games using Raw Input can receive them. Unicode text input and keys outside the supported HID keyboard
+page continue to use Windows input injection. When the driver-backed keyboard cannot be created because the driver,
+broker, or license is unavailable, libvirtualhid falls back to SendInput.
+
+Check the Virtual HID Driver version and license sections on the Web UI Troubleshooting page. Sunshine recreates the
+shared keyboard and mouse after a successful license activation, validation, or deactivation, so you do not need to
+restart Sunshine merely to switch between the HID and SendInput paths.
+
 ### Games do not detect mouse input
 With a compatible Virtual HID Driver and active license, Sunshine sends relative mouse movement, buttons, and scrolling
 through a real HID device so games using Raw Input can receive them. Absolute positioning still uses Windows input
 injection. When the driver-backed mouse cannot be created, libvirtualhid falls back to SendInput; the Windows cursor may
 still move even though a game that listens only for Raw Input receives nothing.
 
 Check the Virtual HID Driver version and license sections on the Web UI Troubleshooting page even when controller input
-is disabled. Sunshine recreates the shared mouse after a successful license activation, validation, or deactivation, so
-you do not need to restart Sunshine merely to switch between the HID and SendInput paths.
+is disabled. The same live refresh used by the keyboard path also switches the mouse between HID and SendInput without
+requiring a Sunshine restart.
 
 ### Permission denied
 Since Sunshine runs as a service on Windows, it may not have the same level of access that your regular user account

packaging/linux/AppImage/AppRun

@@ -28,7 +28,7 @@ echo "
  ------            # This message
 
          $ARGV0  --install, -i
-                   # Install input rules sunshine.service files. Restart required.
+                   # Install or update input rules and sunshine.service files.
 
          $ARGV0  --remove, -r
                    # Remove input rules sunshine.service files.
@@ -52,6 +52,8 @@ function install() {
   sudo udevadm control --reload-rules
   sudo udevadm trigger --property-match=DEVNAME=/dev/uinput
   sudo udevadm trigger --property-match=DEVNAME=/dev/uhid
+  sudo udevadm trigger --subsystem-match=hidraw
+  sudo udevadm trigger --subsystem-match=input
 
   # sunshine service
   mkdir -p ~/.config/systemd/user
@@ -66,6 +68,7 @@ function install() {
 function remove() {
   # remove input rules
   sudo rm -f /etc/udev/rules.d/60-sunshine.rules
+  sudo udevadm control --reload-rules
 
   # remove uhid module loading config
   sudo rm -f /etc/modules-load.d/60-sunshine.conf

packaging/linux/Arch/sunshine.install

@@ -1,11 +1,15 @@
+# shellcheck shell=bash
+
 do_setcap() {
-  setcap cap_sys_admin,cap_sys_nice+p $(readlink -f usr/bin/sunshine)
+  setcap cap_sys_admin,cap_sys_nice+p "$(readlink -f usr/bin/sunshine)"
 }
 
 do_udev_reload() {
   udevadm control --reload-rules
   udevadm trigger --property-match=DEVNAME=/dev/uinput
   udevadm trigger --property-match=DEVNAME=/dev/uhid
+  udevadm trigger --subsystem-match=hidraw
+  udevadm trigger --subsystem-match=input
   modprobe uinput || true
   modprobe uhid || true
 }

packaging/linux/copr/Sunshine.spec

@@ -414,21 +414,23 @@ cd %{_builddir}/Sunshine/build
 %post
 # Note: this is copied from the postinst script
 
-# Load uhid (DS5 emulation)
-echo "Loading uhid kernel module for DS5 emulation."
+# Load uhid for descriptor-driven gamepad emulation
+echo "Loading uhid kernel module for gamepad emulation."
 modprobe uhid
 
 # Check if we're in an rpm-ostree environment
 if [ ! -x "$(command -v rpm-ostree)" ]; then
   echo "Not in an rpm-ostree environment, proceeding with post install steps."
 
-  # Trigger udev rule reload for /dev/uinput and /dev/uhid
+  # Reload the rules and reapply them to virtual gamepad child nodes.
   path_to_udevadm=$(which udevadm)
   if [ -x "$path_to_udevadm" ]; then
     echo "Reloading udev rules."
     $path_to_udevadm control --reload-rules
     $path_to_udevadm trigger --property-match=DEVNAME=/dev/uinput
     $path_to_udevadm trigger --property-match=DEVNAME=/dev/uhid
+    $path_to_udevadm trigger --subsystem-match=hidraw
+    $path_to_udevadm trigger --subsystem-match=input
     echo "Udev rules reloaded successfully."
   else
     echo "error: udevadm not found or not executable."

packaging/linux/flatpak/scripts/additional-install.sh

@@ -6,14 +6,19 @@ cp "/app/share/sunshine/systemd/user/app-dev.lizardbyte.app.Sunshine.service" "$
 echo "Sunshine User Service has been installed."
 echo "Use [systemctl --user enable app-dev.lizardbyte.app.Sunshine] once to autostart Sunshine on login."
 
-# Load uhid (DS5 emulation)
+# Load uhid for descriptor-driven gamepad emulation
 UHID=$(cat /app/share/sunshine/modules-load.d/60-sunshine.conf)
-echo "Enabling DS5 emulation."
+echo "Enabling gamepad emulation."
 flatpak-spawn --host pkexec sh -c "echo '$UHID' > /etc/modules-load.d/60-sunshine.conf"
 flatpak-spawn --host pkexec modprobe uhid
 
 # Udev rule
 UDEV=$(cat /app/share/sunshine/udev/rules.d/60-sunshine.rules)
-echo "Configuring mouse permission."
+echo "Configuring virtual input permissions."
 flatpak-spawn --host pkexec sh -c "echo '$UDEV' > /etc/udev/rules.d/60-sunshine.rules"
-echo "Restart computer for mouse permission to take effect."
+flatpak-spawn --host pkexec udevadm control --reload-rules
+flatpak-spawn --host pkexec udevadm trigger --property-match=DEVNAME=/dev/uinput
+flatpak-spawn --host pkexec udevadm trigger --property-match=DEVNAME=/dev/uhid
+flatpak-spawn --host pkexec udevadm trigger --subsystem-match=hidraw
+flatpak-spawn --host pkexec udevadm trigger --subsystem-match=input
+echo "Virtual input permissions have been updated."