Basic Modding Tutorial

Here is a basic modding tutorial for folks who want to get started modding characters in Trails of Cold Steel 3, 4 and 5 (Reverie). (There is also experimental support for CS2.) While I have written the toolset to accommodate very complex modding, understanding what is going on under the hood is not necessary for most simple mods. Here we will do a basic mesh delete, mesh modification (partial delete in this case) and texture replacement. This tutorial does not have any major spoilers, and is basically safe for someone who has played at least part of Cold Steel III (honestly safe for anyone at all, even if you have only played part of CS1).

Note that this is not a tutorial on how to use tools like Blender or Paint.NET. I will not be teaching basic universal skills - please refer to other tutorials such as those on YouTube etc. I particularly recommend watching "3DMigoto Costume Mod Tutorial for Fairy Tail (PC)" by Ikaros; while it was made for 3DMigoto, I learned 90% of what I know from that video alone. I will put some basic steps so that you can still follow along, even if you have no Blender skills, but this tutorial will be much easier with some basic skills.

Basic Setup

1. Install Python 3, if you don't have it already. (Microsoft store, I'm using python 3.9 but any version newer should work.)
2. Install Blender (free!) in Steam. Optional: change to 4.2 LTS (right click Blender in steam, select Properties -> Betas -> 4.2 stable LTS).
3. Download DarkStarSword's plugin here (Right Click, Save As)
4. Install the plugin (Blender -> Edit menu at top -> Preferences -> Add-ons -> Install, click the link for video.)
5. Download the ED8 Model Toolset
6. Run the included "install_python_modules.bat" batch file, which will install all necessary python libraries to use the toolset.
7. Download a copy of the compiler from the Trails Research Group. Hereafter this will be referred to as WorkFolder.zip. (Note: There is a separate compiler for CS2, currently only available on the Kiseki Modding Discord. If it is added to github, I will update the links.)
8. Install the Windows SDK.
9. Obtain a copy of the tbled editor by Lukas Himbert, which we will use to read the t_name table.

Obtaining and decompiling a model

First, let's get ourselves a model! I want to mod Emma's default CS4/Reverie costume today, which looks just like her default CS3 costume except without the hat.

1. Open tbled, and select your game (Schema Menu -> Use builtin schemas for ______). Open {Cold Steel Game Folder}/data/text/dat_en/t_name.tbl. Find your model. Here I can see I want "Emma: Hair Accessory" which is C_CHR005_C10.pkg. (How do I know I do not want "Emma: No Hat" instead? Experimenting.) WARNING: t_name.tbl has major spoilers for each game - do not carelessly browse this file if you care about spoilers!

2. (For NISA releases) From the ED8 Model Toolset, grab extract_pka.py and put it in {Cold Steel Game Folder}/data/asset/D3D11, and double-click it. Press enter when it asks you for the pka and it will default to assets.pka. Type in C_CHR005_C10.pkg to get Emma: Hair Accessory.

3. Copy your extracted model to a folder, with ed8pkg2gltf.py and lib_fmtibvb.py. Double click ed8pkg2gltf.py and it will decompile your model. When it is done, you will have a new folder, C_CHR005_C10 with the decompiled model, which I will refer to as the work folder.

NOTE: Instead I actually recommend running ed8pkg2gltf.py from the command line. Press Win-R, type "cmd" and change directories to your work folder, then type: python ed8pkg2gltf.py Python will not report any errors if the script crashes when you double-click the script, and no one will be able to help you. Run from the command line for helpful error messages.

4. You can safely delete chr005_c10.bin and chr005_c10.gltf (unless you have other reasons to use them). We will not be using the glTF model in this tutorial.

Inside the work folder, you will see 1. assetconv_temp, which has textures, 2. C_CHR005_C10, which has the asset xml and true shaders, 3. meshes, which has the meshes and metadata.json, which has the skeleton and materials and all other metadata required to compile the model files into a working PKG.

Re-compiling the model

Before doing any mods, I am actually going to go through re-compiling the model. This is a good exercise to make sure you know how to get a working PKG file from your decompiled model. In addition, all subsequent mods below will refer back to this step.

