How To Use
- Download the latest release as a zip file from the Releases page
- In Blender, under
Preferences, clickInstall...and select the zip file - Make sure to tick the Enable checkbox to enable the addon
For more information on this you can check out Blender's manual page on add-ons.
It is possible to clone this repository or a fork of it directly in case you'd like to make your own changes to the code in a local copy.
This is described in more detail under Cloning the repo and making changes.
Select the objects that you want to export. In this selection, the exporter will consider all mesh objects and the first armature object that it can find.
Navigate to File > Export > SMF.
Select the export options that you want to use and save the SMF file.
In the export settings you can currently define a couple of additional options. The default settings are shown below.
SMF makes use of dual quaternions when animating models. Blender, by default, does not use quaternions for deforming the vertices attached to an armature.
To allow this and to better reflect how an animation will look in SMF the Preserve Volume option can be enabled on the armature modifier(s).
The following image shows an armature modifier's preferred settings for use with SMF:
Note The SMF exporter exports the skinning weights that are stored in vertex groups of meshes, deform groups as Blender calls them.
Therefore theBind to Vertex Groupsoption should be enabled.
Note The exporter does not export bone envelopes. These can be converted to vertex groups however using
Assign from Bone Envelopesin Weight Paint mode.
The exporter can pack images linked to the materials in the SMF file.
For this to work correctly, images should either be linked directly as the input to the Material Output node or indirectly through a single shader node of any type (Principled BSDF, Diffuse BSDF, ...).
Visually, the shader node setup should look like one of the following:
| Indirectly Linked | Directly Linked |
|---|---|
 |
 |
Note SMF supports a single texture per mesh. If you want to include all assigned materials, make sure to split meshes by material before exporting.
SMF supports multiple animations. Blender also supports this, in a way, by allowing you to link multiple actions to the same armature via Nonlinear Animation.
Note Throughout this wiki the terms
actionandanimationare used interchangeably. You could say that, in Blender,actionsare used to store animation data. In SMF,animationsstore animation data.
By default the exporter checks if the selected armature object has an action set.
In this case the action is exported and the SMF model will contain a single animation.
When Export NLA Tracks is enabled the exporter looks for all unique actions that it can find on the NLA tracks of the armature object and exports those.
Each action is exported as a separate animation. The names of the actions are used as the names of the animations in the SMF file. The NLA track names aren't used for this.
| Export Current Action (Single) | Export NLA Tracks (Multiple) |
|---|---|
 |
 |
You can choose to export either keyframes or samples.
Keyframes exports the actual keyframes of the animation. Every moment where a keyframe is set for at least one bone is considered a keyframe.
Samples creates new keyframes for the animations that are exported, by chopping up the entire action in subdivisions equal pieces. The number of keyframes that are exported for an animation is subdivisions+1, including one at the start (SMF keyframe time 0) and one at the end (SMF keyframe time 1).
This value isn't used directly by the exporter itself. It corresponds to SMF's Sample Frame Multiplier setting.
The value that you define here is the sample frame multiplier value that gets exported for each animation.
Enable the following Armature Options when importing models:
Fix Leaf BonesFind Bone Chains
TODO
TODO
Blender uses bones while SMF uses nodes. Because Blender has no concept of nodes - it does mention joints - it means that two bones that have their head joint in the same location don't have a shared parent node.
Because of this you should make sure to have a single root bone in Blender that acts as the root node in SMF. The root bone's head is never exported.
Blender allows for disconnected bones (see the Blender manual page on Parenting). This Blender feature largely corresponds to the detached nodes feature of SMF.
Since, in the general case, bones' tails are exported the exporter inserts an additional SMF node for each disconnected bone to represent its head. This way, the rig comes out identical. The special case is the root bone, which acts directly as the root node.
All bones must have their scale set to 1 and scale cannot be animated (i.e. keyframed). This is because of how the SMF format stores transforms: as dual quaternions. Dual quaternions store a translation in the first quaternion (the real quaternion) and an orientation in the second quaternion (the dual quaternion), they cannot store a scale factor.
This means that:
- Any scaling you do to bones must be applied. The bone scale of all bones to be exported must be 1.
- Bone scale cannot be animated, i.e. an animation cannot contain any
Scalekeyframes (see Manipulating Keyframes).
You should make sure to use images with dimensions that are a power of two. Models that have texture images with different dimensions might not display correctly.
Constraints are currently not supported by the exporter but will be considered in a future update.
Modifiers are not applied in version 0.8. They are applied in version 0.9.
Blender 4.1 changed how auto smoothing works. In versions up to 4.0, Auto Smooth and the Auto Smooth Angle were a property of the mesh. These properties were removed and replaced by the Smooth By Angle Modifier. The exporter will not call Mesh.calc_normals_split() when the Blender version is greater than or equal to 4.1. The exported normals will still be correct though.