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.

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 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 rollup UI to any number of objects at any time, through a special new function.

Note:

You cannot use Custom Attributes for per-face data. The face-data channels store objects of a user defined type and MAXScript cannot create objects of types other than those known by MAXScript.

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

)

)

Notes:

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 attribues on base objects, modifiers, and materials.

Remapping Parameters when Redefining Custom Attributes

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

For 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 parameter Param1 to parameter Param9 in existing instances.

Next Topic:

MSCustAttribDef Class

See also

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