MAXScript Tools | 3ds Max 9 Bible

MAXScript is pervasive and can be found in many different places. This section looks at the MAXScript tools and how different scripts are created and used.

Let's look at some of the tools used in working with MAXScript. Max has several tools that make creating and using scripts as simple as possible.

The MAXScript menu

The MAXScript menu includes commands that you can use to create a new script, open and run scripts, open the MAXScript Listener window (keyboard shortcut, F11), enable the Macro Recorder, open the Visual MAXScript Editor, or access the Debugger dialog box.

The New Script command opens a MAXScript Editor window, a simple text editor in which you write your MAXScript. See the "MAXScript Editor windows" section later in this chapter for more on this editor window. The Open Script command opens a file dialog box that you can use to locate a MAXScript file. When opened, the script file is opened in a MAXScript Editor window, as shown in Figure 49.1. MAXScript files have an .MS or .MCR extension. The Run Script command also opens a file dialog box where you can select a script to be executed.

image from book
Figure 49.1: MAXScript is written using standard syntax in a simple text editor window.

Note

When you use Run Script, some scripts do something right away, whereas others install themselves as new tools.

The MAXScript Listener command opens the MAXScript Listener window. You can also open this window by pressing the F11 keyboard shortcut. The Macro Recorder command starts recording a MAXScript macro. The MAXScript Listener and recording macros are covered later in this chapter.

The MAXScript Utility rollout

You access the MAXScript Utility rollout, shown in Figure 49.2, by opening the Utilities panel in the Command Panel and clicking the MAXScript button. This opens a rollout where you can do many of the same commands as the MAXScript menu.

image from book
Figure 49.2: The MAXScript rollout on the Utilities panel is a great place to start working with MAXScript.

The MAXScript rollout also includes a Utilities drop-down list, which holds any installed scripted utilities. Each scripted utility acts as a new feature for you to use. The parameters for these utilities are displayed in a new rollout that appears below the MAXScript rollout.

Tutorial: Using the SphereArray script

Here's a chance for you to play around a little and get some experience with MAXScript in the process. In the Chap 49 directory of the DVD is a simple script called SphereArray.ms. It's similar to the Array command found in the Tools menu, except that SphereArray creates copies of an object and randomly positions them in a spherical pattern.

To load and use the SphereArray script, follow these steps:

Select Create Standard Primitives Box, and drag in the Top viewport to create a Box object that has a Length of 10 and Width and Height values of 1.0.
Select the box object, open the Utilities panel in the Command Panel (the icon is a hammer), and click the MAXScript button.

The MAXScript rollout appears.
Click the Run Script button in the MAXScript rollout to open the Choose Editor file dialog box, locate the SphereArray.ms file from the Chap 49 directory on the DVD, and click Open.

The SphereArray utility installs and appears in the Utilities drop-down list. (Because SphereArray is a scripted utility, running it only installs it.)
Choose SphereArray from the Utilities drop-down list. Make sure that the box object is selected.
In the Sphere Array rollout, enter 50 in the Object Count field and 2.0 for the Radius field. Now click the Go! button to run the script.

The script adds 50 copies of your box to the scene and randomly positions them two units away from the box's position.

Figure 49.3 shows the results of the SphereArray MAXScript utility. Notice that the SphereArray script looks much like any other function or tool in Max.

image from book
Figure 49.3: The results of the SphereArray MAXScript utility

The MAXScript Listener window

Figure 49.4 shows the MAXScript Listener window (keyboard shortcut, F11), which lets you work interactively with the part of Max that interprets MAXScript commands. The top pane of the Listener window (the pink area) lets you enter MAXScript commands; the results are reported in the bottom pane (the white area) of the Listener window. You can also type MAXScript commands in the bottom pane, but typing them in the top pane keeps the commands separated from the results. If you drag the spacer between the two panes, you can resize both panes as needed.

image from book
Figure 49.4: The MAXScript Listener window interprets your commands.

When you type commands into either pane and press Enter, the MAXScript interpreter evaluates the command and responds with the results. For example, if you type a simple mathematical expression such as 2+2 and press Enter, then the result of 4 is displayed in blue on the next line. Most results appear in blue, but the results display in red for any errors that occur. For example, if you enter the command hello there, then a Type error result appears in red because the MAXScript interpreter doesn't understand the command.

