Scripted Custom Attributes
Custom Attributes let you create and assign additional parameters to any object, modifier, or material in your scene. This is useful for game and other project-specific data.
MAXScript provides a way to define and add these custom attributes to objects in the scene and also a way to define UI rollups for accessing these attributes.
Global and Private Custom Attributes Definitions
Custom Attribute Management Functions
Custom Attributes Definition Values
Access to Custom Attributes Virtual Array
Custom Attributes in Materials and Texture Maps
Attribute Definitions
Attributes can be added to an object via an " attribute definition ". This is a syntactic construct in MAXScript that is similar to a scripted plug-in definition, but rather than adding a new plug-in class, a definition is built that can be used to add custom attributes and rollout UI to any number of objects at any time, through a special function.
The syntax has the following form:
attributes <name> [version:n] [silentErrors:t/f] [initialRollupState:0xnnnnn] [remap:#(<old_param_names_array>, <new_param_names_array>)] ( <locals> <globals> <parameters> <rollouts> <handlers> )
The name is a descriptive name for the definition and can be either a <name> or a <string>.
The attribute header keyword parameters and main clauses are basically identical to the same keyword parameters and clauses in Scripted Plug-ins. The 'custom attributes' are effectively the parameters defined in any parameter clauses in the body of the attributes definition. The UI for them is defined by the rollout clauses, which will be automatically displayed in the Command Panel and Material Editor when an object containing custom attributes is selected.
The initialRollupState argument is an integer whose 32 bits are used to initialize the rollouts' rollup state in both the create and the modify panel. The semantics are different, however for these two cases. Whenever the rollouts are created in the create tab, their state will be that specified by this value. In the modify tab, the first time an object of this type is modified the state will be that of this value, but after that it will remain what it was last set to. The bits of this value indicate the corresponding rollout is rolled up (closed). The zero bit corresponds to the first rollout, the first bit is the second rollout, etc. The default value of 0x7fffffff is used so the command panel can detect this value is not being overridden, and just leave the rollouts as is. For example, a value of 0x07 would result in the first 3 rollouts being rolled up, and the remaining rollouts open. (2^2+2^1+2^0 = 4+2+1 = 7)
The following example defines three new attributesfor weapon objects in a game level editor set up. The attributes, hitPoints, cost and sound, are defined as parameters and the UI for them in a rollout:
The auto-UI connection between the parameters and rollout items via the ui and keyword is the same as the support in Scripted Plug-ins. You can treat attribute scripting as basically identical to scripting plug-ins, in terms of parameter, rollout setup and handler programming.
Since 3ds Max 5.1, scripted custom attributes can be applied to any MAXWrapper object - base objects, modifiers, materials, nodes, controllers, rootnodes, render effects, etc.
The only place the UI for custom attributes is currently supported is the Material Editor and the Command Panel, so you will only be able to see any rollouts associated with the custom attributes on base objects, modifiers, and materials.
Remapping Parameters when Redefining Custom Attributes
The optional remap :keyword allows parameter names in the definitions to be changed when updating existing definitions. It is also available in Scripted Plug-ins.
The keyword takes as an argument a 2 element array, where each element contains an array of string literal or name values. The size of the 2 arrays must be the same.
The names in the first array are the existing parameter names, the names in the second array are the new parameter names. As parameter names are read in while migrating existing plugin instances, the parameter names are searched for in the first array. If the name is found, the data associated with that parameter is moved to the parameter name in the corresponding location in the second array. If a parameter name is not found in the first array, the parameter name is not remapped. If the parameter name in the second array does not match a parameter name in the new definition, the parameter data is not moved to the new definition.
This will move the data associated with parameter Param1 to parameter Param9 in existing instances.
See Also
Except where otherwise noted, this work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License. Please see the Autodesk Creative Commons FAQ for more information.