MAXWrapper Common Properties, Operators, and Methods

Value > MAXWrapper : Value > MAXWrapper Derived Value

The following properties and methods are applicable to any value that is derived from MAXWrapper.

Properties

The following MAXWrapper value and class properties give you access to the plug-in category such as, Standard Primitives, Extended Primitives, or Particle Systems:

<MAXWrapperobject>.category Name, read-only 
<maxclass>.category Name, read-only 
<maxsuperclass>.categories Array, read-only

The category property returns a Name value containing the category. You can use it on either a 3ds Max object class such as, Line, Box, or Fog, or on an instance of any 3ds Max object class. For scene nodes, the category usually corresponds to one of the names in the drop down list in the Create panel. These are the categories such as, #Standard_Primitives , #Compound_Objects , and #Particles_Only .

For modifiers, the category determines which group the modifier appears in the Configure Button Sets/Modifiers list. These are the categories such as, #MAX_STANDARD , #MAX_EDIT , and #MAX_SURFACE .

For textures, the category determines which group the texture appears in the Material/Map Browser. These are the categories such as, #2D (2D maps), #3D (3D maps), and #COMP (Compositors).

The categories property can be used on any of the 3ds Max object superclasses such as, Shape, GeometryClass, Helper, SpacewarpObject, TextureMap, or Modifier to get a list of the available categories for that superclass, returned as an array of Names.

FOR EXAMPLE:

$line01.category --returns #Splines
Gengon.category --returns #Extended_Primitives
Shape.categories --returns #(#Shape, #Splines, #NURBS_Curves)

<maxsuperclass>.classes Array, read-only

Returns an array of MAXClass values that belong to the MAXSuperClass. These MAXClass values can be used to create instances of the class.

FOR EXAMPLE:

--create an instance of each light class:
for aLight in light.classes do aLight()

<MAXWrapperobject>.classID 
<maxclass>.classID

The classID property retrieves the internal 3ds Max Class ID of the MAXWrapper classes and objects.

The value returned is an array containing two numbers, PartA and PartB of the 3ds Max internal class ID.

For a MAXWrapper object, the value returned is the Class ID of the class of which the object is an instance.

The combination of the PartA and PartB numbers is guaranteed to be unique for each class.

FOR EXAMPLE:

Box.classID --returns #(16, 0)
b=box()
b.classID --returns #(16, 0)

<MAXWrapperObject>.superClassID 
<maxclass>.superClassID

Retrieves the 3ds Max superclass ID of the MAXWrapper classes and objects.

<maxclass>.creatable Boolean, read-only

Returns true if the class is flagged as being creatable.

This property returning true does not guarantee that the class is really creatable.

<maxclass>.ispb2based Boolean, read-only

Returns true if the underlying class definition is a ClassDesc2, false if a ClassDesc.

ClassDesc2 classes use ParamBlock2, and ClassDesc classes use ParamBlock (pre-3ds Max3).

<maxclass>.localizedName

A read-only property which contains the localized name of the class.

<maxclass>.dllName String, read-only

A read-only property which contains the DLL file name implementing the class, if the class was defined by a plugin DLL; otherwise it will contain undefined.

Available in 3ds Max 2012 and higher.

<maxclass>.dllIsLoaded Boolean, read-only

A read-only boolean property which contains true when the DLL implementing the class has been already loaded or false when it has been deferred. If the class was not defined in a plugin DLL, this property will contain undefined.

Available in 3ds Max 2012 and higher.

FOR EXAMPLE:

for sc in superclasses do
(
format "%\n" sc
for c in sc.classes do
format "\t% : % : %\n" c c.dllName c.dllIsLoaded
)

Methods

copy <MAXWrapper_object>

The copy() function is implemented by all the 3ds Max objects available in MAXScript such as, scene objects, controllers, modifiers, materials, and others. You can use this function to make a clone of the source object, for example, in situations where you want individual copies or you want to make a shared object unique.

FOR EXAMPLE:

addModifier $foo $baz.bend

will cause foo to share the bend modifier on baz , whereas:

addModifier $foo (copy $baz.bend)

will give foo a separate clone of the bend modifier on baz . Any changes to the bend modifier on foo will not affect baz and vice versa.

In the next example, we set up several objects that share a single rotation controller.

EXAMPLE:

c = bezier_rotation()
$foo.rotation.controller = c
$baz.rotation.controller = c
$bar.rotation.controller = c

