Page 1 of 1

Path, Folders, .mat and .tobj files [Guide]

PostPosted: Tue Mar 18, 2014 5:15 am
by Oleg
ETS2 Path and folders guide.
    This guide applies to questions on:
  • missing in-game resources (shader not found);
  • .mat and .tobj files are not created on export;
  • files not found on import into ZModeler.

Even if you are aware about ETS2 modding workflow, game data structure and files, you should still read this guide as it might give some valuable hints to improve your own workflow.

First of all, game resources are always packed into achieves, known as .scs (actually, .zip files renamed to .scs). Each achieve is mounted by the game to it's own virtual "resources" drive, so the game has a mapped location of each resource exactly the same way as you have your files located in folders and sub-folders on your hard drive, the only differences is that game accesses and loads (unpacks) each resource on demand only.

Before you start modding ETS2 you have to make the very first step: unpack game achieves into your local drive, so you have all the resources available as files. This routine is known as "unpacking the base", since the "base.scs" is generally the whole game resources you might see in game: models, textures, materials, effects and so on. I personally always unpack the base into "My Documents/Euro Truck Simulator 2" folder. Note, when game patch is applied, you should unpack the base.scs again. Once unpacked, you will see a lot of folders and sub-folders there:


Unpacking the base is a must, since it contains resources available to the game and to game mods. Each game mod can still use (or more precise word is "refer to") base resources. For example, each truck model can safely refer to a common environment mapping textures, some brushed or stamped metal textures are shared among truck models, so you might find daf_xf model refering to a texture located in man_tgx, and it's ok for the game.

As I've mentioned earlier, these resources are "mapped" and "referred" by the game. Consider "mapped" as "each file on a given location is known to be available" (and will be unpacked and loaded on demand), and "referred" is known as file location with absolute path given. So, to refer onto some file or resource, an absolute path on a "virtual drive" is given. For example, if you open any .mat file as a text file, you will see references onto texture object files (tobj)


Each texture object file, in a run, refers to a texture image file(s), given an absolute path too. As you see, the physical location is not specified (drive letter, mod name or anything of a kind), each file reference starts with a leading slash / followed by folder name(s) and finally the file name is given. When the game reads .scs files it populates is "virtual drive" with available resources and matching files/resources coming from mods will suppress previously available resources. Consider this as redefining of resource location, as certain file previously available in base.scs should then be loaded from some_mod.scs

Here we come to the mod structure closely in terms of resource reference replacement. If you modded the truck model located in "/vehicle/truck/volvo_vh16_2012", then your mod should contain "vehicle/truck/volvo_fh16_2012" folder, so original model file(s) are properly replaced with modded files. So, each mod should retain original folder structure, thus original game resources are properly replaced with modded resources. At the same time, your mod should contain modified resources only, so you can reduce memory consumption and increase loading speed. For example, if you modded the truck geometry, you should not pack textures into your mod, since original game resources can still be used. In most cases, respective texture object (tobj) files can still be omitted as original resources will suit fine.

The folder where the game looks for the mods is entitled "mod", this is the folder where you put your mod packages, so the game finds them quickly on a very early loading stage.

Loading a model into ZModeler.

ZModeler does not deal with .scs packages, instead all required resources should be unpacked and available. Once the base.scs was unpacked, you should specify the location of unpacked base in the import window. Given a location of unpacked base, plus the absolute reference to resource, ZModeler will be able to locate a resource given it's reference, starting from the base folder. For example: D:\My documents\Euro Truck Simulator 2/vehicle/truck/volvo_fh16_2012/, where "D:\My documents\Euro Truck Simulator 2" is the base folder. Once specified and always used.

Here we come to some problem of loading a modded file(s). For example, you have downloaded a mod, it contains some modded files, materials and some additional textures, but it still can use resources located in base. In order to load such a model, base resources and mod resources have to be available, but unpacking mod (resources) into unpacked base folder is certainly bad idea. Instead, you can unpack such a mod into a temporary folder and specify this folder as the "Mod folder" on import. Thus, while importing a model from unpacked mod, ZModeler can reach resources in unpacked base and in unpacked mod:
"D:\Temp\ETS2Mods/vehicle/truck/volvo_fh16_2012/" texture will be found on import while it's reffered as "/vehicle/truck/volvo_fh16_2012/" and "D:\Temp\ETS2Mods" is specified as Mod folder.


If you have several inter-connected mods (when one scs pack require shared resources from another scs pack), you should unpack them all into a temporary mod folder, so all these resources are available on import.

Exporting a model from ZModeler.

It's very important to understand, that each resource references has to be constructed properly. Any geometry model have to refer to it's materials with a proper absolute path reference, and each material refers to textures with a proper absolute path too. The formerly-known Origin value was used to specify the absolute path to the exported model, so the Origin was used to construct absolute path references to materials and textures. In order to suppress the Origin path for certain materials or textures, a materials group or texture groups are used. You can create a material group in materials browser, give it an alternate absolute path as a name, and drag&drop respective materials into this group. The name of the group name will be used as a path to respective material when exporting. The same applies to textures, so you can create a pool of common textures for several mods, or force your model to use some shared materials or textures from the base.

