---

🚀 What is Dualsense-Multiplatform?

Dualsense-Multiplatform is a high-performance, policy-based C++ library that unlocks the full potential of Sony's DualSense and DualShock 4 controllers through direct HID communication.

🌍 True Cross-Platform Architecture

Dualsense-Multiplatform is engine-agnostic by design. It is a pure C++ library that works anywhere C++20 is supported.

The library leverages policy-based design to abstract platform-specific details. This zero-cost abstraction makes it trivial to extend support to new platforms or custom hardware without touching the core logic.

---

🎮 Live Web

Experience the core C++ architecture running natively in your browser. This real-time debugger leverages WebAssembly (WASM) for high-performance execution, seamlessly integrated through a clean TypeScript and JavaScript binding layer.

🧩 Browser Extension

You can also use this tool as a dedicated browser extension for an integrated experience.

• Status: Available now on the Chrome Web Store Add-ons.
• Compatibility: Works natively on Google Chrome, Microsoft Edge, Brave, Opera, Firefox, and other browsers.

---

✨ Features

• 🏗️ Extensible Multi-Platform Architecture Engine-agnostic C++20 design. Supporting new hardware is as simple as implementing the core connection interface, making it suitable for any environment—from PC to embedded systems.
• 🔌 Dynamic Connection (Hot-Swap) Robust plug-and-play logic that automatically detects controller connection and disconnection in real-time.
• ⚡ High-Performance & Low-Latency Optimized for minimal CPU overhead and memory footprint, ensuring zero impact on the main application loop.
• 🎮 Transparent Integration Designed to coexist with existing system input managers without device conflicts or driver interference.
• 🎯 Adaptive Triggers Precise low-level control over resistance, haptic effects, and vibration for R2/L2 triggers.
• 💡 Lightbar & LED Control Programmatic control over the controller's LED colors and player indicators.
• 🎤 Smart Mute Logic Automatic handling of the microphone mute LED state based on device status.
• 🎮 Multi-Controller Support Native support for DualSense (Standard/Edge) and DualShock 4. The model-agnostic architecture is prepared for legacy hardware expansion, such as PS1 and PS2 models.

---

🏆 Implementations & Integrations

1. Unreal Engine — Middleware Unreal-Dualsense Pro | UE5 Controller Integration Plugin

🌐 unreal-dualsense-pro.valoto.games

🛒 Fab.com - Middleware Unreal-Dualsense PRO

---

2. Raspberry Pico W — Microcontroller Integration

Demonstrating the extreme portability and architectural efficiency of the library, the same core logic used in AAA game engines runs perfectly on a Pico W (264KB RAM / 2MB Flash).

🎥 Watch the example video on YouTube

The Pico W implementation includes complete support for all advanced DualSense capabilities:

Input	Output (Haptics & More)
Motion: Full 6-Axis Gyro & Accel	Adaptive Triggers: Weapon, Feedback & Buzz modes
Touchpad: Multi-touch & Coordinates	Haptic Feedback: Dual independent motor control
System: Battery & Charging status	RGB Lightbar: Full color & Player LED control
Standard: All 17 buttons + Analog sticks	Architecture: Production-ready C++20

The Pico W implementation uses the exact same C++ core files as the Unreal and O3DE integrations, with zero logic changes.

👉 Check out the Pico W implementation

---

3. FFI Integration — Use from Any Language

Test quickly with a C# implementation or create an implementation for your preferred language. The C-compatible API is designed to integrate seamlessly with any language that supports FFI (Foreign Function Interface), including Python, Rust, Go, Java, and more.

📥 Precompiled Binaries (Windows x64)

For quick integration without building from source, **download the precompiled .dll binary directly from the releases page. This shared library is ready to use with any compatible host application or game engine that supports C-compatible FFI (Foreign Function Interface).

🌐 C-API Repository: Gamepad-Core-Host

🚀 Client Implementation Example

