Tutorial 2: Adding new command extension wares to X²

[Reven]

Introduction

Adding new commands to X² is great, but at some point we are going to want to make a user have to actually do something in the game in order for them to get their greasy mitts on your hard work. After all, X² is a space simulation. The old saying that one does not appreciate what one does not have to work for is, in my opinion, quite true.

In this tutorial we will learn how to create a new command extension ware in X², and learn how to tie new commands into it. As an example for this tutorial, we are going to create a script that adds the new ware called "Hire Gunnery Crew". After all, a "ware" doesn't need to be an actual object. We can use a new ware to simulate any sort of action a player performs where the player pays money for something. In this case, hiring expert crews to man your ship's turrets.

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.
• For this tutorial, a copy of Oliver "OlisJ" Lyven's X2Modder will be quite useful.

Procedure

Adding a new ware can be a very complicated process. A future tutorial will go into more detail on the modding process of creating a new ware from scratch. We will focus here on specifically adding command extensions, as that is the ware that is most useful to a script-writer.

Since this process is essentially a continuation of the process of adding new commands, you obviously need to have a new command to attach to the new ware you will create. After this, you need to select the blank ware that will be used to hold your new one, and then edit your XML language file to contain the added strings you need. Finally, we need another init script to tell X² which stations to add our new ware to.

Step 1
The first step is, as mentioned, to create a new command that will attach to the command extension ware you want to add. This topic is covered in Tutorial 1.

