float_script : floatController
point3_script : point3Controller
position_script : positionController
rotation_script : rotationController
scale_script : scaleController
Constructor
Properties
<script_controller>.script String default: varies
lets you programmatically get and set the text for scripts. For example,
$foo.position.controller=position_script()
$foo.position.controller.script = "$baz.pos - [20,20,35]"
See also
Controller Common Properties, Operators, and Methods
MAXWrapper Common Properties, Operators, and Methods
Value Common Properties, Operators, and Methods
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.
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 some parameter, a properties dialog becomes available in Track View through the right-mouse-button menu or the Properties button on the Track View toolbar. This dialog contains two text boxes and several buttons:
Script text box: You type the script to compute the controller value here. See the section below on writing controller scripts for details.
Result text box: This box shows the results of an evaluation or any error messages caused by errors in your script.
Evaluate button: Cause an evaluation of the controller script to be made and prints the result in the Result box. The evaluation is computed for the current position of the 3ds max time slider.
Load/Save buttons: Load and save scripts to text files.
Close button: Compiles and checks the controller script and if all is OK, close the properties dialog. Any problems result in a dialog asking whether you really want to close the box with an incorrect script. If you do, the controller yields a null value (0, [0,0,0], etc.) when evaluated by 3ds max.
Writing Controller Scripts
3ds max interprets the text you type into the Script text box as the body of a MAXScript block expression, so you can type as many expressions as you want on as many lines as you want and they are evaluated in turn and 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, etc.
The value returned from a script controller may 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 a 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. The exception is when script or expression controllers are used. For these controllers, the data value returned must be the unscaled value, as 3ds max will then apply the scaling factor to the output value. In the documentation of the MAXWrapper classes, any scaling applied to a property is shown. If there is no scaling listed, no scaling occurs for that property. For example, a portion of the Capsule documentation is:
<Capsule>.radius Float default: 0.0 -- animatable
<Capsule>.height Float default: 0.0 -- animatable
<Capsule>.slice_from Float default: 0.0 -- animatable, angle
<Capsule>.slice_to Float default: 0.0 -- animatable, angle
From this, a scripted controller would return unscaled values for the radius and height properties, and radians for slice_from and slice_to. The scaling types, stored value meaning, and scaling value applied to the true controller value are as follows:
Angle -- value stored in radians, output scaled by 57.29578
Percentage -- value stored as fraction (0 to 1), output scaled by 100
For properties that have a Color value type, the controller output is automatically scaled by 255. If a point3_script is assigned to one of these properties, each component value should stored as fraction (0 to 1). Remember that converting a MAXScript Color value to a Point3 value does not apply a scaling factor û red as point3 returns a value of [255,0,0]. Therefore you must explicitly scale a Color value by dividing by 255 if it is output by the script controller.
The body of a script controller's script is any valid MAXScript expression that evaluates to the proper data type, and can contain global and local variables, functions, and structure definitions. The script is compiled in its own local scope, and the locals are only visible inside the scope of the script controller. Script controller local variables are heap-based locals, which are slightly different from normal (stack-based) locals. Normal locals are visible in the current scope and have a lifetime of one execution of that scope. Heap-based locals are also visible only in the current scope, but have a lifetime equal to the lifetime of the top-level expression where they are defined. A script controller's locals are created the first time the script is executed and are kept permanently in the heap (unless and until you redefine the script). This means you can store values in local variables during one execution of the script controller and these values will still be present at the next evaluation. You cannot access the script controller's locals from another utility or from Listener, because they are not executing within the scope of the script controller. See Scope of Variables for more information.
As a special case, you can exit a script controller's script using a return <expr>.
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 render 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 if you need to with the standard MAXScript variable, currentTime. You can also reference scene property values at other times by using explicit 'at time' expressions in your scripts, as in normal MAXScript programming.
Remember that MAXScript lets you write multiline string literals, if you need.
Example:
--A position script keeping the object at the center of all other objects
--in the scene as they move about:
local pos = [0,0,0]
for o in objects where o != $foo do
pos += o.pos
pos / (objects.count - 1)
The above script computes the average position of all objects except the current one (written as $foo here) by setting up a local variable that iterates through all objects except $foo, accumulates a total position vector, and computes the average in the last line, which is the final result of the script.
Example:
--A position script keeping the object attached to the highest vertex in a
--given object:
local high_index = 1, high_z = (getVert $foo 1).z
for i in 2 to $foo.numVerts do
if (getVert $foo i).z > high_z then
(
high_index = i
high_z = (getVert $foo i).z
)
getVert $foo high_index
The above script runs over the vertices in $foo remembering the index of the vertex with the largest z and returns that vertex's coordinates as the new position.
Limitations
Script controllers are not automatically updated when you interactively modify objects that they depend on.
If you move the time slider or if you animate the changes and then play the animation, the changes are reflected automatically. Because the scripts can refer to other objects in very indirect ways or conditional ways, it is not possible for MAXScript to automatically determine the objects a script depends on.