Defining Custom Functions

MAXScript’s built-in functions are very powerful. They provide access to objects, allowing you to read and set their properties. However, scripting in 3ds Max normally entails going beyond simple object creation. Fortunately, MAXScript allows you to make your own functions, giving you the ability to streamline and customize your work.

In MAXScript, you can use functions to perform almost any of the software’s operations. Start with a simple function definition that subtracts two variables:

MAXScript returns subtract() to let you know that it has defined the function, subtract.

The definition contains the keyword function (you can also use the word fn in place of function), followed by the name of the function (subtract), followed by the list of variables (x and y). The equal sign signifies the start of the body of the function. The body is the series of statements that the function executes. Even if there is only one statement, the body of the function must be in parentheses.

NOTE:

Any variables created in the body of a function are local variables unless otherwise specified.

Once a function has been defined, it can be used anywhere throughout the script. Therefore, it is useful to place function definitions at the beginning of your scripts.

In order to use a function, you simply enter the function name and the values for its variables:

This example uses what are known as positional arguments. When you call the function, you must supply both arguments, and you must supply them in the proper order for the function to execute properly.

The second type of arguments you can use are keyword arguments. This is what is used for all of the object constructors in MAXScript. The function definition is the same, with the exception of declaring the keyword arguments, or default values for the variables in a function.

The following example determines whether a number is positive, negative, or equal to zero.

EXAMPLE

function sign val:0 =
(
if val == 0
then messagebox ("Equal to 0")
else if val > 0
then messagebox ("Greater than 0")
else messagebox ("Less than 0")
)

The messagebox command causes a message box to pop up on the screen, displaying the argument in the parentheses that follow the command.

In this example, a parameter called val has been declared in the function definition. The value after the colon is the parameter’s default value. When the function definition contains parameters like this, they are optional in the function call. If you enter sign(), without specifying any parameters in the function call, MAXScript uses the default value:

The "Equal to 0" message box appears, since the default value for val (0) will be used. However, if you do define val:

sign val:-5

the "Less than 0" message appears. You can include as many keyword arguments in a function as you need, and they can be entered in any order when calling the function. This is useful when you consider functions such as object-creation functions, where the new object might have 20 or 30 parameters associated with it. If you wanted to use positional argument functions to create the same objects, you would have to provide all of these parameters, in the right order, each time you wanted to call the function.

It is also possible to use both positional and keyword arguments in the same function call. In this case, you must use positional arguments first, followed by the keyword arguments,

FOR EXAMPLE

function mycube side position:[0, 0, 0] =
(
box length:side width:side height:side pos:position
)

This function requires you to enter the size of the cube, but the position is optional.

Next Topic

Structure Definitions