The MEL Command

Now that we know where to enter MEL commands in the Maya interface, it might be beneficial to know exactly what a MEL command is.

The most fundamental element of any use of MEL is the command . Although Maya does a wonderful job of abstracting end users from manually entering commands, almost every button pressed in Maya in actuality executes a MEL command.

What essentially happens when a user presses that button is that the interface figures out which options have been set for that command, and executes the command with those options. The best way to see this in action is to open Maya s Script Editor. As an example, open the Create>Polygonal Primitives>Sphere Options box and set the options to those seen in Figure 3.5.

Figure 3.5: The Polygon Sphere Options box.

Click Apply so that the Options box stays open. If we open the Script Editor, in the History section we will see text similar to that in Example 3.3.

Example 3.3: The command feedback results of creating a sphere.

 polySphere -r 10 -sx 15 -sy 30 -ax 0 1 0 -tx 1 -ch 1;  // Result: pSphere2 polySphere1 //  

You can begin to see the relationship between the interface and the actual commands issued. The actual command is called polySphere . The options for the command, called flags , are easily distinguished by the "-" that prefaces them. Flags are important aspects of any command. A flag allows us to set values for various aspects of a command. Note that when any command is passed to Maya without a flag specifying a particular value, Maya will use the default value, or the value set by user preferences, as in the case of construction history.

Every command available in MEL, and any flags associated with it, is included in the online documentation of Maya. Also available is the help command, which can quickly call up a listing of commands and their flags. For example, if in the input area of the Script Editor we enter the code seen in Example 3.4, we get a listing of each of the possible flags available for the polySphere command.

Example 3.4: Getting help on the polySphere command.

 help polySphere; 

An interesting and important aspect of command flags is that, much like attribute names, Maya allows a single flag to have two names, both a short and a long name . While the appeal of using the short names for flags is understandable, using the long versions makes code easier to read for the original author and anyone else who might need to work with it in the future.

We should notice that Maya echoes the command flags using the short flags. Therefore, if we look at our polySphere command and use the information gleaned from the help command, we can break our polySphere command down to decipher where each flag comes from. If we take the code from Example 3.3, and use the information gathered from the help command used in Example 3.4, we can translate the command into something more readable, which we see in Example 3.5.

Example 3.5: Converting short arguments to long arguments.

 polySphere -r 10 -sx 15 -sy 30 -ax 0 1 0 -tx 1 -ch 1;     polySphere         -radius 10         -subdivisionsX 15         -subdivisionsY 30         -axis 0 1 0         -texture on         -constructionHistory on         ; 

As we can see, the command becomes infinitely more readable. Not only have we replaced the short name of each flag with its long version, we have replaced the values for the texture and constructionHistory flags with the word on instead of the value 1. Both flags are a Boolean value, meaning either on or off. We discuss Boolean values in Chapter 4, An Introduction to Programming Concepts.

Each value from the Polygon Sphere Options box is represented within the issued command. Also in the command is the construction history flag. Construction history is, by default, turned on in Maya. What happens is when any command that can possibly create construction history is issued, whether through the user interface or via MEL if no flag is set, Maya looks to see whether the user currently has construction history toggled on or off. Maya combines all these variables (remember this word ”we will hear it a lot in this book) and issues the command. It is important to check the documentation for any command used in a MEL script, because we never know when an obscure flag with a default value will produce an unpredictable result.

Command Modality

One important concept to understand when dealing with commands is that they are modal . Modal means that when the command is issued, it is set into one of three modes: create , edit , or query . Not every command allows for every mode, nor is every flag available in every mode.

Sounds confusing? It can be, but in practice, it really becomes second nature. We never explicitly tell a command to be in create mode; by default, a command will be in create mode. This is not to say that the command is necessarily creating anything. A more applicable name would be the "do" mode. Essentially, unless we explicitly use the “edit or “query flags on a command, it is in create mode.

The edit mode is used to set flags on a node after it has been created. The “edit flag should be set immediately, before any other flag. After setting the command to edit mode, we can set as many flags as we want, providing that they operate in the edit mode for that command. The query mode is used to request information pertaining to a particular flag. As with the “edit flag, the query flag should be issued first, before any flags. The query mode returns only the information for the last flag in the command. The “edit and the “query flags are mutually exclusive, and only one can be used at a time. Interestingly, because of Maya s node-based structure, many of the options set by flags are actual attributes on nodes, and can be accessed and set using the commands getAttr and setAttr . Even within MEL, Maya s open architecture allows multiple solutions to one problem. In Example 3.6, we edit the sphere created in the previous examples.

Example 3.6: Using a command in edit mode

 polySphere -edit -radius 3 - subdivisionsX 30; 

Our sphere is now smaller, and has 30 subdivisions around the axis. We can confirm this by using the polySphere command in the query mode, seen in Example 3.7.

Example 3.7: Using a command in query mode.

 polySphere -query -radius;  // Result: 3 //  

The value returned can be seen in the Command Feedback, in the Script Editor s History area, or directly in the Command Shell. Notice that we only get a result if we have the sphere selected. If we had deselected the sphere, and then executed our command, we would have received an error similar to the one seen in Example 3.8.

Example 3.8: A MEL error from not having the object selected.

  // Error: No object was specified to edit //  

Maya is actually very inconsistent when it comes to executing commands with multiple items selected. Some commands will find the first available object to operate on. Others will operate on the entire selection list. Some will return an error when multiple objects are selected, and others will not even function if something is selected. Luckily, the engineers at AliasWavefront realized this and provided a third standard argument for any command that allows us to specifically name an object we want to execute a command on.

In a new scene, at the Command Line type the command seen in Example 3.9.

Example 3.9: Creating a sphere with default parameters.

 polySphere constructionHistory on name myBall ; 

Since we did not explicitly set flags for the radius, subdivisionsX, or subdivisionsY, Maya uses the default values. Now, de-select the sphere. By adding the name of our object, our target if you will, to the end of our command, we can use the edit or query flags on our sphere, even if we do not have our object selected, as seen in Example 3.10.

Example 3.10: Using a node name to query information.

 polySphere query radius myBall ;  // Result: 1 //  

Command Arguments

Occasionally, a command will need specific information to function. If a command requires information, called an argument , to be passed to it, the command will fail if these arguments are missing. A perfect example is the move command. What use is the command if we can t tell it how much to move? As a general rule, any command arguments will come after any flags have been set, but before the command target, which, along with flags, can technically also be termed an argument.

At the end of every command we have entered is a semicolon. The semicolon is to MEL what a period is to a sentence . It encapsulates one thought or command together and delineates it from another, even if one command is spread across multiple lines, or multiple commands are on the same line. This is most important when executing multiple commands at once, such as when we create a shelf button, in an expression, or most obviously, as in a script. The ability to split a single command across multiple lines doesn t do anything for Maya, but can do wonders for the readability of a command string.

Now, we have our standard format for MEL commands, seen in Example 3.11.

Example 3.11: The MEL command construct.

 command         [command mode]         [-flag flagValue]         [required arguments]         [ target ] ; 

Believe it or not, we now have the capability to write tiny little tools. By highlighting any MEL commands and middle-mouse-button (MMB) dragging the text to a shelf, we can create a shelf button. One of the easiest things we can do is create commands with preferences preset, or that carry out a series of commands over and over. At this point, we have to hard code each line, but we will soon learn to create more dynamic and flexible tools. In our final example, seen in Example 3.12, we use a series of MEL commands to create a polygonal book object.

Example 3.12: A series of MEL commands, essentially a simple script.

 polyCube         -width 2.2         -height 0.4         -depth 3.2         -axis 0 1 0         -texture 1         -constructionHistory off         -name book ;     select         -replace book.f[0] book.f[2] book.f[4] ;     polyExtrudeFacet         -constructionHistory off         -keepFacesTogether on         -localScale 1 0.782538 1 ;     polyExtrudeFacet         -constructionHistory off         -keepFacesTogether on         book.f[0] book.f[2] book.f[4];     move         -relative         0 0 -0.0434924         book.f[0] ;     move         -relative         -0.0434924 0 0         book.f[4] ;     move         -relative         0 0 0.0434924         book.f[2];     select         -replace         book.f[16] book.f[19] ;     move         -relative         0.0434924 0 0;     polySoftEdge         -angle 0         -constructionHistory 0         book.e[0:43] ;     select -clear  ;