From docs/sync-watcher.md in the repository (generated, always the current text).
When you change controls in a game that JoyPro manages, JoyPro asks after the game has closed whether to take the changes into your profile. Where several relations use that button (same device, input and modifiers), it asks which relation the change belongs to, or whether to make a new one. Only what JoyPro manages counts.
Settings > Games > Watch game configs (on by default) switches it off; then nothing is watched at all. Per game, the Start page's game cards have a Watch for changes box, see Which games are watched.
The GUI watches while it is open. To keep watching after it closed (or from Windows sign-in on), a tiny tray host takes over (Settings > Run in the background): Start with Windows (in the tray) and Close to tray, see Tray and autostart.
#How it works
- Every JoyPro export records the game's state. Right after a successful export (DCS, IL-2, Star Citizen and every
registry game, also exports that only write game-wide settings) the engine stores a fingerprint of the files (or
registry values) JoyPro manages in
<data>\Sync\<game>.json(<data>=%LOCALAPPDATA%\JoyPro2, orJOYPRO_DATA_DIR): size, write time and SHA-256 per file, and a baseline, i.e. hashes of every bind (plane, action, device, input, modifiers) and axis tuning the file holds, read with the game's own import. JoyPro's own exports therefore never ask anything. A file Windows refuses to read (a Microsoft Store install keeps its data EFS-encrypted and refuses a file without the EFS mark) is stamped by size and write time instead of its hash; it used to break the record, and MSFS 2024 stayed untracked (2.2.6 report). An import of a game that has no record yet records it too, so a game you only imported is watched from then on. Only games JoyPro exported to or imported from (or whose state was accepted) are watched, every config it exported to (also one exported to a custom path, and the config location you set withengine games config set), and never a game you marked as one you do not have (engine games install disable) or unticked on the Start page (Which games are watched). - The GUI (or, while it is closed, the tray host) watches those files (
gui\JoyPro.Watch\GameConfigWatcher.cs): oneFileSystemWatcherper config folder, filtered to the managed file names (LastWrite, Size, FileName), or a registry change notification for games that keep their controls in the registry. A change starts a 2 s debounce (a game'sSettleSecondsfromsync statuswhen it needs longer: the MSFS Microsoft Store save folder 10 s). - After the game has closed. When the debounce ends and one of the game's processes runs (by process name, or any
exe under the game's
ProcessFolders: MSFS StoreXboxGames\<game>\Content\,WindowsApps\<family>_), the watcher waits for itsExitedevent (no polling; only when Windows refuses that wait it looks again every 10 s), then waits 3 s more (games write their config while closing;SettleSecondswhen longer). - What changed?
engine sync status --game <id>compares the fingerprint (a file whose content is unchanged is no change, even with a new write time). If it changed,engine sync diff --game <id>reads the config into a scratch profile (the loaded profile is never touched) and compares it with the profile. No changes (only formatting, or only things JoyPro does not manage): the new state is accepted silently. Otherwise a dialog lists the changes. - The dialog: one line per change with a tick box and a choice: one of the candidate relations, (new relation)
with an editable name, or (ignore). It comes with a notice in the window ("A game changed its controls", an
information, not a warning); when JoyPro's window is not the active one (the user is on the desktop or already in
another program), its taskbar button flashes until the user switches to it. The focus is never taken. Take over runs
engine sync apply(the profile is saved), Not now keeps the changes for later (JoyPro asks again after the next change or start), Ignore these runsengine sync accept(the profile stays; the next export writes it over the game's changes). - Changes made while JoyPro was closed are offered at the next start (once the game is not running).
- With the GUI closed, the tray host checks the same way and shows a notification ("A game changed its controls"); clicking it (or the tray menu's Review entry) opens JoyPro2 with this dialog. See Tray host.
#Which games are watched
Every game card on the Start page ("Your games") has a Watch for changes box ("JoyPro notices when you change binds in this game and offers to take them over"); the section header has Watch all (ticked: all installed games are watched, empty: none, mixed: some; a click on a mixed box unticks all).
- Default: ticked for every installed game; a game JoyPro does not find has the box unticked and greyed (nothing to watch).
- Only explicit choices are stored, so a game installed later is ticked by itself, and a game the user unticked stays unticked, also after it was uninstalled and installed again. Ticking it again stores "watched".
- Where:
ui-settings.jsonnext towatchGameConfigs(%APPDATA%\JoyPro2, tests<JOYPRO_DATA_DIR>\settings):"watchedGames": { "WarThunder": false, "DCS": true }, keyed by the game ids ofengine games installs/engine sync status. The GUI writes it at each tick; the tray host reads it (and keeps it when its own Watching switch rewriteswatchGameConfigs). Code:gui\JoyPro.Watch\GameWatchChoices.cs. - Not "I do not have this game": that is
games-disabled.jsonof the engine, which hides the game everywhere and blocks import and export. An unwatched game keeps its card and still imports and exports; only the watcher leaves it alone. The engine is not involved (it never watches), so there is no engine command for it. - The master switch (Settings > Games > Watch game configs, also the Start page's Game watcher switch and the tray menu) still wins: off, nothing is watched whatever the ticks say; the ticks can still be changed and apply when it is on again (the Start page says so above the cards).
- Live: the GUI applies a tick at once without asking the engine again: it filters the last
sync status(GameWatchChoices.Filter) and hands the result toGameConfigWatcher.Update, which releases the unticked game'sFileSystemWatchers / registry wait at once and creates them for a ticked one. A game ticked again is checked once for what it changed while it was not watched (after it has closed, as always). Settings > Games shows "Not watched (unticked on the Start page): ...". The tray host is paused while the GUI runs (the only place to tick) and reads the ticks again whenever the GUI closes, so it never needs a restart either; a late event of a game unticked meanwhile is dropped by both.
#Tray and autostart
The watcher only works while something runs. After the GUI closes, a separate small process keeps watching: the
tray host (<install>\tray\JoyPro.Tray.exe, WinForms NotifyIcon, no Avalonia, no render loop). The GUI itself
always ends when its window closes, so its memory goes back to Windows.
Settings > Run in the background (system tray):
| Setting | Default | What it does |
|---|---|---|
| Start with Windows (in the tray) | off | writes the value JoyPro2 = "<install>\tray\JoyPro.Tray.exe" --tray to HKCU\Software\Microsoft\Windows\CurrentVersion\Run (per user, no admin); unticking removes it. Ticking it also ticks Close to tray. |
| Close to tray | off | the tray host runs while the GUI is open (paused, its icon is there) and goes on watching after the GUI closed; off: closing the GUI ends the watching too (a tray host started with Windows ends with the GUI) |
Both are stored in ui-settings.json (startWithWindows, closeToTray; %APPDATA%\JoyPro2, tests
<JOYPRO_DATA_DIR>\settings). The tray host reads watchGameConfigs, watchedGames, closeToTray and lastProfilePath there and
writes only watchGameConfigs (its menu switch, only while the GUI is closed), keeping every other field. The Run entry
is the tray host next to the running GUI, so a portable copy starts from where it is. At every GUI start with the
setting on, the entry is written again when it is missing, starts a JoyPro2 that no longer exists (a moved portable
folder) or starts JoyPro.Gui.exe (the first tray mode); an entry for another existing install's tray host is left
alone (tick the box again to switch to this copy). If Windows' own Settings > Apps > Startup has JoyPro2 switched off
(StartupApproved\Run), the setting says so; JoyPro2 does not change Windows' switch. Code:
gui\JoyPro.Gui\Services\AutostartService.cs (IRunKeyStore; the tests use an in-memory store, set in
TestEnvironment, and check that the real key is unchanged).
#Tray host
gui\JoyPro.Tray (the exe, a thin WinForms shell) and gui\JoyPro.Watch (net9.0 library shared with the GUI:
GameConfigWatcher, SyncOutput for the engine's sync JSON, TrayWatcherHost with the logic, GuiPresence,
SingleInstanceGuard, UiSettingsFileStore). The GUI builds it and copies it to <output>\tray\ (publish:
<publish>\tray\).
- Watching:
engine sync status(with the GUI's common options) lists the configs, of which it watches the games ticked on the Start page (watchedGames); the sameGameConfigWatcheras the GUI. At its own start it offers what changed while nothing ran. - After a change (the game has closed):
sync status --game <id> --path <config>, then--profile <last profile> sync diff. No change JoyPro manages:sync accept, silently. Otherwise a balloon notification (Windows shows it as a toast; it never takes the focus): "A game changed its controls - DCS World changed 2 controls JoyPro manages. Click here to take them over or ignore them in JoyPro2.", and the menu gets "Review the changes made in DCS World (2)". Without a last profile nothing is asked (as in the GUI; the config stays changed for later). - Review (the notification, the menu entry, or a left click while changes wait): starts
JoyPro.Gui.exe --review <game>|<config> .... The GUI loads the last profile if none is loaded and shows the existing dialog (Take over / Not now / Ignore these). A GUI that already runs gets the list through<settings>\gui-request.txtand its activation event, and comes to the front. - Menu: Open JoyPro2 (also a left click), Review ..., Watching game configs (checked = on; greyed while the GUI is open), Exit.
- Log:
<data>\Logs\tray-<date>.log(logging) says what it decided after a game closed (notification shown,accepted without asking,content is unchanged) and when it paused for the GUI; the GUI logs the same decisions (offering N change(s) in the dialog,took over,ignored) in its own log. The notification's sender is "JoyPro2" (the tray exe's file description). - Hand-over, no double prompts: the GUI announces itself after it took its single-instance mutex (writes
<settings>\gui.pid, sets the eventLocal\JoyPro2.Gui.<hash>.Started). The tray host waits for that event on the thread pool, then disposes its watcher and forgets its pending reviews (the GUI watches and offers them itself), and follows the GUI process'sExitedevent. When the GUI ends it reloads the settings: Close to tray on -> watch again (without offering again what the user postponed with "Not now"), off -> the tray host ends. - One tray host per user and settings folder (
Local\JoyPro2.Tray.<hash>.Running); a second start ends at once. The GUI starts it (throughExternalProcess, never in the tests) when Close to tray is ticked, at GUI start with Close to tray on and when the GUI closes with it on (not when an update closes the GUI; the update script stops the tray host, the restarted GUI starts it again). - Usage recording: while it watches, the tray host also catches up with the games' logs (
engine usage harvest), follows them live and harvests after a game closed (usage statistics); it hands this over to the GUI like the watcher. - Small: workstation GC without the background GC thread, no tiered PGO; after startup and after each check one
compacting GC and
SetProcessWorkingSetSize(-1, -1)give the pages back. No timer, no polling. - GUI: one GUI per user (mutex
Local\JoyPro2.Gui.<hash>.Running, event...Activate); a second start brings the running one to the front and hands over its--reviewlist.JoyPro.Gui.exe --tray(the first tray mode's Run entry) starts the tray host and ends. A test run (JOYPRO_DATA_DIR) has its own names and never meets the user's JoyPro2. Code:gui\JoyPro.Gui\AppShell.cs,Services\TrayHostLauncher.cs,ViewModels\MainWindowViewModel.Tray.cs.
Tests: gui\JoyPro.Gui.Tests\TrayHostTests.cs (the tray host with fakes: offering what changed meanwhile, one
notification, silent accept, no profile, Review / Open arguments, pause while the GUI runs and resume without asking
again, ending with Close to tray off, the Watching switch, unsubscribing), TrayHostResourceTests (the real watcher:
1000 writes -> 1 notification, handles 630 -> 630, managed heap +0.8 MB; 200 GUI start/exit hand-overs: handles
630 -> 633), TrayModeTests.cs (Run command and repair, settings shared through ui-settings.json, --review / --tray,
the review hand-over, single instance, GuiPresence with a real mutex and event, the sync output parser).
Measured 2026-10-11, Release build of JoyPro.Tray.exe --tray with its own JOYPRO_DATA_DIR and five watched games
(DCS, IL-2, War Thunder, X-Plane, Falcon BMS; 5 config folders):
| Tray host | (the GUI kept in the tray, previous version) | |
|---|---|---|
| idle CPU, 60 s | 0 ms (0 ms/s) | 7-30 ms/s (Avalonia's compositor) |
| working set after start | 11-12.5 MB | ~156 MB |
| private bytes | 13 MB | ~130 MB |
| handles / threads | 358 -> 354 over 60 s / 21 | 627-651 / 58 |
| second start | ends after 101 ms |
A process standing in for the GUI (its mutex, pid file and event): the tray host's handles 354 -> 349 while it ran (watchers released), 357 after it ended (watching again); with Close to tray off the tray host ended itself.
#Changes made in JoyPro that the game does not have yet
Every export (and the first import of a game) also stores the profile's binds of that game that really reached the game
(ProfileKeys in <data>\Sync\<game>.json; an export that kept the game's bind on a conflict leaves the other one
out). engine sync pending --game <id> compares the profile with it and with the game as it is now: a bind added in
JoyPro that the game lacks, or removed in JoyPro that the game still has, is pending (grouped per action: moved, added,
removed). Before an import the GUI asks when something is pending (Export first / Import anyway / Cancel), and
sync diff never offers such a bind as a game change (no take-over that undoes the user's own edit). Records written
before 2.4.3 have no ProfileKeys: nothing is known until the next export (Known false).
#What counts as a change
Only binds and axis tuning JoyPro manages:
- devices the profile uses (a device the profile never used is not JoyPro's), the keyboard only when the profile has keyboard binds for that game (the export rules, see export);
- actions JoyPro writes: registry games their catalog (
DB\<Game>\actions.tsv), Star Citizen the ship action maps; - DCS: only the aircraft whose files changed (
Config\Input\<aircraft>\...); - values are compared as the game uses them, rounded to 4 decimals, after the game's own import: Star Citizen writing 0.21 as 0.20999999, DCS writing 0.2 as 0.20000000298023, War Thunder reordering keys or writing machine.blk as a diff against its preset, other whitespace or element spelling are no change;
- the baseline makes the diff report what the game changed: a bind JoyPro could not write (or one you added in JoyPro since the export) is not reported as removed, and a bind the file already had is not reported as new;
- DCS: what counts is the device's defaults plus its diff.lua, not the diff alone. DCS saves the diff against the
defaults of the device type (e.g. the T-Pendular-Rudder has its rudder on JOY_Z by default) and drops a bind equal to
such a default; JoyPro's .jp copy keeps it, and it stays active unless the diff has a "removed" entry for it. The
defaults are the ones of the DCS list refresh:
CleanProfile\DCS\<plane>\<device type>.cffor a type with defaults of its own, else the plane's generic<plane>.cf(smoke:engine\tests\smoke\sync_dcsdefaults.ps1).
| Kind | Meaning | Choices |
|---|---|---|
added |
the game binds an action to a device/input/modifiers the profile does not have for it | a relation that binds that input in this game (or holds the action), a new relation, ignore |
removed |
a bind the profile has (and the file had) is gone | the relation that holds it (the action leaves it; DCS: only that aircraft), ignore |
changed-tuning |
an axis' dead zone, saturation, curve, invert or game parameter changed | the relation (gets the value as its game tuning; DCS: the aircraft's, or the base when the relation only flies that aircraft), a new relation (the axis moves there), ignore |
changed-modifiers |
same action and input, other modifiers | the relation (its modifiers change for all its games), another relation with these modifiers or a new one (the action moves), ignore |
changed-setting |
a game-wide setting the profile holds for the game (ffb set --device *) has another value in the game |
take over (the value becomes the profile's setting for the game), ignore |
A relation that is rebound by a choice ("now bound to ...") changes for every game it has, as everywhere in JoyPro.
Game-wide settings count only for the keys the profile holds for the game (those JoyPro writes), compared rounded to 4
decimals and against the baseline (IL-2 writes 0.333 as 0.33: no change). They are read from: War Thunder settings{}
and the other blocks of machine.blk, Falcon BMS (Falcon BMS User.cfg, Feedback.ini, the pilot file), Star Citizen
attributes.xml, IL-2 data\input\current.devices (then data\startup.cfg), X-Plane's Joysticks.prf, Elite's
.binds, the Arma 3 profile (RTD options, vibrations; Arma 2 has none), WARDOGS GameUserSettings.ini
([/Script/WDGame.WDUserSettings]), X4 inputmap.xml <config> and config.xml next to it, Arma Reforger's
ReforgerGameSettings.conf / GameUserSettings.conf (the one the game saved last wins) and VTOL VR's gameSettings.cfg
next to inputbindings.cfg (settings of game VTOLVR, watched with VTOLVRNative).
#Games and what is watched
| Game | Watched | Processes |
|---|---|---|
| DCS | Saved Games\DCS\Config\Input, *.diff.lua and modifiers.lua, with subfolders |
DCS |
| IL-2 Great Battles | data\input: global.actions, devices.txt, current.responses, current.devices; data\startup.cfg |
Il-2 |
| Star Citizen | the profile's actionmaps.xml and attributes.xml |
StarCitizen |
Registry games with a file (War Thunder machine.blk, X-Plane .prf, Elite .binds, X4 inputmap.xml, Arma profiles, Reforger .conf, WARDOGS ini and sav, IL-2 Korea) |
that file, plus the files that hold its game-wide settings (IGameSettingsSource): X4 config.xml, Reforger's game settings in each app*_user*\settings, VTOL VR native gameSettings.cfg |
the integration's ProcessNames (e.g. aces, X-Plane, EliteDangerous64, X4) |
| Registry games with a folder | Falcon BMS User\Config\Setup.v100.*.xml, Falcon BMS User.cfg, Feedback.ini, *.pop, VTOL VR SaveData\BYOJ_*.xml, MSFS profile folders (all files) |
as above |
| MSFS 2020 / 2024 | JoyPro's package (2024) or the Steam remote folder, inputprofile_* of the Steam remote folders, the Store save folder's containers.index with subfolders (10 s settle) |
FlightSimulator2024 / FlightSimulator, or any exe in the Store install folders |
| Nuclear Option | HKCU\Software\Shockfront\NuclearOption (registry notification); the fingerprint covers Player0's Rewired controller maps only |
NuclearOption |
JoyPro's own files next to the game's (.jp, .joypro-meta.json, .joypro.json, .jpbak) are never part of the
fingerprint. Status uses the config path discovery the export uses (with your config location from engine games config set first) and adds every other config JoyPro recorded for the game (an export to a custom --path); the GUI watches
each of them. A disabled game shows State: disabled and has nothing to watch.
#CLI
engine sync status [--game <id>] [--path <config>]
engine sync accept --game <id> [--path <config>]
engine --profile <p> sync diff --game <id> [--path <config>]
engine --profile <p> sync apply --game <id> --choices <file.json> [--path <config>]
engine --profile <p> sync pending --game <id> [--path <config>]
-
pendingJSON:{ Game, DisplayName, Known, Binds, Count, Actions: [{ ActionId, Title, Kind (moved|added|removed), Planes }], Message, Warnings }. -
statusJSON:{ DataFolder, Games: [{ Game, DisplayName, Installed, ConfigPath, Kind (files|registry), State (unchanged|changed|untracked|missing|not-installed|disabled), Disabled, Tracked, Changed, RecordedUtc, Reason (export|accept|apply), Fingerprint, Files, ChangedFiles, ChangedPlanes (DCS), Watch: [{ Directory, Filters, IncludeSubdirectories }], RegistryKey, ProcessNames, ProcessFolders (image path prefixes that count as the game), SettleSeconds (0: the watcher's default), Warnings }] }. Tests:JOYPRO_TEST_GAME_PROCESSES=MSFS2024=<name>[,<name>];<game>=...replaces the reported process names (MSFS2024=for none), so a stand-in process (a copy ofPING.EXE) plays the game and a game the developer plays meanwhile does not take part; withJOYPRO_TEST_MSFS_HOMEthe MSFSProcessFoldersare<home>\XboxGames\<game>\Content\only. Hashing only happens for files whose size or write time differ from the record (about 150 ms for every game on a PC with 18 games installed). -
diffJSON:{ Game, DisplayName, ConfigPath, Tracked, Baseline, Planes, ProfileBinds, FileBinds, Changes: [{ Id, Kind, Game, Plane, ActionId, ActionTitle, IsAxis, Device, Input, Modifiers, ModifierStrings, OldModifiers, OldTuning, NewTuning, Relations, Candidates, Suggested, NewRelationName, SettingKey, SettingLabel, OldValue, NewValue, Description }], Warnings, Errors }(OldValue / NewValue only forchanged-setting). Without--pathand--gamestatus may list a game more than once, one entry per config.Candidates: the relations that hold the bind (removed / changed), the relation an added bind joins, then those that bind the device + input + modifiers in this game, then those that hold the action.Suggested: the relation to preselect,neworignore. An added bind joins the relation of any game or aircraft that uses exactly that input with those modifiers, unless the aircraft is bound there to another action (EngineDcsImport.RelationToJoin, the same rule as the DCS import's "add to my profile" andrelations item move-to-input);newonly when no relation can take it (2.4.2; up to 2.4.1 only this game's relations of the aircraft whose files changed counted). The ids are stable as long as the file and the profile do not change. -
apply --choices:{ "Choices": [ { "Id": "c...", "Target": "<relation>" | "new" | "apply" (settings) | "ignore", "Name": "<new relation name>" } ] }(or the bare list). Changes not listed are ignored. Afterwards the config counts as known, so ignored changes are not offered again. Output:{ Game, ConfigPath, Applied, Ignored, NewRelations, ChangedRelations, Fingerprint, Steps, Warnings }. -
accept: the current state counts as known; nothing is imported.
The whole journey in the games themselves (GUI or tray host running, a bind changed in the game's controls menu, the dialog after the exit, Ignore / Take over, no dialog without a change) is tested in the games before a release.
#Resources
The watcher must never cost anything noticeable:
- no polling and no periodic timer: file events (overlapped I/O in the kernel), one registry wait on the thread pool,
a one-shot debounce timer per game that only runs after a change,
Process.Exitedwhile a game runs; - every
FileSystemWatcher, timer, registry key, wait handle andProcessis disposed and every event unsubscribed when a game is no longer watched, the setting is switched off or JoyPro closes; the only collections hold one entry per watched game; - in the tray: not the GUI but the tray host (WinForms, no render loop): 0 ms CPU in 60 s idle, ~12 MB working set; its only waits are the GUI-started event and, while the GUI runs, the GUI process (both on the thread pool);
- engine calls only after a change (status ~150 ms; diff of one DCS aircraft ~0.2 s; the record after an export: 1.3 s
for 180 DCS files / 9.5 MB,
Sync\DCS.json~1 MB for 54 000 binds). The GUI's background checks keep the output pane of the last command.
Measured by gui\JoyPro.Gui.Tests\GameConfigWatcherTests.cs (runs alone, dotnet test gui\JoyPro.Gui.Tests --filter GameConfigWatcherTests), 2026-10-11:
| Test | Result |
|---|---|
| 1000 writes to a watched file (and 1000 to an unwatched one in the same folder) | 1 report (debounced); process handles 426 -> 428, managed heap 3.3 MB -> 3.3 MB, working set 68 -> 69 MB |
| idle 3 s with the watcher on | 0-16 ms CPU for the whole test process |
| 200 x watch / unwatch two games | handles 408 -> 406, managed heap flat, watcher holds 0 handles afterwards |
| change while the "game" runs (a renamed ping.exe) | no report until it exits, then one |
| registry value changed twice | two reports (the notification is armed again) |
The per-game ticks, gui\JoyPro.Gui.Tests\GameWatchChoiceTests.cs, 2026-10-12: GameWatchChoiceTests (defaults for
installed and missing games, untick saved and read back by a new GUI and by the tray host's store, tick again, Watch
all / none, a game installed later ticked by itself, an unticked game staying unticked after a new install, the tray
host watching only ticked games and taking new ticks after the GUI closed, the Start page render
docs\ui\start-game-watch-dark.png / -light.png with JOYPRO_UI_DESIGN_OUT set) and GameWatchChoiceWatcherTests
(real file watchers on temp folders):
| Test | Result |
|---|---|
| GUI: two tracked games, one unticked | only the ticked game has a FileSystemWatcher; the untick needs no engine call; master switch off -> 0 handles, on -> the ticked game only |
| GUI: 200 x untick / tick | process handles 831 -> 842, the watcher holds the same 4 handles as before, 0 after stop |
| tray host, real watcher: write to the unticked and the ticked game's config | only the ticked game is reported; after the GUI ran and the user ticked the other game, its write is reported too; every watcher holds 0 handles after the pause and the end |