Pathname Literals

Names identify entities such as variables and parameters inside the running MAXScript program. If you want to identify objects by name in the 3ds Max scene, you use a pathname. Pathnames can name a single object in the scene, specify a particular object using a path through the object hierarchy, or name sets of objects using pattern matching.

The full syntax for a pathname literal is:

<path_name> ::= $<path> | $ 
<path> ::= [ <objectset> ] [ / ] [ <levels> ] <level_name> 
<levels> ::= <level> { / <level> } 
<level> ::= <level_name>

<level_name> ::= { <alphanumeric > | _ | * | ? | \ }
'{ <alphanumeric > | _ | * | ? | \ }'

The root of a <path> can be an <objectset> , which limits the pathname searching to the object set you specify. ObjectSets are described in ObjectSet Values.

EXAMPLES:

$box01 -- object named 'box01'
$torso/left_up_arm/left_low_arm -- hierarchy path name
$*box* -- all objects with 'box' in
-- the name
$torso/* -- all the direct children of
-- $torso
$helpers/d* -- all helper objects whose name starts with 'd'

All objects in a 3ds Max scene are arranged in a hierarchy as presented in Track View. This is both an important organizing scheme in 3ds Max, and it suggests a MAXScript naming scheme for objects based on the path to an object through the hierarchy. It is also very similar to path names in an operating system's directory structure.

FOR EXAMPLE:

$dummy/head/neck

names the scene object neck whose parent is object head , which has the top-level parent object dummy . This pathname helps you identify a specific object in a 3ds Max scene, even if several objects have the same name. If head is unique in the scene, MAXScript lets you use the shorthand $head to refer to it regardless of its hierarchy position. Even if the object is not uniquely named you can use the shorthand form, but it is undetermined which of the same-named objects you will get.

Pathnames also provide a powerful way to refer to several objects at once, such as all the children of a certain parent, or all the objects with names containing the string foot . For this, you can use wild-card patterns, as you can with operating system shell file naming schemes.

FOR EXAMPLE:

$dummy/*

names all the immediate children of dummy . The "*" character is used as a wild card.

$neck*

finds all the objects, whose names start with the string neck , anywhere in the hierarchy.

You can use wild cards anywhere in a pathname.

FOR EXAMPLE:

$*foot*

finds all the objects with foot anywhere in their names. The "*" wild-card character effectively matches any number other characters.

You can also use the "?" wild-card character to match exactly one "don't care" character. This is, the "?" wild-card character will match any single character.

FOR EXAMPLE:

$box0?

finds all the objects that begin with box0 and have exactly one character after the 0 in their names.

Wild-card characters can also be used for specifying parent levels in a hierarchy.

FOR EXAMPLE:

$dummy/*/*

names all the children of all the children of $dummy .

If you want to find an object and all the children of the object at any nested level, you use the special ellipsis level name "...",

FOR EXAMPLE:

$dummy/.../box*

names all the children of all the children of $dummy .

This refers to $dummy and all the box* children at any level below $dummy . The "..." indicates to search the entire hierarchy below the level of the ellipsis. MAXScript lets you omit the "/" when using "..." because it is unambiguous:

$dummy...box*

Or, in another common example,

$dummy...*

names $dummy and all the children of $dummy at any level.

If you use a wild card in an object pathname MAXScript will manipulate all matching objects at one time.

FOR EXAMPLE:

hide $*foot*

hides all objects whose names contain foot .

You can also perform automatic collection mapping, where a property for each matching object is set.

FOR EXAMPLE:

$*box*.position += [10, 10, 0]

adds [10,10,0] to the positions of all scene objects whose names contain box . For more information, see Collections.

You can use a shorthand form for specifying the currently selected object or objects with the pathname syntax. A lone "$" character refers to either the currently selected object if a single object is selected, the current selection set as an ObjectSet if more than one object is selected, or undefined if no objects are selected. This is a useful shorthand for use in the Listener when working on selections.

FOR EXAMPLE:

$.pos = [0,0,0]
hide $
rotate $ 35 z_axis

NOTE:

Inside a script, it is better to use the selection ObjectSet rather than $ .

selection always contains an ObjectSet regardless of the number of selected objects. Where hide $ will generate an error if no objects are selected (because $ contains the value undefined ), hide selection will not generate an error.

Due to the way that 3ds Max internally processes notification signals, the $ form of accessing selected objects is not recommended in a select change handler. To access the selected objects, you should use the selection ObjectSet. This is because $ relies on information that has not yet been set in the selection processing whereas selection uses a different method of accessing selections and the information it uses has been set up.

Pathname Literals

See Also