JoyPro2 Discord GitHub
Engine (CLI)

engine x4 (X4: Foundations)

Show:

6 commands of engine x4. Each with every option and every value it takes, what it does, which GUI buttons use it, and an example.

#engine x4 paths

written
engine x4 paths
For beginners

Lists where JoyPro finds the input map of X4: Foundations on this PC. The first one is what engine x4 scan, engine x4 import and engine x4 export use when you give no path. Detect in the Other Games panel (Start page, Expert import) runs it and puts the first one into File / Folder.

engine x4 paths --text
Advanced
  • %USERPROFILE%\Documents\Egosoft\X4\<id>\inputmap.xml of every account folder (and Documents\Egosoft\X4\inputmap.xml), newest first.
  • A config location you set yourself (engine games config set, Settings > Games) comes first.
  • No options. Reads only; it also works while the game runs or when it is not installed.
Technical internals
  • Output: JSON (Game, DisplayName, ConfigPaths, Warnings), or text with --text ("X4: Foundations (experimental) Config Paths", "Paths: " and one line per location). Exit code 0, also when nothing was found (empty list).
  • engine x4 without an action runs paths.
  • Related: engine x4 scan, engine games paths, engine games install set; game page x4.

What it does Lists where JoyPro looks for this game's controls on this machine: files, folders or registry keys (your config location from games config set first). A file the game has not written yet can be listed (e.g. Arma Reforger's JoyPro.conf, Project Wingman's Input.ini).

Example

engine x4 paths --text

#engine x4 catalog

written
engine x4 catalog
For beginners

Lists the X4: Foundations actions JoyPro manages (its command list): id, axis or button, category and title. An export writes only these actions, and the relation editor and the search list them.

engine x4 catalog --text
Advanced
  • The list is %LOCALAPPDATA%\JoyPro2\GameData\DB\X4\actions.tsv (when that folder does not exist, the DB\X4 folder next to the engine).
  • It is built from the game's Controls menu by engine x4 refresh-db, or by the first scan, import or export.
  • catalog only shows the list; it never builds it. Titles that look like ids are shown readable.
  • No options. Reads only; works without the game installed.
Technical internals
  • Output: JSON (Game, Source, Actions with Id, Title, IsAxis, Category, Warnings), or text with --text ("X4: Foundations (experimental) Action Catalog", "Source:", "Actions: ", then <id> | axis|button | <category> | <title> per action).
  • Without a list: the warning X4: Foundations (experimental) action catalog not found: <path> and an empty list, exit code 0.
  • Related: engine x4 refresh-db, engine x4 export, engine db games; game page x4.

What it does Lists every action of JoyPro's command list of this game with its kind and category: <data>\GameData\DB\<Game>\actions.tsv, else the program folder's DB\<Game>.

Example

engine x4 catalog --text

#engine x4 scan

written
engine x4 scan [<config-path>] [--path <config-path>] [--ignore-device <name>] [--ignore-devices <csv>]
For beginners

Shows the joystick binds X4: Foundations has now, without changing your profile or the game. Use it to look before an import. Look first on the game's card of the Start page and Scan in the Other Games panel run it.

engine x4 scan --text
Advanced
  • It reads the active binds and <config> params of inputmap.xml, and the device slots of config.xml in the same folder (DirectInput instance GUID).
  • Path (positional or --path): another inputmap.xml.
  • --ignore-device <name> / --ignore-devices <a;b> (separated by | or ;, --ignore-devices also by commas) leave the binds of those devices out (a name without {GUID} means every device of that name); a step line names them and counts the binds.
  • Keyboard binds JoyPro reads in this game are listed too; engine x4 import takes them only with --include-keyboard.
  • Safety: reads only and is not refused while the game runs. It is refused when the game is not installed (set its folder: engine games install set) or switched off in Settings > Games.
  • A fresh install has no command list yet: the first scan builds it from the installed game and saves it (a step line says so).
Technical internals
  • Output: JSON (ConfigPath, BindingsRead, Bindings with ActionId, Device, Input, IsAxis, Reformers, Inverted, then Steps, Warnings, Errors), or text with --text ("X4: Foundations (experimental) Scan", "Config:", "Bindings Read:" and the list).
  • Exit code 0; 1 when the result has errors, for example No X4: Foundations (experimental) config file found. Pass the path explicitly.
  • Unknown options fail with Unknown X4 scan argument(s): ...; MSFS options (--game-profile, --include-disconnected, --include-sim-defaults) are refused.
  • Binds of the vJoy device JoyPro forwards into (--vjoy-tunnel) are left out.
  • Related: engine x4 import, engine x4 paths, engine x4 catalog; game page x4.

What it does Reads the game's controls (its control file or folder, or registry values for Nuclear Option and Tiny Combat Arena; Ace Combat 8 stores none) and shows the joystick binds, without changing the profile. Without a command list yet (fresh install) it first builds the list from the game and saves it.

OptionValuesMeaning
--path<config-path>Optional explicit path override. Use when you prefer option form over positional path.
--ignore-device<name>Leave the binds of this device out (one per flag; a name without {GUID} means every device of that name). Example: --ignore-device 'vJoy Device'.
--ignore-devices<csv>Leave the binds of these devices out (separated by commas, | or ;). Example: --ignore-devices 'vJoy Device,Old Pedals'.

