The following management functions are available through the custAttributes struct:

custAttributes.count <obj> [BaseObject:<boolean>]      

Returns a count of the number of separate scripted custom attribute sets have been added via the .add() function.

If the optional keyword argument baseObject is set to true (the default), in case the object specified is a node, the base object will be operated on instead. If false , the node itself will be operated on.

custAttributes.get <obj> (<index> | <attrib_def>)[BaseObject:<boolean>] 

Returns the custom attribute set, specified as an index or by its defining attribute definition.

If the optional keyword argument baseObject is set to true (the default), in case the object specified is a node, the base object will be operated on. If false , the node itself will be operated on. (In versions prior to 3ds Max 5.1, the base object was always used.)

The custom attribute set values returned by the custAttributes are effectively holder values for the object's custom parameters in that attribute set. You can get at these parameter values as simple properties on the attribute set value.

EXAMPLE

   gp = custAttributes.get $ gameParams
   gp.hitPoints= 50                   

This is equivalent to accessing the custom attribute parameters directly on the object:

   $.gameParams.hitPoints = 50                 

custAttributes.delete <obj_or_collection> (<index> | <attrib_def>) [baseObject:<boolean>] 

Deletes the specified custom attribute set from the object or from all the objects in the given collection. The set to be deleted is defined by index number or by its defining attributes definition.

If the optional keyword argument baseObject is set to true (the default), in case the object specified is a node, the base object will be operated on. If false, the node itself will be operated on.(In versions prior to 3ds Max 5.1, the base object was always used.)

custAttributes.makeUnique <obj> (<index> | <attrib_def>) [baseObject:<boolean>] 

If some objects with custom attribute sets share a specific attributes definition, you can make selected objects have unique copies of the definition.

If the optional keyword argument baseObject is set to true (the default), in case the object specified is a node, the base object will be operated on. If false , the node itself will be operated on.(In versions prior to 3ds Max 5.1, the base object was always used.)

EXAMPLE

   custAttributes.add $box* def1              

You can make box01 unique with:

   custAttributes.makeUnique $box01 def1           

or all of them unique with:

   custAttributes.makeUnique $box* def1         

custAttributes.getDef (<obj> <index>) | <custAttrib> [baseObject:<boolean>] 

Returns the attribute definition for a given custom attribute set in an object or from a custom attribute set accessed with the .get() method.

If the optional keyword argument baseObject is set to true (the default), in case the object specified is a node, the base object will be operated on. If false , the node itself will be operated on.(In versions prior to 3ds Max 5.1, the base object was always used.)

custAttributes.getDefs <obj> [baseObject:<boolean>] 

Returns an array of definitions in attribute set order.

If the optional keyword argument baseObject is set to true (the default), in case the object specified is a node, the base object will be operated on. If false , the node itself will be operated on.(In versions prior to 3ds Max 5.1, the base object was always used.)

Next Topic:

Custom Attributes Definition Values

Handling Scripted Custom Attribute Definition Conflicts

3ds Max uses the version information of scripted custom attribute definitions to decide how to manage situations where there was a conflict between an existing custom attribute and one being loaded from a scene. Starting with 3ds Max 2012, the CA definition with the highest version number is used, by default. However, this behavior can be changed using the following methods in the custAttributes struct.

custAttributes.getSceneLoadVersionHandlingBehavior()

Returns the current behavior for handling custom attribute definition conflicts when a scene is loaded.

custAttributes.setSceneLoadVersionHandlingBehavior   {#neverUpdate | #alwaysUpdate | /
 #updateWhenLoadVersionGreaterThanCurrentVersion | #updateWhenLoadVersionGreaterThanOrEqualToCurrentVersion} /
 persistent:<boolean>

Sets the behavior for handling custom attribute definition conflicts when a scene is loaded. The options are:

• #neverUpdate - never use the definition from the scene file, regardless of the version number
• #alwaysUpdate - always use the definition from the scene file, regardless of the version number
• #updateWhenLoadVersionGreaterThanCurrentVersion - only use the scene file version when its version number is greater than the existing definition version
• #updateWhenLoadVersionGreaterThanOrEqualToCurrentVersion - only use the scene file version when its version number is greater or equal to the existing definition version

When persistent is true, this setting is persisted between 3ds Max sessions.

custAttributes.getSceneMergeVersionHandlingBehavior()

Returns the current behavior for handling custom attribute definition conflicts when a scene or object is merged with the current scene.

custAttributes.setSceneMergeVersionHandlingBehavior {#neverUpdate | #alwaysUpdate | /
 #updateWhenLoadVersionGreaterThanCurrentVersion | #updateWhenLoadVersionGreaterThanOrEqualToCurrentVersion} /
 persistent:<boolean>

Sets the behavior for handling custom attribute definition conflicts when a scene or object is merged. The options are:

• #neverUpdate - never use the definition from the merged scene file, regardless of the verison number
• #alwaysUpdate - always use the definition from the merged scene file, regardless of the version number
• #updateWhenLoadVersionGreaterThanCurrentVersion - only use the merged scene file version when its version number is greater than the existing definition version
• #updateWhenLoadVersionGreaterThanOrEqualToCurrentVersion - only use the merged scene file version when its version number is greater or equal to the existing definition version

When persistent is true, this setting is persisted between 3ds Max sessions.

Scene Loading Callbacks for Custom Attributes

There are some situations where you might want to manage how custom attribute definitions are handled when loading scene files, for example if an API changes and you need to "patch" the custom attributes in a new version of 3ds Max. You can register callbacks to deal with custom attributes using these methods.

custAttributes.registerDefLoadCallback <function>

Registers a callback that is called for each scripted custom attributed definition as it is loaded from the scene. The <function> takes a single argument, which is the custom attribute definition as a string, and returns a string. The function can modify the string to effectively re-define the custom attribute as it is loaded. Available in 3ds Max 2021 and higher. Note: You should only make the minimum changes required to make the Custom Attribute definition successfully load, as the definition is then used to load instances of the Custom Attribute from the scene. Specifically, do not add or remove parameters, change their type, or change whether they are animatable, as all of these changes will affect the load process. If you need to make more extensive changes, you can do so after the scene has loaded using custAttributes.redefine().

If there are errors when the callback runs, the error message is printed to the listener and the function is removed as a callback (it is no longer called for subsequent custom attribute definitions).

You can register multiple functions as callbacks.

<boolean>custAttributes.unRegisterDefLoadCallback <function>

Removes the specified function. Returns true if the callback is found and removed, false if it is not found. Available in 3ds Max 2021 and higher.

custAttributes.unRegisterAllDefLoadCallbacks()

Removes all callbacks registered by registerDefLoadCallback(). Available in 3ds Max 2021 and higher.

custAttributes.showregisteredDefLoadCallbacks [to:stream] [asArray:<boolean>]

Shows all callbacks registered by registerDefLoadCallback(). If to: is specified, output is sent to the specified stream. If asArray:true is specified, information is returned as an array. Each array element will be a 2 element array, where the first element is the function name, and the second element is the script file where the function was defined, if any. Available in 3ds Max 2021 and higher.

For Example

Consider the "weaponData" custom attribute example. If we wanted to change the "default" parameter, and add a version parameter, we could register the following callback:

fn modifyCADef def =
(
if (findstring def "weaponData") != undefined do 
    (
        def = substituteString def "default:10" "default:20"
        def = substituteString def "attributes weaponData\n" "attributes weaponData version:1\n"
    )
    def
)
custAttributes.registerDefLoadCallback modifyCADef
custAttributes.showregisteredDefLoadCallbacks()