Distributing Maya plugins

Here I discuss various ways you can ship a Maya plugin to end users. Ultimately the methods I present below can be automated and wrapped with scripts or installers (.msi etc.) You can see my [  Git repository ] to get a template project that demonstrate how to generate a windows installer for Maya plugin with CMake and CPack.

A plugin usually contains:

• .mll binary files
• icons
• mel/python scripts

You need to gather all those files and tell Maya where to find them. To this end you will need to define the following Maya environment variables:

MAYA_SHELF_PATH=C:\installation_folder\prefs\shelves // <- Must be defined first
PYTHONPATH=C:\installation_folder\scripts 
MAYA_SCRIPT_PATH=C:\installation_folder\scripts 
MAYA_PLUG_IN_PATH=C:\installation_folder\plug-ins 
XBMLANGPATH=C:\installation_folder\prefs\icons 

Defining those variables can be done as follows:

• OS variables: update the global system environment variables
• Maya.mel: edit C:\Users\name\Documents\maya\version\Maya.mel
• Custom shortcut: launch Maya with a .bat script to setups local variables.
• Modules: add .mod in C:\Users\name\Documents\maya\version\modules\
• Application plugin: add PackageContents.xml in
  • Windows: C:\ProgramData\Autodesk\ApplicationPlugins\plugin_name\
  • MacOs: /Users/Shared/Autodesk/ApplicationAddins/

Each method as its pros and cons which I will detail below. Personally my preference goes to the Application Plugin method which I find the most robust. This is also the official method to provide plugins through the autodesk app store (see also developer guidelines). Finally this is the method I use in my template project demonstrating how to ship a Maya plugin with CMake/CPack.

Using system environment variable

Directly edit the user's system environment variable with a bat script to add the needed variables (MAYA_SHELF_PATH etc.)

Pros

• shelves will automatically and properly load for every versions of Maya.

Cons

• hard to maintain a script that robustly update those variables (especially under Windows).
• hard to clean up when uninstalling
• users might not want you to mess with their system environment in the first place.

I don't recommend at all...

Using Maya.env

You directly add a file Maya.env in  C:\Users\name\Documents\maya\version\ . Pros and cons are almost identical to the above method.

Pros

• shelves will automatically and properly load for every versions of Maya.
• Slightly safer than editing the global OS environment variables.

Cons

• hard to maintain a script that robustly update those variables and do the clean up when uninstalling.
• users might not want you to mess with their local Maya.env in the first place.

If you're testing out your plugin on your local machine it's a good solution, but I don't recommend for shipping.

Using a custom shortcut

Start Maya with a special script that loads the correct environment variables! You can also have a shortcut linking to %COMSPEC% /C start /d Contents\ launch.bat 2018 in order to launch your script. 

Pros

• shelves and whatknot, everything will load and work properly
• not messing with anything this is the solution where you least tamper with the user files and environment.

Cons

• User needs to understand why using the standard shortcut won't load his plugins.

Using the module file

Just add a .mod file in the user directory C:\Users\name\Documents\maya\version\modules\. See the Maya documentation to understand this file format. The shelves won't load you will need to include a userSetup.py in your script folder (PYTHONPATH)

 Pros

• not messing with existing user files.
• everything can be neatly centralized in one place

Cons

• The .mod file needs to be generated at installation time to know the plugin location. (or you can lock the installation to be in the user directory and use relatives paths
• Shelves won't load with MAYA_SHELF_PATH you need to run a script manually (userSetup.py will be execute automatically, don't use .mel because there can be only one userSetup.mel contrary to python)
  • Don't try and use Pymel code at this stage as it won't have initialized properly, stick to Maya.cmds. Also, you can't do UI stuff at the point because Maya UI hasn't been built at this stage.

Using Application plugin

Almost the same as the module version but it is the official way to distribute plugins on the Autodesk app store. Plus you can specify a custom mel script to be launched at startup.

Add a PackageContents.xml file in:

• Windows: C:\ProgramData\Autodesk\ApplicationPlugins\plugin_name\
• MacOs: /Users/Shared/Autodesk/ApplicationAddins/

The MEL script specified in the xml file your-plugin-name_load.mel will be automatically executed at startup. You can see many other examples of PackageContents.xml just looking at the installation files of some free plugins on the Autodesk App store.

 Pros

• official method to ship plugins trough Maya app store
• not messing with existing user files.
• everything is neatly centralized in one place (which is the official location to store plugins)

Cons

• The PackageContents.xml file needs to be generated at installation time to know the absolute path of the plugin files. Instead, I recommend you use relative paths and lock the installation path to be in C:\ProgramData\Autodesk\ApplicationPlugins\plugin_name\ This way PackageContents.xml does not need to be dynamically changed according to some custom installation path.
• Shelves won't load with MAYA_SHELF_PATH you need to load them through the your-plugin-name_load.mel startup script.

This my favorite option.

References

Application plugin
Modules (1)
Modules (2)

One comment

Name

Email (optional field, I won't disclose or spam but it's necessary to notify you if I respond to your comment)

All html tags except <b> and <i> will be removed from your comment. You can make links by just typing the url or mail-address.

Anti-spam question:
√4 + 40 = ?

Small things make base men proud.
-- William Shakespeare, "Henry VI"