Using the script editor to investigate functionality

The script editor is your primary tool in order to learn about Maya's script-based functionality, as well as a great place to test small snippets of code outside a full script. One of the most useful aspects of the script editor is that it will show you the commands that correspond to the actions that you take within Maya's interface.

This is one of the best ways to learn about the commands involved in your day-to-day Maya tasks. For example, let's use it to find out how to make a polygonal cube with Maya Embedded Language (MEL):

How to do it...

1. Open the script editor by going to Windows | General Editors | Script Editor.
2. You'll likely note that there is a lot of text already displayed, even if you've only recently opened Maya. To make things easier to see, go to Edit | Clear History from within the Script Editor window's menu.
3. Now try making a polygon cube by holding down space to bring up the hotbox and going to Create | Polygon Primitives | Cube.
4. Use the interactive creation tool to specify the poly cube's dimensions.
5. Observe the output in the top half of the script editor. You should see something like the following:

   setToolTo CreatePolyCubeCtx;
   polyCube -ch on -o on -w 5.502056 -h 3.41434 -d 7.451427 -sw 5 -sd 5 -cuv 4 ;
   // Result: pCube1 polyCube1 //

How it works...

The output that Maya provides is presented as the MEL commands that correspond to the action that you've just taken. That can be a great way to find out which commands you'll need to use in your own scripts. In this case, it's the polyCube command, which will create a polygonal cube. Every command in Maya comes in two flavors—the MEL version and the corresponding Python command.

The script editor shows you commands in MEL syntax, which tends to take the form of:

commandName -option1Name option1Value -option2Name option2Value;

The MEL syntax borrows a lot from batch scripting wherein it relies on strings of option names (generally referred to as "flags") and corresponding values. The corresponding Python command generally has the following syntax:

commandName(option1Name=option1Value, option1Name=option1Value)

As you can see, the MEL and Python versions are fairly similar, but with some key differences:

• In the MEL version, flag names are indicated with a dash, and their values follow directly after, whereas in Python, options are given with the "optionName=value" syntax
• Python encloses all the flags in parentheses, whereas MEL does not
• MEL requires a semicolon (;) at the end of each line, whereas Python does not

Another big difference between MEL and Python is how they treat whitespace characters (spaces, tabs, and newlines). MEL, like most languages, doesn't care about whitespace; statements are terminated with semicolons, and blocks of code are defined with matched sets of curly brackets.

Python, however, uses whitespace characters to control program flow. This is often one of the strangest things about Python to people who are new to the language, but not to programming. In Python, blocks of code are defined by indentation. You can use either tabs or spaces, but the key thing is that you're consistent. In Python, every time you increase the number of tabs (or spaces) at the start of a line, it's equivalent to adding an opening curly bracket, and every time you decrease that number, it's equivalent to a closing curly bracket. This can often be confusing, as the structure of your program is defined by characters that may not actually be visible. If you're new to Python and having trouble keeping track of your whitespace, you might want to change your editor settings to display whitespace characters. Most programmer-friendly text editors include such an option, and it can be a big help.

The specific list of options for each command can be found in the built-in Python documentation, accessible from within Maya by going to Help | Python Command Reference. For most commands, you'll find a long list of options.

To make things even more complicated, every option has both a short name and a long name. For example, the polyCube allows you to specify the number of subdivisions along the X axis. You can use either the long name, "subdivisionsX" or the short name, "sx" to set it.

For example, all of the following will result in the creation of a 1x1x1 polygonal cube with five subdivisions along the X-axis.

The MEL versions are:

polyCube -sx 5;
polyCube -subdivisionsX 5; 

The Python versions are:

maya.cmds.polyCube(sx=5)
maya.cmds.polyCube(subdivsionsX=5)

Feel free to use either the short or long version for your arguments. You can also mix and match, using short names for some arguments and long names for others.

In practice, it's generally best to use short names for common arguments (ones that you're likely to remember) and long names for more obscure / more rarely used arguments. Remember that just because your code seems completely sensible to you right now, it may look confusing when you revisit it 6 months (or 6 years!) from now. Make it easy for your future self by using long names (and including comments) when necessary.

There's more...

You may be wondering why Maya offers two different methods for scripting, MEL and Python. That's a simple case of backwards compatibility. MEL came first and was available in Maya long before Python support was added. Back then, you had to use MEL for day-to-day tasks, and if that couldn't provide you with what you needed, you had to dive into the C++ API (which was quite involved and hard to work with on non-Windows systems). Python unites both approaches, but MEL is still supported to allow older scripts to work. It's also possible that you might get better performance with MEL than with Python, as the Python functionality is a wrapper around MEL. Python is a much nicer language to work with though, so it's generally a worthwhile trade-off.

Note that the script editor doesn't (by default) show you everything that you do. Under normal circumstances, Maya shows you a slightly filtered output based on what you are most likely to be interested in. This is usually a good thing, but there are times when you'll want to disable it. To show all the output, go to the script editor and select History | Echo all Commands. This will cause Maya to output everything to the script editor. This generally means much, much more output than you want, but can sometimes be helpful. In practice, you'll generally want to leave that option off except when you're trying to replicate a given piece of functionality in a script, and the default output isn't giving you any insight into what Maya is doing.

See also

If you have Maya setup to use interactive mode for the creation of primitive shapes, you must have seen the following in the output presented in the Script Editor:

setToolTo CreatePolyCubeCtx;

Contexts are an alternative way of getting input from the user, and we'll have more to say about them in Chapter 10, Advanced Topics.