• Please note that we've updated the Mount & Blade II: Bannerlord save file system which requires you to take certain steps in order for your save files to be compatible with e1.7.1 and any later updates. You can find the instructions here.

[Tutorial (Unfinished)] Mastering your tools: managing resources with OpenBRF

Users who are viewing this thread


Grandmaster Knight
Hello everyone, I am Maroon, one of the main developers of Full Invasion over the past few years. In my modding endeavours I have mainly focused on optimisation and the correct implementation of resources in a mod.
In this tutorial I will be sharing the knowledge I have gathered over the years, to fully explain those parts of Openbrf that are a bit less obvious. As Openbrf is a very versatile tool, I will cover a lot of topics, from the usage of vertex colouring, to the proper way to use shaders and flags, to keeping your resources manageable, to setting up vertex animations, and more.
Note: I will not be covering the very basics of using Openbrf, as that would add a lot of content to this already very lengthy tutorial. For a more basic tutorial, look at the main Openbrf download page.

Another note: this tutorial is far from finished. There are a lot of options that Openbrf provides that I have not yet covered, but writing this tutorial takes a long time, and I want to share what I've already written with the community. Expect updates and expansions to the tutorial in the future.

[anchor=top]Table of contents[/anchor]
  • Chapter 1: Meshes
    • Cleaning redundant data from meshes
    • Vertex Coloring
    • Ambient Occlusion through Vertex Colouring
  • Chapter 2: Materials
    • Setting up a Material
    • Using the correct shader
    • Using the Specular Settings
    • Material Flags
  • Chapter 3: Module management
    • Show unreferenced texture files
    • Efficiently move textures between modules

[anchor=C1]Chapter 1: Meshes[/anchor]

[anchor=C1C]Cleaning redundant data from meshes[/anchor]
Free optimisation of mesh data

One of the most important and often overlooked features of Openbrf is the cleaning of meshes. During the exporting and importing of meshes from editors and converters to Openbrf, there's a fair chance that the conversion of the original mesh data to an .obj file has created some redundant data. Openbrf has an automatic function that checks for such redundancies, and removes them without editing the way the mesh looks.
One such a conversion issue that can pop up can be seen by looking at the faces, vert, and pos values in the mesh's data field. In basically all meshes, these three values should be unique. Sometimes after importing a mesh, however, you may find that the vert and pos values are identical. This should not be the case, and this can be resolved.
The clean-up function can be found when you right-click a mesh, and is called "Clean redundant vert/pos". Selecting this option automatically removes all redundant data from the mesh, reducing your file size, and reducing the impact the mesh has on the performance of your mod, without any visual degradation.

[anchor=C1A]Vertex Colouring[/anchor]
Creating color variations without adding textures

A little used feature of Openbrf is the option to add a layer of colour over your mesh, creating a very different look with the click of a button. This process is called "Vertex colouring". Vertex colouring essentially tells the game "on this vertex of the mesh, overlay the mesh with this colour". This can be used to create colour variations of a mesh, with almost no additional cost to your mod's size, as you don't need a new texture for it!
Here's an example. This is a simple white hood:
When right-clicking on the mesh, you will see the option to "Colour Uniform...". This opens the following menu:
Here you can pick a colour to overlay on the mesh, and when you click "OK":
Bam! Now we have a whole new colour on the mesh. Better yet, it still uses the same material as before, so no new textures are needed. If you want to, you can tweak the vertex colour more by right-clicking on the mesh and selecting the "Tune Colours HSB..." option.
If we use this option several times, we can get a bunch of variations that all use the same base texture:

[anchor=C1B]Ambient Occlusion through Vertex Colouring[/anchor]
Creating shadows without shaders

