There are several types of scripts. These categories roughly divide script types by the type of UIs they generate.
• Scripted function—A scripted function contains one or more functions, but does not generate a UI. After you run the script, you can call the functions from the Listener or another script.
• Scripted utility—A script that defines one or more rollouts on the Utilities panel for its UI.
• Scripted plug-in—This is a specialized type of script that creates new 3ds Max tools, or extends existing tools. In all other types of scripts, you use code to perform actions that you can already perform with the 3ds Max UI, such as creating boxes and spheres, assigning controllers, and configuring viewports. With a scripted plug-in, you can create new geometric objects, maps, modifiers, and so on. The UI for a new tool appears in the appropriate part of the 3ds Max UI. For example, a new map is listed in the Map Browser, while a new modifier appears on the Modifier List.
• General scripts—Any other scripts fall into the category of general scripts. With such a script, you could generate a floating dialog as a UI, or have no UI at all. For example, you could write a script that creates a series of spheres, similar to the scripts you created in Chapter 1. This script would not generate a UI.
MacroScripts
With the addition of a few lines of code at the start of a general script, you can cause the script to appear as an action item in the Customize User Interface dialog. This means you can add the item to a toolbar or other UI element so you can then call the script from there. This also means you can call or execute the script from a keyboard shortcut.
Such a script is called a MacroScript. It can generate a UI and define functions, but it does not have to. It is simply a general script with a command that causes it to appear as an action item.
The name MacroScript came from its intended use, which was to help users unfamiliar with MAXScript create scripts from code displayed in the Listener. For a repetitive sequence of commands, you can perform the sequence once manually, which would display the corresponding Macro Recorder output in the top (pink) pane of the Listener. Then you could copy and paste the Macro Recorder output to the MAXScript Editor, run the script, and work with its corresponding action item in the Customize User Interface dialog.
To turn any general script into a MacroScript, you can do either of the following:
• Add the necessary code at the beginning to designate the script as a MacroScript, and then run the script.
• Highlight the contents of the script in the MAXScript Editor (or any other place where 3ds Max displays code, such as the Listener), and drag it to a toolbar. This automatically generates an internal name for the MacroScript, such as Macro1, Macro2, and so on.
Building User Interfaces ■
53 Script Files
In general, you save a script file name with the extension .ms. To keep your scripts organized, you should save MacroScripts with the extension .mcr. Technically, you could save either type of script with either extension, and the scripts will still run.
However, using the appropriate extension tells you (and others) how you intend the script to be used.
You can cause a script to run automatically when 3ds Max is started. To do this, you place the script in any of the following folders:
• 3dsmax/stdplugs/stdscripts
• 3dsmax/plugins, or any subfolder under plugins
• 3dsmax/ui/macroscripts, or any subfolder
• 3dsmax/scripts/startup
When you start 3ds Max, the startup routine searches these folders in the order shown, looking for files with the extensions .ms, .mcr, and .mse. (The extension .mse is used for encrypted script files. For more information, see “Encrypting Script Files”
in the MAXScript Reference.)
Rollouts
Rollouts are at the heart of any MAXScript-generated UI. Before you can create any user interface elements such as
checkboxes and spinners, you must create at least one rollout to hold them. The term rollout in MAXScript refers to the kind of rollout you are familiar with, such as those on command panels and dialogs. With MAXScript, you can also display a rollout as a single dialog, if you like.
Fortunately, it is very easy to create a custom rollout with MAXScript and populate it with user interface elements.
To create a rollout, you use the following construction:
rollout <variable> “Rollout Name”
(
<UI elements such as check boxes, buttons, and spinners>
)
The variable holds the rollout’s internal name, which you will use within the script to reference the rollout. The string “Rollout Name” is the name that will appear at the top of the rollout.
The code between the open and close parentheses is called the rollout clause. You define all user interface elements, and what each one does, within the rollout clause.
To get started, create a very simple rollout.
To create and display a rollout:
1. Open a new MAXScript Editor, and type the following:
rollout a "Something New"
(
spinner b "Enter a value: "
button c "Click Me"
)
This defines the rollout labeled “Something New.” The variable a contains the internal reference to the rollout, which you can use in other parts of the script to refer to the rollout.
The spinner and button commands create a spinner and button with the labels you included between the quotation marks. The variables b and c hold the internal reference to the spinner and button, respectively.
2. Run the script.
Nothing happens. You have to set the location and appearance of the rollout.
3. At the end of the script, type the following:
createDialog a 200 50
4. Run the script.
This displays the rollout as a dialog named Something New, with a width of 200 and height of 50. It contains two UI elements, a spinner and a button.
The command createDialog creates a new floating dialog using the rollout commands. Because the rollout’s internal name is a, the command createDialog a references the rollout definition you made earlier in the script.
If you change the spinner value and click the button, nothing happens. You must add event handlers to make something happen when you interact with the UI.
To add event handlers:
1. Close the Something New dialog.
In the MAXScript Editor, after the spinner line, enter the following:
on c pressed do (
d = b.value
sphere pos:[d,0,0]
)
Run the script. The dialog appears as it did before.
2. Change the spinner value, and click the button. Each time you click, you create a sphere at the X position indicated by the spinner value.
Let’s take a closer look at how this works. The line on c pressed do is an event handler for the button c. This tells the script to run the code between the parentheses when the button c is pressed.
The spinner is held in the variable b. The value in the spinner entry area can be accessed with the property .value. Thus, b.value is the value in the spinner entry area.
When the button c is pressed, the script puts the spinner value in the variable d, then creates a sphere with its X position equal to the spinner value.
To convert the script to a MacroScript:
To make this script accessible from a button on the toolbar, you can simply highlight the text and drag it there.
1. Close the SomethingNew dialog.
2. In the MAXScript Editor, select all the text with CTRL+A.
3. Drag from the selected text to a space between two buttons on the main toolbar. When the cursor changes to an array with a plus sign, release the mouse.
A new button appears on the toolbar. The buttons looks like a miniature MAXScript Editor or Listener.
4. Click the new button.
The Something New dialog appears, and you can create spheres with it as usual.
5. Close the Something New dialog.
6. Right-click the New button, and choose Edit Macro Script.
A new MAXScript editor window appears with a version of your script. A few lines have been added at the start to make the script into a MacroScript. This new version of your script has been saved in the file DragAndDrop-Macro#.mcr, where
# is an incremental number used to identify this particular script.
Note: The creation of this new script has not affected your original script, which still exists in its own MAXScript Editor window.
7. Close the MAXScript Editor containing the drag-and-drop script.
The script you have created here is a general script. You can quickly convert it to a utility by changing a few lines of code.
To convert to a scripted utility:
1. Close the Something New dialog.
Building User Interfaces ■
55
2. In the first line of code, change the word rollout to utility.
3. Delete the last line of code, the createDialog line that displays the floater as a dialog.
4. Run the script.
5. On the Utilities panel, choose MAXScript. From the Utilities drop-down menu on the MAXScript rollout, choose Something New.
The rollout Something New appears on the Utilities panel. You can use the spinner and button the same way you used them on the floating dialog.