TUTORIAL: Link Object to Vert

Linking objects to Vertices
by Jay Price

This tutorial goes through the process of creating a simple script that does two things. First it teaches you how to use MAXScript and do some basic stuff. It also allows you to create a useful script than can be used to link objects to a vertex. Basically it is like the Linked XForm modifier, instead of linking a vertex to and object, you can link an object to a vertex. The object will move (based on its pivot point) to where ever that vertex is currently at.

This tutorial covers the following topics in MAXScript:

Controller Access and Assignment
Scriptable Controllers
Conditional Statements
Floaters
Rollouts
Groups
Different Types of Buttons
Labels

This tutorial uses the following files:

PreScript.max - This is a simple scene with some animation. You don't need to use this...it is just so you can follow along exactly with my tutorial and compare your results
LinktoVert.ms - This is the completed version of the script you are going to write.
LinktoVert-Helper.ms - This is the same script but with some modifications so you can understand the different parts of the script. You aren't writing this one but if you run into problems you should run it. Hit the define buttons to see what the different parts of the script does what.
Download all three files here: linko2v.zip

The very first thing you need to know about scripts is they are NOT hard to write. Scripting is very useful and can greatly reduce the amount of time needed to create a complex scene. You don't have to be a programmer. You don't have to be a math wizard. All you need to do is spend a little time looking through the on-line help and at examples.

Now, open up the PreScript.max file and hit play. It shows a simple box moving around and a teapot that is just sitting there. When we are finished with the script you will be able to pick a vertex on the box for the teapot to be linked to. Now to access MAXScript open up the utility panel and click MAXScript. If you don't see it, hit More.

Here is a brief run down on the MAXScript Rollout.

"Open Listener" opens up the MAXScript listener, basically it is the command prompt of MAX. You can type in stuff like "The_Cube = box length:10 width:10 height:10" and it will make a box at (0,0,0) with those sizes.

"New Script" just opens up a Notepad.exe like thing for writing scripts. Useful hotkeys are "Ctrl + S" to save and "Ctrl + E" to evaluate the script.

"Open Script" opens up a script for editing.

"Run Script" this just runs the script without opening up the editor. When you run a script it either opens up a floater or adds it to the "Utilities" depending on how you wrote the script.

The "Utilities" selection lists the scripts that you have run or are in your MAXScript start-up folder. To open that utility's rollout, click on the arrow and the list opens up. Highlight the script you want and release the mouse button. It should open up a Rollout below.

Lets think ahead of what we will need to write in our script. We will need to select the vertex, and the object that will be linked to the vertex. Once we select the objects we should link them. No problem, that is only three buttons. Now to actually move the teapot to the vertex we will use a Scriptable Controller. A Scriptable Controller is just like a float controller or a bezier controller but the main difference is you can have access to all of MAXScript’s functionality. It is MUCH more powerful than the expression controller. To keep this script pretty simple it will just get a vertex numberthat the user will select ahead of time and allow the user to pick a child object. To select the vertex the user can apply a meshselect modifier or similar and select the vertex.

Click on New Script and lets begin to write. (There is a list of all the functions I used at the bottom of the tutorial)

First thing we need to write is:

MainFloater = NewRolloutFloater "Link To Vertex" 300 315

This creates the floater in which our buttons will be placed. In other words it is the User Interface to our script. "NewRolloutFloater" is a built in function that creates the floater. It takes three parameters: name, width, height. The name of the floater is "Link To Vertex" (make sure it is in quotes) The size of the floater will be 300 315 or width by height (in pixels), this will give us plenty of room. In order to access this floater we need to assign it to a variable, that way we can access it where ever in the script. We assign it by with "MainFloater ="

Now that we created the Floater we need to add a rollout to it.

Rollout Vert_Linker "Vertex Linker" (

) -- Close Rollout

