Chapter 18
Plug-in Scripts

Featuring

•  Creating Tools

•  Creating Extended Plug-in Scripts

•  Building Geometry using Plug-in Scripts

Plug-in scripts are scripts that behave just like any plug-in: they’re seamlessly integrated into the UI. You can create several types of plug-in scripts; scripts that extend objects and parameters that already exist; and scripts that generate and manipulate information.

Creating Tools

Tools are scripts that are driven by mouse input, like click and drag. They’re essential for plug-in scripts, but can also be used in Macro Scripts and other scripts.

Tools are created using the TOOL command. They will require two main actions: ON MOUSEPOINT and ON MOUSEMOVE. These actions will define how the tool will behave when users click and when they drag the mouse.

Listing 18.1 is an example of a tool. It creates a regular box and converts it to a NURBS Object. Start a new script and type it, or open the tool_nurbsbox.ms file from the CD that accompanies this book.

tool NURBSBox
(
local st, ed1, ed2
on mousePoint clickNo do
 (
 if clickNo == 1 do
 (
 st = gridPoint
 in coordsys grid b = box length:0 width:0 height:0 pos:gridPoint
 b.name = uniquename “NBox”
 )
 if clickNo == 3 then
 (
 convertTo b NURBSSurface
 select b
 #stop
 )
 )
on MouseMove clickNo do
 (
 if (clickNo == 2) do
 (
 ed1 = gridPoint
 d1 = abs (ed1.x - st.x)
 d2 = abs (ed1.y - st.y)
 b.length = d2*2
 b.width = d1*2
 )
 if (clickNo == 3) do
 (
 ed2 = gridPoint
 d3 = distance ed2 ed1
 b.height = d3
 )
 )
)

On the MOUSEPOINT event, you define what the tool will do in two situations: when the mouse is first clicked (clickNo == 1) and when the third click happens (clickNo == 3).

In the first click, you create the object and assign its position. Notice the script uses in coordsys grid, so you will create the object in the current view/grid. Then, the position is assigned using GRIDPOINT. This command will return the position of the click in the active grid.

In the third click, you convert the object to NURBS, select it, and finish the tool, using #STOP. On the MOUSEMOVE event, you define what the tool will do when the mouse is dragged. In this example, you defined two situations: when the mouse is dragged after the click, with the mouse still pressed (clickNo == 2); and when the mouse is dragged after the user released the mouse button (clickNo == 3).

The first drag defines the box length and width. Both will be defined using the X and Y distance, also specified using gridPoint. The second drag defines the height of the box, using the distance between the last click and the actual mouse position.

Evaluate this tool, and execute it, typing starttool NURBSBox. Notice how it behaves the same way that objects are created in MAX.

You can also have this tool as a Macro Script and assign a button to it, which will make it behave like an object being created. You will need to use these tools with plug-in scripts, in order to create the objects properly.

Creating Plug-in Scripts

There are basically three types of plug-in scripts: extended plug-in scripts extend an existing plug-in and adjust its parameters; system plug-in scripts create nodes, but will not allow any editing of this creation, since they behave similarly to a system object; and creation plug-in scripts create new plug-ins and behave just like regular plug-ins.

You’ll learn some examples and applications of some of these plug-ins and their differences.

Creating Extended Plug-in Scripts

The extended plug-in scripts are the easiest to create. They allow you to extend an existing plug-in, adding more parameters or simplifying the existing ones. You’ll see that the extending plug-in scripts are very similar, regardless of their type. Looking at Table 18.1, you will see all the extending plug-in scripts listed; we’ll only demonstrate a few of the categories, so play with the others a little, creating your own customized materials, maps, etc.

For instance, let’s create a plug-in script that will extend the box object, and will create a simple cube instead of a regular box, as seen in Figure 18.1.

FIGURE 18.1  Cube plug-in script

Start a new script (this script, named plugin_cube0.ms, can be found on the CD) and type:

 plugin geometry cube
 name:”Cube”
 category:”Mastering 3D Studio MAX”
 classID:#(0x36b2b15a, 0x60b9a9bb)
 extends:Box
 (

The PLUGIN command defines the plug-in. It requires the plug-in type, which is geometry in this example, and a variable name (“cube”). You also need to specify the name and category of the plug-in, which will define where it will appear in the Create tab.

The plug-in script also requires a classID . The classID is a hexadecimal number that allows MAX to identify which plug-in is being used. This value is given using the GENCLASSID() command, which generates a new classID for you to use in your scripts.

	NOTE The classID must be unique to each plug-in and plug-in script.

The last parameter in the PLUGIN command is extends , which defines the object that is being extended. In your example, you’re extending the box object, so you used extends:Box.

Now you will continue writing the script, by defining the tool. The plug-in script automatically executes the tool named Create.

In our example, continue typing:

 tool create
 (
 on mousePoint clickNo do
 (
 if clickNo == 1 do nodeTM.translation = gridPoint
 if clickNo == 2 do #stop
 )
 on MouseMove clickNo do
 (
 if clickNo == 2 do
 delegate.width = sqrt(gridDist.x^2 + gridDist.y^2 + gridDist.z^2)
 delegate.height = delegate.length = delegate.width
 )
 )
 )

© 2000, Frol (selection, edition, publication)