Creating a Maya Plugin Tutorial

 

The tutorials here assume you are working on a mac with the xcode development environment. You'll have to modify the instructions a little for other IDEs and OSs.

The steps outlined below are;

  1. Prepare for coding the plugin
  2. Code the plugin
  3. Test the plugin
  4. Debug the plugin

 

Preparing to code the plugin

First download the xcode project template from the downloads section, and begin a new maya plugin project.

The key thing in the project is to make sure that the IDE knows where to find the maya header files and libraries. On MacOs, this is located in;

There are different types of plugins that you can create. This tutorial will guide you through creating a "command" plugin. That means that the plugin will create a custom command, that will be available to the end user through mel.

 

Coding the plugin

If you used the maya plugin template, then you will have a project that looks like the following;

blankProject

The template creates a class called "blankCmd" that extends the class MPxCommand (all command plugins have to extend this class). You should rename it to something more suitable. The name of the command in the template code hasn't been set, so you should edit the highlighted lines to give the command a name. There is no requirement that the command name and the class name be the same, but it seems common sense to make it so.

In this example I used the command name of "fooCmd", and the resulting project looks like this;

There are three main methods shown; initializePlugin(), uninitializePlugin() and doIt(). The initializePlugin() method is used to register the command with maya.

Line 23: When the user selects the plugin through the plugin manager and presses the information icon, the author and version will be displayed

Line 25: the actual registering of the command occurs here. Maya create a fresh instance of this class every time that this command is invoked, that is why the creator() method returns a new instance each time.

Lines 26-29: if the registering failed, then the stat variable will be false and the plugin will not be loaded.

 

The unitializePlugin() has exactly the opposite function to initialize plugin. These two methods get called when the user selects the plugin from the plugin manager and asks it to be loaded or unloaded. This is something that you will be doing many times, when trying to debug a real plugin!

The real meat of the command takes place in the doIt() method. In the skeletal version this is completely blank. In the best tradition of helloworld programs, the implementation here displays the hello world message when invoked.

We'll return to some points that you should bear in mind in coding the doIt() function, a little later.

Before we move on and try to get this plugin built, you have to make one more edit on the project. Open the "Targets" widget and select "DemoProject" (this may be different, depending on what you called your project when you created it). Now click the . In the window that pops up, select the Build tab, you should see something like the following;

Change the highlighted one to be "fooCmd". Now you can build the project. In xcode you can do this by invoking Build->Build or with the shortcut key: Command-B.

Fix those syntax errors that you must have introduced ;), then observe that the end result of compiling and linking is an executable called "fooCmd.bundle". On MacOS maya plugins are stored as bundles, on other platforms this will be a .dll

 

Testing the plugin

Ok, now we are ready to test the plugin. The first thing to do is to move the plugin to maya's plugin directory. Where this is depends on how you have maya setup. You can place the plugin, right next to the plugins that maya ships with, or you can have your own plugin directory. The location of the plugin doesn't matter too much during development, but becomes critical when deploying to maya users. More on that later.

For now locate the fooCmd.bundle file. If you are not sure where it is, then click on it and select the info icon, it will show you the folder that this file is buried in;

Copy the file to the maya plugin directory;

Applications/Autodesk/maya8.5/Maya.app/Contents/MacOS/plug-ins

Start maya and go to Windows->Settings/Preferences->Plug-in Manager. You should see your plugin listed, but not loaded. If that is not the case, press "refresh" or make sure that you did copy the plugin to the correct directory.

Load the plugin and then click the info button next to it. You should something like the following;

This shows that the plugin loaded ok, and the info tells you what command this plugin provides.

Ok now open the script editor (Windows->General Editor->Script Editor).

In the script editor window type in "FooCmd;" and press control Enter to execute the command.

If you get a syntax error, check your typing carefully. The result is the hello world message on maya's status line.

Congratulations you just wrote your first plugin!

 

Debug the plugin

Of course that all worked fairly well, but it was a trivial example. In practice, you will find that you get errors in your plugin. So what's the best way to go about debugging it?

First of all you will quickly find out that if you modify the code and attempt to copy the fooCmd.bundle file back into the maya plugins directory, you will get an error. This is because maya creates a file lock on plugins that it has loaded, this stops you from overwriting the file whilst it is in use.

To overcome this you will need to do the following steps;

  1. unload the plug
  2. copy the plugin file to mayas directory
  3. (re)load the plugin

Useful mel commands to do this are; unloadPlugin("fooCmd") and loadPlugin("fooCmd"). Now you can create a shelf and place these commands on the shelf to make life a little bit easier.

That helps with the plugin deployment cycle, but that still doesn't help us debug it. There are two main strategies that we can use.

First of all maya can be executed from within the IDE in debug mode. This allows us to place breakpoints in the code and examine variable values etc. If you downloaded the template, you will see that there is already an executable configuration created that you can use for this.

You can execute maya in debug by doing the following;

Now usually any attempts to write to "cout" or "cerr" streams for a plugin, never get shown to the user. But if you enable the debugging console, you will be able to see this output.

I'll cover this style of debugging more in a future tutorial, but one thing you should know about it is that maya operated much more slowly in debug mode and this can be quite painful.

 

The second strategy is to run maya, outside of the IDE, and use logging for debugging. This is a little crude, but for the speed reason noted above, in practice, I use both techniques.

Where to go from here

Now of course you want to do more than the hello world plugin. I advise two things. First of all, get David Gould's excellent book on maya plugins and work through it.

Secondly look through the developers API documentation that comes with maya and look at the example plugins.

The helloworld plugin is very simple, as such it doesn't illustrate many concepts that you will come across, such as maya's parameter parsing mechanism and conforming to the undo mechanism. I recommend that you follow my tutorial on creating the CityBlockPlugin.

Back to Tutorials | Home