Blender

Blender is an open source 3D content creation suite that has built-in support for the file format COLLADA that the HPL engine uses to import most 3D models.

When it comes to working with HPL, Blender works best with models without an armature. As of now, there is no known and tested way to properly export armatures from Blender in a way for HPL to read them properly. For a potential fix (untested on newer releases), check "Notes on 2.6".

Tutorial - Blender 2.8

The following applies both to new models and edits of existing models. When importing a .dae model from any FG game, one has to reconstruct the materials - for some reason, they aren't imported into Blender.

1. Make sure that your model has unwrapped UVs. Alternatively, you can unwrap your model after adding the texture.
2. Very important! HPL* doesn't like when there are orphaned textures and materials. Be very careful not to add any unnecessary ones, because it will cause problems later.
3. Also keep in mind that HPL allows only one material with one texture per mesh (object). No more, no less.
4. Select your mesh and go to the materials tab.
5. Make sure that the shader is set to Principled BSDF. Other shaders can cause issues with texturing the model in the game.
6. Click on the circle next to the “Base Color” setting.
7. Pick “Image Texture” from the pop-up menu.
8. Click on “Open” and pick your texture file.
9. From now on, if you need to open the texture somewhere (e.g. for UV unwrapping), click on the square icon with a triangle and a dot and select the texture from the drop menu. This way you won't be cloning the texture. If you need to apply the created material/texture to another object or reapply it to the current one, make sure to use this method as well.
10. Before exporting, make sure to remove all non-mesh components, like lights and cameras, as well as unused textures, materials and images. This is most easily done in the tree viewer, after setting it to the "Blender file" mode. Make sure to delete the duplicate and orphaned data as well if there are any issues.
11. Make sure that in export settings the “Geometry→Triangulate” option is marked. You might also need to set the up axis to be the Y axis (Blender uses Z as up and HPL uses Y). In case that doesn't work, you can rotate the model manually to have +Y axis as up and to face the correct axis. You can also see notes on Blender 2.5 for another potential solution.
12. Open the exported file with the ModelViewer. If you've succeeded, the model will show up as textured. A .mat file will be created, to which you can add normalmaps and such. If you were editing an existing model, it should load the existing material from the original model.
    • If the viewer crashes, you probably didn't assign materials properly or didn't triangulate the model. Another cause could be that the "one material per object, one texture per material" rule wasn't followed.
    • If the model isn't textured correctly, you probably have redundant images and/or materials in the blend file.

PS. As of yet I haven't found a way of properly exporting animations from Blender. I've tried multiple COLLADA plugins and countless export settings (including a completely different format - .fbx). Following this tutorial will make the animated model load in-game, but most likely the armature will have errors and the animation will be corrupted. Perhaps applying the fix mentioned in the Blender 2.6 section could help.

*This tutorial is applicable both for HPL1 and HPL2. HPL3 was not tested but most likely will work as well.

Important information about images

Textures(.dds, .jpg. tga and other general image formats) and material files(.mat, the engine specific file) - The material file is an XML file that contains information on what images is used in the material to create the texture and other properties. When the game loads a 3D model it searches for the name of the image used as a texture for the model(the .dds etc) and then replaces that name with the extension .mat to know what material file to use. Because of this it is important that the texture used has the same name as the material file, with the exception of the extension.

Example: your model uses texture.dds. The game will look for texture.mat, and if it's not found, it will try to create one and load texture.dds into the material file.

Blender to COLLADA to HPL - additional info

This section was written by yasar11732 in forums.

First thing to take into account when exporting is, correctly U.V mapping the texture. Adding texture to material without U.V mapping will NOT work, it will just crash your model viewer.

Also, before adding texture to your models, save your model (blender file) to where textures resides (It is better if they all in one place). And use relative paths when adding textures instead of absolute paths, then export your .dae to same place. So that you can easily port your models from one place to another (Always keep .dae and textures together). If you don't do that, you will probably fail at some point when trying to move your models from one place to another.

Sometimes, when you export your model and see it in model viewer, you may see that texture is shown “inside” of the model, not the outside (look really weird)! That is because normals of your model is mixed up. You should go back to blender and flip the normals and export again. This should solve your problem.

And also, one should remember always to use textures with sizes of exponents of 2 (256×256, 512×512, 128×1024 etc.). Otherwise it will either crash your model viewer, look awkward or result in run-time errors and worse performance.

One last point to remember is that, materials you create might be mixed up when you create it and one material accidentally get linked against 2 different geometries (or datablocks, or vertex groups… whatever one calls it). If this happens without proper care (accidentally), your model will not export correctly.

You can export rotation/location/scale animations without problem, however, I couldn't export shape animations correctly into .dae format. If anyone can do it and post the method, it would be great to learn about it.

And also, do not try to export armature/bones, because as far as I can say, that doesn't work either. If someone could do it, I also want to hear about how to do it.

Notes on Blender 2.5

