TECHNOLOGY:

3dsMAXScript Tutorial

TUTORIAL OUTLINE
what is MAXScript?
an introduction

basic object creation and manipulation

interface
expressions
basic scripting
integers, floats, and strings
arrays
creating primitives
transform in script
move vs. position
how to rotate a primitive
assigning modifiers

programming, how to speak in script

introducing the script editor
MAXScript editor short keys
conditional statements
for loop statements
while and do loop statements
creating floating dialog boxes

3ds MAXScript

the general-purpose scripting language for

3ds Max. MAXScript is used to automate many
tasks, including modeling, animation, material
construction, and rendering. It can also be used to
add custom command-panel roll-outs to the user
interface.

what is max script?

MAXScript provides users of these products with the ability to:
Script most aspects of the programs use, such as modeling, animation, materials, rendering, and so on.
Control the program interactively through the command-line Listener window.
Package scripts within custom Utility panel roll-outs or floating windows to give them a standard user interface.
Package scripts as macro scripts, and install these macro scripts as buttons in the products toolbars, as items in menus, or assign
them to keyboard shortcuts.
Extend or replace the user interface for objects, modifiers, materials, textures, render effects, and atmospheric effects.
Build scripted plug-ins for custom mesh objects, modifiers, render effects and more.
Build custom import/export tools using ASCII and binary file I/O.
Write procedural controllers that can access the entire state of the scene.
Build batch-processing tools, such as batch-rendering scripts.
Set up live interfaces to external systems through OLE Automation.
Record your actions in the product as MAXScript commands.
Store scripts in scene files to run at each of the supported notification events, for example when a scene has been reset, a file has
been opened or saved, rendering has been started or stopped, object selection has changed and so on.

interface
F11

Listener window The MAXScript Listener window is an

interactive interpreter for the MAXScript
language. MAXScript is created by
typing it into the listener window and
activating the command.
Macro Recorder Pane When Macro recorder pane is active all
activity from listener window appears in
sequence.
Output Pane Displays the outputs or errors from
executed scripts and commands
Mini listener also an interactive interpreter, the mini
listener is a single line window that
shows script currently being edited or
executed.

Expressions - an instruction to execute

something that will return a value

- VALUE

- PARAMETER

- VALUE

- PARAMETER

- VALUE

- PARAMETER

INPUT TEXT:
OUTPUT TEXT:

- OBJECT NAME

- PATH NAME

expressions
Input text - expressions, sub-expressions,
controllers, functions, notes or identifying
text
Output text - result of executed expression
Error text -notification of failed input

CONTROLLER

Execution text - notification of successful

input
Path name - label assigned to identify an
object in script

INPUT TEXT:
ERROR TEXT:

Parameter - adjustable conditions

- [x,y,z] DEFINED VECTOR

- PARAMETERS

INPUT TEXT:
EXECUTION TEXT:

- NAMED OBJECT

- ACTION/FUNCTION

Object name - name of element before

path name is assigned

Value - assigned parameter of a condition

Controller - an evaluation of an expression
Action/Function - the type of alteration for
a parameter in a function argument

FUNCTION ARGUMENT

FUNCTION

Function argument - a controller containing

an action or function
Function call- an expression that contains
a function argument

basic scripting

Expressions in MAXScript are similar to mathematical

expressions, in fact the MAXScript listener works like
an elaborate calculator.
Equations (input text) can be entered in the listener
window and executed pressing numerical enter or
shift enter.
The result (output text) will then appear in blue.
Conventions do exist for organizing scripts, basic
rules to consider:
- statements and
expressions can be broken
over multiple lines

In MAXScript there exists two different kinds of

numbers. Floats and Integers
An Integer is a whole number, such as 0, 1, 2, 3
A Float is floating-point number and contains a
decimal point, such as 1.25, 2.5, 3.33333333
If the script performed is only made of integers the
result will be whole numbers.
100 + 50 = 150
If the script contains floats the result may have
decimals.

- MAXScript is not case sensitive

