Controller Key Functions

Value > MAXWrapper > Controllers > Key Functions

 

   

Animation Controllers - Quick Navigation

    

addNewKey <controller> <time> [#select]

Adds a new key to the controller track at the specified time. The value for the new key is the interpolated controller value at the specified time. The new key is also selected if the #select optional argument is specified. The value for the new key is the interpolated controller value at that time. addNewKey() will not add a key if it already exists at the specified time. The return value in this case is the key located at the specified time.

NOTE:If the controller is a compound controller (like a Position_XYZ controller), a value of OK is returned. A single key value cannot be returned because addNewKey creates a key in each of the sub-controllers.

This function returns a MAXKey value representing the key, so you can set its various properties. See MAXKey Values for details.

    

deleteKeys <controller> [#allKeys | #selection]

Deletes keys from the controller according to the optional symbolic argument supplied.

#allKeys (default): deletes all keys in the controller.

#selection : deletes the currently selected keys

    

deleteKey <controller> <index>

Deletes the indexed key. Key indexes are 1- based.

    

selectKeys <controller> [ <interval> | <time> ]

Selects the specified keys in the track view. If an interval is given, all the keys within the interval are selected. If a single time is given, the key at that time is selected. If no time or interval is given, all keys are selected.

    

deselectKeys <controller> [ <interval> | <time> ]

Deselects specified keys. Arguments are as described in selectKeys() .

    

selectKey <controller> <index_integer>

Selects the indexed key. Key indexes are 1- based.

    

isKeySelected <controller> <index_integer>

Returns true if indexed key is selected, false otherwise. Key indexes are 1- based.

    

deselectKey <controller> <index_integer>

Deselects the indexed key. Key indexes are 1 -based.

    

moveKeys <controller> <time> [#selection]

Moves the specified keys by the time given. If #selection is specified, move the current selection otherwise move all keys. The moveKeys function only works on track properties: .controller and .track . It is not defined on the keys’ virtual array.

EXAMPLES 

moveKeys $box01.pos.controller 5
moveKeys $box01.pos.track 5

    

moveKey <controller> <index_integer> <time>

Move the indexed key by the specified time.

    

numKeys <controller>

Returns the number of keys in the controller. Returns -1 if you call it on a controller that does not support keyframing.

    

getKey <controller> <index_integer>

Returns the indexed key as a MAXKey instance. See Controller Key Functions for MAXKey class information.

    

getKeyTime <controller> <index_integer>

Returns the time of indexed key.

    

getKeyIndex <controller> <time>

Returns the index of the key at the specified time.

    

numSelKeys <controller>

Returns the number of keys currently selected in the track view.

    

sortKeys <controller>

Re-sorts keys according to their times. Some MAXKey operations can result in out of order keys and this function must be called to correctly order keys. See the Controller Keys and Key Properties topic for MAXKey properties information.

    

createLockKey <controller> <time> <rot_or_pos_integer>

This method is called to create a locking key at the specified time. This is a key that looks back to the previous key and creates a new key at the specified time that matches the previous key in value. It also adjusts the parameters for the key such that the value stays constant from the previous key to this key. For instance, for a TCB controller the continuity of the previous key and new key will set to 0. For a Bezier controller the out tangent type of the previous key is set to linear and the in tangent type of the new key is set to linear.

If the controller passed to this method is a transform level controller, <rot_or_pos_integer> specifies whether to create the key in the transform controller’s position or rotation (or roll angle) sub-controller. If rot_or_pos_integer = 0, the key is created in the position controller. For all other values, the key is created in the rotation (or roll angle) controller.

If the controller passed to this method is not a transform level controller, the <rot_or_pos_integer> value is not used.

Returns true if the key creation was successful, false otherwise.

The following script shows example usages of some of the above methods.

EXAMPLES 

-- controller test bed 2
b=box height:10
at time 5 animate on b.height=50
at time 10 animate on b.height=100
bhc=b.height.controller
bhk=bhc.keys
addnewkey bhc 7
addnewkey bhc 9
for k in bhk do format "%:%\n" k.time k.value
selectKeys bhc (interval 7 9)
deleteKeys bhc #selection
bhk
addnewkey bhc 7
addnewkey bhc 9
selectKeys bhc (interval 7 9)
deleteKeys bhc #selection #slide
bhk
addnewkey bhc 7
addnewkey bhc 9
selectKeys bhc (interval 7 9)
deleteKeys bhc #selection #slide #rightToLeft
bhk
addnewkey bhc 8
i=getKeyIndex bhc 8
selectKey bhc i
moveKey bhc i 10
bhk
getKeyTime bhc 4
b.width.controller=noise_float()
numkeys b.width.controller

    

appendKey <key_array> <max_key>

Appends the given key to the specified key array at the key’s original time.

EXAMPLE 

--Create a Box and a Sphere
source_obj = box()
target_obj = sphere()
-- Animate the position of the Box on frames 50 and 100.
with animate on
(
at time 50 source_obj.pos.controller.x_position = 100
at time 100 source_obj.pos.controller.x_position = 200
)
--Animate the position of the Sphere on frames 40 and 80
with animate on
(
at time 40 target_obj.pos.controller.x_position = 50
at time 80 target_obj.pos.controller.x_position = 60
)
--Print keys of both controllers
format "Source Keys X Pos: %\n"source_obj.pos.x_position.controller.keys
format "Target Keys X Pos: %\n"target_obj.pos.x_position.controller.keys
--Get the 2nd key from the X axis controller of the position transformation
source_key = source_obj.pos.x_position.controller.keys[2]
--Get the X axis position controller keys array of the target object
target_keys = target_obj.pos.x_position.controller.keys
--Assign the key from the source to the target controller
appendKey target_keys source_key
--The Sphere now has a 3rd key on frame 50 with the value 100
format "Target Keys After appendKey: %\n" target_obj.pos.x_position.controller.keys

OUTPUT 

$Box:Box008 @ [0.000000,0.000000,0.000000]
$Sphere:Sphere001 @ [0.000000,0.000000,0.000000]
200
60
Source Keys X Pos: #keys(0f, 50f, 100f)
OK
Target Keys X Pos: #keys(0f, 40f, 80f)
OK
#Bezier Float key(2 @ 50f)
#keys(0f, 40f, 80f)
#Bezier Float key(3 @ 50f)
Target Keys After appendKey: #keys(0f, 40f, 50f, 80f)
OK

    

assignKey <key_array> <max_key> <index>

Deletes the key specified by <index> from the target key array and inserts the source key into the target key array at the source key’s time.

NOTE:

The source key first overwrites the target key specified by <index>, then the resulting array is sorted by time. The result is the same as described above.

EXAMPLE 

--Create a Box and a Sphere
source_obj = box()
target_obj = sphere()
-- Animate the position of the Box on frames 50 and 100.
with animate on
(
at time 50 source_obj.pos.controller.x_position = 100
at time 100 source_obj.pos.controller.x_position = 200
)
--Animate the position of the Sphere on frames 10 and 20
with animate on
(
at time 10 target_obj.pos.controller.x_position = 50
at time 20 target_obj.pos.controller.x_position = 60
)
--Print keys of both controllers
format"Source Keys X Pos: %\n" source_obj.pos.x_position.controller.keys
format"Target Keys X Pos: %\n" target_obj.pos.x_position.controller.keys
--Get the 2nd key from the X axis controller of the position transformation
source_key = source_obj.pos.x_position.controller.keys[2]
--Get the X axis position controller keys array of the target object
target_keys = target_obj.pos.x_position.controller.keys
--Assign the key from the source to the target controller,
--delete original sourcekey 3
assignKey target_keys source_key 3
--The Sphere now has a 3rd key on frame 50 with the value 100,
--original 3rd key on frame 20 has been deleted:
format "Target Keys After assignKey: %\n" target_obj.pos.x_position.controller.keys

LISTENER OUTPUT 

$Box:Box009 @ [0.000000,0.000000,0.000000]
$Sphere:Sphere002 @ [0.000000,0.000000,0.000000]
200
60
Source Keys X Pos: #keys(0f, 50f, 100f)
OK
Target Keys X Pos: #keys(0f, 10f, 20f)
OK
#Bezier Float key(2 @ 50f)
#keys(0f, 10f, 20f)
#Bezier Float key(3 @ 50f)
Target Keys After assignKey: #keys(0f, 10f, 50f)
OK
NOTE:

appendKey and assignKey only work on controllers that directly support key frames. The source and target need to be of the same type. The controller level property<control>. supportsKeys (boolean, read-only) returns true if the controller implements the I_KEYCONTROL interface and thus can be used as argument of the appendKey and assignKey functions. See supportsKeys.

To copy a key between controllers:

  • Make sure that the source and target controllers are of the same type

  • Check to see if they support keys using the. supportsKeys property

    • If not, see if they have subanims

    • If they have, recurse down into the subanims

  • Repeat the check for the subanims and so on.

    

copyPasteKeys <controller> (<map_struct> | <fn> <arg>) [#replacekeys] [#insertkeys]

This function is pretty similar to the existing mapKeys() method, but implies that some keys have been selected. Upon calling copyPasteKeys(), selected keys will first get copied, then copied keys get selected and pasted, using either the map_struct or a mapping function as described in the mapKeys() method topic. Available in 3ds Max 8 and higher.

Using the #replacekeys argument deletes any unselected key within the copied keys' range. Additionally, using the #insertkeys argument shifts any unselected key that is located on or after the copied keys' insertion point to the right (the location of the first copied key) with a time value equal to the length of the copied keys' range.

See Also

Please send us your comment about this page

Creative Commons License Except where otherwise noted, this work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License. Please see the Autodesk Creative Commons FAQ for more information.