MAXScript Language Reference > 3ds Max Objects > Custom Attributes >

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

NoteYou cannot use Custom Attributes for per-facedata. 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 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:

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

Note

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.

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

- Scripted Plug-ins

- Scripted Plug-in Clauses