Node User-Defined Properties and Methods

The functions described in this topic give you access to scene object user properties, accessible in the 3ds Max user interface in the User Defined tab in the Object Properties Dialog.

There are two ways to access and set the user defined properties in the Object Properties dialog, either as one single string representing the entire contents or as key/property pairs in the form:

<key1> = <property1><key2> = <property2>...

where, the keys are identifiers (Name or String values) and the properties can be numbers, booleans ( true / false ), or text strings. There are two MAXScript methods for setting and getting individual keyed properties, and two methods that let you treat the property text as a single big string.

The <node> methods are:

getUserProp <node> <key_string> 	 

Retrieves the node's user property with the given key as a string. <key_string> is either a String or a Name value. If the key does not exist, a value of undefined is returned.

setUserProp <node> <key_string> <value>   

Sets the node's user property with the given key to the given value.

getUserPropBuffer <node> 

Retrieves the entire user property buffer as a string containing all the user property settings. This is effectively the contents of the User Defined Properties box in the 3ds Max Object Properties dialog.

setUserPropBuffer <node> <string> 

Sets the user property buffer to the given string.

The following two example code fragments save and load user properties for objects in a scene.

The first code fragment creates a file and loops through all objects outputting for each the object name and user property buffer string. Note that the object name goes out in a form that will come back in (through a readValue() ) as a direct reference to a scene object. Also, the user property string is output using print() , so it will be in a quoted form to be read as one (long) string literal by a corresponding readValue() .

-- create file and for all objects,
-- dump object name and user props
f = createFile "foo.dat"
for o in objects do
(
format "$%\n" o.name to:f -- output name in a pathname form
print (getUserPropBuffer o) to:f -- output buffer as a string literal
)
close f

The second code fragment reads in the file created by the first piece and applies the user properties to any same-named object in the current scene. Note that readValue() can read in pathnames ( $<name> ) and will yield either the named scene object or undefined if the named object is not in the scene. The readValue() function can also read in a multiline string literal in one pass.

-- open file and read in object names and
-- user properties to set
f = openFile "foo.dat"
while not eof f do
(
o = readValue f-- read object
if o != undefined then-- if present, read and set user prop string
setUserPropBuffer o (readValue f)
)
close f