X Rebirth Official Tools

The place to discuss scripting and game modifications for X Rebirth.

Moderators: Moderators for English X Forum, Scripting / Modding Moderators

User avatar
Posts: 11796
Joined: Fri, 21. May 04, 17:15

X Rebirth Official Tools

Post by Ketraar » Wed, 26. Feb 14, 15:52

X Rebirth Official Tools

On Steam, a tool collection called "X Tools" is available for owners of X Rebirth and X4: Foundations (formerly known as "X Rebirth Tools").

To install the tools, just click here. Alternatively, go to Library -> Tools in your Steam client, scroll down to "X Tools" and double-click the entry.
Please Note: If you have a Non-Steam version of X Rebirth, the tools can be downloaded here.

Steam will treat this application like any other game, so for example the Launch button will be called "Play". Don't be confused by that.

The X Tools contain the X Catalog Tool, which can be used to extract and create .cat/.dat files. Both console and Windows GUI versions of the catalog tool are available.

When launching X Tools, Steam will ask you what you want to do. You have the following options:
  • Play X Tools
    This will launch the Windows command console in the X Tools directory. You can run console-based tools like XRCatTool from there.
  • Readme
    This will open the Readme text file. Make sure you read it before using any tools.
  • Catalog Tool
    This launches the GUI version of the catalog tool, which you can use to extract or create .cat/.dat files.

Steam Workshop

With the Steam Workshop, finding and installing X Rebirth extensions is now easier than ever before. Just browse the extensions in the Workshop, subscribe to an extension that you are interested in, and it will be installed automatically the next time your start X Rebirth. Just make sure you read the description and check for incompatibilities with other subscribed extensions.

Extensions from the Workshop will also be updated automatically when the author submits updated content. To disable an extension on the next game start, just unsubscribe from it, either in-game or on the Steam website.

For more information, see the Workshop guide.


X Rebirth Mission Director

The Mission Director (MD) is a subsystem of the game and interprets mission scripts written in an XML-based language. The MD in X Rebirth is based on the same core concepts as the MD in X3: Terran Conflict, but with major changes based on feedback from MD users and a completely new implementation. To help with that EGOSOFT has made the X Rebirth Mission Director Guide available to the public. It contains a vast amount of information for everyone wanting to learn their ways around the MD.



The DebugLog is a useful helper with regards to track errors/issues in the engine. It records any error which occurred (including script errors) and reports it to the user.

Instruction on its use and functionality can be found here


Command Line

The Command Line allows you to enter certain commands to trigger debug functionality. This can be particularly helpful for scripters.

Instruction on its use and functionality can be found here


AI Scripts

To maintain compatibility with older versions of AI scripts, which may be restored from a savegame, there are some special measures that you have to take. At time of saving a game, the most important state information of an AI script is the blocking action that it is currently in. When loading a savegame, the blocking action has to be found again. This imposes some restrictions on how to change existing scripts in newer versions.

How to add new blocking actions? The <aiscript> node can have a version attribute. Without the attribute, the version is assumed to be 0. All blocking actions, including <run_script>, now have the attribute "sinceversion". So when creating a new version of the script, increment the script version, and add new blocking actions with the according sinceversion attribute.

There is a validation mechanism in the game that can find out if you have forgotten a sinceversion attribute, see the command line documentation. However, note that there is no such validation when a savegame is loaded. When loading a savegame with incompatible scripts, the affected scripts will be in wrong states. This may not be obvious right away after loading, but it can break the AI in many subtle ways.

Some helpful facts and restrictions:
  • You CANNOT remove a blocking action in a later version
  • however, you can e.g. use chance="0" so it's skipped in the future.
  • You CANNOT change the order of blocking actions in the script (e.g. move a <wait> past a <run_script>).
  • Be careful when adding a new <attention> node, or when changing the min attribute of an existing node. For the affected attention level(s), blocking actions of old and new <actions> have to be compatible.
  • You SHOULD NOT rename or remove label sections which contain any blocking actions, or move the blocking actions to another label section. (Doing so is not really harmful but it affects the label to which an interrupted script will return.)
  • You CAN add, remove or change any non-blocking actions without restrictions, except for <label> (see above).
  • You CAN change the flow control surrounding blocking actions, e.g. move them in or out of <do_if>, <do_while> etc.
  • You SHOULD NOT move blocking actions in or out of blocks of a repeating <do_all> (e.g. with exact, min, or max attribute).
  • You SHOULD NOT change the counter variable name of a repeating <do_all> if it contains blocking actions.
  • You CANNOT remove or rename scripts that contain blocking actions. Changing the file name is OK, since only the internal name matters. (If you do rename or remove them, this triggers a return to the previous script on the callstack, but with an error message.)
  • You CAN add new scripts, of course.
  • You CAN change the interrupt priorities of scripts. This automatically adjusts the priorities of existing callstacks. It's up to you to make sure that the callstack priorities still make sense after loading a game.
  • You CAN add, remove or change global interrupt conditions, actions, and script calls. Global interrupt handlers are not saved, they are set up again when loading a game.
  • You CAN add, remove or change <interrupt>, <interrupt_after_time> and <on_attentionchange> nodes of blocking actions. They are set up again when loading a game.
  • You CAN change the delays in <wait> and <interrupt_after_time>. The start times of blocking actions are saved, and the delays are re-evaluated when loading a game (even if they are random!).
  • You CAN change the content of blocking actions, but you SHOULD NOT change the attributes that define objects that the blocking actions run on (e.g. the object of a <move_to> action) - these are re-evaluated when loading a game, so the blocking actions can be finished correctly.
Analogously to MD cues, AI scripts can have <patch> elements to perform patch actions immediately after loading a savegame of an older version. See the XML schema documentation.

You can update AI scripts at run-time using a mechanism similar to the MD refresh, which is quicker than saving and reloading the game. Use the command "refreshai" on the in-game command line.



To keep things clean we encourage anyone with questions about any of the here listed tools to post them in the Rebirth Tools Discussion Topic where experience can be shared and questions answered.


Return to “X Rebirth - Scripts and Modding”