Script Controllers

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

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

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] "

Notes:

In versions prior 3ds Max 8, it was possible to provide a script string as a construction parameter, but it would not work as expected:

When assigning a script controller to a track, 3ds Max 7 automatically reads the current value of the track and assigns it to the new controller to make it valid and to preserve the original value. For example, if the track contains the value 12.6, after assigning the script controller, the string inside the controller will be automatically set to "12.6" to preserve the last known value.

For that reason, trying to assign the script in a single pass
does not work in 3ds Max 7.

For example:

$Box01.height.controller = float_script script:"random 0 100"

will not work because the script controller instance is first created on the right-hand side, the script string "random 0 100" is assigned to it, then the controller is assigned to the left-hand side, and its script string is immediately overwritten with a new string containing the current value of the left-hand side track.

You should always assign the controller first, then assign to its .script property.

example:

fs = float_script()

$Box01.height.controller = fs

fs.script = "random 0 100"

 

In 3ds Max 8 and higher, the behavior described above has been corrected. An internal flag has been added to all controllers to denote whether the controller is "new" or "not new", thus using the current track value only when a new controller is being assigned. Thanks to this new behavior, the script string in controllers where the script property has already been set will not be replaced.

 

<script_controller>.ThrowOnError Bool default:true

Controls whether to throw when an error occurs 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.

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:

<boolean>SetExpression <&TSTR>Expression

Expression is In parameter

Sets the expression string to the string passed by-reference. Returns true on success, false otherwise.

<TSTR by value>GetExpression()

Returns the expression string.

<TSTR by value>GetDescription()

 

<boolean>SetDescription <&TSTR>Description

Description is In parameter

 

<integer>NumVariables()

Returns the number of variables defined in the controller.

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

Name is In parameter

Constant is In parameter

Adds a constant. The first argument is the name of the constant. The second argument is the value to be assigned to the constant. Returns true on success, false on failure.

<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. The first argument is the name of the target. The second argument is the value to be assigned to the target. The optional Offset keyword can be used to define a time offset. Returns true on success, false on failure.

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

Name is In parameter

Adds an object. The first argument is the name of the object. The second argument is the value to be assigned to the object. Returns true on success, false on failure.

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

Name is In parameter

Adds a node variable. 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>SetConstant <value>Which <&fpvalue>Constant

Constant is In parameter

Sets a given constant to the specified value.

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

Owner default value: undefined

Sets a given taget to the specified target value. Returns true on success, false on failure.

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

Sets a given object to the specified object value. 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.

<boolean>DeleteVariable <value>Which

Deletes the specified variable. Returns true on success, false on failure.

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

Name is In parameter

Renames the specified variable to the given name. Returns true on success, false on failure.

<time>GetOffset <value>Which

Returns the time offset of the specified variable.

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

Sets the time offset of the specified variable to the given value.

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

<fpvalue by value>GetConstant <value>Which

Returns the value of the specified variable.

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

asObject default value: false

Returns the value stored in the specified target.

<maxObject>GetObject <value>Which

Returns the object value stored in the specified object variable.

<node>GetNode <value>Which

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

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

asObject default value: false

Returns the value stored in the specified variable.

<value>GetVarValue <value>Which

Returns the value stored in the specified variable.

<enum>GetType <value>Which

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

Returns the type of the value stored in the specified variable.

<TSTR by value>GetName <index>Index

Returns the name of the indexed variable.

<index>GetIndex <&TSTR>Name

Name is In parameter

Returns the index of the variable specified by name.

<void>Update()

Updates the controller.

<TSTR by value>PrintDetails()

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

See also

Using Script Controllers

 

Controller Common Properties, Operators, and Methods

MAXWrapper Common Properties, Operators, and Methods

Value Common Properties, Operators, and Methods