Rollout is a constructor that creates a panel where you will put all the buttons, labels, and other stuff. It takes 2 parameters, the first is the name of it, which will be Vert_Linker. The other "Vertex Linker" is the title or string that will show up on the Rollout when you run the script. Now everything inside the "( )" will be stuff that is in the rollout, like buttons and what happens when you push those buttons. Since we are doing this whole script on one rollout the " ) --Close Rollout " will be one of the last things in the script. The " -- Close Rollout " is a comment. If you put "--" MAXScript sees that this is a comment and skips over anything left on that line. You use them to put info into your script which won't be executed when the script is run. I always put a comment after a " ) " that way I can keep track of what I was suppose to be in the "( )".

Now is a good time to see your progress. Hit Ctrl + E. This evaluates your script so far. You should see this pop up.

All you see is your floater. But you defined a rollout too, but it isn't there. That is because one useful feature of the floater is you can add new rollouts to it when needed. Add the following line to the VERY END of your script. It should even be past ") -- Close Rollout":

addRollout Vert_Linker MainFloater

addRollout takes two parameters. The first is the name of the Rollout you have already defined and the second is the Floater you want the rollout to appear on. Now hit Ctrl + E again and see the change.

Now that you have the rollout defined it is time to put some stuff in it. I like to keep my Rollout's neat and semi-organized, that way people besides yourself will feel more comfortable with your script. One way to keep it clean is with the "group". Group is a Rollout Control, it controls the rollout's layout. The first thing we want in our floater is a way to select the vertex we want to be the parent so we will title this group "Pick Vert". Type the following in inside the Vert_Linker Rollout parenthesis.

group "Pick Vert" (

) -- Close Group

Group takes one parameter which is the title of the group. Everything you want in the group should be inside the " ( ) "

Lets add some labels before we make the button in this group. Type:

Label getvert1L "Select a vertex to be parent" Label getvert2L "then hit 'Get Selected Vert' "

Label takes two parameters, the first is the name of the label and the second is the text that will be displayed.

Now lets add a button. Type:

Button GetVert_Button "Get Selected Vert"

Button makes just a normal button you push. It takes two parameters. The name of the button and the text that is on the button.

Since we would like to know what vertex we selected we will add the following line in.

Label vertnumL "Vertex Number: (none selected)"

This is another label. You can change labels when hitting buttons and stuff. Which is what will happen with this one.

Lets to a quick catch up. You now should have the following:

MainFloater = NewRolloutFloater "Link To Vertex" 300 315

Rollout Vert_Linker "Vertex Linker" (

group "Pick Vert" (

Label getvert1L "Select a vertex to be parent"
Label getvert2L "then hit 'Get Selected Vert' "
Button GetVert_Button "Get Selected Vert"
Label vertnumL "Vertex Number: (none selected)"

) -- Close Group

) -- Close Rollout

addRollout Vert_Linker MainFloater

I like to organize my script by using tabs. Now hit Ctrl + E and you should have a floater like this:

Lets add the next part, the selection of the child object (or the object you are linking to the vertex). Type the following after the " ) -- Close Group" since this is a new group:

group "Pick Child" (

Label childL "Select Child Object"

PickButton GetChild_PB "Get Child"

Label childnameL "Child Object: (none)"

) -- close group

This makes the second Group. This is basically the same as the last group except that you are using a different type of button. The PickButton has the same parameters as the Button but when you push it, it puts you into a selection mode. Where you have to pick an object in the scene. As you may have noticed I like to make my names descriptive of what they are. You can pick whatever names you want. But it is much easier to use descriptive names. If you want hit Ctrl + E to see what you just added.

Now it is time to add the link button and respective group.

group "Link ME Plz!" ( Button LinkME_Button "Link ME!" enabled:off ) --close group

Since this is pretty straight forward I didn't include any labels. However there is something different with this button. After the second parameter I included enabled:off. Buttons have the property of being enabled or disabled. Enabled is just the property to turn on or turn off the button. The default is on, but I changed it to off. I want you to do pick the object and vertex before you link anything. That way you don't have problems. The off is a built in value, like true, false, on, and undefined.

Time for another Recap. You should now have the following script.

MainFloater = NewRolloutFloater "Link To Vertex" 300 315

