X4 Code Debug

X4 Code Debug is a pseudo debug adapter for Egosoft's X4: Foundations scripting language. Instead of attaching to the running game, the extension tails the game-generated log files, extracts diagnostics for the current mod, and mirrors relevant script trace output in the VS Code Debug Console.

✨ Features

Tails the newest log file matching a configurable mask inside the game log directory.
Ignores historical content at startup, then follows new lines in real time (even when logs rotate).
Parses [=ERROR=] entries that belong to the active X4 extension and surfaces them as VS Code diagnostics.
Detects AI and MD script debug messages, filters them against the extension’s scripts, and streams them to the Debug Console.
Prefixes each Debug Console error or debug message with a timestamp so you can correlate events quickly.
Works entirely offline — no dependency on launching the game from VS Code.

⚠️ Known limitations

There are no breakpoints, call stacks, or variable inspection since the game engine does not expose this information.
The extension indexes only XML scripts inside aiscripts/ and md/ folders. Other script types are ignored.
The extension does not parse or validate XML; it relies on well-formed scripts to provide accurate diagnostics.

🚀 Getting started

Install the extension

Via VS Code Marketplace

Directly from VS Code

Open VS Code and go to the Extensions view (Ctrl+Shift+X or Cmd+Shift+X on macOS).
Search for "X4 Code Debug" and click "Install".
Reload VS Code if prompted.

From the web

Visit the X4 Code Debug page on the VS Code Marketplace.
Click the "Install" button, which will prompt you to open VS Code and install the extension.
Reload VS Code if prompted.

Via VSIX file

Download the latest .vsix.zip file from the Nexus Mods: X4 Code Debug.
Extract the .vsix file from the downloaded .zip archive.
In VS Code, open the Extensions view (Ctrl+Shift+X or Cmd+Shift+X on macOS).
Click the three-dot menu in the top-right corner and select "Install from VSIX...".
Choose the downloaded .vsix file and click "Open".
Reload VS Code if prompted.

Setup a launch profile

Open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P on macOS).
Type "Debug: Open launch.json" and select it.
If prompted, select "X4 Code Debug" as the environment.
Configure the launch.json file with the appropriate settings for your X4 extension.
Save the launch.json file.

Launch configuration attributes

key	required	description
`extensionRoot`	✔	Relative or absolute path to the X4 extension to debug. Relative is based on `${workspaceFolder}` (default: `.`).
`logFolder`	✔	Directory that contains the X4 log files.
`logMask`	✔	Glob used to pick the active log (e.g. `debuglog.txt` or `.log`).
`pollIntervalMs`	–	Poll frequency for new data (default `1000`).
`maxChunkSize`	–	Maximum bytes read per poll (default `262144`).
`clearDiagnosticsOnStop`	–	When enabled, diagnostics clear when the debug session ends (default `false`).
`openFileOnError`	–	When enabled, opens the script file and jumps to the first error when a new error appears (default `true`).
`openFileOnDebug`	–	When enabled, opens the script file and jumps to the first debug message when a new message appears (default `false`).

Example launch configuration

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "X4 Code Debug",
      "type": "x4-debug-log",
      "request": "launch",
      "extensionRoot": "test",
      "logFolder": "C:/Users/YourUser/Documents/Egosoft/X4/[SteamId]/logs",
      "logMask": "debuglog*.txt",
      "clearDiagnosticsOnStop": false,
      "openFileOnError": true,
      "openFileOnDebug": false
    }
  ]
}

Preparing the game to generate logs

The comprehensive guide to setting up X4: Foundations to produce the necessary debug log file is available on the Egosoft Wiki - h2odragon's HOWTO-hackx4f

Debugging

Start the debug session by selecting the "X4 Code Debug" configuration and clicking the green play button in the Run view.
Interact with your X4 game as needed to generate log output.
Monitor the X4CodeDebug output channel for diagnostic messages and errors.
Use the information provided in the output to troubleshoot and fix issues in your scripts.

⚙️ Extension settings

setting	description
`x4CodeDebug.enableExtensionDebugLogging`	When enabled, the extension writes verbose debug logs to the `X4CodeDebug` output channel.

🧭 Diagnostics behavior

Diagnostics refresh automatically when new errors for the active mod appear.
Each error includes the parsed message plus any * Input/* Pos detail from the log.
Diagnostics clear when a new debug session starts or finishes (if set).

🎬 Video demo

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

📝 Credits

Egosoft - for the game itself (In fact - for the series of games)!
Members of the x4_modding discord channel - for their answers, support, ideas, and inspiration!

🛠 Changelog

[1.0.2] - 2025-10-10

Fixed
- Corrected the extension icon
- Resolve the VS Code–bundled node executable
- Proposal as a debugger in the launch configuration creation dropdown

[1.0.0] - 2025-10-09

Added
- Initial public version

X4CodeDebug

X4DevTools