MAXScript Language Reference > 3ds Max Objects > Animation Controllers > Controller Types > Script Controllers >

# Script Controllers

    float_script : floatController  point3_script : point3Controller position_script : positionController rotation_script : rotationController scale_script : scaleController

Value > MAXWrapper > Controllers > Script Controllers

| Animation Controllers - Quick Navigation

Constructor

    float_script ... point3_script ... position_script ... rotation_script ... scale_script ...

Script controllers have been significantly enhanced in 3ds Max 8. Please see Using Script Controllers for detailson the changes.

Properties

    <script_controller>.script String default: varies

Lets you programmatically get and set theexpressiontextof a script controller.

Please see Script Controller Assignment Behavior Changes in 3ds Max 8 for some history notes on the changes introduced to this property's behavior in 3ds Max 8.

EXAMPLE
    obj = Box ()--create a box
    obj.position.controller=position_script ()--assign position script
    obj.position.controller.script ="[F,0,0]"--set the expression
    --The box will move one unit per frame along X since
    --the internal controller variable F contains the current frame

    <script_controller>.ThrowOnError Bool default:true

Controls whether to throwwhen an erroroccurs in the expression.

Available in 3ds Max 8 and higher.

Note

There is a discontinuity between the MAXScript Debugger window, getting variable values via Function Publishing System and evaluating the script controller.

- When working with the Debugger dialog, variable values are shown based on the current slider time.

- When accessed via Function Publishing System, the variable values returned are based on the current MXS time.

- When evaluating the controller, the result is based on the current time value, but also the range of the controller, the Out-Of-Range Type set for the controller, and any Ease curves applied to the controller.

This means that while 'NT' might show one value in the Debugger dialog, its value in the evaluation may be different!

Interfaces:

All script controllers expose the IScriptCtrl Interface since 3ds Max 8.

This interface provides all methods to access the controller through MAXScript.

## Interface: IScriptCtrl

Methods:

## User-Defined Variables

A script controller supports four types of user-defined variables: Constant, Target, Object and Node. The main difference between these variables is the type of value or reference they contain, which in turn determines the type of notification messages that will cause an update of the script controller.

Note that in the Script Controller UI, the creation of the variable and the assignment of the value is performed in two separate steps (the Create button always creates a Constant Variable with a value of 0), while in MAXScript, the creation and assignment are performed in a single step.

### Constant Variable

A constant variable can contain a constant value.

The MAXScript Expression assigned to the variable will be evaluated andif thereturn valueis a constant, it will be used as the value of the variable. The constant variable creates no dependencies on other objects.

If the expression evaluates to a MAXWrapper (like a node, material, modifier, controller etc.), the result will be storedinan Object variable and will be updated dynamically. In other words, the .addConstant() method will be have like the .addObject() method and the resulting variable will not be a Constant variable but an Object variable.

If the result of the expression evaluation is a subAnim, it will be stored as a Targetvariable. In other words, in this case .addConstant() will behave like the .addTarget() method.

    <boolean>AddConstant <&TSTR>Name <&fpvalue>Constant

    Name is In parameter
    Constant is In parameter

Adds a constantvariable to the controller.Corresponds to the "Create" and"Assign Constant" buttonsin the Script Controller UI.

A constant variable returns the value of the MAXScriptexpression assigned to it.The expression itself can be any valid MAXScript expression which evaluates to a value.

The first argument is the name of the constantvariable.

The second argument is theexpressionto be assigned to thevariable.

Returns true on success, false on failure.

    <boolean>SetConstant <value>Which <&fpvalue>Constant

    Constant is In parameter

Sets the the constant variablevalue.

The first argument is either the name of the variable as string, or the index of the variable as integer.

The second argument is the MAXScript expression providing the value.

    <fpvalue by value>GetConstant <value>Which

Returns the value of the expression assigned tothe constant variable specified by name or index.

Throws a Runtime error if the variable name does not exist or the variable does exist but is not a constant variable.

EXAMPLE
    obj = Teapot ()
    $Teapot:Teapot01 @ [0.000000,0.000000,0.000000]
    obj.scale.controller=scale_script ()
    Controller:Scale_Script
    obj.scale.controller.addConstant "test" (pi*2)
    true
    obj.scale.controller.getValue"test"
    6.28319
    obj.scale.controller.getValue"test2"
    -- Runtime error: IScriptCtrl::GetVarValue - Bad Index or name: "test2"

### Target (Track) Variable

A target variable contains a reference to a subAnim Track.

The script controller will be updated when a notification about subAnim changes is sent. For example, if a target variable contains a reference to the Angle subAnim of a Bend Modifier applied to a Teapot, changing any subAnim of the Teapotor the Bend Modifierwill cause an update of the script controller, including changing the Bend Angle, Teapot Radiusetc.

Transformations ofthe Nodethe object containing the trackis attached to will NOT cause an update of the script controller unless the Node track itself or a transform trackis selected as the reference.

While it is allowed to assign the Node as the subAnim to be stored in the variable, this would be highly inefficient since any change to any of the subAnims of the referenced node will cause an update of the controller. Use the Node Variable to make a dependency on a Nodeinstead.

See Also Referencing Nodes and Controllers in Script Controllers FAQ for more details.

    <boolean>AddTarget <&TSTR>Name <value>Target Offset:<time> Owner:<value>

    Name is In parameter
    Offset default value: 0f
    Owner default value: undefined

Adds a target variable to the controller. Corresponds to the "Create" and "Assign Track" buttons in the Script Controller UI.

The first argument is the name of the target variable.

The second argument is the Trackvalue to be assigned to the target variable.

The optional Offset: keyword can be used to define a time offset.

The optional Owner: keyword argument can be used to define the owner of the Track.

Returns true on success, false on failure.

    <boolean>SetTarget <value>Which <value>Target Owner:<value>

    Owner default value: undefined

Sets a tagetv ariable specified by name or index in the first argumentto the target (subAnimtrack) value specified by the second argument.Corresponds to the "Assign Track" buttons in the Script Controller UI.

The optional Owner: keyword argument can be used to define the owner of the subAnim track.

Returns true on success, false on failure.

    <value>GetTarget <value>Which asObject:<boolean>

    asObject default value: false

Returns the reference target stored in the target variable specified by name or index in the first argument.

If the optional asObject: keyword argumentis supplied and is true, the return value will be converted from a subAnimto a MAXObject.

EXAMPLE
    obj1 = Teapot ()--Create a teapot
    $Teapot:Teapot01 @ [0.000000,0.000000,0.000000]
    obj2 = instance obj1--Create an instance
    $Teapot:Teapot02 @ [0.000000,0.000000,0.000000]
    obj2.pos = [-100,0,0]--Place the instance 100 units along -X
    [-100,0,0]
    obj3 = Box pos:[100,0,0]--Create abox 100 units long X
    $Box:Box01 @ [100.000000,0.000000,0.000000]
    ctrl = float_script()--Create aFloat Script Controller
    Controller:Float_Script
    obj3.height.controller = ctrl--Assign Controller to Height of Box
    Controller:Float_Script
    ctrl.addTarget "myTeapot" obj1[4]--Add Target Var. with Teapot Obj.
    true
    ctrl.setExpression "myTeapot.Radius"--Set Height to Teapot Radius
    true
    ctrl.getTarget "myTeapot"--Get the Target Track as SubAnim value
    SubAnim:Object__Teapot
    ctrl.getTarget "myTeapot" asObject:true--Get as Object
    Teapot
    ctrl.PrintDetails()--Print the controller details
    "** Script Control Details **
    * Description:
    (null)
    * Expression:
    myTeapot.Radius
    * Variables
    Members: 5
    01) T, Constant = 16000.0
    02) S, Constant = 3.33333
    03) F, Constant = 100.0
    04) NT, Constant = 1.0
    05) myTeapot, Track: $Teapot01.'Object (Teapot)', tick offset = 0
    "

### ObjectVariable

An object variable can hold a MAXWrapper value including Animation Controller, Base Object, Modifier, Material, Scene Node etc.

Most subAnim tracks in 3ds Max do not have a controller assigned by default. A controller is assigned automatically when a keyframe animation is first created or could be assigned manually via TrackView or MAXScript. Thus, the object variable can only hold a reference to an existing animation controller and cannot referenceparametersubAnim tracks without a controller. For creating a reference to a subAnim, use the Target Variable instead.

    <boolean>AddObject <&TSTR>Name <value>Object

    Name is In parameter

Adds an objectvariable to the scriptcontroller. Corresponds to the "Create" and "Assign Controller" buttonsin the Script Controller UI.

The first argument is the name of the objectvariable.

The second argument is the Controllerto be assigned to the objectvariable.

Returns true on success, false on failure.

    <boolean>SetObject <value>Which <value>Object

Setsthe object variable specified by name or index in the first argument to the controller object value specified by the second argument.

Returns true on success, false on failure.

    <maxObject>GetObject <value>Which

Returns the controller object referenced bythe object variable specified by name or index in the first argument.

### Node Variable

A node variable can hold a reference to a Scene Node only.

The script controller will be updated only when the node is changed, including changes to its Position, Rotation and Scale transformsand deletion of the node.Changes to the object attached to the node or its sub-anims will NOT cause an update of the script controller.

This variable type is very useful for accessing data from the object the script controller is assigned to without causing circular dependency problems. See Script Controller - Avoiding Circular Dependency for details.

    <boolean>AddNode <&TSTR>Name <node>Node

    Name is In parameter

Adds a node variable to the controller. Corresponds to the "Create" and "Add Node" buttonsin the Script Controller UI.

A node variable contains a reference to a scene node. Since the reference is name-independent, changing the name of the node stored in the variable does NOT affect the functioning of the script controller.

The first argument is the name of the node variable.

The second argument is the scene node to be assigned to the variable.

Returns true on success, false on failure.

    <boolean>SetNode <value>Which <node>Node

Sets a given node variable to the specified scene node value. Returns true on success, false on failure.

    <node>GetNode <value>Which

Returns the scene node value stored in the specified node variable.

### Delete Variable

    <boolean>DeleteVariable <value>Which

Deletes the used-defined variable specified by name or index.

Variables with index 1 to 4 are read-only and cannot be deleted - a Runtime error will be thrown if such an attempt is made. See .NumVariables() method documentation below for details.Thus, the argument must be either an index greater than 4 or a name of an existing user-defined variable.

Returns true on success, false on failure.

## General Variable Access

### VariableInspector Methods

    <integer>NumVariables ()

Returns the number of variables defined in the controller.

A default controller with no user-defined variables already provides 4 pre-defined variables for time access:

1 - T, Current Time In Ticks, Constant

2 - S, Current Time In Seconds, Constant

3 - F, Current Time in Frames, Constant

4 - NT, Current Normalized Time, Constant

User-defined variables generally have an index higher than 4.

    <boolean>VariableExists <&TSTR>Name

    Name is In parameter

Returns true if the given variable name exists in the controller, false if it does not exist.

    <enum>GetType <value>Which

    GetType enums: {#unknown|#target|#constant|#object|#node}

Returns the type of the variable specified by name or index.

### Variable Name and Index

    <TSTR by value>GetName <index>Index

Returns the name of the indexed variable.

    <boolean>RenameVariable <value>Which <&TSTR>Name

    Name is In parameter

Renames the variable specified by name or index in the first argument to the name specified by the second argument.

Returns true on success, false on failure.

    <index>GetIndex <&TSTR>Name

    Name is In parameter

Returns the index of the variable specified by name.

### Variable Value Access

    <value>GetValue <value>Which asObject:<boolean>

    asObject default value: false

Returns the value stored in the specified variable.

If the optional asObject argument is supplied as true, the return value will be converted to an object reference is applicable.

    <value>GetVarValue <value>Which

Returns the value stored in the specified variable.

EXAMPLE
    obj = Teapot()--Create a teapot
    $Teapot:Teapot01 @ [0.000000,0.000000,0.000000]
    obj.scale.controller = scale_script ()--Add a Scale Script Controller
    Controller:Scale_Script
    obj.scale.controller.numVariables ()--Default Variables Count
    4
    obj.scale.controller.addConstant "test" (pi*2)--Add a Variable
    true
    obj.scale.controller.variableExists "test"--See if it exists
    true
    obj.scale.controller.variableExists "someValue" --This one does not
    false
    obj.scale.controller.GetType "test" --Check Variable Type
    #constant
    obj.scale.controller.numVariables ()--Check Variable Count
    5
    obj.scale.controller.getIndex "test" --Get the variable's index
    5
    obj.scale.controller.getName 5--Get the 5th variable's name
    "test"
    sliderTime = 1f--Set the current scene time to frame 1
    1f
    obj.scale.controller.getValue 1--Time in Ticks
    160.0
    obj.scale.controller.getValue"T"--Time in Ticksaccessed by Name
    160.0
    obj.scale.controller.getValue 2--Time in Seconds
    0.0333333
    obj.scale.controller.getValue"S"--Time in Secondsaccessed by Name
    0.0333333
    obj.scale.controller.getValue 3--Time in Frames
    1.0
    obj.scale.controller.getValue"F"--Time in Framesaccessed by Name
    1.0
    obj.scale.controller.getValue 4--Normalized Time in Range 0-100
    0.01
    obj.scale.controller.getValue"NT"--Normalized Timeby Name
    0.01
    obj.scale.controller.getValue 5--User Constant Variable
    6.28319
    obj.scale.controller.getValue"test"--User Constant by Name
    6.28319
    obj.scale.controller.getValue"sunPos"--User Constant by Name
    -- Runtime error: IScriptCtrl::GetVarValue - Bad Index or name: "sunPos"
    obj.scale.controller.renameVariable"test" "someValue"--Rename...
    true
    obj.scale.controller.getValue"someValue"--User Constant by New Name
    6.28319

### Variable Time Offset

The Time Offset can be applied to any variable and defines the time context in which the variable will be evaluated. The default offset is 0. In other words, the value of a variable can be the same or different than the time at which the controller is being evaluated.

    <boolean>SetOffset <value>Which <time>Offset

Sets the time offset of the variablespecified by name or indexto the giventimevalue.

    <time>GetOffset <value>Which

Returns the offset time value of the specified variable.

## Expression

The Expression is the MAXScript Expression evaluated by the script controller to determine its final value.

    <boolean>SetExpression <&TSTR>Expression

    Expression is In parameter

Sets the expression stringof the script controllerto the string passed by-reference.

Returns true on success, false otherwise.

    <TSTR by value>GetExpression ()

Returns thescript controller'sexpression string.

    <void>Update()

Updates the controller by reevaluating its expression.

## Descriptionand Details

The Descrition is a user-defined string value describing the features and functionality of the script to be read by other users of the 3ds Max scene containing the controller.

    <TSTR by value>GetDescription ()

Returns the description string.

    <boolean>SetDescription <&TSTR>Description

    Description is In parameter

Sets the description string.

    <TSTR by value>PrintDetails ()

Prints information about the script controller, including description string, expression code and variable details.

Related Examples

How do I keep a Plane aligned to 3 Point Helpers?

How do I change the text in a Text Shape dynamically?

#### See Also

- Using Script Controllers

- Referencing Nodes and Controllers in Script Controllers FAQ

- Script Controller - Avoiding Circular Dependency

- Controller Common Properties, Operators, and Methods

- MAXWrapper Common Properties, Operators, and Methods

- Value Common Properties, Operators, and Methods