How to: Import custom models to Cold Steel IV
This page is here to guide you in the process of adding custom models to Cold Steel IV. It is currently one of the most complex operations in modding as it involves several steps, and is still at a somewhat early stage. The guide will lead you to insert Van Arkride from Kuro no Kiseki to CSIV, but in a very rough state. He will not be able to fight or doing anything more than running on the field.
The current process includes the following steps in chronological order:
- Obtaining the model to import (Van Arkride) as a FBX file
- Importing it in Maya 2015/2016/2017/2018
- Creating the dummy shaders, then applying them to Van's materials in Maya (including his shadow shader)
- Exporting Van to .dae using the ColladaMaya plugin
- Importing Van in CSIV using CSIVAssetImportTool to obtain a .dae.phyre file
- Updating the shader names in it
- Using Ouroboros' ED84 decompiler, scripting the Idle and Running animations.
Note that this process is extremely tedious and unecessarily convoluted but that's all we have.
The best advice I can give after several issues and wasted time and frustration about file paths, is that you should work in a single folder, for example called "Work Folder", consisting of a "shaders" folder, where you will also put ED9AssetExporter, but also the CSIVAssetImportTool. The pictures in this guide might not reflect that, because while writing this guide I was not fully aware of all the constraints. But at least the text should be up to date.
To extract Van's model from Kuro no Kiseki game files, we will be using KuroTools mdl exe.
First we search for Van's model file which is called chr0000.mdl. We will also grab his run (chr0000_mot_run.mdl) and idle (chr0000_mot_wait.mdl) animations. All the mdls are located in "THE LEGEND OF HEROES KURO NO KISEKI\c\asset\common\model".
Then we will put all the files inside a folder near ED9AssetExporter.exe:
And the folder (called "model", above) content:
All that is left is drag and drop the folder containing van mdl and his animations onto ED9AssetExporter.exe.
The tool outputs a FBX file. However, it does not have any texture. It is because textures are separate from the mdl file,
since they are located in "\THE LEGEND OF HEROES KURO NO KISEKI\c\asset\dx11\image".
To know which texture you need to use, you will have to run the tool and take note of what the tool is outputting on the console;
those are the missing textures:
Get them all from c\asset\dx11\image and place them in the same directory than ED9AssetConverter:
At the time of writing this guide, we didn't find a better tool than Maya 2015 to 2018, as Blender dae export doesn't seem to work well when injected in CSIV (supposedly, the skeleton doesn't seem compatible).
That's why we will be using Maya 2018 from here.
Once Maya is launched, import chr0000.fbx into the scene:
You can ignore the possible warnings that show up. The result should look like this:
When enabling the texture, nothing really shows up. It is because Van's shadow is a mesh itself and is covering him.
You can hide that mesh by selecting the kage one and CTRL + H.
Note: if any texture looks wrong, you might want to convert them to DDS BC1.
Right now, we don't really care, as the only thing we will be doing is applying a shader to each material.(Actually only she shadow, because it is a tedious process).
Something that might get important later, is that some of the Kuro character models have too many bones to import correctly in Cold Steel. There is a hardcoded limit of bones per model that you need to respect, otherwise some bones will be removed without the associated weights being remapped, leading to animation issues. The only solution we found was to manually remove a few "non important" bones, and remap the vertexes they affected to another bone, close to the one being removed.
Shaders are by far the most complex part of the process, so read carefully this section.
I will list what we know about shaders right now and explain briefly the process before getting into details:
- Shader files are the .fx files you can find when unpacking pkg files.
- In their original form, they are source files written in HLSL language. In CS1 .fx.phyre files, you can find the source code in HLSL directly at the bottom of the files. From CS2 they are all compiled into binary form (called direct3D shader bytecode, read http://timjones.io/blog/archive/2015/09/02/parsing-direct3d-shader-bytecode). The DXBC magic word can help identify the bytecode sections in a .fx file. Note that it is possible to decompile them into HLSL again using some tools like this one https://github.com/etnlGD/HLSLDecompiler. Also note that there is a project to reimplement the shader into unity (https://github.com/PMONickpop123/ED8Shader)
- Those files contain a set of shader parameters, switches, and functions. We do not know what the source code of those functions is but we can extract the value of the shader parameters after compilation (The values are present in the .dae.phyre).
- The switches disable or enable certain parts of the source file shader that are then not compiled into bytecode, which means that for a single source shader, it will exist multiple variants depending on which switches were selected. When compiled based on the switches, the binary content is different depending on which switches were selected, and a checksum is calculated based on that binary content, which leads to variants of the ed8_chr.fx file being called "ed8_chr.fx#HEXADECIMALSEQUENCE"; those files came from the same .fx source files but different switches and parameters were selected.
- The switches from our ed8_chr.fx file will be selected through Maya, and written as selected inside the exported .dae.
Finally, note that since we do not want to write any source code in HLSL, our goal is only to use already compiled shader files from the original game, eventually tuning the parameter values (we won't write any function or code in HLSL).
This means our ed8_chr.fx file doesn't contain any code. Even if it the same set of parameters was used than an original Cold Steel shader inside Maya, since our fx file doesn't contain any function, the binary content after compilation will be shorter and different, thus a different checksum will be calculated. That will lead to a different filename for the resulting .fx.phyre file called "ed8_chr.fx#HEXADECIMALSEQUENCE2", which will be etched into the .dae.phyre file; this filename will need to be updated to refer to the original Cold Steel shader file that contain the functions implemented by the CS devs, functions that we want but couldn't write and compile ourselves.
In this guide, I will first explain how to parameterize a shader the whole way in Maya copying the parameter values of the original shader manually, then explain how to use the "presets" (or custom switches) that were added to simplify the process a bit. This is for the sake of understanding what is going on.
The very first step is to select existing shaders from original Cold Steel models. We will select one for the shadow and will only do
one material for this tutorial, because it is a very tedious process. Normally you would do all materials.
The shader used for shadow is "ed8_chr.fx#7D5B6AA14716CB4C48A6EB8A4185E522.phyre", which is available in a lot of characters' PKGs.
(Example here, it is taken from a Rean DLC pkg)\
So first, we need to open the .dae.phyre which is using this shadow shader with the PhyreDummyShaderCreator.
To do that, just drag and drop the .dae.phyre onto the PhyreDummyShaderCreator executable.
It will produce a list of fx files, one for each shader variant used by the .dae.phyre. The one we will open with notepad is the shadow one, #7D5.
It gives us the shader parameter for the shadow. Those are the ones we will copy in Maya for the ed8_chr.fx file applied to the shadow material.
Note that we know #7D5 is used for the shadow because the DummyShaderCreator produces a txt file called materials.txt which links each material to its shader:
"shadow_collada" (the las one) gives you #7D5.
We will also use a default shader in the rest of the process, the default one we will use will be body_skin => ed8_chr.fx#F797E04B6E5A5AC069D06B3241589336, so grab the dummy fx corresponding to that file, we will need it later. Also grab the cgfx version of it. If you didn't unpack the same pkg than me, just grab one of the shaders used for the body in general. We only need something generic that will not mess up the model too much, because we will not be making a shader for each material. Normally you wouldn't need a default shader as you would make a shader for each material of your model, but for this tutorial we just go the easy way, and only make one shader for the shadow, and a default one for the rest of the materials.
We provide a generic ed8_chr.fx dummy shader without any code in it, only parameters. Well, technically the current version has some code in there but we don't care about it, we only need the switches.
The trick is that we will be using existing shaders from Cold Steel that were already compiled by the developers. In Maya, we are just using empty shaders to set the parameters in the output dae.
So in order to do that, move the COLLADA.mll file corresponding to your Maya version to the Maya/bin/plug-ins folder. You also should switch
the rendering engine to DirectX11 (Windows > Preferences):
Then restart Maya.
Once Maya is restarted, you need to open the plugins manager (Windows > Preferences > Plug-in manager), find COLLADA and tick the Loaded box.
Now you will be able to import .fx files and set the parameters for each material. As explained before, for this tutorial we will only do the shadow material.
Before doing anything more, make sure that your ed8_chr.fx file is put inside the shaders folder inside your work folder.
In Hypershade (Windows > Rendering Editors > Hypershade), select the chr_shadow material.
On the right (The attribute editor), instead of "Lambert", select colladadx11Shader1.
And then below, select the provided ed8_chr.fx.
Here is the hard part. Once the fx is selected, a few sections appears.
You will first open the Material Switches one, and proceed to select every switches (every parameter name, if you want) that is present
in the dummy shader file we created for the shadow previously (and opened in notepad).
When you reach the "sampler" part after BloomIntensity, instead of activating all Samplers, just tick the "Activate Samplers" box, which will take care of all of them. Finally, the last one you want to tick is the Texture2D (the last line of the dummy fx file), DiffuseMapSampler.
Once this is done, close this section and open the Material Parameters > Uniform section. You will get something like this:
We will now port all the values obtained from the dummy fx file:
Including the chr_shadow_conv.dds texture that will be used for the Texture2D parameter called DiffuseMapSampler. You will find this texture in any character PKG after conversion from .dds.phyre to .dds. However, you must first put the chr_shadow_conv.dds inside the folder where you store all the other textures; if you follow this guide, that would be ED9AssetConverter. Once you did that, select chr_shadow_conv from that folder.
For the half4 parameters, they use a color + a ".w" component".
You set the color in RGB value which will deal with the first 3 values and you set the .w to the fourth one.
However, usually they all have the same set of values, so the default values should do, and you shouldn't have to fill them.
You should finally obtain something like this:
where file1 is chr_shadow_conv.dds.
OK, that's one material done, now do all the others!...For this tutorial, we will stop here.\
But you get the idea: the same process has to be gone through for all the materials so that each
of them has a different, custom shader.
Now that the shader(s) have been taken care of, we will export the model to dae, which is the format used by the game.
A very important step is to gather all your texture file
To do this, go to File > Export All, create a new folder where we will extract the model, and set the export parameters like this:
The "Files of type" field must be set to COLLADA exporter (not DAE_FBX export)
Also, it is EXTREMELY IMPORTANT for you to export the .dae to the same folder where all your textures were located. If you used ED9AssetConverter to extract the model, then you need to export the dae to the folder containing ED9AssetConverter.exe, where all textures and fbx are located.
This is because the path of each texture in the dae is relative to the export location, but also because of an annoying constraint of the CS4 importer tool that requires all textures to be in the same folder than the model.
When the file has finished exporting, you can open the .dae with notepad and check if all DDS files have their path in the same folder than the dae, like this:
And the same should go for the .fx file:
Now we will use the CSIVAssetImportTool to produce the .dae.phyre and dds.phyre to later be packaged into a pkg. So if you respected my advice back at the beginning, Van's dae and all of his textures should be next to CSIVAssetImportTool.exe.
Remember that we have a shaders folder in it.
This folder is where you will put the default shader dummy fx file and cgfx that we selected (the body one) and the ed8_chr.fx file.
The folder should look like this (after getting rid of ED9AssetConverter, the fbx, and the model folder):
Now, just drag and drop van.dae onto Process.bat.
It will create a D3D11 folder containing the textures as .dds.phyre and the model as .dae.phyre. It also contains a folder called shaders with
5 shaders, one is the shadow one and the other fours come from the default shader (the body one).
The content is almost ready to be packaged, except that we now need to replace the shaders with actual ones from Cold Steel. Normally you should have saved somewhere the original shadow .fx.phyre file, as well as the body .fx.phyre. Those two are the only shaders we will need. However we need to update all references to the dummy shader inside the .dae.phyre with the references to the original shaders we will be using, and this can only be done in a hex editor.
So open van.dae.phyre in a hex editor, and look for ".fx". You will find a section in the file where all the shaders reference are stored.
Every shader is separate from the other by a 00 byte. We will replace all the "dummy_...." shader with our original body shader, which was called
"ed8_chr.fx#F797E04B6E5A5AC069D06B3241589336". However, we also need to make sure the file size doesn't change, so all the bytes you will remove needs to be replaced with 0 at the end of the path to ensure that. Example here with the first path:
We removed "dummy_" and the whole hash code at the end of the path, added zeros at the end of the path to ensure the file size remains unchanged.
This annoying process is necessary as the phyre file has a lot of pointers and we don't want to make them address the wrong thing.
Repeat the same process for all dummy shaders.
Once this is done, the last shader remains: the custom one. In our situation where we only had one custom shader added through Maya, it is simple to guess that this shader is the shadow one. But if you really went through the process of creating a shader for all materials, it can be a bit difficult to link them to their original shaders. The only way we currently have is to open van.dae.phyre with the PhyreDummyShaderCreator. It will generate a list of fx files with their parameters, that you can link to the original fx files you copied in the first place by looking at the content of the .fx files. If the parameters are the same in the same order, then both files are compatible, and you can replace the new path with the name of the original shader.
For example, for the shadow shader, here is what we obtain by opening van.dae.phyre with the PhyreDummyShaderCreator:
By comparing the original shader #7D5 used for the shadow with the new shader used for the shadow, we can see that both fx file have the same content:
meaning that they are compatible. Thus we will replace the name of the new shadow shader #F60 with the name of the old shadow shader #7D5:
Now that all files are prepared, we need to pack them into a pkg. This involves creating a new folder called C_CHR000 (we will replace Rean), and writing a new asset_D3D11.xml.
So first, create the folder, and put all the dae.phyre and dds.phyre, as well as a asset_D3D11.xml extracted from a random character PKG from CS4 (doesn't matter who).
You also need to get the original shaders, the one for the shadow (which will be in the pkg you first unpacked, and is named #7D5), and the one for the body (should be in the same pkg, mine was #F79.
The final content of the folder should look like this:
Finally, we need to change the xml file so that it matches our new pkg content.