Modifying materials (textures and shaders)

This is a deep dive on materials and how to change shaders. If you just want to change a texture, please refer to the basic modding tutorial. The second half of this tutorial has a link to a tutorial on obtaining UV (texture coordinate) maps, a discussion about specular maps, and a discussion about transparency.

Understanding materials

Materials are the combination of textures and a shader set (a sequence of small programs used by the GPU to draw the object, most often a vertex shader and a pixel shader but there may be others). The shaders will apply the textures to the object, and then modify the appearance (e.g. applying shininess and transparency). We can change textures but shaders cannot be directly modified. We can exchange one shader set for another, however. For a deep discussion on why shaders cannot be (easily) directly modified, please refer to this tutorial.

For the purposes of this tutorial (and really all the tutorials), there are meshes that are made up of submeshes. Each mesh is a collection of submeshes grouped together and attached to a single node, with a single vertex group (bone) map. For example, Dana's main body is c005_ps4_main2 (the mesh, attached to the c005_ps4_main2 node as a VPAX block), which is made up of 9 submeshes - c005_ps4_main2_00 through c005_ps4_main2_08. Each submesh has its own material, but all submeshes in a mesh must use the same shader set (but they can have individual tuneable parameters for those shaders).

Shader assignment

Shader sets are assigned in the RTY2 block, which is at the mesh level. That means that all submeshes in a single mesh use the same shader set. These are all listed in {Ys VIII / IX directory}/pcshader/shdlist.csv.

Shader sets are listed in materials_metadata.json upon mesh export. For example, Dana's main body c005_ps4_main2 has its shader assignment in rty2_shader_assignment in materials_metadata.json, the contents of which looks like this:

    "c005_ps4_main2": {
        "rty2_shader_assignment": {
            "material_variant": 15,
            "unknown": 0,
            "v0": [
                0.0,
                0.0,
                0.0
            ]
        },
...

One can see it uses material_variant: 15, which is CHARA_TOON_BONE (the basic character shader) according to shdlist.csv. Her hair utilizes material_variant: 17 which is CHARA_TOON_BONE_NORMAL. Dana's eyes are material_variant: 110, which is UV_EYE_BONE_BASIC. Changing this value will change it for the entire mesh, and all submeshes must have compatible mesh files and material blocks. (For example, meshes using material_variant: 15 do not utilize the TANGENT spot in the .vb file, but material_variant: 17 meshes do - and thus a mesh missing this data will not look correct when moved from a material_variant: 15 spot to a material_variant: 17 spot.)

Shader parameter and texture assignments

Every mesh in a model must have a material applied to it. This assignment is made in the toolset using the .material file, which is a plain text file in JSON format. If you edit this file in notepad, you will see the name of its assigned material. For example, in Dana's default costume (c005_p.it3), her outfit (c005_ps4_main2_00) is assigned to "c005n_base".

Contents of c005_ps4_main2_00.material:

{
    "material_name": "c005n_base",
}

Looking in materials_metadata.json, in the c005_ps4_main2 section underneath rty2_shader_assignment is material_parameters. The first section is c005n_base.

        "material_parameters": {
            "c005n_base": {
                "MATM_flags": 65793,
                "MATE_flags": 65793,
                "unk0": [
                    92,
                    0,
                    1,
                    0,
                    0,
                    2,
                    0
                ],
                "parameters": [
                    [
                        0.8820000290870667,
                        0.6557745933532715,
                        0.5530139803886414,
                        2.0
                    ],

...continued...

                ],
                "textures": [
                    {
                        "name": "p0052",
                        "flags": [
                            1,
                            0,
                            0,
                            0
                        ]
                    },

...continued...

There are 4 sections to each material:

1. The name - each material needs its own unique name! If you modify a material but a different submesh has the same material, and you forget to change the name, then you may end up wondering why nothing changed.
2. Material flags. The first number (92, in the example above), is a legacy value and should not be changed (it is the size in bytes of the flags and parameters).
3. Tuneable shader parameters. The parameters themselves can be tuned by changing the numbers; however we do not know what these numbers do.
4. Texture names, and their sampler definitions.

Modifying the material without changing it

To change textures, see the basic modding tutorial. Note that if you are not changing the material, then you can change the textures but NOT the texture slots. (e.g. If the material expects a normal map, you must provide one.) You cannot simply remove the slot and you cannot add new slots, unless you change the material. Note: In some cases, you can leave the name of a texture as an empty string, and the game engine will know to omit it. This is not universal as far as I know, however.

To change the tuneable parameters, simply modify the numbers. I do not know what effect this has, however.

To change the texture sampler definitions, you can edit the values. Each texture has 4 sampler values. I do not know what the former two values are (perhaps mipmap filters?). The latter two values are for UV wrapping. Valid values are 0: REPEAT, 1: CLAMP_TO_EDGE, 2: MIRRORED_REPEAT. Here is a tutorial on what these values mean - keep in mind the tutorial was written for WebGL, but the fundamentals are the same.

UV maps etc

For a tutorial on obtaining, evaluating and manipulating UV maps, please see my Cold Steel tutorial.

The specular maps

Very few Ys VIII costume models use normal maps, but shader 15 (CHARA_TOON_BONE aka the common character shader) uses specular maps. Unlike Cold Steel, the specular maps are quite dark in Ys VIII and are very very sensitive. For example, here Dana's dress is shaded with mono-color specular maps that apply an even sheen to the dress, with black to 3 very modest greys. You can see that the shine gets out of control pretty quickly.

As you can see, #282828 is a dark gray, it is hard to distinguish from black. Yet, as you can see above, it is enough for the shader to apply so much shine that details are obliterated.

Thus, when you are creating your specular maps, aim for dark. If you use Normal Map Online for example, a decent starting point is Strength of 0.3, Mean of 0.5 and Range of 0.3.

Transparency and the order of materials

Within a mesh, the game will render the submeshes in order from first to last. This is not a common (or, quite frankly, acceptable) way to render meshes. What this means for transparency is that objects behind the transparent object will be rendered only if they were processed before the transparent object. Otherwise they will be invisible.

For example, here I have reversed the order of the materials in the right image such that the transparent weave was ordered first, instead of last, using the Material Properties panel to the right of the 3D Viewport.

Now the transparent weave is rendered first, and all the meshes that should be behind it are no longer visible.

Keep this in mind when merging submeshes for export in Blender, as Blender often scrambles the order of the submeshes when combining them into a single mesh. Use the Material Properties panel (shown above) to reorder them such that transparent submeshes are rendered after the objects that should be visible behind them.