Documentation
MMD Tools is a blender addon for importing and exporting model or motion data related to MikuMikuDance. As it is under ongoing development as of writing (8 November 2016), it is recommended that you download the dev_branch of mmd_tools, available at https://github.com/powroupi/blender_mmd_tools/archive/dev_test.zip .
To install MMD Tools to Blender 2.78, copy the "mmd_tools" folder, contained inside the blender_mmd_tools folder, to \2.78\scripts\addons, then enable MMD Tools in Blender from the Add-ons tab of the User Preferences dialog. For other versions the version number directory will vary according to that version (E.g. in 2.73 the path will be \2.73\scripts\addons).
- Installation Nodes:
-
Please DO NOT install multiple versions of
mmd_tools, they will conflict each other. -
Please DO NOT rename
mmd_toolsfolder to any other names, otherwise it will not work. - Do not directly install the zip file you downloaded. Extract & Copy the mmd_tools folder contained inside the zip file to Blender's addon path instead. (see 3rd Party Add-ons & Add-on Directory)
-
Please DO NOT install multiple versions of
On installation, MMD tabs will become available from the Tool panel, MMD Display/MMD Shading/MMD SDEF Driver subsections will appear on the Properties shelf, MMD Material and MMD Texture subsections will open for the Materials section of the Properties window, and a MMD Model Information subsection will open for the Object section of the Properties window. When a joint or rigid body is selected, additional subsections will open in the Object tab of the Properties window.
This creates the heirarchy structure necessary to the successful export of an MMD-style model, as well as the root bone MMD requires. Along with Import Model (below), it is one of two ways to create a model understood by mmd_tools to be an MMD-style model. It does not create any meshes. To attach meshes to this structure, use Attach Meshes to Model (below).
Cycles is an alternate renderer for Blender that handles materials differently than the default Blender Internal rendering engine. Convert Materials for Cycles will convert the material settings of a selected MMD-style model to a format appropriate to Blender Cycles.
Imported models are stored as a single object by default. To rapidly separate each material in a model into a separate object, select the model, then Separate By Materials. By default, shapekeys will be removed from any meshes no longer affected by those shapekeys in order to prevent some issues with Blender's corruption of vertex morph data.
Join Meshes is the reverse of Separate By Materials. To rejoin all objects making up an imported model, select any object belonging to that model, then Join Meshes. The model will recover all objects that have ever been a part of it and join them into a single object.
This will locate any meshes not part of an MMD-style model and attach them to the last material in the selected imported model. To use this, select any part of any MMD-style model and Attach Meshes to Model. There's no need to select any of the new meshes you wish to attach. Meshes already part of an MMD-style model will not be affected (for instance, if you have imported two separate models into a single Blender scene.)
If you are attaching to an MMD-style model that contains meshes, you may instead select the mesh you wish to attach and the model to which you desire it attached, then join those objects (ctrl-J).
MMD and Blender handle bone appends in different ways. To translate between these, use Apply to translate appends into a form usable by Blender or Clean to translate appends into a form usable by MMD. Bones will be cleaned automatically upon export.
Just as with bones, physics are handled differently by MMD and Blender. Use Build to translate physics information into a form usable by Blender and Clean to translate physics information into a form usable by MMD. Built physics can reduce performance significantly. It's recommended to only build rigids when necessary-- generally, immediately prior to rendering.
Imports a model intended for use with MMD (.pmx or .pmd) into Blender.
By disabling any of these buttons you can limit which elements of a model are imported into Blender. By default, all elements are imported.
Applies a scale (centered on the origin) to all elements of the model. Smaller numbers lead to smaller imported models. Default value is 1.0.
When checked, mmd_tools will attempt to repair invalid faces and vertices upon import. It is nevertheless recommended that you validate and, if necessary, repair any model prior to importing into Blender.
When checked, vertices in the same location will be merged, duplicated faces will be removed.
When checked, the bone's tail of IK links will be corrected.
This will rename bones that use the standard MMD right/left nomenclature into a system that Blender can recognize, permitting appropriate mirroring. (The export script will automatically revert names from saved versions.)
When checked, mmd_tools will generate mip-maps for the model's main texture. The method for generating mip-maps can lead to artifacts, and so you may wish to disable this.
These will reduce the influence of attached sphere textures, lightening multiplicative spheres and darkening additive spheres as the influence is reduced. This is the same as reducing the diffuse color under the influence subsection of the specific texture in the Properties window. This will not affect exports of the imported model.
Specifies the verbosity of feedback from importing. If enabled, the log file will be written to the same directory as the model being imported, in the format [model file name].mmd_tools.import.log .
Applies a scale (centered on the origin) to all elements of the model. Smaller numbers lead to smaller exported models. Default value is 1.0.
If enabled, any texture images referenced by the model will be written to the appropriate directory, relative to the exported model. Existing files will be overwritten. Even if a Base Texture Folder has been specified (below), textures will never be written to that folder, but only to the appropriate directory for the model based on its export path.
When Sort Materials is enabled, mmd_tools will attempt to re-order your materials in a way least likely to cause transparency problems. It does not take vertex or material morphs into account, and is less reliable than specifying a particular order via the Material Sorter (below).
When checked, the hidden/invisible meshes will not be exported.
By default, mmd_tools does not pay attention to vertex order, and may export vertices in any order that it deems fit. This may affect some effects used via MME. To write vertices in the original order from an imported file, enable Custom. To write vertices in an order sorted by Blender, enable Blender.
As with importing a model. If enabled, a log file will be written to the destination directory.
Allows you to load a .vmd file as a set of animation keyframes into Blender. To load an animation, begin by selecting a valid MMD model, such as one that has been imported, by selecting the base parent object from the Outliner (see below). Then Import Motion.
Motions can also be imported onto Camera objects. This will convert them to MMD Camera objects. Select a Camera object (the main parent), then Import Motion, selecting an appropriate .vmd. Import options are the same as when importing an animation onto a model.
Scale will be applied to any bone movement. Smaller numbers create smaller movements. It's recommended to use the same scale with which a model has been imported.
If a Margin is specified, a number of empty frames (equal to the Margin) will be inserted at the beginning of the animation, before the initial, imported keyframe.
Bone Map determines how bones specified in a .vmd will be mapped onto an armature. With Renamed Bones, the motions bone identifiers will be renamed on import in the same manner as for models imported with Rename Bones (above), then applied based on the model's bone names in Blender. With PMX, the motion's bone names will be checked against the model's stored bone names, rather than Blender's displayed bone names. With Blender, the motion's bone names will be checked against the actual names of bones used in Blender.
If enabled, current model pose will be treated as its rest pose. Useful for importing T-pose based motion to A-pose based model, etc.
If enabled, the motion will be imported by using X-Axis mirror.
If enabled, this will tell Blender to use 30 frames per second. The frame range will also be expanded as necessary to include the complete imported motion.
Basic support for exporting motions is now available. Currently, it can export bone animation, shape key animation, and camera/lamp animation, but self shadow, and other vmd specific animations are not supported yet. Also keep in mind these notes/issues:
- Support f-curves only, drivers or NLA tracks are not supported. You may bake the animation to a new action if you want to export a final animation.
- The interpolations of bone rotation and camera rotation may not look right, since MMD use the same interpolation for all channels of rotation (x, y, z, w).
- In blender, select root empty object to export model animation (bone and shape key), select armature object to export bone animation only, select mesh object to export shape key animation only, select MMD camera object to export camera animation. And only active object's animation will be exported.
- Bone names are limited to 15 bytes (about 7 words of unicode character), there is no error message, just remember to keep bone names short.
Display Items allows you to edit the display panel necessary for MMD's handling of animation. The top panel allows the selection or creation of display groups that may be selected, edited, reordered, deleted, or created. The bottom panel shows the elements of that group, which may be similarly selected or edited. Note that selecting, for instance, a bone and changing its type to Morph will lead to problems with MMD.
When a bone entry has been selected, its corresponding bone can be rapidly selected from the Display Items subsection through the Select button.
Morph Tools allows you to edit the MMD specific paramters of morphs. Blender respects only vertex morphs, in the form of shape keys (see below). However, morph parameters should be preserved through import-export cycles, and can be edited from this panel. If a morph is not yet placed in the display panel, an i icon will be displayed to the right of the morph in the topmost panel of Morph Tools.
This subsection provides a list of rigid bodies contained in the selected model. They can be rapidly selected from this panel.
This subsection provides a list of joints contained in the selected model. They can be rapidly selected from this panel.
For situations where it is important (generally having to do with transparency), Material Sorter allows specification of material order. It will allow sorting of any materials contained within a single object, and so is no longer of use once a model has been separated by materials.
Meshes Sorter allows rapid selection of any of the sub-objects of an MMD model, for use after it has been separated by materials. Changes to the order of the meshes will be maintained through exports or Join Meshes (above).
Bone Order allows you to check the bone properties that affect the model's behavior on the MMD which uses different bone system. The bone order is stored in the vertex groups of the first mesh object which has a modifier named mmd_bone_order_override on it of your model. Although you can rearrange bones in Blender via this panel, PMXEditor is a better choice since you can check the result immediately.
Using the information in the MMD Material subsection of the Material tab of the Properties window, you may alter any of the material parameters used by MMD. Note that while changing any of these will affect both the Blender render and any exported model, changing Blender specific alternatives will affect only the Blender render, but not any exported model. For example, changing the Specular Color field of MMD Material will change Blender's specular highlights (in the Specular field of the Specular subsection), but changing Blender's Specular will not change the Specular Color in MMD Material. Edge Line is not implemented in Blender rendering by mmd_tools, but edge related changes made in the MMD Material subsection will affect exported models.
The MMD Texture subsection of Materials allows specification of the fields and flags used for texturing MMD models. As with MMD Material settings above, mmd_tools will propagate changes made in this subsection to other elements of Blender, but not vice versa. That is to say, changing the sphere blend mode in MMD Texture will affect Blender's render, but changing Blender's render by changing the blend mode in Texture/influence will not affect MMD Texture settings, nor any exported models.
This allows one to edit the various model-specific fields used by MMD models. Change MMD IK Loop Factor applies a multiplier to the Blender iterations of all IK bones (not just those selected), and is only accessible when a bone or armature has been selected. It will affect only animation in Blender, and not any exported model.
Contains information regarding rigid body objects, built or unbuilt. As with MMD Materials, changes made in this subsection will affect Blender's physics, but changes made in Blender's physics elsewhere will not affect this subsection, and will not export with a model. Some changes will take effect regardless of whether rigid bodies have been built, but some will not. It's recommended to rebuild rigid bodies after making any changes to this subsection.
Contains information regarding joint objects. As with MMD Materials, changes made in this subsection will affect Blender's physics, but changes made in Blender's physics elsewhere will not affect this subsection, and will not export with a model.
Due to the different ways that Blender and MMD handle bones, bone order is of little importance to Blender but of potentially large importance to MMD. In order to preserve bone order through import/export cycles, imported models are generated with the mmd_bone_order_override modifier. So long as this modifier exists unapplied on even a single object contained in the model, mmd_tools will use this on export to restore bone order, to the extent allowed by edits made in Blender.
If bone order is unimportant for your model, you may safely delete or apply this modifier.
mmd_tools keeps track of the edge scale vertex attribute used by MMD models through the mmd_edge_scale vertex group. If a vertex is deleted from this group-- or the entire group itself is deleted-- mmd_tools will provide the default edge scale of 1 on export. If your model does not take advantage of per-vertex edge scale, you may safely delete this vertex group. Be aware of how this vertex group may affect weight normalization and Limit Total vertex groups actions (below).
mmd_tools keeps track of imported vertex order via the mmd_vertex_order vertex group. As with mmd_edge_scale above, this vertex group is safe to delete if you are not concerned with vertex order, and as above, be aware of its effects on editing weights within Blender.
MMD's vertex morphs are represented by Blender's shape keys. New shape keys that are created within Blender will be exported as vertex morphs. These morphs will be exported to morph group 4 (lower right). Newly created shapekeys will not be available as morphs to functions like Display Items (above) until they have been exported to an MMD format and then re-imported.
All models require a Basis shapekey to properly export into the .pmx format. If your mesh does not possess a Basis, one can easily be created from the Shape Keys subsection of the Data tab of the Properties window, with a mesh selected. Hit the + button to create a new shape key; if none yet exist, this will be created as the Basis key. (This is most frequently necessary when shape keys have been deleted in order to apply modifiers.)
There are 3 shape keys created by mmd_tools to preserve SDEF information. While Blender does not respect SDEF deformation itself, mmd_tools will use these shape keys to preserve SDEF through import/export cycles. Any bones moved in Blender will not update SDEF information; you will need to update SDEF centers in an application like PMXE instead.
At this time, the only support mmd_tools provides for other kinds of morphs (bone morphs, material morphs, etc.) is through the editing panels on the toolbar. These morphs are not linked to the appropriate properties for imported models, and imported animations will not create registrations for any morphs other than vertex morphs.
Understanding the hierarchy with which mmd_tools imports and creates models can be important. Models with an improper hierarchy may not export or animate properly.
Each model consists of a single base parent object which contains [modelname]_arm, joints, rigidbodies, and sometimes temporary children. Joints and rigidbodies contain children holding MMD relevant (unbuilt) data for each. When rigid bodies are built (above), the main parent and the temporary child are populated with Blender-friendly objects that enable physics. By default, joints and rigidbodies groups are not displayed in the preview; these objects can be viewed by clicking the eye (preview) icon to the right of each on the Outliner panel.
[Modelname]_arm contains mesh, bone, modifier, and vertex group data. By default, [modelname]_arm is hidden, while its child [modelname]_mesh is displayed in the preview. Bones can be viewed by unhiding [modelname]_arm, and are contained in a nested hierarchy within the Pose child of [modelname]_arm. [Modelname]_mesh is another child of [modelname]_arm which contains object modifiers, vertex groups, and all meshes, organized by material. These meshes are in the [modelname] child of [modelname]_mesh. Each mesh (material) also has texture image data as a child.
When an MMD-style model is selected, the MMD Display subsection of the Properties shelf allows rapidly hiding or revealing elements of the model, including the mesh, armature, rigid bodies, joints, temporary objects, and names. Rendering of toon textures or sphere texture can be enabled or disabled as well. This is on a model-by-model basis, and only the selected MMD-style model will be affected.
MMD Shading allows you to choose two alternate shading styles for your MMD models. GLSL uses the same system as Blender's GLSL shading and adds a hemispheric light to the scene to more closely resemble default MMD lighting. Shadeless is a style that ignores shadowing, shading only via any Toon texture. Reset will reset shading to default Blender shading and return Viewport Shading to Solid. Unlike MMD Display, MMD Shading options will affect the entire scene, and not just a selected model. Note that missing texture images under either of these shading modes will create a magenta warning, when they won't under the default Blender shader.
When an MMD-style model is selected, the MMD SDEF Driver subsection of the Properties shelf allows binding/unbinding MMD SDEF data of selected mesh objects. Enable Auto Run Python Scripts is required for proper functionality.
By clicking the triangle to the left of mmd_tools's entry in the Add-ons tab of the User Preferences dialog, you may access version information and preferences.
This allows you to specify the folder where shared toons are stored so that they may be properly rendered by Blender. Typically this should be a folder like MikMikuDanceE_[version]\Data.
When a Base Texture Folder has been specified, mmd_tools will be used to determine the relative path of the textures of the exported models (the base folder part will be removed from the path). For example, if C:\texture has been specified as the Base Texture Folder, C:\texture\sphere\starry.spa will be exported as sphere\starry.spa, relative to the model and export directory. This allows you to customize the directory layout of the textures.
This allows you to specify the folder where csv dictionaries are located so that you can use custom dictionary instead of internal dictionary to translate names.
This allows you to specify the distance threshold for creating extra non-collision constraints while building physics. The larger the value you specify, the more extra non-collision constraints may be created.
Some objects that can be generated or imported into Blender have integrated images. These images will not always be exported in an MMD-friendly file format. This can cause display errors in MMD or other editing applications. If you are encountering errors after generating a new MMD model with texture export, please verify that these textures are in MMD compatible file formats and convert them as necessary, or delete the textures from the impacted materials.
Blender and MMD sometimes handle bones in very different manners. While most basic bone structures are handled properly in Blender with mmd_tools (i.e., identically to MMD), some more complicated structures may not be.
mmd_tools defaults to a posed model. When IK bones are not placed in default locations identical to their IK targets, or differences in Blender's handling of bones leads to disagreement with the default pose, models may become deformed when there was no intention to do so. In order to prevent this issue and guarantee that your mesh isn't suffering any unexpected deformation, you may want to place your model in rest position. The easiest way to do this is to select your armature from the outliner by clicking on [modelname]_arm, then switch to the Data tab of the Properties window. Under the Skeleton subsection, click the Rest Position button to prevent any accidental pose.
MMD models can contain custom normal data for each vertex. mmd_tools handles this via Blender's Custom Split Normals Data. Unfortunately, Blender's handling of this data can easily lead to difficult-to-fix artifacts when vertices are merged, leading to Blender adopting one or the other custom normal rather than averaging them. Prior to merging vertices, it's advised that you clear custom split normal data. You can do this by selecting one or more vertices then, on the Geometry Data subsection of the data tab of the Properties Window, clicking the Clear Custom Split Normals Data.
Blender and MMD do not use the same precision for their data. This can lead to slight shifts in position. These shifts are normally far too small to be meaningful. However, they can be enough to break mirroring.
In general, mmd_tools will attempt to export a model as it is displayed in the preview. Shapekeys and modifiers that are previewed, but not necessarily applied, may affect an exported mesh. However, in some situations, unapplied modifiers may not export properly. If you find this to be the case, you may need to apply the modifier. Unfortunately, this will require deleting all shape keys from the relevant object, and then recreating a Basis shapekey after the modifier application to enable export.
mmd_tools exports materials with UV seams by duplicating vertices that lay along those seams. If autosmooth is enabled, Blender can easily create inappropriate normals for these vertices. If you are having this problem, you may wish to disable autosmooth, or merge these vertices any time Blender separates them; mmd_tools will handle their separation at time of export, when it will preserve their (merged) normals. Alternatively, these normals can be fixed relatively easily in an application like PMXE through the Join Near Normals operation.
One of the major advantages of editing MMD models in Blender is the ease with which BDEF4 weights can be created and edited. However, there are a number of pitfalls of which to be wary.
It is easy to create a vertex in Blender that is weighted to more than four bones, but MMD is limited to BDEF4. When mmd_tools encounters a vertex weighted to more than four bones, it drops the least influential, then renormalizes, but this renormalization may lead to problems. Before exporting, it's recommended that you use the Limit Total tool from the Weight Tools subsection of the Tools tab of the Weight Painting toolbar, limiting yourself to 6 vertex groups. Keep in mind the additional vertex groups of mmd_edge_scale and mmd_vertex_order. The default locking of these groups will not prevent them from counting toward the limited total. If you have deleted one or both of these vertex groups, adjust your limit appropriately.
It's also easy to create weights that are not normalized in Blender. Although mmd_tools should now renormalize these weights properly, provided that vertex groups are appropriately limited, you may wish to normalize them manually. Unfortunately, the default locking of mmd_edge_scale and mmd_vertex_order will not prevent them from factoring into the Normalize All tool (accessed from Weight Tools subsection of the Tools tab in Weight Painting mode) in Blender 2.77. If you need to normalize weights in Blender, you will need to delete these two vertex groups.
Rigid bodies that are generated in Blender may need some time to adapt to an imported motion. This is especially true when the origin of the imported motion differs significantly from the origin of the model onto which the motion is imported. Use of the Margin import parameter can be used to give physical bodies a chance to relax before the main animation begins.
Pasting flipped poses in Blender may lead to inappropriately renamed bones. For now, you are advised to avoid pasting flipped poses. If this is unacceptable, you may find that importing models and motions with Renamed Bones enabled solves the issue. In Edit mode of an armature object, [Armature]->[Symmetrize] may lead to the same issue on Blender 2.83+, you may use X-Axis Mirror as an alternative tool.
Lat models are designed for a very cartoonish look through the use of multiple transparent layers. With default settings, they won't look right in Blender. Good effects have been realized through enabling Backface Culling on the Shading subsection of the Properties shelf and Shadeless on the MMD subsection of the Properties shelf.
In order to properly render shared toons (represented by Toon01.bmp through Toon09.bmp in typical MMD models), it's necessary to make changes to User Preferences.
mmd_tools currently uses Japanese names for elements of MMD models, but you may need to make changes to Blender's preferences in order to properly display Japanese characters. In order to do so, navigate to the System tab of the User Preferences dialog and enable International Fonts.
mmd_tools stores UV morph offset data in Vertex Groups with the names in the form of UV_[morph name][axis], axis is one of {'+X', '-X', '+Y', '-Y', '+Z', '-Z', '+W', '-W'}. To edit UV morphs via mmd_tools in normal way, see tutorial How-to-create-and-edit-Material-morphs,-Group-morphs,-Bone-morphs,-UV-morphs.
mmd_tools creates custom bone properties that can cause errors when generating a rig from a Metarig with the Rigify add-on. To prevent errors, please click [Apply]/[Clean] Bone Constraints via mmd_tools Operator panel or disable mmd_tools whenever using Rigify.
mmd_tools will register frames for morphs from imported animation if and only if a shapekey named appropriately is present. If you would like to register frames for other kinds of morphs and create your own drivers, consider creating appropriately named shapekeys-- perhaps just copies of the basis shapekey-- in order to capture these registrations. For information on using shapekey registrations in drivers for other properties, see https://blender.stackexchange.com/questions/42390/how-can-i-set-a-shape-key-value-to-be-a-drivers-variable .
We are migrating the documentation: MMD & Blender Wiki in English / MMD & Blender Wiki in 日本語