Model Retexturing Tutorial

From GrimWiki
Jump to: navigation, search
Model Retexturing Tutorial
Series Custom Assets
Author JohnWordsworth
Overview How to replace textures on Grimrock models to generate unique content.


This tutorial goes through the process of re-texturing a 3D model in Legend of Grimrock in order to create a custom model. Specifically, we will retexture the Ice Lizard with a red texture in order to create a new monster, the Fire Lizard.

What You Will Need

In order to work through this tutorial, you will need the following tools, or a similar alternative, on your PC.

After downloading the above tools, ensure that they are installed onto your PC and that you have extracted the Asset Pack to an easily accessible directory. For the purposes of this tutorial, the asset pack is installed in E:\Modding\Grimrock\AssetPackV2\.


3D Models for use in the Legend of Grimrock are stored in a Grimrock specific file format and end with the file extension .model. These files contain mesh data, bone data and the name of the material to apply to each part (segment) of the objects that make up that model file. The materials themselves are defined in .lua files, and the game engine reads these .lua files and matches up the relevant material definition and the names of the materials in the .model files to figure out which textures to apply to a .model file opened with the game. While this sounds complicated, it's easier when you see it in action, so lets get to it.

Creating a New Dungeon

The first thing you will need to do is create a new dungeon for Legend of Grimrock using the Dungeon Editor. If you already have a new Dungeon that you are working on then you can skip this step.

Launch the Dungeon Editor by running Legend of Grimrock and clicking "Dungeon Editor" in the main menu. From here, open a dungeon you have been working on or create a new one by clicking "File -> New Project". Enter a Dungeon Name and your name as the Author, and you're ready to go. A new Dungeon should appear as a simple room with a torch.

Duplicating Existing Content

Grimrock Model Toolkit settings to enable the previewing of textures in the toolkit.
Original Ice Lizard asset rendered in the Grimrock Model Toolkit.

First of all, we will simply explore the existing content so that we can see all of the elements that make up the model we are going to re-texture.

Launch the Grimrock Model Toolkit from your Start Menu. Before we can preview Grimrock Models with textures, we need to tell the Model Toolkit where to look for textures. As the textures that come packaged with the game are packed away in a .dat file, we will point the Toolkit at the extracted assets directory to find textures. Click on Tools -> Settings to bring up the Settings dialogue. Set the Asset Pack Directory to E:\Modding\Grimrock\AssetPackV2\assets\, or whichever directory you have extracted your asset pack to. You should also set the Dungeon Path to <MyDocuments>\Almost Human\Legend of Grimrock\Dungeons\<Dungeon Name>\. This will allow the Model Toolkit to find your new texture when you have made them.

Now click on File -> Open and browse to E:\Modding\Grimrock\AssetPackV2\assets\models\monsters\ and open ice_lizard.model. You should see the Ice Lizard rendered on a White Grid with the traditional, blue Ice Lizard texture. The files in question that make up the Ice Lizard and are relevant to this tutorial are:

Asset Path Description
<AssetPack>\assets\models\monsters\ice_lizard.model The 3D Model which contains the mesh vertices, texture mapping, vertex normals, bump mapping and material parameters.
<AssetPack>\assets\scripts\materials.lua This file describes all materials in the game, we're only interested in the ice_lizard material block however.
<AssetPack>\assets\textures\monsters\ The diffuse texture, which contains the colour information of the model.
<AssetPack>\assets\textures\monsters\ The specular texture, which describes how specular lighting should be applied to the model.
<AssetPack>\assets\textures\monsters\ The normal texture, which describes how bump mapping should be applied to the model.

Copy and rename these files into your mod_assets directory of your new dungeon, as shown in the table below. All assets stored in this directory will get packaged with your mod when you prepare it for Steam or the Mod Nexus.

Asset Pack Path Renamed Mod Path
<AssetPack>\assets\models\monsters\ice_lizard.model <Dungeon Folder>\mod_assets\models\fire_lizard.model
<AssetPack>\assets\textures\monsters\ <Dungeon Folder>\mod_assets\textures\

We don't need to copy and rename the materials.lua, because your mod will already have a materials.lua into which we can add the new material definition later. We also don't need to copy the specular and normal maps for the model, as we will be using the originals of those from the Ice Lizard. If, however, you also wanted to change how the light reflects off of the surface of the lizard (say, you were adding some scars or some other graphical features that might imply a different surface bumpiness) then you would also want to copy the Specular and Normal maps at this point.

Creating the Fire Lizard Texture

Fire Lizard diffuse texture after changing the Hue and Saturation of the Ice Lizard texture.
DDS Export settings using the GIMP DDS Plugin.

