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 sets of 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 user defined properties in the Object Properties dialog are accessed 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, though Names are not recommended, see the note below) and the properties can be values. For the old methods, these can be numbers, booleans, or text strings. For the new methods, any value where (val==execute(val as string)) is true can be used.

Note: The setUserProp()/getUserProp() methods do not always produce predictable results. The setUserPropVal()/getUserPropVal() methods are the preferred way to get/set user properties, as of 3ds Max 2019.1 Update.

Note: The key is case sensitive. If a name value is used, it is converted to the string originally used to define the name value, which might be different than the case of the specified name value itself. For this reason, we do not recommend you use name values as keys for any of these methods.

The <node> methods are:

getUserPropVal <node> <key_string> [asString:<boolean>] [decodeCRLF:<boolean>]

Retrieves the node's user property, where the property key corresponds to <key_string>. Available in 3ds Max 2019.1 Update and higher. The property value's string is evaluated as a MaxScript value if asString is not specified, or is specified as false. If the evaluation of the value's string is successful, that value is returned, otherwise the value's string is returned as a string value. If asString is specified as true, the property value's string is always returned as a string value.

The node parameter can be specified as rootNode or an XRef root node (the .tree property), which gets a user defined property for that root node. Available in 3ds Max 2019.2 Update and higher

When returning a string value, if the first and last character of the string are quotes, those quotes are removed from the string. When returning a string value, if decodeCRLF is not specified or is specified as true, any carriage return or line feed hex representations in the property value's string are converted to carriage return or line feed characters, otherwise they are not. That is, '\xd\xa' would be converted to '\r\n'.

If the property key does not exist, a value of undefined is returned. If the property key exists but no value is present, a value of 'emptyVal' is returned.

Note: Using getUserPropVal() to retrieve properties written either in the Object Properties dialog or with setUserProp() may give unexpected results. For example:setUserProp "p1" "xxx"; v=getUserPropVal "p1". In this case, v will most likely be 'undefined', because it was not saved in quotes, so is considered a value representation (a global variable name), and the contents of the variable name are returned. This is essentially the same as v=execute "xxx".

Note: The special value type emptyVal (a distinguished instance of the Empty class) is used to indicate properties that have a key but no value. For example, if the property key "xxx" is defined without a value, calling getUserPropVal() returns an 'emptyVal'. For keys that are not defined, the same call returns 'undefined'.

setUserPropVal <node> <key_string> <value>  [quoteString:<boolean>] [encodeCRLF:<bool>]

Sets a user property on node, where the property key corresponds to <key_string> and the property value is corresponds to <value>. Available in 3ds Max 2019.1 Update and higher. Any value type where (val == execute (val as string)) can be used. If <value> is a string, and quoteStrings is not specified or is specified as true, the property value's string is enclosed in quotes, otherwise it is not. If <value> is a string, and encodeCRLF is not specified or is specified as true, any carriage return or line feed characters in the property value's string are converted to hex representations, otherwise they are not. That is, '\r\n' would be converted to '\xd\xa'. If a value of 'emptyVal' is used, the key is written but no value is written.

The node parameter can be specified as rootNode or an XRef root node (the .tree property), which sets a user defined property for that root node. Available in 3ds Max 2019.2 Update and higher.

getUserProp <node> <key_string>

Retrieves the node's user property, where the property key corresponds to <key_string>. If the key does not exist, a value of undefined is returned. MAXScript tries to convert the property value to a number, if that fails then to a boolean, and if that fails it returns the value as a text string. This can cause incorrect conversions in some cases. For example, if the property value was set to "1m", getUserProp() returns a Time value of 1800f since "1m" is interpreted as a Time literal of 1 minute. For this reason you should use getUserPropVal() instead.

The node parameter can be specified as rootNode or an XRef root node (the .tree property), which gets the user defined properties for that root node. Available in 3ds Max 2019.2 Update and higher.

setUserProp <node> <key_string> <value>

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

The node parameter can be specified as rootNode or an XRef root node (the .tree property), which sets a user defined property buffer for that root node. Available in 3ds Max 2019.2 Update and higher.

<boolean>doesUserPropExist <node> <key_string>

Returns true if the specified user property exists on the node. Available in 3ds Max 2019.1 Update and higher.

The node parameter can be specified as rootNode or an XRef root node (the .tree property), which looks for user defined property for that root node. Available in 3ds Max 2019.2 Update and higher.

<boolean>deleteUserProp <node> <key_string>

Deletes specified user property on node. Available in 3ds Max 2019.1 Update and higher. Returns true if the property existed.

The node parameter can be specified as rootNode or an XRef root node (the .tree property), which deletes a user defined property for that root node. Available in 3ds Max 2019.2 Update and higher.

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.

Note:

To include new line characters in a multi-line User Property Buffer string, you have to use the combination \r\n (carriage return and new line). See String Literals for a list of control characters.

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() .

EXAMPLE

-- 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.

EXAMPLE

-- 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

You can access the user property buffer on an XRef by first getting the XRef with xrefs.getXRefFile(), and then getting the XRef root node with the .tree property.

EXAMPLE

-- Properties on an xref scene
i = 1  -- index value
z = xrefs.getXRefFile i
getUserPropBuffer (z.tree)

<dict> getUserPropsAsDict <node> [asString:<bool>] [decodeCRLF:<bool>]

NEW in 3ds Max 2024.1 Update: Returns a dictionary containing the user properties defined for the specified node.

If the optional asString keyword parameter is specified as true, the values in the returned key/value pairs is returned as a string, regardless of its type. The default is false.

If the optional decodeCRLF keyword parameter is specified as true, any carriage return or line feed hex representations in the property value's string are converted to carriage return or line feed characters, otherwise they are not. That is, '\xd\xa' would be converted to '\r\n'. The default is true.

For example:

t = teapot()
myProps = Dictionary #("prop1", "one") #("prop2", 42) #("prop3", true)
setUserPropsFromDict t myProps
getUserPropsAsDict t
--> Dictionary #string (DataPair "prop1" "one") (DataPair "prop2" 42) (DataPair "prop3" true) 
getUserPropsAsDict t asString:true
--> Dictionary #string (DataPair "prop1" "one") (DataPair "prop2" "42") (DataPair "prop3" "true")

setUserPropsFromDict <node> <dict> quoteStrings:<bool> encodeCRLF:<bool>

NEW in 3ds Max 2024.1 Update: Sets the user properties for the specified node to the specified dict, where the keys become the property names and the values become the corresponding values.

Warning:

Calling this method will overwrite any existing user properties on the node.

If the optional quoteStrings keyword parameter is specified as true, the property value's string is enclosed in quotes, otherwise it is not. The default is false.

If the optional encodeCRLF keyword parameter is specified as true, any carriage return or line feed characters in the property value's string are converted to hex representations, otherwise they are not. That is, '\r\n' would be converted to '\xd\xa'.