.. _GameEngineExport: Game Engine Export ******************* .. image:: img/game_engine_header.jpg :align: center .. image:: img/godot_logo.png :align: center .. raw:: html
| Overview ========= 2 types of skeleton can be exported: **Humanoid** for human characters, **Universal** for any skeletons Format: **FBX** or **GLTF** .. note:: GLTF requires Bender 3.4 and higher Although it's not officially supported, it's still possible to export to other formats by importing back the file in Blender, and exporting with built-in Blender exporters (DAE for example) Shape keys are exported, with option to apply them on top of existing modifiers. Full support in Unity, Unreal Engine (FBX), Godot (FBX, GLTF), and probably other game engines supporting these formats as well. | Export Requisites ================= * Ensure the character is not too small, otherwise it may lead to issues, such as bad retargetting. Try to consider one meter = one grid unit, ideally it has to be approximately this big compared to the grid floor (see screenshot below). Scale the mesh and armature (**S key** otherwise). .. image:: img/ge_scale_28.jpg :align: center | * Once the character is rigged and skinned, select its armature and go to **File > Export > Auto-Rig Pro FBX/GLTF** .. image:: img/file_export_28.jpg :align: center | .. _custombonesexport: Custom bones ------------- New bones created in the rig (clothes, hair, props...) are not exported by default. To export them, they must be tagged as custom bones: * Select the custom bones and click the dedicated button: .. image:: img/set_custom_bones.jpg :align: center | * Or, their name must starts with **'cc\_'** (stands for custom controller, e.g. 'cc\_sword'). * Or, tag them with a **'cc'** or **'custom_bone'** property, by adding a custom property to the bone .. image:: img/custom_bone_prop.jpg :align: center | If they are parented to an FK bone, they will be parented to the deforming bone automatically at export time. E.g, if "cc_watch" is parented to "c_forearm_fk", it will be parented to "forearm_stretch" which is the final deforming bone in the exported armature. If "cc_hat" is parented to "c_head.x", it will be parented to "head.x". Make sure to parent them directly to the "_stretch" bones when using an IK chain which has no direct controllers, such as "forearm_stretch". | Stretch - Scale ---------------- Stretch/scale of the arms and legs bones is not properly handled by the Fbx format, since the children bones always inherit the scale from their parent bones, and this is leading to rotation issues when scaling axes non-uniformly. For this reason, the stretch features must either be disabled or use additional tricks: No stretch: - Make sure to set to zero the **Auto-Stretch** and **Stretch Length** values of the arms and legs, and do not move the **c_stretch** controllers (elbows, knees). If stretchy bones are required: - Use the **No Parents** feature, see :ref:`exportsettings`, to flatten the exported skeleton hierarchy (bones are not parented) - Or, use the **Soft-Link** feature. Select deforming bones that should be stretched (for example arm bones) and click **Set Soft-Link Bones**. This will preserve bones scaling to 1 (no scale), while keeping their actual stretched position. This especially works well with multiple twist bones (more than 2), it gives the illusion that bones are scaled, while they are not. .. image:: img/softlink_button.jpg :align: center | .. image:: img/softlink.jpg :align: center | | Preserve Volume ---------------- In game engines, dual quaternions skinning is generally not supported, unlike Blender does with the "Preserve Volume" feature in the armature modifier. So make sure to uncheck **Preserve Volume** in the armature modifier in Blender to see the right deformations. .. image:: img/preserve_volume_28.jpg :align: center | It may be best to use multiple twist bones for the arms and legs, see :ref:`armsoptions` | Shape Keys ----------- Animations of shape keys are exported automatically. Topology changing modifiers (e.g Solidfy, Mask, Subdivision Surface...), are supported by the **Apply Modifiers** feature in the **Misc** export tab. If the character's facial is only rigged with shape keys, a good practice is to create custom properties on the head control (c_head.x), and setup drivers so that these properties drive the shape keys values (for example a property "smile" drives the "smile" shape key value). This way, the shape keys animations are stored in the same action as the control rig since they're connected to properties, allowing export of multiple actions/animations. Without properties, shape keys are stored in separate actions dedicated to shape keys, without any connection between the rig action and shape keys action. This makes it impossible to export multiple actions properly, since the shape keys actions are not automatically linked to the rig actions when exporting. | Root Motion ------------ Unity """"""" In Unity, root motion is automatically computed by looking for the center of skeleton, regardless of the bone hierarchy/animated bones nodes. Then no extra step is required. Unreal Engine """""""""""""" For Unreal Engine, the armature (rig) object itself must be animated. Since this is not convenient, Auto-Rig Pro includes an option to animate the "c\_traj" bone controller instead. This can be enabled with the **Root Motion** option in the export settings: .. image:: img/root_motion_2_28.jpg :align: center | .. image:: img/c_traj.png :align: center | By default, the IK feet and hips ("c\_root_master.x") controllers are parented to the "c\_traj" bone. Animators may prefer to unparent them, so that the "c\_traj" controller does not influence other bones. To do that: * Select the IK feet bones ("c\_foot_ik") and set their Child Of constraint influence to 0 .. image:: img/constraints_feet_28.jpg :align: center | * Select the "c\_root_master.x" bone, enter Edit Mode (Tab key) and clear its parent bone .. image:: img/parent_root_28.jpg :align: center | Animators may also prefer automatic tracking of the "c_traj" position using a constraint: add a **Copy Location** constraint to the c_traj, with the rig and **root.x** bone as target. Disable Z axis to keep it on the ground level: .. image:: img/traj_constraint.gif :align: center | | Custom Master Bones -------------------- Sometimes, the game engines may require a specific skeleton hierarchy, with a dedicated root/master bone at the base. * For example:: MyRootBone pelvis spine... If that is the case for you, follow these guidelines. By default, Auto-Rig Pro will not export the c_pos and c_traj master controller, looking like this in the Blender scene:: c_pos c_traj c_root_master.x c_spine_01.x... * To add a custom master bone that will be exported to Fbx, create a new bone (Edit mode > Shift A) and insert it in the hierarchy after the "c_traj" bone:: c_pos c_traj MyRootBone c_root_master.x... * Note that it's also necessary to replace the target bone in the "c_foot_ik" and "c_hand_ik" bones constraints, since "c_traj" is the default target bone. * Then make sure to select your custom master bone, and click "Set Custom Bones" to include it in the export. * Done, the exported hierarchy will be the following:: MyRootBone pelvis spine... | | .. _EXPORTACTIONS: Animations Export ------------------- In Blender, animations are called "actions" and multiple actions can be created for a character. However, when exporting to Fbx, all actions contained in the file are exported by default, no matter if they've been created to animate the rig or other objects. Exporting actions that are not linked to the rig may potentially corrupt the character animation. To see why, open the **Action** window of Blender, and try to link other actions to the character. It may get distorted, scaled weirdly, depending on the keyframes stored in the action. .. image:: img/assign_actions_28.jpg :align: center | To fix it, in the export options, you can click the eye button to display the exported actions. Click the check boxes to enable or disable action export, or use "Only Containing" to filter by name. .. image:: img/select_action_3_28.jpg :align: center | .. _fixrig: Check-Fix Rig =============== .. image:: img/check_fix_rig.jpg :align: center | These tools are useful to identify and fix quickly possible problems with the rig, that would make it not compatible with export, especially bones stretch issues. The **Check Rig** buttons only reports issues in a pop-up window, while the **Fix Rig** button will apply the following changes: * Disable all possible arms and legs stretches (c_stretch controller set to location 0, disable auto-stretch, set stretch length to 0...) * Disable the *Preserve Volume* option of the armature modifiers of skinned meshes, to show the actual exported deformations in Blender. This may change somehow the result, then it's recommended to check that animations still look good in the scene, and you can correct them if necessary. | Export Types ============== **Universal** exports a simplified bone hierarchy for any creature: bipeds, quadrupeds, spiders, centaurs... **Humanoid** is for human bipeds rigs only. It exports a simplified bones hierarchy like Universal, plus supports the Unreal Mannequin bones orientation as an option and humanoid naming convention. It's useful for retargetting, root motion... The drawback of this type is the bone restriction: in Unity to setup more facial bones than the jaw and the eyes, extra steps are required. Note that Unity internally handles the forearm twist by twisting the forearm bone without using a dedicated twist bone, unless an additional script/plugin is used to handle the twist bone. * Clicking **Unity** or **Unreal** hides or shows the export options dedicated to each engine. .. image:: img/universal_04_28.jpg :align: center | .. _exportsettings: Export Settings ================ Rig ---- Selection Only """""""""""""""" By default, all skinned objects are exported. If enabled, only the selected ones will be exported Full Facial """""""""""" **[Humanoid Only]** Exports all facial bones, otherwise only the main ones are exported (jaw, eyes...) and facial bones weights that are not exported are transferred onto the head weights. Advanced """""""""" Exports the bend/secondary bones (especially useful for cartoon characters to curve the arms, legs). .. note:: Arms and legs secondary controllers are automatically exported if they're set to **Twist** (see :ref:`SecondaryControllers`) .. image:: img/cardman_noodles.gif :align: center | Push Additive """""""""""""" If secondary controllers are set in **Additive** mode, compensate the weight loss of the additive bend bones, since the additive armature is not exported. Export Twist """""""""""""" Exports twist bones. A percentage can be defined to set the amount of twist. Generally 0.5 gives best results. 1.0 .. image:: img/twist_inf_100.jpg :align: center | 0.5 .. image:: img/twist_inf_50.jpg :align: center .. note:: Twist bones are automatically exported if there's more than one twist bone per limb (see :ref:`armsoptions`, :ref:`legsoptions`) No Parents """""""""""" Enables stretchy animated bones. Caution: to achieve this, bones are unparented (flat hierarchy). .. image:: img/allow_stretch.gif :align: center | Rename Bones """""""""""" Rename bones with custom names. Create a .txt file, and set custom names by writing base_name = new_name, one per line:: root.x = pelvis spine_01.x = spine1 spine_02.x = spine2 ... This .txt file path must be set in the "Rename Bones from File" field in the **Auto-Rig Pro: Export** panel: .. image:: img/rename_bones_from_file.png :align: center | Custom Export Script """""""""""""""""""" A python script can be written to execute post-instructions on the export skeleton. It is run after generating the export skeleton, and before baking actions. Set the script file path in the "Custom Export Script" field in the **Auto-Rig Pro: Export** panel. Example:: import bpy rig_export = bpy.context.active_object print(rig_export.name) bpy.ops.object.mode_set(mode='POSE') for pb in rig_export.pose.bones: print(pb.name) .. note:: The rig object name must not be changed with custom script. It's defined by the :ref:`rigname` setting in the Misc tab. These custom instructions are "use it at your own risks", they should be written carefully Units x100 """""""""""" Multiply scale units when exporting by a 100 factor, to allow retargetting in Unreal, and initialized scale transform in Unity as well (1.0). UE4 Legacy """""""""""""" **[Unreal Only]** Must be enabled when exporting for the older UE4 version. Metacarpal finger bones are not exported. Rename for UE """""""""""""" **[Unreal Only]** Rename bones according to the Unreal Engine's humanoid naming. Unity will handle the default names properly so this checkbox is not visible when Unity is chosen. Mannequin Axes """""""""""""""" **[Unreal Only]** Match the bones orientations with the Unreal Mannequin. This allows to directly import the skeleton as the Mannequin skeleton in Unreal. - 4 spine bones and 1 neck bone are required to match the **UE4** Mannequin. - 6 spine bones and 2 neck bones are required to match the **UE5** Mannequin. It's also best to export the character in A-Pose when exporting to UE, see :ref:`ChangeRestPose`. .. image:: img/skeleton_mannequin_ue.jpg :align: center | Root Motion """""""""""" Transfer the "c_traj" bone animation to the armature object (root node in Fbx file) animation when exporting, to support root motion in game engines. Add IK Bones """""""""""""" **[Unreal Only]** Add the Unreal Mannequin IK bones: "ik_foot_root", "ik_foot_l",... | Animations ----------- .. image:: img/select_actions_2.jpg :align: center | Bake Actions """""""""""""" Enable actions export (animations) Type """""" Type of actions to export. **Actions** will export individual actions, while **NLA** will export a single animation for the whole scene as defined in the NonLinearAnimation editor. As Multiple Fbx Files """""""""""""""""""""""" To export one Fbx file per action Frame Range """""""""""""" To define the frame range that will be exported for each action (start and end frames). The **Markers** setting allows to export frames between two markers named "start" and "end" inserted at the desired frames in the action. Action Names """""""""""""" By default the action names may be too long when exported, with superfluous identifiers, this can be used to shorten their name to the minimum Simplify Factor """""""""""""""""" Higher value will decrease the file size at the expense of the quality. Lower values are recommended to fix animation inaccuracies such as "floating" feet effects. Actions Manager """""""""""""""""" If enabled, the actions manager will be used to define which actions will be exported. Actions can be grouped together, and enabled/disabled as a group quickly. Only Active """""""""""""" To export only the current, active action linked to the rig. Only Containing """""""""""""""" To export only actions including the given word in their name. E.g. setting "soldier" will export the action "soldier_walk" but won't export "john_walk". Useful when dealing with multiple actions in the scene. Actions can be excluded from export using the checkboxes, and removed from the file by clicking the **X** button | .. _gemisc: Misc ------ .. image:: img/ge_panel_misc.jpg :align: center | Global Scale """""""""""""" Apply a global scale, although it's not recommended: better scale the armature and meshes before exporting. Smoothing """""""""""" Polygons smoothing options (normals data), **Normals Only, Face, Edge**. Choose **Edge** to avoid import warning message in UE. Apply Modifiers """""""""""""""" Apply modifiers when exporting. Supports topology changing modifiers and shape keys Apply Subsurf """""""""""""" Apply the Subsurf modifier Fix Rotation """""""""""""" Add imperceptible jitter to bones position to avoid rotation issues when exporting animations. Should be enabled only when necessary (buggy rotations) Fix Matrices """""""""""""" Use an alternative method to evaluate bones matrices, to avoid rotation issues when exporting animations Add Dummy Mesh """""""""""""" When no meshes are exported, only the skeleton, it can be useful to add an empty/dummy mesh object so that the animated skeleton can still be imported in game engines. For example, Unreal Engine needs it. Force Rest Pose Export """"""""""""""""""""""" By default the bind pose/rest pose is not exported if no meshes are exported with the skeleton. This allows to force the rest pose data export anyway. Initialize Fbx Armature Rotation """""""""""""""""""""""""""""""""" If the skeleton object has non-zeroed out rotations in the game engine, check this Initialize Fbx Meshes Rotation """""""""""""""""""""""""""""""""" If the meshes objects have non-zeroed out rotations in the game engine, check this Bake Axis Conversion """"""""""""""""""""" Enables special axes and scale values when exporting, to comply with the Bake Axis Conversion attribute of Unity. Bones Axes """""""""""" Set the primary and secondary axes of bones when exporting .. _rigname: Rig Name """""""""" Set the name of the exported rig Embed Textures """"""""""""""" Force textures to be embedded in the Fbx file. May not work if shaders are different from a Principled BSDF shader. | Export by Script ================= Exporting by script is fully supported, here are some examples for various purposes. These snippets can be copy-pasted in the Blender text editor, then click **Run Script** in the editor header menu. .. image:: img/run_script.jpg :align: center | * Export a character:: import bpy import os # set the file path output here file_output = "F:\\MyExportFbx.fbx" # set some settings... scn = bpy.context.scene scn.arp_export_rig_type = 'UNIVERSAL' # types: 'humanoid' for humanoid characters, 'mped' for universal skeletons scn.arp_engine_type = 'UNREAL' # other useful settings # scn.arp_keep_bend_bones = True # scn.arp_units_x100 = True # scn.arp_bake_actions = True # scn.arp_export_name_actions = True # scn.arp_export_name_string = "test" # scn.arp_mesh_smooth_type = 'EDGE' # scn.arp_ue_root_motion = True # scn.arp_export_noparent = True # scn.arp_export_twist = True # run export bpy.ops.arp.arp_export_fbx_panel(filepath=file_output) | * Batch export all selected rigs:: import bpy import os character_names = [i.name for i in bpy.context.selected_objects] def set_active_object(object_name): bpy.context.view_layer.objects.active = bpy.data.objects.get(object_name) bpy.data.objects.get(object_name).select_set(state=1) for char_name in character_names: bpy.ops.object.select_all(action='DESELECT') set_active_object(char_name) # set the file path output here file_output = "F:\\"+char_name+".fbx" # export it bpy.ops.arp.arp_export_fbx_panel(filepath=file_output) | * Batch export character meshes as separate Fbx files (including the skeleton):: import bpy import os mesh_names = ['Cube.001', 'Cube']# add your mesh object names to the list here rig_name = 'rig'# set here your armature name bpy.context.scene.arp_ge_sel_only = True def set_active_object(object_name): bpy.context.view_layer.objects.active = bpy.data.objects.get(object_name) bpy.data.objects.get(object_name).select_set(state=1) for mesh_name in mesh_names : bpy.ops.object.select_all(action='DESELECT') set_active_object(mesh_name) set_active_object(rig_name) # set the file path output here file_output = "F:\\"+mesh_name+".fbx" # export it bpy.ops.arp.arp_export_fbx_panel(filepath=file_output) | Unreal Engine Tips ====================== Import specifications ----------------------- If the mesh have shape keys, importing with **Use TOAs Ref Pose** enabled may lead to incorrect blend shapes in Unreal. If this happens, make sure to turn it off. .. image:: img/unreal_import_toa.png :align: center | Retargetting -------------- UE Humanoid Specifications """""""""""""""""""""""""""" * The Unreal humanoid rig features 4 spine bones (root + 3 spine bones). So it's possible to set the Auto-Rig Pro spine count to 4 too in the Rig tab of the Auto-Rig Pro panel. Otherwise, when assigning the regtargetted bones, just map the spine_03 slot to the spine_02. .. image:: img/ue_retarget_spine.jpg :align: center | * Make sure the 'advanced' bones are properly mapped (click **Show Advanced** to display the facial and fingers bones). If you don't use them, click the X button to unassign. * For better results, pose |unrealdoc| .. |unrealdoc| raw:: html your character as the target rig rest pose .. image:: img/base_pose.jpg :align: center | .. _retargetskeleton: Retargetting Translation Type """""""""""""""""""""""""""""" * To avoid strange arm/legs rotations after retargetting, set their translation type to **Skeleton**. Display the retargetting options by clicking this in the bones tree: .. image:: img/ue_retarget_options.jpg :align: center | Then set to Skeleton this property: .. image:: img/ue_retarget_skeleton.jpg :align: center | Rotation Offsets ----------------- Sometime, because of differences in the rest position of the source and target rig, or because the animation itself contains artefacts, it's necessary to apply rotation offset over the retargetted animation for better results. It's especially true for the fingers. Here is how to fix wrong fingers rotations of the ThirdPersonRun included in UE: * Select and rotate the bones in the 3d viewport (animation window) .. image:: img/ue_fingers_offset_01.jpg .. image:: img/ue_fingers_offset_02.jpg * Select all the bones you've modified in the Skeleton Tree: .. image:: img/ue_fingers_offset_03.jpg :align: center | * Click the **Key** cross button then the **Apply** button. .. image:: img/ue_fingers_offset_04.jpg :align: center | * Save your asset and you're done! | Unity Tips ============ .. _skintotalweights: Skin Weights -------------- In Unity, the **Skin Weights** setting in the **Quality** panel defines the maximum number of deforming bones per vertex. This is useful to keep high realtime performances since too many deforming bones can slow down calculations. However, this may lead to bad deformations, if this value doesn't match the number of deforming bones in the Blender rig. For example, if some vertices are deformed by 5 bones while the Unity limit is set to 2, this is going to lead to some serious deformation issues. .. image:: img/unity_skin_weights.jpg :align: center | * If you're concerned with in-game performances, then make sure to keep the **Skin Weights** value to 4 bones or less. In Blender, ensure vertices have no more than 4 deforming bones. This can be automatically done with the |limittotaldoc| setting. Then ensure deformations are still correct after this, and tweak weights if necessary. .. |limittotaldoc| raw:: html Limit Total Vertex Groups .. image:: img/limit_total_vgroup.gif :align: center | * If performances are not a deal breaker, set **Skin Weights** to **Unlimited** in Unity to ensures all weights are taken into account |