JoyPro2 Discord GitHub
Game reference

X4: Foundations, X Rebirth, X3

Show:
TitleSupportEngine commandBind fileIn-game test
X4: Foundationsnativeengine x4Documents\Egosoft\X4\<id>\inputmap.xml (XML) + the slots in config.xml36/36
X Rebirthdocumented
X3 (Reunion, Terran Conflict, Albion Prelude)documented

The game page in plain words: X4: Foundations. Full matrix: Game support. What an export does in this kind of game: Export flow, in the game.

From docs/games/x4.md in the repository (generated, always the current text).

Tags: [OBS] seen in real files of an installed game · [OBS-bin] seen in the installed X4.exe (its name/value tables and how it reads and writes the config; addresses for maintainers), looked at for interoperability only, nothing modified · [SRC] the game's own scripts and data (gameoptions.lua, libraries/*.xml, text files in the .cat/.dat archives, the format Egosoft's modding tools use) or official docs · [INF] inferred · [UNVERIFIED] needs one check in the running game. Research 2026-10-01 on X4 9.00 (Steam build 23660954, version.dat = 900). The game was not started.

engine x4 refresh-db builds the list on the user's PC.

#X4: Foundations

#Files

What Where
Install Steam app 392160, steamapps\common\X4 Foundations via libraryfolders.vdf. Data in 01.cat/.dat … 09.cat/.dat plus extensions\*\ext_0N.cat/.dat [OBS]
User folder (Steam) <Documents>\Egosoft\X4\<SteamID32>\ = LastOwner SteamID64 − 76561197960265728, also in steam_autocloud.vdf (accountid) [OBS]. One folder per Steam account. Linux: ~/.config/EgoSoft/X4/<id>/ [SRC Steam forum]
User folder (GOG) <Documents>\Egosoft\X4\ without id folder [SRC third-party, UNVERIFIED]
Active bindings inputmap.xml in the user folder. The game only reads this file [SRC gameoptions.lua: LoadInputProfile("inputmap", …)]
Saved user profiles inputmap_1.xml … inputmap_5.xml (menu "Save Profile", ids 101-105, names "Custom 1-5" or a custom name). Loading one copies it into the active map; nothing in config.xml points to a slot [SRC displayInputProfiles; exe string inputmap_%u.xml]. None exist before the first save [OBS]
Shipped profiles libraries/inputmap.xml (id 1, "Default - Keyboard & Mouse / Controller") and libraries/inputmap_defaults_*.xml (gamepad arcade id 3, Warthog 5, X52 6, T.16000M 7/8/9, T.Flight 10, VKB 11/12, VPC 13/14, WASD 15). Names on text page 1023 [SRC]
Device slots, options config.xml in the user folder, <joysticks> element [OBS, OBS-bin]
Steam Cloud steam_autocloud.vdf is present, so Steam Auto-Cloud syncs this folder [OBS]; which files are synced is not known [UNVERIFIED]

#inputmap.xml format [OBS user file, SRC shipped maps, OBS-bin loader strings]

<?xml version="1.0" encoding="UTF-8"?>
<inputmap version="196" id="3">
  <config>
    <param name="invert_steering_roll" value="true"/>
    ...
  </config>
  <!-- input actions -->
  <action id="INPUT_ACTION_TOGGLE_TRAVEL_MODE" source="INPUT_SOURCE_JOYBUTTONS_2" code="INPUT_XBUTTON_BACK"/>
  <!-- input states -->
  <state id="INPUT_STATE_FIRE_PRIMARY_WEAPON" source="INPUT_SOURCE_JOYAXES" code="INPUT_JOYAXIS_RZ" sgn="-1"/>
  <state id="INPUT_STATE_MATCH_SPEED" source="INPUT_SOURCE_KEYBOARD" toggle="1" code="INPUT_KEYCODE_X_SHIFT"/>
  <!-- input ranges -->
  <range id="INPUT_RANGE_THROTTLE" source="INPUT_SOURCE_JOYAXES_2" code="INPUT_JOYAXIS_Z"/>
