JoyPro2 Discord GitHub
Reference

Virtual joystick mode (vJoy + HidHide)

Show:

From docs/virtual-joystick.md in the repository (generated, always the current text).

Per game you choose: the game uses your physical devices (native, as always) or one virtual joystick (virtual). In virtual mode JoyPro puts every input that the game's relations use - axes, buttons, hats and the buttons of their modifiers, from all your sticks, throttles and panels - onto one vJoy device (more only when one is not enough: a vJoy device has at most 8 axes, 128 buttons and 4 hats; up to 16 devices). The export writes the game's binds to the vJoy device, JoyPro.VJoy.exe copies the physical inputs to it live, and HidHide hides the physical devices from that game, and only from that game.

Why: some games take only a few joysticks (Arma Reforger: the first four that send input), pick up the wrong ones or renumber them when a device is added. With virtual mode the game sees one device whose inputs never move.

Needs: vJoy 2.1.9 and HidHide 1.5 (both free). JoyPro configures both itself; each change asks Windows for administrator rights once. Not installed: the page's "What this page needs" (and Settings > Components) installs the official, pinned and checked installers on the user's click (vJoy 2.1.9.1, HidHide 1.5.230, ViGEmBus 1.22.0; docs/components.md).

#How it fits together

Part Where What it does
Mapping table profile (Pr0file.VirtualJoystick, JSON) physical device + input -> vJoy device + input; never reshuffled
engine vjoy ... engine/EngineVJoy.cs, engine/VJoy/VJoyMapping.cs per-game mode, table, status, vJoy setup, HidHide session
Export/import scope EngineVJoy.GameScope around every game command the game's binds point at the vJoy slots while the game is exported, imported, scanned or synced
HidHide session engine/VJoy/HidHideSession.cs (also linked into the GUI) plan, journal, apply, verify, restore, crash recovery
Forwarder gui/JoyPro.VJoy (<GUI>\vjoy\JoyPro.VJoy.exe) DirectInput (non-exclusive) -> vJoyInterface.dll, live
GUI page Virtual Joystick (bottom bar), MainWindowViewModel.VirtualJoystick.cs toggles, status, table, Start/Test/Stop, live view
Virtual functions engine/VJoy/VirtualFunctions.cs, VirtualFunctionRuntime.cs (shared), EngineVJoyFunctions.cs, GUI MainWindowViewModel.VirtualFunctions.cs, VirtualFunctionEditorViewModel.cs functions between the physical inputs and the virtual outputs, evaluated by the forwarder every pass
Chaining and modes VfChain, VfModeSet (VirtualFunctions.cs), the runtime; GUI MainWindowViewModel.VirtualModes.cs, Views/Controls/VirtualFunctionGraphView.cs functions reading other functions' outputs; named modes with inheritance; the editable graph
Gremlin import engine/VJoy/GremlinImport.cs, EngineVJoyGremlin.cs Joystick Gremlin R13/R14 profiles into functions and modes, with a report
Game input limits engine/VJoy/GameInputLimits.cs what a game reads of one joystick; warnings above it

#The mapping table

  • Inputs: every relation with an active node of a game in virtual mode and a bind on a game controller (keyboard and mouse stay as they are), plus the modifier buttons of those binds. vJoy devices are never a source.
  • A hat is one slot (its eight directions go along: JOY_BTN_POV1_UR on the stick becomes JOY_BTN_POV2_UR on vJoy if the stick's hat 1 sits on vJoy hat 2).
  • New inputs get a slot in a fixed order (device name, then axes, buttons, hats by number). An axis keeps its own axis when it is free (X stays X), else the first free one; buttons and hats take the next free number. A physical device stays on the vJoy device it already uses where it fits.
  • Existing slots never move. A slot no relation uses any more stays (--prune drops it, --reset starts over), so the game's binds are the same from run to run. One table serves all virtual games: a physical input has the same vJoy input in every game.
  • engine vjoy settings --first-device N --last-device M limits the vJoy devices JoyPro uses (default 1-16). JoyPro's in-game test kit (tools/e2e) uses vJoy device 1; virtual mode and the kit do not run at the same time.

#Export, import, sync

While a game in virtual mode is exported, imported, scanned or synced (engine dcs|il2|sc|<game> export|import|scan, engine sync status|diff|apply|accept --game <game>), every bind on a mapped physical input (and every modifier on a mapped button) points at its vJoy slot; afterwards the profile gets its physical devices back. Binds an import or a sync brings in on vJoy slots are turned back into the physical inputs. So the game file holds vJoy binds, the profile always holds your real devices. If the table needs a new slot during an export, it is given and saved. If a needed vJoy device is missing (not configured, or DirectInput does not list it), the export stops with a message instead of writing binds nobody can use.

The vJoy device's identity in the games is its DirectInput name (vJoy Device {GUID}); vJoy numbers its devices by HID collection (&col01 = the first configured device). Games that tell devices apart only by name (for example WARDOGS, Arma Reforger) cannot tell several vJoy devices apart: keep such games within one vJoy device.

#vJoy devices in imports (2.5.0)

vJoy devices are imported and exported like any other device: a user may feed one on purpose (VoiceAttack, a feeder of their own) and bind it in the game; no default ignore list leaves them out. Only the vJoy device JoyPro tunnels into is JoyPro's own: Settings "vJoy device JoyPro tunnels into" (instance 1-16, default none) passes --vjoy-tunnel <n> to every import and scan (engine dcs|il2|starcitizen import|scan, engine <game> import|scan). The engine finds that instance's device the way the virtual mode does (the HID collection &col0n against the configured vJoy devices, EngineVJoy.ScanDevices) and adds its vJoy Device {GUID} to the ignore list (registry games: its binds are dropped from the read); every other vJoy instance stays a normal device. When that vJoy device is not connected nothing is left out and the log says so. Checked by engine\tests\smoke\vjoytunnel.ps1 (two fake vJoy devices: without the option both are imported, --vjoy-tunnel 1 leaves out only device 1, 2 only device 2, 17 is refused).

How the tokens of --device / --ignore-device of dcs|il2|starcitizen import|scan become device names (Program.TryResolveDeviceFilters, 2.6.0): an exact name of a profile, connected or game-listed device stays; a name without GUID ("vJoy Device") becomes every device of that name; an ignored device that is not there stays as given (it never hides another device, such as another vJoy instance; a single other device of the same model that is not vJoy is added too); a selected device that is not there becomes one device, chosen deterministically, never the tunnel device, a real device before vJoy unless the token names vJoy. The message names the device ("vJoy device 2", the model), the log keeps the full name. The IL-2 lookup reads devices.txt with the import's GUID conversion (the reversed last 8 bytes), and with JOYPRO_FAKE_DEVICES the fake devices are the connected ones. Before, a tunnel or ignored vJoy name could be swapped for another vJoy device (the live log: "Multiple devices matched ... auto-selected vJoy Device {GUID}"). Checked by engine\tests\smoke\il2vjoy.ps1.

Exports (2.6.0): the GUI passes --vjoy-tunnel and the import's ignored devices (--ignore-device) to every export (engine dcs|il2|starcitizen|<game> export). Those devices are never cleared in any mode, like a device that is not connected: one rule in GameCommands.RunExport (GameDeviceDirectory.MarkKept, GameDevice.Kept) that every exporter checks where it releases binds (clean, nuke, "my profile wins"); IL-2 and Star Citizen take the same list. The device stays in the device list (slot and device order of the games do not change) and binds the profile itself has on it are still written. A game in virtual mode writes to the tunnel device, so there it is JoyPro's and is cleared as usual. Checked by ExportKeptDevicesTests (per game class a fake vJoy device holding game binds survives clean + nuke; without the option the same export clears it). Arma Reforger has no case there: the game never sees vJoy, so its export skips vJoy binds and gives vJoy no slot (engine\tests\smoke\reforger.ps1 checks that).

One source of truth (2.6.0). The tunnel setting is also where virtual mode writes: the GUI passes --vjoy-tunnel to every engine vjoy command, and the engine makes that device the first vJoy device of the table (EngineVJoy.ApplyTunnel: FirstDevice = the tunnel device, saved with the next change). So the table's slots, the function outputs (an output without a device goes there), the forwarder, the exports (GameScope), the Gremlin import (its vJoy device moves there) and Battlefield's one joystick all use the tunnel device, and a VoiceAttack-fed vJoy below it is never written. Imports and scans leave the tunnel device out only for games in native mode; a game in virtual mode reads it, because its binds on JoyPro's slots are turned back into the physical inputs and its binds on function outputs are the profile's own (leaving it out would lose them). engine vjoy status reports TunnelDevice and TunnelWarnings (no tunnel device named while virtual mode writes one; a table that needs a second vJoy device, which imports of native games then read like any other); the page's Status card shows both. After changing the tunnel device, export the virtual games again (the slots move to the new device). Not covered: sync (engine sync) compares only the devices the profile uses and passes no tunnel; the nuke of IL-2, Star Citizen and the registry games' exports clears binds on every connected device it does not write, the tunnel device included (only DCS keeps it).

#The page for pad-only players (2.7.0)

When every virtual game is on the Xbox pad (ACE COMBAT 8 ...), the page is the pretend controller's: the bar button and title say "Pretend controller", the status says "The pretend controller needs the free helper ViGEmBus. Install it in the card below." and ": 12 inputs are on the pretend controller. Everything fits." (the game's name, never its id), Test and Start speak of the pretend controller. vJoy, HidHide, the HidHide session, the forwarding rate, the tunnel, the pad's technical notes, the mode lists, "What this page needs" and Refresh show only under Show details for experts (vJoy, HidHide, modes) (ui-settings.json virtualJoystickDetails, kept over a restart). The ViGEmBus card is translated and uses the same term. Tests: ThirdNoviceReviewTests, VirtualJoystickTests.

