How to make Custom Paintmods

To make a paintmod at the bare minimum the following will be required:
• A text editor (Notepad++ is great)
• X-Tools CAT/DAT exporter/importer
• A compression tool that can compress files to .gzip

In addition, it is also useful to have the following programs for making and working with pattern files:
• Nvidia texture tools importer/exporter (or a similar program that can convert between .png and
.dds)
• A drawing or graphic design tool to make patterns (GIMP is a great open-source option but of
course there are proprietary options too)

To start off, its best to get the folder hierarchy set up and the *.xml documents in the correct place, all folders and files must match the style of the vanilla hierarchy (this can be checked by unpacking the catalogues of the game into a directory).
Folders required are outlined below:

Within \libraries the following files are required
(This list has been ordered based on the order the files should be changed in to avoid making errors rather than the alphabetical order in which they appear)

Within \paintmods the following files are required

1 icon file for every paintmod, this is a gzipped *.dds file with the .dds file extension removed before compression. The filename must be lowercase and match the paintmod’s wareid. Failing to place an icon file for each paintmod will result in random icons from vanilla gamefiles being used instead.

Within \pattern the pattern files are placed if patterns are being used on paintmods. Much like the icons the files must be a gzipped *.dds file with the .dds file extension removed before compression. The filename must be lowercase but can be pretty much any string with letters and numbers (underscores are probably okay but other special characters should be avoided).

Once all the files have been created in the correct folders it’s time to start setting up the files. All .xml files are formatted to insert extra sections into the identically named vanilla sections. These work by using the diff root tag with the add, replace and remove operators (More on how X4 foundations uses xml here[forum.egosoft.com]). For paintmods only the add operator is required. An example of how a *.xml file can be formatted for x4 is shown below from adding paintmods to the paintmods.xml, all other xmls will have a similar layout.

Note: <paint ... /> is all on one line, steam typesetting makes it run over multiple lines unfortunately.

Now that a paintmods file has been created and set up like the example above its time to look at what attributes there are and what values they can take. Importantly, not all of the attributess are required and omitted attributess will revert to the default, however, for consistency, even if its not required by the game, it is good to make sure they are in the same order as the vanilla files.

While some of these attributes take a floating point number it is often best to restrict it between -1 and 1 for best results

Additionally, if working with patterns, the following is required:
An example of a paintmods.xml file contents without a pattern applied is the following (Note that omitted attributes will be set as the default values):

An example of a paintmods.xml file contents with a pattern applied is the following:

Again <paint ... /> is all meant to be on one line.

The wares.xml is the heart of any mod that adds wares and paintmod mods are no different. The file specifies the name, description, price range and average, volume and transport type. Conveniently, paintmods all follow the same format:

Everything from <container ref="sm_gen_wares_common_01_macro" /> and onward need not be changed.

Note: <ware id ... > is all meant to be on one line but steam typesets this incorrectly

stock.xml specifies where, what amounts and what the likelihood is of being able to buy a given ware from either a regular or pirate station trader. Again, much like wares.xml the format can be followed to the letter.


Additionally, to give paintmods to pirate traders [@id='default_trader'] can be changed to [@id='pirate_trader']. Finally, paintmods can be added to traders of a specific faction by using the faction tag.

icons.xml relates each paintmod ware to the icon that is shown in the redesign menu. It doesn’t require a lot of work as it changes only one line regardless of how many paintmods and respective icons you create.


It’s possible of course to write out the full paths instead of asterisks if the icons are named differently to the paintmods for whatever reason.

Taking a step back from xml its time to look at how patterns work within the context of paintmods. Patterns must be square and preferably 1024x1024 as this is the size used by the default patterns already in game. Patterns can be any combination of colours or monochromatic but it is important to note that multi-coloured paintmods can’t have their colours changed in paintmods.xml where monochromatic paintmods can have their colour changed on a whim and makes created different coloured versions of the same pattern much easier. Transparent regions of patterns become sections where the hull texture is evident, white regions become the colour specified by red=”” green=”” blue=”” and black regions will remain black. When patterns are inverted the white regions become black and the black regions become the colour specified by red=”” green=”” blue=””.

With the pattern file created in an editor of some description it is time to get it into the correct format. If the editor being used doesn't support the *.dds format natively export it as a *.png to minimise loss and preserve transparency. The *.png can then be converted to *.dds with the Nvidia texture tools exporter. Finally, delete the *.dds file extension and compress it to a gzip file in

With all necessary files and folders created and filled to test it in game the X Tools CAT/DAT Importer/exporter (more information here[forum.egosoft.com]) is required to condense all the files into a readable extension. Simply specify the location of yourmodnamehere, choose “import folders” and select both assets and libraries. Then choose export as catalogue and place the catalog into the extensions\yourmodnamehere folder of the game’s root directory. Finally, create a content.xml file in the extensions\yourmodnamehere folder and insert the following information:

An id is not required for the mod to work or for uploading to the steam workshop.

Now the mod should be good to go and already enabled when the game is run. If desired the mod can be uploaded to the steam workshop, to do so follow the process outlined in this guide here