A different way to use vertex colouring is to use it to create a form of Ambient Occlusion. Ambient Occlusion (AO) is a technique that calculates how exposed to ambient lighting each part of a mesh is. This is especially useful in scene prop meshes, to create dark corners where it makes sense to have them. Ambient Occlusion can help make a prop feel more realistic and alive. Luckily for us, OpenBRF has an option to automatically calculate the AO values of a mesh and store them as vertex colour values.
Let's have a look at another example. This is a wall from the OSP mod Crusader's Way to Expiation:
As you can see, all parts of the prop are lighted equally much, even the roofed walkway that's tucked way more into a corner. If we right-click on the mesh, and select the option "Color with Ambient Occlusion", OpenBRF does its magic, and shows us:
A new version of the mesh with more shadows in the dark corners. If you're not quite happy with the results, you can always use the aforementioned "Tune Colors HSB..." option to tweak the results. If you are consistently dissatisfied with the results of the AO calculations, you can also edit the settings used during calculating the AO values in the Settings menu:
Though both normal vertex colouring and AO generation use vertex colouring, it is possible to apply the AO option on a vertex coloured mesh if you hold Shift while clicking on the "Colour with Ambient Occlusion" option. This "multiplies" the AO values, essentially giving your mesh the information from both options.

[anchor=C2]Chapter 2: Materials[/anchor]

Without a doubt the most overlooked yet critical part of OpenBRF is the Materials tab. Materials are used to tie textures to meshes, and define exactly how and when meshes should be rendered. Every mesh needs to have a material, as without a material they cannot have textures applied to them. Similarly, textures that are never used in a material generally go completely unused by the game (though there are a handful of exceptions, more on that later). So let's start by going over the basic options you have when setting up a material.

[anchor=C2A]Setting up a Material[/anchor]

Materials can be created in two ways: through the Import New Material option, or the Import New Texture option. Both options are found in the Import menu, where you will find the "New Material..." and "New Texture..." options. You can also simply copy and paste an existing material and edit it from there.

Linking a texture to a material is a simple step. All you need to do is enter the name of your texture in the correct field of the “Data” column of your material. You have several options here:
DiffuseA:Main texture, this is essentially a painting that’s laid over your mesh.
DiffuseB:Secondary texture, only used for facial textures.
Bump:Bump/normal map, used to add an extra depth effect to your texture.
Enviro:Environment map, used as a reflection. A handful of shaders use this map to create the illusion that the environment is reflected by the linked mesh.
Specular:Specular map, the map that determines what parts of the texture are shiny, and to what degree.

When working with a standard item, you will need at least a DiffuseA texture, a specular map if your item has metal parts in it, and usually a normal map to add extra detail to the item. DiffuseB is only ever used for facial textures, which are a completely different beast. 99% of the time this field can be ignored.

[anchor=C2B]Using the correct shader[/anchor]

Materials all require a shader to tell the game how this material should render in game. There are many options to pick from, though most can be ignored. When you make a new material, OpenBRF defaults to using the simple_shader material. If you're creating an item or prop that will be used in game, do not use this shader!. simple_shader does not use lighting at all, which means your item or prop will look very weird in game. Instead, it should only be used for UI elements, but usually you don't need to touch these.
The shader that you should be using depends on the kinds of textures your material uses. If you are making a material for items, there are three things you should look for when selecting your shader (aside from if it has a DiffuseA texture, which it should always have):
  • Is the mesh that uses this material skinned? Skinned meshes contain the information needed to tie it to a skeleton. The only skinned meshes in M&B are body armor, boots, horses, and sometimes helmets.
  • Does your material have a bump map?
  • Does your material have a specular map?
Based on these three questions, you can select a shader from the following table:
Skinned  Bump  Specular    Shader you should use

Keep in mind that these shaders are mainly used for items! Materials used for other kinds of meshes, like scene props, UI elements, flora, skyboxes, etc, use different shaders. As a rule of thumb, look through the .brf files found in the CommonRes folder for similar meshes and copy what they do. These are the meshes used by Native, and these generally are set up correctly.

