How-To: Maya RunTimeCommands

Continuing off of the post I did last week I have another tip to share. This time I want to talk about RunTimeCommands and their value when used across a development team. I am just going to jump right in..

Benefits:

  • All your scripts can be categorized and added to the Hotkey Editor.
  • Enables you to setup your custom Shelf Buttons using the same RunTimeCommand names.
  • Renaming scripts will have no longer break local Hotkeys and Shelf Buttons setup by your artists.
  • Converting old scripts from MEL to Python will no longer break local Hotkeys and Shelf Buttons setup by your artists.

So What are RunTimeCommands and how do we use them?

To explain this I need to talk about Maya’s Hotkey system. Most people know that all of the Hotkeys are saved in the prefs directory in a file called userHotkeys.mel. If you open this file in a text editor it is clear that each Hotkey references a NamedCommand (these are generated automatically).

NamedCommands act as a reference to the script that needs to be executed during a key press.

RunTimeCommands on the other hand actually register NamedCommands within the Hotkey Editor. This allows you to categorize and store these commands for later use.

The hierarchy looks like this:
Hotkey > NamedCommand > RunTimeCommand > Script

The first step in creating your own shared RunTimeCommands is to setup a Python (or Mel) file with all of your commands. In the example below add some commands to change the grid spacing/size as well as the Space Cleaner script. The first commands are categorized in NRS_Display, while the last command is in NRS_Other. You can name your categories anything that makes sense for your team (Display, Modeling, Animation, Tools, etc)

Here is a sample py setup:

# python default runTimeCommands
import maya.cmds as cmds

# DISPLAY
cmds.runTimeCommand( 'increaseGridSpacing', annotation='Increase grid spacing', command='import gridControl as gctrl\ngctrl.gridSpacing(1)', cat='NRS_Display', d=True )
cmds.runTimeCommand( 'decreaseGridSpacing', annotation='Decrease grid spacing', command='import gridControl as gctrl\ngctrl.gridSpacing(0)', cat='NRS_Display', d=True )
cmds.runTimeCommand( 'increaseGridSize', annotation='Increase grid size', command='import gridControl as gctrl\ngctrl.gridSize(1)', cat='NRS_Display', d=True )
cmds.runTimeCommand( 'decreaseGridSize', annotation='Decrease grid size', command='import gridControl as gctrl\ngctrl.gridSize(0)', cat='NRS_Display', d=True )

# OTHER
cmds.runTimeCommand( 'cleanNamespaces', annotation='Remove unused namespaces', command='import spaceCleaner as sc\nsc.spaceCleaner()', cat='NRS_Other', d=True )

Flags:

  • annotation – a short description of the command displayed on mouse hover in the Hotkey Editor
  • command language – sets the language of the command flag to use either Py or Mel
  • command – the actual script command you wish to execute (either py or mel)
  • category – this flag sets the category for this command to live under in the Hotkey Editor
  • default – Important always set this flag to True!

Now that you have setup, named, and categorized each of your RunTimeCommands you will need to import your Python file in Maya’s userSetup.py so it runs on startup (see my last post here on how to share userSetup files).

Replace “sharedUserCommands” with the name of your Python RunTimeCommand file.

# Add this line anywhere in your userSetup.py file
import sharedUserCommands

If you deploy a custom Shelves to your artists I advise that you update the Shelf Buttons to now execute the RunTimeCommands you created. Remember that all of the RunTimeCommands are actually MEL, not Python!

The value of using RunTimeCommands in this way gives you the control to rename, convert, and categorize all of your scripts and tools without breaking the hotkeys, shelf buttons, and workflow of your artists. I know this pipeline has come in handy myself, I hope others find it useful too!