X3 is a great game, but my biggest annoyance with it, is that all the decisions have been made for you to an over-the-top degree, and all you are left with, decision wise, is a choice of which is worse.

Modding changes all this.

It allows you to tweak the specification files in many many ways, that allow you to play the game the way you really want to, without the restrictions of someone who obviously does not think the way you do. Lets face it, if you read the forum threads, there are many distinct playing styles and a lot of argument over what should and should not be done.

For me, in the forums, the most disliked phrase is "then it wont be balanced". By who's definition of balance ? Everyone has a different definition of what balance should be. And no matter how you define it, it still means that the game blocks the ability to be who and what you want. Which for me is unbalance. The whole purpose of playing the game is fun and where is the fun of being told you cant do something because its not balanced ? Lets not go there, thats an argument for other places.

I am a firm believer in player choice, and X3 really does not give you any. At least, not enough for me.

If I want to be virtually invincible and take on the whole universe and win, I should be able to.

If I want to play a trader game without the need to have large fleets of defensive ships and Lasertowers, I should be able to.

If I want to be the worst Pirate ever, I should be able to.

If I want to make the game almost impossible to survive in, I should be able to.

I can.

Modding and the scripting that then uses those mods, is how you do all this.

Threads in the forum are often asking advise on problems encountered with doing mods.

So this is an explanation of the modding files to get you started with some understanding of what you are doing. It is by no means a complete guide. By the time you get to wanting to put new images in the game, of the ships and stations you design, you will be way beyond the scope of what is written here. For the moment, we will limit ourselves to looking at the basic building blocks of the game.

First off, you need doubleshadow's X3 Editor and Modmanager.
http://forum2.egosoft.com/viewtopic.php?t=103977
http://forum2.egosoft.com/viewtopic.php?t=108888

[Edit - For X3TC, there are new versions, make sure you get the right version for the right game.]

The game files come in .cat files (catalogs), and so you need the Modmanager to manage the mod catalogs themselves, and the Editor to change the mod files within the catalog.

Both take a bit of working out how to use, but working that out is half the fun of modding.

There are 2 type of catalogs in the X3 game. The ones that reside in the game root directory, and the ones that reside in the \mods directory.

As of X3 2.5, the X3 directory contains 01, 02, 03, 04, 05, 06, where 06 was the changes made by the 1.4 patch, 07, 08 and 09.

Each of these catalogs contains a different set of files, although when you look at them, they appear to be the same files.

The game was built to allow changes easily.

01.cat contains the object (model) files for stations only. 02.cat contains the dds textures only. 03.cat contains additional objects, mostly the ones from cutscenes, in addition it contains more textures. 04.cat contains the objects files for ships, a few more textures, and the rest of the base game files, including the original T files. 05.cat is the files patching the base V1.0 game upto V1.3. And lastly, 06.cat contains the changes between V1.3 and V1.4.

Note: "Not all files were changed between V1.0 and V1.3, nor between V1.3 and V1.4, so some files the game uses might not be in 06.cat that you may want to change." (Quote from Armageddon, with thanks). V2.5 note : The same applies in the later patches.

Files named 07.cat and 08.cat are the v2 patches and 09.cat is the V2.5 patch. Most of the tfiles we will deal with here are now stored in 08.cat.

The changes are applied dynamically as the game loads, with each higher numbered catalog adding to the previous one, and in fact where the same file is found, overwriting the previous ones. So only the latest file from any catalog is used by the game.

After these are used, the game looks for any selected mod file in the \mods directory and again adds or overwrites to create the game specifications that are used as you play.

So what that means is, if you use a mod in \mods, it dynamically changes the game from the default game. And thats what we use to make the changes we want.

If you look in one of the downloadable mods catalog, you will find only the actual files that are added or changed, not a complete set.

There is an extra trick as well. If you place a mod in the X3 directory, and name it the next available number (10 for example), then this mod will be applied as if it was a game patch. However, if a another game patch comes out, it will be overwritten and lost, so if you do this be careful of installing game patches after modding this way.

The use for this is to enable a very large mod to be applied to the game as if it was a patch, and still allow you to do minor mods that work with it.

However, combining mods is not an easy task as the mechanism was not designed to do this easily.

So, lets look at the specification files needed for basic modding, along the lines of changing the specs of your favourite ship.

Within each catalog, are directories that contain different parts of the game's description of every object and every aspect of the game.

The one we will be most concerned with is the \types directory.

This directory contains the main object files, as least as far as simple changes are concerned.

tships
This file contains the definitions of every ship in the game. Plus a few that are not. It allows you to change things like speed, rudder, accelleration, turrents, main guns, missiles fireable, cargo, shields, price at the shipyard etc. etc. This is the file most people will modify first.

tfactories
This file contains all the definitions for the factories and stations in the game.

