File referencing allows you to manage complex scene hierarchies. To gain the most benefit from file referencing, use the following tips to ensure a more efficient workflow. As well, a basic understanding of namespaces will help your workflow. For more information, see Namespaces.
File and node naming for file referencing
Pre-planning the file and node naming conventions for the parent scenes and referenced files is important and will greatly add to the success of the implementation of file referencing in your production environment. In particular plan to ensure that:
Alternatively, you can specify namespaces of shorter length than the default file name when it makes sense. A shorter node name streamlines your workflow when working with Maya's editors (Channel Box, Outliner, Layer Editor, and so on). You create a custom namespace by typing the desired text string in the Create Reference option window. For example, you could select to use a custom namespace called mt instead of the word mapleTree. The tree1 node name in the above example would be called mt:tree1. This reduces the length of the name (and any typing) that may be required when working in Maya.
If you add non-referenced nodes to the reference namespace, this can cause name clashes with referenced nodes (for example, if the reference is unloaded when a node is added to the namespace), and prevents the namespace from being deleted when the reference is removed. For more information, see Namespaces.
Namespaces are the preferred method for managing naming when working with file references in Maya. It is not recommended that you employ Maya's renaming prefix convention when using file referencing. While the DAG path or long name of a node may make it unique when using renaming prefixes they do not work consistently within file referencing and will complicate the hierarchical DAG changes which causes problems later on.
File formats for file referencing
Saving files in the Maya ascii file format (.ma) is preferred when using file referencing. Maya ascii files can be opened and edited in your favorite text editor, and are easier to troubleshoot if the file or some components of the file do not load as expected.
File paths for file referencing
File referencing only supports absolute paths and paths with environment variables. Relative path names are not supported when using file referencing. An environment variable can be used as a superior alternative to a relative path as it is explicit and customizable to each user's file structure.
Relative path (not supported):
Absolute path (supported): C:/projects/cityscene/scenes/street.ma
Environment variable path (supported): $myProject/scenes/street.ma
For more information on environment variables see Setting environment variables using Maya.env.
For more information, see Edit reference paths in the Reference Editor.
When planning to use file referencing in your production environment, consider your team’s workflow practices (modelers, riggers, animators, materials and so on), as well as the overall requirements for the project before you determine your scene’s hierarchy.
In general, you should reference files in a bottom up manner (that is, reference small items into bigger items). This bottom up structure allows you to easily load or unload any segments of the scene that are not required by the user. For example, when creating a city parent scene, a door and other related components should first be referenced into a building file. Then reference the building into the street file, and then reference the street file into the city parent scene.
When building a character, reference the model into the rigged file. Then reference the rigged file into the environment where the character will be animated. This ensures that a change to the rig is correctly propagated to all environment files that may use the character.
When referencing many files into a scene, the amount of data can rapidly become complex to manage. The Outliner and Hypergraph overview editors have filtering options that allow you to limit the amount of data that gets displayed.
The Display Layer editor allows for sorting of layers alphabetically which will help with organization.
You can extract segments of a normal scene as a referenced file if it becomes more complex than originally anticipated. Specific components of the scene can be selected and then exported as a separate referenced child scene file using the Export Selection as a Reference command. Exported referenced child scene files are automatically referenced and loaded into the currently open scene. It is not possible to use the Export Selection as a Reference command using a file reference.
A nice benefit of creating file references in this manner is that each region of the scene is in the correct worldspace position and does not need to be repositioned when referenced into the parent scene.
Instancing of objects can be used to aid scene management by further reducing the amount of data in a scene. For example, if a street scene is to be filled with streetlights, the streetlight file can be referenced in once and then the remaining streetlights instanced. If the streetlight file is unloaded, all the streetlights in the scene will disappear because of their instancing relationship to the original streetlight file.
If you have a reference file and instance an object within it and then later remove the reference file, both versions of the objects will be removed in the parent scene. A transform node will be left behind in the parent scene for the instance. This node remains in case other changes have been applied to the instance by the user in the parent scene.
Do not rename a node or change a hierarchy in a referenced file if the parent scene contains objects that are instanced. Such a change will make the instance disappear; Maya will be looking for an object that no longer exists. Maya’s instancing is name-based. By renaming the object in the reference file, you make the original go away such that the parent scene can no longer find it.
The file reference locator option is useful when you need to move a file reference in the scene view via its group node. The locator also acts as a visual cue for the reference whenever the reference is unloaded. The locator option is only available in the Reference Options window when the Group option is selected. The locator option groups the contents of the referenced file under a locator, annotated with the reference node name. You can load or unload a reference within the scene by right-clicking on the locator and selecting from the context sensitive menu.
For more information, see File > Create Reference.
A parent scene file can be adversely affected by edits that are made at the referenced child scene file level of the hierarchy. That is, an edit made at the parent scene level could become unresolvable if node names and connections are changed at the child scene file level. For some examples of other adverse affects, see Modify a file reference.
Removing unwanted reference node edits
There may be situations where you want to remove unwanted edits from the reference node. For example, you have been applying and removing animation from a file reference while working within the parent scene. You’ve finalized the animation, but now want to ensure there are no unwanted setAttr edits on attributes that should not animated in the final version.
In order to remove unwanted edits you must:
Example: Removing all edits of a particular type
This example shows you how to determine the name of the reference node associated with a file referenced into your currently open scene.
reference -q -f world:planet
Maya displays the directory path and name of the reference file. In this example, the reference file name is world.
file -q -rfn world.ma
Maya displays the name of the reference node as follows:
worldRN
Once you have determined the name of the reference node, you must unload the reference file in order to remove the reference edits.
file -unloadReference worldRN
reference -editCommand “setAttr” -rfn worldRN -q
file -cleanReference worldRN -editCommand “setAttr”
The setAttr edits are removed from the reference node worldRN.
file -loadReference worldRN
Subsequent references of a file that is already referenced in the parent scene get differentiated from the first reference by the addition of a unique copy number on their filename. For example, the file named world.ma would get named world.ma{1}, world.ma{2}, and so on, in the parent scene each time it was subsequently referenced.
Avoiding use of the default shader
If you reference a file in which you’ve altered the default shader (lambert1), these changes are superseded by the default shader of the parent file. To avoid this situation, create a new shader in the child file and assign that rather than using the default shader.
If you reference a file into your current scene with shared shading networks enabled, the shading networks from the referenced scene are combined with those in the current scene (including those of any references). This avoids creating duplicate shading networks when you want the same ones used throughout your scene, including the reference.
Shading networks can only be shared if the shading networks are identical. Maya considers two shading networks to be identical only if all the nodes included in it have both the same name and type while traveling upstream from the shading group.
While the name and type of each node in the shading network must be identical in order for the shading network to be shared, the actual values in each node are not considered. So, a node in a child scene with one value (for example, blue) is considered identical to a node in the parent scene with a different value (for example, red) as long as its name and type match.
However, certain shading networks cannot be shared. They are:
If any of these items appear in the shading network, the network is not shared when the file is referenced with shared shading networks enabled.
Any items that exist downstream of the shading network are also not shared. The only items shared are those items upstream of the shading network.
All edits to referenced nodes that are shared are stored on one common shared reference node. Shared references can only be deleted from the Reference Editor using the Remove Reference menu item. The shared reference node remains for any references that were shared and is only removed when the last shared reference is removed.
Dynamic attributes that are added to a shading network that is subsequently shared may be lost unless the same attributes are created on each of the shading networks to be shared prior to sharing.
If you reference a file into your current scene with shared display layers enabled, the display layers from the referenced scene are combined with those in the current scene (including those of any references). This avoids creating duplicate display layers when you want the same ones used throughout your scene, including the reference.
Maya uses the display layer name to determine how the referenced display layer is added to the current scene. If a display layer name already exists in the parent scene, any objects assigned to an identically-named display layer in a child scene are added to the original parent display layer when they are referenced.
If a child scene contains a display layer that does not exist in the parent scene, the display layer from the child scene appears in the Display Layer editor of the parent scene when the child scene is referenced. If these child scenes are later removed from the parent scene, their associated display layers are removed from the Display Layer editor as well.
Shared display layers are automatically placed in the default namespace.
All edits to referenced nodes that are shared are stored on one common shared reference node. Shared references can only be deleted from the Reference Editor using the Remove Reference menu item. The shared reference node remains for any references that were shared and is only removed when the last shared reference is removed.
When a pre-Maya 6.5 file that contains references is converted to a later version Maya file, a reference node named "_UNKNOWN_REF_NODE_" may be created and/or a special "_UNKNOWN_REF_NODE_" entry may be added to existing reference nodes.
This node type was used to store any edits that were made prior to 6.5 until those edits could be applied.
Once all references in the scene have been loaded, all edits should be applied and the _UNKNOWN_REF_NODE_ areas and nodes should disappear. If there are any edits which can not be applied (for example, nodes in the original reference file that were renamed or deleted), the _UNKNOWN_REF_NODE_ will remain in the file.
If you need to remove these reference nodes, you can do so by querying for the _UNKNOWN_REF_NODE_ and deleting it. That is, this specific node type cannot be deleted using the Reference Editor. In the Script Editor:
File reference optimization and errors
By default, if you reference the same file twice, on file open Maya copies the existing nodes instead of re-reading them from disk. Occasionally, using this built-in multiple reference optimization feature of file referencing can cause errors. The MAYA_FORCE_REF_READ environment variable turns off the file referencing optimization and forces reference files to be explicitly read in all cases. This fixes Maya's behavior in some situations that would otherwise be evaluated incorrectly.
For more information, see General variables.
File referencing helper scripts
A number of file referencing helper scripts are available as part of the Maya Bonus Tools. Bonus Tools is a free collection of useful Maya scripts and plug-ins that are available from the Autodesk Web site (www.autodesk.com/maya-bonustools).
To download the Bonus Tools from the Autodesk web site
You will need to register in order to obtain access to some areas of the Autodesk Web site. Once installed, the Bonus Tools appear within Maya in their own drop-down menu.
Illegal character handling for namespaces
Previously, for Maya versions 2010 and below, the characters '<' and '>' would get converted to '_' if encoutered in a node name or namespace name. Any leading invalid characters are removed, and all others are converted to underscore.
namespace -add "<foo>" // Result: foo_ createNode transform -n "<bar>" // Result: bar_ namespace -add "foo<bar>" //Result: foo_bar_
For Maya 2011 and above, the characters '<' and '>' will still be removed and converted to '_' for node names. However, for namespace names, Maya will consider everything in between those characters as a placeholder namespace. Therefore, you should update your code if you are using these characters and relying on Maya to correct them. For example, in Maya 2012:
namespace -add "<foo>" // Result: <foo> createNode transform -n "<bar>" // Result: bar_ namespace -add "foo<bar>" //Result: foo_bar_
File referencing and render layers
When using file references in a scene with render layers, ensure that the current layer is the masterLayer when you import the file reference and save the scene file. Render layers and file referencing and saving are more stable if the selected layer is the masterLayer.
