Script Controller

The Script controllers work similarly to Expression controllers. They provide a Script Controller dialog where you can enter a script for computing the controller value.

Assign Controller > ... Script

The following Script controllers are available in 3ds Max:

Float Script: float controller
Point3 Script: Point3 controller
Transform Script: matrix3 PRS controller
Position Script: position Point3 controller
Rotation Script: rotation Quaternion controller
Scale Script: scale Point3 controller

The differences among the various types of Script controllers are mainly in the type of animation track you can assign them to. For example, you assign a Transform Script controller to a Transform Track, a Position Script controller to a Position track, and, if the Position controller is Position XYZ, you can assign a Float Script controller to any or all of the individual Position tracks (Position X/Y/Z).

The primary advantages of Script controllers are:

They can use all the features of the MAXScript language, including loops, scripted functions, and path names.
Almost any property of any object in a scene can be used to help compute controller values, including mesh vertices, values of properties at arbitrary frame times, and other non-animatable properties that are not accessible in Expression controllers.
They can use MAXScript global variables to communicate and coordinate with other controllers and scripts in 3ds Max.

Refer to the MAXScript Help for a complete explanation of this scripting language.

Transform Script Controller

A Transform Script controller contains all of the information contained in a Position/Rotation/Scale (PRS) controller in one scripted matrix value. Instead of having three separate tracks for position, rotation, and scale, you can access all three values simultaneously from a single script controller dialog. Because a script defines the transform values, they are easier to animate.

The value of the controller script must be a matrix3 value. A matrix3 value is a 4x3 3D transformation matrix. For more information, see the Matrix3 Values topic in the MAXScript Help.

Writing Controller Scripts

3ds Max interprets the text you type into the Script text box as the body of a MAXScript block expression. You can type as many expressions as you want on as many lines as you want, and they are evaluated in turn. The value of the last expression is taken as the controller value. This value must yield the right type for the controller: float for Float, point3 for Position, quat for Rotation, matrix3 for Transform, and so on.

Because the text is inside a block expression, you can declare local variables that are visible only within the script and are temporary for one evaluation. You can also declare or access global variables that are shared with all other scripts in MAXScript and hold their values from one evaluation to the next.

A controller is always evaluated by 3ds Max with respect to a specific animation time. This might be the current time slider or incrementing frame time if an animation is playing, or a rendering is under way. In the case of Script controllers, the time being evaluated is used to establish an automatic "at time" context around the controller script, so any properties you access (outside of other explicit “at time” expressions) yield the correct values for the current controller evaluation time. This means you don't have to do anything special in your scripts to work at the correct time. You can access the evaluation time with the standard MAXScript variable, currentTime. You can also reference scene property values at other times by using "at time" expressions in your scripts, as in regular MAXScript programming.

Assign Nodes and Tracks to Variables

When you need to refer to nodes in your scene or to animation tracks, it is recommended that you use the Script controller variable toolset to create variables to assign to any particular node or controller track. This way, if you decide to later on rename your scene objects, the script controllers using these objects are preserved because the variables maintain the link to the nodes.

Otherwise, if you assign, for example, a node to a variable manually in the dialog's Expression window, that link becomes broken as soon as you rename that particular node.

Note: It is especially important to assign nodes and tracks to variables with the corresponding buttons when using XRef scenes and objects.

Procedures

Example: To keep an object centered relative to other objects in the scene during an animation:

Name the object that should remain centered foo and assign a Script controller to its Position track.
Enter foo in the Name field and click Create.
The new variable is automatically added to the Variables list.
With the variable highlighted, click Assign Node.
The Track View Pick dialog opens, listing the contents of your scene.
Expand the Objects hierarchy until you locate foo. Highlight it and click OK.
The foo node is assigned to your variable.
Enter the following script in the Script Controller dialog's Expression window:
local pos=[0,0,0]

for o in objects where o != foo do

pos += o.pos

pos / (objects.count - 1)

This script computes the average position of all objects, except the current one (written as foo here) by setting up a local, iterating over all objects except foo, accumulating a total position vector, and computing the average in the last line, which is the final result of the script.

To use a Transform Script controller:

Select an object.
Right-click to open the quad menu.
In the Transform quadrant, click Curve Editor.
Select the Transform track of the selected object in Track View.
Select Transform Script from the Assign Transform Controller dialog and click OK.
The Script Controller dialog opens.
Edit the matrix3 value in the Script Controller dialog, and click Evaluate when you are finished.

Interface

Assigning a Script controller automatically opens a Script Controller dialog where you can enter a script. You can open the dialog subsequently by right-clicking the track on the Motion panel or in the Track View hierarchy and choosing Properties, or clicking the Properties button on the Track View toolbar.

Tip: You can resize the dialog by dragging an edge or a corner.

Create Variable group

Name: Lets you enter and edit the name of user variables.
Create: Creates a variable and adds it to the Variables list.
Delete: Removes the highlighted variable from the Variables list. You can also delete a variable by typing its name into the Name field and then clicking Delete.
Rename: Renames the highlighted variable.

Variable Parameters group

Tick Offset: Specifies a time offset in ticks for the current variable. When the script is evaluated, the variable's value is set from the current time plus the Tick Offset value.
Note: The Time Offset has no effect on variables that are assigned a constant.

Variables list

Lists all available variables in the controller. The following pre-defined constant variables are available in every script Controller and cannot be deleted or renamed:

F the current time in frames
NT the normalized time
S the current time in seconds
T the current time in ticks

Assign Constant

Opens a dialog that lets you assign a constant to the highlighted variable.

Value expression Enter any MAXScript value or expression (such as an integer, a float, an array, and so on).
Value expression result Displays the results of the expression above.
Evaluate Analyzes the expression at the current time.
OK Assigns the value expression result to the current variable.
Cancel Disregards the current value expression result and closes the dialog.

Assign Track

Lets you assign a track to the highlighted variable.

Assign Controller

Lets you assign a controller to the highlighted variable. The controller's value is taken at the current time plus the variable's Tick Offset.

Assign Node

Lets you assign a node to the highlighted variable.

Expression window

Displays the expression to evaluate. You can edit the text in this window.

Description window

In this text window, you can enter comments about how the controller works, how to use it, and so on.

Save

Click to save the script to a MAXScript (.ms) text file.

Load

Click to load a script from a MAXScript (.ms) text file.

Debug

Opens the Script Controller Debug Window, which displays the value of all variables used in your script.

Evaluate

Evaluates the script expression. The evaluation is computed for the current position of the time slider.

Close

Compiles and checks the controller script for errors. If no errors are found, the dialog is closed. Any problems result in a query box asking whether you want to revert the expression to the original value of the current track and close the dialog (OK), or to return to editing the expression (Cancel).