Since the command example from that tutorial is too basic to justify adding it to a brand new extension, the sample for this lesson is a stub (empty placeholder) script that we will complete in an upcoming tutorial (#4 on combat scripting). Just to whet your appetite, this new command is the "Turret->Assign gunnery crews to turret" command and will be an advanced turret-control script that will intelligently (at least as intelligently as I can program) select targets based on their threat level. It will also switch between multiple weapon types (if available) depending on what is most appropriate for the current target at the current range.

Step 2
Adding a new ware from scratch is more in the neighbourhood of a mod than a script. However, similar to the extra "blank" command slots that Egosoft has provided for us, there are 20 extra command extension wares.

The wares are all defined in "type" files, which are simply text files that contain all the information needed to define each different ware. These text files are compressed, and then packaged into container files. The container file pair 02.cat/02.dat is one that holds the ware definition type files (instructions on how to view the type files are located at the end of the tutorial).

The last 20 lines of the type file TWareT.txt are the entries for the extra "blank" command extensions that you will use to add new ones.

Code: Select all

TWareT.txt
28;0;0;0;0;59;5753;0;35714;1;1;0;SS_WARE_SW_NEW1;
28;0;0;0;0;60;5763;0;17;1;1;0;SS_WARE_SW_NEW2;
28;0;0;0;0;61;5773;0;14;1;1;0;SS_WARE_SW_NEW3;
28;0;0;0;0;62;5783;0;56;1;1;0;SS_WARE_SW_NEW4;
28;0;0;0;0;63;5793;0;88;1;1;0;SS_WARE_SW_NEW5;
28;0;0;0;0;64;5803;0;283;1;1;0;SS_WARE_SW_NEW6;
28;0;0;0;0;65;5813;0;383;1;1;0;SS_WARE_SW_NEW7;
28;0;0;0;0;66;5823;0;1389;1;1;0;SS_WARE_SW_NEW8;
28;0;0;0;0;67;5833;0;3396;1;1;0;SS_WARE_SW_NEW9;
28;0;0;0;0;68;5843;0;4215;1;1;0;SS_WARE_SW_NEW10;
28;0;0;0;0;69;5853;0;5635;1;1;0;SS_WARE_SW_NEW11;
28;0;0;0;0;70;5863;0;65735;1;1;0;SS_WARE_SW_NEW12;
28;0;0;0;0;71;5873;0;17857;1;1;0;SS_WARE_SW_NEW13;
28;0;0;0;0;72;5883;0;35445;1;1;0;SS_WARE_SW_NEW14;
28;0;0;0;0;73;5893;0;324515;1;1;0;SS_WARE_SW_NEW15;
28;0;0;0;0;74;5903;0;638508;1;1;0;SS_WARE_SW_NEW16;
28;0;0;0;0;75;5913;0;225755;1;1;0;SS_WARE_SW_NEW17;
28;0;0;0;0;76;5923;0;1931535;1;1;0;SS_WARE_SW_NEW18;
28;0;0;0;0;77;5933;0;2209150;1;1;0;SS_WARE_SW_NEW19;
28;0;0;0;0;78;5943;0;6727565;1;1;0;SS_WARE_SW_NEW20;

As you can see, the entries are simply lines of values separated by semicolons. Out of the 13 columns, we are interested in the 7th and 9th. The 7th column is a reference to an entry in the XML language file that will be for this ware. The 9th column is the price of the ware. To get what the final cost will be (or at least close to it), multiply the values in the 9th column by 28. The price you want your extension to be will be one of the major factors in determining which one to use for your new ware.

As an example, when Egosoft made the "Trade Extension MK3" plugin, they wanted the new extension to cost around the 500,000 credit mark. So, they used the SS_WARE_SW_NEW_13 entry. This brings us to the other major factor in determining which one to use for your new ware, and that is which ones have been used in other writers' published scripts.

Unfortunately, there is not currently any easy way to know what has been used with other scripts released by other writers. As mentioned in Tutorial 1, there is an effort underway to form a working group that will assign and track the usage of these types of resources, but until this is in place, the best way to find out is to post in a forum and ask. If you use an entry that someone else has used before, it is not necesarily catestrophic. It simply means that your script will not be able to be used by a player who also uses the other, conflicting one.

The only one currently used by an official Egosoft script is the SS_WARE_SW_NEW_13 entry noted above. This should be avoided by all script writers.

For our example, I want a price point that is quite high, so I chose SS_WARE_SW_NEW12. The price of this one (column 9) is 65735 * 28 = ~1.8 million credits. We now note the value in column 7, which is 5863, and go on to the next step.

Step 3
We need to return to our XML language file now. We will continue to use the one from the first tutorial, 440021.xml.

If you load up the copy of this file included with this tutorial's sample scripts, you will notice an addition since last tutorial. There is a new page, page 17. This very important page contains the text strings for all space object names (a space object is anything that can be in space - factories, stations, ships), and also all possible equipment and wares.

Any entry that ends in "1" is the name of a space object. If it ends in "2", it is the description for a space object. If it ends in "3" it is the name of a ware, and if it ends in "4" if it is the description of a ware.

Remember the number we noted from column 7 of the ware type file? The number was 5863. As this ends in 3, you now know that this is the text ID number that we need to use to assign a name to this ware. To add a description to the ware, we simply use the next entry, 5864. Our addition to the XML language file, then, could look like this:

• <page id="17" title="Boardcomp. objects" descr="Quad line groups for ware factory pairs or twins (spoken by Boardcomputer)">
  • <t id="5863">Hire gunnery crews</t>
  • <t id="5864">
    • You can hire highly trained gunnery crews to man your ship's turrets. These experienced crews are generally considered to be far more effective than the standard combat AI software that is commonly in use today.
    </t>
  </page>

Step 4
Our final step is to create the scripts that we will use to configure the galaxy with our new ware. For this, we use another "init" script. This time, init.plugin.guncrews.xml. For the most part, this script is identical in function to the init script we created in Tutorial 1. It creates a (as of right now, non-functional) new command and attaches it to a script and a ware. However, right at the beginning, we have one difference:

Code: Select all

START [THIS] -> call script 'plugin.guncrews.init' :

We fork off a second script right at the beginning of our init. Why do this? This is because of the way init scripts work in X². When this init script is run, the rest of the galaxy hasn't yet been defined. Since the purpose of this is to add a new ware type to an existing equipment dock, we can't do this when the galaxy hasn't been "created" yet. So, we need to put in a delay. However, since the init scripts are executed sequentially, we can't implement our delay directly within it. This would delay everything else. What we do is call another script with the START prefix. This tells the script engine to "fork" off another process - to run the specified script in parallel with what it is currently doing. It is this second script where all the real work of putting our new ware into the universe will be done.

The very first thing we need to do in this second script is to implement the delay we talked about.

Code: Select all

@ = wait 1 ms

We don't need to delay very long. Just the process of putting in the delay will cause the script engine to reschedule this process at the end of it's queue. Since all the galaxy creation work will then be scheduled ahead of it, after this short delay we can be assured that we can safely interact with objects in the universe.

Now we get into the real meat of placing our new ware. The first thing we need to do is find the sector that contains the station we will want to have sell our new ware. In this case, Argon Prime. The coordinates of Argon Prime are 1,3. That is, it's the second sector from the left (coordinates start at 0, so 1 is the second sector from the left), and the 4th sector down. We plug these galactic coordinates into the script engine's get sector statement:

Code: Select all

$ArgonPrime = get sector from universe index: x=1, y=3

Next we want to find the station within the sector that we want:

Code: Select all

$EquipmentDock =  find station in galaxy: startsector=$ArgonPrime class or type=Argon Equipment Dock race=Argon flags=null refobj=null serial=null max.jumps=0

This statement says to find a station starting from the sector Argon Prime which is an Argon Equipment Dock, belongs to the Argon race, and is 0 jumps from the sector we specified. In short, the specific Argon Equipment Dock that is in Argon Prime. You can use the find station in galaxy statement to find almost anything - even ones you don't know for sure are there. For example, if you wanted to find any pirate bases that happened to be within 3 sectors of some location.

Now, since the universe is dynamic, there is a possibility that this equipment dock doesn't exist any more. That is, our find station statement may have failed. So, everything we do next needs to occur within a test - this test makes sure that the station we are trying to add our new ware to actually exists:

Code: Select all

if $EquipmentDock -> exists

Now, let's say that Egosoft loves your new ware so much that they want to add it to a game patch. If the ware we want to add already exists in the station, we don't want to add it again. Or, if for any reason this script is run a second time, good coding practices call for making sure that the ware we want to add to the station isn't already there:

Code: Select all

if not $EquipmentDock -> trades with ware Hire gunnery crews

Now that we've made sure we are only going to add the ware under the right conditions, we go ahead and do it:

Code: Select all

$EquipmentDock -> add product to factory or dock: Hire gunnery crews
$discard = $EquipmentDock -> add 1 units of Hire gunnery crews

Here we tell the equipment dock to add our new ware type to the list of ware types it trades in. Since we want people to actually be able to buy one, we also can't forget to actually add one unit of this ware to the station's inventory.

The "$discard" variable is simply because we're not really interested in the result of that statement. Most scripting statements that people might want to ignore the result of have an option to "ignore return value". This particular one doesn't, so we just assign it to a variable we don't care about.

And, after we close off our if statements, we're done. Just need a couple of...

Code: Select all

end
end

...ends.

Review

To add a new command extension ware, we:

1. Create the scripting command we want to attach to the ware
2. Select the pre-defined "blank" command extension ware type we will use to turn into our new ware.
3. Add the name and description of our ware to an XML language file.
4. Write init scripts that initialise our scripting command, and that correctly adds the new ware to the universe.

Appendix

If you wish to view the actual ware type definition files, you will need to use X2Modder. Run the program, click Unpack Dat, and use the file requester dialog to navigate to the file <X²>\02.cat (where <X²> is, of course, the directory you installed X² into).

[ external image ]
Even a Microsoft technical support
engineer could use this utility.

When the container is unpacked, you will have a new folder, "02", that contains everything that the container has inside. The ware type files will be located in the 02\types directory. When they are first unpacked from the container, they will still be in compressed form and have the extension ".pck". To decompress one, click Decompress PCK on X2Modder and navigate to the ware type file you wish to decompress. The file we were interested in for this tutorial was TWareT.pck which decompresses into TWareT.txt. This contains all the "technological" wares. Other files contain all the other wares and equipment types.

One small note, the file MRUValues.pck which is a file included in the 02\types folder (from the 02.CAT/02.DAT container file) is an empty .pck file. Since it's not actualy a valid .pck file, the X2Modder program can't decompress it and the program reports an error. The author is aware of this issue, and will more than likely make code to handle these empty .pck files in a future version.

[Reven]

Anyone who has downloaded the companion scripts prior to this message being posted in the thread should download them again. I had the final versions sitting on my desktop and didn't upload them to the FTP site until just now - sorry.

[Accushot]

Brilliant! I almost understand it now...keep up the good work.

[simduck]

Is it possible to have a special place for scripting tutorials & hints only? (sorry just found it)

There is heaps on information on how to script & I find it difficult to find it all. The 2 from Reven are fantastic.

By any chance, is there or does any one have an explianation of what each command in the script editor does (commands when actually scripting)?

Thanks

[giskard]

Just a note or two in regard to the tutorial.

After following the instructions above, my own NEW ship upgrade worked a treat with the following exceptions.

The game appears to load TwaresT.txt at start up so after youve added a new entry you have to quit the game and restart.

Unless you have your script in an ini file thats already been run and saved off in a game save or when a new game has been started. You may have to run the script that sets up your ware again before it appears on the ware list under the name you have chosen for it. Id guess the same problem happens with other T type files.

No major issue here, just a few odd things that others may run into.

Giskard

[Metuelisator]

Moin,

Good work on the tut, it helped me alot on my pirate station ware.
2 suggestions you might add:

1. Everyone should check in the init script, if the main script is already running, even if it is no loop. A.E. in my pirate station info the init checks if its not already there as ware ond only if not start-> mainscript.

2. Since X2 V1.3, we do not need the waitforGalaxy 1ms, just rename your init script to setup. A setup.makewhatever.xml waits automatically for the galaxy to be created, and then starts.


so denn

[giskard]

Moin,

Good work on the tut, it helped me alot on my pirate station ware.
2 suggestions you might add:

1. Everyone should check in the init script, if the main script is already running, even if it is no loop. A.E. in my pirate station info the init checks if its not already there as ware ond only if not start-> mainscript.

2. Since X2 V1.3, we do not need the waitforGalaxy 1ms, just rename your init script to setup. A setup.makewhatever.xml waits automatically for the galaxy to be created, and then starts.


so denn

Great, thanks for the tip, i was wondering about that and have actually used a setup file my self anyway and i put the delay in that. Guess i dont need it.

Giskard

[Metuelisator]

aye i did it the same way. Then burnit dropped that info in a topic on the german script forum, but its very hidden ;)

[Shanjaq]

Great tutorial, but there's one thing I must know: How do I change the ware ID in the scripts? What if your ware ID conflicts with wares from another mod? I've looked into the scripts and found nothing even remotely like what's listed in TWareT.txt!

[Hiroshima]

This deserves a sticky

[JustHere4Coffee]

it's already got one - it's listed in the sticky "tutorials" thread

[Xenon_Slayer]

Are the next parts coming out soon?

[CBJ]

Reven's not been posting since February, so I doubt it.

[Reven]

The third one was mostly done ages ago, I just had an attack of real life that hit hard and lasted longer than I had anticipated. I apologize to the community - but I'm back now, so expect to see the third installment soonest. I'm not sure that the rest of them are necesary any more, so we'll see about those.

Again, sorry for having dropped off the map.

[CBJ]

Well, I'm glad to be proven wrong. Welcome back Reven.

[gillrichard]

Reven's not been posting since February, so I doubt it.

lol aint that a kick in the heeaaaad.