MMD Tools/Manual for v1

This page is the manual for older versions.
See the MMD Tools/Manual for MMD Tools v2 or later.

#### Create Model

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).

#### Convert Materials for Cycles

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.

#### Separate By Materials

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

*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.

#### Attach Meshes to Model

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).

#### Apply and Clean Bone Constraints

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.

#### Build and Clean Rigid Body

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.

#### Import Model

Imports a model intended for use with MMD (.pmx or .pmd) into Blender.

##### Mesh/Armature/Physics/Display/Morphs

By disabling any of these buttons you can limit which elements of a model are imported into Blender. By default, all elements are imported.

##### Scale

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.

##### Clean Model

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.

##### Remove Doubles

When checked, vertices in the same location will be merged, duplicated faces will be removed.

##### Fix IK Links

When checked, the bone's tail of IK links will be corrected.

##### Rename Bones

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.)

##### Use MIP maps for UV textures

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.

##### Influence of .sph and .spa textures

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.

##### Log level and create log file

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 .

#### Export Model

##### Scale

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.

##### Copy Textures

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.

##### Sort Materials

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).

##### Visible Meshes Only

When checked, the hidden/invisible meshes will not be exported.

##### Sort Vertices

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*.

##### Log Level

As with importing a model. If enabled, a log file will be written to the destination directory.

#### Import Motion

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

*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.

##### Margin

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

*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.

##### Treat Current Pose as Rest Pose

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.

##### Mirror Motion

If enabled, the motion will be imported by using X-Axis mirror.

##### Update Scene Settings

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.

#### Export 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

*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

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*.

#### Using Material, UV, Bone and Group Morphs

**Bind** allows you to use morphs other than vertex morphs in Blender.

By bind, a mesh named `.placeholder` is added to the model.
`.placeholder` has all kinds of morphs as shape keys, including vertex morphs.

### Rigid Bodies

This subsection provides a list of rigid bodies contained in the selected model. They can be rapidly selected from this panel.

### Joints

This subsection provides a list of joints contained in the selected model. They can be rapidly selected from this panel.

### Material Sorter

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

*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

*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.

## Properties Window

### Materials

#### MMD Material

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.

#### MMD Texture

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.

### Object

#### MMD Model Information

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.

#### MMD Rigid Body

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.

#### MMD Joint

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.

### Modifiers and Vertex Groups

#### mmd\_bone\_order\_override

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\_edge\_scale

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\_vertex\_order

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.

### Shape keys and morphs

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.

## Outliner

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.

## Properties Shelf

### MMD Display

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

*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.

### MMD SDEF Driver

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.

## Add-on Preferences

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.

### Shared Toon Texture Folder

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. (`toon01.bmp` ~ `toon10.bmp` files are included)

### Base Texture Folder

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.

### Dictionary Folder

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.

### Non-Collision Threshold

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.

## Known Issues and Common Problems

### Texture Export

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.

### Bones and Posing

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.

### Custom Normals

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.

### Precision and Mirroring

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.

### Export as previewed

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.

### Texture Seams

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.

### Weight Painting and Vertex Groups

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 Body Animation

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

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

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.

### Shared Toons

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.

### Improper display of Japanese language

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.

### UV Morphs

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 morphs.

### Rigify

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.

### Registering frames for morphs other than vertex morphs

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 .