Branch: master
Find file Copy path
bbdbdee Jan 4, 2019
2 contributors

Users who have contributed to this file

@Darkblader24 @michaeldegroot
442 lines (321 sloc) 17.4 KB

Cats Blender Plugin (0.12.2)

A tool designed to shorten steps needed to import and optimize models into VRChat. Compatible models are: MMD, XNALara, Mixamo, Source Engine, Unreal Engine, DAZ/Poser, Blender Rigify, Sims 2, Motion Builder, 3DS Max and potentially more

With Cats it takes only a few minutes to upload your model into VRChat. All the hours long processes of fixing your models are compressed into a few functions!

So if you enjoy how this plugin saves you countless hours of work consider supporting us through Patreon:

Master branch:

Development branch:


  • Optimizing model with one click!
  • Creating lip syncing
  • Creating eye tracking
  • Automatic decimation
  • Creating custom models easily
  • Creating texture atlas
  • Creating root bones for Dynamic Bones
  • Optimizing materials
  • Translating shape keys, bones, materials and meshes
  • Merging bone groups to reduce overall bone count
  • Protecting your avatars from game cache ripping
  • Auto updater

More to come!


Check our website to report errors, suggestions or make comments!


  • Blender 2.79 or 2.80 (run as administrator)
    • mmd_tools is no longer required! Cats comes pre-installed with it!


  • Check your 3d view and there should be a new menu item called CATS ....w00t

  • If you need help figuring out how to use the tool:

VRChat - Cat's Blender Plugin Overview

Skip the step where he installs "mmd_tools" in the video below, it's not needed anymore!

VRChat - Importing an MMD to VRChat Megatutorial!

Code contributors:

  • Hotox
  • Shotariya
  • Neitri
  • Kiraver


This tries to completely fix your model with one click.

Import/Export Model
  • Imports a model of the selected type with the optimal settings
  • Exports a model as an .fbx with the optimal settings
Fix Model
  • Fixes your model automatically by:
    • Reparenting bones
    • Removing unnecessary bones
    • Renaming and translating objects and bones
    • Mixing weight paints
    • Rotating the hips
    • Joining meshes
    • Removing rigidbodies, joints and bone groups
    • Removing bone constraints
    • Deleting unused vertex groups
    • Using the correct shading
    • Making it compatible with Full Body Tracking
Start Pose Mode
  • Lets you test how bones will move.
Pose to Shape Key
  • Saves your current pose as a new shape key.
Apply as Rest Pose
  • Applies the current pose position as the new rest position. This saves the shape keys and repairs ones that were broken due to scaling

Model Options

  • Translate certain entities from any japanese to english. This uses an internal dictionary and Google Translate.
Separate by material / loose parts
  • Separates a mesh by materials or loose parts
Join meshes
  • Joins all/selected meshes together
Merge Weights
  • Deletes the selected bones and adds their weight to their respective parents
Delete Zero Weight Bones
  • Cleans up the bones hierarchy, deleting all bones that don't directly affect any vertices
Delete Constraints
  • Removes constrains between bones causing specific bone movement as these are not used by VRChat
Recalculate Normals
  • Makes normals point inside of the selected mesh
  • Don't use this on good looking meshes as this can screw them up
Flip Normals
  • Flips the direction of the faces' normals of the selected mesh.
Apply Transformations
  • Applies the position, rotation and scale to the armature and its meshes.
Remove Doubles
  • Merges duplicated faces and vertices of the selected meshes.

Custom Model Creation

This makes creating custom avatars a breeze!

Merge Armatures
  • Merges the selected armature into the selected base armature.
  • How to use:
    • Use "Fix Model" on both armatures
      • Select the armature you want to fix in the list above the Fix Model button
      • Ignore the "Bones are missing" warning if one of the armatures is incomplete (e.g hair only)
      • If you don't want to use "Fix Model" make sure that the armature follows the CATS bone structure (
      • DO NOT delete any main bones by yourself! CATS will merge them and delete all unused bones afterwards
    • Move the mesh (and only the mesh!) of the merge armature to the desired position
      • You can use Move, Scale and Rotate
      • CATS will position the bones according to the mesh automatically
      • If you want multiple objects from the same model it is often better to duplicate the armature for each of them and merge them individually
    • Select the base armature and the armature you want to merge into the base armature in the panel
    • If CATS can't detect the bone structure automatically: select a bone you want to attach the new armature to
      • E.g.: For a hair armature select "Head" as the bone
    • Press the "Merge Armatures" button -> Done!
