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.

Unlike Maya, models exported from Blender don't require deprecated versions of the software to work with HPL. However, this is at a cost of lower compability (i.e. problems with exporting armatures and the inconvience of using a different up axis).

Tutorial - Blender 2.8

Note: This tutorial was written and tested on HPL2. HPL1 and HPL3 were not tested but most likely will work as well.

This tutorial goes over the most crucial practices which will make a Blender export work in HPL.

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.

Following this tutorial will make any model load in-game, but models with armatures will most likely have errors and their animations will be corrupted. See the Animation section for more information.

General rules

First, a few things to have in mind while making or editing a model:

1. Make sure that your model has unwrapped UVs.
2. Redundant textures and materials in the export will cause issues. Be careful not to add any unnecessary ones.
3. HPL allows only one material with one texture per object (submesh). No more, no less.

Importing

Importing the COLLADA file:

Simply click File>Import>Collada. Usually this will be enough.

However, you might find that nothing actually gets imported into the program. In that case, an often issue is the library_effects section of the .dae file made by Maya. Copy the file, edit it with a text editor, and delete all of the contents between and including the library_effects tags. Doing that should fix the issue and the file should import normally.

Exporting

1. Select a submesh and go to the Materials tab.
2. Make sure that the shader is set to Principled BSDF. Other shaders don't necessarily have to cause issues, but this one has been used with success.
3. Click on the circle next to the “Base Color” setting.
4. Pick “Image Texture” from the pop-up menu.
5. Click on “Open” and pick your texture file.
   • 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.
6. Repeat the previous steps until all submeshes have an assigned material with a texture.
7. Export the object as COLLADA (.dae) or, alternatively, as FBX. See the next section for more details.
8. 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.
9. Make sure that in export settings the “Geometry→Triangulate” option is marked.
10. If the object has an armature, or is supposed to be a StaticObject (not an Entity - those can be rotated in the Model Editor), you will need to set the export "up" axis to be the Y axis (Blender uses Z as up, 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. See notes on Blender 2.5 for more help.
11. Open the exported file with the ModelViewer - it is the best of the HPL editors for quick checks and prototyping. 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 loads, but isn't textured correctly, there probably are redundant images and/or materials in the blend file.

Blender to HPL

General

HPL supports COLLADA (.dae) and FBX. COLLADA is the "go-to" format used by FG. FBX is valid too, but seems to be more likely to crash the ModelViewer if anything is incorrect.

First thing to take into account when exporting is UV mapping the texture. Adding a texture to a material without UV mapping will NOT work, it will just crash the Model Viewer (or any other HPL instance).

It is recommended that 1 unit is set to equal 1 meter.

HPL uses Y as the up axis. Blender uses Z. As of 2.8, the export option to change the up axis seems to not work for HPL, so it is recommended to rotate the object manually before exporting. This is only necessary for static objects (anything designated to be an entity can be rotated in the Model Editor) and objects with armatures (which sometimes can't be rotated in HPL).

Make sure to save your project files (.blend) in the same folder as your textures and exports - this will simplify porting to HPL, and moving the file in general. Blender should by default use relative paths, but if you used absolute paths - change that setting because it will break the model on other computers, and probably won't even load in the Model Viewer.

Animations

Rotation/location/scale animations can be exported without a problem, however there is no known way of exporting shape animations correctly into the .dae format.

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.

Textures

Keep in mind that HPL culls all backfaces - in other words, textures are visible from only one side of the model. If the exported model has a texture on the "inside", you need to go back to Blender and flip the normals before exporting again.

It is highly recommended to use textures with power-of-two sizes (256×256, 512×512, 128×1024 etc.). Otherwise the model might crash your Model Viewer, look awkward or result in run-time errors and slightly worse performance.

Materials

Each submesh can, and must, have only one material! It's been also reported that if a material gets linked to 2 different geometries/datablocks/vertex groups/etc., it will crash in HPL. However, using the same material for multiple objects should work normally.

The in-game material is an XML file (.mat) that contains information on what images (.dds, .jpg, .tga and other formats) are used in the material to create the in-game look. Always set the diffuse texture of the Blender-material to have the same name as the engine-material (.mat) you want it to have. All other textures (normalmaps, etc.) can be later added in the Material Editor.

For more information about materials, check the General section in the HPL3 model export guide. The information there is also applicable to older HPL engine iterations.

Plugins

There are two plugins for HPL3 in Blender. They both are meant for making/prototyping maps in Blender, but their features and level of documentation varies.

• HPL3 plugin from Cadely
• HPL3 plugin from rbx775 - might be more comprehensive as it matures

Deprecated

Note: Subsequent updates and the Blender 2.8 UI rehaul have deprecated the following sections. However, they are kept here in order to preserve any potentially useful information.

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 1.3 (Machine for Pigs compatibility) update. (This was tested with Blender 2.68, but earlier versions may work too.)

Tutorial - Blender 2.7 and lower

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.