= MakeHuman Blender OgreXML toolchain for creating and importing animated human characters
:author:
:revnumber:
:revdate: 2016/03/17 20:48
:relfileprefix: ../../
:imagesdir: ../..
:experimental:
ifdef::env-github,env-browser[:outfilesuffix: .adoc]


This guide describes how to use MakeHuman Blender OgreXML toolchain.


== Tools

The latest versions at time of writing are:

*  MakeHuman: 1.0.2
*  Blender: 2.72
*  OgreXML exporter for Blender: 0.6.0

The tools can be downloaded from the following URLs:

*  MakeHuman: link:http://www.makehuman.org/[http://www.makehuman.org/]
*  Blender: [link:http://www.blender.org/[http://www.blender.org/]
*  OgreXML exporter for Blender: <<jme3/external/blender/blender_ogre_compatibility#,Working Blender and OgreXML Versions>>


== Seed Project

Public domain seed project with some preset characters and animations:

*  JME3 Open Asset Pack: link:https://github.com/bubblecloud/jme3-open-asset-pack[https://github.com/bubblecloud/jme3-open-asset-pack]


== Preparation

.  Install MakeHuman and Blender.
.  Install MakeHuman Blender importer from MakeHuman installation to Blender scripts folder and enable the script from Blender `menu:File[User Preferences>Addons]`.
.  Install OgreXML exporter to Blender scripts folder and enable the script from Blender `menu:File[User Preferences>Addons]`.
.  Clone the seed project or create your own project.
.  Locate or create character model folder (src/main/resources/character/human/female)


== Creating Character Model with MakeHuman

.  Create character model with MakeHuman. (link:http://www.makehuman.org/documentation[http://www.makehuman.org/documentation])
**  NOTE: If you want to use JME3 Open Asset Pack animations without tweaking then use either male.mhm or female.mhm as preset and do not change the body proportions.

.  Choose basic skeleton from Pose/Animate tab if you are not already using either of the presets.
.  Export to blender exchange format from `menu:Files[Export]` tab.
**  Choose `menu:Mesh Format[Blender exchange]` +
[%interactive]
*** [x] Options
*** [x] Feet on Ground
*** [x] Scale Units
*** [x] Meter



== Animating Character Model with Blender

.  Import the character model in blender exchange format (MHX) to Blender or open preset blender file female.blend.
.  If you use your own character you can append animations from male.blend or female.blend preset files with Blender `menu:File[Append]` function. Animations are in the animation folder.
.  Tune the character model / materials and animate the character. (link:https://www.blender.org/support/tutorials/[https://www.blender.org/support/tutorials/])


== Exporting Character Model from Blender to Ogre XML

.  Make sure that your scene objects in Blender do not have any spaces or special characters in their names. Rename them if they do.
.  Arrange all your animations in single NLA track after each other without overlaps or touching in the timeline.
.  Unlink any animations linked directly to your character armature or mesh.
.  Export using `menu:Blender[File>Export Ogre3D]` (scene and mesh) and tick the following options: +
[%interactive]
**  [x] copy shader programs
**  [x] Export Scen
**  [x] Export Meshes
**  [x] Export Meshes (overwrite)
**  [x] Armature Animation
**  [x] Optimize Arrays
**  [x] Export Materials
**  [x] Tangents
**  [x] Reorganize Buffers
**  [x] Optimize Animations



== Importing Ogre XML to JME3

You can load the ogre XML with asset manager or import them to SDK and hence convert them to JME3 asset format.

You can test the animations by making your own version of AnimationPreviewer:

link:https://github.com/bubblecloud/jme3-open-asset-pack/blob/master/src/main/java/com/jme3/asset/AnimationPreview.java[https://github.com/bubblecloud/jme3-open-asset-pack/blob/master/src/main/java/com/jme3/asset/AnimationPreview.java]