To later make one of the controllers unique, you can do this:

$baz.rotation.controller = copy $baz.rotation.controller

When the MAXWrapper object is not a scene node, the copy is only created in MAXScript memory. When the MAXWrapper object is a scene node, a new scene node is created which is visible and accessible by the user in the 3ds Max viewports.

exprForMAXObject <MAXWrapper_object> [explicitNames: <boolean>]

Returns a string containing a MAXScript expression that will 'name' the specified MAXWrapper object using property access and indexes as needed.

FOR EXAMPLE:

If you have in variable m a bend modifier on a scene object named "foo", then:

exprForMAXObject m

will yield the string:

"$foo.bend"

When the explicitNames: option is set to true, explicit node names are returned. When set to false, selection relative names are returned. If not specified, the current Macro Recorder settings under Customize > Preferences > MAXScript tab > Code Generation are used.

This method is an exposure of an internal method used by the MacroRecorder. When the explicitNames: option is not specified, its output will vary depending on the Macro Recorder options.

MACRO RECORDER EXAMPLE:

b=box()
-->$Box:Box002 @ [0.000000,0.000000,0.000000]
c=b.pos.controller
-->Controller:Bezier_Position
exprformaxobject c
-->"$Box002.pos.controller"
bm=bend()
-->Bend:Bend
addmodifier b bm
-->OK
exprformaxobject bm
-->"$Box002.modifiers[#Bend]"

Here, changing the Macro Recorder options from "Explicit scene object names" to "Selection-relative scene object names", yields:

exprformaxobject bm
-->"$.modifiers[#Bend]"

NOTE:

In some cases, the Macro Recorder generated code does not work as expected. One such case is the ambientColorController - exprForMaxObject() returns an invalid expression in this case:

exprForMaxObject ambientColorController
-->"Scene[#Environment].Ambient_Light.controller"

Possible workarounds to access the ambient color controller are:

(getclassinstances scene)[1].Environment.Background_Color.controller 

(getclassinstances RenderEnvironment)[1].Background_Color.controller

createInstance <maxclass> [ keyarg1:v] [ keyarg2:v] ...

This method is used to directly create the 'base objects' that you see in a Node (or any other object). The main use for this is to create temporary geometry base objects from which meshes will be extracted to help create the meshes for scripted geometry primitive plug-ins. The optional <keyargs> are the same base-object keyword arguments as can be supplied for the class constructor. These are typically the parameters of the base object.

FOR EXAMPLE:

b = createInstance Box length:10 height:40 width:20

creates an instance of a Box. This box will not appear in the 3ds Max viewports, as it is not a node. It only contains the geometry associated with the Box object. You can get at the mesh representation of these instanced objects with the mesh property, which yields a TriMesh value.

replaceInstances <old_MAXWrapper> <new_MAXWrapper> transferCAs: <bool>

Replaces all instances of the old MAXWrapper with the new MAXWrapper. Old and new MAXWrapper must have the same superclass.

If transferCAs is true , any custom attributes on the old_MAXWrapper are transferred to the new_MAXWrapper if there is at least one occurrence of transferring the reference.

References are not transferred for MAXWrapper values.

Available in 3ds Max 2008 and higher. Previously, available in the Avguard Extensions.

WARNING:
Minimal error checking, use with extreme caution.

isValidObj <value>

Returns true if the value points to a MAX object (a MAXWrapper), and the MAX object has not been deleted.

NOTE:

In some cases, the MAX object might be deleted from the scene, but the object itself is not deleted. This method will return true in this case.

isValidValue <value>

Returns True if the argument is a valid value, False if the value has been deleted. Available in in 3ds Max 2017 and higher.

getClassName <MAXWrapper>

Returns the class name of the MAXWrapper as a string value.

<bool> isUsedInScene <MAXWrapper> skipCustAttributes:<false> includeXrefScenes:<false>

NEW in 3ds Max 2018: This function returns true if the MAXWrapper is used by the scene, other than by Scene Material Library (which in some cases can contain materials not being used by the scene). The scene includes the material editor, renderer, render effects, and so on. Specify skipCustAttributes as true to skip over any MAXWrapper objects held in Custom Attributes. Set includeXrefScenes as true to search any Xrefed scenes as well.

Example
mat = StandardMaterial() --> Standardmaterial:Standard isUsedInScene mat --> false s = sphere material:mat -->$Sphere:Sphere001 @ [0.000000,0.000000,0.000000] isUsedInScene mat -->true

