Command Plug-ins

Sample Command Plug-in

The following Python code is a sample command plug-in. We examine the relevant sections of this sample command plug-in below.

Python API 2.0:

# sampleCommand.py

import sys
import maya.api.OpenMaya as OpenMaya
# ... additional imports here ...


##########################################################
# Plug-in 
##########################################################
class MyCommandClass( OpenMaya.MPxCommand ):
    kPluginCmdName = 'myCommandName'
    
    def __init__(self):
        ''' Constructor. '''
        OpenMaya.MPxCommand.__init__(self)
    
    @staticmethod 
    def cmdCreator():
        ''' Create an instance of our command. '''
        return MyCommandClass() 
    
    def doIt(self, args):
        ''' Command execution. '''        
        # Remove the following 'pass' keyword and replace it with 
        # the code you want to run.
        pass
    
##########################################################
# Plug-in initialization.
##########################################################

def maya_useNewAPI():
	"""
	The presence of this function tells Maya that the plugin produces, and
	expects to be passed, objects created using the Maya Python API 2.0.
	"""
	pass

def initializePlugin( mobject ):
    ''' Initialize the plug-in when Maya loads it. '''
    mplugin = OpenMaya.MFnPlugin( mobject )
    try:
        mplugin.registerCommand( MyCommandClass.kPluginCmdName, 
            MyCommandClass.cmdCreator )
    except:
        sys.stderr.write( 'Failed to register command: ' + MyCommandClass.kPluginCmdName )

def uninitializePlugin( mobject ):
    ''' Uninitialize the plug-in when Maya un-loads it. '''
    mplugin = OpenMaya.MFnPlugin( mobject )
    try:
        mplugin.deregisterCommand( MyCommandClass.kPluginCmdName )
    except:
        sys.stderr.write( 'Failed to unregister command: ' + MyCommandClass.kPluginCmdName )

##########################################################
# Sample usage.
##########################################################
''' 
# Copy the following lines and run them in Maya's Python Script Editor:

import maya.cmds as cmds
cmds.loadPlugin('sampleCommand.py')
cmds.myCommandName()

'''

Python API 1.0:

# sampleCommand.py

import sys
import maya.OpenMayaMPx as OpenMayaMPx
# ... additional imports here ...

kPluginCmdName = 'myCommandName'

##########################################################
# Plug-in 
##########################################################
class MyCommandClass( OpenMayaMPx.MPxCommand ):
    
    def __init__(self):
        ''' Constructor. '''
        OpenMayaMPx.MPxCommand.__init__(self)
    
    def doIt(self, args):
        ''' Command execution. '''
        
        # Remove the following 'pass' keyword and replace it with 
        # the code you want to run.
        pass
    
##########################################################
# Plug-in initialization.
##########################################################
def cmdCreator():
    ''' Create an instance of our command. '''
    return OpenMayaMPx.asMPxPtr( MyCommandClass() )

def initializePlugin( mobject ):
    ''' Initialize the plug-in when Maya loads it. '''
    mplugin = OpenMayaMPx.MFnPlugin( mobject )
    try:
        mplugin.registerCommand( kPluginCmdName, cmdCreator )
    except:
        sys.stderr.write( 'Failed to register command: ' + kPluginCmdName )

def uninitializePlugin( mobject ):
    ''' Uninitialize the plug-in when Maya un-loads it. '''
    mplugin = OpenMayaMPx.MFnPlugin( mobject )
    try:
        mplugin.deregisterCommand( kPluginCmdName )
    except:
        sys.stderr.write( 'Failed to unregister command: ' + kPluginCmdName )

##########################################################
# Sample usage.
##########################################################
''' 
# Copy the following lines and run them in Maya's Python Script Editor:

import maya.cmds as cmds
cmds.loadPlugin('sampleCommand.py')
cmds.myCommandName()

'''

Maya Plug-in Entry and Exit Points

Maya plug-ins require two specific functions: initializePlugin(), and uninitializePlugin(), which are respectively called when Maya attempts to load and unload the plug-in. If these two functions do not exist in the file, the plug-in will fail to load.

def initializePlugin( mobject ):
    ''' Initialize the plug-in when Maya loads it. '''
    ...
def uninitializePlugin( mobject ):
    ''' Uninitialize the plug-in when Maya un-loads it. '''
    ...

The code within these functions depends on the plug-in type; in the current case, our plug-in class is derived from MPxCommand, so we must register it by calling MFnPlugin.registerCommand(). This function takes the following two parameters:

Command Name - This variable, which has been arbitrarily named kPluginCmdName, contains the name of our command. We assign the string 'myCommandName' as its value, which is re-used in MFnPlugin.dergisterCommand() and in the error reporting call to sys.stderr.write(). Having registered our command's name as 'myCommandName', we can run our command using the following Python instructions in Maya's Script Editor:
```
import maya.cmds as cmds
cmds.myCommandName()
```
Command Creation Function Reference - The second parameter is a reference to a function which creates an instance of our command. Here, cmdCreator creates an instance of our command class and returns it as a valid Maya object pointer.
Note that in the Python API 1.0, the pointer must be cast to a valid Maya object using OpenMayaMPx.asMPxPtr(). This is not required in the Python API 2.0. However, a maya_useNewAPI() function must be defined to indicate what type objects are being passed.
```
def cmdCreator():
    ''' Create an instance of our command. '''
    ...
```

Command Behavior

The behavior of our command is defined in MyCommandClass, which inherits from MPxCommand - the base class of all custom Maya commands. Classes prefixed by MPx are known as proxy classes, and are used to create various plug-in types. In the Dependency Graph Plug-in Basics section, we show how classes derived from MPxNode are used to create other plug-in types such as custom deformers, constraints, software and hardware shading nodes, surfaces, etc.

class MyCommandClass( OpenMayaMPx.MPxCommand ):
    
    def __init__(self):
        ''' Constructor. '''
        ...
    
    def doIt(self, args):
        ''' Command execution. '''
        
        # Remove the following 'pass' keyword and replace it with 
        # the code you want to run.
        pass

The class name (MyCommandClass) can be any arbitrary name, however it must contain two specific functions:

__init__(self) - This is the command's constructor. Its body must invoke the constructor of the base class from which it is derived.
doIt(self, args) - This is the command execution function; any code you want to run when your command is invoked should be written here. When the command is run either through MEL or the maya.cmds Python module, the command is instantiated, and its doIt() method is passed the specified arguments via the args parameter.
NOTE:For more information on defining your command's arguments and flags, see Command Arguments and Flags.

NOTE:Your command can also support the undoIt() and redoIt() functions, allowing it to be undone and re-done. For more information, see Creating and Manipulating Objects.