Maya → Unity 

Art Pipeline

The following is my example of how to automate and streamline a game art pipeline workflow for Maya and Unity. The focus is on eliminating the need to follow lots of naming conventions, navigate directory trees over and over between your Maya project and Unity project, and automating repetitive art tasks that can be prone to error (e.g. exporting a rig without constraints, animation baking, naming files, etc.) I've included explanations for how to:

  1. Setup your system for Maya python scripting.

  2. Auto create assets and folder structures.

  3. Auto export assets such as static models, rigged models, and animations into Unity.

The AssetManager.py code has been battle tested on several games that shipped. However, the code is a WIP that hasn't been refactored and refined fully. I've tried to make it readable and added lots of comments, but some rough edges and bugs may exist. I plan to flesh out this tutorial at a later date with more explanations of the code.

Git Repo

Start by cloning the Art Pipeline repo from here:

https://github.com/bradley-newman/ArtPipeline.git

Set Maya Project

Be sure to set your Maya project before beginning a new project. This will create standard folder structures and allow the scripts to load unique settings for each project when switching between projects. For example, later on we will load a .JSON file that lives in the Maya Project root folder and describes folder naming conventions. 

To set a the project:

  1. From the Maya menu bar go to File Set Project.

  2. Navigate to the desired folder.

  3. Click Set.

Setup Dev Environment

To setup your development environment so you can write Python code with autocomplete and debugging, follow these steps (sorry, this is for Windows only at the moment):

Python Setup

  1. Download and install Python 2.7.6: https://www.python.org/ftp/python/2.7.6/python-2.7.6.amd64.msi

  2. Choose "Install for all users"

  3. Path: leave default (e.g. C:\Python27)

  4. Add this path to your computer’s PATH environment variable so scripts can find your Python installation.

PyMEL Setup

For Maya scripting, I prefer to use the PyMEL lib because it's more object-oriented than using straight Maya Python commands. To setup PyMEL do the following:

  1. Download Pymel 1.0.10rc2 from here: https://github.com/LumaPictures/pymel/archive/1.0.10rc2.zip

  2. Extract this zip to someplace convenient like: C:\pymel-1.0.10rc2

Maya Environment

Each version of Maya has a Maya Environment file called "Maya.env" (e.g. C:\Users\Name\Documents\maya\2018\Maya.env) where you can include paths to your scripts or libs. Take note of where you checked out the git repo, for example: (C:\ArtPipeline\MayaTools), as well as the PyMel dir (C:\pymel-1.0.10rc2). Edit the Maya.env file to include these paths, for example:

PYTHONPATH = C:\ArtPipeline\MayaTools;C:\pymel-1.0.10rc2;

MAYA_SCRIPT_PATH = C:\ArtPipeline\MayaTools;

This allows shelf buttons and other scripts to call functions in scripts that live in these paths.

Wing Python IDE Setup

Wing Python IDE works well for writing and debugging scripts. To set it up:

  1. Download and install Wing 6.0: http://wingware.com/pub/wingide-personal/6.0.6/wingide-personal-6.0.6-1.exe

  2. Open an existing Wing project or create and save a new project.

  3. Setup Maya Interpreter

    1. Copy the path to mayapy.exe (e.g. C:\Program Files\Autodesk\Maya2018\bin\mayapy.exe)

    2. With the Wing project open, choose the menu Project > Project Properties.

    3. Environment > Python Executable > check the custom radio button.

    4. Paste the path to mayapy.exe.

    5. Apply and OK

    6. Project > Save Project.

  4. Setup PyMEL AutoComplete:

    1. Download Maya 2018 Devkit zip: https://s3-us-west-2.amazonaws.com/autodesk-adn-transfer/ADN+Extranet/M%26E/Maya/devkit+2018/Maya2018-DEVKIT_Windows.zip

    2. Extract the folder to someplace convenient like: C:\Maya2018-DEVKIT_Windows

    3. In Wing, go to Edit > Preferences > Source Analysis > Advanced

    4. In the Interface File Path, click Insert and enter the path for the Maya Devkit PI folder, e.g. C:\Maya2018-DEVKIT_Windows\devkit\other\pymel\extras\completion\pi

    5. Click Apply and OK

  5. Setup Maya Debugging:

    1. Copy wingdbstub.py from the Wing install directory into the same directory as your python scripts.

    2. Edit wingdbstub.py to be: 

      kEmbedded=1
       

    3. In the lower left corner of Wing, click the bug and make sure Accept Debug Connections is turned on.
    4. Add the following code to your python script to connect to the debugger 

      import wingdbstub
      wingdbstub.Ensure()

       

    5. Set breakpoints in your code, and then start the debugger.

    6. Go into Maya and run your code and it should connect to Wing and pause at the breakpoint.

  6. Troubleshooting: https://wingware.com/doc/howtos/maya