100.00 + 50.00 = 150.00

- Comments and notes can be added to the script by

adding a double-hyphen --

If the script contains both integers and scripts the

default is to floats.
100 + 150.00

integers , floats, strings

Names and titles can be established by
using to indicate a proper name
A call and response can be programed
by establishing values using =
Strings are sequences of symbols or
digits in computer programming that
are given a value.
A undefined string in MAXScript is any
input that is executed without first
assigning value. The output text will
read undefined.
To define a string:
joke= Why did the chicken cross the
road?
Now MAXScript understands the output
command for the input joke.
Strings can be built upon, can contain
scripts, expressions, and equations.

arrays
Arrays are an ordered collection of
values in MAXScript used to group
multiple strings or elements into one
expression.
Elements contained in arrays can be
any type of value and multiple value
types can be used in one array.
A basic empty array:

#()

#: must start expression followed by

(element, element)
There is no limit to the number of
elements contained in an array.

creating primitives

How to create a 3dsMax standard

primitive with no parameters:
primitive()
Ex.
sphere()

objectname

This action creates the standard primitive

box at (0,0,0). The empty parentheses ()
executes with default parameters.
It is important to name objects or create
a handle, as they are created so they can
be referred back to in script later.
mybox = box()
handle

objectname

To create a standard primitive with

parameters specific values must be
inserted.
mybox = box length:20 width:20 height:20
handle objectname

parameters

Remember to create a variable

name or handle for each object.
mybox=box()
9

transform in script
Using the handle the specific objects properties can be accessed easily.
mybox.height
40.0
mybox.length
40.0
mybox.width
40.0
To change the name:
mybox.name = greenbox
To change the color:
mybox.wirecolor=(red,orange,yellow,green,blue,brown,black,white)
or
mybox.wirecolor=(color 255 0 255)
To change the position:
The position is expressed as the X, Y, Z coordinates.
mybox.pos = [0,-75,0]
To change the size:
The scale property requires a scaling factor for X, Y, and Z axes
mybox.scale = [1,1.5,1]
MAX reads scale box 100%,150%,100%
Note: parameters do NOT change, just MAXworld scale
10

To identify of find additional

parameters that can be
modified MAXScript has a built
in search command.
Finding additional parameters:
showclass () will list
parameter settings for specified
object type
showclass box.*

How to apply box transforms:

How to move a box:

move vs. position

move mybox [x,y,z]

move mybox [2,3,4] this move the box 2
units on the x axis, 3 units on the y, and 4 on
the z
move mybox [10,10,10]
Moving a box is additive, if input 3x box will
continue to move 2,3,4 unites
It is important to note that you are not moving
the object to <x,y,z>, but by the amounts
<x,y,z>.
VS.
How to change the position of a box:
mybox.pos = [10,0,0]
This moves the box to position 10 on X axis,
0 on y, and 0 on x. This is a absolute process
so no matter how many times to add it to the
listener it will achieve same result.
*scale and parameters are similar.

11

how to rotate a primitive

Rotation has three ways to express values in MAXScript.
1. Euler Angles
3 angles introduced by Leonhard Euler used to describe the
orientation of a rigid body in 3D space. (X,Y,Z)
2. Quaternions
A number system introduced by William Rowan Hamilton that
extends the complex number to calculate 3D rotation.
3. Angle-axis
A way to store 3 elements by multiplying the unit rotation axis by
the rotation angle
In this tutorial Euler Angle rotation will be used.
To apply a rotation transform in MAXScript, the first step is to
define the rotation as a sort of rotation object, and then apply the
rotation object to the object you want to rotate.
The rotation object is defined in the following way:
0. *tell MAXScript how you want to rotate
rot_obj = eulerangles x y z *
1. tell MAXScript what rot_obj does
rot_box = eulerangles 0 30 0
2. apply the established rotation function to the intended object
rotate mybox rot_box
12

Some modifiers will require preparation for

more complex transformations.

assigning modifiers

How to prepare for more complex

