Farmsim Forensics: UDIM, the Giants way and beyond

Welcome to the second episode in a new series of blogs and tutorials for Farming Simulator 19 modding: ‘Farmsim Forensics’. In this series, we take a deep dive into some of the more advanced concepts and techniques used in making maps, buildings, vehicles and implements for Farming Simulator.
This is not a beginners series. Basic knowledge of the various tools used for modding, like GIANTS Editor, Blender, Photoshop or similar is assumed.

The GIANT’s Causeway, Northern Ireland

In this episode, let’s take a closer look at UDIM. Or more specifically, working with materials in FS19, because there’s a lot more to it than just UDIM. As things tend to go in this community, using UDIM has very quickly become the litmus test for texturing quality. However, all that glitters is not gold…

There’s a number of high level tutorial articles and videos out there, that serve a very good purpose. If you want to quickly find out how to assign a predefined Giants material to part of your truck or tractor, they are an excellent resource. The problem is, these tutorials don’t show you the how, nor the why, nor the full potential of the system. So if you want to find out, take the red pill, you stay in Wonderland, and I show you how deep the rabbit hole goes.

What is UDIM?

Before diving into all the Giants-specific stuff, let’s have a quick look at what UDIM is. UDIM stands for U-dimension, and allows you to use more than the normal ‘0 to 1’ UV texture space. It assigns a unique number to each tile, and its main purpose is to allow you to specify multiple, smaller textures to a single model, in situations where using a bigger single texture is no longer sufficient.

UDIM UV tiles

Beyond the very basic functionality of specifying UV mapping for a model in a standardised way, there is no universal UDIM implementation in rendering and game engines. Only the most recent versions of the main 3D software packages, Maya and Blender, have improved support for UDIM, but as we’ll see later on, we have some tools in our toolbag to make working with UDIM a breeze.

‘UDIM support in FS19’ — What does that mean?

So, now that we have a general idea what UDIM is, let’s have a look at what it actually means that FS19 ‘supports’ UDIM. To really understand that, we need to take a couple of steps back, and first have a look at how the game engine translates your 3D model into a textured object visible in the game.

Simplified view of a rendering pipeline

The diagram above shows a simplified view of the graphics rendering pipeline. The bag of vertices on the left? That’s your 3D model. There’s two moments in the pipeline where we can control what the end result will look like. The first one is the vertex shader. It’s main purpose is to determine the position of your vertices. The next one is the pixel shader, also called fragment shader, that colors them.

FS19 has implemented these shaders in Cg, a shader language based on the C programming language, developed by Nvidia. The actual shader code is part of the internals of FS19, so I can’t show you a fragment of it, but in case you’re curious and know your way around the game files, they are included in the shared/shader.gar archive. The good news is, Giants included a huge number of so called ‘hooks’ in them. Hooks are moments in the execution of the shaders where you can insert your own code to be executed.

This is something very few people are aware of. Giants actually provided us with an extensive and very open framework allowing us to affect almost every aspect of how the game looks, and behaves.

The way to specify these hooks, and tell the game engine how you would like to affect the way something is rendered, is through shader XML files. This is familiar territory for most modders, as you select these shader XML files in GIANTS editor. There’s plenty of shaders included, the buildingShader and the vehicleShader probably being the most used for, as the name implies, buildings and vehicles.

Shaders included in FS19

I thought this article was about UDIM?!

You’re absolutely right, and we’re almost there. For that, we need to take a closer look at the vehicleShader, because that is the shader that ‘supports UDIM’. Now from the introduction about UDIM, you know that UDIM is basically nothing more than unwrapping parts of your model into different UV tiles, so you can assign different textures to them.

In the vehicleShader however, Giants did something more than just that. They used a very specific implementation for interpreting the UDIM tiles in a model. This interpretation goes beyond the basic definition of UDIM, and it violates the UDIM standard. Because most readers are probably here because they just want to know ‘how to UDIM their tractor/truck’, we’ll have a detailed look at what they did, how they did it, and how you can use it first.

UDIM support in FS19. The story of how a single shader abuses UDIM, in a non-standard way, to implement a flawed material library, and became the de facto standard for all vehicles and implements in FS19.

VehicleShader — Vertex Shading

