Skip to content

Latest commit

 

History

History
146 lines (119 loc) · 6.11 KB

README.md

File metadata and controls

146 lines (119 loc) · 6.11 KB

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.
    image
  • 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
    image
  • 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

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.

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 😊

  • 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