Maxscript by a practical example

PixelStudio 2007-01-15 00:00 tutorial  > 3ds MAX  > scripting

Learn how to create script using maxscript

Maxscript by a practical example

Hello people, in this tutorial I'll be showing you on how to create a nice script using maxscript. Before beginning to program it's always a good idea to plan what you want to create.

Just a quick note, the final script is far from finished and contains a couple of bugs. But well the fun is solving them your selfs and I apologize for my bad English and most important this is NOT a beginner's tutorial some programming experience is required!!!!!!!

The idea for this tutorial is as follow:
As I'm working as a 3D designer to create architectural visualization, I usually get the material colors from the architect. Most of the architect uses standard color schemes like the RAL colors (more info at )

So we generally looked up the RAL color and RGB value on the Internet and create a material for it. This takes time, and it would be better if we had a material library that has all the colors in it, so we could just pick and use the correct material.

Well one way to create such a library is by hand, but when you have to create a couple of hundreds you could imagine it takes a while hehe
A faster way would be to create a library by coding a script that does it for us.

So before we begin we need all the RAL-colors and their corresponding RGB values. I found a table on the Internet that listed the RAL colors and their RGB values, and copied it to a text file (found in the attachment)

An example of the text file:
1000 Green beige 204 204 153
1001 Beige 210 170 90
1002 Sand yellow 208 168 24
1003 Signal yellow 255 204 0
You see here the RAL number, its name and the RGB values.

In scheme we would be doing this:


Now we got an idea on what we want to create we start up 3dsmax and begin on the fun part.

Step 1 creating an interface

An interface for a maxscript can be create using code and by using the build in tool 'Visual maxscript editor'. The visual maxscript tool is accessed through the menu bar item MAXScript in 3dsmax.

The interface of the editor is fairly simple.

The tools / objects can be added through the toolbar on the bottom. Just be dragging them to the main area (the grey rectangle)

So back to our example we would like a couple of buttons and thingies to read/select the input file, set material settings and set the output path.

Now for you guys recreate the interface as I have done.

If you cannot get it exactly like mine, don't worry you can edit those control further on. Just get the basic layout. It'll help you further on.

The layout is created by dragging controls to the main form and editing the properties (right panel)
The Caption property is the most you will edit, for example if you drag a group onto the form you can set the text in the caption property

Next you have to save this (file > save as).
This can be in 2 different formats:
1) .VMS file
2) .MS file

The vms file can be loaded back into the visual maxscript editor, while the .ms can be loaded in the maxscript editor. We want to save both and then use the .ms file to go on.

Part 2 creating the maxscript

In part 1 we create the interface and saved it as a .vms and a .ms file. Well in this part we create the code behind the interface, in very basic words 'if you click a button something must happen'

So maxscript is created by using the maxscript editor that is build in 3dsmax, you can find this also under the menubar > maxscript > new maxscript.

The maxscript editor looks like notepad, and well you need no more. At this point it also useful to load the maxscript reference (under help in 3dsmax) In this reference you can find very much info in creating scripts.

Now click on File > open and load the saved interface .ms file. You can see here you cannot load a vms file this explains the two formats

Well you now see a bunch of code, this code resembles your interface you created in part1. if you did it correct you have something like this code below:

Don’t worry if your code does not look the same as mine, we are gonna edit this code.
First of all let’s start to break it up and keep it structured
First we rename the rollout to a better name, and give it a title. This rollout resembles the grey area in the visual maxscript editor.

Now we have to get this code to be a bit more structured, so we can see what is where. And work in a structured way.

Also I have changed some properties, this requires some explaining: If we for example see a 'label object' this is composed by several arguments:

First the definition of the object in this case 'label'
Next is the name of the object: InputfileName. It is important to name those objects that you use in your script!After this there are a couple of properties for example “file name” is the caption, pos:[24,40] is the position etc etc. You can edit is as you like it to be.

So at this point it is handy to see what you code looks like when you run it, as you may expect you want to press run and you see the result. Well unfortunately this is not the case. You have to program a bit more. And program max to create a dialog. The code for this is: CreateDialog RAL this is going at the very end of you script.

If you have added this you can run the script by going to 'file > Evaluate all' or press the shortcut ctrl-e For those guys whole are lost already here is the total script so far:

Important notice : If you are gonna follow this tutorial until the end, you have to name the objects like I did. Otherwise it won’t work. So the best is just to copy/past the code above.

If you run this (by pressing ctrl-e) you see the form you have created. Try pressing some buttons… Nothing happens. Well this is cause we have not programmed the buttons. So close you form and go back to the maxscript editor. First of all we have to set some variables :