When we looked at the rendering pipeline earlier, I mentioned there’s a vertex shader, and a fragment shader. For the UDIM part, all the exciting stuff happens in the fragment shaders, as that’s the shader that applies the textures, but just to make sure we covered everything, this is the vertex shader part of the vehicleShader, that simply sets the position to the position it has in your 3D model, unchanged. There are cases though, where the vertex shader is used to change vertex positions. Use cases vary from tire deformation, to jiggling parts, and even tracks are fully implemented using the vertex shader.

<CodeInjection position="GET_POSITION_VS">
<![CDATA[
  float3 mPos          = In.position.xyz;
]]>
</CodeInjection>

VehicleShader— Fragment Shading

Here’s where the UDIM magic happens. Based on the UV tiles you unwrapped your model parts in, the shader needs to figure out which texture to use. The implementation Giants used in the vehicleShader sets a few conditions for this. The maximum number of tiles in the U-direction is set to 8. And a special meaning is added to the row of tiles at V -1.

Giants’ ‘modified’ UDIM grid

The UDIM standard does not allow tiles with negative coordinates in both U and V directions, but fortunately, both Blender and Maya will still allow you to put your UVs there. More about that special row in a bit, first let’s take a look at the ‘standard’ tiles. If you put your UVs in any of the regular UDIM tiles, where does the shader get the textures from?

Texture arrays, or ‘Giants Material Library’

The shader takes 3 texture files. These 3 texture files point to so called ‘texture arrays’ for the diffuse, specular and normal textures. These texture arrays are special DDS image files that contain an array of images, in a certain order. The order of the images corresponds to the order of the UV tiles (1001, 1002, 1003 etc.). A single DDS texture array can hold as many images as needed. For use in Giants’ shader, all images need to be the same type, and the same resolution. Giants also ships with a set of these texture arrays, that I call the Giants Material Library. You don’t have to use them, and I’ll show you how to create your own texture arrays in a bit, but first let’s have a look at what’s actually in there.

These are the 39 materials that Giants has included in their material array. Each of them corresponds to a specific position in the UV grid. For reference, this is the UV grid with all the materials. All of these maps are designed as tiling maps, which means they use small textures (512x512) that are repeated across the surface of your model. That way, regardless of the size of your model, you will always enjoy the same texture resolution.

UDIM cheatsheet

To use any of the materials, simply move your UV map into the corresponding tile. For example, if you want your part to be wood, move your UV 6 tiles to the right, and 1 tile up.

Material Selector for Blender

You can do this manually, or if you use Blender, you can use the excellent tool made my NLD Community member fa285634, available for Blender 2.79 and Blender 2.80+ (links below). With that tool, you simply select your components UV map, and click the button for the desired material. The tool automatically move the UV map into the correct tile. I highly recommend using this tool!

The Special Row

As mentioned above, the vehicleShader defines a special row of UV tiles below the normal grid, with V coordinate -1. These slots are named colorMat0 to colorMat7. What makes these slots special, is that the shader allows you to specify a color, as well as a material number in the GIANTS Editor. This gives you 8 slots to use any of the materials, in any color you want. The color you select will completely replace the diffuse texture of the material you selected.

colorMat properties in the Custom Shader panel in GIANTS Editor

Now that we’ve covered the basics about UDIM, and we’ve taken a closer look at how Giants uses it in their vehicle shader, it’s time to address some of the misconceptions about UDIM and materials in FS19.

‘Do you UDIM?!’ Sometimes I do, sometimes I don’t, and you would not be able to tell the difference.

Myth: UDIM makes everything look good

False. Generally speaking, UDIM does not affect how your model looks, at all. Yet, it’s the first thing anyone asks about a new model, or a converted model, or just if you just mention you’re a modder: ‘Do you UDIM?!’. My answer: sometimes I do, sometimes I don’t, and you would not be able to tell the difference. Because here’s the thing: UDIM turns out to be nothing more than a fancy way to set your UV coordinates. What makes something look good, is the quality of the materials. You can use UDIM all you want, but if the materials it points to look bad, there’s nothing UDIM can do to help you there. And vice versa, if I use a custom set of textures, with proper maps, and I don’t use UDIM, the result will be exactly the same.

I’ll let that sink in for a moment: UDIM does not make your model look good. The key here is not UDIM, it’s PBR. PBR, short for Physically Based Rendering, is a method to render a material in a way that is physically correct, taking into account the different effects that lighting has based on the physical properties of a material, like the roughness, metalness, reflectivity etc. All of the materials in Giants’ Material Library are PBR materials, which is what makes them look good. So the next time you want to ask about the use of realistic looking materials, don’t talk about UDIM, and simply ask:

Did you use PBR?

Confusion: not all PBR materials are created equal

So let’s say you decide to use your own material, then how would you go about creating that? Giants has done an amazing job in making this as confusing as possible. Not only did they not document any of this, they have also used a lot of conflicting wording throughout.

When creating PBR, there’s more than one way to generate a set of textures to represent a material. The two most common workflows are the specular workflow and the metalness workflow. In a specular workflow, a material is described by it’s specularity, and it’s glossiness. In a metalness workflow, a material is described by it’s roughness, and it’s metalness.

Different PBR workflows

Here, you see the two sets of maps side by side. Clearly, the two are not interchangeable at all. Giants uses roughness/metalness, but with a twist. Instead of roughness, they have decided to use smoothness in their maps, which is the inverse of roughness. In normal terms, if something is smooth, it isn’t rough, and the other way around. Mix these up, and the result is either a lot duller, or a lot shinier, than you expected. I hear this a lot from different modders.

Smoothness vs Roughness for Giants’ Painted Metal material (#16)

I haven’t found a single tutorial, video, article or webpage about FS19 materials anywhere on the internet that gets this right. Not one…

So, what did Giants do to make this confusing?

1. In the Material panel in GIANTS Editor, the first map is called ‘Albedo Map’. So far so good. The second map is called ‘Gloss Map’. Wait? Didn’t we say Giants uses a rough/metal workflow. Exactly, so this is not a gloss map, it’s a combined rough/metal map. The next two settings in that panel are actually for smoothness and metalness, so that’s correct.
2. Next up is our beloved vehicle shader. It takes three texture arrays, as we have seen before. They are called mArraySpecular, marrayNormal, and mArrayDiffuse. The filenames for the default texture arrays match this naming convention as well. However, 2 out of the 3 are wrong. The specular one isn’t a specular map (in fact, a specular map is an optional additional map used in both PBR workflows). Instead, we find our trusty smoothness/metalness map here. The last one, the diffuse map, is also not a diffuse map. In fact, it’s the albedo map. A diffuse map is used in the other PBR workflow, and vastly different, because it doesn’t contain color for metal parts.
3. Okay, this last one isn’t one that you’ll ever get to see most likely, as it’s buried deep in the shader source, but I want to share it anyway in case any other OCD developers/purists happen to be reading this:

#if defined(GLOSS_MAP)
// Roughness map layout is: RGB = smoothness, ambientOcclusion, metalness

So if a GLOSS_MAP is defined (which isn’t a gloss map), then the comment reminds us how the roughness map (which, again, it isn’t) is composed. And people wonder why us simple modders can’t get it right…

Is that really normal…

Before we can wrap up this part about materials and maps, there’s one more thing we need to look at, and that’s normal maps. As most of you who made it this far through this article probably know, normal maps are a way to define details in the surface (bumps and dents), without adding additional vertices to your model. Lighting is used to ‘fake’ these details, while the actual surface remains completely flat.

Rendering with normal maps (image by Pac72, source: https://commons.wikimedia.org/wiki/File:Rendering_with_normal_mapping.gif)

Normal maps do what they do by describing the angle at which light would be reflected from the surface. It only describes the angle, so it has no concept of actual depth or height of a dent or a bump. However, if we look at the Material panel in GIANTS Editor, we notice a field there called ‘bump depth’.

Bump Depth setting in GIANTS Editor

So, what’s that being used for? Apparently, there must be some way to tell our shaders about the bump depth. As it turns out there is. Not used by the vehicle shader, and by most other shaders, but usable for things like buildings, it is possible to add additional information to add a displacement map to the alpha channel of the normal map. Don’t let the term ‘bump depth’ confuse you (again), the map with the additional information is in fact a displacement map, not a bump map. I won’t go into detail about the differences, I’ll do that in another article about the building shader.

The GIANTS material maps layout

The only thing in this diagram we haven’t discussed yet is the ambient occlusion map in the green channel of the rough/metal map. And honestly, there’s not too much to say about it either. Ambient occlusion is a fancy way of saying ‘baked shadows’. In this context, that really only applies to shadows that are inherent to the material itself, and because of that it’s most commonly called ‘micro AO’. Examples are shadows caused by bumps in leather, or by holes in perforated fabric.

If you decide to work with your own materials, and I’m going to show you how in a minute, your material either has it or it doesn’t. If it does, that green channel there is the channel it goes into.

The sky is the limit

As we’ve seen earlier, the vehicle shader is ‘just’ one implementation of a shader, that ‘just’ happened to pick a specific way to interpret texture maps, and a specific way to interpret UDIM tiles. Does that mean you should limit yourself to it? By all means, no. There’s tons of ways to use the existing shader as an example, and adapt it to something that suits your needs, whatever that need may be. Maybe in the future I will do a follow up with a couple of examples, but for now, I want to take a shot at answering the question I get the most: can I use my own materials?

Creating your own material library

Giants’ Material Library goes a long way, with it’s 39 materials you’re off to a flying start. But sooner or later, there comes a time where you run into a material you need that’s not in there, a different type of wood maybe, an improved texture, maybe a material you made in Substance Designer. Especially as a more seasoned modder, or texture artist, you build your own library over time, and the Giants materials may slowly start to feel limiting. I’d like to show you how to make your own material library. We’ll create one using 3 custom materials.

Custom UDIM grids for my own materials

For that, we need to create texture arrays, similar to the built-in ones. I’m going to show you how you can create your own from scratch. First, make sure you gather all the texture maps for all the materials you want to include. You’ll need the albedo maps, the rough/AO/metal maps, and the normal maps.

Just like when using these textures directly, make sure they are in DDS format. Feel free to use any method for the conversion, just make sure that all textures you use have the same format and the same resolution. For the conversion, I like using the awesome ImageMagick command-line tool (link below), allowing my to convert all of them in one go:

> magick mogrify -format dds *.png

Next, grab a copy of the Texture Assemble tool from the GIANTS Developer Network website (link below), and extract it to a convenient location. With that tool, we can create our 3 texture arrays:

> ./textureAssemble.exe myTextureArray_albedo.dds Rustingmetal_Albedo.dds Bowling_ball_Albedo.dds Gravel_Albedo.dds
Loading 'Rustingmetal_Albedo.dds'.
Loading 'Bowling_ball_Albedo.dds'.
Loading 'Gravel_Albedo.dds'.
> ./textureAssemble.exe myTextureArray_normal.dds Rustingmetal_Normal.dds Bowling_ball_Normal.dds Gravel_Normal.dds
Loading 'Rustingmetal_Normal.dds'.
Loading 'Bowling_ball_Normal.dds'.
Loading 'Gravel_Normal.dds'.
> ./textureAssemble.exe myTextureArray_rough.dds Rustingmetal_Rough.dds Bowling_ball_Rough.dds Gravel_Rough.dds
Loading 'Rustingmetal_Rough.dds'.
Loading 'Bowling_ball_Rough.dds'.
Loading 'Gravel_Rough.dds'.

Take a note of the order in which you list your textures. The order determines where in the UDIM grid your texture ends up, starting at 0,0 and filling it row by row. With our 3 texture arrays packaged, it’s time to hop over to the GIANTS Editor, and use those new materials. I’ve prepared a model that is UV mapped to the 3 tiles we created materials for.

After exporting it to GE, you go through the normal steps of assigning the vehicle shader. Then, in the Custom Shader panel, replace the default texture arrays, under Custom Texture 0, 1 and 2, with your own texture arrays.

If everything was done correctly, you should now see your new materials in the viewport.🎉

Even though this works great, more often than not you would probably much rather add your own materials to the existing texture arrays, in order to use both Giants’ materials, and your own. Unfortunately, it is not possible to add additional textures to an existing texture array. And the only way I found to extract them involves opening them in GIMP, exporting them to an intermediate format, extracting them again, and converting them back to DDS. So I’ll make it easier for you. I have prepared an archive with all the images from all 3 texture arrays. With this, you can pick the materials you need, add your own, and create your texture arrays as described above. Use the link below the image to download.

detailArray_extracted.zip

This turned out to be a way longer article than I had originally planned. I deliberately left out some topics, like the wear and dirt mask, because a lot has already been written elsewhere about that, or shader variations, because that’s an entire article on its own. So while this is definitely not the final word on everything related to FS19 shaders and materials, I think we did cover substantial ground when it comes to UDIM.

If you have any questions, or topics you would like to see in a future article, feel free to leave a comment.

Enjoy modding, enjoy gaming, and stay tuned for new articles!

Useful links

Cg (programming language)

Material selector for blender 2.79

Material Selector for blender 2.8-PR

ImageMagick

Texture Assemble — https://gdn.giants-software.com/download.php?downloadId=73

detailArray_extracted.zip