An XRefScene value represents an XRef Scene object in 3ds Max. An XRefScene value is returned when the *xrefs.addNewXRefFile()* and *xrefs.getXRefFile()* functions are called.

XRef Scene objects can be nested. For example, scene file A can contain an XRef Scene object specifying XRef file B, and XRef file B can contain an XRef Scene object specifying XRef file C (eg: A xrefs B, and B xrefs C). To provide access to the nested XRef scene objects, the applicable XRefScene methods provide an optional root keyword parameter. If this argument is provided then these methods act on the root node of the specified XRefScene value, otherwise they act on root node of the current scene. To get to C from A, you load A and do something like:

EXAMPLE

   bXref = xrefs.getXRefFile 1-- taken from root node of current scene
   cXref = xrefs.getXRefFile 1 root:bXref-- taken from root of bXref
   cRoot = cXref.tree -- to get root of C 

Scenes with a script controller whose script has explicit references ($sphere01, etc.) to objects in an incoming xref scene have a problem where the objects in the xref scene are invisible to MAXScript, and so the script will fail. This is actually a general problem with xrefs, you cannot have scripts of any kind in the xref scene (scripts controllers, param wires, callback scripts, etc.) that depend on explicit scene object references.

This problem has been solved in 3ds Max 8 and higher where scripted controllers store references using parameter blocks and can resolve them within nested xrefs.

Constructor

