Maya MEL scripting tutorial



Written by Kevin Wafer                                                                         Contact : kevinwafer@googlemail.com


(c) Copyright Kevin Wafer 2006.                                    First version 16th Sept 2006. Last edit 26th Aug 2008.


Ask questions about this tutorial on the GameArtist.net forum.




Welcome to the Maya scripting tutorial. Some basic knowledge of Maya is assumed in this tutorial, a tutorial which is primarily designed for frequent Maya users who would like to understand the seemingly mysterious world of Maya programming. We'll focus some light on how Maya's scripting language (MEL) works. MEL is not as hard to understand and learn as perhaps it first seems. Once the syntax is understood, the rest comes easy.

If you are a MEL scripter, you may like to update your knowledge with some of the tricks I`ve aquired over the years. Where you see `WAFER'S TIP`, you will see a more advanced, different or better way of doing something.

This tutorial is relatively new, and I`m adding new content all the time, please feel free to email any suggestions or feedback.





1. EXTREME BASICS


1a. What is MEL all about?

Short answer

Q: What is MEL?
A: A scripting language used by Maya.

Q: Why should I use MEL?
A: Automate tasks, extend and customise Maya.


Long answer

MEL is a scripting language. A scripting language is a programming language that doesn't require compiling. To over simplify for a moment, compiling is a process that is applied to programmes that makes them perform more efficiently.

A scripting language shouldn't be thought of as an inferior programming language. MEL is powerful and highly flexible. The only real downside of MEL is that it's not quite as fast as a compiled language. If speed is vital, then it may be better to write a Maya plugin with a compiled language rather than find MEL solutions.

People often say that MEL is like the programming language C. It has some similarities, and previous experience programming with C or another language will be a big help to learning MEL. But the amount of relevence is all down to what you want to do with MEL. Artists without a programming background can immediately start writing scripts that contain a series of actions that would be slow and boring to do manually.

For me, I find MEL allows me to do whatever I want to do in Maya. It allows me to customise, and use Maya in ways that suit me. Sometimes the built in tools just don't allow you to do what you need them to. MEL allows you to modify them or build your own versions, creating new tools that no one has ever created abefore. MEL makes Maya into a playground, a great place to experiment with ideas and concepts.



1b. Where do I start?

Short answer

Q: Where do I begin?
A: The script editor is a good place to start

Q: How do I get to the script editor
A: In the Maya menu, Window -> General Editors -> Script Editor.


Long answer

The script editor is the best place to start any MEL related play. Advanced scripters tend not to use it quite so much. If you are starting out scripting or you want to do a quick experiment, you should definately be using the script editor.

To launch the script editor, locate the button in the far right bottom corner of your Maya window. The button is just below the animation buttons, directly below the `Animation preferencs` button and to the right of the `command feedback window`. Please see the icon highlighted in green.

Maya's script button

OPTIONALLY : You can also launch the script editor via the menu.  Window -> General Editors -> Script Editor

WAFER'S TIP : The script editor can also be called by writing  ScriptEditor;   in the `Command Line` or within a script/tool.

When the script editor has launched, you will see the following window.

Maya's script editor

If you have an inquisitive eye, you will notice I have written something in these windows.

The bottom window is where you do all your work. You can paste code into this window or you can write you own code in this window. But whatever you do in the bottom window, you must `execute` at some point for Maya to react to it. Execute is another word for `run` of course, but this word always sounds brutal and totalitarian to me!

You can `execute` your code via the menu of the script window   Script -> Execute. You can also press your numeric keypad enter. You standard enter will just make a new line in the script editor!

Copy and paste the following into your script editor window :

print "This isn't so hard.";

Then execute it by pressing enter on your numeric keypad, or using the menu option Script -> Execute

OPTIONALLY : If you don't have a numeric keyboard enter, you can press CTRL + ENTER together.

WAFER'S TIP : If you highlight your code and press numeric ENTER or CTRL + ENTER, Maya will only execute the highlighted code, and not clear it from the lower script editor window.



1c. The Maya command line

Short answer

Q: What is the command line?
A: The text entry strip that runs along the bottom of the Maya window. It's not particularly useful.

Q: What is the command line used for?
A: The command line is usually used to execute procedures (programmes), or single lines of code.


Long answer

Maya's command line isn't quite so useful. You can skip this section if you like. The command line is great for starting programmes, but not really much else. The most important component of this bar is the `Command feedback` window. Which is the right hand half of the window.

The `Command feedback` window gives us all sorts of useful feedback, such as warnings and errors from scripts. Often I`ll end a script by using the code print "Script done."; . This will print Script done. in the `Command feedback` line so that I know when my script has finished. You can experiment with this as I have below in this image. Remember to press numeric ENTER or CTRL + ENTER to execute this line of code.