Caution

The MAXScript interpreter is very fickle. A misspelling generates an error, but MAXScript is case-insensitive, which means that uppercase and lowercase letters are the same as far as Max is concerned. Thus, you can type sphere, Sphere, or SPHERE, and Max sees no difference.

The Listener window has these menus:

File: You can use this menu to close the window (Ctrl+W), save your work (Ctrl+S), run scripts (Ctrl+R), open a script for editing (Ctrl+O), or create a new script from scratch (Ctrl+N).
Edit: This menu is where you access all the common editing functions you need, such as cutting, pasting, and undoing.
Search: You use this menu for searching through the window to find specific text (Ctrl+F), find the next instance (Ctrl+G), or replace text (Ctrl+H).
MacroRecorder: This menu lets you set various options for the MAXScript Macro Recorder.
Debugger: This menu provides a way to open the Debugger dialog box.
Help: This menu provides access to the MAXScript Reference (F1).

Tutorial: Talking to the MAXScript interpreter

This tutorial gives you a little experience in working with the MAXScript Listener window and a chance to try some basic MAXScript commands.

To start using MAXScript, follow these steps:

Choose File Reset to reset Max.
Choose MAXScript MAXScript Listener (or press F11) to open the MAXScript Listener window.
Click anywhere in the bottom pane of the Listener window, type the following, and press Enter: sphere()

A sphere object with default parameters is created.
Next enter the following in the lower pane, and press the Enter key:
```
 torus radius1:50 radius2:5 
```
Max creates a torus and adds it to your scene. As you specified in your MAXScript, the outer radius (radius1) is 50, and the radius of the torus itself (radius2) is 5. The output tells you that Max created a new torus at the origin of the coordinate system and gave that torus a name: Torus01.
Now use MAXScript to move the torus. In the Listener window, type the following:
```
 $Torus01.position.x = 20 
```
After you press Enter, you see the torus move along the positive X-axis. Each object in Max has certain properties or attributes that describe it, and what you've done is access one of these properties programmatically instead of by using the rollout or the mouse. In this case, you're telling Max, "Torus01 has a position property. Set the X-coordinate of that position to 20."

Note
The $ symbol identifies a named object. You can use it to refer to any named object
To see a list of some of the properties specific to a torus, type the following:
```
 Showproperties $Torus01 
```
A list of the Torus01 properties appears in the window.

Figure 49.5 shows the MAXScript Listener window with all the associated commands and results.

image from book
Figure 49.5: Use the MAXScript Listener window to query Max about an object's properties.

An important thing to understand from this tutorial is that you can do almost anything with MAXScript. Any property of any object that you can access via a rollout is also available via MAXScript. You could go so far as to create entire scenes using just MAXScript, although the real power comes from using MAXScript to do things for you automatically.

Tip

Max remembers the value or the last MAXScript command that it executed, and you can access that value through a special variable: ? (question mark). For example, if you type 5 + 5 in the Listener window, Max displays the result, 10. You can then use that result in your next MAXScript command by using the question mark variable. For example, you could type $Torus01 .radius2 = ?, and Max would internally substitute the question mark with the number 10.

At the left end of the status bar, you can access the MAXScript Mini Listener control by dragging the left edge of the status bar to the right. By right-clicking in this control, you can open a Listener window and view all the current commands recorded by the Listener. Figure 49.6 shows this control with another command along with the objects from the last example.

image from book
Figure 49.6: The resulting objects created via the MAXScript Listener window

MAXScript Editor windows

The MAXScript Editor window enables you to open and edit any type of text file, although its most common use is for editing MAXScript files. Although you can have only one Listener window open, you can open as many editor windows as you want.

To open a new MAXScript Editor window, you can choose MAXScript New Script, choose File New from the MAXScript Listener window, or click the New Script button in the MAXScript rollout in the Utility panel. You can also use MAXScript Editor windows to edit existing scripts.

For creating a new script, opening both an Editor window and the Listener window is usually best. Then you can try out things in the Listener window, and when the pieces of the MAXScript work, you can cut and paste them into the main Editor window. Then you can return to the Listener window, work on the next new thing, and continue creating, cutting, and pasting until the script is done.