Dependencies

An important internal mechanism in 3ds Max defines the dependency relationship between 3ds Max objects. For example, a material depends on its various maps, a path controller depends on its percent controller, a scene node depends on its base object, and so on.

The refs struct provides methods to access and manage MaxWrapper object references. These methods are provided primarily for debugging and investigating reference hierarchies. They are not required for general scripting and plug-in development. The "Get" methods are safe to use. The "Set/Replace" methods are extremely unsafe, and should only be used if you really know what you are doing.

The following method returns the MAXWrapper objects that depend on a specified MAXWrapper object.

refs.dependents&<MAXWrapper_object>[ immediateOnly:&<boolean>]

Returns an array of the 3ds Max MAXWrapper objects depending on the specified MAXWrapper object. The specified MAXWrapper object can be any MAXWrapper object such as, a scene node, controller, material, modifier, and so on.

If the optional keyword immediateOnly is supplied and set to true, only the immediate dependents of the specified object will be returned.

FOR EXAMPLE:

refs.dependents $foo.material.diffuseMap

CAN RETURN

#(Material_#3, Material_#2, Map_#2:Noise, Material_#1)

which shows that the diffuseMap in $foo is referenced in material #1, material #2, material #3, and noise TextureMap #2.

The following example shows several objects being created, and sets up controllers on the objects which depend on other objects.

SCRIPT:

theSphere=sphere ()-- create a sphere
theCone=cone radius1:0 radius2:20-- create a cone
theHelix=helix height:100 pos:[100,100,0]-- create a helix
theCone.target=theSphere-- assign theSphere as target of theCone
--  a look at controller is automatically
--  assigned to theCone
--  assign path controller to theSphere, path to follow is the helix
theSphere.position.controller=path path:theHelix
refs.dependents theSphere-- show dependents of the sphere
refs.dependents theCone-- show dependents of the cone
refs.dependents theHelix-- show dependents of the helix

OUTPUT:

$Sphere:Sphere002 @ [0.000000,0.000000,0.000000]-- result line 1
$Cone:Cone002 @ [0.000000,0.000000,0.000000]-- result line 2
$Helix:Helix002 @ [100.000000,100.000000,0.000000]-- result line 3
$Sphere:Sphere002 @ [0.000000,0.000000,0.000000]-- result line 4
Controller:Path_Constraint-- result line 8
#(Controller:Look_At, $Cone:Cone002 @ [0.000000,0.000000,0.000000])-- result line 9
#()-- result line 10
--  following is output of line 11
#(ReferenceTarget:ParamBlock2, Controller:Path_Constraint, Controller:Position_Rotation_Scale, $Sphere:Sphere002 @ [135.000000,100.000000,0.000000], Controller:Look_At, $Cone:Cone002 @ [0.000000,0.000000,0.000000])

refs.dependsOn <MAXWrapper_object>

Returns an array of the 3ds Max MAXWrapper objects that the specified MAXWrapper object directly depends on.

The specified MAXWrapper object can be any MAXWrapper object such as, a scene node, controller, material, or modifier.

FOR EXAMPLE:

b = box()
refs.dependsOn b

RETURNS

#(Controller::Position_Rotation_Scale, Box)

This shows that the node directly depends on its transform controller and its base object. The node will also be indirectly dependent on the MAXWrapper objects that these objects depend on (the position, rotation, and scale controllers for the transform controller).

refs.dependson also returns the Custom Attributes of an object. In versions prior to 3ds Max 7, Custom Attributes were not considered by this method as technically they are not dependent on the object.

refs.dependencyLoopTest <MAXWrapper_object> <MAXWrapper_object>

Returns true if the two MAXWrapper objects create a dependency loop, false otherwise.

FOR EXAMPLE:

a = box pos:[-100,0,0]
--> $Box:Box001 @ [-100.000000,0.000000,0.000000]
b = box pos:[100,0,0]
--> $Box:Box002 @ [100.000000,0.000000,0.000000]
a.material = standardMaterial()
--> Standardmaterial:Standard
refs.dependencyLoopTest a b
--> false
refs.dependencyLoopTest a a.material
--> true

refs.dependentNodes <MAXObject> firstOnly: <bool> baseObjectOnly: <bool>

Returns node(s) that are dependent on the specified MAXObject.

