Go to: Synopsis. Return value. Keywords. Related. Flags. Python examples.

Synopsis

addAttr([attributeType=string], [binaryTag=string], [cachedInternally=boolean], [category=string], [dataType=string], [defaultValue=float], [disconnectBehaviour=uint], [enumName=string], [exists=boolean], [fromPlugin=boolean], [hasMaxValue=boolean], [hasMinValue=boolean], [hasSoftMaxValue=boolean], [hasSoftMinValue=boolean], [hidden=boolean], [indexMatters=boolean], [internalSet=boolean], [keyable=boolean], [longName=string], [maxValue=float], [minValue=float], [multi=boolean], [niceName=string], [numberOfChildren=uint], [parent=string], [proxy=string], [readable=boolean], [shortName=string], [softMaxValue=float], [softMinValue=float], [storable=boolean], [usedAsColor=boolean], [usedAsFilename=boolean], [usedAsProxy=boolean], [writable=boolean])

Note: Strings representing object names and arguments must be separated by commas. This is not depicted in the synopsis.

addAttr is undoable, queryable, and editable.

This command is used to add a dynamic attribute to a node or nodes. Either the longName or the shortName or both must be specified. If neither a dataType nor an attributeType is specified, a double attribute will be added. The dataType flag can be specified more than once indicating that any of the supplied types will be accepted (logical-or).

To add a non-double attribute the following criteria can be used to determine whether the dataType or the attributeType flag is appropriate. Some types, such as double3 can use either. In these cases the -dt flag should be used when you only wish to access the data as an atomic entity (eg. you never want to access the three individual values that make up a double3). In general it is best to use the -at in these cases for maximum flexibility. In most cases the -dt version will not display in the attribute editor as it is an atomic type and you are not allowed to change individual parts of it.

All attributes flagged as "(compound)" below or the compound attribute itself are not actually added to the node until all of the children are defined (using the "-p" flag to set their parent to the compound being created). See the EXAMPLES section for more details.

Type of attribute Flag and argument to use
boolean -at bool
32 bit integer -at long
16 bit integer -at short
8 bit integer -at byte
char -at char
enum -at enum (specify the enum names using the enumName flag)
float -at "float" (use quotes since float is a mel keyword)
double -at double
angle value -at doubleAngle
linear value -at doubleLinear
string -dt "string" (use quotes since string is a mel keyword)
array of strings -dt stringArray
compound -at compound
message (no data) -at message
time -at time
4x4 double matrix -dt "matrix" (use quotes since matrix is a mel keyword)
4x4 float matrix -at fltMatrix
reflectance -dt reflectanceRGB
reflectance (compound) -at reflectance
spectrum -dt spectrumRGB
spectrum (compound) -at spectrum
2 floats -dt float2
2 floats (compound) -at float2
3 floats -dt float3
3 floats (compound) -at float3
2 doubles -dt double2
2 doubles (compound) -at double2
3 doubles -dt double3
3 doubles (compound) -at double3
2 32-bit integers -dt long2
2 32-bit integers (compound) -at long2
3 32-bit integers -dt long3
3 32-bit integers (compound) -at long3
2 16-bit integers -dt short2
2 16-bit integers (compound) -at short2
3 16-bit integers -dt short3
3 16-bit integers (compound) -at short3
array of doubles -dt doubleArray
array of floats -dt floatArray
array of 32-bit ints -dt Int32Array
array of vectors -dt vectorArray
nurbs curve -dt nurbsCurve
nurbs surface -dt nurbsSurface
polygonal mesh -dt mesh
lattice -dt lattice
array of double 4D points -dt pointArray

Return value

None

In query mode, return type is based on queried flag.

Keywords

attribute, dependency, graph, add, dynamic, create

Related

aliasAttr, attributeInfo, connectAttr, deleteAttr, disconnectAttr, getAttr, getClassification, nodeType, objExists, objectType, renameAttr, setAttr

Flags