Tip

You can also send text back to the Listener window for Max to evaluate. Just select some text with the cursor or mouse, and press Shift+Enter (or just Enter on the numeric keypad). Max copies the selected text to the Listener window and evaluates it for you.

The File, Search, Debugger, and Help menus in the MAXScript Editor window are the same as those used for the Listener window, with the exception of the Evaluate All command. This command (choose File Evaluate All to access it) is a fast way of having Max evaluate your entire script. The result is the same as if you had manually selected the entire text, copied it to the Listener window, and pressed Enter.

The Edit menu includes commands to Undo (Ctrl+Z), Cut (Ctrl+X), Copy (Ctrl+C), Paste (Ctrl+V), or Delete (Delete) text. It also includes access to the Visual MAXScript window with the New Rollout and Edit Rollout (F2) menu commands. The pop-up menu also includes a command to Select All (Ctrl+A). You can also access this menu as a pop-up menu by right-clicking in the window.

The Macro Recorder

The MAXScript Macro Recorder is a tool that records your actions and creates a MAXScript that can be recalled to duplicate those actions. Using the Macro Recorder is not only a quick and easy way to write entire scripts, but it is also a great way to make a working version of a script that you can then refine. After the Macro Recorder has created a MAXScript from your recorded actions, you can edit the script using a MAXScript Editor window to make any changes you want.

You can turn the Macro Recorder on and off either by choosing MAXScript Macro Recorder or by choosing Macro Recorder image from book Enable in the MAXScript Listener window. The check mark next to Macro Recorder command on the MAXScript menu indicates that the Macro Recorder is turned on.

When the Macro Recorder is on, every action is converted to MAXScript and sent to the MAXScript Listener window's top pane. You can then take the MAXScript output and save it to a file or copy it to a MAXScript Editor window for additional editing. The Macro Recorder continues to monitor your actions until you turn it off, which is done in the same way as turning it on.

The Macro Recorder menu in the MAXScript Listener window includes several options for customizing the macro recorder, including

Enable: This option turns the Macro Recorder on or off.
Explicit scene object names: With this option, the Macro Recorder writes the MAXScript using the names of the objects you modify so that the script always modifies those exact same objects, regardless of what object you have selected when you run the script again. For example, if the Macro Recorder watches you move a pyramid named $Pyramid01 in your scene, then the resulting MAXScript will always and only operate on the scene object named $Pyramid01.
Selection-relative scene object names: With this option, the Macro Recorder writes MAXScript that operates on whatever object is currently selected. So if (when you recorded your script) you moved the pyramid named $Pyramid01, you could later select a different object and run your script, and the new object would move instead.

Note
To decide which of these options to use, ask yourself, "Do I want the script to always manipu-late this particular object, or do I want the script to manipulate whatever I have selected?"
Absolute transform assignments: This tells the Macro Recorder that any transformations you make are not relative to an object's current position or orientation. For example, if you move a sphere from (0,0,0) to (10,0,0), the Macro Recorder writes MAXScript that says, "Move the object to (10,0,0)."
Relative transforms operations: Use this option to have the Macro Recorder apply transformations relative to an object's current state. For example, if you move a sphere from (0,0,0) to (10,0,0), the Macro Recorder says, "Move the object +10 units in the X-direction from its current location."
Explicit subobject sets: If you choose this option and then record a script that manipulates a set of subobjects, running the script again always manipulates those same subobjects, even if you have other subobjects selected when you run the script again.
Selection-relative subobject sets: This tells the Macro Recorder that you want the script to operate on whatever subobjects are selected when you run the script.
Show command panel switchings: This option tells the Macro Recorder whether or not to write MAXScript for actions that take place on the Command Panel.
Show tool selections: If this option is selected, the Macro Recorder records MAXScript to change to different tools.
Show menu item selections: This option tells the Macro Recorder whether or not you want it to generate MAXScript for menu items you select while recording your script.

Tutorial: Recording a simple script

In this tutorial, we create a simple script that squashes whatever object you have selected and turns it purple.

To create a script using the Macro Recorder, follow these steps:

