Documentation

Introduction

This is the main documentation of Mustard models. If you are using these models for the first time, I highly suggest to quickly go through the main points (expecially Requirements and Performance), and use the other sections as a reference when you need more information about a specific feature.

Note: Each model has a so-called Generation, which is the general set of features of the model. In general, the bigger the Generation number, the better and more updated should be the model.
If you are unsure which Generation is your model, you can check if it is available in the model list or in the old model list. If you got the model from different sources, it is likely the model is Generation 2.

Requirements

A rough estimation of the PC requirements is the following.

  • Ryzen or Intel 7000 CPU, with at least 4 cores.
  • AMD or Nvidia GPU with at least 8Gb of VRAM. If you have less VRAM and you encounter crashes on renderings, consider to downgrade the quality of the textures to 2K (see FAQs, Renderings stop with Out of Memory errors). Integrated GPUs might not even allow you to load the model in Viewport.
  • 16 Gb of RAM.
  • Free space on disk to make the swap memory do its work! Thus I advise you to work an SSD.

Software Requirements

Blender Add-ons Requirements

Model GenerationDiffeomorphicMHX
Generation 2Compulsory 1.5.1cNot needed
Generation 3Optional 1.6.1 or above*Compulsory**
*: the installation is advised if you want to use some additional features of Diffeomorphic.
**: the IK/FK panel is only available in the MHX panel, and not in the MustardUI.

Note: remember to enable the add-ons after installing them!

If you don’t know how to install an addon, check the related Blender documentation page (or simply find a quick video googling it).

Preliminary Steps

Before using the models, be sure to check the requirements. Moreover:

  • put the textures and the model .blend file in the same folder. If for any reason the models has some pink textures, check that the textures are available in the same folder as the .blend file in a “textures” folder. You can also force Blender to search the missing textures with the operator Find Missing Files.

MustardUI and Tools

The models are using the MustardUI as main UI to change most of the model properties. Press N in the Viewport to show the panels on the right, as in the image.

Some guidance notes.

  • Properties/tools that can affect performance if activated/deactivated, are colored in red, to be more easy to spot in the text.
  • If (Advanced) is in front of a property, it will be available only if Advanced settings is enabled (see Settings panel in MustardUI).
  • If you put the mouse over any property in the MustardUI and you wait some instants, an explanation of what that propery is doing will appear.
  • If you have more MustardUI enabled models on the scene, and Viewport Model Selection is deactivated (see Settings section of the documentation), there will be an additional first panel where you can choose whose the model considered by MustardUI.

In the Body properties, you can find all the properties related to the main character mesh and shaders.  The list of tools/options is:

  • Smooth Correction (if available): it can decrease performance if activated. It smooths the mesh when you bend it with the armature or other modifiers before the Smooth Correction modifiers in the modifier stack. I suggest to disable it during production, and enable it only when you need the final details of collisions (for instance the skin on a outfit) and for renderings.
    Note: it is extremely important to disable Smooth Correction before sculpting!
  • Normals Auto Smooth: it can decrease performance if activated. Also note that from 3.1, activating this option you will effectively turn off the possibility to use GPU subdivision for the body. I suggest to turn this off always during production, and eventually activate it before renderings.
  • Eevee Optimized Normals: only during Material Preview and Rendered viewport options (with Eevee), it can increase performance if activated. If disabled, the material uses the standard Normal nodes which are default on Blender. When enabled, a custom Normal node is used to optimize the viewport Eevee rendering. I suggest to enable this option when you animate, if you need to use Material Preview or Rendered options in Viewport, and disable it before renderings.
    Note: if deactivated, also the outfits normal nodes will be changed to the custom node.
  • Subdivision Surface: it decreases performance when activated. It smooths the mesh, at the cost of a high impact on performance. The bigger the level, the smoother the mesh will be, but also the performance hit. I suggest to enable it only when you need to check the details of collisions (for instance the skin on a outfit) and for renderings.
    Note: disabling this for renderings, if the model uses Random Walk Subsurface Scattering, might create visible artifacts on the skin!
  • The remaining sections can contain various properties of the model, and depends on the model considered.

Note: some properties might be hidden until Advanced options is enabled (see Settings section of the documentation). For instance, the shader options of most of Mustard models are not available if Advanced options is disabled.

