[Guide] Recoloring Game Assets

[Sie_Sayoka]

This is a beginner's guide on how to recolor game assets from the very start of the process to uploading the mod on the Steam workshop. This is mostly a compilation of knowledge on the forum already curated for the current game update at the time of this post. Know that there probably are more efficient ways of doing things as I am still a beginner myself. Hopefully this will be useful for people making their first X4 mod.

Required Tools:

• X Catalog Tool Extracts/compiles game data. Also allows uploading to Steam workshop.
• XR Converters Exports/imports these files into .dae files.
• Blender Used to edit .dae files. I use v4.4.
• Notepad++ Used to edit .bat and .xml files.

For this guide I'll be going step-by-step and make it as simple as possible. I'll also try and explain what each step does and its importance. In this example the color of liquid storage modules will be changed.

• 1. Install X Catalog Tools
  Getting Started: Tools, Scripting and Modding
  
  You can either download and install X Catalog Tool from the link above or if you use the Steam version of the game, go to your Steam library and search for 'X Tools'.
• 2. Prepare Workspace
  
  You'll need a folder for your the extracted and modded files. It doesn't matter where this folder is... probably. I put mine in the root of my game drive. In this folder you need another folder where your extracted files will go, I named mine "unpacked".
• 3. Extract .dat files
  Use the Catalog Tool and press the 'Import catalogs...' button. Search for your 'X4 Foundations' folder, usually "...\Steam\steamapps\common\X4 Foundations" but it depends on where you installed the game. Select 01.cat to 09.cat (not 0x_sig.cat) and open it. This will start reading the .dat files which may take a few minutes, the app will be unresponsive but just leave it be for a while. Strictly speaking we only need to extract with 01.cat for this guide as this contains all the assets but extracting the other 8 files would be good in the future for modding other things.
  
  
  Once it finishes your window should look something like this with thousands of files.
  
  
  Press the 'Extract' button and select the folder where your files will go. After you've moved the files to this folder it should look something like the above picture.
• 4. XR Converters
  Download XR Converters and put it in your mod folder. It reads .xml files which is a list of other files that an asset is composed of then converts the game model files (.xmf) into .dae files which we can edit through Blender. This program is run through the command prompt which many people have found challenging, including myself. To make things easier we can make .bat files.
  
  • 4a. Importxmf
    Convert Xml to dae Collada File
    For an example I'll edit hab_par_l_01 otherwise known as the Paranid L Dome. Create a Text Document in the mod folder. In the text file I'll add the following:

    Code: Select all

    XRConvertersMain.exe importxmf "A:\XRConverters\unpacked" "A:\XRConverters\unpacked\assets\structures\habitat\hab_par_l_01.xml"
    pause

    The pause line isn't required but it is useful to display any errors that may happen during the conversion process. Without this line the window will close itself after it's done.
    Save the text document and rename it to something descriptive such as hab_par_l_01 unpack.bat. This will change the file from .txt to .bat and allow us to double click on it for XRConvertersMain.exe to do its thing other than us having to use the command prompt.
    
    If everything was done correctly a .dae file should be created in the same location as where the target .xml file is. In this case it will be the habitat folder.
  • 4b. Troubleshooting
    
    If it says that the application has stopped working then it means that you mistyped something in your .bat file. Double check everything.