Open the Purple pyramid.max file from the Chap 49 directory on the DVD. This file includes a simple pyramid object.
With the pyramid object selected, choose MAXScript MAXScript Listener (or press F11) to open the MAXScript Listener window.
In the Listener window, open the MacroRecorder menu and make sure that all the options are set to the relative and not the absolute object settings, thereby telling the script to work on any selected object instead of always modifying the same object.
Returning to the MacroRecorder menu, select Enable. The Macro Recorder is now on and ready to start writing MAXScript. Minimize the Macro Recorder window (or at least move it out of the way so you can see the other viewports).
Dock the MAXScript Listener window to the Left viewport by right-clicking the viewport name and choosing Views Extended MAXScript Listener.

Now you can keep things out of the way while you work.
With the object selected, choose Modifiers Parametric Deformers XForm to add an XForm modifier to the object.
Select the non-uniform scale tool and restrict it to the Y-axis. Right-click anywhere in the Front viewport to make it active (if it's not already), and then drag the Y-axis gizmo downward to squash the pyramid.
In the Modify panel, click the color swatch next to the object name field to open the Object Color dialog box. Pick one of the purple colors, and click OK.
The script is done, so in the MAXScript Listener window, choose MacroRecorder Enable to turn off the Macro Recorder.
Now it's time to try out your first MAXScript effort. Add a sphere to your scene. Make sure that it's selected before moving to the next step.
In the top pane of the MAXScript Listener window, select all the text (an easy way to do so is by pressing Ctrl+A), and then hold down the Shift key and press the Enter key to tell Max to execute the MAXScript.

In Figure 49.7, you can see the script and the sphere that has been squashed and has changed color.

image from book
Figure 49.7: Running the new squash-and-turn-purple script

The MAXScript Debugger

The MAXScript Debugger, shown in Figure 49.8, is a separate window that allows you to stop the execution of a script using breaks and look at the variable's values as the script is being run. This information provides valuable information that can help to identify bugs with your script.

image from book
Figure 49.8: The MAXScript Debugger lets you check the values of variables as the script runs.

The MAXScript Debugger dialog box is opened using the Debugger menu command in the various MAXScript tool windows or using the MAXScript image from book Debugger Dialog menu command on the main interface. The Command field at the top of the Debugger window lets you input commands directly to the debugger. The Output area displays the results. Several buttons at the bottom of the Debugger window let you control how the debugger works:

Break: Causes the current script to break out of its execution
Run: Starts the execution of the current script
Evaluate: Executes the command entered into the Command field
Watch: Opens the Watch Manager window where you can specify distinct variables to watch
Config: Opens the MAXScript Debugger Parameters dialog box where you can configure the debugger
Stop: Halts the execution of the current script
Clear: Clears all the text in the Output field

Watching variables

The Watch button opens the Watch Manager, shown in Figure 49.9. Clicking the Variable column lets you type in a new variable to watch. The Value column displays the value of the listed variables as the script is executed.

image from book
Figure 49.9: The Watch Manager lets you watch the value of specific variables.

Using debugger commands

Once the execution of a script has been halted by clicking on the Break button, you can enter specific commands in the Command field at the top of the debugger and click the Evaluate button to execute them. Table 49.1 lists the available debugger commands.

Table 49.1: MAXScript Debugger Commands
Open table as spreadsheet
Command	What It Does
threads	Displays a list of all current threads.
setThread (thread no.)	Makes the specified thread number the active thread.
stack	Dumps the stack for the active thread.
setFrame (frame no.)	Makes the specified frame number the active frame.
locals (variable)	Dumps the value for the specified variable for the active thread and frame. If no variable is listed, then all variable values are dumped.
getVar (variable)	Gets the value of the specified variable.
setVar (variable)	Sets the value of the specified variable.
eval (expression)	Evaluates the specified expression.
?	Displays a list of debugger commands.

Configuring the debugger

The Config button opens the MAXScript Debugger Parameters dialog box, shown in Figure 49.10. This dialog box includes several options for deciding when to break out of the script execution. It also lets you define the time for each break.

image from book
Figure 49.10: The MAXScript Debugger Parameters let you set the break cycle time, among other settings.