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

Synopsis

character( objects , [addElement=name], [addOffsetObject=string], [characterPlug=boolean], [clear=name], [empty=boolean], [excludeDynamic=boolean], [excludeRotate=boolean], [excludeScale=boolean], [excludeTranslate=boolean], [excludeVisibility=boolean], [flatten=name], [forceElement=name], [include=name], [intersection=name], [isIntersecting=name], [isMember=name], [library=boolean], [memberIndex=uint], [name=string], [noWarnings=boolean], [nodesOnly=boolean], [offsetNode=boolean], [remove=name], [removeOffsetObject=string], [root=string], [scheduler=boolean], [split=name], [subtract=name], [text=string], [union=name], [userAlias=name])

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

character is undoable, queryable, and editable.

This command is used to manage the membership of a character. Characters are a type of set that gathers together the attributes of a node or nodes that a user wishes to animate as a single entity.

Return value

stringFor creation operations (name of the character that was created or edited)
string[]For query operation (names of items in the character)
booleanFor isMember operation

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

Related

bakeClip, characterMap, clip, clipEditor, clipSchedule

Flags

addElement, addOffsetObject, characterPlug, clear, empty, excludeDynamic, excludeRotate, excludeScale, excludeTranslate, excludeVisibility, flatten, forceElement, include, intersection, isIntersecting, isMember, library, memberIndex, name, noWarnings, nodesOnly, offsetNode, remove, removeOffsetObject, root, scheduler, split, subtract, text, union, userAlias
Long name (short name) Argument types Properties
name(n) string create
Assigns string as the name for a new character. Valid for operations that create a new character.
text(t) string createqueryedit
Defines an annotation string to be stored with the character.
empty(em) boolean create
Indicates that the character to be created should be empty. (i.e. it ignores any arguments identifying objects to be added to the character.
subtract(sub) name query
An operation between two characters which returns the members of the first character that are not in the second character. In general, characters should be mutually exclusive.
union(un) name query
An operation that returns a list of all the members of all characters listed.
intersection(int) name query
An operation that returns a list of items which are members of all the character in the list. In general, characters should be mutually exclusive.
clear(cl) name edit
An operation which removes all items from the given character.
flatten(fl) name edit
An operation that flattens the structure of the given character. That is, any characters contained by the given character will be replaced by its members so that the character no longer contains other characters but contains the other characters' members.
nodesOnly(no) boolean query
This flag modifies the results of character membership queries. When listing the attributes (e.g. sphere1.tx) contained in the character, list only the nodes. Each node will only be listed once, even if more than one attribute or component of the node exists in the character.
isIntersecting(ii) name query
An operation which tests whether or not the characters in the list have common members. In general, characters should be mutually exclusive, so this should always return false.
isMember(im) name query
An operation which tests whether or not all the given items are members of the given character.
split(sp) name create
Produces a new set with the list of items and removes each item in the list of items from the given set.
noWarnings(nw) boolean create
Indicates that warning messages should not be reported such as when trying to add an invalid item to a character. (used by UI)
addOffsetObject(aoo) string queryedit
Indicates that the selected character member objects should be used when calculating and applying offsets. The flag argument is used to specify the character.
removeOffsetObject(roo) string edit
Indicates that the selected character offset objects should be removed as offsets. The flag argument is used to specify the character.
addElement(add) name edit
Adds the list of items to the given character. If some of the items cannot be added to the character because they are in another character, the command will fail. When another character is passed to to -addElement, is is added as a sub character. When a node is passed in, it is expanded into its keyable attributes, which are then added to the character.
include(include) name edit
Adds the list of items to the given character. If some of the items cannot be added to the character, a warning will be issued. This is a less strict version of the -add/addElement operation.
remove(rm) name edit
Removes the list of items from the given character.
forceElement(fe) name edit
For use in edit mode only. Forces addition of the items to the character. If the items are in another character which is in the character partition, the items will be removed from the other character in order to keep the characters in the character partition mutually exclusive with respect to membership.
excludeTranslate(et) boolean create
When creating the character, exclude translate attributes from transform-type nodes. For example, if your character contains joints only, perhaps you only want to include rotations in the character.
excludeRotate(er) boolean create
When creating the character, exclude rotate attributes from transform-type nodes.
excludeScale(es) boolean create
When creating the character, exclude scale attributes from transform-type nodes.
excludeVisibility(ev) boolean create
When creating the character, exclude visibility attribute from transform-type nodes.
excludeDynamic(ed) boolean create
When creating the character, exclude dynamic attributes.
userAlias(ua) name query
Returns the user defined alias for the given attribute on the character or and empty string if there is not one. Characters automatically alias the attributes where character animation data is stored. A user alias will exist when the automatic aliases are overridden using the aliasAttr command.
characterPlug(cp) boolean query
Returns the plug on the character that corresponds to the specified character member.
scheduler(sc) boolean query
Returns the scheduler associated with this character, if there is one. A scheduler will only exist if you have created clips on your character.
library(lib) boolean query
Returns the clip library associated with this character, if there is one. A clip library will only exist if you have created clips on your character.
memberIndex(mi) uint query
Returns the memberIndex of the specified character member if used after the query flag. Or if used before the query flag, returns the member that corresponds to the specified index.
root(rt) string create
Specifies the transform node which will act as the root of the character being created. This creates a characterOffset node in addition to the character node, which can be used to add offsets to the character to change the direction of the character's animtion without inserting additional nodes in its hierarchy.
offsetNode(ofs) boolean query
Returns the name of the characterOffset node used to add offsets to the root of the character.

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

# create two characters with whatever is currently active
cmds.character()
cmds.character()

# create a set which contains two sub characters
cmds.character( 'character1', 'character2', n='parentCharacter' )

# Add the keyable attributes of ikHandle1 to a character
cmds.character( 'ikHandle1', add='character1' )

# Remove the scale attributes for a transform from a character
cmds.character( 'sphere1.sx', 'sphere1.sy', 'sphere1.sz', remove='character1' )

# Query the members of the character
members = cmds.character('character1', query=True)

# Query the character plug for a specified member
cmds.character( members[0], q=True, cp=True )

# Query the library and scheduler of the character
cmds.character( 'character1', q=True, library=True )
cmds.character( 'character2', q=True, sc=True )

# Add the sphere as an offset object on the character
cmds.character( 'pSphere1', e=True, addOffsetObject = 'character1' )