#Virtual Xbox pad (mode "xbox", ViGEmBus)

For games that only read Xbox controllers (XInput) or only one device, a game can use a virtual Xbox 360 pad instead of vJoy: engine vjoy mode <game> xbox (GUI: "Xbox pad"). It needs the free ViGEmBus driver by Nefarius (BSD-3-Clause). JoyPro detects it (engine vjoy status: installed, running, version) and explains it; the GUI installs the official ViGEmBus 1.22.0 on the user's click and consent (docs/components.md). The engine never installs drivers, and no test touches the driver.

  • On the pad by itself (2.7.0): a game that reads no generic joystick at all, only Xbox controllers (IGameDeviceLimit with MaxJoysticks 0 and SuggestedMode xbox, and engine vjoy limits "reads no joystick": ACE COMBAT 8, Hell Let Loose: Vietnam), uses the Xbox pad when the user has chosen no mode for it (VJoySettings.ModeOf: the stored choice, else xbox for such a game, else native). That effective mode counts everywhere: status (Mode, AutoMode, ReadsOnlyXbox), plan/map, forwarder-config, HidHide, the GUI's auto start and the export's scope. An explicit engine vjoy mode <game> native|virtual|xbox wins and is stored (native as a word only for such a game). The GUI says "On the Xbox pad by itself: the game reads only Xbox controllers" and lists the game only when the profile uses it; without ViGEmBus the Games card says so with the one-click install.
  • Per game its own table (VJoySettings.XboxSlots[game], in the profile), because an XInput game takes one pad and has its own layout. Unlike vJoy slots (which stay so exported binds never move), a pad slot that no relation of the game feeds any more goes at the next map (no --reset needed): the pad's games get no binds from JoyPro, and a stale slot would still drive its control.
  • Several games on the pad (2.7.0): each keeps its own table; one pad table is live at a time. The forwarder uses --xbox-game (the GUI passes the game whose process runs, with auto start and with Start/Test), else the user's pick (engine vjoy settings --xbox-pad-game <game>, the page's "Xbox pad table for Start and Test"), else the first game with something to forward. forwarder-config names the others as xboxWaiting; nothing is dropped.
  • A hat direction on a pad button: a relation bound to one hat direction (JOY_BTN_POV2_R) whose action the game has on a button (Change target -> Y) gets that direction as its own input (slot input = the bind token, forwarder kind hatdir). A whole hat still goes to the D-pad; directions that a button slot or a function reads are left out of it (skip), so one hat direction never drives two controls.
  • The game's layout first: when the game's catalog knows the default gamepad key of an action (5th column of DB\<Game>\actions.tsv, an Unreal FKey name such as Gamepad_LeftX, Gamepad_LeftTriggerAxis, Gamepad_FaceButton_Bottom, Gamepad_LeftStick_Up), the physical input of that relation is pinned to that control. Two axes on one control: the one moved last wins (a note says so). An input whose kind does not fit the control (a button on an action that sits on a stick axis) gets a free control and a note.
  • The rest in order: axes -> left stick X/Y, right stick X/Y, left/right trigger; buttons -> A B X Y LB RB Back Start LS RS, then the D-pad directions, then the triggers (pressed = fully pulled); a hat -> the D-pad (diagonals included). Guide is never given (Windows opens the Game Bar on it). A button can also push a stick half (XB_LX+, XB_LY- ...) when the game's layout wants that. What does not fit is listed per game (status, plan, map, GUI mapping tab).
  • One axis on both triggers (XB_TRIGGERS): when one physical axis drives two actions of a relation that the layout puts on LT and RT (a collective on "ascend" and "descend"), the forwarder splits it at the axis centre: above it RT, below it LT, both up at the centre.
  • Reversed axes: the invert of the game's curve reverses the pad axis (target suffix ~, e.g. XB_RX~, XB_TRIGGERS~; with a curve the curve carries it). It is the game's own scope (game, family, aircraft) when there is one, else the game's pad convention (IGamePadConventions.PadInvertDefault), never DCS's base invert (EngineVJoy.PadBaseInvert in BindTuning.ResolveWithoutDetent): a throttle inverted for DCS still gives RT when pushed forward on the pad. ACE COMBAT 8's Pad_Pitch is reversed by default: with the game's default "Pitch Controls" the pad stick pushed up pitches the nose up (checked in game, 2026-11-14), so a HOTAS pushed forward must give the pad stick down. Who sets "Pitch Controls: Inverted" in the game unticks Invert for ACE COMBAT 8 alone (Axis response, Applies to: ACE COMBAT 8; DCS keeps its own).
  • Axis curves on the pad (2.7.0): the pad's games get no export, so nobody else would apply the relation's axis tuning. forwarder-config sends each axis slot of the live pad game its curve (curve: 1025 outputs for stick positions -1..1, AxisModels.Sample of BindTuning.Resolve(bind, game): the game's own scope, else the base (the Default curve), with the game's model), the same formula the Binds page previews; the invert is part of the curve then (no ~). ACE COMBAT 8 and Hell Let Loose: Vietnam have the model xboxpad (dead zone, saturation X/Y, curvature or 11-point user curve, slider, invert; evaluated like the base curve). JoyPro.VJoy builds a lookup table per slot once (raw value in, bent raw value out; a straight line keeps 1:1) and applies it without allocating (JoyPro.VJoy bench --xbox-curves). vJoy games stay 1:1: the game applies the exported curve. The Binds page's axis panel says "JoyPro applies this curve itself on the virtual Xbox pad" for those games (binds tuning show lists them as XboxPadGames).
  • Layout chosen in the game: a game can give its gamepad layout itself (IGameGamepadLayout): Hell Let Loose: Vietnam reads the layout A/B/C picked in the game's settings, and engine vjoy map moves the pins when it changes.
  • Forwarding: engine vjoy forwarder-config --xbox-game <game> writes that game's table (see "Several games on the pad"). JoyPro.VJoy run --xbox-sink vigem creates the pad for the run (neutral at start and end, disconnected afterwards); --xbox-sink dry (default, tests, the GUI's Test button) writes nothing. The report is computed from the last state of every physical device: two buttons on one control combine, a pressed button on a stick half wins over the axis on that stick, triggers take the larger value; stick Y follows XInput (up = positive), so a physical stick pushed forward gives a positive Y. No allocation per pass.
  • When to start the pad: the general rule (start the virtual device before the game) is for vJoy, which games look for once at start. The Xbox pad games tested so far, Hell Let Loose: Vietnam and ACE COMBAT 8, want the pad created after their title screen shows: in the in-game runs of 2026-10-11 a pad that existed before the launch never reached Hell Let Loose: Vietnam (probably Steam Input or the game's startup taking the pads present at launch), while a pad connected while the game ran worked; tools\e2e\games\HllVietnamXbox.ps1 and AceCombat8Xbox.ps1 therefore create it once the title shows. JoyPro does not delay the pad by itself (Start by hand or the auto start, which creates it within about 3 s of the game's process): if such a game does not react to the pad, press Stop and Start once the title screen shows.
  • Export: games that can store gamepad binds (IGameGamepadBinds) get their binds on the virtual pad (Xbox 360 Controller (JoyPro virtual pad) with XB_* inputs). Games with fixed gamepad layouts (Hell Let Loose: Vietnam) keep their layout; JoyPro's table follows it, so nothing has to be written.
  • HidHide: as for vJoy - the physical devices of the Xbox games' tables are hidden from those games only. (An XInput-only game ignores DirectInput devices anyway; hiding keeps a real Xbox pad or a stick that pretends to be one out of the way.) Games that read only Xbox controllers (ACE COMBAT 8, Hell Let Loose: Vietnam) get no HidHide step at all (see HidHide below).