</inputmap>
  • Game-written file: UTF-8 without BOM, LF, two-space indent, /> without space, the three comments as section markers. Within each section the entries are sorted by the numeric id of the control (checked on all 441 entries of the user file); several entries per id are allowed (one per input). Attribute order as written by the game: id, source, [toggle], code, [sgn] [OBS].
  • Root version = profile format version (196 in 9.00), id = id of the profile it came from (user file: 3), shipped maps also carry name="{1023,n}" and mouse="true". Keep both attributes. On a version change the game patches older user maps with the sinceversion/removed="true"/force="true"/copyfrom/match entries of the shipped maps; these attributes occur only in shipped maps [SRC, OBS].
  • Element = control type: <action> (one-shot), <state> (held / button, toggle="1" makes it latch; shipped maps write toggle="true"), <range> (analog). Loader messages: a range bound to a digital input is ignored, a range with sgn has the sgn ignored, an action/state bound to an axis without sgn is ignored [OBS-bin].
  • sgn="1"/"-1" = half axis used as a button for actions/states (INPUT_STATE_BOOST on INPUT_JOYAXIS_SLIDER1 sgn="1" in the VKB map) [SRC].
  • Numeric ids: the exe has {name, value} tables for every enum (INPUT_ACTION_WIDGET_BACK = 16, INPUT_RANGE_THROTTLE = 4). The Lua menu and the text pages use the numbers, the XML uses the names [OBS-bin, SRC].

#Sources and codes [OBS-bin enum tables, SRC menu.getInputName]

source value meaning
INPUT_SOURCE_KEYBOARD 1 keyboard
INPUT_SOURCE_JOYAXES, _2 … _8 2-9 axes of joystick slot 1-8
INPUT_SOURCE_JOYBUTTONS, _2 … _8 10-17 buttons and POV of joystick slot 1-8
INPUT_SOURCE_MOUSEAXES / MOUSEBUTTONS 18 / 19 mouse
INPUT_SOURCE_COMPASSMENU / _2 30 / 31 entries 1-8 of radial menu 1/2 (INPUT_COMPASSMENU_n)
20-29 VR controllers, emulated mouse buttons
  • Buttons (INPUT_XBUTTON_*, value = DirectInput button number): 1 A, 2 B, 3 X, 4 Y, 5 LEFT_SHOULDER, 6 RIGHT_SHOULDER, 7 BACK, 8 START, 9 LEFT_THUMB, 10 RIGHT_THUMB, 11 BIGBUTTON, 12-64 INPUT_XBUTTON_12 … INPUT_XBUTTON_64 [OBS-bin]. The XInput names are reused for joysticks: the Warthog map fires primary weapons with INPUT_XBUTTON_A (stick button 1 = trigger) and secondary with B (button 2 = weapon release) [SRC]. No button above 64.
  • Hat: INPUT_XBUTTON_DPAD_UP, _UP_RIGHT, _RIGHT, _DOWN_RIGHT, _DOWN, _DOWN_LEFT, _LEFT, _UP_LEFT (65-72). One hat per device; there are no codes for a second POV [OBS-bin].
  • Axes (INPUT_JOYAXIS_*): X 1, Y 2, Z 3, RX 4, RY 5, RZ 6, SLIDER1 7, SLIDER2 8 = DirectInput lX … rglSlider[1]; 3LY…3RR, VRTRIGGER_L/R are 3D-mouse/VR axes [OBS-bin; SetProperty(DEADZONE/RANGE) strings for X, Y, Z, Rx, Ry, Rz, Slider(n)].
  • Modifiers are part of the code name and value: keyboard and mouse _SHIFT (+256), _CONTROL (+512), _SHIFT_CONTROL; joystick _MOD1 (+1024), _MOD2 (+2048), _MOD1_MOD2 (e.g. INPUT_XBUTTON_14_MOD1). Which buttons act as joystick modifier 1/2 is stored per profile in a <config> child named custom_modifier_<shift|ctrl|joystickmod1|joystickmod2> whose children carry source/code; the exact child markup is [UNVERIFIED] (no shipped or user file uses it; only the loader is known) [OBS-bin XIn::InputProfile::GetConfigModifierButtons, SRC config.input.modifiers].
  • Keyboard: INPUT_KEYCODE_<DIK name> with the DirectInput scan code as value (ESCAPE 1, 1 2, …). The menu refuses Escape, Delete, Shift+Insert, Shift+Delete, Ctrl+X/C/V and Ctrl+Insert [SRC forbiddenKeys].