Rollout Vert_Linker "Vertex Linker" (

group "Pick Vert" (

Label getvert1L "Select a vertex to be parent"
Label getvert2L "then hit 'Get Selected Vert' "
Button GetVert_Button "Get Selected Vert"
Label vertnumL "Vertex Number: (none selected)"

) -- Close Group

group "Pick Child" (

Label childL "Select Child Object"
PickButton GetChild_PB "Get Child"
Label childnameL "Child Object: (none)"

) -- Close group

group "Link ME Plz!" (

Button LinkME_Button "Link ME!" enabled:off

) -- CLose group

) -- Close Rollout

addRollout Vert_Linker MainFloater

You are now finished the User interface part of the script. The only thing that remains is to define what happens when you push the buttons. Hit Ctrl + E to see the script so far. Go ahead and push some of the buttons. Nothing will happen.

Now it is time to add some actions to those buttons. First lets do the getvert_button. Type

on GetVert_Button pressed do (

parentOBJ = $
vertnum = (getvertselection parentOBJ)[1]
vertnumL.text = "Vertex Number: " + (vertnum as string)
VertPicked = true
if ChildPicked == true do LinkME_Button.enabled = on

) -- Close on GetVert

Alright, a lot to explain here. The buttons work this way, you hit a button and the script looks through the defined "on statements" for what to do when that button is pushed. This piece of script does this, "on Button_Name pressed do (........)" is the generic form of the action. The only thing different with ours is we substituted GetVert_Button in for Button_Name. It is easy to remember the syntax too. It is a shorten version of "When the button _____ is pressed do the following" All buttons, spinners, checkboxs, etc have syntax similar to this, however each one is slightly different. The next line is "parentOBJ = $". The "$" is the character for "the currently selected object". Since you are getting the selected object's vertex the script needs to know what object it is. The "parentOBJ" is just a variable that I am assigning that object to. So in the scene I provided, the parentOBJ will be the box. Now the next line is a little tricky. "vertnum = (getvertselection parentOBJ)[1]" This assigns the vertex that is currently selected with the meshselect or editmesh modifiers to the variable "vertnum". The "getvertselection parentOBJ" this is the actual function that gets the vertex number.

getvertselection takes one parameter (a mesh), in this case it is our parent object or the box. The getvertselection function gives an array (fancy name for a list) back of all the selected vertices. Since we are only going to select one vertex the array will only have one number in it. This is where the "[1]" comes in. An array in MAXScript looks like this #(1,3,69,13). To access the individual numbers in this array we use the following syntax. Myarray[1] This will output 1, the first number in the array. Or Myarray[2] will output 3 or the second number in the array. Since the getvertselection gives us the vertex in an array we have to extract that vertex number from the array. By extracting the integer we can deal with a number (or integer) instead of a list of numbers. This is why the [1] is at the end of it. It outputs the first and only number in the array (our vertex) as an integer and saves it as the variable vertnum.

The next line changes the label below the Get Vert button. In order to change the what the text of the label says we change the value of "vertnumL.text" If you remember, vertnumL was our label we made that said "Vertex Number: (none selected)" Well we want to change this to "Vertex Number: (our vertex number)" So this is how we do it. vertnumL.text = "Vertex Number: " + (vertnum as string). The vertnumL.text stores the string (what is says) well we want to keep the "Vertex Number: " part. But we want to add the number of our vertex. So we add it to the string by using the "+" sign. The only problem is the variable vertnum (our vertex number) is stored as a interger but the value of vertnumL.text has to be a string. This is why the "as string" is there. It converts the integer to a string so it can be appended onto "Vertex Number: " Back to the block of script we wrote. The next two lines...
VertPicked = true
if ChildPicked == true do LinkME_Button.enabled = on are needed to activate our LinkME_Button we made. We had made the LinkME_Button inactive when we created it.

if is a conditional statement. If this then that. The "==" doesn't assign anything, it is used to test. We are testing to see if the Child has already been picked. If it has then the LinkME_Button will become enabled. If it hasn't then it remains locked.

The button should now work when you use it. Remember, you HAVE to select a vertex before you push the get vert button. Because the Button gets what ever is currently selected. If a vertex is not selected and you push the button the script will crash and burn. Onto the next button.

To get the "Get Child" button to work, type the following,

on GetChild_PB picked obj do (

Child_Obj = obj
childnameL.text = "Child Object: " + Child_Obj.name
ChildPicked = true
if VertPicked == true do LinkME_button.enabled = on

) --close on getchild

