MAXScript provides a number of built-in functions for displaying information about the classes that are accessible in your particular 3ds Max installation. These functions are useful as an online reference for the core 3ds Max classes and provide the only way of determining what properties in third-party plug-in classes are accessible.
The apropos(), showClass() and showProperties() methods take pattern strings as input. Pattern strings can contain:
* matching any sequence of characters (zero or more)? matching any single character[SET] matching any character in the set[!SET] or [^SET] matching any character NOT in the set. A set is composed of characters, or a range of characters separated by a hyphen, such as "0-9" or "A-D". Sets are case-sensitive, and uppercase letters are "less than" lowercase, so "a-Z" is not valid, while "A-z" is.
Special characters can be escaped (treated as a literal character) by prepending with a backslash \. The special characters are: []*?!^-\
The apropos() function is used to search for and print out information about global variables by name pattern and class of contents.
This function has the form:
apropos <pattern_string> [ implicitWild:true ] [ to:<stream> ]The <pattern_string> argument is a string containing a wild-card pattern for matching against global variables.
The pattern form is:
<variable_name_pattern_string[:class_name_pattern_string]>that is, a global variable name pattern optionally followed by a ':' and a class name pattern.
If the optional class name pattern is given, it restricts the printout to globals containing values of the specified classes.
The apropos() function assumes a wild-card '*' at the start and end of each pattern, implying a 'contains' pattern match, unless implicitWild:false is specified, in which case no '*' are assumed. See Pattern Strings above for more information.
The output consists of the global variable name, a tag in () indicating if the variable is a system or const (unchangeable) variable and the class of the value currently in it, followed by a printed representation of that value.
EXAMPLES
apropos "light" -- any variables with 'light' in the variable name
apropos ":float" -- any variables containing float values
apropos "" to:f -- dump all variables to the stream f
apropos "controller:super" -- the list of controller superclasses
apropos "foo:control" -- any variables whose name contains 'foo'
-- and that contain controller classes
> apropos "[x-z]*" implicitWild:false -- any classes or functions that start with x, y, or z
Here's a fragment of the first example's output:
lights (const ObjectSet): $lights
lightLevel (system Float): 1.0
Sunlight (const MAXClass): Sunlight
Directionallight (const MAXClass): Directionallight
lightLevelController (system Control): Controller:Bezier_Float
light (const MAXSuperClass): light
NewLight (const Primitive): NewLight()
lightTintColor (system Color): (color 255 255 255)
Volume_Light (const MAXClass): Volume_Light
lightTintColorController (system Control): Controller:Bezier_Color
gw.getMaxLights (Primitive): getMaxLights()
gw.setLight (Primitive): setLight()
To make scripting easier to teach and use everyday, a ScriptTool function for Help has been added. It is an alias for apropos.
Typing Help "Box" will show all the commands using the name BOX.
The showClass() function prints information about a specified 3ds Max class or classes. It has the following form:
showClass <pattern_string> [ to:<stream> ]where <pattern_string> is a string containing a wild-card pattern to match against 3ds Max class names, superclass names and property names, and the optional to:<stream> keyword argument specifies a Stream Value to output the display to.
The pattern string has this form:
"<class_name>[:<superclass_name>][.<property_name>]"See Pattern Strings above for more information about special characters allowed in pattern strings.
EXAMPLES
showClass "path*" -- all 3ds Max classes starting 'path'
showClass "noise.*" -- all the accessible properties on the
-- Noise texture map
showClass "*:mod*" -- all the modifier classes
showClass "*.*rad*" -- all the classes with a property name
-- containing 'rad'
showClass "*.*" to:f -- everything, out to a file
showClass "*:*controller*" -- all the classes that have
-- "controller" in their superclass
-- name
> showClass "[X-Z]*" -- all classes that start with X, Y, or Z
In the output from the last example, the controllers include 3ds Max's core controllers and any 3rd-party plug-in controllers. In some cases, embedded controllers for some complex plug-ins might be visible in the showClass() listing (such as for Character Studio Bipeds). You must not attempt to create and use these controllers individually, this might result in system exceptions.
If you leave out the superclass pattern (the ':' part), it matches all superclasses. If you leave out the property pattern (the '.' part), you only get class names printed.
The following shows examples of the showClass() output:
SCRIPT:
showclass "box*" -- show all classes whose name starts with "box"
showclass "box.*" -- show all properties for class box
OUTPUT:
Box : GeometryClass {10,0} -- start of output from line 1
BoxGizmo : helper {3bc31904,67d74ec9}
OK -- result returned from line 1
Box : GeometryClass {10,0} -- start of output from line 2
.height : float
.length : float
.lengthsegs : integer
.width : float
.widthsegs : integer
.mapCoords : boolean
.heightsegs : integer
OK -- result returned from line 2
The getObjectName function returns the class name of an object, as it would appear in the history browser or modifier stack. If the passed object is not an object or modifier, this function returns undefined. The function has the following syntax:
getObjectName <object> [localizedName:<bool>] When the localizedName keyword parameter is true (the default), the localized name as it appears in the UI is returned. Otherwise the non-localized name is returned. Available in in 3ds Max 2022 and later
For example:
SCRIPT:
myBox = Box name:"myBox"
myBend = Bend()
myCompass = Compass()
getObjectName myBox
--> "Box"
getObjectName myBend
--> "Bend"
getObjectName myCompass
--> "Compass"
The showProperties() function is used to display the properties for a specific object that is an instance of one of the MAXWrapper classes. It can be used in place of showClass() in situations where you have an actual object in hand. Unlike showClass() , it can display the dynamic properties that might appear in individual objects as you work on them in the scene such as, the sub-controllers in a list controller or the animated control points in an FFD modifier.
The showProperties() function has the following form:
showProperties <maxwrapper_object> [ <property_pattern> ] [ to :<stream> ]where <maxwrapper_object> is the 3ds Max entity to be inspected, the optional <property_pattern> is a wild-card pattern that names the properties to be inspected, and the optional to:<stream> keyword argument specifies a Stream Value to output the display to.
The <property_pattern> is a pattern string. See Pattern Strings above for more information about special characters in pattern strings.
If the property name pattern is not supplied, all properties are listed.
SCRIPT:
showProperties $foo.bend -- show properties of the Bend modifier on object foo
ffdmod = $baz.'FFD_box__4x4x4' -- point to the FFD modifier on object baz
showProperties ffdmod "disp*" to:log -- show properties starting with "disp" in the FFD modifier
showProperties $foo.pos.controller -- sub controllers in a position list controller
> showProperties $foo "[t-z]*" -- show properties starting with t to z on object foo
When the 3ds Max entity specified is a node (for example, $box01), this function only displays the properties of the base object. It does not show the properties of the transform controllers, modifiers, or materials applied to the object. To display the properties for one of these objects, it must be specified as the 3ds Max entity as shown in the above examples.
showProperties includes properties defined by FPS interfaces in 3ds Max 8 and higher.
The following shows examples of the showProperties output:
SCRIPT:
b = box() -- create a box
ffd_mod = ffdBox() -- create a ffdBox modifier
addmodifier b ffd_mod -- apply ffdBox modifier to the box
showproperties b -- show all properties for the box
showproperties ffd_mod -- show all properties for the ffdBox modifier
OUTPUT:
$Box:Box07 @ [0.0000,0.0000,0.0000] -- result from line 1
FFD_box__4x4x4:FFD(box) 4x4x4 -- result from line 2
OK -- result from line 3
.height : float -- start of output from line 4
.length : float
.lengthsegs : integer
.width : float
.widthsegs : integer
.mapCoords : boolean
.heightsegs : integer
OK -- result from line 4
.dispLattice (Lattice) : boolean -- start of output from line 5
.dispSource (Source Volume) : boolean
.deformType (<unknown>) : integer
.falloff : float
.tension : float
.continuity : float
.inPoints (Inside Points) : boolean
.outPoints (Outside Points) : boolean
.offset : float
.lattice_transform : transform
OK -- result from line 5
To make scripting easier to teach and use everyday, a ScriptTool function for "Show" has been added.
Show is the short way of typing ShowProperties
EXAMPLE:
Show $ --will show you the properties of the selected object
The getPropNames() function is similar to showProperties() , except it returns the property names for a specific object as an array. Unlike showProperties() , you can specify whether to return only the names of dynamic properties of the object.
The getPropNames function has the form:
getPropNames <maxwrapper_obj> [ #dynamicOnly]The getPropNames() function returns an array of the property names accessible on the object.
FOR EXAMPLE:
if a FFD(Box) modifier with animated control points is applied to a sphere,
getPropNames $sphere01.'FFD(box) 4x4x4'
could yield:
#(#dispLattice, #dispSource, #deformType, #falloff, #tension, #continuity, #inPoints, #outPoints, #offset, #Lattice_Transform, #Control_Point_49, #Control_Point_50, #Control_Point_51, #Control_Point_52, #Control_Point_53)
When the 3ds Max entity specified is a node (for example, $box01), this function only returns the properties of the base object. It does not return the properties of the transform controllers, modifiers, or materials applied to the object. To return the properties for one of these objects, it must be specified as the 3ds Max entity as shown in the above examples.
getPropNames includes properties defined by FPS interfaces in 3ds Max 8 and higher.
If you call getPropNames() on MAXWrapper classes such as, Box, Line, or Bend, it will return the properties common to all instances of that class. If you call getPropNames() on a 3ds Max entity, it will return the properties currently defined for that entity. If you add the optional keyword #dynamicOnly to the getPropNames() call for an entity, it returns the dynamic properties unique to that instance.
FOR EXAMPLE:
if a FFD(Box) modifier with animated control points is applied to a sphere,
getPropNames $sphere01.'FFD(box) 4x4x4' #dynamicOnly
could yield:
#(#Lattice_Transform, #Control_Point_49, #Control_Point_50, #Control_Point_51, #Control_Point_52, #Control_Point_53)
#dynamicOnly is specified. These properties are unique to the specific FFD modifier.As a special case, you can also call getPropNames() on the superclass 'Node' to get the list of properties common to all scene nodes such as, .position , .name , or .wireColor .
FOR EXAMPLE:
getPropNames node
The getPropNames method has been extended to work with the various interface values. The method will return the names of properties exposed by the interface.
FOR EXAMPLE:
getpropnames s.inode
#(#boneEnable, #posTaskWeight, #rotTaskWeight, #boneAutoAlign, #boneFreezeLength, #boneScaleType, #stretchTM, #boneAxis, #boneAxisFlip, #primaryVisibility, #secondaryVisibility, #applyAtmospherics, #vertexColorType, #showVertexColors, #shadeVertexColors, #handle, #posInParent, #rotInParent, #scaleInParent, #scaleOrientInParent)
The getProperty() and setProperty() functions allow you to access and set properties using computed property names.
The forms for each of these functions are:
getProperty <obj> <property_name> [removeUIScaling:<boolean>]
setProperty <obj> <property_name> <value> [applyUIScalling:<boolean>]The property name can be either a name, for example, #length , or a string, for example, "length" . You can construct property names with string operations.
The removeUIScaling/applyUIScaling parameters default to true. If false, the value will be affected by the scale factor on High DPI displays, for those properties related to screen values (for example, #pos for UI controls). Available in in 3ds Max 2017 and higher.
EXAMPLES:
getProperty foo #x -- equiv. to foo.x
setProperty $foo "radius" 23 -- equiv. to $foo.radius = 23
getProperty $foo.ffd_2x2x2 ("control_point_" + n as string)
The getPropNames() function can be used in conjunction with the getProperty() function to implement object 'dumping’ tools that can iterate over all the properties of an arbitrary object and output them as required.
FOR EXAMPLE:
for p in getPropNames $foo do
format "% = %\n" p (getProperty $foo p)
Similar functions for accessing and setting the values of property-assigned controllers are:
getPropertyController <value> <string_or_name>
setPropertyController <value> <string_or_name> <controller>Get and set the controller assigned to the named property of the value. If no controller has been assigned to the property, a value of undefined is returned.
As of 3ds Max 2024, setting a propertty controller to a controller value of undefined removes the current controller.
The hasProperty() function allows you to test whether an object has a specified property name. Unlike isProperty(), the property name string supports wildcard patterns.
hasProperty <obj> <prop_name_or_pattern_string>Returns true if the object has the given property or has properties matching the string pattern.
FOR EXAMPLE:
hasProperty $Box01 "height" --test for height in a Box
--> true
hasProperty $Box01 "radius" --test for radius in a Box
--> false
hasProperty $Sphere01 "radius" --test for radius in a Sphere
--> true
hasProperty $Sphere01 "rad*" --test for any property name
--> true --starting with "rad" in a Sphere
The isProperty() function allows you to test whether an object has a specified property.
isProperty <MAXWrapper_object> <property_name_or_string>isProperty() returns true if the specified property is a property of the MAXWrapper object, false otherwise. The property name can be either a name, for example, #length , or a string, for example, "length" . You can construct property names with string operations.
EXAMPLES:
b=box()
s=sphere()
isProperty $Box001 #height --test for height in a Box
--> true
isProperty $Box001 #radius --test for radius in a Box
--> false
isProperty $Sphere001 #radius --test for radius in a Sphere
--> true
hasProperty and isProperty do entirely different things.
EXAMPLES:
hasProperty $Box01 "name"
--> false
isProperty $Box01 "name"
--> true
hasProperty uses the same code as showPropeties() , but instead of returning a list of the properties found, it returns true on the first property name that matches the specified pattern. showProperties is looking at just the box base object and its MAXClass definition. It does not look at any higher level properties (and in versions prior to 3ds Max 8 it does not look at any of the FPS interface exposed properties).
isProperty on the other hand actually tries to access the specified object with the specified name and to detect whether the access succeeded or failed.
isPropertyAnimatable <obj> <string_or_name>Returns true if the property is found and is animatable. Returns false if the property is not found or is not animatable.
FOR EXAMPLE:
s = Sphere() --create a sphere
--> $Sphere:Sphere01 @ [0.000000,0.000000,0.000000]
isPropertyAnimatable s #radius --check if radius is animatable
--> true
isPropertyAnimatable s #mapCoords --check if UV coords are
--> false
ANOTHER EXAMPLE:
s = Sphere() --create a sphere
--Print a list of all properties of the sphere and whether
--they are animatable or not:
for i in getPropNames s do
format "% Property: % - Animatable: %\n"s.name i (isPropertyAnimatable s i)
RESULT:
$Sphere:Sphere003 @ [0.000000,0.000000,0.000000]
Sphere003 Property: #smooth - Animatable: true
Sphere003 Property: #radius - Animatable: true
Sphere003 Property: #segs - Animatable: true
Sphere003 Property: #mapcoords - Animatable: false
Sphere003 Property: #slice - Animatable: false
Sphere003 Property: #hemisphere - Animatable: true
Sphere003 Property: #sliceFrom - Animatable: true
Sphere003 Property: #sliceTo - Animatable: true
Sphere003 Property: #chop - Animatable: false
Sphere003 Property: #recenter - Animatable: false
Sphere003 Property: #realWorldMapSize - Animatable: false
OK
3ds Max stores all of properties for objects in structures called subAnims. In some cases, a subAnim will contain nested subAnims. An example of this can be seen with the Standard material. If you apply a Standard material to a 3ds Max object, and then expand the object's tracks in Track View to display the material, you will see three Track View nodes - Parameters, Maps, and Shader. Each of these nodes is a subAnim defined in the Standard material’s class. Expanding the tracks for these three nodes, you will see various properties listed. These properties are defined in each of the nested subAnims in a structure called a ParamBlock.
MAXScript automatically finds animatable properties in all ParamBlocks associated with an object. To access these properties, you use the same nesting as shown in Track View when referencing those properties in MAXScript.
FOR EXAMPLE,
you would access the Ambient Color property in a Standard material in MAXScript as:
$box01.material.shader.diffuse_color
For more information about accessing animatable properties in MAXScript, see also Indexed Access to Animatable Properties in 3ds Max Objects.
The properties accessible on various kinds of values are documented for each class. Many of the foundation classes in MAXScript (such as, point3, color, and so on) support a special kind of nested-property assignment which allows sub-properties on object properties such as, the .x , .y , and .z coordinates in a node's .position property to be individually and directly set. See Nested Object Properties for details.