Header

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".

A typical Maya ASCII file header looks like:

//Maya ASCII 1.0 scene

//Name: solstice.ma

//Last modified: Sun, Dec 21, 97 10:18:26 AM

File references

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;

or

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.

Here is an example:

file -r -rpr "solar" "/u/sally/work/solar.ma";

If the file "solar" contained an object called "sun", that object would be accessible in this file using the name "solar_sun".

Requirements

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.

A statement in the Requirements section looks like this:

requires productName version

This is an example of a typical requirements section:

requires maya "2.0";

requires specialPlugIn "1.2";

(For a full description of the requires command, see the MEL Command Reference online document.)

Units

This section of the file consists of a single currentUnit command, stating what units are used in this file. This setting will determine how all the numbers found in the file are interpreted.

Example:

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.)

File Information

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.

Nodes, attributes, and parenting

This section of the file contains the bulk of the data.

This is where new nodes are created with the createNode command, and their attributes are set with the setAttr command.

Nodes from referenced files (and globally defined nodes) can also be selected here with the select command, and have their attributes set with the setAttr command.

New "dynamic" attributes may be added to a node with the addAttr command.

Finally, nodes can be parented to other nodes here with the parent command.

(For complete information on all of these commands, see the online MEL Command Reference document.)

The creation of a new node looks like this:

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.

The setAttr command looks like this:

setAttr attributeName value;

or sometimes:

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;

// etc...

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;

The parent command is also used to do instancing. (That is, when you want to have two nodes that share children). This is done using the -add flag, like this:

parent -add childNodeName parentNodeName;

For the special case of instancing an object at the top level (also called the world), the -w flag is used in conjunction with the -add flag.

parent -w -add childNodeName;

(A parent node name is not specified, because the parent is the world, which contains all things.)

Script nodes

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.

Disconnections

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;

For example:

disconnectAttr "sphere.tx" "cone.ry";

For complete information on the disconnectAttr command, see the MEL Command Reference online document.

Connections

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.)

The format of these commands is this:

connectAttr sourceAttributeName destinationAttributeName;

For example:

connectAttr "sphere.tx" "cone.ry";

connectAttr "sphere.squish" "sphere.sz";

Limitations to editing Maya ASCII files

Maya ASCII files support only the statements described above.

If you do decide to add custom MEL code directly to a Maya ASCII file, keep the following in mind:

• If you edit a Maya ASCII file and add arbitrary MEL commands to it, these commands will not be saved out after you read in the file.

  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 are other limitations when you are adding arbitrary MEL commands directly into a Maya ASCII file.

  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).