Basic Modding Tutorial

Here is a basic modding tutorial for folks who want to get started modding characters in Trails through Daybreak (Kuro no Kiseki). While I have written the toolset to accomodate 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 the first 5 minutes of Trails through Daybreak.

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 Kuro MDL Tool.
6. Run the included "install_python_modules.bat" batch file, which will install all necessary python libraries to use the toolset.
7. Download Kuro Tools, which we will use to read the t_name table. (Kuro Tools comes with its own MDL editor! Give it a try, although this tutorial is for my tool.)

Obtaining and decompiling a model

First, let's get ourselves a model! I want to mod Agnès' default costume today.

Copy t_name.tbl into your KuroTools/scripts&tables folder.

For CLE releases:  The tables are kept in {Kuro Game Folder}/f/table/

For NISA release:  The tables are kept in {Kuro Game Folder}/table/ AFTER decompressing script_en.p3a

Type cmd into the address bar and press enter to open the command line.

NISA release: Extract the .tbl files from the script_en.p3a with p3a_tool.exe (comes with NISA Daybreak, Ys X, etc).

p3a_tool.exe extract script_en.p3a

Copy t_name.tbl to your KuroTools installation, to the folder with tbl2json.py.

Run python tbl2json.py t_name.tbl and it will decode the .tbl file into a .json file. Find your model. Here I can see I want "Agnès Claudel" who is chr5001. 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) I do not have the NISA release, so I will do my best here. (I will buy the game when the English language release comes out, and will update these instructions as necessary.) Drag asset_common_model.p3a onto p3a_tool.exe to decompress /asset/common/model/ into your {Kuro Game Folder} folder. The file you want is {Kuro Game Folder}/asset/common/model/chr5001.mdl.

(For CLE releases) The file you want is {Kuro Game Folder}/c/asset/common/model/chr5001.mdl.

For CLE releases:  The models are kept in {Kuro Game Folder}/c/asset/common/model/
                   The model config files are kept in {Kuro Game Folder}/f/asset/common/model_info/

For NISA release:  The models are kept in {Kuro Game Folder}/asset/common/model/ AFTER decompressing asset_common_model.p3a
                   The model config files are kept in {Kuro Game Folder}/asset/common/model_info/ AFTER decompressing asset_common_model_info.p3a

NISA release: Extract the .mdl files from the asset_common_model.p3a with p3a_tool.exe.

p3a_tool.exe extract asset_common_model.p3a

3. Copy chr5001.mdl to a folder, which I will refer to as the work folder, along with kuro_mdl_export_meshes.py, kuro_mdl_import_meshes.py and lib_fmtibvb.py. Double click kuro_mdl_export_meshes.py and it will unpack your model. When it is done, you will have a new folder, chr5001 with the unpacked model inside.

NOTE: Instead I actually recommend running kuro_mdl_export_meshes.py from the command line. Again, type cmd into the address bar of the windows explorer menu, then type:

python kuro_mdl_export_meshes.py chr5001.mdl

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.

Inside the {Work Folder}/chr5001/ folder, you will see 1. all the meshes (.fmt/.ib/.vb/.vgmap files), 2. the materials (materials_info.json), 3. the mesh structure including bone palettes and material assignements (mesh_info.json), 4. the skeleton (skeleton.json) and 5. a list of all the textures used by this .mdl (image_list.json), and 6. a file indicating the repack target version (mdl_version.json).

Textures are not kept in the .mdl file. Edit image_list.json with Notepad or equivalent to see what the texture filenames are.

For CLE releases:  The textures are kept in {Kuro Game Folder}/c/asset/dx11/image/
For NISA release:  The textures are kept in {Kuro Game Folder}/asset/dx11/image/ AFTER decompressing asset_image.p3a

Re-compiling the model

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

1. If you followed the above steps, you will have your original chr5001.mdl file, kuro_mdl_export_meshes.py, kuro_mdl_import_meshes.py, lib_fmtibvb.py and the chr5001 folder which contains your model files.

Note: The MDL importer expects a working .mdl file to already be in the folder. It will use the working .mdl file as a template, and copy over portions of the .mdl file that are not in the meshes / metadata folder.