Maya's command line





2. OUR FIRST SCRIPT



2a. What scripts should I start writing?

Short answer

Q: What kind of script should I start with?
A: Something simple but functional.

Q: What's the quickest way to start scripting?
A: Play around with other MEL scripts to get an idea of what MEL looks like.

Long answer

Planning what we have to do, and identifying goals for our programming is the way to go for all MEL scripts big or small.

Having an actual need for a script is excellent motivation for learning how to write one. Once you have identified a good idea for a script, the next step is to break the script down into chunks of what needs to happen for the script to work.

Let's say we've identified a need for a material renamer. We've decided that renaming materials by hand takes far too long. As we think about how we can write such a script, we can imagine that the first task we need to figure out is how to read a selection of Maya materials. Then the next thing would be to process the selection of materials, renaming each one at a time.

WAFER'S TIP : I always break my scripts down in to little chunks, or modules. The MEL term for this is procedures. I then get those little fragments of programme working properly, then glue them all together.



2b. A material renaming script

Short answer

Q: Why a material renaming script?
A: This script is real life script that is useful and can be modified easily.

Q: What will I learn?
A: You will learn some essential commands and scripting functionality.


Long answer

Before we start writing our script, let's create some materials for our script to use as test materials.

In Maya`s Hypershade window ( Window -> Rendering Editors -> Hypershade ) create some Maya Materials. Creating some materials of type Blinn in Hypershade will be a good choice, but our script should name any material types. Alternatively, if you prefer you can load up a scene that contains materials as a test scene.


First things first, let's see how to print out what is in a selection. Select some geometry or some materials, and then execute this script.


string $selection[] = `ls -selection`;
print $selection;

You'll see that the script has returned a list of our selection.



Let's move on to something more advanced.

This script will rename your materials that you have selected materials in the Hypershade (Window-> Rendering Editors -> Hypershade) to the name you have given to $newName. In this example our materials will be named to Our_New_Name, Our_New_Name1, Our_New_Name2 etc.



string $newName = "Our_New_Name";

string $removeMat[] = {"lambert1", "particleCloud1", "initialShadingGroup", "initialParticleSE"};
string $materials[] = stringArrayRemove($removeMat,`ls -mat`);

for($material in $materials){

      print $material;
      rename $material $newName;

      print ("Renamed material : " + $material + "\n");
}


To test the above script in action, create some materials in Hypershade, and then select a few of them. Then copy and paste the above script into the script editor and execute it (Script -> Execute)

You should see that this script has named our selected materials to Our_New_Name ;

Let's see what the script is doing.

1. First we define the new name for the materials. I've defined it as "Our_New_Name", you can change this to whatever you fancy.

2. The second part of the script defines which materials should not be renamed, these are the default Maya materials, such as "lambert1".

3. The third line gets a list of the selected materials minus the default Maya materials which we defined in the line above. The command stringArrayRemove removes the first string from the second string. The second string is a list of our selected materials which is created by the ls command. The -mat part says `just return the materials` in our selection.

4. Something interesting happens next. We create a loop! In this loop we will go through each material in the selection (the $materials variable contains our selection). Each time we go through the loop the variable $material becomes the next in the list of materials in $materials. This loop will continue until it has gone through each material in $materials.

5. The print statements are quite self explanatory :) The last important part is the renaming of the current material in the list. The syntax for the Maya rename command is rename oldname newname.




3. USEFUL MEL FOR TOOLS


3a. File handling

Return the current open Maya file
string $KW_TempSceneName =`file -q -sceneName -shortName`;


Return the current open Maya file with full path
string $KW_TempSceneName =`file -q -sceneName`;


3b. Environment variables


Script path
$KW_TempVariable = `getenv "MAYA_SCRIPT_PATH"`;

Where Maya is installed
$KW_TempVariable = `getenv "MAYA_LOCATION"`;

Documents and settings etc.
$KW_TempVariable = `getenv "USERPROFILE"`;

Get environment variables
$KW_TempVariable = `getenv "PATH"`;



3c. Plugins


Load a plugin
loadPlugin "myPlugin.mll";

Unload a plugin
unloadPlugin "myPlugin";



Ask questions about this tutorial on the GameArtist.net forum.

Kevin Wafer has been an industry professional since 1994.
You can contact him at kevinwafer@googlemail.com


Back to menu