#Auto setup on the Xbox pad (2.7.0)

What the ACE COMBAT 8 live test of 2026-11-14 found is JoyPro's default for every profile (EngineVJoy.PadAutoSetup, engine/VJoy/XboxPadAutoSetup.cs; deterministic, made again at every plan; JoyPro's own functions have ids starting with auto-pad- and go when nothing asks for them any more; a function the user made on the same input wins):

  1. Throttle split: when the game accelerates on RT and decelerates on LT, the axis of the throttle relation (the one with the accelerate action) drives both triggers (XB_TRIGGERS: forward RT, back LT, centre neutral), also when the decelerate action sits in another relation (a toe brake relation); that other axis gets no trigger (a note says so).
  2. Yaw on pad buttons (LB/RB): an "Axis ends to buttons" function with an end zone of 0.35 (it presses at about 30 % deflection). The axis is the one the relations put on the yaw actions, else the user's stick twist (an axis relation of the function map's yaw on a device that is not pedals), else the rudder pedals.
  3. Chords (IGamePadChords.PadChords): ACE COMBAT 8's flares are L3 + R3 pressed together (not confirmed in game yet). A macro with "pressed together" (together = 1: every step starts at once and is held its own time, here 120 ms) fed by the user's relation of flare, else cms_switch:fwd, else cm_dispense.
  4. Menu D-pad (IGamePadChords.DPadFunctions): ACE COMBAT gives wingman orders on the D-pad. "Buttons to hat" from the user's relations of wingman, comm_menu or comm_switch on one device (hat directions, or buttons with a direction), when the table leaves the D-pad free and the inputs serve nothing else of the game.
  5. Holds (IGamePadConventions.PadHolds): ACE COMBAT's High-G turn is both triggers fully pressed. A button relation named "High-G", else the relation holding DCS's ASC Direct Control (the "Cobra button" of the Su-27, Su-33, J-11A; not F-16 MPO or the Mirage switches), becomes a remap to XB_LT + XB_RT; a button output on a trigger adds to the table's trigger (VfRuntime.XboxAxisAdds, the larger value wins), so the throttle split keeps working. Without such a relation the plan says how (and pad-check counts it as missing).
  6. One input, one job: a table input that a function of the game reads leaves the table (a shift function keeps its slot); the hat directions such functions read are left out of a whole-hat D-pad.
  7. Look on a free hat (IGamePadConventions.PadLookActions: the right stick for looking around, on the topmost hat of the stick): when no relation of the game reaches the look actions (ACE COMBAT 8 Pad_CameraYaw / Pad_CameraPitch on the right stick) and no function of the user writes that stick, a "Hat to axes" function (hat-axes: each direction holds the stick out while held, a diagonal both) reads a hat nothing of the game uses. The hats are those the profile binds somewhere (any game, or a modifier) and those the connected devices really have (their device catalog entry, else what DirectInput reports), so a profile with ACE COMBAT 8 alone finds the stick's free hat too. Best first: a hat of a look / view / camera relation of another game, then the hats of the devices of the game's must-haves in their order (pitch, roll, gun: the stick and its grip), per device the lowest hat (POV1 is the top hat on most sticks). The function runs only while that game's pad runs, so the hat keeps its job elsewhere (trim in DCS). An axis relation on the look actions (a free ministick) always wins. The Setup wizard places that axis relation itself where a centring axis is free: on a single-hat HOTAS (T.Flight HOTAS 4 / X / One, the stick's only hat holds the target switch, flares and weapon change, which come first) look left / right goes on the throttle's spring-return rudder rocker (catalog axis type centring); look up / down stays without a control there. Known limitation: a device with one hat and no free axis has no place for look around; pad-check then reports look as n/a (hardware limit) instead of a miss.

engine vjoy pad-check [--game <game>] reports per pad game what the profile reaches there (the game's must-haves IGamePadConventions.PadEssentials: ACE COMBAT 8 pitch, roll, gun, missile, target; the throttle split, yaw, each chord, the hold, the menu D-pad, look around) with a score 0..1 for a setup harness (the pad persona's gates leave look out: it is no flight control). The function map puts ACE COMBAT 8's Pad_ThrottleDown ("Throttle down (brake)") under throttle, not wheel brakes, so relations suggest offers it to the throttle relation.

Games of this class and how to add more: docs/games/one-device-games.md.

#One-device games: the suggestion

Games that read one joystick or only Xbox pads declare it (IGameDeviceLimit): Battlefield 6/2042 (one joystick, virtual), Hell Let Loose: Vietnam and ACE COMBAT 8 (no joystick, xbox).

  • engine vjoy status shows "one-device game: suggested" while such a game is native, and the status JSON has SuggestedMode, MaxJoysticks and DeviceLimitNote per game.
  • engine vjoy mode <game> native warns.
  • The GUI's Games list shows the suggestion with a Use it button.
  • An export in native mode warns when the binds use more joysticks than the game reads.

Axes a game must not see: a game can rule out vJoy axes (AvoidVJoyAxes). Battlefield takes a joystick with Rx/Ry for an Xbox pad and then hides its joystick page. While such a game is in virtual mode:

  • the planner gives no new input those axes;
  • a kept slot on one of them is flagged (move it with engine vjoy map --reset);
  • configure-vjoy sets the vJoy device up without them, e.g. vJoyConfig 1 -f -a x y z rz sl0 sl1 .... This is the one case where a device loses something: an avoided axis the table does not use.

#vJoy configuration

engine vjoy status|plan show per vJoy device what the table needs and what it has. engine vjoy configure-vjoy runs vJoyConfig <n> -f -a x y z rx ry rz sl0 sl1 -b <buttons> -p <hats> for each device that lacks something - one administrator prompt for all (several devices go through one elevated engine vjoy elevated-run). The new configuration is the union of what the device has and what the table needs (all eight axes as soon as one is used, buttons in steps of 32, continuous hats), so a device never gets smaller. Afterwards export the virtual games again: games may list a reconfigured vJoy device anew, and adding a second vJoy device can change the first one's DirectInput identity (it gets a HID collection number).

vJoy's maximum. A vJoy device offers up to 8 axes, 128 buttons and 4 hats (16 devices). JoyPro plans for that maximum: the table and the virtual functions use buttons 1-128; what the configured device lacks shows as "needs" (status, plan, the page). engine vjoy configure-vjoy --max [--device N] [--dry-run] (GUI: "Set up vJoy for maximum" on the Overview, shown while a device has less, asks first) gives every vJoy device JoyPro uses vJoyConfig <n> -f -a x y z rx ry rz sl0 sl1 -b 128 -p 4 (force feedback kept; an axis a virtual game must not see, Battlefield's Rx/Ry, stays out unless the table uses it). Windows must restart before a vJoyConfig change takes effect (vJoy asks for it; often every change needs a restart); JoyPro never restarts Windows and the result says so. engine vjoy status reports AtMaximum per vJoy device. Tests only ever run the dry run.

