From eb5684342f838b97e3507d88c6e92dc54defacf9 Mon Sep 17 00:00:00 2001 From: Johnny D Date: Sun, 20 Sep 2026 04:47:38 -0400 Subject: [PATCH] Switch2Kit: streamline documentation and Qt source wiring Restore the upstream README and keep controller setup in Docs/Switch2Kit.md, without stale feature-branch instructions or fork-specific download URLs. Declare optional mapping sources once in the Qt target on every platform. Keep the Switch2Kit pin, feature defaults, runtime code, deployment steps, and regression suites unchanged. Prepared with AI assistance; human review and native application/hardware validation remain required. --- Docs/Switch2Kit.md | 277 +++++++++++++++------------ Readme.md | 80 +------- Source/Core/CMakeLists.txt | 5 - Source/Core/DolphinQt/CMakeLists.txt | 13 +- 4 files changed, 168 insertions(+), 207 deletions(-) diff --git a/Docs/Switch2Kit.md b/Docs/Switch2Kit.md index b866fe61e89b..49a754a8811e 100644 --- a/Docs/Switch2Kit.md +++ b/Docs/Switch2Kit.md @@ -1,172 +1,213 @@ -# Native Switch 2 controllers in Dolphin +# Native Switch 2 controllers -**This maintained Dolphin fork embeds [Switch2Kit](https://github.com/jmonster/Switch2Kit) for NSO GameCube and Nintendo Switch 2 Pro controllers on macOS 15+, with experimental Linux x86-64 and Windows x64 support.** +Dolphin's optional Switch2Kit backend connects NSO GameCube, Nintendo Switch 2 Pro +controllers and individual Joy-Con 2 halves through Bluetooth and SDL. It requires +a build with `ENABLE_SWITCH2KIT=ON`; the option is off by default. Enabled builds +require macOS 15 or newer, or the experimental Linux x86-64 / Windows x64 setup below. +No separate dashboard, network bridge, system-wide SDL override, virtual-controller +driver or Accessibility permission is needed. -Start with the [download, extraction and launch instructions](../Readme.md#quick-start), then [connect and select a port](#playing-a-gamecube-game) below. Ordinary upstream Dolphin binaries do not contain this integration. Installing the library alone does not modify other applications. No separate dashboard, network bridge, system-wide SDL override, virtual-controller driver or Accessibility permission is required. +## Playing a GameCube game -## Applications and prerequisites +In **Controllers**, find **Switch 2 Controllers**, click **Find Controllers**, allow +Bluetooth access and hold the controller's Sync button. Close other applications +managing the same controller. A manual search lasts 60 seconds; use Find again to retry. -Use this fork's successful **Native Switch2Kit** (macOS), **Switch2Kit Linux application** or **Switch2Kit Windows application** workflow on the implementation branch, not a source/diagnostics archive. GitHub artifact downloads require sign-in and expire (desktop application artifacts are retained for 14 days). An outer artifact ZIP contains the application ZIP or tarball. A configured job or earlier-revision pass is not proof that a particular download passed. These are development builds, not a published production release or a hardware-qualification claim. +Select **Switch2Kit GameCube** or **Switch2Kit Pro Controller 2** in the physical-device +dropdown beside the desired GameCube port. This selects **Standard Controller** and +applies the recommended buttons, sticks, triggers and rumble mapping. A device can be +assigned to only one active Standard Controller port through this shortcut; set its +old port to None before moving it. Verify the controls in **Configure**, then open a game. -### macOS +**Standard Controller** is the emulated device the game sees. The adjacent dropdown +selects the physical controller. Changing the emulated type does not start Bluetooth +discovery. These controllers do not use **GameCube Adapter for Wii U** mode. -Use macOS 15 or newer on Apple Silicon (`arm64`) or Intel (`x86_64`). Download the matching **Dolphin-Switch2Kit-arm64** or **Dolphin-Switch2Kit-x86_64** artifact from [Native Switch2Kit](https://github.com/jmonster/dolphin/actions/workflows/native-switch2kit.yml), extract both ZIP layers, move `DolphinQt.app` to Applications and open it normally. The app embeds its controller library and Swift runtime. Enable Bluetooth and permit Dolphin under **System Settings > Privacy & Security > Bluetooth** when requested. Ad-hoc signing is not notarization; use Apple's [per-app approval procedure](https://support.apple.com/en-us/102445) only for an application you trust. Do not turn off Gatekeeper globally. +In **Configure**, **Use Recommended Mapping** applies the preset to the selected +supported device. Changing that window's device selection, refreshing the list or +reconnecting does not overwrite bindings. Replacing custom settings requires confirmation +(Cancel is the default) and creates a uniquely named **Before Switch2Kit Port ...** +profile. Restore it with **Profile > Load**. A missing preset or failed backup leaves +the mapping intact. -### Linux +The GameCube preset preserves independent analog L/R travel and digital full clicks. +The Pro preset matches the printed A/B/X/Y labels; + is Start, R is GameCube Z, and +ZL/ZR supply on/off L/R. Pro triggers cannot reproduce a variable analog squeeze. -The development target is Ubuntu 24.04 x86-64 with a graphical desktop and working graphics/audio drivers. Other distributions and architectures have not been qualified by these application jobs. The package is an installed directory, not a universal AppImage. Install the normal distribution runtimes; on Ubuntu 24.04: +### Automatic connection and recovery -```sh -sudo apt-get update -sudo apt-get install bluez libsystemd0 libqt6widgets6t64 libqt6svg6 qt6-qpa-plugins libevdev2 libudev1 libusb-1.0-0 libasound2t64 libpulse0 libgl1 libegl1 -``` +**Automatically connect** starts listening now and saves the choice for future launches. +It is off by default: launching Dolphin with it off does not start Bluetooth or request +permission. With it on, discovery continues independently of emulation pause and the +settings window, without the manual search's 60-second limit. + +**Disconnect All** stops input and discovery for the current session, even when automatic +connection is checked. Polling, resuming a game and reopening settings cannot undo that +stop. Use Find or re-enable automatic connection to resume. The saved choice still applies +on the next launch. Unchecking automatic connection stops automatic discovery without +disconnecting ready controllers; a handshake already admitted may finish. + +Automatic discovery connects available supported controllers, not a saved allowlist. +It does not assign ports or replace mappings. It cannot wake a powered-off controller +or bypass Bluetooth access requirements, and continuous discovery uses radio resources. + +`Switch2Kit.ini` in Dolphin's user configuration directory stores `[Settings] AutoConnect` +and persistent physical-device numbers separately. Failed settings reads or saves do not +overwrite the existing configuration or change the runtime choice. Use Find to retry a +failed start after resolving the reported problem. Unreadable/unwritable configuration or +exhaustion of the 64 saved identity slots falls back to ordinary device numbering; verify +assignments in that case. Adapter or device-address changes can also affect identity on +Linux and Windows. Reconnecting two otherwise unchanged identical controllers in reverse +order retains their saved assignments. -Use the **Dolphin-Switch2Kit-linux-x86_64** application artifact from [the Linux workflow](https://github.com/jmonster/dolphin/actions/workflows/switch2kit-linux.yml). Extract the outer ZIP, then: +## Controller differences and motion -```sh -tar -xzf Dolphin-Switch2Kit-linux-x86_64.tar.gz -./Dolphin-Switch2Kit-linux-x86_64/bin/dolphin-emu -``` +Discover each Joy-Con 2 half with Find/Sync, then use the ordinary per-port **Configure** +window to bind its SDL buttons and axes manually. The quick port selector supports +GameCube and Pro controllers; the backend does not combine Joy-Con halves into a pair. -Keep `bin/Sys`, `lib` and `share/Switch2KitNotices` with the executable when relocating the directory. Swift runtime libraries are packaged; installing Swift or changing `LD_LIBRARY_PATH` is not a launch prerequisite. System libraries and graphics drivers are not bundled. +For Wii games, configure an **Emulated Wii Remote** separately. The GameCube-port shortcut +does not configure Wii motion, and this integration does not provide a calibrated-motion +setup UI. Selecting a controller or supplying a test calibration file is not motion setup. -Turn Bluetooth on in your desktop's Bluetooth settings. BlueZ must be running, the adapter must support Bluetooth LE, and your normal account must have system-bus/GATT access. `bluetoothctl show` can confirm the powered adapter. Dolphin does not change adapter power, install permissive D-Bus rules, erase bonds or invoke BlueZ Pair/RemoveDevice. Start discovery in Dolphin and hold Sync; the controller-protocol handshake is separate from OS pairing. Resolve access failures through your distribution's normal Bluetooth policy, not by running the emulator as root. +NSO GameCube rumble uses its Bluetooth on/off motor channel; Pro/Joy-Con use their +HD-rumble path. Verify actual motor behavior and that zero, disconnect and quit stop it. +An automated callback test is not a physical rumble test. -### Windows +## Applications and prerequisites -The experimental desktop target is Windows 11 x64, with a Bluetooth LE adapter/driver and graphics drivers. Native build/consumer jobs use Windows Server runners and are not evidence of physical Windows 11 pairing. ARM64 and 32-bit Windows are not covered. Install the [Microsoft Visual C++ x64 runtime](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist) when required by Windows or the application. +For development artifacts, open this repository's **Actions** tab and choose a successful +run for the revision being tested. The workflows and application artifacts are: -Download **Dolphin-Switch2Kit-windows-x86_64** from [the Windows application workflow](https://github.com/jmonster/dolphin/actions/workflows/switch2kit-windows.yml). Extract the outer ZIP and its inner `Dolphin-Switch2Kit-windows-x86_64.zip`. Open `Dolphin-Switch2Kit-windows-x86_64/Dolphin.exe`. Retain all DLLs, Qt plugins, `Sys` and `Switch2KitNotices`. The package stages the selected Swift runtime as well as `Switch2KitC.dll`; no Swift compiler installation or compiler-specific PATH is required to launch it. +| Platform | Workflow | Artifact | +| --- | --- | --- | +| macOS | [Native Switch2Kit](../.github/workflows/native-switch2kit.yml) | `Dolphin-Switch2Kit-arm64` or `Dolphin-Switch2Kit-x86_64` | +| Linux | [Switch2Kit Linux application](../.github/workflows/switch2kit-linux.yml) | `Dolphin-Switch2Kit-linux-x86_64` | +| Windows | [Switch2Kit Windows application](../.github/workflows/switch2kit-windows.yml) | `Dolphin-Switch2Kit-windows-x86_64` | -Enable **Settings > Bluetooth & devices > Bluetooth**, close competing controller applications, then use Dolphin's Find/Sync procedure below. Honor any legitimate system pairing/access prompt. The backend does not silently change pairing policy or erase device bonds. Run as a normal user. Do not disable SmartScreen, antivirus or Bluetooth security to bypass an error. A missing DLL before a window appears is a package/runtime prerequisite problem, not a pairing failure: re-extract the complete controller-enabled artifact and check that revision's native launch job. +GitHub artifact downloads require sign-in and expire. Extract the outer artifact ZIP and +then the application ZIP or tarball inside it. Source and diagnostics archives are not +applications. Check the build and launch results for that exact revision; these development +artifacts are not published production releases or evidence of hardware qualification. -## Playing a GameCube game +### macOS -Use a Dolphin application built with this option (not an ordinary upstream build). -Close other applications that are managing the same controller. In Dolphin's -Controller Settings, find the **Switch 2 Controllers** section above **Common**. -Click **Find Controllers**, allow Bluetooth access, and hold Sync on the wireless -controller. Discovery lasts 60 seconds. - -Choose the connected **Switch2Kit GameCube** or **Switch2Kit Pro Controller 2** -in the physical-controller dropdown beside the desired GameCube port. This selects -**Standard Controller**, applies the correct button/stick/trigger preset and binds -**Motor** for rumble. No manual profile selection is needed. Each physical controller -can be assigned to only one active Standard Controller port through this shortcut; -set its old port to None before moving it. Other controller types and backends -continue to use Configure normally. - -Pairing stays separate from the emulated controller type: **Standard Controller** -is what the game sees, while the adjacent dropdown selects the physical input -device. Changing the type does not start Bluetooth discovery. - -In **Configure**, **Use Recommended Mapping** applies the same mapping to the -selected supported device. It is explicit: selecting a device, refreshing the list, -or reconnecting a controller does not overwrite bindings. Replacing custom buttons, -calibration, or other settings requires confirmation (Cancel is the default) and -creates a uniquely named **Before Switch2Kit Port …** profile. Use Profile → Load -to restore it. A missing preset or failed backup leaves the current mapping intact. - -The GameCube preset preserves independent analog L/R travel and digital full -clicks. The Pro preset matches printed Nintendo A/B/X/Y labels; + is Start, R is -GameCube Z, and ZL/ZR provide on/off GameCube L/R. Pro triggers cannot produce -GameCube-style variable squeeze. - -Open the game normally. Port bindings use Dolphin's existing settings. -This is not wired GameCube USB-adapter mode. +Use macOS 15+ and the artifact matching Apple Silicon (`arm64`) or Intel (`x86_64`). Move +`DolphinQt.app` to Applications and open it. Enable Bluetooth and allow Dolphin under +**System Settings > Privacy & Security > Bluetooth**. The app embeds its controller library +and Swift runtime. Ad-hoc signing is not notarization: use Apple's +[per-app approval procedure](https://support.apple.com/en-us/102445) only for an app you +trust, rather than disabling Gatekeeper globally. -### Automatic connection and recovery +### Linux -Enable **Automatically connect** in the **Switch 2 Controllers** section. -This starts listening now and saves your choice for future Dolphin launches. After -initial pairing, turn the controller on again after a long pause: Dolphin can -rediscover it without reopening settings or pressing Find. Discovery runs on the -SDK's Bluetooth queue, independently of emulation pause and the settings window. -There is no repeating Find timer or 60-second limit in automatic mode. - -The option is off by default. With it off, Find still searches for 60 seconds, -and merely launching Dolphin does not start Bluetooth or request permission. -With it on, Dolphin starts once on the main run loop after SDL initialization. -The status distinguishes continuous listening from a finite manual search. - -**Disconnect All** in that section stops input and discovery for the current -session, even with this option checked. Polling, returning to the app, resuming a -game or reopening settings cannot undo that explicit stop. Use Find or re-enable -the option to resume; the saved option still applies on the next app launch. -Unchecking the option stops automatic discovery without disconnecting ready -controllers. A connection handshake already admitted may finish. - -Automatic discovery connects available **supported** controllers, not arbitrary -Bluetooth devices and not only a saved allowlist. Close competing controller apps. -It does not overwrite custom mappings or assign a new controller to a game port. -The transport retains its capacity limits, serialized handshakes, duplicate-filtered -scans and bounded retry behavior; continuous listening still uses Bluetooth radio -resources. It cannot wake a powered-off controller or bypass initial pairing or -Bluetooth permission. - -The choice is stored as `[Settings] AutoConnect` in `Switch2Kit.ini`, alongside -but separate from physical identities. Failed reads/saves do not overwrite existing -settings or change the runtime choice. A saved choice whose start failed remains -visible; use Find to retry after resolving the reported problem. - -The controller's physical identity is assigned a persistent Dolphin device number -in `Switch2Kit.ini` in Dolphin's user configuration directory. Reconnecting two -identical controllers in reverse order does not change their intended saved -assignments. An unreadable/unwritable configuration or exhaustion of the 64 saved -slots falls back to Dolphin's ordinary device numbering; in that case verify the -selected device. No controller identifiers are written to diagnostic messages. +The development target is Ubuntu 24.04 x86-64 with a graphical desktop, graphics/audio +drivers, a powered Bluetooth LE adapter, BlueZ and normal system-bus/GATT access. Install +the distribution runtimes: -## Controller differences and motion +```sh +sudo apt-get install bluez libsystemd0 libqt6widgets6t64 libqt6svg6 qt6-qpa-plugins \ + libevdev2 libudev1 libusb-1.0-0 libasound2t64 libpulse0 libgl1 libegl1 +tar -xzf Dolphin-Switch2Kit-linux-x86_64.tar.gz +./Dolphin-Switch2Kit-linux-x86_64/bin/dolphin-emu +``` + +Keep `bin/Sys`, `lib` and `share/Switch2KitNotices` with the executable. Swift runtime +libraries are packaged; system libraries and drivers are not. This is an installed +directory, not a universal AppImage. No Swift installation or `LD_LIBRARY_PATH` override +is needed to launch it. `bluetoothctl show` can check adapter power. The backend does not +power adapters, erase bonds or invoke BlueZ Pair/RemoveDevice. Resolve access errors using +the distribution's normal Bluetooth policy, not by running Dolphin as root. -The quick port selector supports GameCube and Pro controllers. Discover each Joy-Con 2 half using Find/Sync, then use the ordinary per-port **Configure** window and SDL device selection to assign that half's buttons and axes manually. This fork does not automatically combine the halves into one controller or create a system-wide virtual pair. +### Windows -For Wii games, choose **Emulated Wii Remote** and configure its ordinary inputs separately. The GameCube-port shortcut is not Wii motion setup. This maintained fork does not supply the SDK's separate pinned-upstream Dolphin patch's calibrated-motion setup UI. Do not assume that selecting a controller or a test calibration file gives usable Wii motion. Cemu has its own explicit measured-motion workflow; that is a different integration. +The experimental target is Windows 11 x64 with Bluetooth LE and graphics drivers, plus +the [Microsoft Visual C++ x64 runtime](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist) +when required. Open the extracted directory's `Dolphin.exe`. Keep all DLLs, Qt plugins, +`Sys` and `Switch2KitNotices` together. The selected Swift runtime is included; launching +does not require Swift or a compiler-specific PATH. ARM64 and 32-bit Windows are not covered. -NSO GameCube rumble uses the dedicated Bluetooth on/off motor channel, not HD waveforms or short firmware feedback clips. Pro/Joy-Con retain their HD-rumble path. Zero, disconnect and teardown stop output; stale requests cannot restart retired sessions. Check actual motor behavior on your hardware rather than treating an automated callback test as a physical result. +Enable Bluetooth in **Settings > Bluetooth & devices** and use Find/Sync. Honor legitimate +system access prompts. Run as a normal user; do not disable SmartScreen, antivirus or +Bluetooth security to bypass an error. A missing DLL before the window appears is a +packaging/prerequisite problem, not a pairing failure. Re-extract the complete artifact and +check its launch results. Windows Server CI does not establish physical Windows 11 pairing. ## Build from source -The optional backend is OFF by default; disabled builds do not require Swift or raise the platform deployment target. Enabled builds need SDL3, Qt and the platform toolchain below. Use the maintained fork's selected submodules, not the SDK's separate upstream patch scripts. While this PR is unmerged: +Start from a checkout containing this integration and follow the ordinary Dolphin build +prerequisites in [Readme.md](../Readme.md). Initialize the recorded dependencies: ```sh -git clone --branch feature/switch2kit-desktop-platforms --recurse-submodules https://github.com/jmonster/dolphin.git dolphin-switch2kit -cd dolphin-switch2kit +git submodule update --init --recursive ``` -**macOS:** install Xcode 26+ with Swift 6.2+, open Xcode to finish setup and select its Command Line Tools. Then: +Keep the pinned Switch2Kit revision; do not apply the SDK's separate Dolphin patch scripts. +Disabled builds do not require Swift or raise the platform deployment target. Enabled builds +require SDL3, Qt and the platform toolchain below. + +**macOS:** use Xcode 26+ with Swift 6.2+, finish Xcode setup and select its Command Line Tools. +On Apple Silicon, use a native Terminal and Homebrew rather than Rosetta. ```sh brew install cmake ninja nasm automake libtool qt@6 -cmake -S . -B build-switch2kit -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_OSX_DEPLOYMENT_TARGET=15.0 -DCMAKE_OSX_ARCHITECTURES="$(uname -m)" -DENABLE_SWITCH2KIT=ON -DENABLE_SDL=ON -DENABLE_QT=ON -DUSE_SYSTEM_SDL3=OFF -DENABLE_VULKAN=OFF -DENABLE_TESTS=OFF -DCMAKE_PREFIX_PATH="$(brew --prefix qt@6)" -DPOSTPROCESS_BUNDLE=ON +cmake -S . -B build-switch2kit -G Ninja \ + -DCMAKE_BUILD_TYPE=Release \ + -DCMAKE_OSX_DEPLOYMENT_TARGET=15.0 -DCMAKE_OSX_ARCHITECTURES="$(uname -m)" \ + -DENABLE_SWITCH2KIT=ON -DENABLE_SDL=ON -DENABLE_QT=ON \ + -DUSE_SYSTEM_SDL3=OFF -DCMAKE_PREFIX_PATH="$(brew --prefix qt@6)" \ + -DENABLE_VULKAN=OFF -DENABLE_TESTS=OFF -DPOSTPROCESS_BUNDLE=ON cmake --build build-switch2kit --target dolphin-emu --parallel 3 open build-switch2kit/Binaries/DolphinQt.app ``` -**Linux:** install Swift **6.2.1** using the [official Linux installation instructions](https://www.swift.org/install/linux/), then the build dependencies used by the Ubuntu application job: +**Linux:** install Swift 6.2.1 using the [official instructions](https://www.swift.org/install/linux/), +then the Ubuntu application job's build dependencies: ```sh -sudo apt-get install build-essential cmake ninja-build python3 pkg-config qt6-base-dev qt6-base-private-dev qt6-svg-dev libbluetooth-dev libevdev-dev libudev-dev libusb-1.0-0-dev libasound2-dev libpulse-dev libx11-dev libxi-dev libxrandr-dev libegl1-mesa-dev libgl1-mesa-dev libsystemd0 dbus +sudo apt-get install build-essential cmake ninja-build python3 pkg-config \ + qt6-base-dev qt6-base-private-dev qt6-svg-dev libbluetooth-dev libevdev-dev \ + libudev-dev libusb-1.0-0-dev libasound2-dev libpulse-dev libx11-dev libxi-dev \ + libxrandr-dev libegl1-mesa-dev libgl1-mesa-dev libsystemd0 dbus bash Tools/build-switch2kit-linux.sh --run ``` -The helper builds, installs and opens `build-switch2kit/install/bin/dolphin-emu`. Keep the whole install prefix for later launches. `openbox`, `wmctrl`, `x11-utils`, `xvfb` and `xauth` are CI GUI-test dependencies, not a requirement for an ordinary desktop user. +The helper installs and opens `build-switch2kit/install/bin/dolphin-emu`. Keep the complete +install prefix. The workflow's Xvfb/window-manager tools are only needed for CI GUI tests. -**Windows:** install Visual Studio **2026 Desktop development with C++**, Windows SDK 10.0.22621 or newer, Git, CMake, Ninja, Python 3, PowerShell 7 and native x64 Swift **6.3.3** following [Swift's Windows instructions](https://www.swift.org/install/windows/). Open 64-bit PowerShell in the checkout: +**Windows:** install Visual Studio 2026 Desktop development with C++, Windows SDK 10.0.22621 +or newer, Git, CMake, Ninja, Python 3, PowerShell 7 and native x64 Swift 6.3.3 using +[Swift's instructions](https://www.swift.org/install/windows/). In 64-bit PowerShell, run: ```powershell ./Tools/build-switch2kit-windows.ps1 -Run ``` -The helper selects VS 2026 and one compatible Swift installation, builds the native controller library and complete Dolphin target, then opens `build-switch2kit-windows/Binaries/Dolphin.exe`. Swift 6.2's compiler is incompatible with VS 2026 STL headers; a different standalone clang on PATH does not replace Swift's compiler. Do not bypass Dolphin's compiler guard or Microsoft's STL checks. Build-time runtime PATH setup is process-local; extracted packages are tested without it. +The helper selects compatible Visual Studio and Swift installations, builds the controller +library and Dolphin, and opens `build-switch2kit-windows/Binaries/Dolphin.exe`. Swift 6.2's +compiler is incompatible with VS 2026 STL headers. A standalone clang on PATH does not +replace Swift's compiler; do not bypass either project's compiler checks. -To update a source build, quit Dolphin, use `git pull --ff-only`, update the recorded submodules with `git submodule update --init --recursive`, and rerun the same build command. Do not erase your Dolphin user configuration. +To update, quit Dolphin, run `git pull --ff-only` and `git submodule update --init --recursive`, +then repeat the build command. Do not erase Dolphin's user configuration. ## Qualification and troubleshooting -A missing **Switch 2 Controllers** section means the launched binary was built without this backend. A controller absent after a 60-second search warrants checking adapter power/access, Sync mode, competing connections and the reported status; retry Find after resolving the cause. Do not reinstall a dashboard or a system SDL override. A changed adapter or device address can change Linux/Windows physical identity: verify the selected player port instead of relying on a displayed ordinal. - -The native workflows build real applications. Desktop launch qualification extracts the exact uploaded archive into a new directory, uses private test profiles, verifies the loaded controller/Swift libraries come from that package, opens a GUI, requests normal quit, and relaunches. It deliberately seeds noninteractive test settings; it does not establish pristine first-use dialogs, downloaded-app approval, Bluetooth hardware or gameplay. A run is qualified only after those checks pass for its exact head. The executable runtime-wiring regression also checks missing-runtime failure, deployment-error propagation, optional-backend isolation and relocatable resources; fixture DLLs are not substituted into the application artifact. - -Retained mapping/host regressions exercise real mapping and host code against controlled UI/storage boundaries, including cancellation, backup/rollback, stable identity, saved consent, explicit stop and shutdown ordering. Protocol, rumble, calibration, bounded queues, permissions, signing and license coverage remain in the SDK/fork suites. No prose-length, heading-order or branding assertion is needed to protect these behaviors. - -Record hardware acceptance separately for each model/firmware/OS/adapter and tested commit: first pairing and denied-access retry; every press/release and stick; independent GameCube analog travel and digital clicks; correct rumble and stop; two identical controllers returning in reverse order; saved assignments after app restart; Bluetooth loss/recovery; explicit Disconnect remaining stopped; normal quit; and gameplay. For Dolphin's automatic mode, power a controller off for longer than 60 seconds and reconnect without opening settings, then test disabling automatic discovery without dropping a live controller. These changes do not claim that checklist has been physically completed. +A missing **Switch 2 Controllers** section means the binary lacks this backend. For a +controller absent after a search, check adapter power/access, Sync mode, competing +connections and the displayed status, then retry Find. Installing a dashboard or replacing +system SDL is not a remedy. + +The workflows check builds and extracted-package launch using private test settings. +They do not establish pristine first-use dialogs, downloaded-app approval, Bluetooth +hardware or gameplay. Mapping and host regressions cover cancellation, backup/rollback, +identity, saved consent, explicit stop and shutdown ordering; keep those checks when +changing the integration. + +Record hardware acceptance for each controller model, firmware, OS, adapter and commit: +first pairing and denied-access retry; every press/release, stick and trigger; rumble and +stop; two identical controllers reconnecting in reverse order; saved assignments after +restart; Bluetooth loss/recovery; explicit Disconnect remaining stopped; normal quit; and +gameplay. For automatic connection, leave a controller off longer than 60 seconds and +reconnect without opening settings, then disable automatic discovery with a controller +still connected. A passing build or launch check does not complete this checklist. diff --git a/Readme.md b/Readme.md index af50a87c8bc7..a5cf89078562 100644 --- a/Readme.md +++ b/Readme.md @@ -1,82 +1,4 @@ -# Switch2 Dolphin - A GameCube and Wii Emulator w/Switch2 NSO controller support - -**This fork embeds [Switch2Kit](https://github.com/jmonster/Switch2Kit) for NSO GameCube and Nintendo Switch 2 Pro controllers on macOS 15+, with experimental Linux x86-64 and Windows x64 builds.** - -Get this controller-enabled Dolphin, connect your controller, select a GameCube port, and play. No separate Switch2Kit dashboard, network bridge, SDL override or virtual-controller driver is needed. Individual Joy-Con 2 halves remain available through manual bindings. - -## Quick start - -Build locally using the macOS commands below or the [platform build guide](Docs/Switch2Kit.md#build-from-source); no CI run is needed to build from source. For a prebuilt application, use the artifacts below from **this fork**, not upstream Dolphin binaries. Sign in to GitHub, select a successful run for `feature/switch2kit-desktop-platforms` while this PR is unmerged, and download the named application artifact. Open the run's jobs to check the build and launch results for that revision. Source and diagnostics archives are not applications. These are expiring development artifacts, not published, notarized or production-signed releases; use [Build from source](#build-from-source) when no matching artifact is available. - -### macOS - -To build locally, use macOS 15+, Xcode 26+ with Swift 6.2+, and Homebrew. Open Xcode once to finish setup and select its Command Line Tools. On Apple Silicon, use a native Terminal and Homebrew rather than Rosetta. - -```sh -brew install cmake ninja nasm automake libtool qt@6 -git clone --branch feature/switch2kit-desktop-platforms --recurse-submodules https://github.com/jmonster/dolphin.git dolphin-switch2kit -cd dolphin-switch2kit -cmake -S . -B build-switch2kit -G Ninja \ - -DCMAKE_BUILD_TYPE=Release \ - -DCMAKE_OSX_DEPLOYMENT_TARGET=15.0 \ - -DCMAKE_OSX_ARCHITECTURES="$(uname -m)" \ - -DENABLE_SWITCH2KIT=ON -DENABLE_SDL=ON -DENABLE_QT=ON \ - -DUSE_SYSTEM_SDL3=OFF \ - -DCMAKE_PREFIX_PATH="$(brew --prefix qt@6)" \ - -DENABLE_VULKAN=OFF -DENABLE_TESTS=OFF -DPOSTPROCESS_BUNDLE=ON -cmake --build build-switch2kit --target dolphin-emu --parallel 3 -open build-switch2kit/Binaries/DolphinQt.app -``` - -Move `build-switch2kit/Binaries/DolphinQt.app` to Applications and reopen that same app for later sessions. You do not need to pair the controller in macOS Bluetooth Settings first: in Dolphin's **Switch 2 Controllers** section, click **Find Controllers**, then hold Sync. Discovery only starts through Find or the opt-in **Automatically connect** setting; Sync alone does not start a stopped backend. - -On macOS 15 or newer, use [Native Switch2Kit builds](https://github.com/jmonster/dolphin/actions/workflows/native-switch2kit.yml): **Dolphin-Switch2Kit-arm64** for Apple Silicon, or **Dolphin-Switch2Kit-x86_64** for Intel. Extract the downloaded artifact ZIP, then the `Dolphin-Switch2Kit-.zip` inside it. Move `DolphinQt.app` to Applications and open it. Enable Bluetooth and allow Dolphin's Bluetooth request. A denied permission can be changed under **System Settings > Privacy & Security > Bluetooth**. - -The development app is ad-hoc signed, not notarized. Use Apple's [per-app Open Anyway procedure](https://support.apple.com/en-us/102445) only for a source you trust; do not disable Gatekeeper globally. - -### Linux - -Use Ubuntu 24.04 x86-64 with a desktop session, graphics drivers, a powered Bluetooth LE adapter, the running BlueZ service and normal system-bus access. Install the distribution runtime prerequisites listed in the [Linux guide](Docs/Switch2Kit.md#linux). Use [Switch2Kit Linux application builds](https://github.com/jmonster/dolphin/actions/workflows/switch2kit-linux.yml), artifact **Dolphin-Switch2Kit-linux-x86_64**. Extract the outer download ZIP, then run: - -```sh -tar -xzf Dolphin-Switch2Kit-linux-x86_64.tar.gz -./Dolphin-Switch2Kit-linux-x86_64/bin/dolphin-emu -``` - -Keep the whole extracted directory, including `bin/Sys`, `lib` and `share/Switch2KitNotices`. The packaged Swift runtime does not require a Swift installation or `LD_LIBRARY_PATH` override. This is not a universal Linux/AppImage package; system desktop libraries and drivers are still required. - -### Windows - -Use Windows 11 x64 for the experimental desktop instructions, with Bluetooth LE enabled, its adapter driver, graphics drivers and the Microsoft Visual C++ x64 runtime. Native CI uses Windows Server runners; physical Windows 11 controller acceptance is not claimed. Use [Switch2Kit Windows application builds](https://github.com/jmonster/dolphin/actions/workflows/switch2kit-windows.yml), artifact **Dolphin-Switch2Kit-windows-x86_64**. Extract the outer artifact ZIP, then `Dolphin-Switch2Kit-windows-x86_64.zip` inside it. Open `Dolphin-Switch2Kit-windows-x86_64/Dolphin.exe`. - -Keep its DLLs, `Sys`, Qt plugins and `Switch2KitNotices` together. The package includes the selected Swift runtime; do not install Swift or add a compiler directory to PATH merely to launch it. Do not run Dolphin as administrator or disable SmartScreen/antivirus to bypass a failure. See the [Windows guide](Docs/Switch2Kit.md#windows) for prerequisites and the source fallback. - -### Connect and play - -1. Close other apps or consoles managing this controller. In Dolphin, open **Controllers** (Controller Settings). In the **Switch 2 Controllers** section, click **Find Controllers**, and hold the controller's **Sync** button until its player lights sweep. Allow any legitimate Bluetooth access prompt. Discovery lasts 60 seconds; click Find again to retry. Bluetooth Settings power/access and Dolphin's discovery are separate; no global permission or pairing bypass is required. -2. Beside the desired **GameCube port**, select the physical **Switch2Kit GameCube** or **Switch2Kit Pro Controller 2**. Dolphin selects **Standard Controller** and applies recommended controls and rumble. Do not select **GameCube Adapter for Wii U** mode for these wireless controllers. -3. Open that port's **Configure** window. Verify presses/releases, sticks, D-pad, rumble and triggers, then open your GameCube game. NSO GameCube L/R analog travel and full clicks are independent; Pro ZL/ZR are digital and cannot reproduce an analog squeeze. - -Reopen the same extracted application on later launches. Saved physical assignments and custom mappings persist. Enable **Automatically connect** in the **Switch 2 Controllers** section for Dolphin's opt-in reconnection policy; it is off by default, so otherwise use Find again. **Disconnect All** in that section stops the backend without deleting mappings. Explicit **Use Recommended Mapping** and slot replacement preserve the existing confirmation/backup behavior; discovery does not silently replace custom bindings. - -For Wii games, configure an **Emulated Wii Remote** and its SDL input normally; the GameCube-port shortcut does not configure Wii motion. Discover each Joy-Con 2 half with Find/Sync and map each desired device manually. Do not assume a paired virtual controller or calibrated motion is created automatically. The [controller guide](Docs/Switch2Kit.md#controller-differences-and-motion) explains these distinctions. - -Screenshot 2026-09-19 at 1 58 43 PM - -### Build from source - -The [build guide](Docs/Switch2Kit.md#build-from-source) contains complete platform prerequisites and commands. Clone the implementation branch while the PR is unmerged: - -```sh -git clone --branch feature/switch2kit-desktop-platforms --recurse-submodules https://github.com/jmonster/dolphin.git dolphin-switch2kit -cd dolphin-switch2kit -``` - -Do not apply the SDK's separate pinned-upstream patches to this maintained fork. Ordinary upstream-style builds below leave Switch2Kit disabled unless requested. Linux and Windows remain experimental; automated build/launch checks do not establish physical pairing, rumble, reconnect or gameplay acceptance. - -## Upstream Dolphin documentation - -The information below describes Dolphin generally, including builds without this fork's Switch2Kit feature. Controller-enabled builds use the platform requirements above. +# Dolphin - A GameCube and Wii Emulator [Homepage](https://dolphin-emu.org/) | [Project Site](https://github.com/dolphin-emu/dolphin) | [Buildbot](https://dolphin.ci/) | [Forums](https://forums.dolphin-emu.org/) | [Wiki](https://wiki.dolphin-emu.org/) | [GitHub Wiki](https://github.com/dolphin-emu/dolphin/wiki) | [Issue Tracker](https://bugs.dolphin-emu.org/projects/emulator/issues) | [Coding Style](https://github.com/dolphin-emu/dolphin/blob/master/Contributing.md) | [Transifex Page](https://app.transifex.com/dolphinemu/dolphin-emu/dashboard/) | [Analytics](https://mon.dolphin-emu.org/) diff --git a/Source/Core/CMakeLists.txt b/Source/Core/CMakeLists.txt index 838349d1aba7..710b21ea3aa4 100644 --- a/Source/Core/CMakeLists.txt +++ b/Source/Core/CMakeLists.txt @@ -20,11 +20,6 @@ if(ENABLE_QT) endif() if(ENABLE_SWITCH2KIT) - if(NOT APPLE) - target_sources(dolphin-emu PRIVATE - DolphinQt/Config/Mapping/Switch2KitMapping.cpp - DolphinQt/Config/Mapping/Switch2KitMapping.h) - endif() if(WIN32) # These C++ hosts share one runtime directory and one Swift product: the # facade. Stage its complete compiler-selected runtime closure before the diff --git a/Source/Core/DolphinQt/CMakeLists.txt b/Source/Core/DolphinQt/CMakeLists.txt index 79946aab3221..d527f56d0038 100644 --- a/Source/Core/DolphinQt/CMakeLists.txt +++ b/Source/Core/DolphinQt/CMakeLists.txt @@ -448,6 +448,14 @@ if (NOT WIN32) ) endif() +if(ENABLE_SWITCH2KIT) + target_sources(dolphin-emu PRIVATE + Config/Mapping/Switch2KitMapping.cpp + Config/Mapping/Switch2KitMapping.h + Config/Mapping/Switch2KitMappingPolicy.h + ) +endif() + target_compile_definitions(dolphin-emu PRIVATE -DQT_USE_QSTRINGBUILDER @@ -718,11 +726,6 @@ if(APPLE) endif() if(ENABLE_SWITCH2KIT) - target_sources(dolphin-emu PRIVATE - Config/Mapping/Switch2KitMapping.cpp - Config/Mapping/Switch2KitMapping.h - Config/Mapping/Switch2KitMappingPolicy.h - ) set(SWITCH2KIT_BLUETOOTH_USAGE "NSBluetoothAlwaysUsageDescriptionDolphin uses Bluetooth to connect to the controllers you select.") switch2kit_embed(dolphin-emu) endif()