Next up we're going to open our texture in GIMP and work on making our Fire Lizard look dangerous. Open GIMP and open "<Dungeon Folder>\mod_assets\textures\". Untick "Load Mipmaps" from the Load DDS dialogue.

We will just do a simple re-colour of the diffuse texture in this tutorial, so that this tutorial doesn't veer off into a tutorial about generating specular and normal textures. If we simply recolour the diffuse texture, then the current specular and normal textures should provide a pleasing result, as we are not changing the 'bumpiness' of the object or how we want lighting to reflect off of it.

So, we will use the Colors -> Hue-Saturation dialogue. Click on the 'Master' button, so that we are modifying the whole palette of colours and then set Hue to 160 and Saturation to 40. The skin should now be a nice fiery red.

Now you will need to export your new texture as a dds file. You can overwrite and should save with the following settings:

  • Compression: BC1 / DXT1
  • Generate MipMaps: Ticked

The compression option determines how your texture is saved. BC1/DXT1 is an efficient format which is good for textures that have no transparency. If your texture had transparent parts to it (such as some of the dangling parts of the Herder), then you would want to use BC3/DXT5, which supports an alpha channel. This will make your file bigger however, so you should only use it if you need transparency.

Your file should now be compressed and ready to loaded onto a DirectX compatible graphics card.

Creating the Fire Lizard Material

Now that we have a selection of texture files, we need to tell Grimrock how to tie them all together and how they relate to the models in the game. Open <Dungeon Folder>\mod_assets\scripts\materials.lua in a text editor such as Notepad++. We are going to create a material definition as described in the Materials section of the Asset Definition Reference.

Enter the following entry into materials.lua;

	name = "fire_lizard",
	diffuseMap = "mod_assets/textures/fire_lizard_dif.tga",
	specularMap = "assets/textures/monsters/ice_lizard_spec.tga",
	normalMap = "assets/textures/monsters/ice_lizard_normal.tga",
	doubleSided = false,
	lighting = true,
	alphaTest = false,
	blendMode = "Opaque",
	textureAddressMode = "Wrap",
	glossiness = 65,
	depthBias = 0,

The above definition creates a new material. There are a few notes of importance with these material definitions:

  • name: The name must be unique, unless you want to override a default material used by other models. "fire_lizard" is a safe name, but if you are unsure, you might want to prefix it with a few characters, like "jw_fire_lizard".
  • diffuseMap: Note that the file names listed here end with .tga, even though the game expects files of the .dds file type using the .dds extension.
  • specularMap/normalMap: Notice here that we are referencing the original assets that are bundled with Grimrock here, as we have not changed them. You can reference all assets packaged with grimrock when defining/cloning objects/materials in Lua by starting your string with "assets/".

Save the file, and if you still have the dungeon editor open, click "File -> Reload Project" to reload the materials.lua. If there is a syntax error in the file, you will be notified at this point. Otherwise, the process will be silent.

Creating the Fire Lizard Model

Fire Lizard in the Grimrock Model Toolkit after using the Material Replace tool.

Ok, we are almost there now. Next up, you just need to tweak the model file so that it references the new material instead of the old ice lizard material. Launch the Grimrock Model Toolkit and open fire_lizard.model from your dungeon's mod assets folder. You should see a blue-textured Ice Lizard in the middle of the screen.

Next click on Tools -> Material Find / Replace. This dialogue box scans through the mesh data for all material names and allows you to change the name of the material applied to specific parts of the model. There is only one material listed for the Ice Lizard, 'ice_lizard'. Select ice_lizard from the existing material name dropdown and then type 'fire_lizard' into the New Material Name box. This will replace references in the model file of the material ice_lizard to fire_lizard.

Close the dialogue and click "Tools -> Reload Material Library". The lizard should now turn a fearsome read colour! Finally, save this new fire_lizard over the existing fire_lizard.model file in your dungeon's mod assets directory.

Adding the Fire Lizard to the Game

There's just one more step to complete - adding the Fire Lizard to the game. In order to add the Fire Lizard to the game, you need to define a new monster for the Dungeon Editor to place. Edit "monsters.lua" with NotePad++ or your favourite text editor in <Dungeon Name>\mod_assets\scripts\monsters.lua.

	name = "fire_lizard",
	baseObject = "ice_lizard",
	model = "mod_assets/models/fire_lizard.fbx",
	health = 900,
	immunities = { "fire" },

The above script defines a new class of monster in the game, the Fire Lizard. After adding the above script to your monsters.lua file, head back to the Dungeon Editor and click "File -> Reload Project" to re-load the new objects you have described in the .lua files. You should now be able to search for the monster fire_lizard in the left hand panel and add them to your Dungeon!

Fire Lizard in the Dungeon Editor.