Zanoza Software

22nd September 2023.Materials library in .zml files

Materials editor provides an option to load and save individual material files. This was generally used by game formats that store materials as external files, so one was able to update or change materials without bothering with loading the model file itself.

However, it was a demanded option to be able to manage/access material files from the rest of supported game formats and/or be able to configure newly-created material to be game-ready.
An ability to save material (or several materials) from ZModeler in a native format with no loss of configuration data was the solution I have chosen. Now, you can Load/Save multiple materials as "ZModeler Materials Library" files (.zml) files, using "Load..." and "Save..." buttons in Materials browser:

Since every .zml file is a library of materials, you can use "Save...\Save into..." option or add new materials or replace existing materials in a file. Like in the Load... option, you get a list of available materials inside a library file (to replace on save or to be loaded on load), as well as the preview image and quick description including shader, adaptation and group (if applied).

When material is loaded from a library file, ZModeler tries to load required textures too, as textures are not stored in a library file. If you deal with materials from GTA game, I advise to unpack and store associated textures as .dds images next to the library file, as textures can not be loaded from texture dictionary files (.ytd files). The image below shows a standard license plate material from GTA loaded from a library file into an empty scene. Standard textures were loaded from the same folder as .dds textures.

Extra advantage of using load/save of native ZModeler materials is that they store states and variations too. For example, ETS2/ATS models (and especially prefab models) can use shared materials across a set of models files for sidewalks, road and grass. And these materials can be configured to have different variants (for different countries or different tiles setup):

Saving such a material in a library allows to load it with all states configured. Of cause, if your scene does not have some material state configured (e.g. not used in your prefab model), the load will show a warning (on missing variant) and will discard such a variant on load. The image below shows a "sidewalk" material loaded from a library into the scene with no states created: only default state was loaded.

Material names
Since materials accessed inside materials library by their names, the name of material within a library is unique. An attempt to add material with the same name into a library that has such a material already will result in automatic rename in manner "name[1]", "name[2]" and so on. For example, if you save several different materials with the same name into a library file, all materials will get saved, but some of them will get renamed:

The image above shows three "red" materials saved into a library file and, as a result, you can see "red", "red[1]" and "red[2]" materials in a library now. If you repeat the operation and try to save three "red" materials once again, the "red" material in a library will be replaced (with the first one of three "red" materials coming for saving), but the other two "red" materials will not replace existing "red[1]" and "red[2]" as their names are not matching. As a result, you will get one material replaced ("red") and a pair of newly added ("red[3]" and "red[4]").

Pay attention to "Save...\Save into..." option. When using this method, you are allowed to select material in a list of materials in a library file you have picked for save. The saved material will replace the selected one (unique names are retained, so if you save a "road" material instead of "pavement" and the library already has another "road" material, the newly-saved will get named as "road[1]").

In particular, when you deal with GTA materials, their default name usually matches the name of primary texture (the one on "DETAIL" texture slot). This causes several different materials to have the same name (e.g. when "vehicle_genericmud_car" texture is used on DETAIL texture slot and the actual texture is on DETAIL2 slot). Consider giving a meaningful names to materials before saving them in a library file as there is no rename option provided (unless loading, renaming and saving-into with replacement of original material).

Discuss in forums: 2 comments