Transform Script Controller

The software 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 must yield a matrix3 value.

Since 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 with respect to a specific animation time by the software. 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, current Time. You can also reference scene property values at other times by using "at time" expressions in your scripts, as in regular MAXScript programming.

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.

After assigning a Transform Script controller, a Properties dialog is available by right-clicking the track in the Track View hierarchy and choosing Properties.

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 tying its name into the Name field and click Delete.

Rename—Renames the highlighted variable.

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:

Assign Constant—Opens a dialog which lets you assign a constant to the highlighted variable.

Value expression—Enter any MAXScript value (such as an integer, a float, an array, etc.) or expression.

Value expression result—Displays the results of the expression above.

Evaluate—Analyzes your 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 controller to the highlighted variable. The controller's value is taken at the current time plus the variable's Tick Offset.

Assign Controller—Lets you assign a track to the highlighted variable.

Assign Node—Lets you assign a node to the highlighted variable.

Expression text field—Enter the script expression here to calculate the controller value.

Description text field—Enter comments regarding the functionality of the controller.

Load/Save—Load and save scripts to text files.

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).