Tutorial 1: New X² commands - connect a script to X²'s menus

The place to discuss scripting and game modifications for X²: The Threat.

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

User avatar
Reven
Posts: 1133
Joined: Thu, 10. Jul 03, 07:42
x4

Tutorial 1: New X² commands - connect a script to X²'s menus

Post by Reven » Sat, 24. Jan 04, 13:32

Introduction
We are all familliar with the in-game ship's command menus. Navigation, Combat, Trade, Special... and you can also add in Turrets. Egosoft has made X² extremely extensible, and that includes these menus. Many of us by now have downloaded and installed scripts that add in more functionality, such as BurnIt!'s new Trade Command Extension Mk. 3 with it's "Start Sector Trader" command. I am going to go step-by-step on how to take your script and integrate it in the game - show you how to make your own new commands.

This is not a tutorial on scripting in general. I would caution you that with scripts, you can do almost anything - and scripting is quite complex. If the meaning of a scripting command isn't clear to you, then I advise extreme caution in playing with it. Definitely don't do it and then overwrite a save. I suggest everyone start a new game and get a save close to the beginning that you use for your script writing.

I am going to use as an example in this tutorial, a script I wrote that attaches into the trade menu. This script attempts to maintain the amount of product in a factory at a set level. This is useful if you have a factory that can only hold a very small amount of product, and you don't want to have to transfer the product manually to a transport all the time. A full explanation for the script and reasoning behind it is in my post on the subject.

Requirements
  • A copy of this tutorial's companion scripts.
  • An XML editor is useful, but not a must. I prefer simple ones, such as Peter's XML Editor. There are lots of others though, many of them free.
Procedure
There are three basic steps to attaching a script to the command menus. First of all, you obviously need the script you are going to attach in. Secondly, you need an XML language file that contains the added text for the game. Lastly, you need another script - one that is run automatically each time X² starts up and actually does the attaching of the script to the menu system.


Step 1
The source script. As this isn't a tutorial on scripting in general, we're not going to cover this step in much depth at all. I will say, though, that one of the best ways to learn scripting is to go over those that have already been done. I would suggest downloading X2Modder by OlisJ and using this to decompress X²'s built-in scripts. Egosoft was nice enough to provice a fairly nice XSL stylesheet for X² scripts, so you can simply double-click on them once they have been decompressed to view them.

