XRefObject : Node

An XRefObject value represents an XRef object in 3ds Max. An XRefObject value is returned when the *xrefs.addNewXRefObject()* function is called. There are two objects associated with an XRef object in 3ds Max - the non-proxy object and the proxy object. The proxy object is typically a lower resolution object that is used as a standin for the non-proxy object in the viewports.

Note: In 3ds Max 8 and newer, the objXrefMgr is the preferred way of working with XRefs in MAXScript. Scripts that use both XRefObject and objXrefMgr methods on the same XRefObject may not work correctly.

Constructor

xrefs.addNewXRefObject <filename> {<objectname> | <objectname_array>} [#proxy] \
 modifiers:{#xref | #merge | #drop}    manipulators: {        #xref | #merge }        \
dupMtlNameAction: {#prompt |    #useXRefed |    #useScene |    #autoRename} \
reparentAction: {#promptReparent|#alwaysReparent|#neverReparent}

Loads the specified node object from the specified scene file as an XRef object. The case of *objectname_string* must match the object's name in the scene file.

If an array of object names is specified, the return value will be an array of the XRef'ed objects. Note that if a manipulator's name is specified in the array, and manipulator: *#merge* is specified, the merged manipulator is not included in the result array since it isn't an XRef Object.

If *#proxy* is specified, the node object is loaded as the proxy object, otherwise it is loaded as the non-proxy object.

The XRefObject is always loaded at world center.

References between XRef objects brought in as a single operation are maintained, so that if you have a object parameter controlled by a manipulator, and you XRef in both the object and the manipulator, the manipulator will still control the object's parameter.

Modifiers:

#xref - XRef Object contains any modifiers on object (default)
#merge - XRef Object contains base object, any modifiers on object are applied to the XRef Object
#drop - XRef Object contains base object, any modifiers on object are dropped

Manipulators:

#xref - bring manipulator in as an xref
#merge - bring in manipulator as a manipulator

dupMtlNameAction: (available in 3ds Max 2010 and higher)

#prompt - Prompts the user to define the duplicated material names action (default)
#useXRefed - Uses the material from the XRef.
#useScene - Uses the scene material.
#autoRename - Rename the material to avoid dupilication.

reparentAction: (available in 3ds Max 2019.1 Update and higher)

#promptReparent - Prompt the user to re-parent the xref (the default).
#alwaysReparent - Always re-parent the xref, and do not prompt the user. This is the default if 3ds Max is running in quiet mode (for example, running as Max Batch).
#neverReparent - Never reparent the xref, and do not prompt the user.

In 3ds Max 6 and higher, *xrefs.addNewXRefObject* returns undefined when the argument is a file with DRF extension.

Properties

<XRefObject>.proxyFileName String default: varies

The file name of the proxy object.

<XRefObject>.fileName String default: varies

The file name of the non-proxy object.

<XRefObject>.currentFileName String default: varies

The file name of the non-proxy object if the *useProxy* property is *false* , the file name of the proxy object if the *useProxy* property is *true* .

<XRefObject>.objectName String default: varies

The name of the non-proxy object.

<XRefObject>.proxyObjectName String default: varies

The name of the proxy object.

<XRefObject>.currentObjectName String default: varies

The name of the non-proxy object if the *useProxy* property is *false* , the name of the proxy object if the *useProxy* property is *true* .

<XRefObject>.useProxy Boolean default: varies

If *true* , the proxy object will be displayed in the viewports, otherwise the non-proxy object will be displayed.

If the XRef object is added to the scene using the *xrefs.addNewXRefObject()* method, this parameters default value will be *true* if *#proxy* is specified, *false* otherwise.

<XRefObject>.renderProxy Boolean default: false

If *true* , the proxy object will be rendered, otherwise the non-proxy object will be rendered.

<XRefObject>.updateMaterial Boolean default: false

If *true* , sets the Update Material option on.

<XRefObject>.ignoreAnimation Boolean default: false

If *true* , sets the Ignore Animation option on.

<XRefObject>.actualBaseObject -- read-only

Returns the actual base object of the referenced object as opposed to the base object of the XRefObject.

If 'Use Proxy' is turned on for the XRefObject, the proxy base object is returned if a proxy object is defined, otherwise a value of 'undefined' is returned.

Available in 3ds Max 8 and higher.

Methods

updateXRef <XRefObject>

Reloads the XRef object.

The following XRefObject interfaces are available in 3ds Max 8 and higher:

XRefObject interfaces

Interface:IXRefItem

Properties

.srcFileName : filename : Read

Contains the source file name.

Read-only.

.srcItemName : string : Read

Contains the name of the source item.

Read-only.

.xrefRecord : Interface : Read

Contains the XRef record Interface.

Read-only.

.unresolved : boolean : Read

Contains true if the XRef is unresolved, false otherwise.

Read-only.

.nested : boolean : Read

Contains true if the XRef is nested, false otherwise.

Read-only.

Methods

<maxObject>GetSrcItem resolveNested:<boolean>

resolveNested default value: false

Returns the source item object of the XRef Object.

If the object is being referenced from nested files (in other words, the object is referenced from a Max file containing an XRef of the object from another file instead of the actual object) and resolveNested is set to true, nested XRef files will be resolved.

<integer>GetParentItems <&maxObject array>parentItems

parentItems is Out parameter

Returns an array of parent items in the by-reference Out parameter.

<integer>GetRootItems <&maxObject array>rootItems

rootItems is Out parameter

Returns an array of root items in the by-reference Out parameter.

<integer>GetChildItems <&maxObject array>childItems

childItems is Out parameter

Returns an array of child items in the by-reference Out parameter.

<void>GetNodes <&node array>xrefNodes

xrefNodes is Out parameter

Returns an array of XRef nodes in the by-reference Out parameter.

Interface:IXRefProxy

Properties

.proxyFileName : filename : Read

Contains the proxy file name.Read-only.

.proxyItemName : string : Read

Contains the proxy item name.Read-only.

.proxyRecord : Interface : Read

Contains the proxy record Interface.Read-only.

.displayProxy : boolean : Read|Write

When set to True, the proxy will be used in the viewport.

.renderProxy : boolean : Read|Write

When set to True, the proxy will be used by the production renderer.

.useLocal : boolean : Read|Write

Get/set the state of the "Enable/Use Local" property in the "Proxy Object" rollout.

When set to False (default), the Proxy Object will not be used and the XRef content will be loaded instead.

When set to True, the local Proxy Object will be loaded.

Available in 3ds Max 2016 and higher.

Interface:IXRefObject

Properties

.activeFileName : filename : Read

Contains the active file name.Read-only.

.activeObjName : string : Read

Contains the active object name.Read-only.

.activeRecord : Interface : Read

Contains the active record Interface.Read-only.

Methods

<maxObject>GetSourceObject <boolean>resolveNestedXRef modifiers:<&maxObject array>

modifiers default value: #()
modifiers is Out parameter

Returns the source object. The optional modifiers: by-reference parameter will return the array of modifiers applied to the source object.

XRefObject : Node

XRefObject interfaces

Related pages