In the game Reads X4: Foundations's files only; nothing changes in the game. A scan only shows what an import would bring and does not change the profile. X4: Foundations details · what each mode changes

Example

engine x4 scan --text
How the options interact
  • --ignore-device / --ignore-devices leave the binds of those devices out of the scan or import (the result names how many).

#engine x4 import

written
engine x4 import [<config-path>] [--path <config-path>] [--replace] [--include-keyboard] [--ignore-device <name>] [--ignore-devices <csv>]

--ignore-device(s): the binds of these devices are left out

For beginners

Reads the space flight binds of X4: Foundations into your JoyPro profile, with the game's inverts and throttle mode. Nothing in the game changes. The GUI runs it with Import on the X4 card of the Start page.

engine x4 import --profile "C:\Users\Pilot\Documents\JoyPro\My Sticks.pr0file" --text
Advanced

It reads %USERPROFILE%\Documents\Egosoft\X4\<id>\inputmap.xml (the active binds and <config> params) and the device slots of config.xml in the same folder. <id> is the Steam account's folder.

  • Default: adds to the open profile (--merge means the same); --replace replaces every relation of the profile by what X4 has.
  • --include-keyboard also reads the flight controls' keyboard lines.
  • Devices are matched to X4's slots through config.xml (DirectInput instance GUID).
  • Safety: reads only, not refused while the game runs; the profile is kept as "Before import from X4: Foundations (experimental)" first.
  • --ignore-device <name> / --ignore-devices <a;b> leave the binds of those devices out (a name without {GUID} means every device of that name); a step line says how many binds were left out.
Technical internals
  • Output: JSON of the import result or a text report with --text; exit code 1 on an error (No X4: Foundations (experimental) config file found. Pass the path explicitly.).
  • Without a path it reads the file engine x4 paths lists first; a fresh install builds the command list from the game's files first.
  • With --profile the profile is saved afterwards; a game JoyPro never exported to is watched from now on.
  • Related: engine x4 scan, engine x4 export; game page x4.

What it does Imports the game's joystick binds into the loaded profile (merged by default; --replace starts from an empty relation list). Without a command list yet it first builds the list from the game.

OptionValuesMeaning
--path<config-path>Optional explicit path override. Use when you prefer option form over positional path.
--replaceswitch (no value)For game import: start from an empty relation list instead of merging into the loaded profile.
--include-keyboardswitch (no value)
--ignore-device<name>Leave the binds of this device out (one per flag; a name without {GUID} means every device of that name). Example: --ignore-device 'vJoy Device'.
--ignore-devices<csv>Leave the binds of these devices out (separated by commas, | or ;). Example: --ignore-devices 'vJoy Device,Old Pedals'.

In the game Reads X4: Foundations's files only; nothing changes in the game. The binds come into the profile as relations; JoyPro's own data next to the game file brings back names, groups, modifiers and curves. X4: Foundations details · what each mode changes

Example

engine --profile 'C:\JoyPro\profiles\pilot_main.pr0file' x4 import --text
How the options interact
  • --ignore-device / --ignore-devices leave the binds of those devices out of the scan or import (the result names how many).

#engine x4 export

written
engine x4 export [<config-path>] [--path <config-path>] [--mode clean|add|merge|merge-overwrite] [--dry-run] [--include-keyboard] [--nuke-untouched-devices] [--ignore-device <name>] [--ignore-devices <csv>]

Only ship flight actions: clean and nuke release those on the written / unused devices; --ignore-device(s) and --vjoy-tunnel devices are never cleared

For beginners

Writes your space flight binds into X4's inputmap.xml in place, on the slots of your devices; menu, first-person, keyboard and mouse binds stay. Close X4 first, and pin every device to a slot once in the game. The GUI's Export now on the X4 card runs it.

engine x4 export --mode clean --nuke-untouched-devices --profile "C:\Users\Pilot\Documents\JoyPro\My Sticks.pr0file" --text
Advanced

A conflict is another flight control on the same slot and input; the map and detail-monitor twins of a control count as one control.

