Materials library in .zml files

Post a reply

:D :) :( :o :shock: :? 8) :lol: :x :P :oops: :cry: :evil: :twisted: :roll: :wink: :!: :?: :idea: :arrow: :| :mrgreen:

BBCode is ON
[img] is ON
[url] is ON
Smilies are ON

Topic review

Expand view Topic review: Materials library in .zml files

Re: Materials library in .zml files

by Oleg » Sun Oct 01, 2023 12:21 pm

Texture references inside .zml files are their original path\name (e.g. "E:\Modding\MyMod\Test\"). Upon loading .zml file, material tries to load texture from its original location, but is allowed to search for it if not found. In particular, it will try every folder listed in "Settings->Services->Textures" list. Also I have refined textures loading code with explicit attempt to load from current folder, so get the latest update and give it a try again.

In case of GTA models, loaded textures (loaded from .ytd packages) will have no origin record, just a file name. So the saved .zml file will contain a reference to texture filename only. Given that, the associated texture should be in the same folder as the .zml file to be loaded properly. Or such textures can be in some shared textures folder listed in "Settings->Services->Textures", this should work fine too.

Re: Materials library in .zml files

by Moviefreak » Sat Sep 30, 2023 8:52 pm

Anyone succeeded to save a material correct? i can only save zml files that are about 14kb, when i load a zml file on a new project, only some textures are loaded, all the textures are saved in the same folder as the *.zml...

Materials library in .zml files

by Oleg » Fri Sep 22, 2023 7:31 am

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).