#What a game reads of one joystick

JoyPro sets vJoy up for 128 buttons, but a game may read less: DirectInput's DIJOYSTATE has 32 buttons, DIJOYSTATE2 128; some games read one hat or none. engine/VJoy/GameInputLimits.cs keeps what is known per game, with the confidence (verified = JoyPro's game code enforces it or it was read from the game's files/binary, documented = the game's own docs or help, reported = players/forums) and the source; engine vjoy limits [--game g] lists it, the status JSON has InputLimit and LimitWarnings per game. Where a game's table slots or virtual function outputs lie above what it reads, the plan, engine vjoy status, functions list|add and the game's line on the page warn: "Arma 2: Operation Arrowhead reads only the first 32 buttons of a joystick: the virtual function outputs on button 40 on vJoy 1 will not work there." Unknown limits never warn. Lower button numbers come first everywhere (slots and function outputs take the lowest free one), so such games keep working while the table is small.

Game Buttons Axes Hats Confidence Note
DCS World 128 8 4 documented
IL-2 Great Battles 128 8 4 documented 128 since 5.204
IL-2 Cliffs of Dover / Blitz 128 8 1 documented 128 since 5.025; one hat per device in the file format
IL-2 1946 32 8 4 reported 4 hats shared by all devices
Falcon BMS 128 8 2 documented 128 with g_nButtonsPerDevice 128 (4.37 launcher), else 32; two 8-way hats in all
FSX / Prepar3D 32 8 ? reported
MSFS 2020/2024 ? 8 1 (4-way) documented more than 32 in the sim, SimConnect add-ons see 0-31; JoyPro writes one hat
X-Plane 11/12 160 25 1 verified further hats become buttons
ACE COMBAT 7 32 8 4 (4-way) documented the game's Input.ini help
Arma 2 / OA 32 8 1 verified DIJOYSTATE
X4: Foundations 64 8 1 verified the game's input tables
G-Rebels 96 24 0 documented Unreal's Raw Input plugin
VTOL VR (BYOJoystick) 128 8 4 (4-way) verified
ACE COMBAT 8, Hell Let Loose: Vietnam - - - documented XInput only: virtual Xbox pad

Not known (no warning): Star Citizen (sources conflict), War Thunder, Arma 3, Arma Reforger, Battlefield 6/2042 (the enum has 36 buttons, players see about 18), Elite Dangerous (players report 32, Joy_41 works), IL-2 Korea, WARDOGS, the Rewired games (Nuclear Option, Tiny Combat Arena).

#HidHide

HidHide's configuration is global: a cloak switch, hidden devices (device instance paths) and a program list, which is an allow list (only listed programs see hidden devices) or, in inverse mode, a block list (only listed programs lose them). JoyPro:

  • uses the block list with the executables of the virtual-mode games, so only those games stop seeing the physical devices; JoyPro's forwarder, JoyPro, SimHub, Discord and every other program keep seeing them;
  • keeps an allow list the user already uses (inverse off, cloaking on, own entries): then JoyPro's forwarder and JoyPro are allowed and every other program loses the hidden devices while the session runs (the page says so);
  • parks the user's own entries when cloaking was off (dormant): they are taken off the lists for the session and put back exactly afterwards, so switching cloaking on does not wake up an old setup (for example a hidden vJoy or a blocked MSFS);
  • never hides a vJoy device the games need (a hidden one is shown for the session and hidden again afterwards), and takes a trusted program (the forwarder, JoyPro) off a block list for the session;
  • hides the physical devices by the instance path HidHide itself reports (HidHideCLI --dev-gaming), falling back to one derived from the HID path;
  • finds the game executables in the game's installation (marker files and process names, a few levels deep), plus the ones set with engine vjoy exe <game> --add <path> and the running game's executable when the GUI starts for it.

Reading HidHide: one HidHideCLI query per call (--cloak-state, --inv-state, --app-list, --dev-list; combined queries and --dev-gaming can hang without administrator rights), each with a time limit (JOYPRO_HIDHIDE_TIMEOUT_MS, default 8 s); a call that runs over is ended with its child processes, so no HidHideCLI is ever left running (a hung one makes every other HidHideCLI call fail with "Access is denied"). If another HidHideCLI is already running, JoyPro does not start one and says so. A part that cannot be read (time limit, "Error code 0x0005 ... Access is denied" - the hidden-device list needs administrator rights) is unknown, never "off" or "empty": engine vjoy status shows it as unknown, a dry run says its plan is partial and which parts are missing, and a real session or restore stops with nothing changed. A journal whose "previous" lacks the inverse mode never has the inverse mode set back.

Program entries HidHide itself cannot name: HidHideCLI --app-list prints an entry whose stored image path lies on a volume that is not mounted any more (volume numbers change when drives are added) as --app-reg "", elevated or not. Such entries are part of a complete answer (2.6.0; before, they made the program list "unknown" and no session could start - a PC can have several): JoyPro counts them (UnnamedApps in the status JSON, "(+N HidHide cannot name)" in the text), leaves them as they are (they cannot be removed or added by path and name no program on a drive of this PC), says so in the plan, and checks after apply and restore that their number is the same.