How this works in updated filter (build 262 and above)? The "Mod folder" should now be specified on export too. For you to understand it properly, this is the folder where the mod starts from, so the mod folder should be "D:\Mods\Export" if you export your truck into "D:\Mods\Export/vehicle/truck/volvo_fh16_2012" folder. As you can see, the filter can now match "D:\Mods\Export" of your exported file to the mod folder, and the rest can be used as the origin: "/vehicle/truck/volvo/fh16_2012". This is known as a graceful export. Is there any benefit on such a scenario, as you have to make one more step - specify a mod folder on export? There is indeed. When "graceful export" scenario is detected, the filter will consider your mod folder as "free to access" and will create all the required folders and will generate all the required .mat and .tobj files in correct folders at once. Thus, for example, if you have a texture "" assigned to texture-group "/vehicle/truck/share/textures", the filter will create a folders "vehicle/truck/share/textures" too, and it will generate required tobj files there. Technically, a graceful export will create all required folders and files for your mod inside a Mod folder (it will not copy physically texture .dds files however), but at least you have a properly-organized folder structure.

An additional folder organization benefit option was added is using "relative" paths as a group names for materials and textures. Relative path does not start with a slash, and this path is considered to follow the origin. Thus, for example, if you create a group "materials" and assign all materials onto this group in materials browser, create a group "materials/textures" and assign all textures onto this group in textures browser, a graceful export into "D:\Mods\Export/vehicle/truck/volvo_fh16_2012" will produce a folder "D:\Mods\Export/vehicle/truck/volvo_fh16_2012/materials" with all .mat files in it and a folder "D:\Mods\Export/vehicle/truck/volvo_fh16_2012/materials/textures" with all .tobj files in it. So you can keep your exports clean and organized.

As you can see, the "Origin" option is obsolete and should not be used, if you perform an export in "graceful export" scenario. The option might still be available on a root dummy node, it's not a must to delete it, but it should match the "detected" origin on export. If they don't match, a warning message is logged and you get an export in a regular (non-graceful) scenario, when most of .mat and .tobj files are created in the export folder, but their references are not matching their final location.

The image shows a graceful export into "D:\Temp\Mods\Export" folder. As you can see, some extra folders were created, like "/material/environment", "/vehicle/truck/share" and "/vehicle/truck/upgrade/paintjob". These folders contain .tobj files generated too, but as these contain no relevant changes, you can safely delete them (folders and/or files). You should at least delete "material/environment" folder as it contain a static-texture reflection .tobj file and real-time reflections will not work when this .tobj is used.


Re: Path, Folders, .mat and .tobj files [Guide]

PostPosted: Wed Mar 19, 2014 12:45 am
by Oleg
Associated error messages on Import/export:

"Origin" option on root node does not match the export path relative to "Mod folder". The filter will use "Origin" as a destination path still
The root dummy node of your exported hierarchy contains Origin option, and it specifies a path to use. This path does not match the path your are exporting relative to "Mod folder" specified on export. This turns into non-graceful export scenario when all .mat and .obj files are created locally, and the value of "Origin" is used to compose path references on materials and textures. For example, your trailer Origin option specifies /vehicle/trailer_eu/container, but you export into D:\Temp\Mods\vehicle\trailer_eu\reefer (with "D:\Temp\Mods" specified as mod folder). Paths to .mat and .tobj files will be generated with respect to Origin, so "container" will appear in a path, in contrast to "reefer" that you probably intended to use.

Missing "Origin" option on root exported node. Textures path can not be generated properly!
Even thought "Origin" option is obsolete, you have to follow the graceful export scenario by setting correct Mod folder and exporting into some folder inside it. This error message appears when Mod folder is specified, but you export somewhere outside of specified mod folder (non-graceful export scenario). In such a case ZModeler tries to use Origin option to resolve the problem, but Origin is not specified, so ZModeler can't fix export scenario and generate any paths to materials or textures. The result path is undefined. To resolve the problem either add Origin option and specify there a path to use, or specify Mod folder and export somewhere inside mod folder.

"Mod folder" either incorrect or not specified. Might be unable to generate some material or texture files.
Very alike to the previous error, but might appear when Mod folder is not specified at all. To resolve the problem either add Origin option and specify there a path to use, or specify Mod folder and export somewhere inside mod folder.

Can't open file for write: some_file_name.
Some of folders and/or files inside Mod folder are write-protected, so ZModeler can't overwrite them on export. This could be caused by opened files (when you open some .mat files for manual editing they are locked to prevent overwrite). Additionally, your antivirus might prevent ZModeler to create files in some cases. When you specify a Mod folder, this folder and any folder inside it is assumed to be freely-accessible for ZModeler, so it's expected that ZModeler can create folders and files there with no limitations. To resolve the problem, ensure the Mod folder is not write-protected and you don't have any opened .mat or .tobj files located inside Mod folder; apply some different restrictions on ZModeler application in your antivirus if it causing problems.