1. From the modding toolset, copy build_collada.py, lib_fmtibvb.py, replace_shader_references.py and write_pkg.py into the work folder. From WorkFolder.zip, copy CSIVAssetImportTool.exe, all the Phyre_____ files (PhyreAssetDatabase.dll, PhyreAssetDatabaseD3D11.db, PhyreAssetDatabaseUnmanaged.dll, PhyreAssetProcessorDO.dll, PhyreAssetScript.lua, PhyreAssetServices.dll, PhyreAssetSpec.xml, PhyreDummyShaderCreator.exe), SQLite.Interop.dll and System.Data.SQLite.dll into the work folder. You do not need the shader folder or Process.bat. Your folder should now look like this:

For CS2: Instead copy build_collada.py, build_collada_cs2.py, lib_fmtibvb.py, replace_shader_references.py and write_pkg.py into the work folder. You will need PhyreDummyShaderCreator.exe from WorkFolder.zip in the work folder, and all the files of the CS2 asset processor including the contents of CS2AssetProcessor.zip, PhyreAssetScript.lua and PhyreAssetSpec.xml.

2. Build the COLLADA model by double clicking build_collada.py. (For CS2, double click build_collada_cs2.py instead.) NOTE: Again I actually recommend running python build_collada.py from the command line.

3. If the build was successful, there should now be a RunMe.bat in the folder. Double-click RunMe.bat. NOTE: Again I recommend running RunMe from the command line.

4. There should now be a shiny new C_CHR005_C10.pkg file in your folder! Copy that file back to {Cold Steel Game Folder}/data/asset/D3D11 and load up your game to see your model. NOTE, for NISA CS3 the location for mods is {Trails of Cold Steel III}/data/asset/D3D11_us instead.

Basic Mesh Delete

First, we will do a very simple mod - removing an entire submesh. Blender is not involved, but we will use it to preview what will happen.

1. Load Emma's meshes into Blender. (File menu -> Import -> 3DMigoto raw buffers (.vb + .ib)) The meshes are in {Work Folder}/meshes/.

2. Notice that there seems to be two overlapping Emmas. That is because polySurface4962_01.vb is her shadow mesh (the mesh used to render a shadow). Hide (press H) or delete (press X) that mesh from Blender (deleting in Blender will not delete it from the model.)

3. polySurface4962_02.vb is her hair clip, we will delete that. For this mod we do not need Blender at all, except to identify the mesh.

4. Go into {Work Folder}/meshes/ and delete polySurface4962_02.vb. (I recommend backing up your files first.)

5. Compile and test your model. Congratulations on your first mod!

Basic Mesh Modification

This time I want to remove part of Emma's belts. This will not be as easy as removing the hair clip, since the belt is part of the coat.

1. The belt is part of polySurface4962_06.vb. Select polySurface4962_06.vb, go into Edit Mode, select the parts of the belt you want to delete in Blender, and delete. (Again, this is not a Blender tutorial, although the basic steps are below. Please watch the video linked above or reference any Blender tutorial you like.)

Step by step: (Video tutorial here)

A. In the Topbar, go into the Layout workspace (tabs at top -> Layout), if you are not already there. Make sure you are in the 3D Viewport (Shift-F5). In the upper left you can see the current mode, which is likely Object Mode. If you are not in Object Mode, switch into Object Mode (from the drop down, or Ctrl-Tab)

B. In the Outliner, aka the box in the upper right with all the meshes and other objects, hide all the meshes except Emma's dress (polySurface4962_06.vb). Select each one and press H (or click the eye icon on the right). Select polySurface4962_06.vb. Emma's dress should now be selected. Change Object Mode to Edit Mode with the upper left dropdown in the viewport.

C. Three icons will appear directly to the right of Edit Mode, which are Vertex Select, Edge Select and Face Select modes. Switch to Face Select mode.

D. Unselect everything (Select menu -> None, or Alt-A.)

E. With your cursor in the viewport (middle of the screen), hold down mouse wheel click (MWC) and move your mouse to pan and tilt the camera around the model. Hold down Shift-MWC and move your mouse to move shift the camera position (i.e. to strafe across the screen). Use Mouse wheel scroll (MWS) to zoom in and out.

F. Switch to Circle select (Select menu -> Circle Select, or press C). MWS to adjust the size of your "brush" for selecting polygons. Hold down the left mouse button (LMB) to select polygons. Hold down MWC to unselect polygons. Click the right mouse button (RMB) to leave circle select mode. You will need to do this to pan the camera.

