CHAPTER 17
Advanced Scripting

Featuring

•  Declaring Global and Local Variables

•  Preparing Startup Scripts

•  Using Scene Scripts, Callbacks, and Handlers

•  Working with MAX Files (including Xrefs)

•  Customizing Viewports

•  Accessing Global Functions and Properties

You have seen many ways to use MAXScript in MAX. You will now see some features and tools to improve scripting. We’ll examine scene management tools, Xrefs, callbacks, and more. All these commands are not connected to a specific object or function; they’re usually related to the scene or to MAX in general, so they are covered in this chapter.

Declaring Global and Local Variables

When you declare variables in a script, you need to define if they are local or global. If they are local, they will be deleted after the script ends. If they are global, they will remain in memory after the script ends.

In addition, when using multiple rollouts, if the variable is local, it is valid only inside the rollout in which it was defined. When you need to work with variables among rollouts, make sure you declare them as global.

For instance, start a new script and type:

p = undefined
for i in 1 to 3 do
(
local p = i*10
format “Internal: %\n” p
)
format “External: %\n” p

Notice the Internal values are correct, but the External value is undefined. This is because the variable p is local and is deleted right after the FOR command ends.

	TIP It is important to declare variables as local when they are local, so they do not conflict with other variables in other scripts.

Repeat the script, this time declaring p as global:

global p = i*10

Notice now that p will return a value after it ends.

	WARNING When declaring variables as global, make sure you use a unique name that will not be used in other scripts, to avoid possible conflicts. (The only names you cannot use are MAXScript commands. For instance, you cannot use “function” as a variable name.)

Preparing Startup Scripts

You can set up scripts to execute automatically. There are a few ways to do so. MAXScript searches for a file called startup.ms, and executes it automatically when MAX is loaded. You can also put the script in the Startup folder, under Scripts. When launched, MAXScript will search all files in all subfolders inside Startup.

Another way to call a script when MAX starts is using the command line, through the startup shortcut or using a DOS prompt. Simply type 3DSMAX –U MAXSCRIPT script.ms, where script.ms is the name of the script you want to call.

	TIP Put all your utilities in the Startup folder and they will be automatically listed in the MAXScript Utility tab.

Macro Scripts

Macro Scripts are scripts created either by using the Macro Recorder or by typing manually; their file extension is .mcr but they are actually the same file type as MAX scripts (.ms). We saw some information on Macro Scripts before, but let’s see more now.

There are several properties we can add to a Macro Script: the category where the Macro Script will be added; the buttontext that will appear when using a text button; the tooltip of the button; and the bitmap icon (which is explained below).

When you drag and drop, MAX automatically fills these properties for you, auto-numbering the Macro Script and defining it as the Drag&Drop category.

This is an example of a Macro Script:

macroscript example
 category:”Mastering 3D Studio MAX”
 buttontext:”Example”
 tooltip:”Macro Script Example”
 icon:#(“example”,1)
(
script commands...
)

Using Icons

You can use a bitmap icon to define your Macro Script button. It can be automatically defined using the icon property. To create these icons, use any painting program or the Custom Icon Maker script supplied with MAX as a bonus script. (Using the Custom Icon Maker script automates things like saving 24- and 32-pixel versions and color vs. alpha versions of the icon.)

This bitmap is nothing more than a BMP file with two different resolutions (for large and small icons) and a mask file. You can use more than one icon in the same BMP file, simply placing them side by side (see Figure 17.1).

FIGURE 17.1  Sample bitmap icons

When specifying the icon property, you need two parameters: the filename (without path or extension) and the icon number. Icons are numbered left to right, starting at 1. For instance, in the previous Macro Script, we used icon:#(“example”,1) where example would be the BMP file with the icon and we want to use the first icon in this file.

Loading Macro Scripts

There’s no need to load a Macro Script file. Just place it in the UI\Macroscripts folder, or evaluate it (MAX automatically copies it to the correct folder), and it will be loaded automatically when MAX starts.

If you remove an MCR file from the Macroscripts folder, MAX will not load its button in the UI, since it will not find the related script. The opposite does not happen; if you remove a button from the UI, the script file will not be removed.

Plug-in Scripts

Plug-in scripts can be placed in the Startup folder or in any Plugins folder. MAX-Script will search for them there and will load them automatically, like regular plug-ins. You will learn about plug-in scripts in detail in Chapter 18.

Using Scene Scripts

You can save scripts and variables inside a scene. You also can define scripts that will monitor the scene and perform actions in defined situations, such as prior to render, prior to save, when an object is deleted, when a selection changes, etc.

Persistent Variables and Functions

Persistent variables and functions are those that will be saved with the scene. You can create as many persistent functions or variables as you need; just make sure you use unique names so they do not conflict with other variables in other scripts.

You can create a set of functions and variables that will calculate how much time one person takes working on each scene in MAX. This script can be defined as a startup script and will manipulate information saved with the scene. Then, using handlers, you will be able to define when this script will be called and how the result will be output.

You will now start defining some variables as persistent. Open the Listener and type:

persistent global time_working
time_working = 0

This will create a variable that you will use in the script.

Manipulating Persistent Variables

You can list and remove persistent variables. To list all persistent variables (and their values), use the PERSISTENTS.SHOW() command.

To delete persistent variables you can use PERSISTENTS.REMOVE, listing the name of the variable, starting with #. For instance, to remove the persistent variable part_time you would use persistents.remove #part_time. To remove all persistent variables, simply use PERSISTENTS.REMOVEALL() and all persistent variables will be removed.

© 2000, Frol (selection, edition, publication)