tdocks
This file contains the docks in the game and is the one file you cannot do much with. The Trading docks and EQ docks do not want to be changed, so until you know what your doing, leave this file alone.

tcockpits
This file is where the turrents are specified, each turrent being defined by a cockpit design, so that you can jump into one during the game.

tlaser
This file is where all the guns in the game are specified.

tbullets
This file is where all the "bullets" are specified. Each gun fires something, and these are grouped and referred to as a bullet, even through the only true bullet in the game is from the Mass Driver. The coloured blob you see after you pull the trigger, is called a bullet. Range, speed, damage to hull and shields, what they look like. etc.

tshields
This file is where the shields are defined.

tmissiles
This file is where all the missiles are specified. Speed, sheild and hull damage etc.

There is also a series of files containing all the wares used in the game.

There is one other file that should be mentioned.

t\44001 is the language file. It contains all the descriptions and words used in the game, including ship names. This file is accessed through the Text Reference Editor, a utility program you get with the Editor/Modmanager downloads. DO NOT CHANGE THIS FILE.

From a modding perspective, 44001 contains all object names and descriptions including ships, Specific ID ranges for specific things, command slots in each game menu, etc.

The approved range of file names to use is 447000 to 448999. The list is already long for using these, and not contiguous, so make sure you consult the list and choose one thats available.

The compatibility list is at http://forum2.egosoft.com/viewtopic.php?t=96340, post 2 on page 1.

Edit : For TC, the compatibility list is at http://forum.egosoft.com/viewtopic.php?t=216690

In the Text Resource Editor, click new file. A blank file screen appears. Right click on the left column and click add, then add in the page title entry you need, from the 440001 file. In the right column, add in the ID entries you want to add. Click save, and save it into the catalog for your mod, with t\ on the front of the file name. In a setup.scriptname script, you need a "loadtext" command using the last 4 digits of the file name you use.

Its up to you to ensure that if you are building a mod for public distribution, you are using ID's that in the approved ranges of ID's and are available. Once the mod is complete, you should register the mod for inclusion in the lists by posting in the thread the details of the mod in the approved fashion as laid out in the OP.

I cannot over-emphasise that messing with these files and getting it wrong, can destroy your game files to the point where the game will not start or save games will crash.

Another thing to bear in mind is that anything you change in these files is universe wide. If you change an exisiting object in any way, all the objects in the game are changed the same way. For example, I added GPPC's to all the Argon ships, because I wanted ships in my fleet that could defend themselves against anything. Or so I thought. It came as quite a shock to find that all the Pirate Nova's and Busters had PPC's as well, and in a firefight in Argon space, PPC bullets were so thick it was a very dangerous place to be. So just because you can do something, does not mean you can ignore thinking about the consequences of doing it.

Before you mod, backup the entire game and your savefiles.

So, we want to add a new ship.

Easy. We just go into tships and add one ? Wrong !

We know about the files, but we do not yet know the relationship between the files.

Bullets come from guns, which are fitted to turrents and main gun slots, which are fitted to ships.
Shields and missiles are fitted to ships.
Language file gives a ship a name, without which it cannot be placed in the game. Ship names come from this file.

So we want to build a new ship from the ground up. Especially if your doing the whole thing and designing guns and turrents for it.

Add a ship name. (44xxxx)
Add a bullet. (tbullets)
Add the bullet to a gun. (tlasers)
Add the gun to a turrent. (tcockpits)
Add the turrent to a ship. (tships)
Add the gun to the front guns of a ship. (tships)
Add shields to the ship. (tships)
Add missiles to the ship. (tships)
Custom change other ship details. (tships)

If you are just changing the specs of an existing ship, its still the same relationships, except they already exist. But to change some things for the ship, you have to change one of the other files before the ship will show the changes.

Easy ! Wrong. One wrong move and the mod crashes.

So I open the editor and modify the files in the 09 catalog in \x3 ? NO !!! If you mod the main game itself, you risk permanent and irrepairable damage, from which you can only reinstall the game to recover.

The easiest way to create a mod file, is copy the 08.cat and 08.dat files to the \mod directory and rename them to something like mymod.cat and mymod.dat. However, this copies everything, and its a large file. If you later decide to share the mod with others, the file is too big for efficient downloading. But for your first mod, just for your game, its fine.

The hard way to create a new mod file is to create a new directory somewhere, and use the Modmanager to extract all the 08.cat files into. You then create a new mod catalog in X3\mods and add the selected files you actually need. (The latter can be done anywhere but best in \mods where it will end up anyway.). As you add, you need to respecify the correct directory path to place the file into within the mod.

When you have your mod file ready to be worked on, start the game up and select this mod for the game, then start and exit. This links the tcockpits file of the mod dynamically to the tships file within the editor. Its a quirk of the editor and if you fail to do this, you may find that an added cockpit design is not listed when you come to add it to a ship.