When exporting to .dae, there will be a few issues you may notice upon importing your work into the Model Editor of Amnesia. These issues include your model appearing to be missing “pieces,” being incomplete and full of holes. The COLLADA plug-in of Blender 2.5 automatically exports everything as triangles. When it comes to converting quads (i.e. faces with four sides) it does a bad job at it. In Blender 2.5, when you convert a quad into a triangle (Ctrl + T) you'll notice the quad becomes two triangles forming a shape of a quad. However, the COLLADA plug-in when it faces a quad and converts it to a triangle it'll only provide one triangle in the place of the quad (or screw up the vertices of the second triangle). To avoid this issue, you must convert all your quads to triangles in Blender before exporting to .dae format.

Another issue you might run across is when you import your mesh into the Model Editor of Amnesia you notice that your object(s) are rotated (though in Blender it looks perfectly fine). This is caused by the local axis of the object(s) conflicting with the global axis of the environment. To fix this, in Blender, in Object mode, select the object you want to correct and in the menu on the bottom of the 3D View go to Object > Apply > Rotation. This will align the local axis of the object to the global axis of the object. Now when you import your mesh again in the Model Editor everything will be on their proper axis. Do the same for location and scale if need be.

Exporting of object names is also not currently supported in Blender 2.5. This may cause some issues when creating your own entities from your custom models. When attaching a body to your model in the Model Editor of Amnesia and the object doesn't have a name, the game will not be able to properly attach the model to the body. This may result in half of the model located at the exact center of the map, while another part having been properly attached to the model's body. The current workaround is to edit the .dae file and manually add names to your meshes. Under <library_visual_scenes>, each mesh from your model will be represented by a node tag. Simply edit the node tag by adding a name attribute with the value being the object's desired name.

For example:

<node id="Cube" type="NODE" name="Cube">

There are also issues with armatures, but full armature export support is scheduled for Blender 2.6.

Notes on Blender 2.6

Blender 2.6 is capable of exporting armatures to where the ModelView and Model Editor doesn't crash; however, this only after one minor tweak to the exported .dae file. It would appear that the HPL engine is not capable of finding the bones of the controller (armature) when they are parented to an armature node in the .dae file. Current workaround is to either remove the armature parent node or change its type from “NODE” to “JOINT”. Do note, though, that this only prevents the ModelView from erroring out with “Bone '%s' does not exist;” there is no guarantee that your model will look and work exactly as it does in Blender.

As of Blender 2.64 you no longer have to insert a name attribute to the node element (as shown in the notes for Blender 2.5).

As of Blender 2.68 (probably earlier), you no longer need to triangulate the mesh in edit mode before exporting. There is now a triangulate option in the COLLADA export options.

Blender armatures (though not for really complex rigs) and their animations now work with the Machine for Pigs update. (This was tested with Blender 2.68, but earlier versions may work too.)

Deprecated tutorial

Note: After the major UI rehaul of Blender 2.8, this tutorial has been deprecated. However, it is kept here in order to preserve and useful information that might help despite that.

The following is intended to quickly give a sure step by step process to successfully export an object and get it to display within the game engine:

1. When Blender launches it creates a default cube.
2. Save the Blender project (Ctrl + S; File → Save).
3. Select the default cube and click on the Materials button in the Properties panel. Make sure a material is applied to the mesh (default material will work fine).
4. Click on the Textures button in the Properties panel. If there is no texture applied to the material, click on New or the default texture from the list if any. Set Type to Image or Movie, and in the Image menu click Open and select a texture (the .dds/.jpg/.tga/.png not the .mat file). It is best if the texture is in the same directory as the .blend file. In the Mapping menu, make sure UV is set for Coordinates.
5. With the cube selected, press TAB to go to Edit Mode. Make sure all the faces of the mesh is selected. You can do so by pressing A on the keyboard. Press U on the keyboard and select Unwrap (Reset if you haven't created seams for the default cube).
6. With all the faces still selected, convert all quads to tris either by Ctrl + T or Mesh → Faces → Quads to Tris.
7. Go to the UV/Image Editor and in the pop-up menu to the right of the UVs menu, select the previously loaded texture from the list.
8. Go back to 3D View, change draw mode (i.e. Viewport Shading) to Textured and you can see that the model is textured. You'll know it is ready for exporting if both Textured draw mode and the rendered image both show the cube textured.
9. Delete the default camera and default light.
10. Go to File → Export → COLLADA (.dae). In the left panel, at the bottom, there will be export options for COLLADA, specifically texture options. If you're using external textures, then you'd want to make sure Include UV Textures is checked. If you're using internal textures, then you'd want to make sure Include Material Textures is checked. If you want to copy (or overwrite) the textures over to the save location (this should be done at least once), make sure Copy is checked.
11. Save the file as “filename.dae” in a folder within one of Amnesia's directories (preferably the custom_stories directory).
12. Using the model viewer you should now see the newly created cube fully textured.