Check out the companion command-line application that consumes this API:

• Gamepad-Client (C#) - Console application example consuming the C API
• Gamepad-Client (Python) - Python Console application example consuming the C API

---

4. Other Prototypes & Mods

• O3DE-Dualsense — O3DE Gem integration.
• Godot-Dualsense — GDExtension for Godot 4.x, by katamaritaco.

---

Prerequisites

• CMake 3.20 or higher
• C++20 compatible compiler (MSVC, GCC, Clang)
• Ninja (recommended) or Make

📦 Installation & Submodules

Depending on your project needs, you can clone Gamepad-Core in different ways. The library is designed to be modular, allowing you to include only what is necessary for your target environment.

1. 🍃 Minimal Version (Core Only)

Ideal for: Embedded systems (ESP32, Raspberry Pi Pico W, etc.), OS-level applications, engine integrations, or resource-constrained environments where external audio libraries are not required.

• Features: Basic HID communication, buttons, sticks, triggers (feedback/resistance), and lightbar control.

• Engine & App Ready: Designed as a lightweight backend for custom engines (Unreal, Unity via Native C++) or standalone desktop applications.

• Size: Very small footprint with zero external dependencies.

• Flexibility: This core version serves as the foundation for all implementations; you can manually link your own OS-native audio API if needed.

git clone https://github.com/rafaelvaloto/Gamepad-Core.git

2. 🛠️ Developer Version (Full + Tests)

Ideal for: Contributors, library development, or if you want to run the integration tests on your hardware.

• Features: Everything in Standard + the complete Integration Test suite.

git clone --recursive https://github.com/rafaelvaloto/Gamepad-Core.git

If you have already cloned the repository without submodules, run:

git submodule update --init --recursive

---

🧪 Tests

The fastest way to verify Gamepad-Core on your hardware is by running the Integration Tests. This requires cloning the repository with all submodules.

# Configure and build
cmake -S . -B cmake-build-release -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON
cmake --build cmake-build-release --target test-gamepad-outputs -j

# Run (make sure your DualSense/DualShock is connected)
./cmake-build-release/Tests/Integration/test-gamepad-inputs

🎮 Test Controls

Once the console application is running, use your DualSense to test the features:

Input Testing (test-gamepad-inputs)

The test-gamepad-inputs executable allows you to monitor controller data in real-time. To avoid log misalignment due to terminal width limits, it is highly recommended to test one parameter at a time.

Usage:

./cmake-build-release/Tests/Integration/test-gamepad-inputs [flags]

Available Flags:

Flag	Description
--buttons	Displays digital button states (Cross, Circle, etc.)
--analogs	Displays stick and trigger positions (Default if no flags)
--touch	Displays detailed touchpad data (ID, Fingers, Position, Velocity)
--sensors	Displays Motion Sensor data (Gyroscope and Accelerometer)

Note: When --touch or --sensors are passed, the respective hardware features are automatically enabled on the controller.

---

Output Testing (test-gamepad-outputs)

The test-gamepad-outputs executable allows you to test various controller feedback mechanisms, including vibrations, lightbar colors, and adaptive triggers.

Usage:

./cmake-build-release/Tests/Integration/test-gamepad-outputs

[ FACE BUTTONS ]

Button	Action	Effect
❌ Cross	Vibration/LED	Heavy Rumble + 🔴 Red Light
⭕ Circle	Vibration/LED	Soft Rumble + 🔵 Blue Light
🟥 Square	Trigger Effect	Activates GameCube-style trigger snap on R2
🔺 Triangle	Reset	Stops all effects (Panic Button)

[ D-PAD & SHOULDERS (Trigger Mods) ]

Button	Hand	Effect
L1	L2	Gallop Effect (Vibration on trigger)
R1	R2	Machine Gun Effect (Fast vibration)
⬆️ Up	L2	Feedback (Rigid Resistance)
⬇️ Down	R2	Bow (String Tension)
⬅️ Left	R2	Weapon (Semi-Automatic)
➡️ Right	R2	Automatic Gun (Buzzing)

Break Changes v1.0.0

// Scan for connected devices
Registry->PlugAndPlay(DeltaTime);
auto* Gamepad = Registry->GetLibrary(0)

if (Gamepad->IsConnected())
{
    if (auto* Lightbar = Gamepad->GetIGamepadLightbar())
    {
       Lightbar->SetLightbar({0, 255, 0});
    }
    
    if (auto* Trigger = Gamepad->GetIGamepadTrigger())
    {
    }
    
    // ⚠️ REQUIRED: Update output to apply all changes
    gamepad->UpdateOutput();
}

// Available methods for retrieving interfaces.
IGamepadTouch* GetIGamepadTouch() override { return this; }
IGamepadTrigger* GetIGamepadTrigger() override { return this; }
IGamepadHaptics* GetIGamepadHaptics() override { return this; }
IGamepadLightbar* GetIGamepadLightbar() override { return this; }
IGamepadRumbles* GetIGamepadRumbles() override { return this; }
IGamepadSensors* GetIGamepadSensors() override { return this; }
IGamepadSettings* GetIGamepadSettings() override { return this; }

Minimal Example (Standalone C++)

#include "GCore/Templates/TBasicDeviceRegistry.h"

// 1. Choose your platform policy
#ifdef _WIN32
    #include "Platform/windows/windows_hardware_policy.h"
    using platform_hardware = windows_platform::windows_hardware;
#else
    #include "Platform/linux/linux_hardware_policy.h"
    using platform_hardware = linux_platform::linux_hardware;
#endif

// 2. Define your registry policy
#include "Examples/Adapters/Tests/test_device_registry_policy.h"
using DeviceRegistry = GamepadCore::TBasicDeviceRegistry<Test_DeviceRegistryPolicy>;

int main() {
    // Initialize hardware layer
    auto Hardware = std::make_unique<HardwareInfo>();
    IPlatformHardwareInfo::SetInstance(std::move(Hardware));

    // Create device registry
    auto Registry = std::make_unique<DeviceRegistry>();

    // Game loop
    while (true) {
        float DeltaTime = 0.016f; // 60 FPS
        
        // Scan for connected devices
        Registry->PlugAndPlay(DeltaTime);

        // Get first connected gamepad
        if (auto* Gamepad = Registry->GetLibrary(0)) {
    if (Gamepad->IsConnected()) {
                // Update input state
                Gamepad->UpdateInput(DeltaTime);
                
                // Read button state
                auto Context = Gamepad->GetMutableDeviceContext();
                auto Input = Context->GetInputState();
                
                if (Input.bCross) {
                    // Trigger haptic feedback
                    Gamepad->GetIGamepadLightbar()->SetLightbar({255, 0, 0});
                    // Apply vibration
                    Gamepad->GetIGamepadRumbles()->SetRumble(255, 128);
                    
                    // ⚠️ REQUIRED: Update output to apply all changes
                    Gamepad->UpdateOutput();
                }
            }
        }
        std::this_thread::sleep_for(std::chrono::milliseconds((int)(DeltaTime * 1000)));
    }
}

This design makes it trivial to support custom platforms (e.g., PlayStation SDK, proprietary embedded systems) without touching core logic.

🧩 Architecture

Gamepad-Core follows strict separation of concerns to ensure portability and extensibility:

┌─────────────────────────────────────────────────────────────┐
│                    Your Application                         │
│              (Game Engine, Desktop App, Tool)               │
└────────────────────────┬────────────────────────────────────┘
                         │
         ┌───────────────┴───────────────┐
         │   Adapter Layer (Policy)      │  ◄── You implement this
         │  (Engine-specific bindings)   │      (or use examples)
         └───────────────┬───────────────┘
                         │
         ┌───────────────┴───────────────┐
         │      GCore (Abstract)         │
         │  • Device Registry            │  ◄── Pure C++, stable API
         │  • ISonyGamepad Interface     │
         │  • IGamepadTrigger Interface  │
         └───────────────┬───────────────┘
                         │
         ┌───────────────┴───────────────┐
         │   GImplementations (Drivers)  │
         │  • DualSense HID Protocol     │  ◄── Hardware-specific
         │  • DualShock 4 HID Protocol   │
         └───────────────┬───────────────┘
                         │
         ┌───────────────┴───────────────┐
         │   Platform Policy (OS/HAL)    │  ◄── OS-specific I/O
         │  • Windows (SetupAPI + HID)   │
         │  • Linux (HIDAPI)             │
         │  • macOS (IOKit)              │
         │  • Custom (PS5 SDK, etc.)     │
         └───────────────────────────────┘

🎵 Audio Pipeline — How It Works

Gamepad-Core provides a complete audio-to-haptics and audio-to-speaker pipeline. Here's how the data flows from your application to the DualSense hardware:

┌─────────────────────────────────────────────────────────────┐
│                    YOUR APPLICATION                         │
│  • Captures audio (game sounds, music, etc.)                │
│  • Mixes audio channels                                     │
│  • Applies effects/filters                                  │
└──────────────────────┬──────────────────────────────────────┘
                       │ (sends audio buffer)
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                   GAMEPAD-CORE LIB                          │
│  • Receives audio buffer                                    │
│  • Converts to haptic commands (for haptics)                │
│  • Encodes for speaker output (for speaker)                 │
│  • Sends via HID (USB/Bluetooth)                            │
└──────────────────────┬──────────────────────────────────────┘
                       │ (HID commands)
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                   DUALSENSE HARDWARE                        │
│  • Vibration motors (haptics)                               │
│  • Built-in speaker                                         │
└─────────────────────────────────────────────────────────────┘

---

🤝 Contributing

• Add support for a new platform (e.g., FreeBSD, Android)
• Improve documentation or examples
• Optimize HID communication
• Report bugs or suggest features

Feel free to open an Issue or submit a Pull Request.

Guidelines

1. Follow the existing code style (use clang-format)
2. Test your changes with a physical controller
3. Update documentation if you add new features
4. Keep commits focused and well-described

---

⭐ Credits and Acknowledgments

The foundation of this plugin was built upon the research and code from several amazing projects in the community:

• DualSense on Windows API - Initial DS5 implementation logic.
• Nielk1 on GIST - HID report structures.
• DualSenseAPI - Hardware communication references.
• flok pydualsense - Feature report research.
• SAxense - Base for Bluetooth Audio Haptics.
• Awalol/DS5Dongle - Reference Bluetooth Audio (Headset/Speaker) opus codec and buffer sizes.
• miniaudio - Audio playback and conversion library.
• Ryochan7/DS4Windows - Industry standard for DualShock/DualSense on Windows.
• linux/drivers/hid/hid-playstation.c - Reference for calibration, gyroscope, and Linux driver standards.

Special thanks to the community members who helped improve this plugin:

• yncat: For the extensive research and implementation logic regarding USB Audio Haptics, which was crucial for supporting high-fidelity haptics via USB (Issue #105).

---

⚖️ Legal & Trademarks

This software is an independent project and is not affiliated with Sony Interactive Entertainment Inc., Epic Games, Unity Technologies, Godot Engine, or any of their subsidiaries.

Trademarks belong to their respective owners:

• Sony: PlayStation, DualSense, DualShock are trademarks of Sony Interactive Entertainment Inc.
• Microsoft: Windows, Xbox are trademarks of Microsoft Corporation
• Apple: macOS is a trademark of Apple Inc.
• Epic Games: Unreal Engine is a trademark of Epic Games, Inc.
• Unity: Unity is a trademark of Unity Technologies
• Godot: Godot and the Godot logo are trademarks of the Godot Engine project

---