Home
Welcome to the PadForge wiki — the complete reference for users and developers.
PadForge is a modern controller mapping utility for Windows. It maps any controller, keyboard, or mouse to virtual Xbox 360, DualShock 4, custom DirectInput, MIDI, or Keyboard+Mouse controllers that games see as real hardware.
Everything you need to get started and master PadForge.
| Page | Description |
|---|---|
| Installation | System requirements (Windows 10/11 x64), downloading the portable single-file EXE, optional driver overview (ViGEmBus, vJoy, HidHide, Windows MIDI Services), first-launch walkthrough, auto-elevation behavior, and start-at-login setup. |
| Dashboard | The main screen showing engine start/stop with live polling-rate display, per-slot virtual controller cards (status, type icons, device name, slot numbering), the Add Controller popup, DSU motion server toggle and port, web controller server toggle and URL, and driver installation status summary. |
| Controller Slots | Creating virtual controller slots (up to 16), choosing output types (Xbox 360, DualShock 4, DirectInput/vJoy, MIDI, Keyboard+Mouse), per-type driver requirements, slot enable/disable states, deleting and drag-reordering slots, vJoy config bar (axes/buttons/POVs), MIDI config bar (channel/velocity/CC/notes), and multi-slot device assignment. |
| 3D and 2D Visualization | Interactive 3D controller model (rotate, zoom, pan) with live button highlighting and stick/trigger animation, flat 2D PNG overlay view, click-to-map from any control element, custom DirectInput schematic view (dynamic sticks/triggers/buttons/POVs), and Keyboard+Mouse interactive preview with full QWERTY keyboard and mouse graphic. |
| Button and Axis Mappings | The mapping grid (output, source dropdown, live value, record button, invert/half-axis options), recording mappings via button press or axis movement, mouse axis instant detection, Map All wizard, auto-mapping for recognized gamepads, Copy/Paste/Copy From with automatic cross-layout translation (Xbox to DS4 to vJoy to MIDI to KB+M), custom DirectInput dynamic grid, and calibration-aware value preview. |
| Stick Dead Zones | Per-axis dead zone and anti-dead zone sliders (X/Y independent, 0.1% precision), six dead zone shapes (Scaled Radial, Radial, Axial, Hybrid, Sloped Scaled Axial, Sloped Axial), linear response curve, per-axis sensitivity curve editor with presets (Linear/Smooth/Aggressive/Instant/S-Curve/Delay/Custom) and interactive control points, center offset calibration, per-direction max range (left/right/up/down independently), live circular preview, and custom DirectInput multi-stick support (up to 4 sticks). |
| Trigger Dead Zones | Dual-handle range slider (floor and ceiling), anti-dead zone, per-trigger sensitivity curve editor with the same presets as sticks, live value bar, 0.1% precision with raw digit input, custom DirectInput multi-trigger support (up to 4 triggers sharing 8 axes with sticks), and recommended settings for hair-trigger, racing, and default use cases. |
| Force Feedback | Overall gain and per-motor (left/right) strength sliders, swap motors option, Test Rumble button, live motor activity bars, haptic fallback strategy (LeftRight > Sine > Constant), DirectInput FFB through vJoy PID descriptors, directional haptic forces with polar-to-motor-split conversion, condition effects (Spring/Damper/Friction/Inertia), and audio bass rumble (WASAPI loopback capture with configurable sensitivity, bass cutoff Hz, and per-motor scaling). |
| Macros | Creating macros with combo triggers (buttons + axes + POV directions, simultaneous activation), trigger modes (On Press, On Release, While Held, Always), axis threshold configuration (1-100%), trigger source selection (Input Device vs Output Controller), action types (button/key press/release, delay, axis set, system/app volume with volume limit, mouse move/click/scroll with sensitivity), repeat modes (Once, Fixed Count, Until Release), consume trigger buttons option, continuous parallel actions, custom DirectInput 128-button support, and input device axis source for volume/mouse actions. |
| Profiles | Per-application automatic profile switching based on foreground window detection (~30Hz polling), creating/cloning/editing/loading/deleting profiles, executable matching via Browse dialog (case-insensitive full-path match), the Default profile as baseline, topology badges showing per-type controller counts, and profile contents (all slot settings, mappings, dead zones, force feedback, macros). |
| Devices | Physical device card list with status dots (online/offline), VID/PID, type, capabilities, and slot badges. Device detail pane showing GUID and HidHide instance path (marquee scroll). Real-time raw input visualization: progress-bar axes, circle-grid buttons, compass POV hats, gyro/accel values, visual keyboard layout for keyboard devices, and mouse graphic preview. Input hiding via HidHide (whole device) or input hooks (mapped keys/buttons only) with safety warnings. Force Raw Joystick Mode for devices with wrong SDL3 gamepad mappings. Drag-and-drop device assignment to sidebar slots. |
| DSU Motion Server | What the DSU/cemuhook protocol is, supported motion-sensor controllers (DualSense, DualShock 4, Switch Pro, Switch 2 Pro), enabling the server on the Dashboard, step-by-step emulator setup for Cemu/Dolphin/Ryujinx/Yuzu, 4-slot protocol limit, port configuration (default 26760), and automatic SDL-to-DSU axis mapping. |
| Web Controller | Enabling the embedded HTTP/WebSocket server, connecting from any touchscreen browser (phone/tablet), choosing Xbox 360 or DualShock 4 layout, touch controls for buttons/analog sticks (nipplejs virtual joystick)/D-pad (8-way)/triggers, stick click via quick-tap gesture, WebSocket connection status and auto-reconnect, browser Vibration API rumble forwarding, Add to Home Screen for fullscreen, and network/firewall requirements. |
| Settings | Language selection (10 languages with live switching), theme (System/Light/Dark), input engine controls (auto-start, background polling, master hide toggle, polling interval 1-16ms), window options (minimize to tray, start minimized, start at login), driver management cards with one-click install/uninstall for HidHide/ViGEmBus/vJoy/Windows MIDI Services, HidHide whitelist application management, MIDI slot configuration (channel/velocity/CC count/note count/start numbers), settings file operations (save/reload/reset/open folder), and diagnostics (app version, .NET runtime, SDL version). |
| Driver Management | Detailed guide for each optional driver: ViGEmBus (virtual Xbox 360 and DS4, MSI-based install/uninstall), vJoy (custom DirectInput joystick with configurable HID descriptors and FFB, auto-elevation requirement), HidHide (selective device hiding with built-in blacklist/whitelist/cloaking management, no external Configuration Client needed), and Windows MIDI Services (~210MB GitHub download, virtual MIDI endpoint creation). Includes driver status on Dashboard, troubleshooting table, and uninstall guard conditions. |
| Input Precision | 1000Hz polling architecture with 3-tier sleep strategy (HR waitable timer, multimedia timer, Thread.Sleep+SpinWait), wall-clock drift compensation, zero-allocation hot path. Full axis value pipeline from SDL3 16-bit input through unsigned conversion, dead zone processing (double-precision floating point), to vJoy 15-bit or ViGEm native output. Bit-perfect passthrough at default settings. Dead zone math (x360ce-validated), continuous POV hat support (hundredths of degrees), and single-call batch output (UpdateVJD/SubmitReport). |
| Troubleshooting | Solutions for: no devices detected, virtual controller not appearing in games, double input, vJoy not working, rumble issues, audio bass rumble problems, DSU motion not working, settings not saving, high CPU usage, Steam controller conflicts, wrong button mappings (Force Raw Mode), mouse/keyboard input issues, macro not firing, mouse macro problems, Always-mode macros, web controller connection failures, no MIDI output, sensitivity curve issues, Keyboard+Mouse not working, stick drift after calibration, and a quick-reference table. |
Deep technical documentation for contributors and developers who want to understand or fork PadForge.
| Page | Description |
|---|---|
| Architecture Overview | Two-project .NET 10 solution structure (PadForge.App WPF + PadForge.Engine library), full project layout with every file and folder, Mermaid architecture diagram, SDL3-only input design philosophy, MVVM with CommunityToolkit.Mvvm, threading model (6 threads: engine ~1000Hz, UI 30Hz, Raw Input, DSU receive, input hooks, web controller server), thread safety summary table, NuGet dependencies, 16-slot system, build system (dotnet publish single-file), and localization architecture (10 languages, live switching via weak-event INotifyPropertyChanged). |
| Input Pipeline | The 6-step polling loop: Step 1 (SDL device enumeration with ViGEm/vJoy filtering and GUID migration), Step 2 (SDL state reading with gamepad vs joystick API dispatch, force feedback forwarding, multi-slot vibration combining), Step 3 (mapping engine with descriptor-to-Gamepad conversion, dead zone processing, sensitivity curves, center offset, axis inversion/half-axis), Step 4 (multi-device merge per slot with max-wins strategy), Step 4b (macro state machine with trigger evaluation, action execution, volume/mouse continuous actions), Step 5 (virtual controller lifecycle for all 5 types, XInput slot mask detection, vJoy device management), and Step 6 (output state copy for UI display). Includes motion snapshot capture and DSU broadcast between Steps 2 and 3. |
| SDL3 Integration | Complete SDL3 P/Invoke layer (SDL3Minimal.cs), SDL3 vs SDL2 API changes, bool/string/array marshaling patterns, initialization flags and critical hints (JOYSTICK_XINPUT, RAWINPUT must-not-set), device enumeration flow (Phase 1 open, Phase 1b/1c keyboard/mouse, Phase 2 disconnect detection), ViGEm/vJoy filtering with counter-based approach, SdlDeviceWrapper class (open flow, close order, haptic strategy selection, Force Raw Mode), gamepad vs joystick API state reading (axis/button/POV layouts), sensor support (gyro/accel detection, DSU coordinate conversion), GUID construction (product and instance), HID product string fallback, rumble with change detection, Raw Input for per-device keyboard/mouse, and the custom SDL3 fork for Switch 2 Pro Controller (WinUSB composite device, Steam conflict). |
| Virtual Controllers | IVirtualController interface and VirtualControllerType enum. Five implementations: Xbox360VirtualController (ViGEm, Gamepad-to-Xbox360 button/axis/trigger mapping, change detection, FeedbackReceived callback), DS4VirtualController (ViGEm, DS4 naming/D-Pad/Y-inversion/digital triggers, DualShock4DPadDirection), VJoyVirtualController (P/Invoke to vJoyInterface.dll, single UpdateVJD batch call, Y-axis HID inversion, SubmitRawState for custom configs, FFB architecture with FfbDeviceState/FfbEffectState/FfbConditionAxis, global FfbCallback routing by device ID, ApplyMotorOutput with condition effects, static device management methods, generation-based re-acquire), MidiVirtualController (Windows MIDI Services SDK, virtual endpoint creation, CC/Note change detection, auto-mapping), and KeyboardMouseVirtualController (Win32 SendInput, KbmRawState with 256-bit key bitmask, mouse delta/scroll, change-detection key up/down). |
| vJoy Deep Dive | The phantom controller bug (N nodes x N registry keys = N-squared controllers) and the single-node fix. HID report descriptor format (fixed 97-byte layout: 16 axes, 4 continuous POVs, 128 buttons with active/constant padding). Registry structure (DeviceNN descriptors, OEMForceFeedback keys for DirectInput FFB enumeration). FFB HID PID descriptor (report ID offset formula, 13 output reports, 4 feature reports, 11 effect types including condition effects). FFB communication paths (HID vs IOCTL). Device creation via SetupAPI (PowerShell script with DIF_REGISTERDEVICE, critical DeviceName="HIDClass" requirement). Device removal order (nodes before service). Generation-based re-acquire mechanism. Runtime fixes (stale config leak, DLL namespace cache, config swap during reorder). |
| Settings and Serialization | PadForge.xml file format (SettingsFileData root DTO), file discovery order, UserDevice (physical device record with 40+ fields), UserSetting (device-to-slot linkage with MapTo index), PadSetting (200+ mapping/dead zone/force feedback properties with string-based storage), AppSettingsData (engine, window, profile settings), MacroData/ActionData serialization, ProfileData (per-profile PadSettings + macros), SettingsManager (static slot arrays, UserDevices/UserSettings collections, CreateDefaultPadSetting auto-mapping), serialization pipeline (load/save/apply flow), cross-layout MappingTranslation (positional equivalence across Xbox/DS4/vJoy/MIDI/KBM), and backward compatibility handling (array migration, missing fields). |
| Services Layer | Seven service classes bridging engine and UI: InputService (engine lifecycle, 30Hz DispatcherTimer for UI sync, macro snapshot push, audio bass detector integration, auto-save), SettingsService (XML load/save pipeline, PadSetting application to InputManager, slot creation/deletion/reorder), DeviceService (ObservableCollection sync from UserDevices, HidHide blacklist/whitelist management, device assignment/unassignment, input hiding coordination), RecorderService (input recording state machine for button/axis/POV/mouse detection, Map All sequential flow, threshold-based axis detection), DsuMotionServer (UDP server lifecycle, subscription management), ForegroundMonitorService (GetForegroundWindow polling at 30Hz, process name matching, profile switch triggering), and WebControllerServer (HttpListener accept loop, WebSocket per-client I/O, static asset serving, WebControllerDevice creation). |
| ViewModels | ViewModelBase (CommunityToolkit.Mvvm ObservableObject, weak-event CultureChanged for live language switching), MainViewModel (navigation, sidebar items, profile list, engine status), DashboardViewModel (SlotSummary cards, engine toggle commands, DSU/web controller status), PadViewModel (per-slot mapping grid with MappingItem rows, StickConfigItem/TriggerConfigItem dead zone models, MacroItem state machine, VJoySlotConfig/MidiSlotConfig, output snapshots for all 5 controller types, recording flow), DevicesViewModel/DeviceRowViewModel (device cards, AxisDisplayItem/ButtonDisplayItem/PovDisplayItem for live input visualization, slot toggle commands), SettingsViewModel (theme, polling, driver status, file operations), and supporting types (MappingItem source dropdown, MacroItem trigger/action/repeat models). |
| XAML Views | MainWindow shell (NavigationView sidebar with programmatic controller cards, visibility-swapped pages, drag reordering with adorners, cross-panel device drag-drop, Add Controller popup with per-type capacity checks, status bar, driver overlay). DashboardPage (engine toggle, slot cards in WrapPanel, DSU/web controller/driver status). PadPage (custom RadioButton tab strip, 6 tab panels: Controller/Macros/Mappings/Sticks/Triggers/Force Feedback, view switching between 3D/2D/Schematic/KBM/MIDI preview, vJoy/MIDI config bars, multi-device selector, Copy From dialog). DevicesPage (card ListBox with accent selection bar, raw input visualization with axes/buttons/POV/gyro/keyboard/mouse previews, slot toggle buttons, input hiding toggles). SettingsPage (card-based sections, driver cards, HidHide whitelist). ProfilesPage (profile ListBox with topology badges). 14 value converters, theme switching, Segoe MDL2 icon patterns, and code-behind patterns (Bind/Unbind, CompositionTarget.Rendering with dirty flag, flash animation). |
| 3D Model System | HelixToolkit.WPF integration for Xbox 360 and DualShock 4 controller models from Wavefront OBJ meshes (adapted from Handheld Companion, CC BY-NC-SA 4.0). ControllerModelBase abstract class (ButtonMap/ClickMap/DefaultMaterials/HighlightMaterials dictionaries, embedded resource loading with MSBuild digit-prefix suffix matching, ButtonFileMap for OBJ-to-PadSetting name mapping). Xbox 360 model (colored face button overlays, guide ring/LED, 7-color palette) and DS4 model (PlayStation symbol meshes, touchpad screen). ControllerModelView (HelixViewport3D with all built-in controls disabled, custom Preview-event rotation/zoom/pan, click-to-record via 3D ray-cast hit testing, stick ring quadrant detection with Sutherland-Hodgman clipping, hover highlighting, 400ms flash animation with arrow and quadrant ring overlays, gradient material blending for sticks/triggers). |
| 2D Overlay System | PNG overlay system using Canvas inside Viewbox for resolution-independent scaling. ControllerOverlayLayout.cs (auto-generated by overlay_positions.py from SVG parsing + OpenCV template matching). ControllerModel2DView (base image + overlay images at Z-layers, trigger gas-tank fill effect via RectangleGeometry clip, stick translation transforms, quadrant hover/flash with CombinedGeometry clips, click-to-record with quadrant axis detection). ControllerSchematicView (procedural vJoy view with StickWidget/TriggerWidget/PovWidget/ButtonWidget structs, dynamic layout from VJoySlotConfig.ComputeAxisLayout, hover direction arrows, click-to-record with VJoyAxis/VJoyBtn/VJoyPov target names). KBMPreviewView (QWERTY keyboard from KeyboardKeyItem.BuildLayout + contoured mouse graphic with LMB/RMB/scroll/movement circle/X1/X2 side buttons, per-VK-code key highlighting, movement dot tracking). MidiPreviewView (CC vertical bar sliders + musically correct piano keyboard with white/black key layout, live CC value and note state rendering). |
| DSU Protocol Implementation | MotionSnapshot struct (g-force accel + degrees/sec gyro, SDL-to-DSU axis mapping with sign inversions). DsuMotionServer class (UDP socket on loopback, SIO_UDP_CONNRESET suppression, background receive thread). Packet format: 16-byte header (magic/version/CRC32/server ID), version request/response, controller info request/response (4-slot limit, fake MAC addresses), pad data request/subscription (per-slot and all-slot modes with 5-second expiry), and pad data response (84-byte payload with zeroed button/stick/touch data, real motion timestamp and 6-axis accel/gyro floats). CRC32 implementation, subscription management with high-resolution timestamp pruning, and DsuDiag standalone diagnostic tool. |
| Driver Installation Internals | DriverInstaller static class with embedded resources (ViGEmBus EXE, HidHide EXE, vJoyDriver.zip). ViGEmBus install/uninstall (WiX bootstrapper extraction, MSI via msiexec with UAC, registry version detection). HidHide install/uninstall (same WiX/MSI pattern, product code extraction for uninstall). vJoy install (single elevated PowerShell script: pre-install cleanup with critical node-before-service removal order, ZIP extraction to Program Files, pnputil driver store add, SetupAPI device node creation with inline C# P/Invoke). vJoy uninstall (batch script with exhaustive registry cleanup across all ControlSets). Windows MIDI Services (GitHub API release query, ~210MB download, WiX Burn bootstrapper). HidHideController runtime IOCTL API (blacklist/whitelist/cloaking via \.\HidHide device, Multi-SZ buffer format, managed device tracking, DOS device path conversion). Uninstall guard conditions and elevation strategy. |
| Engine Library | PadForge.Engine assembly: Gamepad struct (XInput layout, button flag constants), VJoyRawState (dynamic axes/buttons/POVs for custom DirectInput), MidiRawState (dynamic CC/note arrays), KbmRawState (256-bit key bitmask + mouse deltas + scroll + 5 mouse buttons, Combine method). VirtualControllerType enum and IVirtualController interface. CustomInputState (24 axes, 8 sliders, 4 POVs, 256 buttons, 3-axis gyro/accel). ISdlInputDevice interface (identity, capabilities, haptic, state reading, rumble). WebControllerDevice (browser gamepad with VID 0xBEEF/PID 0xCA7E). DeviceObjectItem and InputTypes (DeviceObjectTypeFlags, ObjectGuid constants matching DirectInput). ForceFeedbackState (change-detection rumble with haptic strategy dispatch, condition effect support). Vibration class (scalar motors + directional FFB + condition axis data). RumbleLogger, InputHookManager (WH_KEYBOARD_LL/WH_MOUSE_LL with volatile suppression sets), RawInputListener (HWND_MESSAGE thread, per-device keyboard/mouse state), SdlMouseWrapper (scroll wheel intensity tracking), and MappingTranslation (positional equivalence across 5 controller layouts). |
| Build and Publish | Solution structure overview, prerequisites (.NET 10 SDK, Windows 10/11 x64). Build command (dotnet publish -c Release, never dotnet build). Publish configuration (single-file, self-contained, compressed, ~85MB output with embedded .NET runtime and debug symbols). Project configuration details (WinExe, WPF+WinForms for NotifyIcon, WinForms implicit using removal). Version management via manual AssemblyInfo.cs. NuGet dependencies (ModernWpfUI, HelixToolkit, CommunityToolkit.Mvvm, ViGEm.Client, NAudio.Wasapi, Windows MIDI Services SDK from local source). Native DLL handling (SDL3.dll and libusb-1.0.dll as Content with Link flattening). Embedded resources (driver installers, 3D OBJ meshes, 2D PNG overlays). Portable deployment (no installer). Release workflow (version update, build, deploy, test, commit, create GitHub release with gh CLI). Diagnostic tools (DsuDiag, VJoyTest, FfbTest). Build troubleshooting table. |
Built with SDL3, ViGEmBus, vJoy, HelixToolkit, .NET 10 WPF, and Fluent Design.