Using Script Controllers

Animation Controllers - Quick Navigation

Script controllers function in similar way to expression controllers, providing a properties dialog in which a script can be entered that is used to compute the controller value. The primary advantages of script controllers are:

• They can use all the features of the MAXScript language including loops, scripted functions, pathnames, etc.

• Almost any property of any object in the scene can be used to help compute controller values, including things like mesh vertices, values of properties at arbitrary frame times, and other non-animatable properties that are not accessible in Expression controllers.

  NOTE:Mesh values, long strings and large bitArrays are not recommended for use in variables inside a script controller because they would use system memory and not MAXScript Heap memory and could cause Out Of Memory situations without ever getting garbage collected.

• They can use MAXScript global variables to communicate and coordinate with other controllers and scripts in 3ds Max.

When you assign a Script controller to a parameter, a Properties dialog becomes available in Track View through the right-mouse-button menu or the Properties button on the Track View toolbar.

The script controller dialog looks a lot like the expression controllers' dialog. Both expression and script controllers now use the same code base and provide very similar features. The main difference is the language used to write the expressions.

The new script controller dialog provides the following controls:

Create Variable group of controls:

• Name text field-lets you enter and edit the name of user variables.

• Create button - used to create a variable. Enter the variable name in the Name field and press the button to add to the list of variables.

• Delete button - used to delete a variable. Select an existing variable from the Variables list to get its name into the Name field OR type the name of the variable manually into the Name field, then press the Delete button.

• Rename button - used to rename an existing variable. Select an existing variable from the Variables list to get its name into the Name field. Type the new name of the variable into the Name field, then press the Rename button.

Variable Parameters group of controls:

• Tick Offset value spinner - this value spinner can be used to specify a time offset in ticks for the current variable. Select a variable from the list and change the Tick Offset value - if the variable is assigned a Track, Controller or Node, (in other words it is not a Constant),when the script expression is evaluated, the variable's value will be taken from the current time plus the Tick Offset.

Variables:

• Variables list - lists all available variables in the controller. You can create any number of user variables as described above. 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. This variable contains the normalized time where t is the evaluation time and the time range is the range on scripted controller. The normalized time is clamped to 0-1 unless the controller's Out-of-Range Type is disabled.

  • S - the current time in seconds.

  • T - the current time in ticks.

• Assign Constant - lets you assign a constant value to the selected variable. The constant value can be ANY MAXScript value, including integer, float, array, node etc. You can enter any valid MAXScript expression in the Value expression field. Then press the Evaluate button to evaluate the expression at the current time. Press OK to assign the value expression result to the variable, or Cancel to not assign a value. In the following screenshot, the constant value is an array containing the integer 1, the global constant value Pi and the position of the scene node Sphere01. The evaluated expression result contains only constant values - the integer 1 does not change, the float value of Pi is taken as the second array element, and the position of the Sphere01 at the current frame (at the moment of the evaluation) is taken as the third array element:

• Assign Track - lets you assign a subAnim track to the selected variable. For MAXScript methods related to this variable type, see Target (Track) Variables.

• Assign Controller - lets you assign a controller to the selected variable. The value of the controller will be taken at the current time plus the variable's Tick Offset. For MAXScript methods related to this variable type, see Object(Controller) Variables

• Assign Node - lets you assign a node reference to the selected variable. See Also Weak References To Nodes in the Expression/Script Controller

Expression text field - used to enter the script expression to calculate the controller value. See the section below on writing controller scripts for details.

Description text field - can be used to provide comments regarding the functionality of the controller.

Load/Save buttons - Load and save scripts to text files.

Evaluate button - Evaluates the script expression. The current time is used unless explicitly stated differently in the code using the at time context or when using controller variables with Tick Offset different than 0.

Close button - Compiles and checks the controller script for errors. If no errors are found, it closes the dialog. If an error is detected, a MAXScript error message is shown first with the description of the problem. After closing the error message, a prompt appears asking whether 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):

 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.