Modding 101, by apricotslice
[Note : X3TC Update at the end.]
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
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
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
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.
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
[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
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
Each of these catalogs contains a different set
of files, although when you look at them, they appear to be the same
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
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
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
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
This directory contains the main object files,
as least as far as simple changes are concerned.
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
This file contains all the definitions for the
factories and stations in the game.
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.
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
This file is where all the guns in the game are
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.
This file is where the shields are defined.
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
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
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
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.
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
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
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,
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
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
If you have trouble, go looking in the forum for
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
X3TC Update :
Theres a few changes in the way
TC handles its files.
The major one is the language
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
Other than that, not much has
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
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.