--mode In inputmap.xml
add nothing is removed; a bind whose input another flight control has gets a mark "Not written to the game"
merge your lines go in beside the control's other inputs; only conflicts are removed
merge-overwrite (engine default) as merge, and a control you bind loses its other lines on pinned slots of connected devices
clean (GUI default) the flight binds of the written slots that are not in your profile are removed, also the stock gamepad flight binds on slot 1
  • --nuke-untouched-devices: the same for slots config.xml pins to connected devices the export does not use; a slot without a pinned device is left alone (not with add).
  • --include-keyboard writes flight keys (never keys X4's menu refuses) and lets merge-overwrite remove a control's keyboard lines.
  • Inverts are one value per control for every device and are set only when every axis on that control agrees. The throttle relation's Slider sets the bidirectional throttle. Relation dead zones are not written; settings you stored for X4 (dead zone, adaptive steering, rumble, auto-roll) are, also by a profile without X4 binds.
  • Never touched: menu, map, first-person, options and accessibility controls, keyboard and mouse lines without the option, slots of devices not connected or not pinned, gamepads, --ignore-device(s), the --vjoy-tunnel device, inputmap_1.xml to inputmap_5.xml and your saves.
  • Safety: refused while X4 runs; both files backed up first (undo: engine backups list); the profile is kept as "Before export to X4: Foundations (experimental)". --dry-run writes nothing.
Technical internals
  • Output: JSON of the export result or a text report with --text; exit code 1 on an error (X4 runs, an invalid --mode, no file found). A device without a pinned slot is skipped ("assign the device to a slot in X4 once").
  • Without a path it writes the file engine x4 paths lists first. Untouched lines stay byte for byte.
  • After a real run: inputmap.xml.joypro-meta.json, the watcher's fingerprint, the export marks (engine export-marks list).
  • The help note says "only ship flight actions": clean and nuke release only the space flight controls of the command list.
  • Related: engine x4 import, engine ffb set; game page x4.

What it does Writes the profile's binds for this game. Only the flight actions JoyPro manages are changed, the game must be closed, and the game's files are backed up first (engine backups). Without a command list yet it first builds the list from the game.

OptionValuesMeaning
--path<config-path>Optional explicit path override. Use when you prefer option form over positional path.
--modeclean add merge merge-overwriteExport mode for DCS/IL2 export commands: clean, add, merge, merge-overwrite.
--dry-runswitch (no value)Report what the export would write; the game's files are not changed.
--include-keyboardswitch (no value)
--nuke-untouched-devicesswitch (no value)DCS export only: delete untouched device .diff.lua/.jp files under Config\\Input (true/false).
--ignore-device<name>Exclude one device per flag. Example: --ignore-device Keyboard.
--ignore-devices<csv>Exclude devices, separated by commas, | or ;. Example: --ignore-devices Keyboard,Mouse.
Every value as a command line
engine x4 export --mode clean
engine x4 export --mode add
engine x4 export --mode merge
engine x4 export --mode merge-overwrite

In the game Writes into X4: Foundations's control files while the game is closed (refused while it runs), after a backup. Space sims: clean and nuke touch only the cataloged ship actions, on-foot and vehicle binds stay. Bind file: Documents\Egosoft\X4\<id>\inputmap.xml (XML) + the slots in config.xml. X4: Foundations details · what each mode changes

Example

engine --profile 'C:\JoyPro\profiles\pilot_main.pr0file' x4 export --dry-run --text engine --profile 'C:\JoyPro\profiles\pilot_main.pr0file' x4 export --mode merge-overwrite --text

#engine x4 refresh-db

written
engine x4 refresh-db [<source-path>] [--path <source-path>] [--dry-run]

Reads the installed game or <source-path> and adds its new actions to the catalog, the known ones stay; writes it only when it changes

For beginners

Builds JoyPro's X4: Foundations command list from the installed game's Controls menu, or adds the actions that are new. Run it after a game update, or when JoyPro says the list is missing. Refresh DB in the Other Games panel (its DB Source box is the path) and the Start page's notice "Command lists to build or update" run it.

engine x4 refresh-db --dry-run --text
Advanced
  • Without a path it reads the installed game (01.cat ... and X4.exe): the menu script ui/addons/ego_gameoptions/gameoptions.lua and the English texts t/0001-l044.xml. Path: the X4 folder, or a folder with those two files (a file means its folder).
  • New space-flight controls of the menu come in; the names of numeric control ids come from X4.exe (else JoyPro's order.tsv). New ids and menu functions are added to order.tsv and functions.tsv next to the list.
  • A known action that is no longer a space-flight control of the menu stays, with a warning.
  • --dry-run reads everything and writes nothing (step "Dry run: nothing was written."). Without it the list is written only when it changed.
  • Safety: only JoyPro's list changes, never a game file; it is refused when the game is not installed or switched off in Settings > Games. The GUI can cancel it while the game's files are read; nothing is written then.
Technical internals
  • Output: JSON of the refresh (DryRun, FilesWritten, Steps with Actions: <old> -> <new>, Warnings, Errors), or text with --text.
  • Exit code 0; 1 when nothing could be read: X4: Foundations was not found. Pass --path with the X4 folder (01.cat ... and X4.exe) or a folder with ui/addons/ego_gameoptions/gameoptions.lua and t/0001-l044.xml.; the list stays unchanged.
  • Writes %LOCALAPPDATA%\JoyPro2\GameData\DB\X4\actions.tsv (with a header line that has the date), and adds the new lines to order.tsv and functions.tsv next to it. After a real run the game's build is recorded for engine db check-updates.
  • Related: engine x4 catalog, engine x4 scan, engine db check-updates; game page x4.

What it does Reads the installed game or <source-path> and adds its new actions to the catalog, the known ones stay; writes it only when it changes.

OptionValuesMeaning
--path<source-path>Same as <source-path>: the game's installation or a file of the game to read the actions from.
--dry-runswitch (no value)Report what the command would do; nothing is written or changed.

Example

engine x4 refresh-db --text