Changing HidHide is one elevated step (one UAC prompt; never bypassed): apply-hidhide, restore-hidhide and recover start the engine elevated (engine vjoy elevated-hidhide, the request passed on its command line, not in a file), and that process does everything: reads HidHide completely, resolves the device instance paths (--dev-gaming), writes the journal, runs all changes in one HidHideCLI call, reads back, compares and writes its result file for the caller. Nothing that needs the rights runs outside it. Before the change JoyPro writes a journal (<data>\VirtualJoystick\hidhide-session.txt, <data> = JOYPRO_DATA_DIR or %LOCALAPPDATA%\JoyPro2) with the state before, what it adds, what it parks and the owner process (the GUI's pid and start time). After the call it reads HidHide back and compares. Restore undoes exactly the journal's changes against the configuration found then (entries the user added meanwhile stay), cloaking off first, and moves the journal to history\. Order on apply: lists first, cloaking last; on restore: cloaking off first - so nothing is hidden while the lists are half done.

HidHideCLI refuses a whole call silently (2.7; it showed as a UAC prompt every 2 minutes): it checks every command before it runs it and stops at the first it refuses, prints the reason on stderr, applies nothing of the call (CommandInterpreter::Start returns before ApplyConfigurationChanges) and still exits with 0. Its checks (HidHideCLI source, Commands.cpp, Utils.cpp, Volume.cpp): a program path must be fully qualified, end in exactly .exe, .com or .bin (case sensitive), and start with a volume mount point in its exact case ("The file name should be located on a storage volume (volume is case sensitive)."): Steam's own spelling c:\program files (x86)\steam\... is refused, and with it cloaking, the hidden devices and every other program of the call. JoyPro therefore sends program paths with an upper-case drive letter, leaves out (with a note) any path or device HidHideCLI would refuse (HidHideCliRules), treats exit code 0 with text on stderr as "refused" (HidHideCli.Rejected, the reason in the result), and when the read-back shows that nothing changed it leaves no session behind (no journal, no restore, no recover prompt later). The fake CLI of the tests refuses exactly like the real one.

Prompts, at most one per explicit action: no HidHide step for games that read only Xbox controllers (ReadsOnlyXbox, e.g. ACE COMBAT 8, Hell Let Loose: Vietnam: they never see the physical sticks) - with only such games in virtual mode apply-hidhide says "HidHide is not needed" and starts nothing elevated; no prompt when HidHide, read without administrator rights, already is as needed (apply-hidhide) or already has its previous configuration (restore-hidhide, recover: only the session record goes). When the read without the rights is not complete, the elevated step decides as before. In the GUI a failed start (declined prompt, refused call, mapping not ready) is never repeated by itself: auto start gets one try per game start and then waits until the game has ended, the page shows the reason and Try again. A partial HidHide result does not stop forwarding (the page warns that the game may also see the physical devices); only a result that leaves a vJoy device hidden from the games with cloaking on (Blocking) restores HidHide and starts nothing.

Crash safety: a journal whose owner process is gone is stale. The GUI checks the journal when it starts and restores a stale session at once (engine vjoy recover, one prompt); apply-hidhide refuses while a stale session waits. Closing JoyPro stops the forwarder and restores HidHide through an engine process that outlives the window. If the prompt is declined, the next start does it. By hand: engine vjoy restore-hidhide, or in the HidHide client untick "Enable device hiding".

#Virtual functions

Per game in virtual mode (vJoy or Xbox pad) the user adds functions that the forwarder evaluates every pass between the physical inputs and the virtual outputs - Joystick Gremlin-like features inside JoyPro's virtual mode.

Type id Name Inputs Outputs Settings
bands ≡ Axis bands in (axis) band1..bandN (buttons, each hold / enter / leave / both) edges (N-1, 0..1), hysteresis, pulse length
cycle ↻ Button cycle next, prev (opt.), reset (opt.) step1..stepN pulse or hold (selector), wrap or stay, pulse length
toggle ◐ Toggle (latch) in out (latched) on or off at start
switch ⇅ Switch to on/off pulses in (maintained switch) on, off (pulses) pulse length, pulse the position at start
presses ⋯ Short / long / double press in short, long, double (all optional) long after, double within, long = pulse or hold
shift ⇧ Shift layer shift, in1..inN (any kind) out1..outN (shifted), base1..baseN (unshifted; default: the input's own slot) hold or toggle
merge ⋈ Merge two axes a, b (axes) out difference / sum / average / larger / smaller, invert A/B
split ⋔ Split an axis in low, high (axes) split point
curve ∿ Axis curve in out JoyPro's axis tuning (dead zone, saturation X/Y, curvature, invert, slider; AxisModels.EvaluateDcs)
axis-buttons ⇔ Axis ends to buttons in low, high (hold / enter / leave / both) end zone, hysteresis, pulse length
axes-hat ✛ Axes to hat x, y hat deflection, 4 or 8 ways
buttons-axis ± Buttons to axis up, down, centre (opt.) out (axis) speed (travel/s), start, spring back speed
hat-axes ⊹ Hat to axes hat x, y (axes, opt.) deflection (a direction holds its axis out while held, a diagonal both)
encoder ⟳ Axis to encoder pulses in up, down step, pulse, gap, queue
turbo » Turbo (repeat) in out pressed for, released for, while held or press on/press off
macro ▶ Macro trigger out1..outN, keys steps (after ms: tap/press/release an output or key, hold ms), once or repeat while held
hat-buttons ✣ Hat to buttons hat up, right, down, left, 4 diagonals (opt.) 4 ways (a diagonal presses both neighbours) or 8
buttons-hat ⊕ Buttons to hat (8-way from 4 switches) up, right, down, left hat diagonal settle time
remap → Remap in (any) out1..out8 (follow the input; a button on an axis = full/rest, an axis on a button = past half) invert an axis
mode ⇆ Mode switch in (button) - switch to / hold (temporary) / toggle / cycle / back; the target modes

Inputs are physical inputs (JOY_X .. JOY_SLIDER2, JOY_BTN<n>, POV<n>, a hat direction JOY_BTN_POV<n>_<dir>) or another function's output (device fn:<id>, input the output's role, see "Function chaining"); outputs are vJoy inputs (JOY_BTN<n>, an axis, POV<n> on a vJoy device), controls of the virtual Xbox pad (XB_A, XB_LT, XB_LX, XB_DPAD, ...) or keys (KEY_A, KEY_LCTRL, KEY_F1, ... - only with the function's Keyboard switch on; keys go out through SendInput with scan codes and only with a real sink, never in a dry run or the GUI's Test).

Storage and planning. Functions live in the profile with the game's virtual-mode settings (VJoySettings.Functions[game], ids f1, f2, ...). Their vJoy outputs are reserved in the table: the planner never gives them to a physical input, they count in what the vJoy device must offer ("+ N function output(s)"), and an output that collides with a slot or another function is flagged. New functions get free outputs (functions add, or an output set to auto): the lowest free button/axis/hat on devices first..last (vJoy's maximum assumed; an output above what the device has now says "Set up vJoy for maximum", one above what the game reads says so too); on the Xbox pad free controls the game's pad table does not use. A shift layer's unshifted output defaults to the input's own slot, so the layer takes the input away from it while shifted. A function's output is bound in relations like any vJoy input (device vJoy Device {GUID}, input JOY_BTN<n>; the editor's "Bind relation" runs engine binds set); exports leave those binds as they are. The physical devices a function reads are hidden by HidHide like the table's.

Evaluation. engine/VJoy/VirtualFunctions.cs (model, catalog, tokens, resolution) and engine/VJoy/VirtualFunctionRuntime.cs (evaluation, simulator) are plain C# 7.3, compiled into the engine, JoyPro.VJoy and the GUI: the CLI test, the editor's preview and the forwarder run the same code. forwarder-config writes the functions resolved (source index, kind, index; vJoy device index) - of the game that started (--game, the GUI's auto start) or of every vJoy game and the Xbox game (Start by hand) - and adds their devices to the sources. The forwarder copies each changed device state into the runtime, calls Tick every pass (also without a change: pulses, turbo, macros, long presses and the incremental axis need the clock) and merges the outputs: every vJoy button, axis and hat a function owns is replaced by what the functions wrote (two functions on one button combine), the Xbox report likewise. Timing resolution is one pass (at 144 Hz 6 ms): a pulse lasts its length rounded up to passes, a macro press is held for at least one pass. A device that disappears releases the functions' buttons; Stop releases every key and output. Nothing is allocated per pass.

CLI. engine vjoy functions types|list|add|set|remove|test (--json by default, --text), see engine/docs/ENGINE_CLI_WIKI.md:

engine vjoy functions add --game DCS --type bands --name "Throttle detents" --input "in=VPC Throttle {GUID}|JOY_Z" --edges 0.05,0.95 --output band3=auto:enter
engine vjoy functions set --game DCS --id f1 --param hysteresis=0.02 | --spec @function.json
engine vjoy functions test --game DCS --id f1 [--stream "0:in=0.5; 100:in=0.97"] [--rate 240] [--duration 600]
engine vjoy functions remove --game DCS --id f1

test simulates (default stream per type: an axis sweep, presses, ...) and lists every output change; nothing goes to vJoy, the pad or the keyboard.

GUI. Virtual Joystick page, tab Functions: the types with icon and one line each, "Add function" (game, type), the list (outputs, state, live state), and the editor: name, on/off, keyboard output; a node view in the style of the force feedback editor (inputs -> function -> outputs, lit while an output fires); the axis band editor (the axis travel as a bar with the bands and their outputs, draggable edges, the hysteresis zones, the input marker); inputs (device, input), outputs (target, vJoy device, band mode, "Bind relation"), settings (sliders/choices), macro steps, the curve view; Try it runs the function in the editor (sliders, press buttons, hat directions; a timer only while it is on), and while Test or Start runs the forwarder's fn lines show the real state (LIVE). Save stores it through the engine.

#Function chaining

An input of a function can read another function's output instead of a physical input: --input "in=fn:f1|band2" (CLI), the input's device list in the editor (⚙ f1 Throttle detents, with that function's outputs as inputs), or a drag in the graph. Examples: an axis band that feeds a toggle, a curve that feeds a split, a tempo container whose long press starts a macro (the Gremlin import builds these). The runtime evaluates the functions in dependency order every pass (a function after the ones it reads), so a chained input sees the value of the same pass, without a pass of delay; every output keeps its value of the pass (VfOut.Level, HatLevel). An output that only feeds other functions needs no virtual target (it is "internal": no vJoy button is used, the editor says "feeds f2 only"). Loops (a function reading itself, directly or through others) are refused by functions add|set ("These functions would read each other in a loop: f1 "A" -> f2 "B" -> f1 "A". Chain them one way only. Nothing was saved.") and by the graph before the engine is asked; the runtime leaves any loop out with that message. Removing a function clears the inputs that read it. A chained input is no device: it is not a forwarder source and HidHide hides nothing for it.

#Modes

Like Joystick Gremlin, a game's functions can have named modes (layers), e.g. Default, Combat, Landing; a mode may inherit from another (engine vjoy modes add --game DCS --name Combat --parent Default, set --parent|--rename, remove, start, list; GUI: the Modes card of the Functions tab). Stored per game (VJoySettings.Modes[game], a VfModeSet); a function lists the modes it works in (functions set --modes Combat,Landing, the editor's "Works in modes"; none = every mode).

  • A function in a mode also works in the modes that inherit from it, unless such a mode (or one closer in its line) has its own function on the same input; a function without modes works in every mode unless the current mode's line has its own function on that input. So "button 1 -> vJoy 1 everywhere, but vJoy 30 in Combat" is two remaps: one without modes, one in Combat.
  • A mode switch function (type mode) changes the mode: switch to a mode, hold it while the button is held (back on release; the switch keeps running in the held mode to see the release), toggle (the next press goes back), cycle through a list, back to the previous mode. Targets: --switch-modes Landing (the editor's "Mode to switch to").
  • A switch takes effect after the pass that asked for it. A function that becomes active starts from its inputs as they are (Prime): a button held through the switch is no new press, so one press never switches twice.
  • Only the functions of the current mode run; the outputs they own are released while they do not run, so a remap in Combat that writes the input's own table slot takes the slot away in the other modes (Gremlin's per-mode remap).
  • The forwarder starts each game in its start mode (modes start, else the first) and reports mode <game> <mode> at start and on every change; the page shows "Mode now (live)" and marks the running mode. Started by hand with several virtual games, each game keeps its own modes (one mode group per game).

#Editing in the graph

The Functions tab shows every function of the chosen game as a node (VirtualFunctionGraphView, the default view of the right side; "Editor" shows the function opened with Edit): columns by dependency, inputs on the left edge of a node with what they read, outputs on the right edge with their target, wires from an output to the inputs that read it, the modes each node works in. Drag from an output dot to an input dot of another function to connect (a wrong kind or a loop is refused with a message), click a wire (or the input it ends at) and then its × or Delete to disconnect, × on a node removes the function (asks first), double-click opens the editor. Physical inputs, outputs, settings, modes, macro steps and curves are edited in the editor's rows; "Add function" adds nodes. Every change goes through the engine.

#Coming from Joystick Gremlin

engine vjoy import-gremlin <profile.xml> --game <game> [--dry-run] [--replace] [--vjoy-device N] (GUI: "Import a Gremlin profile..." on the Functions tab; a dry run shows its report first, Import saves) reads Joystick Gremlin R13 profiles (profile version 9-13: <devices><device><mode><button|axis|hat><container><action-set>) and R14 profiles (profile version 14: <inputs> bound to a root action of the <library>, <modes>), and makes the game's modes and virtual functions from them:

Gremlin JoyPro
devices (by device-guid, else by name) the connected or known device with that DirectInput instance GUID, else by name; unknown: kept as Name {GUID} (listed)
modes, inherit, start mode modes with their parents and the start mode (only when the profile has more than one mode)
remap button / axis / hat -> vJoy remap (several remaps and keys on one input: one remap with several outputs)
response curve + axis remap curve: centre dead zone, saturation X, the spline sampled into an 11-point user curve; inverted when it falls
map to keyboard remap with key outputs (keyboard output on)
macro (keys, pauses, vJoy buttons; repeat single / hold) macro with steps, keyboard output on when it types
switch / temporary / cycle / previous mode, change mode mode (switch, hold, cycle, back)
merged axis (average, sum, minimum, maximum) merge
tempo container (short / long) presses; a set that is not a lone button remap is chained to the long/short output
double tap presses with short and double
chain container cycle (pulse per step)
smart toggle toggle
hat buttons (4 / 8) hat-buttons
axis range as a button (virtual-button limits) bands with that band, chained to the set's actions
hat directions as a button the input JOY_BTN_POV<n>_<dir>

Listed as not imported (never dropped silently): activation conditions (the actions are imported to run always), mouse actions, sounds and speech, pause/resume, user plugins (Python), keyboard devices and keyboard inputs, vJoy devices as inputs, a chain's timeout, macro steps on axes or the mouse, more than 8 outputs on one input, unknown actions and containers, devices that are not connected (imported on Name {GUID}). Listed as imported, but different: a relative axis remap (absolute), axis scaling, asymmetric dead zones or curves (one value for both sides), Bezier handles, a tempo "on press" (JoyPro fires the short press on release), the chain's step held while the button is held (a pulse), a smart toggle's long hold, macro repeat toggle / count, a hat virtual button with several directions, an axis range "from one direction". Gremlin numbers a device's axes 1..8; JoyPro takes them as X, Y, Z, Rx, Ry, Rz, Slider 1, Slider 2, which is Gremlin's order when the device has all eight - check the axis inputs of a device with fewer axes. The vJoy outputs keep Gremlin's vJoy device unless --vjoy-device (or the tunnel device of Settings) moves them; outputs on a button the table already uses are warned about (bind the relations to the outputs like any vJoy button). The R14 reader follows R14's library structure (actions with typed <property> values and child action ids); anything it does not know is listed.

What a Gremlin user does in JoyPro: set the game to vJoy, import the profile, bind the game's relations to the vJoy outputs (or keep the game's binds where they are: the outputs are the same vJoy buttons and axes), Start. HidHide and the forwarder replace Gremlin's own device hiding and its running in the background.

