Introduction
Autodesk® Maya® is an open product. This means that anyone outside of Autodesk can change Maya’s existing features or add entirely new features. There are two interfaces with which you can do this in Maya: via Maya commands or via the Maya API. Different language implementations are used for these two interfaces:
Write scripts using either of the following languages:
- MEL™—(Maya Embedded Language) is a powerful and easy to learn scripting language. Used to execute Maya commands. Most common operations can be done using MEL.
- Python™—is a powerful and easy to learn scripting language, which provides an interface to the Maya commands.
See the Scripting section in the Maya User Guide for an introduction to MEL and Python, and the Technical Documentation section for reference documentation on individual MEL/Python commands.
Write plug-ins using any of these 3 API's:
- C++ API (Application Programmer Interface) — provides better performance than MEL or Python. You can add new objects to Maya using the API, and code executes approximately ten times faster than when you perform the same task using MEL. Also, you are able to execute MEL commands from the API.
- Python API — Based on the C++ API and allows the API to be used through the Python scripting language. There are two versions of the Python API: Python API 1.0 and Python API 2.0. See Plug-ins versus scripts for more information.
- .NET API — The Maya .NET API is similar to the Maya Python API in that it is generated from the Maya C++ API. Most classes in the .NET API have a corresponding class in the C++ API with the same name and with a similar interface (that is, a set of functions and classes). It is a system that allows developers to create plug-ins and extensions for Maya using Microsoft’s .NET technology.
The Maya Developer Help provides a technical introduction to the Maya API, Maya Python API and Maya .NET API.
Overview of the Maya API
The Maya API is a C++ API that provides internal access to Maya and is available on the following platforms: Microsoft® Windows®, Linux®, and Apple® Mac OS® X. You can use the API to implement two types of code resources: plug-ins which extend the functionality of Maya, or stand-alones such as console applications which can access and manipulate a Maya model.
Plug-ins can be built in two ways:
- As dynamic or relocatable libraries which are loaded into Maya using standard operating system functionality. Plug-ins work by accessing the symbol space of the host application Maya. Access to the symbol space of other loaded plug-ins is not available.
- As scripts that use the Maya Python API.
The Maya Developer Kit provides example plug-ins that use the API. Many of the examples are provided with both C++ and Python source codes. To allow both versions to be loaded into Maya at the same time, the convention of prefixing commands and nodes with sp (for example, spHelix) is used for Python API 1.0 plug-ins. You are not required to follow this convention. Python API 2.0 developer kit examples are named with the prefix py (for example, pyBlindDoubleDataCmd).
When you use dynamic libraries, the operating system that you develop on place various restrictions on how to build and name plug-ins. Compiled plug-ins use the following file extensions for the different platforms:
- Linux: .so
- Windows: .mll
- Mac OS X: .bundle
- All platforms for Python plug-ins: .py
Also, the rules for creating plug-ins and API applications differ on the various platforms. See Setting up your build environment.
In addition to the Maya API, a Bifröst API is also available and is located in the bifrostapi folder of your Maya installation directory; for example:
C:\Program Files\Autodesk\Bifrost\Maya2018\sdk\include\bifrostfluids\bifrostapi
The Developer Kit
The Developer Kit is available on the Autodesk Developer Network. The Developer Kit contains 3 major components: include files, libraries, and examples.
The Developer Kit is also referred to as the devkit.
Examples
Copy the Developer Kit archive to your local directory and unzip it, and a folder called devkitBase is created. The Maya API examples are located within the devkitBase\devkit directory. This directory contains an applications and plug-ins folder. The applications folder contains examples of stand-alone API applications while the plug-ins folder contains Maya API plug-in examples. The method for building stand-alone or plug-ins varies on the different platforms. In most cases, Makefiles are used. On Windows and Mac OS X, we have provided IDE solutions for building most of our examples. See Setting up your build environment for information on how to install and set up the Maya Developer Kit.
Both Python API 1.0 and API 2.0 examples are located in the devkitBase\devkit\plug-ins\scripted folder. Python API 2.0 examples are identified with a prefix py in their filenames.
We do not provide the compiled plug-in and applications binaries on the Maya installation DVD. You must build these yourself. Building the Developer Kit examples is described in more detail in the Setting up your build environment.
Include Files
Header files are located in the include/maya directory. Maya header files normally start with the M prefix. For certain types of header files the two letters following the M indicate the header file type: Fn for function set, It for iterator, Px for proxy class. These naming conventions will be described in more detail later.
Libraries
The API is packaged as a set of libraries that correspond to the different functional areas of Maya. These libraries are:
OpenMaya—Contains fundamental classes for defining nodes and commands and for assembling them into a plug-in.
OpenMayaUI—Contains classes necessary for creating new user interface elements such as manipulators, contexts, and locators.
OpenMayaAnim—Contains classes for animation, including deformers and inverse kinematics.
OpenMayaFX—Contains classes for Autodesk® Dynamics™.
OpenMayaRender—Contains classes for performing rendering functions.
These libraries are shared libraries so that many plug-ins can use them at the same time. The libraries are located in the lib directory.
Plug-ins versus scripts
As described above, plug-ins can extend the functionality of Maya. For example, they can do the following:
- Add a new node type to Maya.
- Add a new command to Maya.
- Add more detailed callbacks. (More detailed than scriptJob events/conditions. See scriptJob MEL/Python command reference documentation in the Technical Documentation section.)
- Add new rendering pipelines, and so forth.
C++ versus Python plug-ins
Compiled C++ plug-ins are both platform and Maya version specific. You must compile a separate plug-in per version, per platform. Compiled C++ plug-ins also use different file extensions for different platforms. See Overview of the Maya API above for more information.
A Python plug-in is platform independent, and if the APIs that it uses are consistent between Maya versions, then it is also version independent.
C++ plug-ins can be faster than Python plug-ins; therefore, for performance critical plug-ins, you may wish to write a C++ plug-in. In general, a Python plug-in achieves about 70-80% of the speed of a compiled C++ plug-in.
Python plug-ins versus scripts
As described earlier, there are two interfaces with which you can perform operations in Maya: via Maya commands or via the Maya API. In addition, you can use Python for both of these interfaces. You can use the Python API to create a plug-in, or merely to script. You only need to define a Python plug-in if you plan to extend Maya (for example, to add a new node type, or to add a new command type, and so forth). Otherwise you can use the API in your scripts as you would the maya.cmds module. See the widgetHierarchy.py example in the devkitBase\devkit\pythonScripts folder the Maya Developer Kit. This example imports the OpenMayaUI module and calls methods in the MQtUtil class. It is not a plug-in, and you can run the script directly using the execfile Python command.
Maya commands versus Maya API
The following are a couple of factors you may like to consider when deciding between whether to write a script or a plug-in, and whether to perform operations using the API or Maya commands:
-
Often, the Maya API is faster than Maya commands. The Maya API provides lower level access to Maya, and therefore more wide reaching access to Maya in general. Tasks such as iterating over a graph with filters is easier to execute via the Maya API than it is via Maya commands. In addition, if you were, for example, programming a paint tool that operates on many vertices simultaneously, it could be beneficial to use the Maya API for heavier datasets. If the speed in the Python implementation is not sufficient, you could then port the plug-in to C++.
-
To decide between writing a Python plug-in or a Python script (whether using API or commands), consider whether or not you need to extend Maya, or if you want the ability to load/unload your script.
Documentation
The following documentation components are provided:
- This technical introduction to the Maya API
- The API class descriptions
This technical introduction to the Maya API includes a section for the Maya Python API and Maya .NET API. In addition, the C++ API Reference class description documentation can be used for both C++ and Python API development as it includes information for both of these development approaches. Maya Python API 2.0 Reference documentation is also available.
The Maya .NET API ships with Visual Studio integrated documentation generated from the C++ reference documentation. You can also obtain a .chm of the reference documentation at http://www.autodesk.com/me-sdk-docs.
Related documentation includes:
- The Scripting section in the Maya User Guide. It consists of a MEL and Expressions section and a Python section.
- The Technical Documentation section. It includes the MEL command reference and the Python command reference.
- The Maya Nodes and Attributes reference in the Technical Documentation section. Working with Maya nodes is a normal part of programming the Maya API.
- The What's New / What's Changed? information provided with each release.
- The Release Notes that provide items of interest for developers.
You can access the first four items from the Maya Help. Release notes can be obtained from http://www.autodesk.com/maya-releasenotes.
Other Requirements
Since the Maya API is a C++ API, it is best to have an understanding of the following:
- virtual functions
- class inheritance (including multiple)
- stream classes
- operator methods (there are many operator methods in the Maya API)
In addition, when building a plug-in or a standalone, you must use the compiler and linker that is recommended for the release. This information can be found in the What's New / What's Changed? or in Setting up your build environment of the documentation.
Except where otherwise noted, this work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License. Please see the Autodesk Creative Commons FAQ for more information.