How X3 is loading files

From X-Wiki

This will discuss the system and order in which X3 Reunion is loading its files. Note that this system is the same as used in X2 - The Threat.

File loading order

1. files stored on real file system are scanned
2. files in catalogs are scanned
3. active mod file (if any) is scanned

If X3 finds a file which have already been loaded, it will drop the old file and will remember the newly founded one. That means that new files override the old files.

Because active mod is scanned as last, it has the highest priority and its files take precedence over all other files (this is not entirely truth - see File extension priorities).

How it works

The table shows simplified example when only single file (text resource file) is searched for. The file is first found in the real t directory, then again in catalog and finally in active mod. Note that the virtual file name is still the same.

	Real file name	Virtual file name
1	D:\X3 Reunion\t\440001.xml	t\440001
2	D:\X3 Reunion\04.cat::t\440001.pck	t\440001
3	D:\X3 Reunion\mods\MyMod.cat::t\440001.pck	t\440001

Here X3 will finally associate a virtual file name t\440001 with file D:\X3 Reunion\mods\MyMod.cat::t\440001.pck. This mean that everytime X3 will want to access virtual file t\440001 it will go to D:\X3 Reunion\mods\MyMod.cat::t\440001.pck file.

Real example of the above table can be seen in X3 Editor. In version 0.0.7 select Show loaded files from Settings menu. In older versions open the Settings window and click Show files button.

Now suppose that you want to override the 440001 file in your mod, but you would add it as an xml file instead of pck.

	Real file name	Virtual file name
1	D:\X3 Reunion\04.cat::t\440001.pck	t\440001
2	D:\X3 Reunion\mods\MyMod.cat::t\440001.xml	t\440001	will be ignored

The xml file in MyMod catalog will be ignored although it's loaded as last. It's because extension (type) of file also matters.

File extension priorities

Extensions with higher priority takes precedence in cases where file names are the same.

Priority	Extension	Used for
1.	bob	BOB files
2.	pck	Default extension for packed files. Usually txt and xml files.
3.	pbd	Packed BOD files
4.	pbb	Packed BOB files

The above mean that you cannot override file D:\X3 Reunion\06.cat::objects\ships\boron\boron_M6_scene.pbd with you own scene stored as BOD, because BOD extension has lesser priority than PBD and thus cannot ever override it. You will have to make your scene also PBD (pack it) in order to override the original file.

Note that the table is taken from source codes of X3VFS.dll (a library which is part of X3 Editor) and was deduced empirically.