The first thing you should notice is that the syntax is different for the button. This is a different type of button, the pickbutton, so different syntax is needed. The general form follows, on PickButtonName picked ObjectName do ( ..... ) ObjectName is the object that you picked. Since the obj is a temporary name we will assign it to a variable, Child_Obj. The next line "childnameL.text = "Child Object: " + Child_Obj.name" changes the label below the button to the name of the Child_Obj we picked. The name of an object is stored under Child_Obj.name which is a string so we don't need to convert anything. The rest of the new script is the same as the previous button. Just with the ChildPicked and VertPicked swapped with each other.

Now for the final button. Type:

on LinkME_button pressed do (

Child_Obj.position.controller = position_script()
Child_Obj.position.controller.script = "getvert parentOBJ vertnum"

) --close on LinkMe

This has the same button syntax as the first one we did and it only has two additional lines of script. The first line changes the child_obj's position controller. Animatable objects have controllers and we want the controller to use MAXScript. So we assign the position_script controller to the child_Obj by typing "Child_Obj.position.controller = position_script()" Other info you can get out of an object is. Object.name - its name like teapot01

Object.pos - its current position (0,0,0)

Object.controller - its main controller ie) look at, PRS, Link

Object.rotation.controller - the rotation controller

Look though the help file. You will get tons of info from it.

The last line of text assigns the "mini-script" to the child_obj's position script controller. The function getvert takes two parameters. The first is the object with the vertex. The second is the vertex number. The function returns the position of that vertex. This position is what the scriptable controller uses.

SO....this is what you should have now.

MainFloater = NewRolloutFloater "Link To Vertex" 300 315

Rollout Vert_Linker "Vertex Linker" (

group "Pick Vert" (

Label getvert1L "Select a vertex to be parent"
Label getvert2L "then hit 'Get Selected Vert'"
Button GetVert_Button "Get Selected Vert"
Label vertnumL "Vertex Number: (none selected)"

) -- close group

group "Pick Child" (

Label childL "Select Child Object"
PickButton GetChild_PB "Get Child"
Label childnameL "Child Object: (none)"

) -- close group

group "Link ME Plz!" (

Button LinkME_Button "Link ME!" enabled:off

) --close group

-----------------------------------------------------------------------------
on GetVert_Button pressed do (

parentOBJ = $
vertnum = (getvertselection parentOBJ)[1]
vertnumL.text = "Vertex Number: " + (vertnum as string)
VertPicked = true
if ChildPicked == true do LinkME_Button.enabled = on

) -- close on getvert
-----------------------------------------------------------------------------
on GetChild_PB picked obj do (

Child_Obj = obj
childnameL.text = "Child Object: " + Child_Obj.name
ChildPicked = true
if VertPicked == true do LinkME_button.enabled = on

) --close on getchild
-----------------------------------------------------------------------------
on LinkME_button pressed do (

Child_Obj.position.controller = position_script()
Child_Obj.position.controller.script = "getvert parentOBJ vertnum"

) --close on linkme

) -- Close Rollout

addRollout Vert_Linker MainFloater -- Add Rollout to the main floater

Save it and hit Ctrl + E and try it out. You finished Script should look like LinktoVert.ms. If you are having troubles make sure you have one vertex selected when you hit "get vert" button.

I also included LinktoVert-Helper.ms (shift+click to save). This is the same script just with extra stuff added to show you what groups do what.

Download the script from here: LinktoVert.ms (shift+click to save).

==========================================================================
Used Functions list:
These are all built in functions that I used.

NewRolloutFloater "Name of Floater" width height | Creates a floater
Rollout Name_of_Rollout "Title of Rollout" ( ........... ) | Creates a rollout
addRollout Name_of_Rollout Name_of_floater | adds a rollout to a floater
group Group_Name "title of group" | makes a group with that title
label Label_Name "text" | Puts text onto the rollout
if This do That | tests something and if it works do that
getvertselection object | gets the vertex number of the currently selected object/vertex as an array
getvert object vertex_number | returns the position of that vertex number of that object (x,y,z)