• 5. Blendering
  
  Download and install Blender, it's free! Note that there are some issues using .dae files on versions 2.7+? of blender as this is a rather archaic file type. Don't worry there are ways to fix this which will be covered later. Open blender and drag-drop the .dae file into it, opening the file directly with blender doesn't work for reasons. After doing this you should see the model in blender. It will look weird at first because all model files are visible at the same time.
  
  • 5a. Blender Workspace
    
    To make viewing easier for recoloring change the Viewport Shading options to this, it's located at the top right.
    
    At the very top right is the Scene Collection. This is all of the objects that the asset contains, an equivalent would be layers in a painting program. The model will show other things such as collision and lod variants in it so it's best to hide every object that you aren't working on. To hide/show all of the specific child objects, hold shift and left click on the eye icon.
    
    At the top left is the modes. Clicking on an object will bring up additional modes as shown in the pic. We will be using Object, Edit, and Vertex Paint modes.
    Select and delete the camera and light objects since you don't want those. You may skip this part by changing the default workspace by going to File>Defaults>Save Startup File.
  • 5b. Changing Color
    
    First we need to find the object that we want to edit. In this case I want to change the color of the purple vertices. In object mode I'll click on the purple object which will become outlined and show the name of this object in the Scene Collection.
    
    
    I'll hide all the other objects and go to Edit Mode. Then press A to select all of the vertices. This is a fairly easy object to paint but on many other models the objects aren't separated by color and you'll need to select vertices individually.
    
    
    I'll then go to Vertex Paint mode and click the Vertex Selection box next to it. This will allow me to paint anything that I've selected in Edit Mode.
    
    
    To the right is the Tool tab where I can select the color in which to paint. To fill the entire selection I just need to press Ctrl+X.
    
    
    The color has successfully been changed but It's not done yet. I need to repeat this process for all of the LOD (level of detail) objects so that it will be changed for all distances. For lod1/2 I can skip the Edit Mode part as the purple areas are all contained in an object.
    
    
    However, on lod3 I'll need to select the purple vertices as the object contains purple and other colors. To select multiple vertices on the same face you can hover the cursor over a vertex and press the L key. There are other selection tools to help such as Cursor Selection (C) or X-Ray (Alt+Z).
  • 5c. Saving
    
    Once everything has been recolored I'll save it using the same file name as the .dae file we used. You don't need to save as a .blend file but it's nice to have backups and if it needs to be changed in the future it will make things easier. It's best to make a new folder where you put all your blender files for organization.
    
    
    I'll also export a .dae file. You can uncheck the copy box since all this does is make copies of texture files in your folder which need to be deleted later but it doesn't really matter.
  • 5d. Blender 2.7+ Step
    Solving problem with expected attribute "texcoord" at element "texture"

    Code: Select all

    Schema validation (Error): Error: ERROR_REQUIRED_ATTRIBUTE_MISSING Element: texture, Attribute: texcoord, Line: 32, Column: 67, Additional:

    As mentioned before, we may need to do a fix because higher versions of Blender don't correctly export UV textures in .dae files. Please read the link above. If we try to import the .dae file we just made into blender again it will bring up the above error.
    
    
    Open the .dae file with Notepad++ and add a texcoord for the specified line. I'm not sure if the attribute matters as I couldn't find anything texcoord related to ads_billboard_03_diff_dds-sampler in the original .xml file, the texcoord must be filled though. Nothing bad should happen... probably.
    
    On most assets I've worked on there's only one error but on some there may be multiple.
• 6. Export xmf

  Code: Select all

  XRConvertersMain.exe exportxmf "A:\XRConverters\unpacked" "A:\XRConverters\unpacked\assets\structures\habitat\hab_par_l_01.dae"
  pause

  Now that everything is set we can export the .dae file back into .xmf files. Move or make a copy and replace the original .dae file in the same folder as the .xml file. Then make a new .bat file for exporting. We can name this hab_par_l_01 repack.bat or something descriptive.
  
  
  Everything worked! No errors. The mod is almost ready to be used.
  
  • 6a. Troubleshooting

    Code: Select all

    Node x has multiple meshes attached

    
    To fix this issue open the blender file and select the named node/object. Press A in edit mode to select everything then Delete Loose.
  • 6b. Reverting Changes
    The process of exportxmf will overwrite the files within the unpacked folder. If you've made a mistake and would like to get the original xmf files back repeat step 3 but only select all of the associated files for that specific asset from 01.cat.
• 7. Creating a Mod Extension Folder
  Getting Started: Tools, Scripting and Modding
  Before we can pack everything up we must make a folder within ..\steamapps\common\X4 Foundations\extensions so that the mod has someplace to live and the game will recognize it. In the folder create a text document with the appropriate text as detailed in the above post and rename it to content.xml.
• 8. Importing Mod Files
  Futher Reading
  
  Open the Catalog Tool and set the Root folder for input files to where you extracted the game data. Then click the Import files... button. Since the only objects that I changed were the part_main-lod0 to 3 .xmf files I'll only need to import these.
  
  
  Click the Save as catalog... and save it as subst_01 since this will be replacing certain files. This should be saved in your mod extensions folder. Afterwards you should see subst_01.cat and subst_01.dat files in this folder. It is now ready to be played.
  
  
  Open up the game and check to see your changes. If everything went well it should show up. Good job. Well done.
  
  • 8a. Troubleshooting
    
    If the changes you made do not show up in game the cause could be from any number of reasons. The most likely is that somewhere along the line an incorrect file was added to the .cat. Double check the timestamps in the Catalog Tool as well as the names to ensure that the correct files were indeed added.
• 9. Uploading to Steam Workshop
  Steam Workshop for X Rebirth and X4
  Once your mod is complete it can be uploaded to the Steam Workshop. A thumbnail picture is needed first. I named mine preview.png.
  
  

  Code: Select all

  WorkshopTool publishx4 -path "A:\SteamLibrary\steamapps\common\X4 Foundations\extensions\darkerparanidstations" -preview "A:\SteamLibrary\steamapps\common\X4 Foundations\extensions\darkerparanidstations\preview.png"

  Run X Tools but this time choose the Play X Tools option. This will bring up a command prompt. Because I already have .cat/.dat files in the folder I only need to specify that I want to publish the mod and upload a thumbnail. I'll paste the above code into X Tools.
  
  
  Once you confirm that you'd like to publish the mod it should show up on the workshop. By default it's hidden.
  
  The methods in this guide will work for most things but for some instances I've had issues. Namely surfaces covered by textures like the liquid storage tanks in modules. I'm fairly certain that Blender isn't able to fully read some files and as mentioned before has some problems converting them.