transformations:
Some transformations need expressed
parameters to be fulfilled.
In the case of mybox:
mybox.lengthsegs = ##
mybox.widthsegs = ##
mybox.heightsegs = ##
mybox.mapCoords = true
This will adjust appropriate settings in
Parameters roll-out.
How to create/assign modifiers:
You use the addModifier command and specify
the name of the modifier you want to use and
its appropriate parameters.
addModifier mybox (twist angle:30)

13

14

introducing the script editor

The next step to create more complex or multi faceted scripts is to utilize the MAXScript Editor. The MAXScript Editor is located
under the MAXScript tab.
MaxScript Listener vs. Max Script Editor
MaxScript Listener if for executing or evaluating one set of information at a time
MAXScript Editor can contain multiple scripts and evaluate them in sections or as one complete script
Scripting language is color coded to assist in the organization of the code.
Comments - Green
Events (such as on, if, or while) - Blue
Text strings - Dark Red
The rest of the script remains black.

15

MAXScript Editor Short Keys

To execute a script in the script editor they are not executed
upon pressing ENTER. In order to execute the entire script, use
Evaluate All
FILE COMMANDS
The following menu bar commands and keyboard shortcuts are
available in the MAXScript Editor. The edit commands listed
below are also available in the MAXScript Editor right-click
menu.
File > New, CTRL+N
Opens a new MAXScript Editor window for writing a new script.
File > Open, CTRL+O
Opens a common File Open dialog for choosing an existing
script. A new MAXScript Editor window then displays the
selected script.
File > Close, CTRL+W
Saves the contents of the MAXScript Editor to the current
file name, and then closes the Editor window. If there is not
a current file name (that is, the MAXScript Editor window was
opened with File > New), a common File Save dialog is opened.
File > Save, CTRL+S
Saves the contents of the MAXScript Editor to the current file
name. If there is not a current file name (that is, the MAXScript
Editor window was opened with File > New), a common File
Save dialog is opened.
File > Save As
Opens a common File Save dialog for choosing a new file
name used to store the existing script.
16

File > Evaluate All, CTRL+E

Evaluates the entire contents of the MAXScript Editor. This is
similar to selecting all text, and then pressing SHIFT+ENTER. It
has the advantage that the windows scroll position does not
change.
EDIT COMMANDS
Edit > Undo, CTRL+Z
Undoes the last change made to the MAXScript Editors
content.
Edit > Undo, CTRL+Y
Redoes the undone changes made to the MAXScript Editors
content.
Edit > Cut, CTRL+X
Copies the selected text to the cut/paste buffer and deletes
the text.
Edit > Copy, CTRL+C
Copies the selected text to the cut/paste buffer.
Edit > Paste, CTRL+V
Places the text in the cut/paste buffer at the cursor. If text is
selected when executing this command, the selected text is
replaced with the cut/paste buffer contents.
Edit > Delete, DEL
Deletes the selected text.
Edit > Select All, CTRL+A
Selects all text in the MAXScript Editor.

SEARCH COMMANDS

MAXScript Editor Short Keys

Search > Find Next, CTRL+G

Repeats the last Search > Find by finding and selecting the
next occurrence of the Find What text.

CTRL+Right-Click
Displays a pop-up menu of all the utility, structure, userinterface item, function, handler, plug-in, tool, Macro Script,
and rcmenu definitions that exist in the current script.

Search > Replace, CTRL+H

Displays Replace dialog. Performs search in the MAXScript
Editor for the Find What text, and replaces the matching
text with the Replace With text. Search can be restricted to
occurrences that are not part of a larger word, or are the
exact combination of uppercase and lowercase letters in the
specified text.

CTRL+B
Selects the text in the current bracket. Bracket balancer lets
you check bracket balancing in long bits of code. The balancer
works with any of the following: (), [], and {}. To use it, place the
cursor anywhere in the script text and press CTRL+B. I

Help > Help