In this section you can find the Morphs available, and related tools.

  • Morphs main switcher: the button near the Morphs panel activate/deactivate the morphs for the selected character. In order to use this button you should select the armature related to character considered. Activating the morphs can have a great negative impact on performance. I suggest to disable them when making the main animation, and switch it on for facial animations.
    Note: disabling Morphs will effectively disable all morphs you enabled on the character. But the values of your morphs will not be deleted, if you re-enable the morphs they will be re-activated. Since the face rig drives the morphs, it will not work when Morphs are deactivated.
  • In the morph panel, you can find some additional functions, on the right of the Search Button.
  • Filter button: It allows to show in the Morphs list only the morph which have a value different from 0, and it can be useful to quickly check which morphs are active.
  • Restore button: it restores the value of all morphs to 0.
  • Clear pose button: it restores the pose of the character. back to the rest pose. This operator can also be useful to restore the character bones position if they get stuck to some uncorrect values after using/importing poses and actions.
  • Settings: the settings button opens a box with additional options for Morphs. See the list below for more informations on the single settings.
  • Mute Shape Keys: if enabled, shape keys will be muted when you disable the Morphs. If you want to preserve the values of the shape keys, or use them when the morphs are disabled, you can turn this off. Note that turning this off might have some impacts on performance, but in general it should be negligible.
  • Mute Corrective Morphs: if enabled, Corrective Morphs will be muted when you disable the Morphs. Note that depending on the outfits available, disabling this option might lead to performance decrease. If this happens, consider deleting the outfits you will not use the scene.
  • Mute Face Controls: if enabled, Face controllers (and FACS emotions) will be deactivated to improve performance. If disabled with Mute Face Controls Bones enabled the impact on performance will be minimal, but some controllers that rely on bones (i.e. jaw and eye controllers) might not working correctly. If you disable Mute Face Controls Bones, all controllers will work with a bigger impact on performance. However, even with both Mute Face Controls and Mute Face Controls Bones, their overall impact on performance should be smaller than not disabling all Morphs.

In this section you can change outfits and their properties (global and outfit-specific).

  • (Advanced) Disable Armature Modifiers button: if enabled, Armature modifiers are disabled for outfits that are not used to increase performance.
  • Outfits List: this is the list of all available outfits. Choose one to get the list of available pieces: clicking on the piece name you can activate/deactivate them.
    Near the outfit name it might appear a cogwheel, which explode a list of properties that affect all outfits pieces. Another cogwheel might be available on each outfit piece, and these properties will affect only this specific piece.
    Moreover, an “unlocked” lock is available. Clicking on it, the outfit piece will be kept even if you change the outfit in the outfit list. The “locked” pieces can be found in a list that appears after the current outfit pieces list. Clicking on the “locked” icon, you can remove the outfit and it will not be visible until you go back to the outfit which contains it.
  • Outfit Global Properties: in general, all the properties in this section affect performance negatively if activated. For the Smooth Correction and Normal Auto Smooth, the explanation is the same as in the Body properties section. The Shrinkwrap helps the outfits not to clip in some specific poses, and it can be switched off during production. The Mask modifiers hide some parts of the body mesh when specific outfits are active: I suggest to turn it off during production as they can negatively impact performance.
  • Extras: this list contains all the outfit pieces that are not part of a set, and in general can be used in pair with all other outfits (for instance a pair of glasses).

In this section you can find the list of all hair styles and the particle hair systems on the main body mesh.

  • (Advanced) Disable Armature Modifiers button: if enabled, Armature modifiers are disabled for hair that are not used to increase performance.
  • Hair List: select the hair you want to see on the character. There are also some visibility buttons on the right, to hide the hair in viewport/render. I suggest to always keep the render option on (to not forget to enable it before renderings!), and disable the hair during production since their rendering can negatively impact performance.
  • Hair Particles: select the particle hair to render in viewport/render mode. Enabling particle hair can have a great impact on performance, and thus my advice is to enable them only for renderings.

In this section you can find the list of all layers of the character. You can safely switch them on/off depending on the bones you need, no performance impact here!

The Simplify function can be used to disable most of the heavy features of the model that might not be useful when you are animating. Some of the options work only when enabling Simplify, and won’t be reverted. Check the descriptions for more informations (put the mouse over the property without clicking).

