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.
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 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.
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' :
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
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
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
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
Code: Select all
if not $EquipmentDock -> trades with ware Hire gunnery crews
Code: Select all
$EquipmentDock -> add product to factory or dock: Hire gunnery crews
$discard = $EquipmentDock -> add 1 units of Hire gunnery crews
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
Review
To add a new command extension ware, we:
- Create the scripting command we want to attach to the ware
- Select the pre-defined "blank" command extension ware type we will use to turn into our new ware.
- Add the name and description of our ware to an XML language file.
- 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.