If firstOnly: is true, and if no nodes are dependent on the specified MAXObject, a value of 'undefined' is returned, otherwise a MAXNode value corresponding to the first dependent node found is returned.

If firstOnly: is false or not specified, the return value is always an array.

If baseObjectOnly: is true, only nodes where the MAXObject is the base object will be returned.

Available in 3ds Max 2008 and higher. Previously, available in the Avguard Extensions.

refs.replaceReference  <max_obj> <int> {<max_obj> | undefined}

Replaces the reference at index <int> with either a new reference or undefined (effectively removing the reference). Note: this is an unsafe method and will crash 3ds Max if you do not know what you are doing.

refs.setIndirectReference <MaxWrapper> <int> {<MaxWrapper | undefined}

Replaces the indirect reference at index <int> with either a new reference or undefined (effectively removing the reference). Note: this is an unsafe method and will crash 3ds Max if you do not know what you are doing.

refs.getReference <MaxWrapper> <int>

Gets the reference at index <int> in the object’s reference array.

Example:

s = sphere()
-- $Sphere:Sphere001 @ [0.000000,0.000000,0.000000]
refs.GetReference s 1
-- Controller:Position_Rotation_Scale

refs.getIndirectReference <MaxWrapper> <int>

Gets the indirect reference at index <int> in the objects reference array.

refs.getAddr <MaxWrapper>

Returns the address of the MaxWrapper as an IntegerPtr value. Available in in 3ds Max 2017 and higher.

Example:

s = sphere()
-- $Sphere:Sphere001 @ [0.000000,0.000000,0.000000]
refs.getAddr s
-- 1530273376P

refs.getNumRefs <MaxWrapper>

Returns the number of references held by the specified MaxWrapper object.

Example:

s = sphere()
-- $Sphere:Sphere003 @ [0.000000,0.000000,0.000000]
refs.getNumRefs s
-- 16

refs.getNumIndirectRefs <MaxWrapper>

Returns the number of indirect references held by the specified MaxWrapper object. Note that you can’t create indirect references with MaxScript.

Example:

n = NodeTransformMonitor()
-- ReferenceTarget:NodeTransformMonitor
refs.getNumIndirectRefs n
-- 1

notifyDependents <MAXObject> partIDmsg: <name>: <int> propogate: <bool>

Sends notification message to the dependents of the object.

Available in 3ds Max 2008 and higher. Previously, available in the Avguard Extensions.

Valid partID values and their SDK equivalents are:

#topo	PART_TOPO
#geom	PART_GEOM
#texmap	PART_TEXMAP
#mtl	PART_MTL
#TM	PART_TM
#obj	PART_OBJ
#objectType	PART_OBJECT_TYPE
#select	PART_SELECT
#subSelType	PART_SUBSEL_TYPE
#display	PART_DISPLAY
#vertColor	PART_VERTCOLOR
#gfxData	PART_GFX_DATA
#dispApprox	PART_DISP_APPROX
#extension	PART_EXTENSION
#TMchannel	PART_TM_CHAN
#MTLChannel	PART_MTL_CHAN
#all	PART_ALL
#putInFG	PART_PUT_IN_FG

The default partID is #all.

The msg value corresponds to one of the REFMSG values specified in maxsdk\include\ref.h, and documented in the SDK Help topic "List of Reference Messages and their PartID parameters". The default msg value is 0x050 (REFMSG_CHANGE), unless partID is #putInFG, in which case the default is 0x070 (REFMSG_FLAGDEPENDENTS).

If propogate: is true (the default), the messages are propagated to the dependents of the dependents, recursively.

This method is useful for notifying scripted controllers that a value used in the controller has changed.

FOR EXAMPLE, RUN:

globalmySphereRadius = 10
s=sphere()
s.radius.controller = float_script()
s.radius.controller.script ="mySphereRadius"

NOW RUN:

mySphereRadius = 50

The viewport will not update to reflect the change.

NOW RUN:

notifydependents s.radius.controller

The viewport updates to reflect that the dependents of the controller (the sphere base object and node) are notified about the controller change.

disableRefMsgs() 
enableRefMsgs()

Disable/enable reference notification system. Must be paired.

Available in 3ds Max 2008 and higher. Previously, available in the Avguard Extensions.

WARNING:
USE WITH EXTREME CAUTION

MAXWrapper Common Properties, Operators, and Methods

Dependencies

See Also