The ASCII files that Maya generates are organized into eight sections:
The following describes each section. These sections must occur in the order specified for the file to load properly.
The file header consists of a block of comments to help identify where and when the file was created. Like all comments, this block is ignored by the code that reads in a Maya file. There is one exception, however: the first six characters of the file must be "//Maya".
//Maya ASCII 1.0 scene
//Last modified: Sun, Dec 21, 97 10:18:26 AM
The next section of the file specifies all the non-procedural references. That is, all the other Maya files that are being referred to by this one, if any. For each file that is referenced, there will be a single file command to read it in. All the objects in the referenced Maya file will be available in this file, but their names will be prefixed with a string, usually the file name. The syntax of the file command when used for referencing is:
file -r -rpr prefixString fileName;
file -r -ns nameSpace fileName
The -r option specifies that the file is to be referenced. The -rpr option specifies the string that will be prefixed to all the object names in the file. For complete information about the file command, see the MEL Command Reference online document.
file -r -rpr "solar" "/u/sally/work/solar.ma";
The next section specifies the requirements. This consists of a series of requires commands. This section of the file tells Maya what software is needed to load the file properly. Specifically, what version of Maya, and what plug-ins.
requires productName version
requires maya "2.0";
requires specialPlugIn "1.2";
currentUnit -l cm -a deg -t ntsc;
This example would set the current linear unit to centimeters (other options are millimeters, meters, kilometers, inches, feet, yards, and miles), the angular unit to degrees (other option is radians) and the time unit to NTSC. (For a full description of the currentUnit command and all of its options, see the MEL Command Reference online document.)
This next section consists of several lines providing information about the file. The first five of these are defined by Maya: the application name (Maya), productization (e.g. Complete or Unlimited), version, cut identifier (date and time), and operating system and version. If you have provided additional fileInfo commands specific to your file, they will also appear in this section.
fileInfo "application" "./maya.bin";
fileInfo "product" "Maya Unlimited 4.5";
fileInfo "version" "4.5";
fileInfo "cutIdentifier" "200111121041";
fileInfo "osv" "IRIX 6.5 04151556 IP32";
Maya saves out the current values for the 5 predefined fileInfo statements each time you save your file. Any other fileInfo statements (or binary equivalents) found when loading a file, or issued during the Maya session, are preserved during a session and saved back out with the file.
createNode nodeType -n nodeName;
If this node is a node that can be parented (i.e., it represents geometry or a group of geometry), and it has a parent node that has already been created, the parenting can also be specified in the command:
createNode nodeType -n nodeName -p parentNodeName;
Some nodes (such as the default cameras) are common to every Maya scene. For these nodes, the -s option is specified. This tells Maya not to bother creating a new nodes if a node having the same name and parent) already exists. (This case occurs when a file is being referenced in.)
After the new node is created, it is automatically selected. The createNode command is then usually followed by a series of setAttr commands, to set the data in the node. Since the node is already selected, these commands only need to specify the attribute names and values.
setAttr attributeName value;
setAttr attributeName -type typeName value;
Every attribute has a default value, so setAttr commands are only stored for those attributes whose value is not default. (Or when the value of an attribute from a referenced file is changed.) Here is an example definition, of a sphere:
createNode transform -n "sphere";
setAttr ".s" -type "double3" 2.44 2.44 2.44;
setAttr ".t" -type "double3" -6.96 0 6.9;
createNode nurbsSurface -n "sphereShape" -p "sphere";
setAttr ".tw" yes;
setAttr ".rtw" yes;
setAttr ".ipo" no;
The pattern is similar when setting attributes of nodes that were created in a referenced file. Since these nodes have already been read in (and created), instead of using a createNode command, a select command is used. For example, say the file called "lunar" references another file called "solar", which contains an object called "sun". In the file called "lunar", the scale of this object is changed to 3. This is how that would look in the Maya ASCII file called "lunar".
select -ne solar_sun;
setAttr ".s" -type "double3" 3.0 3.0 3.0;
It is also possible to add new (dynamic) attributes to nodes. This is done with the addAttr command, used similarly to the setAttr command. For this example, say you have created a sphere, and added a float-valued attribute to it called "squish", which can range from -1 to 1, and set that attribute to 0.3. When you save the file, the code will look like this:
createNode transform -n "sphere";
addAttr -ci true -sn "squish" -ln "squish"
-min -1 -max 1 -at "double";
setAttr -k on ".squish";
setAttr ".squish" 0.3;
Not all of the parenting in the file can be done using the -p flag on the createNode command. For example, nodes may need to be parented to other nodes in referenced files. All the remaining parenting relationships are established with the parent command, which looks like this:
parent childNodeName parentNodeName;
parent -add childNodeName parentNodeName;
parent -w -add childNodeName;
Script nodes hold MEL code as part of a scene file. They are also set up to (possibly) execute after loading from a file, just before closing a file, or just before the node is deleted. The "before" scripts are executed when a file is loaded. If a file is closed or the node is deleted, the "after" script is executed. If a scene contains several script nodes, there is no guaranteed order of execution and the scripts should not depend on a specific execution sequence. See the MEL command documentation for scriptNode and the node documentation for script node for details on how to create script nodes.
Because MEL gives access to virtually everything you can do in Maya, the possibilities opened up by script nodes are endless. Specifically, script nodes can be useful for things such as scene cleanup or custom UI.
In files that contain file references, this next section of the Maya ASCII file breaks attribute connections among nodes from referenced files. This is done with a series of disconnectAttr commands which have the following syntax:
disconnectAttr sourceAttributeName destinationAttributeName;
disconnectAttr "sphere.tx" "cone.ry";
The next section of the Maya ASCII file establishes the attribute connections among all the nodes that have been created and referenced. This is done with a series of connectAttr commands. (For complete information on the connectAttr command, see the MEL Command Reference online document.)
connectAttr sourceAttributeName destinationAttributeName;
connectAttr "sphere.tx" "cone.ry";
connectAttr "sphere.squish" "sphere.sz";
Instead, they will be replaced by the explicit descriptions of the nodes, attributes, and connections that resulted from executing the commands. If you wish to add commands that will stay the way they are, you must put them in a file with a .mel extension, and reference that file (using Create Reference... in the File menu, or the file -r command.)
There is no guarantee that all commands will execute successfully. For example, for performance reasons we suspend all undo operations during loading of Maya ASCII and binary files. Some commands rely on undo capability internally to perform their work; these commands will only work from within .mel files (since loading of such files does not turn off the undo capability).