Some of the less self-explicative options are:

  • Blender Simplify: the Blender default Simplify. All subdivision modifier levels will be lowered to the Max.
  • Affect Eeeve Normals optimization: increases performance in Material Preview Viewport mode. For more information, check Eevee Optimized Normals in Body Properties.
  • Disable Physics: all Physics modifiers (including Collisions) are disabled. This works only when enabling Simplify, and the settings are not reverted when disaling Simplify.

Note: When you enable/disable the options, Blender might hang while updating the Simplify options.

In this section you can find some additional Tools.

  • Parent bones: with this tool you can select two bones to quickly parent the second to the first via Child Of modifiers.
  • Auto Breath: select a bone and click on Auto Breath to quickly create a breathing animation. The bone should have locked all transformations that are not needed for driving the breathing, and the min/max values should be 1 (no breath) and 2 (full breath).
    You can also adjust some settings. If you put the mouse over the properties and you wait a couple of instants, an explanation will appear. Check also this video.
    Note: the framerate interval considered is the one of the current scene.
  • Auto Blink: select the blink length factor (time to complete a blink) and the blink chance (number of blinks per minute), and click on Auto Blink to quickly generate a blink animation. Check also this video.
    Note: the framerate interval considered is the one of the current scene.
  • Lips Shrinkwrap: with this tool you can quickly create a shrinkwrap of the lips around an object. Check this video for instructions on how to use this tool.

In this section, some general UI options are available.

  • Advanced options: activating this option, some Advanced options will appear in the UI.
  • Maintenance options: some maintenance tool will appear in the UI, and in a list in the Setting panel itself. In general you will not need to enable this, unless you are asked to generate a log file or you want to clean the model (see below).
  • Debug mode: with this active, the verbosity in the console will increase. You will not need to turn this on unless you need to debug some UI errors. Turning this on might affect performance, as the UI will waste time writing log lines in the console, even if the console itself is not currently active.

If Maintenance options is active, some additional tools will appear.

  • UI Configuration: the UI will switch to Configuration mode. Please follow the instructions on the MustardUI GitHub page if you want to configure a new model or modify an existing model.
  • Re-build Custom Properties: if you remove by mistake some MustardUI related drivers, you can restore them with this operator.
    Note: if you changed the name of the object containing the custom property (for instance the material where a node properties was a MustardUI custom property), the operator won’t be able to restore it, and will clean all the reference in the MustardUI instead. In this case, a warning will appear and the list of errors will appear in the console. You will need to re-add the cleaned custom properties again.
  • Register/Un-register UI script: if registered, the UI will appear also if the model is appended. In general, there is no need to un-register the UI.
  • Clean Model: see the dedicated section below.
  • UI Removal: see the dedicated section below.
  • Create Log File: this will create a log file in the current .blend folder.
    Note: no personal information is logged (as you can see opening the generated file), and no file is automatically sent to any server.

Finally, some informations about the model and MustardUI versions are available in the last box.

Clean Model tool

You can find the Clean model tool in the Settings, after enabling Maintenance Tools.

The tools are the following.

  • Deleted Unselected Outfits/Extras/Hair: with this option you can delete all the Outfits/Extras/Hair from the scene, except the ones selected in MustardUI. The tool will completely delete all data related to those objects. You might need to go to File -> Clean Up -> Recursive Un-used Data Blocks to remove also materials and images associated with the objects.
  • Remove Body/Outfit/Hair Custom Properties: with this option you delete all custom properties of the selected categories from the UI. This will delete data only in the UI, and will not modify or delete any external object/property.
  • Remove Morphs: if the model has the Diffeomorphic support enabled, and you have Diffeomorphic installed, you can remove all the Morphs from the model. This might solve some stuttering and performance problems of the model, at the price of not being able to use the Morphs anymore. The tool will try to preserve the face controllers if Remove Face Rig Morphs is disabled (although some bone based controllers might not work after cleaning). Similarly, the tool preserves the corrective morphs if you deselect the Remove Corrective Morphs option. Finally, since the tool do not delete shape keys associated to Morphs by default, you can also decide to Remove Shape Keys from the model.
  • Remove Diffeomorphic Data: with this option you can delete all Diffeomorphic data on the model and the outfits. After using this option, you will not be able to use Diffeomorphic to import new outfits or morphs, and the Morphs panel will not be available in Diffeomorphic anymore. However, this tool do not remove Face controllers and Morphs. I advice to use this option before starting a still/animation to get some additional FPS (boost can vary from model to model), if you are sure that you do not need Diffeomorphic Tools anymore.

