Command Plug-ins

 
 
 

In the following topic, we outline the basic code structure of a command plug-in.

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: