www.NimbleStudiosInc.com
This email address is being protected from spam bots, you need Javascript enabled to view it

Topics Covered:	MEL commands, flags, and argument; Maya scripting UI;
Sample Script:	A window to hold common tasks

This is the first of several tutorials on MEL. We’ll be starting from the very beginning with this article, and quickly picking up speed in the future. By the end of this article you will have learned what a MEL command is and how to interpret its different parts, how to quickly automate simple tasks using MEL, and, finally, how to build a small piece of custom UI.

Technically MEL stands for “Maya Embedded Language” and could be described as “an interpreted scripting language that interfaces directly with Maya’s core libraries”. Besides being boring enough to make you question reading this article further, those definitions miss the point: MEL is an easy way to take your art to the next level. Everything you do, and almost everything you see, in Maya is driven by MEL. Menu items, check boxes, sliders, heads up display, outliner, attribute editor, etc... All of it is created using MEL. When you check a check box, slide a slider, manipulate a manipulator, or do pretty much anything in Maya, a little bit of MEL is executed. This tight relationship between MEL and the rest of Maya means MEL is a powerful tool for doing such things as:

• Automating repetitive tasks and reducing your ‘click-count’ - with MEL you can write a script that performs far more clicks and drags than you could do in your typical 100-hour work week!
• Building custom UI to suits *your* needs - if you’ve complained about the apparent stupidity of some part of Maya’s UI, then MEL is for you!
• Leverage the power of modern computers to perform advanced math and invent the next great effect or tool!
• And much more!

I realized I’ve dodged the question posed big and bold at the start of this section: “What is MEL?” We’ll get into some of the details later, for now it’s enough to know that MEL is powerful and, as you’ll hopefully see by the end of this article, very accessible.

Now that I’ve got you hooked with that hand-wavy, “one MEL to rule them all” talk - it’s time to bring things crashing back to reality: MEL is a programming language. It is made up of commands, flags, arguments, loops, conditionals and other scary (boring?) sounding things. To use MEL you will need to type out commands and pass them off to Maya.

But it’s not that hard - really. In fact you can do it right now. If you look at the bottom of your Maya window you should see two fields called the Command Line and the Command Feedback:

The Command Line is an input field into which you can type small chunks of MEL quickly. The Command Feedback displays information about recently executed MEL commands and will turn red if there were any problems.

That’s all you need to know to get started - why don’t you give it a whirl, type something into the Command Line and hit Enter ...


... Done? Chances are if you’ve never written any MEL before you got an error - maybe you’re a wise guy and typed “something” into the Command Line, or maybe you entered something more like this:

If so, you’ll note that the Command Feedback field is red indicating that there was an error:


I mentioned before that MEL is made up of commands (sometimes referred to as ‘procedures’). A MEL command is a special word or series of words that can be used to tell Maya to take some action. This is similar in concept to the spoken commands you encounter daily: “Sit”, “Work late tonight”, “One shot” - these are all spoken commands that you might use with dogs, employees, or friends.

When you speak one of these commands you expect a response - usually a specific response particular to the given command. If your boss tells you to “work late tonight” she’s expecting you to, well, work late tonight. And if you tell your dog to “sit” you wouldn’t expect him to walk over to Starbucks and buy himself a cappuccino. This same premise applies in Maya: MEL commands are words linked to actions. When you invoke a MEL command by typing it into the Command Line you cause Maya to perform a particular action specific to that command.

Not every word or series of letters has an action linked to it - put differently: there are a limited number of valid MEL commands. Attempting to type anything but a valid MEL command into the command line will result in an error like the one we saw above. Similarly, if you turned to your friend and told him to “alsdjf!” he’d probably just tell the bartender you'd had enough for the evening.

So we’ve determined that neither “alsdjf” nor “something” are valid MEL commands - what is? To answer this let’s take look at another piece of MEL-friendly UI: the Script Editor.