Changing existing objects is the easiest modding to do, but as stated, be careful the changes dont come back to bite you in the game.

Add and modify from the components end up.

By the time you start on a ship design, everything else you need has already been added or changed.

Oh, new anything, always add it to the end of the file. There is a lot of hardcoding in the program that expects certain objects, especially ships, to be in certain places in the file, and if you move this, the results can be chaotic.

I'm not going to dwell on the editor itself, except to say that looking at what is already there gives clues to how things fit together. Some things are just a click to change, other things need other values changed in order to change. eg. speed is a function of the number of speed upgrades you allow. Some things are type in a value, others are select from a list.

The language file has a sub-section numbered 17, into which are all the ship names and descriptions. What is in here, is what naming and description you see in tships. So this is why you start here with designing a new ship. But where you put the ship name and description is something you need to research first.

A little extra about merging mods.

One thing that was not designed into the game was the ability to merge mods that use the same files, and put new objects in the same place within those files.

While you can place one mod as a numbered patch file, there is still a good chance that even though no conflict arises with a mod in \mods, the program start will not. And the only thing you can do at this point is choose which mod to use or merge them.

To merge them, create an extract directory for each mod. Create an extract directory for game patch 08. Use the Modmanager to extract each mod and the 08 patch to their respective directories.

Look at each mod in detail and determine what is unique to each, then add these to a new mod catalog.

Identify the mod files with conflicts. You can choose which file to use as a base to add the other mod to. It depends on what has been done to it. If its a major mod that does major changes to most objects, then use that. Otherwise, I seriously suggest you add the 08 file first and then manually add each mods additions/changes into the original game file by copying from the original mod file and pasting in to the new mod file. If its an existing object, delete the old reference then copy in to the same spot in the file. if a new one, add to the bottom of the file. If both mods make different changes to the same object, then you will have to start with one of the versions and manual add the other changes.

Doublecheck that all references to another file are catered for, correctly and fully. This is especially true in 440001 where you need to ensure that each new object has not been using the same reference numbers. If necessary, you need to change them so they will not conflict with 440001 or with any other 44xxxx file.

At the end of the process, when you start the game using the new mod, the game should start without fault and save games should also load without crashing. There are instances where save games will not work, but you should know and expect this if its going to happen, designing the mod only for use with a new game.

If you are designing a mod for others to use, crashing is not a good thing. Figure out why before giving it to others.

If you have trouble, go looking in the forum for someone having already asked the question. If you cannot find an answer, then ask. Someone is usually good enough to get back to you reasonably quickly, but be patient, as some questions have very few people available to answer them and how quick they do depends on how much time they give to reading the forum and answering questions.

This is just the basics. Just a place to start from.

Happy modding.

X3TC Update :

Theres a few changes in the way TC handles its files.

The major one is the language file.

44XXXX has changed to XXXX-LYYY, where XXXX is your unique number, and YYY is the language. So in my case 448686 has become 8686-L044, being an english file.

The first thing you need to do to upgrade an X3(R) mod to X3TC is to rename this file.

The other interesting thing is that the Command Menus can now have submenus, so if your adding a lot of commands in your mod, you can now have your own submenu. There is a guide specifically about how to do this in the X3TC scripts and modding guides list.

Other than that, not much has changed.

All the tfiles have a lot more in them now. So if your converting a mod, you need to edit off your entries in each old file, and add them to the bottom of the new files. (Same as a patch update.)

tlasers and tbullets have now got more entries than the previous limitations allowed, but the limits havent been extended, just worked around by means of the Galaxy Subtype field. This still means adding a gun or bullet is very difficult to do (and I have not been able to).

However, there are 2 Dummy guns and 2 dummy bullets, which are unused in the game, so these can be used for new guns and bullets. Just overwrite them with the values you want, including your descriptions in the language file.

There are 3 fields in tlasers to especially look for.

Galaxy Subtype, if wrong, will prevent the gun from showing up in the game. I recommend you leave it alone.

Projectile points to the tbullet file, so make sure you have the gun pointed to the right tbullet entry. This is selected from a list, so make sure you get the bullet in first, start and exit game, then attach the bullet to the gun.

The HUD Icon field displays what you see on the HUD and the gun selection screens.

The guns behaviour in the game is determined by the Projectile you select, so if you get it wrong, the gun will not behave as you expect.

The 8 gun limit on the front of a ship seems to have been increased to 10, as there is a ship now with 10 front cockpit guns. But as always, you can only add extra guns if the model has them.

The contents of the .cat files is much the same, although some differences. The first thing to do before modding is still to create a directory for each cat, and extract all the files using the Modmanager. There have been patches already, so you need to check each .cat from highest number down to find the latest tfile to work with.