[anchor=C2C]Using the Specular Settings[/anchor]

Next up in the Data column are the specular settings. These are only relevant if your material uses a specular map! If it doesn't, you can ignore these settings.
This part of the Data has four values: the first three are labeled as "Spec RGB", and the fourth is labeled as "Coeff".

The Specular RGB values determine how intense the light is that is reflected by the material. The higher the RGB values are, the more intense the reflected light is. Furthermore, giving the three fields different values changes the color of the light reflected.
Here are some examples of the same item, using the same material but with different Specular RGB values.
Here all Spec RGB values are set to 1. As you can see, hardly any light is reflected in this case
Here all Spec RGB values are set to 10. This helmet has some more reflection than the previous one, more in line with what you would expect from such a helmet in actuality:
Here all Spec RGB values are set to 30. Now the amount of light reflected is even higher, in this case probably too high:
Finally, this helmet has the R value at 30, while G and B are set to 10. In this case, the whole mesh has a more red hue when it's reflecting light:

The final value is the Coeff value, which is short for "Light Coefficient". This value determines how much light is reflected by the material, and how broad the reflection is. The higher this value is, the more concentrated the reflection is. This means that the angle at which you can see the reflected light decreases with a higher Coeff value.
Here are some more examples of different Coeff values.
This helmet has a Coeff value of 20:
This helmet has a Coeff value of 80:

Set these values to appropriate levels for the type of material your item would normally use. Generally speaking, for metal textures, setting your values around Specular RGB 10 and Coeff 20 gives you a decent result. Make sure to tweak the values a bit, as your results may vary based on the brightness of your specular map.

[anchor=C2D]Material Flags[/anchor]
Enabling and disabling features on your material

The final part of the material's Data column is the Flags field. This field is used to determine how the material is rendered by the game. The flags field has a numerical value, which is the sum of all enabled flags. If you press the ... button next to the Flags field, you will see a window open up that shows all flags that you can enable. Mousing over the options gives you a small explanation for each option, so I won't go over them here.
On a typical item, you'll see that the flags field is set to 720. This covers the most basic features a standard item (potentially) needs.
The value 720 is a sum of two enabled features: Specular enable (20), which allows the material to use the specular map (makes sense), and Auto transparency (700). Auto transparency allows the material to add transparency to your mesh if the texture used has transparency added to it. If the texture uses the transparency to cutout parts of the texture (this is often done for flora, for example), the Alpha test flag should also be set. Depending on your texture, you will want to use one of the three options available here: large margins (1000), normal margins (2000), or tight margins (3000). This changes the sum of your Flags field to 1720, 2720, or 3720.
There are a lot more options, but generally speaking you do not need to look at these. If you are creating a material that's more unique than a standard item, look up a similar material from Native and work from there.

[anchor=C3]Chapter 3: Module management[/anchor]

Another important feature in Openbrf is the management of your module at large. Openbrf provides several options to help you manage the meshes in your module, increase performance, fix bugs, and more.

[anchor=C3A]Show unreferenced texture files[/anchor]
Remove unused textures all at once

One of the module-wide options provided by Openbrf is the listing and optional removal of textures that go unused by your mod. In order to work, textures need to be found in your Textures folder, and need to be declared in one of your brf files. Openbrf has an option to scan your Textures folder, and check for texture files that are not listed in any of your brf files. These files take up space in your mod, but are never actually loaded, so they take up space without actually providing any use.
This option can be found under the Module menu, and is listed as "Show unreferenced texture files". Clicking this option lets Openbrf compute for a while, after which it spits out this window:
Openbrf then gives you the option to move all unreferenced textures to a separate folder, removing them from the main Textures folder. This makes it easy for you to remove these textures as they have been separated from the textures that are actually used by your mod. You can also use the information provided by this option to properly declare the unreferenced textures in your mod.

[anchor=C3B]Efficiently move textures between modules[/anchor]
Using the Unreferenced texture files option to isolate textures