Folder Structure

 

Conventions

The following is an example of folder conventions for a project to be used as a guide for the folder structure that we will use when creating assets.

Folders


Folders are not created manually by users, instead they are created automatically based on definitions in a .json file called Folders.json that lives in the root of the Maya Project and is maintained by a single person so conventions remain organized and consistent. This file is parsed by a GUI called the "Asset Manager" to display options for the “Root Folder” and “Subfolder” dropdown menus. The following is an example Folders.json file:

Asset Manager

 

Setup Shelf Button

For now I have everything lumped into a giant script called AssetManager.py. It includes a GUI as well as all the pipeline functionality. Follow these steps to setup a shelf button to launch the GUI:

 

  • Open the Script Editor and go to the Python tab and Copy+Paste the following code:


    import AssetManager
    reload(AssetManager)

  • Click and drag select this code and then middle mouse + drag this selected text to the Custom shelf to create a shelf button.

  • Right click this shelf button and choose Edit.

  • Select the Shelves tab and it should have the Custom shelf selected on the left Shelves panel, and the command we just dragged selected in the Shelf Contents right panel, as shown in this image:

  • In the Shelf Editor edit the fields to be the following (highlighted in red below):

    • Rename: Asset Manager

    • Tooltip: Asset Manager

    • Icon Label: AM

  1. Click Save All Shelves.

  2. Restart Maya.

Start GUI

  1. In the custom shelf click the “AM” button and the GUI will open. You can drag and dock this window anywhere. 

Set Unity Project

 

In the Asset Manager click “Set Unity Project Export Path” and navigate to your Unity project “Assets” folder, or a folder beneath assets. Based on the options selected in the Asset Manager “Root Folder” and “Subfolder”, a folder structure will automatically be created inside this export path when you export an asset FBX. For the example pictured above, the script will create the following folder structure:

Choose Asset Type

Once you have chosen a Root and Subfolder for your asset, you now need to choose the “Type” of asset you are creating: “Model”, “Rig”, or “Animation”. Files are referenced into one another according to this flowchart:

  1. Model

    1. The geometry of the asset.

    2. When creating an asset, you must begin by creating a Model. 

  2. Rig

    1. The joints, constraints, and controls for deforming or animating a model.

    2. Creating a Rig requires an existing Model (i.e. the rig file will reference a model file, and then the joints are skinned to the referenced model).

  3. Animation

    1. The file that an animator uses for animating the rig.

    2. Creating an Animation requires an existing Rig (the animation file will reference a rig file, and then the animator will key the referenced rig controls).

Create Model

  1. Set Type = Model.

  2. Enter a Name for the asset.

  3. Click Create.

  4. On creation the following will automatically occur:

    1. An “Export” group will be created in the Outliner.

    2. The file will be saved in the appropriate folder with the name "Example_Model.ma"

  5. Anything under this group will be:

    1. Exported out when you click “Export” in the Asset Manager.

    2. Referenced into a “Rig” file when it’s created.

WORKFLOW TIP:

When modeling, for your WIP meshes it is good to preserve the history and instancing for repeated objects so you can quickly make changes later on. When you are ready to export these meshes, a good practice is to do the following:
 

  1. Duplicate your WIP meshes.

  2. Convert the duplicates from instances to objects.

  3. Merge the duplicates together.

  4. Delete the history for the duplicates.

  5. Move these duplicates underneath the export group.

  6. Export.

Export Model

  1. Click the Export button in the Asset Manager.

  2. On export the following will automatically occur:

    1. The file is saved.

    2. Everything underneath the “Export” Outliner group is exported as an FBX. 

    3. An FBX of the mesh is exported into a Unity asset folder that directly corresponds to the Maya asset folder with the same name.

    4. The original file is reopened.

The code snippets below are taken from the AssetManager.py in Github. The first part of this snippet involves making sure the correct folder exists in the Unity project (lines 1-25).

The second part (lines 28-32) show the process of determining any special steps for exporting a model. Since there isn't much to do, we simply:

  1. Get the appropriate FBX export preset for models. This preset is loaded from disk and can be customized in Maya by: 

    1. Copying the preset files to the correct location (you can find examples in the MayaTools dir).

    2. Maya > File > Export Selection Options > File Specific Options > Edit Preset.

    3. In the Edit Export Preset window under Presets > Current Preset your FBX preset files you copied will show up in the dropdown menu.

    4. Customize the options and click Save Preset.

    5. Then copy these files back to your MayaTools dir.

  2. We construct a string for the full FBX filepath to be saved later.