#Axis settings

  • Inversion is global per control, not per input: <param name="invert_steering_yaw|invert_steering_pitch|invert_steering_roll|invert_throttle|invert_strafe_left_right|invert_strafe_up_down" value="true|false"/> in <config>; first person and menu axes have their own invert_fp_*, invert_controllermouse_*, invert_compassmenu_* [SRC joystick_invert menu, OBS].
  • deadzone = 0-100 %, one value for all axes of all joysticks (applied with DirectInput DIPROP_DEADZONE) [SRC slider, OBS-bin]. bidirectionalthrottle (centre = zero thrust), stick_steering_adaptive, yaw_into_roll are global too. No per-axis curves or saturation.
  • JoyPro (2026-10-05): game settings X4 (engine\FfbModels\X4.cs, engine ffb set --device * --game X4), smoke test engine\tests\smoke\x4.ps1, in-game check tools\e2e\games\X4Settings.ps1 (prepared, not run yet).
    • Invert rule: a relation keeps DCS's direction; X4's invert_* for a flight axis = relation invert XOR the value X4's shipped HOTAS maps use: invert_steering_pitch true (10/10 joystick maps), invert_throttle true (9/10; the VPC Constellation AP 1 map, throttle on a VPC slider that reports reversed, has false), invert_steering_roll true (11/13 maps incl. the default keyboard/gamepad map; the two VKB maps have false), invert_steering_yaw and both strafes false (all maps) [SRC libraries\inputmap_defaults_*.xml]. The same device convention as Elite (see docs/games/elite-dangerous.md "Invert direction"). JoyPro maps INPUT_RANGE_STEERING_PRIMARY to invert_steering_yaw and _SECONDARY to invert_steering_roll (the menu's ranges 1 and 3; with adaptive steering off) [INF]. One value per control for every device: the export sets it when all JoyPro axes written to that control agree, warns and leaves it when they disagree, and warns when another device (a gamepad, an unmanaged slot) is bound to the same control. A value set with ffb set wins (warning when it reverses the relations). The import fills the relation's invert the same way.
    • bidirectionalthrottle follows the throttle relation's Slider (one-sided = false); missing = false (the game's default, assumed; no line is added for false). Explicit bidirectionalThrottle wins.
    • deadzone (0..100 %), stick_steering_adaptive: only from ffb set; relation dead zones are not written (one dead zone for every axis; the export says so). Settings > Game rumbleintensity (% → 0..1 with 2 decimals; the game's slider shows the float value times 100 truncated, so 21 % shows as 20 and 57 % as 56 while the file and the game keep the exact value), autoroll, gamepadmode (0..2) are set in config.xml in place (element text only).
    • Params are edited in place; a missing param is added as the last line of <config>. An export without X4 binds still writes the settings set in JoyPro.
  • The menu offers INPUT_RANGE_STEERING_PRIMARY (21, yaw unless adaptive steering) and INPUT_RANGE_STEERING_SECONDARY (22, roll), pitch, strafe and throttle. INPUT_RANGE_STEERING_YAW (1) and _ROLL (3) exist and sit in the flight context but are not in the menu and no shipped map uses them [SRC]; JoyPro should not write them.

#Device identification [OBS, OBS-bin]

  • A bind names a slot (no suffix = slot 1, _2 … _8), not a device. config.xml maps devices to slots:
    <joysticks>
      <joystick num="0">{42cec570-0a3f-11f0-80-0b-44-45-53-54-00-00}</joystick>   <!-- slot 1 -->
      <joystick num="1" current="0">{...}</joystick>                                <!-- remembered, not active -->
      <joystick disabled="1">{f7a76e70-61eb-11f1-80-01-44-45-53-54-00-00}</joystick> <!-- set to "none" -->
    </joysticks>
    
    Text = DirectInput instance GUID, written with {%08lx-%04x-%04x + 8 × -%02x (so {42CEC570-0A3F-11F0-800B-444553540000} becomes {42cec570-0a3f-11f0-80-0b-44-45-53-54-00-00}). In one checked config the two DEST GUIDs match HKCU\System\CurrentControlSet\Control\MediaProperties\PrivateProperties\DirectInput\VID_03EB&PID_2054\Calibration\0\GUID (VPC MT-50 throttle) and VID_346E&PID_0014 (MOZA R5) [OBS]. The third entry {11ff28de-28de-0001-00-00-50-49-44-56-49-44} (VID 28DE PID 11FF = Steam virtual gamepad, "PIDVID" tail) is not in that key; how X4 builds GUIDs for XInput pads is [UNVERIFIED].
  • num = slot index 0-7 (0 = INPUT_SOURCE_JOYAXES/JOYBUTTONS, 1 = _2, …). Reader: no num → 0, num ≥ 8 ignored, disabled true → device gets no slot, current defaults to true and the first current entry per slot wins. Writer: slot < 8 → num="N" (+ current="0" when not current), otherwise disabled="1". The list keeps up to 32 devices (history of assignments) [OBS-bin, parser at 0x1400d5c10, writer at 0x1400d6080]. The 0-based reading comes from the binary; check it once in the game [UNVERIFIED].
  • Start-up assignment, per device in DirectInput enumeration order: disabled → skipped; listed with a free num → that slot (an auto-placed device already there moves to the next free slot); not listed → first free slot 1-8 [OBS-bin, 0x1400d31ba-0x1400d32ee]. Auto-placement only fills the in-memory slot table; the list entry (and so config.xml) is only created by SetJoysticksOption, i.e. when the user picks a device in "Manage Controllers/Joysticks" [OBS-bin: the only direct call of the slot setter 0x1400d54d0 is in the Lua binding]. Slots of devices without a num entry depend on the enumeration order and can change between sessions (matches the Steam forum complaints about changing order).
  • Max 8 slots; XInput gamepads share them (Lua joystick.xinput flag) [SRC].
  • Devices that are not disabled are auto-placed in enumeration order, as far as X4 accepts them as joysticks (the auto-place branch has a further condition that was not decoded) [INF].
  • JoyPro already has the instance GUIDs (engine/DirectInputDeviceDiscovery.cs, GameDeviceDirectory.InstanceGuid).

#Action catalog (DB\X4\actions.tsv)

  • Source of truth: config.input.controlsorder in ui/addons/ego_gameoptions/gameoptions.lua with the sections space (12 groups), menus (7) and firstperson (2); titles from t/0001-l044.xml pages 1005 (actions), 1006 (states), 1007 (ranges), with "(…)" translator comments removed [SRC].
  • 250 menu controls: 128 flight (6 axes + 122 buttons), 122 not. Flight = all space groups (Steering analog/digital, Weapons, Modes = travel/scan/long-range scan/SETA, Menu Access = radial menus, map, missions, info/comm/scan/teleport, Camera, Target Management, Misc = dock, autopilot, guidance, radar, turrets, drones, wing orders, deployables, cover, stance, container magnet, head tracking reset). Not flight: Options Menu (save/load/quit/quicksave), Accessibility (reduced game speed), Expert Settings, mouse-only rows, Pause, Screenshot, Toggle Sound, Get Up from Chair, the two "in map" rows, all menus and firstperson rows.
  • Functions (functions.tsv, 25): the menu binds several ids at once, e.g. "Toggle Travel Mode" = INPUT_ACTION_TOGGLE_TRAVEL_MODE + INPUT_ACTION_ADDON_DETAILMONITOR_TRAVELMODE (same key works inside the map), "Dock" = DOCK_ACTION + UNDOCK. Function 3 "Interact" also binds INPUT_STATE_FP_INTERACTION_MENU (on foot) and appears in the space and first-person lists.
  • all_controls.tsv: all 444 ids of the exe with numeric id, title, menu group (or function membership), libraries/contexts.xml contexts and use in shipped maps; 168 ids are not remappable in the menu (debug, cinematic camera, VR, map internals).
  • The game's own texts swap two names: INPUT_ACTION_PREV_SUBCOMPONENT is titled "Next Surface Element" and NEXT_SUBCOMPONENT "Previous Surface Element" [SRC].
  • Readable rows (X4Integration.TidyCatalog, applied whenever a list is read, so older lists read the same): the category is the menu group only ("Steering: Analog", not "space/Steering: Analog; function 16; also in ..."), and the steering controls say what they do with the game's name in brackets: "Yaw (Primary Steering Axis)", "Roll (Secondary Steering Axis)", "Pitch (Steer Up-Down)", "Strafe Left-Right (lateral thrust)", "Yaw Left (Steer Left)" ... The primary/secondary axes are X4's yaw and roll (its tooltips: "Left-right / Roll unless adaptive steering is enabled"); checked against X4 9.00 on 2026-10-24: every space-flight control of the menu is in the list (refresh: 128, 0 new).

#Catalog refresh (engine x4 refresh-db [<path>], GUI "DB refresh")

  • Source: the installed game (no path: the X4 install JoyPro detected or engine games install set x4 <folder>), or --path with the X4 folder or a folder with the two files extracted (ui/addons/ego_gameoptions/gameoptions.lua, t/0001-l044.xml, same relative paths or anywhere below). Code: engine/Games/X4CatalogSource.cs.
  • Read-only: the base archives NN.cat/.dat (*_sig skipped, a later archive overrides an earlier one; the extensions do not contain these two files on 9.00), the name tables of X4.exe. Same rules as build_catalog.py: config.input.controlsorder + controlFunctions, titles from pages 1005/1006/1007 (function rows: the function name), "(...)" translator comments removed, {page,id} references resolved; flight = section space minus the groups Options Menu, Accessibility, Expert Settings and Target Management (Mouse), minus the map/seat/system rows and mouse-only rows. Without X4.exe the numeric ids are named from order.tsv (a new id is then reported and skipped).
  • Adds only space-flight controls the catalog does not have; known rows keep id, title and category. order.tsv gets the numeric ids X4.exe has and it does not, functions.tsv the menu functions it does not list. Nothing is written when nothing is new.
  • Run on X4 9.00 (2026-10-10): 250 menu controls, 128 space flight, 444 names from X4.exe (all equal to order.tsv), 0 new. A refresh into an empty catalog reproduces the shipped actions.tsv rows exactly, and order.tsv/functions.tsv stay byte-identical.
  • Smoke test: end of engine/tests/smoke/x4.ps1 (archives packed from engine/tests/fixtures/x4-catalog).

#A user's map as observed

inputmap.xml (version 196, id 3) is the stock "Keyboard & Mouse / Controller" map with about 20 changed entries: 315 keyboard, 15 mouse, 20 radial-menu and 91 joystick entries. All 91 use slot 1 with gamepad semantics (left stick X/Y → strafe/throttle, right stick → primary steering/pitch, Z/RZ = triggers, A/B/X/Y, D-pad). No HOTAS binds, no slot 2-8, no joystick modifiers. With all known devices disabled these binds reach whatever device X4 auto-places in slot 1 [OBS].

#Pitfalls

  • Slot 1 is the gamepad slot of the default maps: a stick that lands in slot 1 inherits the stock gamepad binds (X/Y axes on strafe/throttle, RX/RY on steering, buttons 1-10 and the hat on menu/target/weapon controls) [OBS].
  • Devices with more than 64 buttons or more than one POV (VKB, VPC, WinWing in many setups) lose the extra inputs in X4 [OBS-bin].
  • X4 writes inputmap.xml and config.xml from its in-game state: both are written at the end of a session (their times match userdata.xml and Steam LastPlayed) [OBS]. Nothing may be written while X4.exe runs.

#How JoyPro should export

  1. Find files: <Documents>\Egosoft\X4\<SteamID32>\inputmap.xml (choose the folder of the current Steam user, else the newest inputmap.xml), GOG <Documents>\Egosoft\X4\inputmap.xml. Use the known-folder path for Documents (OneDrive redirection). Never touch inputmap_1-5.xml, uidata.xml, saves.
  2. Refuse while a process X4 runs. Copy to inputmap.xml.jpbak (and config.xml.jpbak if it is written) before the first write.
  3. Device → slot: read config.xml <joysticks>; slot = num+1 of the current, non-disabled entry whose GUID (X4 format) equals the device's instance GUID.
    • Device disabled="1" → skip with "disabled in X4 (Settings > Controls > Manage Controllers/Joysticks)".
    • Device without num → its slot is not stable. Version 1: skip with "assign the device to a slot in X4 once". Optional later: pin it by adding <joystick num="N">{guid}</joystick> (lowest slot not used by another current entry, never more than 8) and keep every other line of config.xml byte-for-byte; enable only after one in-game check of the num mapping.
    • XInput pads are not managed.
  4. Write inputmap.xml as text, not via a DOM rewrite: keep declaration, LF, indentation, comments, <config>, root attributes and every untouched line byte-for-byte. Insert new lines in the right section after the last entry of the same type whose numeric id (from all_controls.tsv) is ≤ the new one, two-space indent, attribute order id source [toggle] code [sgn].
  5. Encode: button n → INPUT_XBUTTON_{A,B,X,Y,LEFT_SHOULDER,RIGHT_SHOULDER,BACK,START,LEFT_THUMB,RIGHT_THUMB,BIGBUTTON} for 1-11, INPUT_XBUTTON_n for 12-64; POV 1 → INPUT_XBUTTON_DPAD_*; axes → INPUT_JOYAXIS_X/Y/Z/RX/RY/RZ/SLIDER1/SLIDER2; source INPUT_SOURCE_JOYBUTTONS[_n] for buttons and hat, INPUT_SOURCE_JOYAXES[_n] for axes (no suffix for slot 1). Ranges get no sgn. Skip with a warning: buttons > 64, POV 2-4, modifier binds (until the custom_modifier_* markup is verified), axes on non-range rows.
  6. Functions: writing a row from functions.tsv writes the same input to every member (as the menu does). Removing only removes members that are flight rows or their map/menu twins, never INPUT_STATE_FP_INTERACTION_MENU.
  7. Clean (written slots) and nuke (slots that config.xml pins with num to devices the export does not use; a slot without a pinned device is left alone because its device is unknown): remove <action|state|range> lines whose id is a flight row (or a function member of one, except FP) and whose source is INPUT_SOURCE_JOYAXES[_n]/JOYBUTTONS[_n] of those slots. This also removes the stock gamepad flight binds on slot 1 when a stick takes it. Keep non-flight ids on those slots, every keyboard/mouse/radial-menu line and every line of other slots.
  8. Keyboard only with --include-keyboard, only flight rows, INPUT_SOURCE_KEYBOARD + INPUT_KEYCODE_<DIK>[_SHIFT|_CONTROL|_SHIFT_CONTROL], never the forbidden keys.
  9. Axis options (implemented, see "Axis settings"): invert_steering_*/invert_throttle/invert_strafe_* for a range JoyPro writes when all its JoyPro axes agree (XOR the HOTAS default), bidirectionalthrottle from the throttle's Slider; the dead zone and the other settings only when set with ffb set. Every other <config> line stays.
  10. Export modes (a conflict = another flight row on the profile's source + code; the rows' map / detail-monitor twins are other contexts and never count): add skips a bind whose input another flight row has (listed as a skipped multi-bind) and removes nothing; merge adds the profile's lines beside the row's other inputs and removes only conflicts; merge-overwrite = merge + a row the profile binds loses its other lines on owned slots (pinned in config.xml to a connected device) and, with --include-keyboard, its keyboard lines. Nuke (7.) also only touches pinned slots whose device is connected.

#X Rebirth (not installed)

  • Bindings in <Documents>\Egosoft\X Rebirth\<id>\inputmap.xml, same vocabulary as X4 (<state id="INPUT_STATE_STRAFE_LEFT" source="INPUT_SOURCE_JOYBUTTONS" code="INPUT_XBUTTON_DPAD_LEFT"/>) [SRC Egosoft forum t=356563]. X4's input system descends from it [INF]; ids, the slot list and the menu catalog would need their own extraction from an install [UNVERIFIED]. Not integrated.

#X3: Reunion / Terran Conflict / Albion Prelude (not installed)

  • Changed controls are stored under <Documents>\Egosoft\X3AP\profiles (folder only exists after a change; X3TC/X3R analogous), format unknown; the launcher selects the input device [SRC Steam forum]. Different engine and format from X4; not integrated.