Performance (JoyPro.VJoy bench, release build, 4 synthetic sources changing every pass, 50 functions of all types): 144 Hz: 9.7 us per pass on average (p99 29 us), 0.47 % of one core (table only: 0.31 %); 240 Hz: 8.5 us average (p99 31 us), 0.31 % of one core; 0 bytes allocated in the loop. The GUI test LoopBenchmarkWithFiftyFunctions measures the same pass without the timer (about 4 us per pass).

#The forwarder (JoyPro.VJoy.exe)

JoyPro.VJoy run --config <file> [--sink vjoy|dry] [--xbox-sink vigem|dry] [--rate Hz] [--mode event|poll] [--parent-pid N] [--protocol] [--monitor] [--duration s] [--vjoy-dll path]
                [--priority below-normal|normal] [--stats-seconds N] [--fake-sources idle|stream|noisy]
JoyPro.VJoy devices [--json]      (DirectInput game controllers with instance GUID and HID path; read-only)
JoyPro.VJoy refresh-rate          (the fastest display's refresh rate, at least 60)
JoyPro.VJoy bench [--functions 50] [--rate Hz] [--seconds 10] [--sources 4]   (the loop with virtual functions and synthetic sources; no device, vJoy or key)
  • Reads every mapped device through DirectInput in non-exclusive background mode with JoyPro's data format (the first 176 bytes of DIJOYSTATE2: X Y Z Rx Ry Rz Slider Slider by GUID, 4 POVs, 128 buttons - the numbering of JoyPro's and DCS's binds). DIPROP_RANGE is set to vJoy's axis range, so axis values go over 1:1; JoyPro's curves, dead zones and inversions stay in the game's settings.
  • At most one pass per period (the rate: default the fastest display's refresh rate, minimum 60 Hz; the period is exact, 144 Hz = 6.94 ms, a one-shot high-resolution waitable timer armed after every pass). A DirectInput change event that comes a period or more after the last pass runs a pass at once (a button goes out at once). A pass that found a change stops watching the change events until one period after it; the pass at the end of that period takes everything that came meanwhile. So a device that reports all the time - real sticks do while nobody touches them (for example a VPC stick and throttle send 180 and 300 reports a second with changing values, the Crosswind 250 and the WinWing panel 100 identical ones, a Rhino force feedback base up to 1000) - costs one pass and one wake-up per period, not one per report, and a button on another device waits at most one period. --mode poll uses the timer only.
  • A pass reads only the devices whose event fired (and DirectInput polled devices, DIDC_POLLEDDEVICE, which are also the only ones Poll() is called for). Every 100 ms a pass reads every device as a safety net for a missed event; a change found that way is counted in the stats line (missed=; 0 with six real devices).
  • Rests when nothing happens: when every device signals its changes, the last pass found no change and no virtual function needs the clock, the timer waits 100 ms (a safety poll); the next change event wakes the loop at once. A virtual function that waits for a time (a pulse end, the next turbo phase, a long press or double-press window, a macro step, a diagonal settle: VfRuntime.NextDueUs) sets the timer to that time instead of running every period; only a moving incremental axis, an encoder queue and a mode change need the very next pass. A resting setup costs 10 passes a second. --mode poll never rests.
  • Performance (2.6.0 budgets, ForwarderSoakTests): the real JoyPro.VJoy (release build, 144 Hz, dry sink, 4 synthetic devices, 52 virtual functions of every type incl. a chain and two modes), CPU from the process's cycle counter (cycles-ms=; Windows' process times, cpu-ms=, are sampled at the clock tick and charge a loop that runs for microseconds at random: 0.000 % or 0.5 % over 20 s): resting (nothing changes) 0.19 % of one core, 10 passes/s; every device changing every pass 0.52 %, 144 passes/s, 144 vJoy writes/s; noisy (one device signals a change 1000 times a second with noise on every axis, like a force feedback base nobody touches) 0.56 %, 144 passes/s, 144 wake-ups/s; private bytes about 8 MB and handles flat (no growth), 0 bytes allocated by the loop in every phase (30 s per phase, after a 12 s warm-up). Budgets: resting 0.5 %, streaming 1.5 % of one core, memory growth at most 1 MB, handles at most +5, no loop allocation after warm-up, at most one pass per period and, noisy, one wake-up per pass.
  • Real devices (2026-11-01, six connected devices, the vJoy live test's table: 6 button slots, 23 virtual functions incl. a running turbo, a mode cycle and a moving incremental axis, 144 Hz, nobody touching anything, DCS not running): before the fix the event wake-ups of the noisy devices gave ~292 passes, ~580 wake-ups and ~268 vJoy writes a second, every pass reading all six devices: 3.3 % of one core with the real vJoy sink, of which the loop thread 1.2 %. Now 144 passes, ~150 wake-ups, ~132 vJoy writes and ~290 device reads a second: the loop thread costs 0.25-0.4 % with the dry sink and ~0.7 % with the real vJoy sink (an UpdateVJD costs ~25 us), the process 2.6 %. The rest is DirectInput itself: its own reading thread takes every HID report of every acquired device (~25 us each, mostly in the kernel), whether it changes anything or not - one resting device costs the process 0.07 % (VKB, 13 reports/s) to 0.7 % (VPC throttle 300/s, Crosswind 250/s), JoyPro.VJoy with no device 0.17 %. That cost belongs to reading these devices at all: a game that reads them natively pays it in its own process, and in virtual mode HidHide hides them from the game, so it moves from the game to the forwarder rather than adding to it. Lowering it would need JoyPro's own HID reader that drains the reports once per period instead of DirectInput (not done: DirectInput's button and axis numbering is what the binds use).
  • Below normal priority: the process runs BelowNormal (its loop thread one step above the process, still below a game's normal threads), so the game always comes first; --priority normal for a test.
  • Writes a vJoy device only when its position changed (UpdateVJD with the whole JOYSTICK_POSITION_V2). Neutral at start (axes centred, buttons up, hats centred) and at the end.
  • No allocation per pass: native buffers, preallocated handles, structs; the stats line reports the loop thread's allocated bytes (stays at the startup value). ~35-40 MB working set, handles flat.
  • A device that disappears releases its buttons and centres its hats (axes keep their last value); it is opened again when Windows reports a device change (WM_DEVICECHANGE), else once a minute (opening a missing device costs DirectInput a device scan).
  • Ends on stop (stdin), when stdin closes (--protocol), when the parent process exits (--parent-pid), on Ctrl+C or after --duration. The default sink is dry (nothing goes to vJoy); only --sink vjoy uses the vJoy devices, and it refuses a vJoy device another feeder holds. JOYPRO_VJOY_DRY=1 forces dry.
  • Protocol lines: ready ... (with priority=), source <i> connected|missing|lost <device>, mode <game> <mode> (at start and on every change), stats passes= hz= wakes= changes= writes= sources= loop-alloc= cpu-ms= ws-kb= handles= private-kb= gc-kb= idle= idle-switches= plus reads= (device reads), missed= (changes only the safety read found), cycles-ms= (the process's CPU from its cycle counter) and loop-ms= (the loop thread's) (every second while the live view is on, else every 5 s, --stats-seconds; once at the end), out <id> <8 axes> <128 buttons hex> <4 hats> (15/s while the live view is on), fn <id> <first input 0..1000> <state> <outputs on, bit mask> per virtual function (15/s while the live view is on), error ..., exit <reason>. The ready line says functions=<n> (and keys=on when a function may type).

#GUI: Virtual Joystick page

  • Overview: what it is and how to use it in plain words; status of vJoy (version, devices), HidHide (state) and JoyPro's session; Set up vJoy for the table (only when needed), Restore HidHide (when a session is active); "What this page needs": the vJoy, HidHide and ViGEmBus cards of docs/components.md (status, license, one-click install); per game a Native/Virtual switch (the games of the profile and every game in virtual mode); options "Hide the real devices" (HidHide on/off) and "Start and stop by itself when a game set to Virtual starts and ends".
  • Mapping: the table (physical input, virtual input, the relations that use it, state), Update mapping.
  • Functions: the virtual functions (see "Virtual functions"): left the types and "Add function", the game's Modes (rename, inherits, at start, remove, add; the running mode live), "Coming from Joystick Gremlin?" (import with the report first) and the list (outputs, modes, what a function reads and feeds); right the graph of the game's functions ("Editing in the graph") or the editor of one function. Overview also has "Set up vJoy for maximum" and, per game, what it reads of a joystick with the limit warnings; its Status card names the vJoy device JoyPro tunnels into.
  • Live test: bars for the eight axes, pressed buttons and hats of each vJoy device as the forwarder writes them, the forwarder's stats and log.
  • Start: updates the table, writes the forwarding table, hides the physical devices (one prompt), starts JoyPro.VJoy --sink vjoy. Test: the same without HidHide and with the dry sink (nothing changes). Stop and an unexpected end of the forwarder restore HidHide. vJoy: press Start before you start the game: games often look for devices only once at start. Exception, the virtual Xbox pad of Hell Let Loose: Vietnam and ACE COMBAT 8: press Start once the game's title screen shows (or Stop and Start there), see "When to start the pad" under "Virtual Xbox pad". The page says so under Overview step 3 and in the tooltips of Start and of the auto start (VirtualXboxPadTimingNote): the game set to Xbox pad by name, nothing when neither is, a note naming both while the games are not loaded (VirtualXboxPadTimingTests).
  • Auto start: only while it is on and a game is in virtual mode, JoyPro looks for the games' processes every 3 s and starts (with the running game's executable added to HidHide's list) and stops by itself.

#CLI

See engine/docs/ENGINE_CLI_WIKI.md (engine vjoy ...). --dry-run everywhere that changes something. JOYPRO_VJOY_FAKE=<folder> replaces vJoy and HidHide by files in that folder: vjoy.txt (installed=<version>, device=<n> axes=x,y,... buttons=<n> povs=<n> discrete=<n> ffb=yes|no), hidhide-state.txt (HidHideCLI's own format), hidhide-gaming.json (--dev-gaming), hidhide-missing (file: not installed), hidhide-exit.txt (exit code of the next apply, -1223 = prompt declined, -1460 = hung), hidhide-deny.txt / hidhide-hang.txt (parts cloak, inverse, devices, apps that are denied without administrator rights / never answer); the elevated step runs as a normal child process then. The calls JoyPro would run go to hidhide-calls.txt and vjoyconfig-calls.txt. JOYPRO_HIDHIDE_CLI=<exe> uses another HidHideCLI (the smoke test uses a script that hangs and denies). In vjoy.txt, vigem=<version> fakes an installed and running ViGEmBus (missing, empty or vigem=no: not installed). JOYPRO_HLLV_SETTINGS=<ini> replaces Hell Let Loose: Vietnam's GameUserSettings.ini (gamepad layout), and JOYPRO_OODLE_DLL=none keeps its catalog refresh from using any Oodle library (another game's is used only with the user's consent, refresh-db --oodle-dll; docs/games/hll-vietnam.md "Oodle").

#Tests

  • engine/tests/smoke/vjoy.ps1 (part of the engine smoke test): table rules and stability, capacity over two vJoy devices, vjoy configure (dry run, one call, never again when it fits), DCS export to the vJoy device incl. modifier and hat, profile keeps the physical devices, import back to physical, missing vJoy stops the export, HidHide dry run, declined prompt, block list with parked entries and vJoy shown, exact restore, stale owner and recover, the user's allow list, denied/hanging HidHide reads (unknown, never "off"; nothing changed; session kept), a journal with an unknown inverse mode, the real CLI path with a stand-in that hangs and denies (time limit, ended with its children), the forwarder table, a dry JoyPro.VJoy run (no allocation in the loop), back to native.
  • gui/JoyPro.Gui.Tests/VirtualJoystickTests.cs: the HidHide state machine (enable/disable, crash of the owner, crash while applying, declined prompt, allow list, inverse switch, a second game, journal round trip, unreadable parts, partial dry run, unknown previous inverse mode) and the page against a fake engine that runs the same state machine (status, toggle, Test, Start/Stop, forwarder ending by itself, recovery at start, auto start, shutdown). VirtualJoystickForwardingTests.cs: the forwarding table (axes, buttons, hats, discrete hats, release, no allocation, JOYSTICK_POSITION_V2 layout).
  • Virtual functions: engine/tests/smoke/vjoy.ps1 section 7 (add with free outputs, reservation against the planner, test with the default and a given stream (pulse length), keys only with keyboard output, forwarder-config, a dry JoyPro.VJoy run with a function (fn lines, no allocation), per-game limit warnings, limits, configure-vjoy --max as a dry run only, remove). gui/JoyPro.Gui.Tests/VirtualFunctionRuntimeTests.cs: every function type with simulated input streams (band edges with hysteresis, enter/leave pulses, cycle wrap/back/reset/hold, toggle and switch, short/long/double timing, shift layers with frozen axes and latch, merge/split math, the curve, axes to hat, the incremental axis rate and spring, encoder pulses, turbo, macro timeline and keys, hat helpers), the merge into the vJoy positions (owned outputs, a shift layer over a slot) and the Xbox report, the forwarder table's JSON, no allocation per Tick, a loop benchmark. VirtualFunctionsGuiTests.cs: the Functions tab against a fake engine (list, add, edit, preview, save spec, live lines, bind, remove, set up for maximum, limits) and offscreen renders of the editors (%TEMP%\JoyPro2.Gui.Tests\vjoy-functions; the whole tab with JOYPRO_VJOY_FUNCTIONS_PAGE_PREVIEW=1).
  • Joystick Gremlin parts: VirtualFunctionChainModeTests (a chained output in the same pass, order independent of the list, loops refused with the message, validation against the game, internal axes, remap, modes with inheritance and takeover, cycle / hold / back, a held button no new press, two games' modes, NeedsClock, NextDueUs (the time of the next turbo edge / long press / pulse end, and ticking only at input changes and at NextDueUs gives the same outputs as ticking every millisecond), no allocation per pass with chains and modes); GremlinImportTests (the fixtures engine\tests\fixtures\gremlin\r13-basic.xml, r13-modes.xml, r14-profile.xml, written from Gremlin's documented format: devices by GUID / name / not found, curves, keys, merged axes, every container, macros, axis ranges, mode changes, the report, the imported profile running with its modes, --vjoy-device, refusal of other XML); VirtualFunctionGraphModesGuiTests (the Modes card, the editor's modes and function sources, the graph's connect / refuse / disconnect / remove / open, the import's report before saving, --vjoy-tunnel on every vjoy command, renders of the tab at 1280 and 2267 in dark and light to JOYPRO_VJOY_RENDER_OUT); engine\tests\smoke\vjoy.ps1 section 8 (modes CLI and a refused parent loop, chaining and a refused loop, forwarder-config with chain and modes, mode DCS Default and priority=below-normal from a dry run, import dry run / import / R14 / not a profile, the tunnel device in the status).
  • ForwarderSoakTests (the forwarder's cost, see "Performance" above): phases idle, stream and noisy (one synthetic device signalling 1000 times a second: at most one pass and one wake-up per period); always 30 s per phase; JOYPRO_FORWARDER_SOAK=1 runs 5 minutes per phase (JOYPRO_FORWARDER_SOAK_SECONDS), JOYPRO_FORWARDER_EXE picks the build (release for the numbers).
  • Nothing in the tests touches the real HidHide, vJoyConfig or a vJoy device: the GUI tests point every engine at a fake (JOYPRO_VJOY_FAKE) and start JoyPro.VJoy only with the dry sink and synthetic devices (ForwarderSoakTests).

#Limits and notes

  • Force feedback is not forwarded (vJoy's FFB would need a feedback loop back to the physical stick).
  • Started by hand, the functions of every virtual game run at once (each game with its own modes, but a shift layer of one game also acts while another runs); auto start runs only the started game's.
  • Verified live in DCS (2026-11-01, tools\e2e\games\VJoyLive.ps1, RunAll test vjoy-live, 58 of 59 checks): JoyPro's elevated HidHide step hid six flight devices from DCS only (dcs.log and the Controls page list the vJoy device and none of them; Wooting, HeadTracker, mouse stay), the export's binds show in the vJoy column, DCS's assignment panel caught a vJoy button pulsed by a chain of virtual functions running on real DirectInput sources (toggle on at start -> turbo), a chained mode switch cycled the modes of an imported Gremlin R13 profile, a Combat-only remap followed the mode, a buttons-to-axis output moved, all 17 imported Gremlin functions ran; restore-hidhide put HidHide back exactly (cloak, inverse, 19 devices, programs incl. 5 HidHide cannot name) and DCS listed the devices again. Forwarder cost there: 6 real sources (noisy devices: event wake-ups gave ~290 passes/s at 144 Hz) with functions that change an output every pass: 2.8 % of one core with the dry sink, 3.8-5.9 % with the real vJoy sink - above the 1.5 % streaming budget. Fixed in 2.6.0 (one pass and one wake-up per period, only signalled devices read, timed functions wake the loop at their due time): see "Real devices" under "The forwarder". The elevated step does not inherit JOYPRO_DATA_DIR: its log lines go to the user's own %LOCALAPPDATA%\JoyPro2\Logs.
  • Not verified on hardware yet: keys from SendInput in a game, the vJoy maximum setup (needs a Windows restart; never run by the tests), modes and chains driven by a person on real devices, a real Gremlin user's profile (R14 especially: the reader follows its structure, the fixtures are written from the documented format), the idle rest with real devices (that every HID device signals its changes) and the forwarder at below normal priority while a game loads every core.
  • Games that identify devices only by name or VID/PID cannot tell several vJoy devices apart.
  • HidHide blocks by executable path: a game started through another executable (a launcher that stays the game) must be listed with engine vjoy exe <game> --add. Microsoft Store games live in protected folders JoyPro cannot list.
  • Anti-cheat systems normally accept vJoy and HidHide (signed drivers), but a game may refuse virtual devices.
  • 4-way (discrete) vJoy hats are supported by the table, but JoyPro configures continuous hats; the discrete layout is not verified on a device yet.