Step 2
Here we start getting to the heart of the issue. Most of the game-text for anything from wares to ship descriptions to menu commands are stored in external XML language files. These files reside in one of two places: they can either be in the X2\t directory, or they can be inside container files (very similar to .zip files). Most of the text already in the game is in XML language files that are inside the *.CAT/*.DAT file pairs in the X² main folder. Any file that is inside one of these containers is treated just as if it were in the normal subdirectories under where you installed X². You can use X2Modder to decompress these containers and look to see what they hold. If you are using the 1.2 patch of X², then the 03.CAT/03.DAT file pair is the container that holds the language files with most of the existing in-game text. These files are 440001.XML and 440002.XML. If you have downloaded and installed BurnIt's Trade Command Extension Mk. 3, then in the X2\t directory you will find 440003.XML. This file contains the added text needed for that new script.

You will have noticed by now that there is a pattern to the way these files are named. The first two digits is actually the language code; 44 is English . You will notice that BurnIt!'s extension came with a '49' file too - which is German. If you want your added scripts to work in multiple languages, then you will need to provide XML language files for each language. This might not be a bad idea, even if the text in them is still in English.

After the language code, the rest of the filename contains a number that is used simply to identify an individual language file to any script that wants to use it. You will use this number to "load" the text from an XML language file into the game from within a script.

Put the language code and the ID number together, and you get the whole filename "440003.XML".

Many people are writing scripts with installers that actually modify the 440003.XML file in order to store text in it. This is the wrong way to do it. I suspect they are doing it this way because they don't know the correct way to add their own new files to X². The whole purpose of being able to have multiple addon language files is so that you don't need to fool with existing (ie: someone else's) language files if you want to add something later on. You simple add another file in.

You will need to pick an ID number for your file. It is important that this ID number not conflict with ID numbers used in any other script or mod. There is an effort underway right now to make a central authority for assigning these numbers, but this is not yet in place. For the time being, I highly recommend you follow these guidelines:
  • Don't use fairly low numbers. 440001.XML through 440003.XML have already been used by Egosoft. It's a sure bet that official Egosoft addon scripts in the future will use more.
  • If you write and release multiple scripts, use one file for all of them. Essentially, this means using one XML language file for ALL your scripts. If/when you release your scripts, release them in two parts - release your scripts seperately from your XML language file. That way anyone downloading it will always get the latest version of it that will work with any and all scripts you have released. This might mean that there is text in the language file that a person is using that is for a script he or she doesn't use. Although there are more ID numbers that are used within XML language files that are potential sources of conflicts, by the time there are enough scripts out there to make these type of conflicts likely, there should be a central method in place for assigning them.
Enough about language files in general - we'll talk about what we need specifically to add a command in to the menu system (you might want to look at the example file, 440021.XML at this point). There are two pieces of text we need to add to the game: the long name of the command, and the corresponding short version of it. Depending on where you are in the game, you will see either a command's long or short name. In the actual menu system you see both, as shown in the illustration:

[ external image ]
Long and short command names

In my example, I chose "Maintain Product Quantity" for the long name, and "MaintainQuant" for the short.

The language files use an XML "PAGE" tag to identify text used for different purposes. A "PAGE" tag with an ID attribute of 2010 identifies text that is for a command's long name whereas 2011 identifies text for a command's short name. Notice as well that the 't' text tag that we are using to mark the text has an ID attribute of 421 and that it's the same ID for both the long and the short. This is important in step 3.

For a single added command, that is all the added text that needs to appear in the XML language file.

Step 3
We have the script we want to use for our new command, and we have an XML language file that will be used for the command menu's text. Now we need to make a little script that links them together in the game. This is one thing that an init script is used for.

An init script is any script with a filename that starts with (surprisingly enough) "init.". Any script named with that prefix will be executed automatically every time X² is run. It is vitally important that you are careful with these. A bug in one could potentially have serious ramifications later on. The example init script is in the file "init.cmd.maintprod.xml".

Our init script must perform three tasks: it needs to load in the XML language file, it needs to tell the game what in-game ware our command is to be linked to, and then it needs to attach our script to a command and tell the game what ships can use this command.

First, loading the XML language file. The first statement in the example is:

Code: Select all

load text: id=21
Remember when we talked about the filename for the XML language file, how it had the language code at the beginning (44 for english) and an ID number at the end we would use to load it with... well, that is that that statement does. If you are playing the english version of the game, this statement tells X² to load the XML language file "440021.XML".

Now we need to attach our script (the example one is called "ship.cmd.maintprod") to a command in the game. An X² "command" is simply an in-game action that you can reach through the menuing system somewhere. There are (obviously) a whole bunch of pre-defined in-game commands in X² - all of which are attached to scripts by the init scripts supplied with the game. While it is possible to add in wholely new commands, this adds complexity to the procedure. Luckily, we don't need to add in a new command. Egosoft was quite nice to us and made 32 extra commands of each type. These are commands that aren't attached to any script - whose sole purpose is to be there for people like us who want to use them to attach scripts to later on.

To use one of these extra commands, we first need to tell the game what "ware" will house our command. That is, what does a person need to buy in order to get access to the command. In the case of the example, we are going to have this command included with the "Trade command extension Mk. 1" ware. So we tell the game any ship that has the "Trade command extension Mk. 1" will be able to use our new command. How do we do this? The next statement in the example init script shows us:

Code: Select all

set ship command upgrade: command=COMMAND_TYPE_TRADE_21  upgrade=Trade Command Software MK1
Remember when we said that the text ID tag (421) in the language file would be important later? This is where it is important. ID #421 corresponds to the COMMAND_TYPE_TRADE_21 command. The "4" refers to the extra trade commands, and 21 refers to the #21 (from 0 to 31) in the list. If, for example, we wanted to have our command in the "Special" menu instead of "Trade", then we would have use the text ID tag "521" in our XML language file, and then use COMMAND_TYPE_SPECIAL_21 instead. Nav commands have ID tags that start with "2", Combat commands start with "3".

Now we have loaded the language file, and told the system that we are adding in a new command and have told it how to find the text for the new command in the XML language file. All we need to do now is link the command to our script:

Code: Select all

global ship map: set: key=COMMAND_TYPE_TRADE_21, class=Ship, race=Player, script='ship.cmd.maintprod', prio=0
global ship map: ignore: key=COMMAND_TYPE_TRADE_21, class=Big Ship, race=Player
There are two statements we use in our example to accomplish this. The first one says: allow the command COMMAND_TYPE_TRADE_21 to be used on any type of ship (class=Ship means all ships) by the player (that's you) and that we want to attach script "ship.cmd.maintprod" to this command and run it at a priority of zero (normal priority) any time it's run.

Now, since in our case this command is useless for a ship of class M6 or larger (since they can't dock to a factory anyway), the next statement says that the command should be attached to whatever ships it was attached to before (which was all of them) except for ships of class "Big Ship" (which is M6 or larger).

We could have done this differently. We could have had a separate statement to attach the command to each class individually (M5, M4, M3, TS, TL, Goner). It saves a little room this way, though, to say attach to all of them and then give the exception. You can decide which way is most appropriate for your script/command.

Deployment
Now we've created a script, written a language file for a command for it, and attached the script to a commant. All that's left now is to deploy our new command. The scripts just need to be in X²'s script directory. The XML language file goes in X²'s "t" directory. And that's all there is to it. If you've done it correctly, you will get a menu that looks like this:

[ external image ]
The results of our labours

Note
I used the number 21 twice here - once to denote the ID number for the XML language file, and once to denote which extra trade command to use. This was probably a poor choice, since it might make for a little confusion. If you're confused between the difference between the XML language ID number, and the command text ID tag number within the language file, then read things over again carefully.
Last edited by Reven on Sat, 31. Jan 04, 15:54, edited 4 times in total.
You were warned... pirates will be hunted down like vermin.

Ex Turbo Modestum

User avatar
LV
Sith Lord
Posts: 8255
Joined: Wed, 6. Nov 02, 20:31
x3tc

Post by LV » Sat, 24. Jan 04, 15:23

Sticky :)
LV's TC Scripts
Readme's For All My Scripts


I felt a great disturbance in the forum, Like millions of voices cried out in terror, then were silenced

si tacuisses, philosophus mansisses

User avatar
giskard
Posts: 5230
Joined: Wed, 6. Nov 02, 20:31
xr

Post by giskard » Sat, 24. Jan 04, 19:21

Im not going to pretend to understand a word of that tutorial at this time.

However I have read it and I must say Reven, you have nicely touched upon problems most users such as my self would have fallen into if we just started scripting.

Its good to be fore warned about such things sometimes :)

I said id wait for the Egosoft docs before diving in (pure lazyness on my part) but i think you did such a great job on the basics of adding stuff to the game (in this case your script idea) I may well give it a go before egosoft release their docs.

OR begin the study part at least.

Great work Reven.

I hope Egosoft mods make this thread sticky.

In the mean time, i'll take your advice about organising my scripts, you have clearly thought it through. Thanks for taking the time and explaining your reasons.

BTW i do not know if anybody has ever pointed this out but 44 the England Area Code if your telephoning the UK. 49 is the German Area Code if your Telephoning Germany. If Egosoft where using REAL area codes for their language files then a complete list could probably be found in any telephone book. Just ignore the Zeros at the start of the number.

Giskard
This signature has been stolen by the well known Teladi Signature Thief X Siggy.

KaosKlown
Posts: 68
Joined: Sat, 29. Nov 03, 18:22
x3

Post by KaosKlown » Sat, 24. Jan 04, 21:51

Sticky please

Thanks Reven.

User avatar
BurnIt!
EGOSOFT
EGOSOFT
Posts: 5066
Joined: Wed, 6. Nov 02, 20:31
x4

Post by BurnIt! » Sat, 24. Jan 04, 23:41

Well done Reven. That's worth a sticky :)
BurnIt!
In der Ruhe liegt die Kraft. / In peace lies strength.

User avatar
giskard
Posts: 5230
Joined: Wed, 6. Nov 02, 20:31
xr

Post by giskard » Sun, 25. Jan 04, 00:03

:)

Giskard

kryptyk
Posts: 483
Joined: Fri, 5. Dec 03, 20:19
x4

Post by kryptyk » Sun, 25. Jan 04, 10:25

nice one Reven :thumb_up:

dajt
Posts: 10
Joined: Sat, 13. Dec 03, 00:11
x2

Great Explanation

Post by dajt » Tue, 27. Jan 04, 02:35

Thanks for the very clear explanation!
SpaceHulk-SP, the most complete free single player version available. See it at http://www.sourceforge.net/projects/hulk

Buzzark
Posts: 98
Joined: Thu, 22. May 03, 18:00
x3

Post by Buzzark » Wed, 28. Jan 04, 15:47

Quality piece of informative writing. Thanks!

taronas
Posts: 354
Joined: Tue, 26. Aug 03, 20:31
x4

Post by taronas » Fri, 30. Jan 04, 08:41

thanks for this info!
Egosoft was nice enough to provice a fairly nice XSL stylesheet for X² scripts, so you can simply double-click on them once they have been decompressed to view them.
unfortunately this XSL contains a bug so it works not with mozilla (my default xml viewer). For bugfix please see here: http://www.egosoft.com/x2/forum/viewtopic.php?t=20704

User avatar
Reven
Posts: 1133
Joined: Thu, 10. Jul 03, 07:42
x4

Post by Reven » Fri, 30. Jan 04, 13:46

taronas wrote:unfortunately this XSL contains a bug so it works not with mozilla (my default xml viewer). For bugfix please see here: http://www.egosoft.com/x2/forum/viewtopic.php?t=20704
Fantastic. I had switched over my .xml files to open with IE since they wouldn't open in Mozilla. I didn't even look at it before I did this, and I suppose I should have. Thanks for this info - I love Mozilla, and it's great to get my scripts working with it.
You were warned... pirates will be hunted down like vermin.

Ex Turbo Modestum

The_Abyss
Posts: 14933
Joined: Tue, 12. Nov 02, 00:26
x3

Post by The_Abyss » Fri, 30. Jan 04, 15:14

Great work Reven - excellent guide.
Strung out on Britain's high, hitting an all time low

Nemesi$
Posts: 120
Joined: Wed, 12. Nov 03, 19:05
x4

Post by Nemesi$ » Fri, 30. Jan 04, 15:36

Indeed a very informative tutorial. It was the reason for me to dig deeper into X²-Scripting ;]

@Reven
I hope you don't want to kill me for my translation of your tutorial into german -> http://www.egosoft.com/x2/forum/viewtopic.php?t=21913

*g*
Die Zehn Gebote haben 279 Wörter, die amerikanische Unabhängigkeitserklärung hat 300 Wörter. Die EU-Verordnung zur Einfuhr von Karamelbonbons hat 25911 Wörter. [Bodo H. Hauser]

User avatar
Reven
Posts: 1133
Joined: Thu, 10. Jul 03, 07:42
x4

Post by Reven » Sat, 31. Jan 04, 16:01

Mind... I'm flattered that you would translate it.

However, there is one issue, and that is someone who has a German version of the game will end up not being able to use the scripts, as it will try and load up a german version of the language file.

If you would be so kind, I would appreciate it if you could translate the strings in the file 440021.xml (located in the download zip file). If you PM me the translations, I'll add a 490021.xml file to the archive, which is what our German friends will need.

Thanks again for doing that. I only wish I could read it to see how well it translates. :)

p.s. Tutorial 2 is now up, and there are 4 (maybe 6) more coming. Feeling ambitious? :?:
You were warned... pirates will be hunted down like vermin.

Ex Turbo Modestum

Nemesi$
Posts: 120
Joined: Wed, 12. Nov 03, 19:05
x4

Post by Nemesi$ » Sat, 31. Jan 04, 19:10

The german version of the 440021.xml should look as followed:
490021.xml

Code: Select all

<?xml version="1.0" encoding="UTF-8" ?>
<language id="49">

<page id="2010" title="Commands" descr=" ">
 <t id="421">Produktanzahl aufrechterhalten...</t>
</page>

<page id="2011" title="Commands" descr=" ">
 <t id="421">ProdAnzauferhalt</t>
</page>
</language>
As soon as I have the time and if I'm in the mood, I'll try to translate the new one.
Die Zehn Gebote haben 279 Wörter, die amerikanische Unabhängigkeitserklärung hat 300 Wörter. Die EU-Verordnung zur Einfuhr von Karamelbonbons hat 25911 Wörter. [Bodo H. Hauser]

derekclifford
Posts: 1
Joined: Sat, 17. Apr 04, 04:45
x2

Post by derekclifford » Tue, 4. May 04, 01:59

Hello,
First may I say what a good game this is!!!!!!
Lots of fun. I have a question about moding the ships, I can't work out from the text file of the ship and the weapons, how and what the relation is between the two. How do I change the weapons of a ship? I can change most other thing and get them to work with no problem.

Please help, I have spent hour and hours trying and your the last hope!!!!

Shara
Posts: 244
Joined: Tue, 24. Feb 04, 19:37
x2

Post by Shara » Tue, 4. May 04, 18:31

Get Storm Front's modding kit:

http://www3.telus.net/public/starnet/ot ... .v.4.0.zip

He has Excel spreadsheets that breakdown all of the TShip/TBullets/TLaser files, and tells you what each delimited item is. Using this, it is easy to figure out what to change.

puffer
Posts: 11
Joined: Fri, 30. Jul 04, 21:59
x2

Post by puffer » Fri, 10. Sep 04, 22:03

Super, great, and awesome! Thanks Reven.

Your explanation was so straightforward that my first attempt worked.
I had made some of my own scripts, but going into the script editor to run them seemed to take some of the "game" away from the game. Not to mention the hassle it was. I'm gonna link all my scripts now!

Thanks again.

User avatar
apricotslice
Posts: 14129
Joined: Sun, 16. May 04, 13:01
x4

Post by apricotslice » Tue, 25. Sep 07, 15:25

I came accross this guide looking for how to set up commands for X3.

Is the init. script name still used for X3, as I cannot find any, just a few !init... files.

If theres a more up to date command guide for X3, can someone link me to it please ?

Cycrow
Moderator (Script&Mod)
Moderator (Script&Mod)
Posts: 22201
Joined: Sun, 14. Nov 04, 23:26
x4

Post by Cycrow » Tue, 25. Sep 07, 16:01

u could not really use init scripts, u use setup scripts instead.

for X3, http://x3.ircwhore.co.uk/help/command/command.html

Post Reply

Return to “X²: The Threat - Scripts and Modding”