As mentioned above, the Show unreferenced texture files moves all the unreferenced textures to a separate folder. If applied in the right way, this can also help you with another problem.
For example: you want to implement a few items from a mod that has just been turned into an OSP. The mod itself is very large, but you only want to add the items found in one of its brf files. This includes having to copy all the textures used by those specific items. However, opening the Textures folder in a file browser does not let you sort the textures by the brf file they are declared in.
This is where the aforementioned Show unreferenced texture files option comes in handy. If you first remove all the actually unreferenced texture files from the OSP mod, you can then remove the reference to the textures you want to copy from the OSP mod to have them all moved to a new folder. Here's what you do:
[list type=decimal]
[*]Go to the "Module" menu and select "Show unreferenced texture files".
[*]Wait for OpenBrf to compute the list, then select "Move all to subfolder "_unused"" to remove all unused textures that you don't want to copy.
[*]Move the _unused folder somewhere else, or remove it, rename it, anything to make it go away.
[*]Delete all the texture entries that you want to copy from the brf files they are listed in.
[*]Double-check that the same textures are not referenced in another brf.
[*]Go to the "Module" menu and select "Show unreferenced texture files".
[*]Wait for OpenBRF to compute the list, then select "Move all to subfolder "_unused""
Now all the files you want to copy are in their own little folder, allowing you to easily move them to your own mod without having to look up each file separately.

Eärendil Ardamírë

Subforum Moderator
Thanks for taking your time to write down this tutorial! I waited long for it since the first time you mentioned that you are going to write it down. And finally, it is here  :party:


Congratulations on the initiative, there are never too many tutorials and references for this great tool that left us mtarini.


Punkbuster 2.0
The final value is the Coeff value, which is short for "Light Coefficient". This value determines how much light is absorbed by the material before it is reflected. This means that the higher this value is, the less light is reflected. The angle at which you can see the reflected light also decreases with a higher Coeff value.
That's not really the case, the Coeff value just affects the reflection of the sun itself (and point lights in some cases).
The higher the value, the smaller but sharper the reflection (increases to the power of "Coeff").
No absorption is going on here.

You also should mention that skinned shader variants are only for skinned/rigged meshes.
Using them on non-rigged meshes will just add complexity and thus reducing performance.


Grandmaster Knight
_Sebastian_ said:
You also should mention that skinned shader variants are only for skinned/rigged meshes.
Using them on non-rigged meshes will just add complexity and thus reducing performance.
I believe the first "question" of that table covers that. If it's unclear I'll try to reword it.

_Sebastian_ said:
That's not really the case, the Coeff value just affects the reflection of the sun itself (and point lights in some cases).
The higher the value, the smaller but sharper the reflection (increases to the power of "Coeff").
No absorption is going on here.
Thanks, reworded that bit!


Grandmaster Knight
Are there any requests for specific sections I should focus on before I start writing the next bits? Also nice to finally hear that this really does come at the tail-end of the usefulness of Openbrf now that Bannerlord is actually close :sad:


Grandmaster Knight
Antonis said:
""""close""""  :razz:
Sure, it'll probably be another 2 years before we get our hands on the modding tools, but I don't think there will be very many people left working on new Warband mods in the meantime now that we actually have an idea of a timeline. Either way, I'm glad to have put this out here!


hey there im using your tutorial to attempt to transfer items from one mod to another. i am very close. i get a message that says "unable to find mesh" when i pull out the weapon. ive checked the mesh name its the same everywhere.

Eärendil Ardamírë

Subforum Moderator
poohbear3499 said:
hey there im using your tutorial to attempt to transfer items from one mod to another. i am very close. i get a message that says "unable to find mesh" when i pull out the weapon. ive checked the mesh name its the same everywhere.
Make sure you use exactly the same big and little letters, it's case sensitive. And make sure that your brf is getting loaded in module.ini
Top Bottom