A XRefScene value represents a XRef Scene object in 3ds max. A XRefScene value is returned when the xref.addNewXRefFile() and xref.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:
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
Note:
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.
However, MAXScript now fully loads any persistent globals in xref'd and merged files, but does NOT make them persistent in the current scene.
As an example of a setup showing how this can be used to address the problem stated above, imagine a file with 3 spheres that will be xref'd. You need to establish persistent globals for all the scene objects to be referrenced in controller scripts, like this:
persistent global s1 = $sphere01, s2 = $sphere02, s3 = $sphere03
This has to be run sometime while the to-be-xrefed scene is the currently open scene and in the controller scripts, you'd say something like:
global s1, s2
dependsOn s1 s2
(s1.pos + s2.pos) / 2
Note this uses 'global' not 'persistent global', so you don't go making them persistent again when they get xref'd into some other scene. So the all the scripts should use persistent globals and not have explicit node name references.
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.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.
Properties
<XRefScene>.filename String default: varies
The file name of the XRef Scene object. If you change this property to a new scene file name, the objects in the specified file are displayed, replacing the objects from the initial scene file.
<XRefScene>.tree Node
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
<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.
Methods
Deletes the XRef Scene object.
Merges the nodes in the XRef Scene object into the scene and deletes the XRef Scene object.
Tries to reload the XRef Scene object. Returns true if the operation is successful, false otherwise.
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.