====== Blender ======

[[http://www.blender.org|Blender]] is an open source 3D content creation suite that has built-in support for the file format COLLADA that the HPL2 engine uses to import 3D models.

===== Program setup =====

The great thing with Blender is that it will work great without any additional settings, plugins or similar.

===== How To - The very basics =====

  - When Blender launches it creates a default cube.
  - Save the Blender project (**Ctrl + S**; **File → Save**).
  - 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).
  - 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//.
  - 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).
  - With all the faces still selected, convert all quads to tris either by **Ctrl + T**  or **Mesh → Faces → Quads to Tris**.
  - 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.
  - 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.
  - Delete the default camera and default light.
  - 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.
  - Save the file as "filename.dae" in a folder within one of Amnesia's directories (preferably the custom_stories directory).
  - Using the [[:hpl2:third_party_tools:tools:viewers:model_viewer|model viewer]] you should now see the newly created cube fully textured.

==== Additional Information about the above steps ====

The above 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. It is not intended to be a lengthy tutorial or be suited for advanced, novice or any specific type of user. It's just a quick how to.

==== 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.

===== Blender to .Dae, How to get it right =====

This article is written by [[http://www.frictionalgames.com/forum/user-15497.html|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, or just look awkward. \\  \\ 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. Will look funny in model view. \\  \\ You can export rotation/location/scale animations without problem, however, I couldn't export shape animations correctly into .dae format (because blender's collada export sucks! Not actively developed.) 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:

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

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.)

===== Notes on Blender 2.8 =====

Blender 2.8 introduces major UI changes, so here's a redux of the tutorial:

1. Make sure to remove all non-mesh components, like lights and cameras. \\ 2. Make sure that your model has unwrapped UVs. Alternatively, you can unwrap your model after adding the texture. \\ 3. Very important! HPL* doesn't like when there are orphaned textures and materials. You must be very careful not to add any unnecessary ones, so follow carefully. If your model crashes for no apparent reason, this is likely the case. Make sure to delete the duplicate and orphaned data before exporting. \\ 4. Also keep in mind that HPL allows only one material with one texture per mesh (object). No more, no less.

5. Select your mesh and go to the materials tab:

{{https://cdn.discordapp.com/attachments/608274016943341578/674982152177319985/picture_1.png?nolink&333x611}} \\ 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:

{{https://cdn.discordapp.com/attachments/608274016943341578/674982187971641404/picture_2.png?nolink&226x54}}

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. 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).

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 .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.

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

===== Blender Tutorials =====

Does Blender seem like a good program for you? But you have not modeled much before or not modeled much with Blender? Here are some useful sites that have tutorials and information to help you out.

  * [[http://www.blender.org/education-help/tutorials/|Tutorials listed on the Blender site]]
  * [[http://blenderunderground.com/|Blender Underground]]
  * [[http://www.cgcookie.com/blender/|Blender Cookie]]