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.

# 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. '''
    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 )

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:

1. 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()

2. 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.

   def cmdCreator():
       ''' Create an instance of our command. '''
       return OpenMayaMPx.asMPxPtr( MyCommandClass() )

Command Behavior

The behavior of our command is defined in MyCommandClass, which inherits from OpenMayaMPx.MPxCommand - the base class of all custom Maya commands. Classes prefixed by MPx in the OpenMayaMPx Python module 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 OpenMayaMPx.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. '''
        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

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.
  NoteFor more information on defining your command's arguments and flags, see Command Arguments and Flags.
  NoteYour 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.