The Script Editor can be launched from the button on the lower right hand side of Maya or through the Window > General Editors > Script Editor menu item. First thing you might notice is a log of our initial foray into MEL:


In short the exact same information we got from the Command Line and Command Feedback. However if you scan your eyes up a bit you’ll see a few other messages - logs of commands executed earlier in your Maya session. This top half is referred to as the History Pane. And the bottom half is the Input Pane.

The Input Pane is simply a bigger, better Command Line - here you can type multiple MEL commands at once divning many lines. Because you can have multiple lines of MEL commands the Enter key resumes its traditional role of inserting a carriage return. To execute a command (i.e. invoke it/issue it/send it to Maya) you have to either hit Ctrl+Enter or use the Enter key found on your numeric keypad. Once you execute commands in the Input Pane they disappear and move up to the History Pane - to keep them in the Input Pane simply select the commands before executing them.

By default any MEL command you invoke, and many of the commands Maya automatically invokes, will be added to the History Pane. As such it is a great way to find out what Maya’s doing “under the hood” and, more importantly, how you can do the same. If you’ve just launched Maya there probably isn’t much going on in the History Pane at the moment. But even at it’s barest you can find a couple examples of real live MEL commands:

Both ‘file -f -new‘ and ‘docServer -start’ are valid MEL commands. Technically only ‘file’ and ‘docServer’ are commands, the dash-y things following them are called ‘command flags’ - we’ll get into that later. For now select ‘file -f -new;’ and copy (Ctrl+C) paste (Ctrl+V) it into the Input Pane. Are you ready? .... Okay let’s execute! Hit Ctrl+Enter and let her rip! ...

... I know it may not look like much happened, but, without opening up the File Menu, without hitting the little axes button thing you created a new scene. Give it another go - create some spheres and cones, and then execute ‘file -f -new’ again ... ... Neat, eh? And the excitement doesn’t stop there - oh no, we’re just getting started. Let’s see what else we can do with a little help from our friends Messieurs History and Input Pane.

It One of MEL’s most hyped virtues is its ability to “automate repetitive workflows” - in fact you’ll see that phrase used almost word for word in countless tutorials and articles (and you’ll note that this one is no different). A fair question might be “So, how exactly can I use MEL to automate repetitive workflows?” - to which someone might respond “Well first you do your workflow and then you use MEL to automate it.” Surprisingly this glib answer isn’t that far off base. Let’s start with a workflow I’m sure everyone is dying to automate: creating a sphere - if we’re lucky we may even have time to move it and scale it a bit. Create a poly sphere by going to theCreate > Poly Primitives > Sphere menu item. If you look back at the History Pane you should see two new lines:

The first line is a valid MEL command, and the second is a ‘comment’. We’ll get into comments in the next article, but for now it’s enough to know that they are completely ignored by Maya. You can execute it or not, it won’t make a difference.  Like before you could copy and paste these lines to the Input Pane, execute them, and create yourself another sphere. Instead try moving the sphere somewhere new and scaling it up a bit. You should now have something like this in your History Pane

In my case three more lines have been added:


Each of these lines starts with a word followed by some letters and numbers. The word, as we’ve seen before, is a MEL command - the letters and numbers are MEL flags and flag arguments respectively. We’ll get to those a bit later. The first two lines starting with ‘move’ are, surprisingly, the MEL commands used to move the sphere back and up a bit. The last line, ‘scale’, is the MEL command to scale the sphere smaller. If you’ll humor me a bit and allow me to call this a ‘workflow’, we’ll move to the next step: using MEL to automate it.

Just to make sure it still works, copy and paste those five lines into the Input Pane and execute them ... ... If all went well you should now have two moved and scaled spheres, one on top of the other. Technically speaking, we’ve just automated that workflow. However, all that cutting and pasting stuff is not nearly as swanky as, say, a button on some sort of shelf like UI. Well, my friend, are you in luck today cause Maya comes complete with not only the world’s best sphere mover and scaler, but also your very own shelf buttons! To tap into the power of the shelf simply select those five lines from the History Pane and, using your middle mouse button, drag the selection onto the Shelf.

Every time you click that button the selected MEL commands will be run. The point of all this is to show how easy it is to capture, save, and replay pretty much anything you do in Maya - you don’t need to write a single line of MEL from scratch. Next time you create a skeleton or import a prop file, take a look at the History Pane - maybe there’s something there you can save and reuse.

This is not quite so important if you’re only executing a single MEL command, but imperative for anything more. This is so that Maya knows when one MEL command ends and another begins. Take a scan up through the History Pane and you should see that every non-comment line ends in a semi-colon. You may also notice that each command is on its own line - this, however is not required. Except for a few exceptions Maya treats spaces, carriage returns, and tabs the same (collectively called whitespace). The move commands from before could have been written like:


Or like


And they would have worked fine so long as semi-colons were used in the right places. The next rule concerns the structure of MEL commands. Your typical MEL command is composed of three main parts:

commandName   flagsAndArguments   target

 A flag is word or series of letters preceded by a dash. In the file command from earlier:

both ‘-f’ and ‘-new’ are flags. A flag is a way to specify the details about how a command should function. Continuing the analogy to spoken commands, instead of just telling your dog to “Sit” you could say “Sit here”. Since the ‘file’ command can perform dozens of operations (save, open, import, etc...), the ‘-new’ flag here indicates that the command is not saving or opening a file but rather creating a new scene.

All flags have two forms, a short form and a long form. In the move command above:


 ‘-r’ is the short form of the ‘-relative’ flag which indicates that the command target should be moved relative to its current position. In contrast the ‘-a’ or ‘-absolute’ flag indicates that the command target should be moved to the provided location regardless of where it is now.


and


are exactly the same commands and will have exactly the same effect. Coupled with flags are arguments. Some flags like ‘-new’ on the ‘file’ command don’t need arguments as there’s really only one way to create a new scene.

If you take a look at the ‘polySphere’ command, however:


you’ll see that every flag used is followed by one or more numbers. These numbers are flag arguments and they provide even more detail about how the command should function. To really geek up the spoken command examples from before: when you tell your dog to “Sit here” or “Sit over there” you’re really telling him to “Sit in a location that is here” or “Sit in a location that is over there” (good luck getting him to obey if you do, though).

In this case “Sit” is the command “in a location that is” is acting like a command flag and “here” is the argument to that flag. If there were a ‘sit’ MEL command it might look like:


In the ‘polySphere’ command above, the ‘-sx’ and ‘-sy’ flags indicate the number of subdivisions in the x and y directions (their long forms are ‘-subdivisionsX’ and ‘-subdivisionsY’). In this case each of the flags is passed the argument 20 indicating it will create a sphere that has 20 subdivisions in the x direction and 20 subdivisions in the y direction. A given command can take any number of flags and arguments, although, each command has a well defined list of acceptable flags. It’s also important to mention that all of the elements of the command must be separated by whitespace:

This is so that Maya can distinguish between the different parts of the command - if it were instead written like:


Or


Or


Maya might think the command had only one argument (first example), that the command name was actually ‘move-r’ not ‘move’ (second example), or that the flag ‘-r0’ had three arguments 0, -1.94, 1666 (third example).

To recap:

• The command name indicates the sort of action you will perform.
• Flags specify ways in which that action will be customized.
• Flag arguments provide additional details about how the flag will customize the action.
• Whitespace is used to separate each element of a command.
• Semicolons are used to separate commands.

And that leaves us with the command target. The command target can serve a number of purposes. For simple commands it might act just like a flag argument: it provides additional details about what the command will do. For those commands that modify objects or UI elements (like ‘move’ and ‘scale’) - the command target indicates which object or UI element will be modified.

At the risk of beating a dead horse, we can expand our canine example to include a feline. If you had two pets but only really wanted your dog to sit you might say “Sit Bowser” to make it clear that Fluffy can go on doing as she pleases. Likewise if you want to move your sphere around the scene you would issue a command like:


Indicating that pSphere1 should be moved up 10 units.

Huh? What’s that you say? The move command from the first example doesn’t have a target? Yep, that’s right:


Many of the commands that require targets have backup plans to handle situations when one isn’t provided. The ‘move’ command, for example, will try to act on whatever object is selected if no command target is provided. There’s loads more syntax to cover, and like a gazillion MEL commands to explore - but that’ll have to wait for later cause now it’s time to leave our spheres behind and make a (slightly more) useful example!

To bring it all together (and take it a little further) you’re going to make your very own “My Settings” window.

Just like a shelf button, each button in the window will execute a MEL command when pushed. The difference, though, is that you’re going to build the window and buttons from scratch using only MEL and without any drag-and-drop magic. The goal of the window is to save you a few mouse clicks by digging some commonly changed Maya settings out from the nested menus in which they hide, and exposing them on each of the buttons.

The meat of the work will be done by commands that you capture from the History Pane - but there are a few UI commands that you’ll need:


These four commands represent each of the main areas of MEL UI building. We’ll be discussing UI in depth in future articles, for now we’ll briefly go over those four commands. A window looks like this:

Almost all MEL UI you create will be contained in a window. You can think of a window as the foundation of your UI - all other components are built on top of it. The next layers on top of windows are layouts - they organize and position any buttons, fields, checkboxes, etc... (Generically called ‘controls’) contained in the UI. A
 ‘columnLayout’ organizes the controls in a column from top to bottom:

A button is an example of a MEL control - like text fields, checkboxes, option menus, and any number of other controls, a button allows the user to interact with (i.e. to control) the UI. She can click a button, check a checkbox, select an option from an option menu and that change will trigger any MEL commands attached to that control.

Finally there’s the ‘showWindow’ command. By default when you create a window it will be invisible - the ‘showWindow’ command makes it visible.

That’s enough talking let’s do some doing. Here’s some code to create the window and buttons from the previous picture:



Let’s walk through the flags:



 ‘-title’ is a flag that sets the words that will be displayed at the top of the window. The flag argument in this case is “English Conversation”  - and you’ll see that indeed the title of the window is “English Conversation”.

A bit of a digression:  the “English Conversation” argument is known in computing circles as a string (short for ‘string of characters’ - basically one or more words or letters). It is characterized by the double-quotes at the beginning and end. These quotes are necessary so that Maya doesn’t treat the space between English and Conversation as an indication that two flag arguments were used.

Next we see:



The ‘-adjustableColumn’ flag determines whether the width of the columnLayout can be changed (i.e. if you make the window wider or narrower will the columnLayout follow suit). The ‘true’ argument says, yes, the width can be changed. This flag isn’t necessary, but it just makes things look prettier.


You’ll notice that the ‘-label’ flag is on a separate line - since Maya treats all whitespace the same this is okay. The ‘-label’ flag is like the window’s ‘-title’ flag, it determines what words will be displayed on the button “Hello, how are you?” in this case.

There you go, you’ve made your very own (useless) user interface!

Let’s put some use into it. As mentioned before this little bit of UI can be used to expose some commonly changed settings. For the sake of example let’s pretend that I’m frequently changing the joint display size between 1 and 0.5 and toggling between hardware and software rendering. Although, to unwind, I love making spheres and moving them around.

First thing I need to do is find out the MEL command used to change the joint display size. I’ll create a couple joints (for reference), open up the script editor, and hunt down the joint size settings.

After several clicks I find it in Windows > Settings/Preferences > Preferences > Kinematics (phew!).

If all goes well I should be able to set the joint size to 1.0, grab the command from the script editor, stuff it onto a button and never again have to hunt through all those menus! Here goes:

Uh oh - what happened? The joints got bigger but there’s no output in the History Pane! Since everything you do in Maya passes through MEL, Maya ends up executing a lot of commands - so many that it would be distracting to display them all in the Script Editor all the time. By default only a few are displayed. If you really want to see them all you can enable Echo All Commands in the Script Editor’s Script menu - now you’ll get a lot more text in the history pane.

Note: the Attribute Editor generates a lot of output, it’s best to close this before turning on Echo All Commands. Also, depending on what you’re doing, echoing all commands can slow Maya down - so it’s best to only turn it on when you’re looking for a particular command. Okay, let’s try again - this time change the joint size back to 0.5.

There we go, the last command:



will set the joint size to 1. Let’s stick it on our button.

There’s one more flag on the button command that we haven’t discussed: the ‘-command’ flag. It takes a string argument that will be executed as a MEL command whenever the button is pushed.

Here’s the new code for the My Settings UI:



Notice that the ‘jointDisplayScale’ command is enclosed in double-quotes since it is being passed to the ‘-command’ flag as a string argument.

Here’s a picture of the UI - when the “Joint Size 1” button is pressed, the joint size will be set to 1:

See if you can add another button that sets the joint size to 0.5.

Next we’ll try to add some buttons for changing the current renderer to Maya Hardware or Maya Software.

Leaving Echo All Commands on, open up the Render View window (either click the  or go to Window > Rendering Editors... > Render View). You’ll notice that a lot of output has scrolled by in the Script Editor. Since we don’t care about it, let’s get rid of it - this will make it easier to figure out what commands are used to change the current renderer.

To clear the History Pane go to: Edit > Clear History in the Script Editor. Watch out, though, that you don’t accidentally clear the Input Pane - if so you may wipe out your work on the My Settings window.

Now go to Options > Render Using > Maya Hardware. Your history pane should look something like this:

You’ll notice that the output isn’t quite as clear as it was for the joint display size. Most operations in Maya trigger secondary, background operations that you normally don’t care about - unfortunately with Echo All Commands on those operations are recorded in the History Pane as well. What this means is that much of time finding MEL commands in the History Pane requires some detective work. Take a scan through the output and see if you can figure out which command was used to change the current renderer to Maya Hardware. If you need to, change it back to Software to see if that helps. You can also try out a command or two, and see if you current renderer was changed in the menu item.  

... Found it? The command to set the current renderer to Maya Hardware is:



Once we add it to our UI, along with a button to set the current renderer to Maya Software, we end up with a script that looks like this:



And this swanky piece of utility:

Just like Windows has Solitaire and cellphones have Tetris - we need to have a little fun too. And there’s nothing I like more than creating spheres and moving them around. Let’s see if we can add the sphere and move commands from before:



I’ve removed some of the flags and changed the arguments so that the commands fit onto the page nicer - feel free to leave them in their long form.

Okay let’s add it to a new button called “Sphere”:


And go! ...


Error!

Looking at the History Pane we see a bit more detail:



This is caused by one of the exceptions to the “Maya treats all whitespace the same” rule: you have to be careful when putting carriage returns into the middle of a string. Once Maya encounters one double-quote it expects to see a second one on the same line. One way around this would be to put all the commands together on the same line:



This is fine if you have a relatively short string, but gets awkward as your string gets longer than the width of the Script Editor. Luckily, if Maya sees a \ (backslash) at the end of line it will ignore the following carriage return. It’s important to note that the carriage return has to come immediately after the backslash - no spaces or anything in between.

With this in mind we can rewrite our window in its final form:


And in all its graphical glory:

As a final step, select your MEL code, and middle mouse button drag it to the shelf - presto you can now launch your settings window whenever you want!

Thanks for reading this far! If you’d never written any MEL before, I hope this was useful. If none of this was new to you: don’t worry! In future articles we’ll be picking up the speed and going much deeper into the magical world of MEL.

If you have any questions about anything Maya related, please feel free to shoot us an email at: This email address is being protected from spam bots, you need Javascript enabled to view it