Create Rig

  1. First create a Model. This model is going to be referenced into the Rig asset.

  2. Set Type = Rig.

  3. You don’t set a name for the rig, it automatically comes from the model.

  4. Click Create.

  5. You will be prompted to use the current model that is opened, or select a model file to reference.

  6. On creation the following will automatically occur:

    1. An Export group will be created in the Outliner with a Skeleton and Rig group.

    2. A reference is created for the Model file.

    3. The file will be saved in the appropriate folder with the name "Example_Rig.ma"

  7. Skeleton group:

    1. This is where you put your joints.

    2. Skeletons require a single root joint that is the parent of all other joints.

  8. Rig group:

    1. This is where you put your control curves for animation.

  9. Skinning:

    1. Skin the skeleton to the referenced model file. For the example below, you’d skin “joint1” to “Example_Model:Mesh”.

Export Rig

  1. Click the Export button in the Asset Manager.

  2. On export the following will automatically occur:

    1. The file is saved.

    2. The mesh reference will be imported and its namespace removed.

    3. Any skeleton constraints will be deleted.

    4. The rig group is deleted.

    5. An FBX of the skinned mesh is exported into a Unity asset folder that directly corresponds to the Maya asset folder with the same name.

    6. The original file is reopened.

The code for exporting a rig is shown below, and involves the following:

  1. A rig references a model file. When we export a rigged / skinned character we want to include the model and skeleton together, so we have to import the model reference into the rig file, and then parent (i.e. move) the model into the export group. (lines 4-10)

  2. The Rig controls and constraints create unnecessary transforms in the FBX in Unity, so they are deleted to avoid confusion and to optimize performance. (line 11)

  3. Finally an FBX export preset for characters is loaded to be used for final export. (line 15)

Create Animation

  1. First create a Model and a Rig. The rig is going to be referenced into this Animation file.

  2. Set Type = Animation.

  3. Enter a Name for the animation.

  4. Click Create.

  5. You will be prompted to use the current rig that is opened, or select a rig file to reference.

  6. On creation the following will automatically occur:

    1. An Export group will be created in the Outliner.

    2. A reference is created for the Rig file.

    3. The file will be saved in the appropriate folder with the name "Example@<AnimName>.ma"

 

The following structure will show up in the Outliner from the referenced rig and model files: 

  1. To create an animation: 

    1. Keyframe the rig control curves. 

    2. When you are ready to export make sure to set your timeline start and end frames for the duration of your animation because this will determine which frames are baked on export.

Export Animation

  1. Click the Export button in the Asset Manager.

  2. On export the following will automatically occur:

    1. The file is saved.

    2. The rig reference will be imported and its namespace removed.

    3. The mesh reference is deleted (unless there are blendshapes).

    4. Any skeleton constraints will be deleted.

    5. The rig group is deleted.

    6. The entire skeleton is baked for every frame of the timeline start and end.

    7. An FBX of the baked skeleton is exported into an “Animations” subfolder that is inside the parent asset folder.

    8. The original file is reopened.

The code for exporting animations involves the most steps to complete.​

  1. We start by getting various strings for names, including the nested Rig and Model references (lines 4-17).

  2. Import the rig reference (line 20)

  3. Check if the model reference has blendshapes. (lines 22-27)

    1. If it does, then when we keep the models during the import of the model. ​

    2. If it doesn't, then we delete the meshes because they aren't needed for animations and just increase the animation file size unnecessarily. 

  4. Find the skeleton and bake the animation frames for the entire hierarchy based on the current timeline start and end. (lines 31-40)​

  5. Delete constraints.

  6. Parent the Skeleton (that was imported from the Rig ref) into the export group. Leave behind the Rig itself so it's not exported. (line 44)

  7. Load the Animation FBX export preset.

Final Export

After all the Model, Rig, Animation specific steps are complete, we arrive at the final export of the FBX, which involves the following steps:

  1. For some custom shader applications, binormals and tangents are required. The normal export process may not include these, so to ensure they are included we triangulate the models first. (line 3)

  2. We select the things to export. Normally, this is just the export group. However, there is support for exporting whatever is directly selected as well. (lines 7-13)

  3. Load the appropriate FBX export preset file from disk (line 16)

  4. Run the FBX export Mel command to export and save the file in the Unity project. (line 18)

  5. The whole export process has been inside a try block, so if it errors at any point we catch the exception and print out the error. (lines 20-29)

  6. Finally, to preserve our work, we close the file without saving our destructive changes and re-open the original file.