Controller Common Properties, Operators, and Methods

Value > MAXWrapper > Animation Controllers > Controller

Animation Controllers - Quick Navigation

Properties

All controllers have the following properties:

<controller>.keys MAXKeyArray -- read-only, the controller’s key array 
<controller>.value varies -- get or set the current controller value

The keys and value properties provide access to the value and keys in a free-standing controller. It is useful when working with the global tracks controllers that are accessible in MAXScript. The controllers that are not keyframeable return an empty KeyArray for their keys property.

The value property is sensitive to the current time and animate contexts, so you can use it to evaluate a controller at various times or to plant keyframes in the controllers that support keys.

You can only assign a value to a controller’s value property if the controller is a key-based controller. The only exception to this is that you can assign a Matrix3 value to a PRS controller’s value property. MAXScript automatically sets the individual position, rotation, and scale values to the values represented in the Matrix3 value.

If an Ease Curve is assigned to a controller, the following controller-related sub-property is available:

<controller>.Ease_Curve Float -- the controller’s ease curve value

If a MultiplierCurve is assigned to a controller, the following controller-related sub-property is available:

<controller>.Multiplier_Curve Float -- the controller’s multiplier curve value

See Ease and Multiplier Curve Functions for methods and notes related to Ease and Multiplier curves.

EXAMPLE:

globaltracks.float.mycontroller.value
globaltracks.float.mycontroller.keys[2]

Associated Properties

All animatable properties in 3ds Max objects let you reference several controller-related sub-properties. These are:

<property>.controller

The property’s controller.

<property>.track

A synonym for .controller.

<property>.isAnimated

A boolean indicating whether the property is animated.

<property>.keys

Read-only, gets the property’s controller’s key array

<property>.supportsKeys

Read-only, boolean, true if controller is key-framable

<property>.keyable

Boolean, true if controller is keyable, false if set to unkeyable

<property>.isHSV

Read-only, boolean, true if controller's value represent HSV colors

The track property is a simple synonym for controller . If an animatable property does not have an assigned controller, the isAnimated property returns false and the controller , track , and keys properties return undefined .

EXAMPLE:

$foo.pos.controller
bend_mod1.angle.isAnimated
$bar.taper.gizmo.scale.keys[2]

You can create controllers like other 3ds Max objects by calling the class' constructor function:

EXAMPLE:

c = bezier_position()

and assign them to animatable properties by assigning to the controller property in those animatables.

EXAMPLE:

$foo.pos.controller = c
$baz.bend.gizmo.rotation.controller = tcb_rotation()
$box01.length = linear_float()

Methods

getPointControllers {<editable_mesh_node> | <editable_spline_node>}

Returns an array of controllers assigned to the vertices in the mesh or spline. If no controller is assigned to a vertex, the array element value will be undefined. For editable splines, each knot consists of three vertices: the in vector, knot, and out vector. The array of controllers returned is a "snapshot" of the current controllers. If controllers are assigned or changed for a vertex, this change is not reflected in the array. If a vertex is added/deleted, the array is not resized to reflect the change in number of vertices.

getPointController <editable_mesh_node> <vertex_index_integer>

Returns the controller currently assigned to the vertex, undefined if no controller is assigned.

getPointController <editable_spline_node> <spline_index_integer> <vertex_index_integer>

Returns the controller for specified vertex in the specified spline, undefined if no controller is assigned. Each spline knot consists of three vertices: the in vector, knot, and out vector.

NOTE:

Applying a controller to a property causes the controller to take on the properties value at frame 0. If keys are present for the controller before the assignment to the property, all keys will be adjusted by the difference between the controller’s value at frame 0 and the property’s value. This is shown in the following example.

SCRIPT

a=bezier_float ()
addnewkey a 0
addnewkey a 10
a.keys[1].value=10
a.keys[2].value=100
b=box()
b.height
b.height.controller=a
b.height
at time 10 b.height

OUTPUT

Controller:Bezier_Float-- result line 1
#Bezier Float key(1 @ 0f)-- result line 2
#Bezier Float key(2 @ 10f)-- result line 3
10-- result line 4, key value at time 0
100-- result line 5, key value at time 10
$Box:Box006 @ [0.000000,0.000000,0.000000]-- result line 6
25.0-- result line 7, default property value
Controller:Bezier_Float-- result line 8
10.0-- result line 9, key value changed from 10 to 25 (delta= +15)
100.0-- result line 10, key value changed by delta = +15

An issue can occur when a single controller is assigned to multiple object properties. The value actually stored in a controller might not necessarily be the same value seen in Track View or in the command panels, nor the same value returned by accessing the property value in MAXScript. Part of a MAXWrapper property definition is scaling value that is applied when reading or setting the true value stored in a controller. For example, the slice_to and slice_from properties associated with many of the geometry primitives is displayed in degrees. The actual value stored in the controller associated with these properties are in radians. This scaling factor is an internal property of the MAXWrapper property, and not an internal property of the controller. Both 3ds Max and MAXScript automatically apply the specified scaling factor when accessing properties, so this scaling is normally invisible to the user. If the same controller is assigned to two properties that have different scaling factors, the question arises as to which scaling factor to apply to the output of the controller. If you are accessing the controller’s value through a MAXWrapper property, the scaling factor associated with that property is applied to the controller’s value. MAXScript also internally stores the last scaling factor applied to the controller’s value. If you are directly accessing the value property of the controller, or the value property of a key in the controller, the stored scaling factor is used. This can result in a controller’s value property returning different values at different times in a script, based on how the controller was last accessed. Because of this, it is highly recommended that you do not instance a controller onto multiple MAXWrapper properties that have different scaling factors. The scaling factor, if any, is listed for each MAXWrapper property in the documentation of the MAXWrapper classes.

displayControlDialog <controller> <string>

Displays the modal controller dialog, if any. The string will be in the dialog title bar. If the controller is a keyframe controller, the key info dialog is displayed for the selected keys. If no keys are selected, no dialog is displayed.