UI Removal tool

By default, this tool just removes the UI preserving settings (UI data) and all the Objects of the model. However, additional operations can be performed.

  • Delete Settings: all the UI data, such as Configuration settings, are deleted.
  • Delete Objects: all the model Objects (including Outfits, Hair and Extras) are deleted from the scene. This should prevent the presence of Orphan data if you want to remove the model from the scene. You might need to go to File -> Clean Up -> Recursive Un-used Data Blocks to remove also materials and images associated with the objects.
  • Delete Bones Custom Shapes: when deleting the model Objects, you can preserve bones custom shapes with this option. This should be deselected if custom bones are shared between different armatures in the scene.

Note: Even with Delete Objects and Delete Bones Custom Shapes selected, this tool might leave some Objects un-deleted. However, it should remove all Orphan data, i.e., data of Objects not available in the scene but still available in the file.

Armature and Poses

In this section you can find some informations about the Armature and the various features of the models.

In the MHX panel (it requires the MHX panel, check the Requirements section of this documentation) you can find most of the armature properties.

In the Properties tab you can for instance:

  • modify the parenting of the head
  • enable finger IK
  • enable/disable rotation limits
  • enable/disable limb stretchiness (if enabled, the mesh will stretch even if if the bone move beyond the leng/hand size)

Note: tongue IK at the moment is not available.

In the FK/IK Switch section you can:

  • switch FK/IK (for instance, in the image FK is active on all limbs)
  • snap the arm/leg bones to IK/FK position. This might be useful if you have a pose with FK mode, and you want to convert the same position of the arm/leg to IK

Some poses are available in a separate file, and will be available in the Asset browser. Check the Pose Library page for the download, installation and usage notes.

Shader

The shader available in the models is heavily optimized for Eevee, but it should work well also on Cycles. Moreover, although I tried to test the shader in different light settings, depending on the scene, the shader might need some tweaks. Some guidance notes.

  • Check the sub-surface scattering (Eevee and Cycles), as in some scenes it might be too low (the skin seems plastic) or too high (red zones on the skin). Especially in scenes with strong lights, you might need to tweak this option.
  • Tweak Normal Strength/Bump Strength/Micro Normals, especially if you are planning to render close-ups of the skin on Eevee.

Note: in some models you might need to activate Advanced options (see MustardUI – Settings section of this documentation) to see this shader properties in the Body panel.

Performance

Due to the high amount of morphs (and therefore Blender drivers) in the model, the model might be slow with default settings, especially if you plan to make an animation. The hints below will help you get decent performance during production!

  • Enable MustardUI Simplify (see Simplify in the MustardUI section).
    Alternatively, if Simplify is not available or you want to optimize the model manually, check these videos to help you tweak the performance of the model during production.
  • You can also enable, in the Render settings tab, Blender Simplify. Set Max Subdivisions to 0 (only for viewport). It is always better to disable Simplify before the final rendering.
  • Some add-ons are known to slow down the viewport when active, even if not actively used in the scene. Some of them are Wiggle bones and Spring bones. In general, it is always advised to disable all unused add-ons to reduce the probability of dealing with these issues.
  • A lot of outfits in the scene, even if disabled, can decrease viewport performance. Therefore, I advise you to delete the outfits you do not want to use in the current scene. If you want to preserve just one outfit, check the Clean Model function (check the Clean tool in the MustardUI – Settings section of this documentation).
  • If you don’t plan to use the available morphs or the face rig, you can always Clean the model (check the Clean tool in the MustardUI – Settings section of this documentation).
    Note: during clean-up, emotions and Face controls will be removed, but the standard face bones (based on weights, and colored green in viewport) will be preserved.
  • If the model crashes when rendering (Out-of-Memory errors), you can try to downgrade the textures.

Additional Useful Resources

Support and contacts

Obviously, you can also contact me if something is not a bug and the documentation is unclear.
Or just to say “hello”! 🙂