Attach Mesh to Armature
  • Attaches the selected mesh to the selected armature.
  • How to use:
    • Move the mesh to the desired position
      • You can use Move, Scale and Rotate
      • INFO: The mesh will only be assigned to the selected bone
      • E.g.: A jacket won't work, because it requires multiple bones.
      • E.g.: A ring on a finger works perfectly, because the ring only needs one bone to move with (the finger bone)
    • Select the base armature and the mesh you want to attach to the base armature in the panel
    • Select the bone you want to attach the mesh to in the panel
    • Press the "Attach Mesh" button -> Done!
Support us:
  • We worked hard on this feature. If you like it consider supporting us, it helps a lot!


Decimate your model automatically.

Save Decimation
  • This will only decimate meshes with no shape keys.
Half Decimation
  • This will only decimate meshes with less than 4 shape keys as those are often not used.
Full Decimation
  • This will decimate your whole model deleting all shape keys in the process.
Custom Decimation
  • This will let you choose which meshes and shape keys should not be decimated.

Eye Tracking

Eye tracking is used to artificially track someone when they come close to you. It's a good idea to check the eye movement in the testing tab after this operation to check the validity of the automatic eye tracking creation.

Disable Eye Blinking
  • Disables eye blinking. Useful if you only want eye movement.
Disable Eye Movement
  • Disables eye movement. Useful if you only want blinking. IMPORTANT: Do your decimation first if you check this!
Eye Movement Speed
  • Configure eye movement speed

Visemes (Lip Sync)

Mouth visemes are used to show more realistic mouth movement in-game when talking over the microphone. The script generates 15 shape keys from the 3 shape keys you specified. It uses the mouth visemes A, OH and CH to generate this output.

Bone parenting

Useful for Dynamic Bones where it is ideal to have one root bone full of child bones. This works by checking all bones and trying to figure out if they can be grouped together, which will appear in a list for you to choose from. After satisfied with the selection of this group you can then press 'Parent bones' and the child bones will be parented to a new bone named RootBone_xyz

To parent
  • List of bones that look like they could be parented together to a root bone. Select a group of bones from the list and press "Parent bones"
Refresh list
  • Clears the group bones list cache and rebuild it, useful if bones have changed or your model
Parent bones
  • Starts the parent process

Texture atlas

Texture atlas is the process of combining multiple textures into one to drastically reduce draw calls and therefore make your model much more performant

Create Atlas
  • Combines all selected materials into one texture. If no material list is generated it will combine all materials.
Generate Material List
  • Lists all materials of the current model and lets you select which ones you want to combine.

Useful Tips:

  • Split transparent and non-transparent textures into separate atlases to avoid transparency issues
  • Make sure that the created textures are not too big, because Unity will downscale them to 2048x2048. Split them across multiple atlases or reduce the individual texture sizes. This can be easily done in the MatCombiner tab.
  • You can tell Unity to use up to 8k textures. Do so by selecting the texture and then choose a different Max Size and/or Compression in the inspector:

Bone merging

Lets you reduce overall bone count in a group set of bones. This works by checking all bones and trying to figure out if they can be grouped together, which will appear in a list for you to choose from. After satisfied with the selection of this group you can then set a percentage value how much bones you would like to merge together in itself and press 'Merge bones'

Refresh list
  • Clears the group bones list cache and rebuild it, useful if bones have changed or your model
Merge bones
  • Starts the merge process

Copy Protection

Can protect your avatars from being ripped from the game cache. Game cache rips in most common cases do not include blendshapes and shaders. This method will make it much harder for people that try to steal your avatar through ripping from cache.

We managed to fix the lighting bugs! Therefore the randomization options are not needed anymore.

How to setup:

  1. Do all the modifications to your model in Blender before you follow the next steps! This option should be the last one you do in Blender before exporting!

  2. You won't be able to see the mesh of your model inside the Unity bone mapping screen (it will be garbled mess, but only in there). Because of that, if you need to actually see your models mesh (e.g. for straightening the fingers for VR), follow the extra steps below. If you don't need to see the mesh (e.g. for unassigning the jaw bone) skip to step 2.

    • Export your model from Blender without enabling the protection
    • Load it up in Unity and configure it in the bone mapping screen and press "Done"
    • In Blender: Click the "Enable Protection" button and export your model
    • Then, except for just dragging the fbx into Unity, you need to go into the folder where this Unity project is located and then replace the unprotected fbx with the protected one. That way your configurations will be kept.
    • Skip to step 5
  3. In Blender: Click the "Enable Protection" button

  4. Export it to Unity by either using the "Export" button within Cats or set the fbx export option by yourself: Geometries > Smoothing > Set to "Face"

  5. In Unity: Set the value of the blendshape 'Basis Original' to 100 like so:

  6. To fix any lighting issues select your .fbx and then select "Import" as the Tangents option here:

  7. Because (for some odd reason) the protection increases your bounding box it could be too big to upload your model. If the VRCSDK complains about your model being too large, edit your bounding box back to normal here: (this option is below the blendshape list from above)

  8. Your avatar now behaves just like a normal one.