xrefs.addNewXRefFile <filename_string> [        #noLoad] [        root: <XRefScene>]      

Adds a new XRef Scene object and returns a XRefScene value. If *#noLoad* is not specified, the XRef Scene file is loaded immediately and the scene updated. If *#noLoad* is specified, the scene is not updated until the user requests it. Use the *updateXRef()* method to load the XRef Scene object.

If *root:<XRefScene>* is specified, the XRef Scene object is treated in the current file during the current session as if it was an XRef Scene object in the file corresponding to the XRefScene value specified. If the specified root XRef Scene object is reloaded, either because the current scene was saved and then reloaded, or because *updateXRef()* was executed on the root XRef Scene object, the XRef Scene object is deleted from the scene.

*xrefs.addNewXRefFile* does not return an error when passed a DRF file - it will return a value different from undefined, and the xref-ed DRF file will appear in red, meaning that there is a "problem" with it. This behaviour is the same as if the user would have opened a DRF file in the File Xref Scene | Add dialog after choosing the All Files filter (.)

xrefs.getXRefFile <index> [     root: <XRefScene>]   

If *root* is not specified, returns the XRefScene value corresponding to the indexed XRef Scene object in the XRef Scenes dialog. If the *root:<XRefScene>* is specified, the XRefScene value corresponding to a nested XRef Scene object within the XRefScene's XRef Scene object is returned. The index is 1-based, and corresponds to the order of the XRef Scene objects listed in the XRef Scenes dialog. You can use the *xrefs.getXRefFileCount()* method to determine the number of XRef Scene objects in the scene.

<RootNode> as XRefScene

Available in 3ds Max 2018 and higher: The "owning" XRefScene for this XRef Scene object. This is a read-only property. If this is a top level XRefScene, this returns undefined .

FOR EXAMPLE:

   aXref = xrefs.getXRefFile 1 --> XRefScene:"xrefed_teapot.max"
   bXref = xrefs.getXRefFile 1 root:aXref --> XRefScene:"teapot.max"
   aXref.owner --> $<root>
   classof aXref.owner --> MAXRootNode
   aXref.root --> undefined
   bXref.owner --> $<root>
   classof bXref.owner --> MAXRootNode
   bXref.root --> XRefScene:"xrefed_teapot.max"
   classof bXref.root --> XRefScene

<XRefScene>.tree : MAXRootNode

The root node of the XRef Scene object. This is a read-only property. You can access the children objects in an XRef Scene object using this property.

FOR EXAMPLE:

   aXref=xrefs.getXRefFile 1-- returns first XRef Scene object
   aXref.tree.children-- objects in the XRef Scene object,
   -- for example, may return:
   -- #children($Box01, $Box02)
   aXref.tree.children[1].width-- returns width value of $Box01
   -- Get user defined properties
   getUserPropBuffer (aXref.tree)

<XRefScene>.parent Node default: undefined 

The parent of the XRef Scene object. By default this is *undefined* but can be set to any node in the scene.

<XRefScene>.autoUpdate Boolean default: false 

If true, automatic XRef file updating is on.

<XRefScene>.boxDisp Boolean default: false 

If true, all nodes the in the XRef Scene object are displayed in Box display mode.

<XRefScene>.hidden Boolean default: false 

If true, the XRef Scene object is hidden.

<XRefScene>.disabled Boolean default: false 

If true, the XRef Scene object is disabled.

<XRefScene>.ignoreLights Boolean default: false 

If true, the lights in the XRef Scene object will not be displayed.

<XRefScene>.ignoreCameras Boolean default: false 

If true, the cameras in the XRef Scene object will not be displayed.

<XRefScene>.ignoreShapes Boolean default: false 

If true, the shapes in the XRef Scene object will not be displayed.

<XRefScene>.ignoreHelpers Boolean default: false 

If true, the helpers in the XRef Scene object will not be displayed.

<XRefScene>.ignoreAnimation Boolean default: false 

If true, any animation in the XRef Scene object will be ignored.

<XRefScene>.overlay Boolean default: false 

If true, treats the XRef scene as an overlay. Overlays allow multiple scene references without the risk of creating circular dependencies. The XRef scene with overlay = true is loaded only into the main scene that references it, and is not visible in other scenes that might XRef the main file that uses the overlay.

Methods

delete <XRefScene> 

Deletes the XRef Scene object.

merge <XRefScene> 

Merges the nodes in the XRef Scene object into the scene and deletes the XRef Scene object.

updateXRef <XRefScene> 

Tries to reload the XRef Scene object. Returns *true* if the operation is successful, *false* otherwise.

flagChanged <XRefScene> 

This method indicates that the specified XRef Scene object has been changed and should be updated. Use the *xrefs.updateChangedXRefs()* method to update the changed XRef Scene objects.

Associated Methods

xrefs.getXRefFileCount [root: <XRefScene>] 

If *root* is not specified, returns the total number of top-level XRef Scene objects in the scene. If the *root:<XRefScene>* is specified, the total number of XRef Scene objects in the nested XRef file within the XRefScene's XRef file is returned.

xrefs.deleteAllXRefs [root: <XRefScene>] 

If *root* is not specified, deletes all XRef Scene objects. If the *root:<XRefScene>* is specified, only the specified XRefScene's XRef Scene object, and its nested XRef Scene objects, are deleted.

xrefs.updateChangedXRefs [#noRedraw] [root: <XRefScene>] 

If *root* is not specified, updates all XRef Scene objects flagged as changed. If the *root:<XRefScene>* is specified, only the specified XRefScene's XRef Scene objects flagged as changed are updated. If *#noRedraw* is specified, the viewports won't be updated after the XRef Scene objects are loaded. Returns *true* if the XRef Scene objects were loaded okay, otherwise *false* .

xrefs.findUnresolvedXRefs [root: <XRefScene>] 

If *root* is not specified, returns an array of file name strings for all the unresolved XRef Scene objects. If the *root:<XRefScene>* is specified, only the unresolved XRef Scene objects within the specified XRefScene's XRef Scene object are returned.

xrefs.attemptUnresolvedXRefs [root: <XRefScene>] 

If *root* is not specified, tries to load any XRef Scene objects that are currently unresolved. If the *root:<XRefScene>* is specified, only the unresolved XRef Scene objects within the specified XRefScene's XRef Scene object are loaded.