Displays the MAXScript Online Reference.
Help > About MAXScript
Displays About MAXScript dialog.
TAB, CTRL+I
Indents selected lines of text by one tab width.
SHIFT+TAB, SHIFT+CTRL+I
Unindents selected lines of text by one tab width.
SHIFT+ENTER
A MAXScript Editor can send code selections to Listener for
evaluation. Select some text in MAXScript Editor and press
SHIFT+ENTER to send the selected text to Listener. Listener
compiles and evaluates it and prints out the result at the
end of the current text in Listener. If you press SHIFT+ENTER
with no text selected, the line containing the cursor is sent
to Listener for evaluation. This behavior is similar to using
SHIFT+ENTER in Listener, except that the results of the
evaluations are printed in the Listener, not inserted into the
MAXScript Editor text.

CTRL+D
Performs a simple syntax coloring scheme in the MAXScript
Editor. Each time you press CTRL+D, the window is redrawn
with comments in green, MAXScript reserved words in blue, and
string literals in dark red.
CTRL+R
Places the cursor at the location where it was previously placed
with a mouse click or a find operation. Consecutive uses of
CTRL+R cycle through the last eight cursor positions. This
feature is useful if you edit at one location, move the cursor
elsewhere with find or scroll operations, and then want to
return to the edit location.
CTRL+J
Opens a modal Go To Line Or Character dialog which lets
you enter a line and/or character position to jump to. This
feature could be used for example with the line and character
numbers found in the output of the Debugger or in an error
message in the Listener in 3ds Max 8 and higher. The default
values in the dialog will be set to the current cursor position.
MAXScript Editor Commands. Web log post. CG PLUS. N.p.,
n.d. Web. 06 Dec. 2012
17

Condition Statements
MAXScript is used to create a series of actions and a set
of rules for how 3dsMAX will execute those actions.
These rules are set up in commands that allow you to
control the path that the software follows it evaluates
your script. The two most useful groups of commands
are the conditional statements and loop statements.
Conditional statements simply tell MAXScript to perform
a specified command if a certain condition is met.

if mybox.height == 10

Ex.
if mybox.height == 10 then mybox.width = 20
To add another layer of information or function an if
then statement can be expanded to include an else
statement.
In addition to color, MAXScript uses numbered lines to
help organize scripts. Commands can be broken up over
several lines and tabs or indentations can also be used
to make functions more clear.
Comments/notes can be added within scripts as long
as they appear in quotes
The double equal sign in the last statement, == tells
MAXScript to compare two values.
The single = sign always signifies assignment.

18

== equal to
!= not equal to
> greater than
>= greater than or equal to
< less than
<= less than or equal to

thenmybox.width = 20

FOR Loop Statements

The second type of command is a Loop statement.
Loops are repetitive operations that tell MAXScript to
repeat the execution of a collection of commands, or
loop.
Loops are similar to PS scripts and are useful for working
with large groups of objects, making it possible to
change to many objects with one set of commands.
For example, to make 50 boxes use a loop to execute
the created command 50 times, rather than creating the
boxes with 50 separate commands.
Loops are also useful for changing the properties of
multiple objects.
There are several different types of loop. The first to be
considered are for and while loops.
The for loop iterates through a range of numbers, time
values, or a sequenced collection of values, such as an
array or object set.
Everything inside of the parentheses makes up a block.
All loop statements must be created as a block. This
statement executes five times. Each time, a new box is
created.
A for statement starts with the word for.
The line, for i = 1 to 5 tells MAXScript to set the
variable i to the value 1, execute the contents of the
loop statement, then set the variable i to 2, execute the
loop contents, and so on. The variable i is called the
index for the loop. Each repetition of the loop is called
an iteration.
19

WHILE and DO Loop Statements

In the case of WHILE and DO loops, expressions are
repeated until MAXScript evaluates the result as false.
The syntax for WHILE and DO loops:
DO LOOP
do<expr>while<expr>
WHILE LOOP
while<expr>do<expr>
EX.
x=10
while x>0 do print (x-=1)

20

Another use for MAXScript is the act of creating