People that try to steal your avatar will then only see a box of mangled waifu trash instead of your original character.

special thanks to @zarniwoop#6081

Shape Key

Apply Shape Key as Basis

  • Applies the selected shape key as the new Basis and creates a reverted shape key from the selected one.

Settings and Updates

This plugin has an auto updater. It checks for a new version automatically once every day.



  • Optimization:
    • Added new "Convert Textures to PNG" button
      • This converts all texture files into PNG files
      • This helps with transparency and compatibility issues
      • The converted image files will be saved next to the old ones
  • Model:
    • Made SSBU models compatible
  • Exporter:
    • No longer warns of meshes that could be split by Unity
    • Instead warns when having more than 70k tris
    • Now warns at 10 materials instead of 4, will be changed back when more nuanced warnings are in place
  • Decimation:
    • Changed default decimation value to 70,000 tris
  • General:
    • Fixed corrupted meshes breaking nearly all Cats features
    • Added automatic fixing of faulty Cats installations
      • Restart Cats if it doesn't show up after updating
    • Rewrote the entire updater
    • Added some Blender 2.8 compatibility fixes
    • Updated mmd_tools


  • General:
    • Fixed an error removing the whole Cats UI
    • Fixed an error on Fix Model and other various buttons
    • Stopping Pose Mode in Blender 2.8 now selects the Box Selection tool instead of the 3D Cursor
    • Updated mmd_tools (improved 2.8 materials)


  • Model:
    • Made VRoid (.vrm) models compatible
    • Made Koikatsu (.pmx) models compatible
    • Pose to Shapekey and Apply as Rest Pose no longer require you to have the armature selected
    • Pose to Shapekey now asks for a shapekey name first
    • Added separate buttons to enable and disable the Full Body tracking fix
    • Improved Export button warnings
    • Pose Mode now always makes the armature selectable
    • Fixed meshes being deleted when a different layer than 0 was visible
    • Fixed all bones being deleted on .dae models
  • Model Options:
    • Put some model options under a new "Show More Options" button
    • Added "Merge Weights To Active" button
    • Added "Duplicate Bones" button
    • Join Meshes now removes subsurface modifiers and applies mirror modifiers
  • Custom Model Creation:
    • Attach Mesh and Merge Armatures no longer remove the full body tracking fix
  • Importer:
    • Added VRM Importer
      • Open the import menu to see the VRM button
      • If its not installed it will provide you with a download link
    • XNALara no longer randomly colorizes meshes
      • This makes combining materials much easier
  • Translations:
    • Locally stored Google translations no longer get deleted after 30 days
    • Added a button to the settings menu to manually delete all local Google translations
  • Eye Tracking:
    • Eyes will no longer be created in weird spots when the weight paint is off (thanks to zaCade for finding the cause of this!)
    • Fixed "Reset Rotation" sometimes not resetting the rotation
  • Visemes:
    • Selecting the "Basis" shapekey is no longer allowed
  • Optimization:
    • Added support for Material Combiner 2.0
  • Shapekeys:
    • Fixed a bug in "Apply Selected Shapekey as Basis"
  • Updater:
    • The settings and locally stored Google translations no longer get reset during a CATS update
  • General:
    • Updated CATS to Blender 2.8
      • It is still compatible to Blender 2.79 and will stay compatible
      • "Combine Materials", "Create Atlas" and "Custom Model Creation" is not yet working in 2.8
      • If you have any issues with Cats in 2.8, please let us know!
    • Updated mmd_tools (for 2.8 compatibility)
    • Huge UI codebase cleanup
    • Loads of bug fixes


  • General:
    • Fixed showing the wrong version number in CATS


  • Translations:
    • Fixed translations breaking due to a Google Translate API change (Thanks BlueLament for the fix!)
  • Custom Model Creation:
    • Fixed Attach Mesh throwing an error when the mesh has no vertex groups

Read the full changelog here.


  • MOAR updates on the armature code
  • Texture translation should have an option to rename the filename also
  • Automatic lower lid creation for eye tracking
  • Manual bone selection button for root bones
  • Full body tracking proportion adjustments


Do you love this plugin or have you found a bug? Post a response in this thread or send your feedback to the official discord server of the plugin for real-time communication: and look for people with the developer role ;)

Support us

If you enjoy how this plugin saves you countless hours of work consider supporting us through Patreon: