Re: Legend of Grimrock 1 Modding
Posted: Fri Oct 06, 2023 6:34 pm
Creating Custom Assets
Using customized assets opens Legend of Grimrock for more in-depth modding than is possible by just using the Dungeon Editor. Using existing Grimrock assets as the basis and changing a few parameters to come up with new item or monster variants is relatively straightforward to do but if you want to take full advantage of the system it is possible for you to use your own graphics, animation and audio for creating a dungeon crawl experience that will look and sound completely different to Legend of Grimrock.
When you create a new project in the dungeon editor, a few folders and .lua files are created into the project’s location. Any .lua, .model, .dds, .animation, .wav or .ogg files within these folders will be packaged along with the dungeons when you export from the Dungeon Editor. Custom assets are defined using .lua scripts and the init.lua (under “mod_assets\scripts\” subfolder) will always be run when the custom dungeon is started. To refresh the changes made to these files, you can reload them in the editor from the File-menu using “Reload Project”. By default the init.lua will import a few other scripts (such as items.lua, monsters.lua as well as standard_assets.lua which contains all the original Legend of Grimrock assets) which serve as the basis for adding your own custom assets.
Note that any new graphics you add to your custom dungeon will consume extra memory so if you have a total conversion mod that doesn’t use any of the original Legend of Grimrock assets, it can be a good idea to comment out the line which imports the standard assets.
Defining a New Item
Let’s start off with something simple by cloning a pre-existing Legend of Grimrock asset. Let’s open the items.lua (which can be found under the project’s scripts subfolder) with a text editor and start off with a pre-existing weapon that we will modify slightly to get a new asset so that we can get familiar with how custom assets are handled. Let’s add the following to items.lua:
Using the cloneObject-function we can take an existing asset, in this case the machete, and create a new asset with new or changed parameters. Any parameters that we don’t define in cloneObject will be left in its original shape. For instance, we didn’t define a weight parameter so our new asset will still weight as much as the original asset did. So, let’s go through the changes we made to the original machete to come up with our new super cool super machete item!
Probably the most essential change to the parameters we made was the name: if we would have retained the original machete name, this item definition would have overridden the original machete item (which is completely fine if that is what you want to do). By changing the name to super_machete, we now have a new asset type instead which will show up in the Dungeon Editor’s asset browser after saving the .lua file and loading the project in the editor. The name parameter is only visible to the modder and the player will only ever see the uiName. You can safely change the uiName at any time but a little more consideration is needed if you want to change the name itself since the dungeon refers to the items by using this name and the dungeon (or its save games) won’t work if the objects spawned into it are not found.
To differentiate the super machete from the normal one, we increased its attack power and added the damageType = "shock", line to turn the damage dealt by the machete into electrical attacks. I also added a description for extra flavor. If you’re curious about what kinds of parameters you can add to items, or to the other assets, they can all be seen in the asset definitions reference. Of course, there’s nothing stopping you from completely changing the parameters of the object or even turning it into a magical staff or a food item but at that point it would be wise to change the graphics too which we will detail in the following guides.
Using Custom Graphics
Graphics in Legend of Grimrock come in a few different flavors. There’s 2D graphics, such as images for cinematics or item icons and then there’s 3D graphics that are used for item meshes, environment objects and monsters. 2D graphics are the more simple case by a wide margin so let’s start off with them.
2D graphics in Legend of Grimrock use DDS (DirectDraw Surface) format which can be saved from Photoshop and GIMP by using 3rd party plug-ins. Standalone converters are available as well. DDS supports compression which is recommended for textures that will be used on 3D models (use D3DFMT_DXT1 for textures without alpha and D3DFMT_DXT5 for textures with alpha) but user interface graphics, such as item icons, should be left uncompressed (use D3DFMT_A8R8G8B8). Mipmaps should be used with all textures and the dimensions of the textures should be to the power of two (16, 32, 64 …) to ensure compatibility.
Let’s say we want to introduce some new item icons in the game. A single item icon is 75*75 pixels in size but we can keep several icons in a single texture (called an atlas texture). Thus, a 512*512 atlas texture, for example, can contain a grid of 6*6, or a total of 36, item icons in it as illustrated by the template image on the right (notice that there is also some padding on the edges since the size of 75 does not divide evenly to fill out the entire 512*512 texture). The item texture also needs an alpha channel for the transparency and, like mentioned earlier, the DDS should be uncompressed.
Once you have a texture with one or more icons in it, you can save the DDS to the textures-subfolder in your project folder and, for this example, let’s name the file “mod_items.dds”. Then all we need to do is to is to modify items.lua a little to make a custom item to use the new texture by adding gfxAtlas = "mod_assets/textures/mod_items.tga", to the item definition (when the gfxAtlas parameter is not defined for an item, it uses the default Legend of Grimrock item atlas). Note that forward slashes, instead of backslashes, are used in the path and that we replaced the .dds with .tga. But don’t rename the file itself: we here at Almost Human use .tga as an intermediate format (which we then automatically convert to DDS which the game engine uses) and the formatting of the item definitions follow this convention. To put it simply: keep the file as a .dds but use .tga in its stead in the item definition.
Now, since the atlas texture is sliced into grid cells of 75*75 size, we just need to pick the right index number for the icon. If you placed the icon graphics into the top left slot, its index is 0 and the slot to the right from it is 1 and so on. Once you have located the right index number, we can replace the number for the gfxIndex parameter in the item definition and now everything should be in place and the new icon is good to go.
3D objects
3D objects in Legend of Grimrock are built out of a few components: a 3D model, material definitions and (optionally) animations. The models and animations use custom file formats (.model and .animation) and we don’t provide exporters for these files (since there are just too numerous software packages out there for us to support) but instead, we provide the specifications for these formats that should enable the community to create plug-ins or converters for creating the assets. The materials for the 3D models are defined by scripting.
When creating 3D models, it is advisable to collapse the mesh into a single object unless it has animated moving parts.
The animation files are separated from the models to make it easier to update the 3D model without needing to re-export all the animations. Each animation file contains the data for a single animation only: for example monsters have separate .animation files for turning left and right and pit trapdoors have separate animations for opening and closing.
The material definitions can be made in the materials.lua script file. The materials are very simple in Legend of Grimrock:
For most assets, the only parameters you need to modify are name, texture maps and sometimes glossiness. A lower glossiness value means more diffuse/softer specular highlights and higher values produce more glossy/sharper highlights and the values we used were usually in the range of 20-80. The specular map, however, is more important for the overall feel of the material: this texture defines the amount of specular as well as its color (if you want to make the whole object less shiny overall, just make the texture darker). You can also leave any of these textures undefined (just delete or comment out the line). Leaving a diffuse or specular map undefined produces the same result as using a blank white texture. For materials with alpha, it is recommendable to use alpha test (also known as “alpha clip”) since alpha blend is not lighted correctly and therefore the material may appear too bright in dark surroundings.
These materials are referred by their name from models/meshes and there can be more than one material per object. In our pipeline we defined the materials by using material names in the 3D modeling software (so if I would have defined the polygons in my object to use a material with the name “moose”, a material definition of the same name would be used from materials.lua in the game) but the exact way how materials are assigned may vary depending on how the exporters or converters will handle it. It is also possible to override materials that the standard assets use (just define a new material with the same name) so if you want to create an albino snail, it is possible to do it without touching the 3D model itself.
Probably the easiest approach to getting started in creating new assets that use new 3D objects would be to take a pre-existing asset definition from the Legend of Grimrock asset pack and to start replacing its models and animations in its definition with new files one by one and checking that it still works after each new addition.
Note that in the asset definitions you frequently need to refer to asset names using .tga or .fbx file extensions even though your files actually need to actually have .dds, .model or .animation file extensions. Tga and fbx are intermediate formats we use here with our asset pipeline and the asset definition file names follow this convention. So you shouldn’t rename your actual files as .tga or .fbx but in the asset definitions you need to replace any .model with .fbx and any .dds with .tga. It’s a little counterintuitive but the system was built on how our in-house asset pipeline and automatic asset conversion system works.
Audio
When creating custom sounds, care needs to be taken when choosing the correct formats. The looping background soundscape is an .ogg-file but all the other samples are 16bit 44100Hz .wav-files. You need to be careful that you use the correct sampling rate and bit depth since other values might work on your computer but not on other platforms.
When creating sounds that are played from the 3d environment (like monsters or spells), the samples need to be mono so that they can be panned correctly according to the position of the source of the sound. Sounds for things that do not come from the environment, such as interface sounds etc., can be in stereo.
Using customized assets opens Legend of Grimrock for more in-depth modding than is possible by just using the Dungeon Editor. Using existing Grimrock assets as the basis and changing a few parameters to come up with new item or monster variants is relatively straightforward to do but if you want to take full advantage of the system it is possible for you to use your own graphics, animation and audio for creating a dungeon crawl experience that will look and sound completely different to Legend of Grimrock.
When you create a new project in the dungeon editor, a few folders and .lua files are created into the project’s location. Any .lua, .model, .dds, .animation, .wav or .ogg files within these folders will be packaged along with the dungeons when you export from the Dungeon Editor. Custom assets are defined using .lua scripts and the init.lua (under “mod_assets\scripts\” subfolder) will always be run when the custom dungeon is started. To refresh the changes made to these files, you can reload them in the editor from the File-menu using “Reload Project”. By default the init.lua will import a few other scripts (such as items.lua, monsters.lua as well as standard_assets.lua which contains all the original Legend of Grimrock assets) which serve as the basis for adding your own custom assets.
Note that any new graphics you add to your custom dungeon will consume extra memory so if you have a total conversion mod that doesn’t use any of the original Legend of Grimrock assets, it can be a good idea to comment out the line which imports the standard assets.
Defining a New Item
Let’s start off with something simple by cloning a pre-existing Legend of Grimrock asset. Let’s open the items.lua (which can be found under the project’s scripts subfolder) with a text editor and start off with a pre-existing weapon that we will modify slightly to get a new asset so that we can get familiar with how custom assets are handled. Let’s add the following to items.lua:
Code: Select all
cloneObject{
name = "super_machete",
baseObject = "machete",
uiName = "Super Machete",
attackPower = 12,
damageType = "shock",
description = "This machete radiates with strange energy.",
}
Probably the most essential change to the parameters we made was the name: if we would have retained the original machete name, this item definition would have overridden the original machete item (which is completely fine if that is what you want to do). By changing the name to super_machete, we now have a new asset type instead which will show up in the Dungeon Editor’s asset browser after saving the .lua file and loading the project in the editor. The name parameter is only visible to the modder and the player will only ever see the uiName. You can safely change the uiName at any time but a little more consideration is needed if you want to change the name itself since the dungeon refers to the items by using this name and the dungeon (or its save games) won’t work if the objects spawned into it are not found.
To differentiate the super machete from the normal one, we increased its attack power and added the damageType = "shock", line to turn the damage dealt by the machete into electrical attacks. I also added a description for extra flavor. If you’re curious about what kinds of parameters you can add to items, or to the other assets, they can all be seen in the asset definitions reference. Of course, there’s nothing stopping you from completely changing the parameters of the object or even turning it into a magical staff or a food item but at that point it would be wise to change the graphics too which we will detail in the following guides.
Using Custom Graphics
Graphics in Legend of Grimrock come in a few different flavors. There’s 2D graphics, such as images for cinematics or item icons and then there’s 3D graphics that are used for item meshes, environment objects and monsters. 2D graphics are the more simple case by a wide margin so let’s start off with them.
2D graphics in Legend of Grimrock use DDS (DirectDraw Surface) format which can be saved from Photoshop and GIMP by using 3rd party plug-ins. Standalone converters are available as well. DDS supports compression which is recommended for textures that will be used on 3D models (use D3DFMT_DXT1 for textures without alpha and D3DFMT_DXT5 for textures with alpha) but user interface graphics, such as item icons, should be left uncompressed (use D3DFMT_A8R8G8B8). Mipmaps should be used with all textures and the dimensions of the textures should be to the power of two (16, 32, 64 …) to ensure compatibility.
Let’s say we want to introduce some new item icons in the game. A single item icon is 75*75 pixels in size but we can keep several icons in a single texture (called an atlas texture). Thus, a 512*512 atlas texture, for example, can contain a grid of 6*6, or a total of 36, item icons in it as illustrated by the template image on the right (notice that there is also some padding on the edges since the size of 75 does not divide evenly to fill out the entire 512*512 texture). The item texture also needs an alpha channel for the transparency and, like mentioned earlier, the DDS should be uncompressed.
Once you have a texture with one or more icons in it, you can save the DDS to the textures-subfolder in your project folder and, for this example, let’s name the file “mod_items.dds”. Then all we need to do is to is to modify items.lua a little to make a custom item to use the new texture by adding gfxAtlas = "mod_assets/textures/mod_items.tga", to the item definition (when the gfxAtlas parameter is not defined for an item, it uses the default Legend of Grimrock item atlas). Note that forward slashes, instead of backslashes, are used in the path and that we replaced the .dds with .tga. But don’t rename the file itself: we here at Almost Human use .tga as an intermediate format (which we then automatically convert to DDS which the game engine uses) and the formatting of the item definitions follow this convention. To put it simply: keep the file as a .dds but use .tga in its stead in the item definition.
Now, since the atlas texture is sliced into grid cells of 75*75 size, we just need to pick the right index number for the icon. If you placed the icon graphics into the top left slot, its index is 0 and the slot to the right from it is 1 and so on. Once you have located the right index number, we can replace the number for the gfxIndex parameter in the item definition and now everything should be in place and the new icon is good to go.
3D objects
3D objects in Legend of Grimrock are built out of a few components: a 3D model, material definitions and (optionally) animations. The models and animations use custom file formats (.model and .animation) and we don’t provide exporters for these files (since there are just too numerous software packages out there for us to support) but instead, we provide the specifications for these formats that should enable the community to create plug-ins or converters for creating the assets. The materials for the 3D models are defined by scripting.
When creating 3D models, it is advisable to collapse the mesh into a single object unless it has animated moving parts.
The animation files are separated from the models to make it easier to update the 3D model without needing to re-export all the animations. Each animation file contains the data for a single animation only: for example monsters have separate .animation files for turning left and right and pit trapdoors have separate animations for opening and closing.
The material definitions can be made in the materials.lua script file. The materials are very simple in Legend of Grimrock:
Code: Select all
defineMaterial{
name = "spider",
diffuseMap = "assets/textures/monsters/spider_dif.tga",
specularMap = "assets/textures/monsters/spider_spec.tga",
normalMap = "assets/textures/monsters/spider_normal.tga",
doubleSided = false,
lighting = true,
alphaTest = false,
blendMode = "Opaque",
textureAddressMode = "Wrap",
glossiness = 40,
depthBias = 0,
}
These materials are referred by their name from models/meshes and there can be more than one material per object. In our pipeline we defined the materials by using material names in the 3D modeling software (so if I would have defined the polygons in my object to use a material with the name “moose”, a material definition of the same name would be used from materials.lua in the game) but the exact way how materials are assigned may vary depending on how the exporters or converters will handle it. It is also possible to override materials that the standard assets use (just define a new material with the same name) so if you want to create an albino snail, it is possible to do it without touching the 3D model itself.
Probably the easiest approach to getting started in creating new assets that use new 3D objects would be to take a pre-existing asset definition from the Legend of Grimrock asset pack and to start replacing its models and animations in its definition with new files one by one and checking that it still works after each new addition.
Note that in the asset definitions you frequently need to refer to asset names using .tga or .fbx file extensions even though your files actually need to actually have .dds, .model or .animation file extensions. Tga and fbx are intermediate formats we use here with our asset pipeline and the asset definition file names follow this convention. So you shouldn’t rename your actual files as .tga or .fbx but in the asset definitions you need to replace any .model with .fbx and any .dds with .tga. It’s a little counterintuitive but the system was built on how our in-house asset pipeline and automatic asset conversion system works.
Audio
When creating custom sounds, care needs to be taken when choosing the correct formats. The looping background soundscape is an .ogg-file but all the other samples are 16bit 44100Hz .wav-files. You need to be careful that you use the correct sampling rate and bit depth since other values might work on your computer but not on other platforms.
When creating sounds that are played from the 3d environment (like monsters or spells), the samples need to be mono so that they can be panned correctly according to the position of the source of the sound. Sounds for things that do not come from the environment, such as interface sounds etc., can be in stereo.