Maya Python plugin template

A template to quickly make a Python plugin for Maya. (For modules, see Maya module template

Features

• simple installation
  • Drag & drop installation with installer.mel. (Windows only)
  • it installs the Python plugin
  • and it installs all Python dependencies (scripts) from https://pypi.org/
• Easily enable / disable a tool with the plug-in manager. Smoothly disable your tools if they cause issues.
  
• Run startup code, without editing userSetup.py, keeping your Maya setup clean. (great for debugging)
• Adds your tool to the Maya menu when plugin enabled, and remove from menu when unloaded
  
• Support MPXCommands (beta)

Overview

handle dependencies automatically

A pip install auto handles dependencies, removing the need for vendoring dependencies.
Without pip install you need to manually install the dependencies.
This template includes a pyproject.toml to support a pip install to a Maya plugin folder.
The below command triggers a pip install from this repo:

pip install https://github.com/hannesdelbeke/maya-plugin-template/archive/refs/heads/main.zip --target "C:/Users/%username%/Documents/Maya/plug-ins"

Read this if the above command fails

<sup>1. if the target folder doesn't exist, this command creates a Maya/plug-ins folder in your documents , which requires admin access.
2. When a user has been renamed on Windows, %username% will return the current name. But the folder path will use the old name, resulting in this demo command failing.</sup>

Maya plugins don't support Python packages, they only support a single `.py` file. To include a package in your plugin, I recommend to use pip dependencies.

the drag and drop installer uses requirements.txt to install dependencies. and installs them to documents/maya/scripts.

Instructions

• click 🟩use this template to create your GitHub repo, & clone it
• change the data in the pyproject.toml
• add dependencies to both requirements.txt and pyproject.toml
• Plugin setup
  • rename the demo plugin folder
  • change the MENU_NAME and other menu variables at the top of the file to customize the tool's menu entry.
  • add load & unload code to the initializePlugin & uninitializePlugin methods
    • initializePlugin & uninitializePlugin don't follow the PEP8 name convention. Do not change this, or they won't run.
  • optionally handle command registration on load & unload
• Optional
  • replace this README.md with your own instructions
  • Add a LICENSE
• edit the installer.mel to support drag and drop installation of your plugin. Change the variable at the top to your python script name. For drag & drop installation of your Maya plugin to documents/maya/plug-ins. Just drag the installer.mel file in Maya. (Windows only)

Extras

see command info

You can add commands to you Maya plugin. Included this in the template but I never use this. Feel free to just delete all code related to commands.

Adding a command to your plugin is optional. (I never had the need for it) In Maya Python scripting, MPxCommand is a base class for creating custom commands. Below is a simple example of creating a custom command using MPxCommand. This example demonstrates a command that creates a cube.

import maya.api.OpenMaya as om
import maya.cmds as cmds

class CreateCubeCommand(om.MPxCommand):
    commandName = "createCube"

    def __init__(self):
        super(CreateCubeCommand, self).__init__()

    def doIt(self, args):
        # Parse the arguments if needed (not used in this example)

        # Create a cube
        cube = cmds.polyCube()[0]

        # Set the result to the name of the created cube
        self.setResult(cube)

# Creator function
def createCubeCommand():
    return om.asMPxPtr(CreateCubeCommand())

# Initialize the plugin
def initializePlugin(plugin):
    pluginFn = om.MFnPlugin(plugin)
    try:
        pluginFn.registerCommand(
            CreateCubeCommand.commandName,
            createCubeCommand
        )
    except:
        om.MGlobal.displayError(
            "Failed to register command: {}".format(
                CreateCubeCommand.commandName
            )
        )

# Uninitialize the plugin
def uninitializePlugin(plugin):
    pluginFn = om.MFnPlugin(plugin)
    try:
        pluginFn.deregisterCommand(CreateCubeCommand.commandName)
    except:
        om.MGlobal.displayError(
            "Failed to unregister command: {}".format(
                CreateCubeCommand.commandName
            )
        )

# Usage:
# 1. Save this script as "createCubeCmd.py"
# 2. Load the script in Maya using the following commands:
#    ```
#    import maya.cmds as cmds
#    cmds.loadPlugin("path/to/createCubeCmd.py")
#    ```
# 3. Run the custom command:
#    ```
#    cmds.createCube()
#    ```

sample repos using this template

create a PR to add your repo below 😊

• https://github.com/hannesdelbeke/maya-pip-qt
• https://github.com/plugget/plugget-qt-maya-plugin
• https://github.com/hannesdelbeke/pyblish-maya-plugin
• https://github.com/hannesdelbeke/maya-plugin-duplicate-obj-along-curve
• https://github.com/hannesdelbeke/maya-plugin-snap-to-closest-UV

• might consider adding: support for toolbox & shelf entries
• PS: You can also use unimenu to add your tool to the Maya menu. Recommended for more advanced studio setups.

references

• maya plugin docs
• list loaded plugins, find plugin command from plugin, .. docs https://download.autodesk.com/us/maya/2010help/CommandsPython/pluginInfo.html#flagcommand
• similar maya plugin template https://github.com/minoue/miMayaPlugins/blob/master/plugin_templates/python_command/pyPluginCmd.py