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_URon the stick becomesJOY_BTN_POV2_URon 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 (
--prunedrops it,--resetstarts 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 Mlimits 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 "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
(
IGameDeviceLimitwithMaxJoysticks0 andSuggestedModexbox, andengine 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 explicitengine vjoy mode <game> native|virtual|xboxwins and is stored (nativeas 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--resetneeded): 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 asxboxWaiting; 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 kindhatdir). 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 asGamepad_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.PadBaseInvertinBindTuning.ResolveWithoutDetent): a throttle inverted for DCS still gives RT when pushed forward on the pad. ACE COMBAT 8'sPad_Pitchis 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.SampleofBindTuning.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 modelxboxpad(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 showlists them asXboxPadGames). - 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, andengine vjoy mapmoves 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 vigemcreates 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.ps1andAceCombat8Xbox.ps1therefore 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)withXB_*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):
- 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). - 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
yawon a device that is not pedals), else the rudder pedals. - 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 offlare, elsecms_switch:fwd, elsecm_dispense. - Menu D-pad (
IGamePadChords.DPadFunctions): ACE COMBAT gives wingman orders on the D-pad. "Buttons to hat" from the user's relations ofwingman,comm_menuorcomm_switchon 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. - 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 toXB_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). - 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.
- 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 8Pad_CameraYaw/Pad_CameraPitchon 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 typecentring); 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 asn/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 statusshows "one-device game:suggested" while such a game is native, and the status JSON has SuggestedMode,MaxJoysticksandDeviceLimitNoteper game.engine vjoy mode <game> nativewarns.- 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-vjoysets 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 reportsmode <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_RANGEis 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 polluses the timer only. - A pass reads only the devices whose event fired (and DirectInput polled devices,
DIDC_POLLEDDEVICE, which are also the only onesPoll()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 pollnever 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
UpdateVJDcosts ~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 normalfor a test. - Writes a vJoy device only when its position changed (
UpdateVJDwith 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 isdry(nothing goes to vJoy); only--sink vjoyuses the vJoy devices, and it refuses a vJoy device another feeder holds.JOYPRO_VJOY_DRY=1forces dry. - Protocol lines:
ready ...(withpriority=),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=plusreads=(device reads),missed=(changes only the safety read found),cycles-ms=(the process's CPU from its cycle counter) andloop-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 saysfunctions=<n>(andkeys=onwhen 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), startsJoyPro.VJoy --sink vjoy.Test: the same without HidHide and with the dry sink (nothing changes).Stopand 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.ps1section 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 (fnlines, no allocation), per-game limit warnings,limits,configure-vjoy --maxas 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 perTick, 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 withJOYPRO_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 atNextDueUsgives the same outputs as ticking every millisecond), no allocation per pass with chains and modes);GremlinImportTests(the fixturesengine\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-tunnelon every vjoy command, renders of the tab at 1280 and 2267 in dark and light toJOYPRO_VJOY_RENDER_OUT);engine\tests\smoke\vjoy.ps1section 8 (modes CLI and a refused parent loop, chaining and a refused loop, forwarder-config with chain and modes,mode DCS Defaultandpriority=below-normalfrom 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=1runs 5 minutes per phase (JOYPRO_FORWARDER_SOAK_SECONDS),JOYPRO_FORWARDER_EXEpicks 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 testvjoy-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 inheritJOYPRO_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.