These go at the beginning of the script. You’ll see later on how and why we use them. Some of you guys will be wondering 'what the heck is a variable?'
Well we can use words (variables) to store things. So if you want to keep track of certain things you can set a variable. As you see here we use errorState to check if there were errors. This variable needs to be set to false at the very beginning of the script with : errorState = false

When you want something to happen when you press a button you have to create something that's called an event.
In our case we have three buttons: InputLoad, Outputset, CreateLib

Below our CreateLib button we are going to program three events (each one for a button)
An event is created like this:

So create the following code below the line 'button CreateLIB "Create Library" pos:[154,280]'


So first of all the inputload-button, here we want to load the source text file (that contains the RAL names and rgb values) Well the code for this is:

Here is how it works :
The first line tells 3dsmax to open the 'open file' dialog, you users can locate to the textfile. Then in the second line we check if the user has choosen a file, if not then set a variable errorState to true
In the third and fourth line we open the file and do a check if that is working.
Finaly we set the label text to our filename. By setting the .text property of our input file name label

The second button is the Outputset.
This buttons is used to set the output file location. The code for this is :


Here we have two variables, SaveLocation and SaveFile.
First we open a 'save file as' dialog with the command getSavePath. We save the in the variable SaveLocation. Next we add a filename to the location. For example if the user has choosen 'C:\Material' as save location, we add '\RAL Material.mat' to the location what give us c:\material\RAL Material.mat

So we have done allot, but are far from finished hahaha
Now we have to do the third button, and this is the more difficult part.

To sum up what we have:
- A input file button that loads our textfile
- A output button that sets the output location and filename
- A couple of buttons on our form to set some material parameters.

So what we have to create now:
1. something to load materialsettings from our interface
2. something to read out the textfile
3. create a material
4. add it into a library
5. and this must be done until we have read to the end of the file.
This is all going to be done if the user clicks on CreateLib, the code for this is : btw you can comment script by using – (text turns green)

First we set two variables to values that have been filled in our interface (amount of glossines and fresnel reflection yes/no).

Next we check if the user has set both the input and output, if not then we set the error variable errorState to true

Between the try and catch() we program the reading from the file and create the material library

We begin with a while loop, this means something like this: Read from the textfile until you have come to the end, and while errorstate=false (no errors)

Then we read a line into a variable inputData, the line may contain some weird characters on the end so we use a methode trimright to get rid of them.
So for example inputData contains '1000 Green beige 204 204 153'
We need to split this into separate words. We use FilterString to do this. Filterstring splits the while line into separate parts. All the words are storred into an array.
In this case our array would look like this :

InputArray[1] = 1000
InputArray[2] = Green
InputArray[3] = Beige
InputArray[4] = 204
InputArray[5] = 204
InputArray[6] = 153

So the idea is now to combine inputarray 1 and 2 and 3 and use 4 5 6 as our RGB values. This is going to work for this, but what happends if we read the next line of the file : 1001 Beige 210 170 90

We the array would look like this

InputArray[1] = 1001
InputArray[2] = Beige
InputArray[3] = 210
InputArray[4] = 170
InputArray[5] = 90

What first was the name of the material (1 2 and 3) is now only 1 and 2. So that means we have to check what part of the line is the name, and what is the RGB values.
This can be done in many ways, b ut I have used the following sollution:

Check the count of the array, then set the name and RGB values.


If there are only 5 values in the array, we use value 1 and 2 for the name and the rest for RGB.
If there are 6 we use 1 and 2 and 3 for the name and the rest for RGB Etc etc
Also I have to convert the RGb values, cause reading from a file gives use a string (pure text) and we need number. This is done by adding 'as float'

Next we check what material type we have to create, I have only createthe vray part (so that is only working right now) if MType.state == 2 do
Now we are gonna create the material with :
new_material = vraymtl name:(MatName) diffuse:(color Rvalue Gvalue Bvalue)
reflection:(Reflcolor.color) reflection_fresnel:(FresBool) reflection_glossiness:(Gloss)
The material is added to the library with : append Mlib new_material
Sooo I hope you guys can follow this. But we are almost at the end.
We only have to save the material library :
saveTempMaterialLibrary Mlib SaveFile
Messagebox "File saved succesfull!!"

When this is done you have reached the end of the script! Yeah.

I hope some of you guys have something usefull learned from this tutorial,
I will make an improved version of this if it is to hard to follow. But I'll need your input and suggestions on this!!


So if you have comments, questions, suggestion you are very welcome to mail me at :

Best regards and happy scripting to you all!

Author: PixelStudio
You may also like...
Chaos Vantage 1.3 released

Chaos Vantage 1.3 released

Chaos Group updated its realtime renderer with new features.


You need to be logged in to leave a comment. Don't have account? Register now.
  • ul. Przedzalniana 8, 15-688 Bialystok, POLAND