2. Repack chr5001.mdl by double-clicking kuro_mdl_import_meshes.py. NOTE: Again I actually recommend running python kuro_mdl_import_meshes.py from the command line.

3. If the repack was successful, there should now be a shiny new chr5001.mdl file in your folder! (The original will be backed up as chr5001.mdl.bak.)

(For CLE releases) Copy your modified chr5001.mdl into {Kuro Game Folder}/c/asset/common/model/. Copy modified texture files to {Kuro Game Folder}/c/asset/dx11/image/. Copy modified model config files to {Kuro Game Folder}/f/asset/common/model_info/ (modifying config files is not common). For Kuro 2, you need to compress the files with cle_compress.py first.

(For NISA release) You can make your own .p3a file that overrides the base game files. Create the following file tree:

asset/common/model/
asset/common/model_info/
asset/dx11/image/

Place your custom files into the folders, and p3a_tool.exe in the base folder. Then, from the command line, run

p3a_tool.exe archive 99_all_my_mods.p3a asset\common\model asset\common\model_info asset\dx11\image

and it will create a new archive called 99_all_my_mods.p3a. Put 99_all_my_mods.p3a in {Kuro Game Folder}/Mods/ (The mods are loaded in lexicographical order).

4. Load the game to see the result!

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.

Note: Certain games using the MDL format, such as Ys X: Nordics, will not accept models with deleted meshes. I do not yet have a solution to this.

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

2. Notice that there seems to be two overlapping Agnès. That is because 1_chr5001_shadow_setup_00.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. 2_chr5001_body_setup36_02.vb is the metal details of her coat, we will delete that. For this mod we do not need Blender at all, except to identify the mesh.

4. Go into {Work Folder}/chr5001/ and delete 2_chr5001_body_setup36_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 Agnès' purse, since it looks funny floating there now that I removed all the trimmings from her outfit. This will not be as easy as removing the trimmings, since the purse is part of the same mesh as her legs.

1. The belt is part of 2_chr5001_body_setup36_00.vb. Select 2_chr5001_body_setup36_00.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 Agnès's belt/purse/legs (2_chr5001_body_setup36_00.vb). Select each one and press H (or click the eye icon on the right). Select 2_chr5001_body_setup36_00.vb. Agnès' belt/purse/legs 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 2_chr5001_body_setup36_00.vb. (Again, I recommend backing up your files first.)

Note: If you are using the newer versions of the 3DMigoto plugin, it will output a .vb0 file instead of a .vb file. DO NOT RENAME THIS FILE. The import script knows to look for .vb0 instead of .vb, and will refuse to load the file if it has been renamed back to a .vb file!

4. You will notice that the inner lining of her purse is part of her sweater mesh, 2_chr5001_body_setup36_03.vb. Repeat steps 1-3 for 2_chr5001_body_setup36_03.vb, removing only the purse liner.

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

Basic Texture Replacement

This time I will change the color of Agnès' sweater (which we determined from the last step is 2_chr5001_body_setup36_03.vb).

1. Open mesh_info.json in a text editor such as Notepad. We can see that the material assigned to 2_chr5001_body_setup36_03.vb is called "cloth_bright".

2. Open material_info.json in the work folder. Find "cloth_bright". We can see the diffuse (basic coloring) texture is "chr5001_03.dds". ("texture_slot": 0 is base color.)

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

Step by step:

A. Open chr5001_03.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 pink 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.

4. Save the file in .dds format. Be sure to save in BC7 UNORM (Linear) format.

5. Put your new file into the textures folder. (Remember that CLE Kuro 2 requires asset compression.)

Congratulations on your third mod, you have made it to the end of the basic tutorial!

Optional: Instead of overwriting the original, you can save as a new file, with a new filename. Then update the name in material_info.json, and repack chr5001.mdl. It will look for the new texture file instead. Note that for CLE Kuro 2, the filename length must be identical. You can reassign chr5001_03.dds to chr5001_xx.dds, but not to chr5001_003.dds or the game will crash.