interfaces to make modeling more efficient and actions
easier to execute.
The basic components of a floating dialog box are:
Dialog: a window with a customized docked command
panel that uses and interface to represent script
Roll-outs: These are the sections within the dialog.
Most of the areas in the Command Panel, notice they are
separated into two or more roll-out sections.
Roll-outs can contain many types of controls: Pick
buttons, Image buttons, Text boxes, Spinners, and
Buttons. (The instructions in this document use Pick
buttons and Buttons that execute or cancel commands.)

creating floating dialog boxes

To create a floating dialog box, copy and paste this
script into the MAXScript editor.
-- USER INTERFACE ITEMS
FirstDialog = newRolloutFloater My First RollOut 500 500
rollout FirstRollout This is the first section:
(
button btn_one I am thirsty. \
tooltip: Press this button to create a sphere \
pickbutton btn_two Squash Object \
tooltip: Press this button to add the Stretch
modifier \
enabled:false \
on btn_one pressed do
(
s = teapot radius:50
btn_two.enabled = true
btn_one.enabled = false
)
on btn_two picked obj do
(
Stretcher obj
btn_two.text = obj.name
btn_two.enabled = false
)
)
rollout SecondRollout This is the second section:
(
button go_away I am finished.
tooltip: This will close your Floating Dialogorama \
on go_away pressed do
(
closeRolloutFloater FirstDialog
)
)
addrollout FirstRollout FirstDialog
addrollout SecondRollout FirstDialog

21

Cantrell, Bradley, and Natalie B. Yates. Modeling the Environment: Techniques and Tools for the 3D Illustration of Dynamic
Landscapes. Hoboken, NJ: Wiley, 2012. Print.
Cantrell, Bradley, and Wes Michaels. Digital Drawing for Landscape Architecture: Contemporary Techniques and Tools for Digital
Representation in Site Design. Hoboken, NJ: John Wiley & Sons, 2010. Print.
Cropp, Audrey M. From Digital Memory: A Cloud for Our Cultural Heritage. Thesis. Robert Reich School of
Landscape Architecture, Louisiana State University, 2012. Baton Rouge: n.p., 2012. Print.
Danziger, Michael. Information Visualization for the People. Thesis. Massachusetts Institute of Technology, Dept. of Comparative
Media Studies, 2008. N.p.: n.p., n.d. Print.
IMAGINE DESIGN CREATE: How Designers, Architects, and Engineers Are Changing Our World [Hardcover]. IMAGINE DESIGN
CREATE: How Designers, Architects, and Engineers Are Changing Our World: Tom Wujec: 9781595910660: Amazon.com: Books. N.p.,
n.d. Web. 29 Nov. 2012. <http://www.amazon.com/IMAGINE-DESIGN-CREATE-Designers-Architects/dp/1595910662>.
Khaslavsky, Julie, and Nathan Sherdoff. Understanding the Seductive Experience. Communications of the ACM May 1999: n. pag.
ACM Digital Library. Web. 29 Nov. 2012.
MAX Script 101. Dir. John Wainwright. Perf. John Wainwright. Vimeo, 2011. Online Video Tutorial.
Murdock, Kelly. 3ds Max Bible. Hoboken, NJ: Wiley, 2008. Print
NRCS. Conservation Plant Releases - Golden Meadow Plant Materials Center. Conservation Plant Releases. Natural Resources
Conservation Service, 09 Nov. 2012. Web. 29 Nov. 2012. <http://plant-materials.nrcs.usda.gov/lapmc/releases.html>.
Treib, Marc. Representing Landscape Architecture. London: Taylor & Francis, 2008. Print.
USDA. PLANTS Database. USDA PLANTS. United States Department of Agriculture, n.d. Web. 29 Nov. 2012. <http://plants.usda.
gov/>.
USDA. Wetland Indicator Status. 2012 National Wetland Plant List. United States Department of Agriculture, 2012. Web. 29 Nov.
2012. <http://plants.usda.gov/wetland.html#subregions>.

41