G. Repeatedly do this until you have selected the polygons you plan to delete. Press C, MWS to adjust size, LMB to select some polygons, MWC to unselect ones you accidentally set, RMB to go back to camera mode, MWC/Shift-MWC to adjust the camera, press C again to select or unselect some more...

H. When you are done, delete those faces. (Mesh menu -> Delete -> Faces, or RMC in the viewport {when not in circle select} and select "Delete Faces") Want to do something else besides just delete? Try transforming! (Mesh menu -> Transform -> Move / Rotate / Scale, or one of the specialized tools like Push / Pull or Shrink / Fatten.) Just remember to consider how your changes will affect pose / animation.

2. Go back into Object Mode.

3. Export the mesh. File menu -> Export -> 3DMigoto raw buffers (.vb + .ib) Overwrite the original polySurface4962_06.vb. (Again, I recommend backing up your files first.)

4. Compile and test your model. Congratulations on your second mod!

Basic Texture Replacement

This time I will change the color of Emma's coat (which we determined from the last step is polySurface4962_06.vb).

1. Open polySurface4962_06.material in a text editor such as Notepad. We can see that the material is called "new_zubon_collada". (zubon is "pants" in Japanese)

2. Open metadata.json in the work folder. Find "new_zubon_collada". We can see the diffuse (basic coloring) texture is "assetconv_temp/dds_dae/D3D11/chr005_02_conv.dds".

3. Open "assetconv_temp/dds_dae/D3D11/chr005_02_conv.dds" and make your changes. (Again, this is not a Paint.NET tutorial, but the basic steps are below.)

Step by step:

A. Open assetconv_temp\dds_dae\D3D11\chr005_02_conv.dds in Paint.NET.

B. The texture is on a single layer, duplicate that layer (Ctrl-Shift-D). You will now have two identical images on top of each other. Select the upper layer, by clicking on it in the Layers window. If you do not see the Layers window, press F7. If you still cannot see it, press Ctrl-Shift-F7 to reset it to its default position in the lower right. (Video tutorial on using layers here.)

C. Select the purple parts of the image. Press S to go into select mode, and to cycle between the four select modes (Rectangle select, lasso select, ellipse select and magic wand. Select part of the area that you want to start. Hold down the Ctrl key while selecting to add to your current selection, and the Alt key to subtract from your current selection.

D. Edit -> Invert selection (Ctrl-I), so that it is now selecting all the parts you do not want to change. Edit -> Erase selection (Press Del), so that all those parts are gone. Your image will not change, because those parts are still present on the lower layer! (You can see this in the layers window.)

E. Optional: I have more success doing recolor if I remove the existing color first. Adjustments menu -> Black and White (Ctrl-Shift-G). Even more optional but recommended: Duplicate this black and white layer a few times. You can try making a bunch of different colors, and then just drag the layers up and down and you will have variations to enjoy with minimal effort!

F. Switch to the Recolor Tool (Press R). Increase the brush size to something large, like 500. Increase the Tolerance to 100% (since we have already removed the areas we do not want recolored). In the Colors tool, select a new color. Drag-Click on the texture, and color the texture. (Note: Where you start will determine the color shift. So if your cursor is over a light area when you start, the entire recolor will be darker, and vice versa.) (Video tutorial on Recolor - This is worth a watch, it shows how to properly recolor and makes some of my steps above moot. But I like my method.)

Optional: Save as a pdn file before saving as a dds file. When you save as a dds file, it will need to flatten all your layers back into a single layer. If you have a pdn file, all the layers will be preserved, allowing you to keep making changes and variant textures.

Notice that there are some things on this map that I did recolor, that you would think I should not have, such as the leaf. It is because this mesh (chr005_body_setup5_05.vb) does not use that portion of the texture, so I did not bother to fix it. That part of her costume will use the original chr005_02_conv.dds. How can you figure out which parts you need to preserve, and which you can alter with no consequence? Using the UV map. Read this tutorial to see how to obtain the map!

4. Save the file in .dds format as a new file. I called mine EmmaTealCoat.dds, and put it in assetconv_temp/dds_dae/D3D11/ with the other textures. Be sure to save in BC7 UNORM (Linear) format. (Be sure to save as a new file! If you overwrite the original instead, your changes will not show up in game because the game engine will load the texture from assets.pka instead.)

5. Edit metadata.json, updating DiffuseMapSampler to EmmaTealCoat.dds. Save your changes.

6. Compile and test your model. Congratulations on your third mod, you have made it to the end of the basic tutorial!