EnglishGermanFrenchRussianPolishItalianSpanish
Log inRegister
 
Tutorial 1: New X² commands - connect a script to X²'s menus
Post new topic Reply to topic Goto page 1, 2  Next
View previous topic :: View next topic
Author Message
Reven





Joined: 10 Jul 2003
Posts: 1064 on topic
Location: HMS Indomitable
Thank you for registering your game
modified
PostPosted: Sat, 24. Jan 04, 14:32    Post subject: Tutorial 1: New X² commands - connect a script to X²'s menus Reply with quote Print

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:


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:
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:
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:
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:


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.


_________________
Ex Turbo Modestum


Last edited by Reven on Sat, 31. Jan 04, 16:54; edited 4 times in total
Back to top
View user's profile Send private message Send e-mail Visit poster's website AIM Address Yahoo Messenger MSN Messenger
LV
Sith Lord




Joined: 06 Nov 2002
Posts: 6359 on topic
Location: The Dark Side
Thank you for registering your game
PostPosted: Sat, 24. Jan 04, 16:23    Post subject: Reply with quote Print

Sticky Smile


_________________
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
Back to top
View user's profile Send private message Visit poster's website MSN Messenger
giskard





Joined: 06 Nov 2002
Posts: 5166 on topic
Location: Go to Home of Light, keep flying around & around until you fall over dizzy.
Thank you for registering your game
PostPosted: Sat, 24. Jan 04, 20:21    Post subject: Reply with quote Print

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 Smile

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.
Back to top
View user's profile Send private message
KaosKlown





Joined: 29 Nov 2003
Posts: 67 on topic

Thank you for registering your game
PostPosted: Sat, 24. Jan 04, 22:51    Post subject: Reply with quote Print

Sticky please

Thanks Reven.

Back to top
View user's profile Send private message
BurnIt!
EGOSOFT
EGOSOFT

MEDAL

Joined: 06 Nov 2002
Posts: 4435 on topic
Location: Wuerselen
Thank you for registering your game
PostPosted: Sun, 25. Jan 04, 00:41    Post subject: Reply with quote Print

Well done Reven. That's worth a sticky Smile


_________________
BurnIt!
I don't want to know who started a fight but I know who ended it.

In der Ruhe liegt die Kraft. / In peace lies strength.
Back to top
View user's profile Send private message Visit poster's website
giskard





Joined: 06 Nov 2002
Posts: 5166 on topic
Location: Go to Home of Light, keep flying around & around until you fall over dizzy.
Thank you for registering your game
PostPosted: Sun, 25. Jan 04, 01:03    Post subject: Reply with quote Print

Smile

Giskard

Back to top
View user's profile Send private message
kryptyk





Joined: 05 Dec 2003
Posts: 392 on topic
Location: MoNW
Thank you for registering your game
PostPosted: Sun, 25. Jan 04, 11:25    Post subject: Reply with quote Print

nice one Reven Thumb up

Back to top
View user's profile Send private message
dajt





Joined: 13 Dec 2003
Posts: 10 on topic

Thank you for registering your game
PostPosted: Tue, 27. Jan 04, 03:35    Post subject: Great Explanation Reply with quote Print

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
Back to top
View user's profile Send private message
Buzzark





Joined: 22 May 2003
Posts: 78 on topic

Thank you for registering your game
PostPosted: Wed, 28. Jan 04, 16:47    Post subject: Reply with quote Print

Quality piece of informative writing. Thanks!

Back to top
View user's profile Send private message
taronas





Joined: 26 Aug 2003
Posts: 255 on topic

Thank you for registering your game
PostPosted: Fri, 30. Jan 04, 09:41    Post subject: Reply with quote Print

thanks for this info!

Quote:
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

Back to top
View user's profile Send private message
Reven





Joined: 10 Jul 2003
Posts: 1064 on topic
Location: HMS Indomitable
Thank you for registering your game
PostPosted: Fri, 30. Jan 04, 14:46    Post subject: Reply with quote Print

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.


_________________
Ex Turbo Modestum
Back to top
View user's profile Send private message Send e-mail Visit poster's website AIM Address Yahoo Messenger MSN Messenger
The_Abyss





Joined: 12 Nov 2002
Posts: 8474 on topic
Location: UK
Thank you for registering your game
PostPosted: Fri, 30. Jan 04, 16:14    Post subject: Reply with quote Print

Great work Reven - excellent guide.


_________________
Strung out on Britain's high, hitting an all time low
Back to top
View user's profile Send private message Visit poster's website
Nemesi$





Joined: 12 Nov 2003
Posts: 116 on topic
Location: X=5325; Y=-10576; Z=837
Thank you for registering your game
PostPosted: Fri, 30. Jan 04, 16:36    Post subject: Reply with quote Print

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]
Back to top
View user's profile Send private message
Reven





Joined: 10 Jul 2003
Posts: 1064 on topic
Location: HMS Indomitable
Thank you for registering your game
PostPosted: Sat, 31. Jan 04, 17:01    Post subject: Reply with quote Print

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. Smile

p.s. Tutorial 2 is now up, and there are 4 (maybe 6) more coming. Feeling ambitious? Question


_________________
Ex Turbo Modestum
Back to top
View user's profile Send private message Send e-mail Visit poster's website AIM Address Yahoo Messenger MSN Messenger
Nemesi$





Joined: 12 Nov 2003
Posts: 116 on topic
Location: X=5325; Y=-10576; Z=837
Thank you for registering your game
PostPosted: Sat, 31. Jan 04, 20:10    Post subject: Reply with quote Print

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

<?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]
Back to top
View user's profile Send private message
Display posts from previous:   
Post new topic Reply to topic Goto page 1, 2  Next
 
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum
You cannot attach files in this forum
You can download files in this forum
Control Panel
Login Data
The time now is Sat, 19. Aug 17, 18:31

All times are GMT + 2 Hours


Board Security

Copyright © EGOSOFT 1989-2017
Powered by phpBB © 2001, 2005 phpBB Group
Template created by Avatar & BurnIt!
Debug: page generation = 0.81477 seconds, sql queries = 29