guide.txt

io_mesh_urho v0.6

This is a Blender addon that helps you exporting your meshes, armatures, animations and materials to Urho3D.
It is an amateur work, done with little knowledge of Urho3D and Blender, but I hope it helps.
Public domain license. Maintained by reattiva (you can contact me @gmail.com).
Contributors: https://github.com/reattiva/Urho3D-Blender/graphs/contributors

 Installation from releases
----------------------------
- download the latest zip file from the releases
- jump to the plus below

 Installation from GitHub zips
-------------------------------
- download the zip file from GitHub repository main page using the button "Download ZIP";
- unzip it;
- select the folder 'io_mesh_urho' and re-create a zip file (you need the folder 'io_mesh_urho' in the zip file);
+ open Blender;
- open 'user preferences' (Ctrl+Alt+U);
- click 'Addons' on the top bar;
- click 'Install from file...' on the bottom bar;
- select the zip file;
- now search in the list, you should see a greyed line named 'Import-Export: Urho3D export';
- click on the checkbox on the right to enable the addon (see below if you can't set the check);
- optional: click 'Save User Settings' to remember this addon as enabled.

 Uncheckable box
----------------
If you can't check the checkbox, there is an error in the exporter and I'll try to fix it. In the 'Window' menu
of Blender, select 'Toggle System Console' to see the error, copy and email it to me, thank you.

 Exporter location in Blender
------------------------------
The exporter is located in:
- Properties panel, by default it is the panel in the right bottom corner, its icon is an horizontal scrollbar
- Render page (camera icon, it is the first icon in the panel)
- Scroll down to 'Urho export'

================
 Exporter panel
================

- Button 'Export'
This button starts the export process using the current options.
Options can be minimized/expanded with '+' or '-'.
- Page icon on the right
This button shows you the log of the last export process.
On Windows a console can be toggled.

- 'Output folder'
This is where the exported files will be created. Click the folder icon on the right to browse and choose 
the folder.
- 'Files overwrite'
By default existing files are not overwritten by the exporter, this option enables overwriting files.
- 'Use subfolders'
This option allows to set custom subfolders, relative to the 'Output folder'. By default Urho3D folder hierarchy
is replicated, with 'Models' to store meshes, animations and material lists, 'Textures' to store textures,
'Materials' to store materials, 'Scenes' to store 'scene' prefabs and 'Objects' to store 'node' prefabs.

- Blank page icon on the right
Restore the default options ('factory' settings).
- Objects
Select the objects you want to export:
  'All': export all the objects in the scene (hidden and moved included).
  'Only selected': export only the selected objects.
- Origin
Set the meshes origin:
  'Global': the origin of all the meshes will be the Blender global origin (the center of the grid), meshes are kept in place.
  'Local': for each mesh the origin will be the object center (little orange dot), mesh is moved to (0,0,0).
- Front view
Allows to alter the rotation of the models.
- Scale
Apply a scale transformation on the object exported.
- Apply Modifiers
If an object has some modifiers stacked, apply them to the mesh before exporting (with Preview or Render settings).
- Select vertices with errors
If a vertex has an error (missing element, invalid UV...), toggle List of errors just after export failure and select one of the errors.
This puts the object in Edit mode and selects the vertices at fault.
- Force missing elements
Vertices can have different elements (position, normal, UV, bone weight), when you export a mesh you can choose 
which elements you want to export (see Geometries below). If a vertex in the mesh does not have an element selected
to be exported, an error is generated. This option prevents these errors forcing the missing elements to a default
value. (You should not use this option but instead try to correct the errors).
- Merge objects
Merge all the objects exported in one Urho model (with different geometries).
- One vertex buffer per object
Split each object into its own vertex buffer. If we can use a 16 bits index (instead of 32) when we use a buffer per
object, then this option is automatically selected.
- Optimize indices
Try to sort triangles in the index buffer to gain an optimal use of the hardware vertices cache. In other words, this
option can speed up the rendering of the mesh. It can be very slow (5 minutes for 30K smooth vertices on an average pc),
so you should preferably disable this feature when prototyping.
- Use LODs
Export each 'Level Of Details' (LOD) present for each object (see LOD below).
  - Strict LODs
  If ON, the LOD will probably have new vertices and your LOD will be accurate as you see it in Blender. 
  If OFF, the LOD will try to use vertices of the first LOD and you could see some acceptable distortions caused by 
  slightly off normals.

- Skeletons
Export the object armature (skeleton).
Suboptions allow to selectively remove bones from the export:
  - Derigify: Try to remove the control bones (.ORG) from the Rigify armature and keeps only the deform bones. (Not fully tested)
  - Only deform bones: skip bones (and their children) for which 'Deform' property is false in Properties > Bone
  (these are bones that don't deform geometry)
  - Only visible bones: skip bones (and their children) for which Armature layer visibility (in Properties > Data > Layers) is not active
  - Clamp bones bounding box: clamp each bone bounding box between bone head & tail. Use case is to ease generation of ragdoll, IK...
- Animations, Animations of objects
The first exports the armature animations, it is available only when the 'Skeletons' option is checked. 
The second exports objects animations. When we are exporting the Timeline animations of multiple object then a single animation is
created with one track for each object. Use "Origin=Local". 
  'Timeline'
  'All tracks (not muted)'
  'All Strips'
  'Selected Tracks'
  'Selected Strips'
  'Selected Strips Actions'
  'Actions used in tracks'
  'Current Action'
  'All Actions'
  - Ending extra frame: extend the animation by one frame before it is exported, this should only be useful when you are
  exporting the Timeline or the Nla-Tracks, and only for looped animations where you had to cut the last frame to get a 
  smooth playback in Blender. See "Animations last frame" below.
  - Export markers as triggers: for each exported animation which contains markers a xml file is created where the time 
  in seconds and the name of the markers are listed. This xml file can be used in Urho as triggers to signal particular 
  keyframe of the animation. For the Timeline only 'Scene Markers' are exported. To add a 'Scene Marker' go to the Timeline 
  or the NLA Editor window, then from the menu Marker, select Add Marker (M). Instead Actions, Strips and Tracks export 
  'Pose Markers'. To add a 'Pose Marker' go to the Dope Sheet, select the Action Editor, create or load an Action, then 
  from the menu Marker, select 'Show Pose Marker' and finally select Add Marker (M).
    - Normalize Time: in the xml file, instead of the number of seconds, use a number from 0 (at the start of the 
      animation) to 1 (at the end)
  - Only keyed bones: export only animation of bones with an animation key.
  - Read actions by Fcurves: export Actions by evaluating the F-Curves instead of updating the whole scene, it should be 
  much faster, it can be used only for Actions.
  - Position, Rotation, Scale: select what animation data to export.
- Geometries
Here you can select what vertex data to export:
  - Position: export vertices positions
  - Normal: export vertices normals
  - UV, UV2: export vertices UV coordinates (see 'UV' section below)
  - Tangent: export vertices tangents
  - Weights: export vertices bones weights (see 'Weights' section below for troubleshooting)
  - Color, Alpha: export vertices colors (see 'Colors' section below)
- Morphs
Export not muted shape keys (Morphs):
  - Normal: export morphed vertices normals
  - Tangent: export morphed vertices tangents
- Export materials
Export the object materials (see Materials below).
  - Materials text list: in the models folder create a text file with the same name of the model, inside there is
    the list of the material files exported that are used by the model. This file is used by Urho3D Editor to retrieve the materials.
- Copy textures
Copy the textures used by the objects materials to the output folder. Sometimes this does not work, especially when
the images are embedded in the blend file are no format was specified for them.
- Export Urho Prefabs: see 'Prefabs' section below


=====
 LOD
=====
To create a LOD: append to the object name "_LOD00.0" (for example "house_LOD00.0"), duplicate the object, rename it
changing the number after '_LOD' with the distance up to this LOD is visible (for example "house_LOD00.0"), reduce its
vertices (you can use the 'Decimate' modifier), repeat these two steps until you have the desired number of LODs.
You can use float or integer numbers, it is important that the numbers are right aligned in the object names.
For example: house_LOD005, house_LOD010, house_LOD100... but not: house_LOD5, house_LOD10, house_LOD100...

=========
 Weights
=========
Issues with weights ('element mask' errors reported in the List of errors when 'Select vertices with errors' is enabled)
might show up when:
  - some vertices are not weighted (skinning issue)
  Fix: redo the skinning for the vertices at fault
  - 'Vertex Groups' and bones are mismatching. This can occur when:
      - a bone has been deleted and its 'Vertex Group' has not been reassigned to remaining bones. This is a skinning issue.
      Fix: reassign 'Vertex Group' (in Properties > Object Data), manually or using Set Parent To Armature Deform With Automatic Weight.
      - a vertex is weighted exclusively to bones that have been removed from export (using one of the 'Skeletons' suboptions).
      Fix:
          - choose another 'Skeletons' suboption or modify Armature layer visibility to include more bones at export.
          - reassign 'Vertex Group' (in Properties > Object Data) so that each vertex is weighted to at least one remaining bone.

=====
 UV
=====
To export UV you need an UV map, you can see the list in the Data page of the current selected object.
The Urho MDL format supports two sets of UV coordinates. You can specify what maps to use by appending "_UV1" or
"_UV2" to the layer name. These suffixes can be used together but also alone, if they are missing the first used
layer will be chosen.
If the exporter reports some "Invalid UV" this means that some triangles of the mesh are mapped in the UV map to
triangles with an area null or too small. You need to increase the area in the UV map, you can set the option
'Select vertices with errors' to find these triangles.

========
 Colors
========
To export vertex colors you need an Color map, you can see the list in the Data page of the current selected object.
Blender colors do not support have alpha, so if you need alpha you need two Color maps, one for the color and one for
the alpha. You need to specify these maps by appending "_RGB" and "_ALPHA" respectively to the layer name. These
suffixes can be used together but also alone, if they are missing the first layer will be chosen for RGB only.
For the alpha color layer use a scale of grey (black=transparent, white=opaque), starting from black or white you can
use the Value slider (V in HSV) to easy change a greyscale color.

=======================
 Animations last frame
=======================
(based on my limited knowledge)
Urho and Blender manage animations in different manners. What seems correct in Blender is not in Urho and 
viceversa, so you need to apply some corrections. The errors are more visible in looped animations.

Say that you have a looping animation of 3 frames: at frame 1 you are at position A, at frame 2 you move at
position B, at frame 3 you move back to A. In frame 1 and 3 you are in the exact same position.
In Blender if you set "Start=1 and End=3" (which sounds rather reasonable) you'll get an unwanted pause in 
the playback, this is because Blender awkwardly insists on playing a full frame when it reachs frame 3.

Say you set FPS=2 so you have 0.5s per frame, the Blender timeline is this:
  0.0s: frame1  ->  0.5s: frame2  ->  1.0s: frame3  ->  1.5s: frame1  ->  2.0s:frame2 ...
Frame3 and frame1 are played for 1.0s total but frame2 only gets 0.5s, hence the pause.
In Blender you solve this by setting: "Start=1, End=2".

Urho is different, at "Start=1, End=3" its timeline is:
  0.0s: frame1  ->  0.5s: frame2  ->  0.999s: frame3  ->  1.0s: frame1  ->  1.5s:frame2 ...
(see "AnimationState::AddTime" for details)
There are no problems in Urho. However Urho needs frame3 to be exported. If you export at "Start=1, End=2"
you'll see a good animation in Blender but a jagged one in Urho.
To export a looped animation set: 
  Start=the first frame, End=the last frame which is a copy of the first frame

This is only needed when the exporter uses the Start and End values so:
  'Timeline', 'All tracks (not muted)', 'Selected Tracks'
Strips and Actions do not suffer this problem (and in this Blender does not make sense).

The option "Ending extra frame" tries to solve this by extending the animation by one frame when exporting.
So you set the animation like Blender wants ("Start=1, End=2" in the example above) then, only if you are
using the Timeline or a Nla-Track, you set this option to export the animation.

===========
 Materials
===========
The exporter will try to generate Urho3D materials that are similar to what you see in Blender, they will not be the
exact same but at least you have a starting point.
This feature works only with the 'Blender Render' engine not Cycles. It will probably need some corrections.

This is how a Blender material setting (on the left) is converted to a Urho3D material parameter (on the right):

--- Blender Material ---
Diffuse.Color * Diffuse.Intensity       = MatDiffColor rgb
Transparency.Alpha [value if enabled]  = MatDiffColor alpha
Transparency.Mask = add 'Mask' to technique when Transparency.Alpha is enabled
Specular.Color * Specular.Intensity     = MatSpecColor rgb
Specular.Hardness                      = MatSpecColor power

--- Blender Object Data ---
Normals.DoubleSided [if true]          = set material 'cull' and 'shadowcull' to 'none' (=double sided material)

Note: the 'Double Sided' option is true by default in Blender when creating a new material, so don't forget to turn it off
unless necessary.

--- Blender Textures ---
Influence.Diffuse.Color [if enabled]   = diffuse  texture and add 'Diff'     to technique
Influence.Geometry.Normal [if enabled] = normal   texture and add 'Normal'   to technique
Influence.Specular.Color [if enabled]  = specular texture and add 'Specular' to technique
Influence.Shading.Emit [if enabled]    = emissive texture and add 'Emissive' to technique
Influence.Shading.Emit [value]         = MatEmissiveColor rgb
[if texture slot name contains '_AMBIENTLIGHT'] = emissive texture and add 'AO'       to technique
[if texture slot name contains '_LIGHTMAP']     = emissive texture and add 'LightMap' to technique

Note: Textures must have Type='Image or Movie' and Mapping.Coordinates='UV'.
Note: The emissive color exported is a shade of grey, you can manually change it to any color.
Note: Emissive, AO, LightMap are exclusive.
Note: AO and LightMap use the coordinates UV2, so the texture slot name will be something like: 'name_LIGHTMAP_UV2'.

============
 Light maps
============
To define a texture to be exported as a light map you can insert '_AMBIENTLIGHT' or '_LIGHTMAP' in the texture slot 
name. You need to use a different set of UV coordinates and add '_UV2' at the end of the texture slot name or the
UV Map name.
It is simpler to use '_AMBIENTLIGHT' because many techniques are already present in Urho3D, you only need to add 
a Zone in your scene, its Ambient Color will modulate the light map.

=========
 Prefabs
=========
Prefabs allow to export Urho3D 'Scenes' and 'Objects'.
They are the equivalent of AssetImporter's 'node' and 'scene' commands.

--- Individual Prefabs ---
Output one prefab per exported object. Use this option when merging objects at export.
Each xml file is named according to its object's name, except when 'Merge objects' option is enabled (xml file is then named
according to the selected object's name).

--- One Collective ---
Create one unic/global prefab containing every exported objects, while retaining hierarchy. An empty root node holds the objects.
The xml file is named according to the scene's name.
Note that this option is not available when 'Merge objects' is enabled.

--- Scene Prefab ---
Same content as 'One Collective', but outputs a Urho3D xml scene (with Octree, PhysicsWorld, DebugRenderer and Light).
The xml file is named according to the scene's name.

--- Physics ---
Select what physics components to create for the prefabs:
  - No physics: do not export physics at all.
  - Individual: export Urho3D physics components (PhysicsWorld, RigidBodies and CollisionShapes).
  - Global: expects a 'Physics.mdl' model as TriangleMesh shape. Useful when using a simplified geometry for the whole scene.

--- CollisionShape ---
There are 2 ways to set the CollisionShape to use for the exported objects:
  - switch the rendering engine to 'Blender Game', enable 'Collision Bounds' in Properties > Physics and then select your shape
  - select a 'CollisionShape' in the Export panel: this shape is used when 'Merge objects' option is enabled or when 'Collision Bounds' is disabled.

=======================================
 Batch export by Sergey Lapin (slapin)
=======================================
 Example on how to use the exporter in a Python script, see:
 https://github.com/reattiva/Urho3D-Blender/issues/78
 To run the script in background/headless mode, good for makefiles and build systems, use the -b flag:
 blender -b blendfile.blend -P exportscript.py

import bpy, os
scene = bpy.context.scene

# Set the output folder and subfolder
basepath = os.getcwd() + "/export/"
subpath = "Models/example"

# Set the exporter options
scene.urho_exportsettings.outputPath = basepath
scene.urho_exportsettings.fileOverwrite = True
scene.urho_exportsettings.useSubDirs = True
scene.urho_exportsettings.optimizeIndices = True
scene.urho_exportsettings.lods = True
scene.urho_exportsettings.skeletons = True
scene.urho_exportsettings.materials = True
scene.urho_exportsettings.textures = True
scene.urho_exportsettings.prefabs = True
##scene.urho_exportsettings.individualPrefab = True
scene.urho_exportsettings.collectivePrefab = True
scene.urho_exportsettings.geometryPos = True
scene.urho_exportsettings.geometryNor = True
scene.urho_exportsettings.geometryUV = True
scene.urho_exportsettings.geometryTan = True
scene.urho_exportsettings.geometryWei = True
scene.urho_exportsettings.source = 'ONLY_SELECTED'
scene.urho_exportsettings.orientation = 'Y_MINUS'
scene.urho_exportsettings.modelsPath = subpath
scene.urho_exportsettings.animationsPath = subpath
scene.urho_exportsettings.materialsPath = subpath
scene.urho_exportsettings.texturesPath = subpath
scene.urho_exportsettings.objectsPath = subpath
scene.urho_exportsettings.scenesPath = subpath

for ob in scene.objects:
    if ob.type == 'EMPTY' and not ob.name.endswith("_noexport"):
        # Select the object and its children, move it to the origin
        bpy.ops.object.select_all(action='DESELECT')
        ob.location = (0, 0, 0)
        ob.select = True
        scene.objects.active = ob
        bpy.ops.object.select_grouped(extend=True, type='CHILDREN_RECURSIVE')
        # Backup and change the scene name to rename the prefab
        sname = scene.name
        scene.name = ob.name
        # Export
        bpy.ops.urho.export()
        scene.name = sname