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 a scene, and also a way to define UI rollups for accessing these attributes.

Custom Attributes Topics:

Adding Custom 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 using 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 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>
)

Remarks

The name is a descriptive name for the definition and can be either a <name> or a <string>.

EXAMPLE

   gameDataCA = attributes "Game Data"
   (
   ...
   )
   or
   attributes gameData
   (
   ...
   )

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 modify panel. However, the semantics are different for these two cases. Whenever the rollouts are created in the create tab, their state will be 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, and so on. The default value of 0x7fffffff is used, so the command panel can detect that this value is not being overridden, and leave the rollouts as is. For example, a value of 0x07 results in the first three 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 attributes for 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:

EXAMPLE

   weaponDataCA= attributes weaponData
   (
   parameters main rollout:params
   (
   hitPoints type:#float ui:hits default:10
   cost type:#float ui:cost default:100
   sound type:#string
   )

   rollout params "Weapon Parameters"
   (
   spinner hits "Hit Points" type: #float
   spinner cost "Cost" type: #float
   dropdownlist sound_dd "Sound" items:# ("boom","sparkle","zap","fizzle")

   on sound_dd selected i do sound = sound_dd.items [i]
   )
   )

The auto-UI connection between the parameters and rollout items using 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 such as, base objects, modifiers, materials, nodes, controllers, rootnodes, render effects, and others.

Custom attributes is currently supported only in the Material Editor and the Command Panel, so you can only 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 two element array, where each element contains an array of string literal or name values. The size of the two arrays must be the same.

The names in the first array are the existing parameter names and 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.

EXAMPLE

   CAT_DEF = attributes Custom_Attributes
   Redefine:CAT_CurrentDef
   remap: # (# ("Param1"),# ("Param9"))
   (
   Parameters main rollout:params
   (
   'Param9' Type:# float UI:'Param9' Default:0.0
   'Param2' Type:# float UI:'Param2' Default:0.0
   )
   Rollout Params "Custom Attributes"
   (
   spinner 'Param9' "Param9" Width:160 Height:16 Align: # Center Type: # float Range:[0,100,0]
   spinner 'Param2' "Param2" Width:160 Height:16 Align: # Center Type: # float Range:[0,100,0]
   )
   )
   CustAttributes.add CAT_TargetObject CAT_DEF #Unique BaseObject : false

This will move the data associated with Param1 to Param9 in existing instances.

Next Topic:

MSCustAttribDef Class