Go to: Synopsis. Return value. Keywords.
Related. Flags.
Python examples.
addAttr([attributeType=string], [binaryTag=string], [cachedInternally=boolean],
[category=string], [dataType=string], [defaultValue=float], [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], [readable=boolean], [shortName=string], [softMaxValue=float], [softMinValue=float], [storable=boolean], [usedAsColor=boolean], [usedAsFilename=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 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 |
None
In query mode, return type is based on queried flag.
attribute, dependency, graph, add, dynamic, create
aliasAttr, attributeInfo, connectAttr, deleteAttr, disconnectAttr, getAttr, getClassification, nodeType, objExists, objectType, renameAttr, setAttr
attributeType, binaryTag, cachedInternally, category, dataType,
defaultValue, enumName, exists,
fromPlugin, hasMaxValue, hasMinValue, hasSoftMaxValue, hasSoftMinValue, hidden, indexMatters, internalSet, keyable, longName,
maxValue, minValue, multi,
niceName, numberOfChildren, parent, readable,
shortName, softMaxValue, softMinValue, storable, usedAsColor, usedAsFilename, writable
| Long name (short name) |
Argument types |
Properties |
longName(ln) |
string |
  |
|
Sets the long name of the attribute. |
|
shortName(sn) |
string |
|
|
Sets the short name of the attribute. |
|
niceName(nn) |
string |
 |
|
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.) |
|
binaryTag(bt) |
string |
|
|
This flag is obsolete and does not do anything any more |
|
attributeType(at) |
string |
|
|
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. |
|
dataType(dt) |
string |
 |
|
Specifies the data type. See "setAttr" for more information on
data type names. |
|
defaultValue(dv) |
float |
|
|
Specifies the default value for the attribute (can only be used
for numeric attributes). |
|
multi(m) |
boolean |
|
|
Makes the new attribute a multi-attribute. |
|
indexMatters(im) |
boolean |
|
|
Sets whether an index must be used when connecting to this
multi-attribute. Setting indexMatters to false forces the attribute
to non-readable. |
|
minValue(min) |
float |
|
|
Specifies the minimum value for the attribute (can only be used
for numeric attributes). |
|
hasMinValue(hnv) |
boolean |
|
|
Flag indicating whether an attribute has a minimum value. (can
only be used for numeric attributes). |
|
maxValue(max) |
float |
|
|
Specifies the maximum value for the attribute (can only be used
for numeric attributes). |
|
hasMaxValue(hxv) |
boolean |
|
|
Flag indicating whether an attribute has a maximum value. (can
only be used for numeric attributes). |
|
cachedInternally(ci) |
boolean |
|
|
Whether or not attribute data is cached internally in the node.
This flag is currently not supported (it will always be set to a
default value of true). |
|
internalSet(internalSet) |
boolean |
|
|
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. |
|
parent(p) |
string |
|
|
Attribute that is to be the new attribute's parent. |
|
numberOfChildren(nc) |
uint |
|
|
How many children will the new attribute have? |
|
usedAsColor(uac) |
boolean |
|
|
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 |
|
|
Is the attribute to be treated as a filename definition? This
flag is only supported on attributes with data type "-dt" of
"string". |
|
hidden(h) |
boolean |
|
|
Will this attribute be hidden from the UI? |
|
readable(r) |
boolean |
|
|
Can outgoing connections be made from this attribute? |
|
writable(w) |
boolean |
|
|
Can incoming connections be made to this attribute? |
|
storable(s) |
boolean |
|
|
Can the attribute be stored out to a file? |
|
keyable(k) |
boolean |
|
|
Is the attribute keyable by default? |
|
fromPlugin(fp) |
boolean |
|
|
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. |
|
softMinValue(smn) |
float |
|
|
Soft minimum, valid for numeric attributes only. Specifies the
upper default limit used in sliders for this attribute. |
|
hasSoftMinValue(hsn) |
boolean |
|
|
Flag indicating whether a numeric attribute has a soft
minimum. |
|
softMaxValue(smx) |
float |
|
|
Soft maximum, valid for numeric attributes only. Specifies the
upper default limit used in sliders for this attribute. |
|
hasSoftMaxValue(hsx) |
boolean |
|
|
Flag indicating whether a numeric attribute has a soft
maximum. |
|
category(ct) |
string |
|
|
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. |
|
enumName(en) |
string |
|
|
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 |
|
|
Returns true if the attribute queried is a user-added, dynamic
attribute; false if not. |
|
| 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. |
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' )