Joined: 21 May 2004
Posts: 8530 on topic
Location: Guimar„es (Portugal)
|Posted: Wed, 26. Feb 14, 16:52 Post subject: X Rebirth Official Tools
|X Rebirth Official Tools
On Steam, a new tool collection called "X Rebirth Tools" is now available for owners of X Rebirth.
To install the tools, just click here. Alternatively, go to Library -> Tools in your Steam client, scroll down to "X Rebirth 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.
Currently the X Rebirth Tools only contain the XR 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 Rebirth Tools, Steam will ask you what you want to do. You have the following options:
- Play X Rebirth Tools
This will launch the Windows command console in the X Rebirth Tools directory. You can run console-based tools like XRCatTool from there.
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.
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
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
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 are used for the event sources
- they are re-evaluated in RestoreBlockingState(), see above.
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.
There is no mechanism like the MD refresh to update AI scripts at run-time. Saving and reloading the game is the only way to get close to this.
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.