attributeType, binaryTag, cachedInternally, category, dataType, defaultValue, disconnectBehaviour, enumName, exists, fromPlugin, hasMaxValue, hasMinValue, hasSoftMaxValue, hasSoftMinValue, hidden, indexMatters, internalSet, keyable, longName, maxValue, minValue, multi, niceName, numberOfChildren, parent, proxy, readable, shortName, softMaxValue, softMinValue, storable, usedAsColor, usedAsFilename, usedAsProxy, writable
Long name (short name) Argument types Properties
attributeType(at) string createquery
Specifies the attribute type, see above table for more details. Note that the attribute types "float", "matrix" and "string" are also MEL keywords and must be enclosed in quotes.
binaryTag(bt) string createquery
This flag is obsolete and does not do anything any more
cachedInternally(ci) boolean createquery
Whether or not attribute data is cached internally in the node. This flag defaults to true for writable attributes and false for non-writable attributes. A warning will be issued if users attempt to force a writable attribute to be uncached as this will make it impossible to set keyframes.
category(ct) string createqueryeditmultiuse
An attribute category is a string associated with the attribute to identify it. (e.g. the name of a plugin that created the attribute, version information, etc.) Any attribute can be associated with an arbitrary number of categories however categories can not be removed once associated.
dataType(dt) string createquerymultiuse
Specifies the data type. See "setAttr" for more information on data type names.
defaultValue(dv) float createqueryedit
Specifies the default value for the attribute (can only be used for numeric attributes).
disconnectBehaviour(dcb) uint createquery
defines the Disconnect Behaviour 2 Nothing, 1 Reset, 0 Delete
enumName(en) string createqueryedit
Flag used to specify the ui names corresponding to the enum values. The specified string should contain a colon-separated list of the names, with optional values. If values are not specified, they will treated as sequential integers starting with 0. For example: -enumName "A:B:C" would produce options: A,B,C with values of 0,1,2; -enumName "zero:one:two:thousand=1000" would produce four options with values 0,1,2,1000; and -enumName "solo=1:triplet=3:quintet=5" would produce three options with values 1,3,5. (Note that there is a current limitation of the Channel Box that will sometimes incorrectly display an enumerated attribute's pull-down menu. Extra menu items can appear that represent the numbers inbetween non-sequential option values. To avoid this limitation, specify sequential values for the options of any enumerated attributes that will appear in the Channel Box. For example: "solo=1:triplet=2:quintet=3".)
exists(ex) boolean createquery
Returns true if the attribute queried is a user-added, dynamic attribute; false if not.
fromPlugin(fp) boolean createquery
Was the attribute originally created by a plugin? Normally set automatically when the API call is made - only added here to support storing it in a file independently from the creating plugin.
hasMaxValue(hxv) boolean createqueryedit
Flag indicating whether an attribute has a maximum value. (can only be used for numeric attributes).
hasMinValue(hnv) boolean createqueryedit
Flag indicating whether an attribute has a minimum value. (can only be used for numeric attributes).
hasSoftMaxValue(hsx) boolean createquery
Flag indicating whether a numeric attribute has a soft maximum.
hasSoftMinValue(hsn) boolean createquery
Flag indicating whether a numeric attribute has a soft minimum.
hidden(h) boolean createquery
Will this attribute be hidden from the UI?
indexMatters(im) boolean createquery
Sets whether an index must be used when connecting to this multi-attribute. Setting indexMatters to false forces the attribute to non-readable.
internalSet(internalSet) boolean createquery
Whether or not the internal cached value is set when this attribute value is changed. This is an internal flag used for updating UI elements.
keyable(k) boolean createquery
Is the attribute keyable by default?
longName(ln) string createquery
Sets the long name of the attribute.
maxValue(max) float createqueryedit
Specifies the maximum value for the attribute (can only be used for numeric attributes).
minValue(min) float createqueryedit
Specifies the minimum value for the attribute (can only be used for numeric attributes).
multi(m) boolean createquery
Makes the new attribute a multi-attribute.
niceName(nn) string createqueryedit
Sets the nice name of the attribute for display in the UI. Setting the attribute's nice name to a non-empty string overrides the default behaviour of looking up the nice name from Maya's string catalog. (Use the MEL commands "attributeNiceName" and "attributeQuery -niceName" to lookup an attribute's nice name in the catalog.)
numberOfChildren(nc) uint createquery
How many children will the new attribute have?
parent(p) string createquery
Attribute that is to be the new attribute's parent.
proxy(pxy) string createquery
Proxy another node's attribute. Proxied plug will be connected as source. The UsedAsProxy flag is automatically set in this case.
readable(r) boolean createquery
Can outgoing connections be made from this attribute?
shortName(sn) string createquery
Sets the short name of the attribute.
softMaxValue(smx) float createqueryedit
Soft maximum, valid for numeric attributes only. Specifies the upper default limit used in sliders for this attribute.
softMinValue(smn) float createqueryedit
Soft minimum, valid for numeric attributes only. Specifies the upper default limit used in sliders for this attribute.
storable(s) boolean createquery
Can the attribute be stored out to a file?
usedAsColor(uac) boolean createquery
Is the attribute to be used as a color definition? Must have 3 DOUBLE or 3 FLOAT children to use this flag. The attribute type "-at" should be "double3" or "float3" as appropriate. It can also be used to less effect with data types "-dt" as "double3" or "float3" as well but some parts of the code do not support this alternative. The special attribute types/data "spectrum" and "reflectance" also support the color flag and on them it is set by default.
usedAsFilename(uaf) boolean createquery
Is the attribute to be treated as a filename definition? This flag is only supported on attributes with data type "-dt" of "string".
usedAsProxy(uap) boolean createquery
Set if the specified attribute should be treated as a proxy to another attributes.
writable(w) boolean createquery
Can incoming connections be made to this attribute?
Flag can appear in Create mode of command Flag can appear in Edit mode of command
Flag can appear in Query mode of command Flag can have multiple arguments, passed either as a tuple or a list.

Python examples

import maya.cmds as cmds

cmds.sphere( name='earth' )
# Add an attribute named ms/mass with a default value of 1 and a
# minimum value of 0.001 and a maximum of 10000.
#
cmds.addAttr( shortName='ms', longName='mass', defaultValue=1.0, minValue=0.001, maxValue=10000 )

# Add a multi attribute named ff/forcefield of type double3.
#
cmds.addAttr( shortName='ff', longName='forcefield', dataType='double3', multi=True )

# Add a compound attribute named sampson with children homeboy, midge,
# damien, elizabeth, and sweetpea of varying types
#
cmds.addAttr( longName='sampson', numberOfChildren=5, attributeType='compound' )
cmds.addAttr( longName='homeboy', attributeType='matrix', parent='sampson' )
cmds.addAttr( longName='midge', attributeType='message', parent='sampson' )
cmds.addAttr( longName='damien', attributeType='double', parent='sampson' )
cmds.addAttr( longName='elizabeth', attributeType='double', parent='sampson' )
cmds.addAttr( longName='sweetpea', attributeType='double', parent='sampson' )

# To add an attribute that is to be interpreted as a color the
# following attribute group must be used.
#
# Note that the word "float" must be in quotations since it is a
# MEL keyword.
#
cmds.addAttr( longName='rainbow', usedAsColor=True, attributeType='float3' )
cmds.addAttr( longName='redBow', attributeType='float', parent='rainbow' )
cmds.addAttr( longName='greenBow', attributeType='float', parent='rainbow' )
cmds.addAttr( longName='blueBow', attributeType='float', parent='rainbow' )

# Other legal attribute types that can be interpreted as colors need
# not specify the "-usedAsColor" flag as it will be assumed.  These
# include "-attributeType spectrum", "-attributeType reflectance",
# "-dataType spectrumRGB", and "-dataType reflectanceRGB".
#
cmds.addAttr( longName='implColor', dataType='spectrumRGB' )
cmds.addAttr( '.implColor', query=True, usedAsColor=True )
# Result: 1 #

# Add a double3 attribute named sanders with children bess, les and wes
#
cmds.addAttr( longName='sanders', attributeType='double3' )
cmds.addAttr( longName='bess', attributeType='double', parent='sanders' )
cmds.addAttr( longName='les', attributeType='double', parent='sanders' )
cmds.addAttr( longName='wes', attributeType='double', parent='sanders' )

# Create a ref Attribute
cmds.sphere( name='moon' )
cmds.select('earth');
cmds.addAttr(longName="someRefAttr", ref="moon.tx");