6

TECHNOLOGY:3dsMAXScript Tutorial

7

TUTORIAL OUTLINE

what is MAXScript?an introduction

basic object creation and manipulationinterfaceexpressionsbasic scriptingintegers, floats, and stringsarrayscreating primitivestransform in scriptmove vs. positionhow to rotate a primitiveassigning modifiers

programming, how to speak in scriptintroducing the script editorMAXScript editor short keysconditional statementsfor loop statementswhile and do loop statementscreating floating dialog boxes

2

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.

3

what is max script?

MAXScript provides users of these products with the ability to:

•Script most aspects of the program’s 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 product’s 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.

4

interface

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.

F11

5

expressions

- PAT

H NA

ME

- OBJ

ECT NA

ME

- PAR

AMET

ER

- VAL

UE

- PAR

AMET

ER

- VAL

UE

- PAR

AMET

ER

- VAL

UE

INPUT TEXT:OUTPUT TEXT:

CONTROLLER

INPUT TEXT:ERROR TEXT:

INPUT TEXT:EXECUTION TEXT:

- ACT

ION/

FUNC

TION

- NAM

ED O

BJEC

T

- PAR

AMET

ERS

- [x,y

,z] DE

FINE

D VE

CTOR

FUNCTION ARGUMENT

FUNCTION

Expressions - an instruction to execute something that will return a value

Input text - expressions, sub-expressions, controllers, functions, notes or identifying text

Output text - result of executed expression

Error text -notification of failed input

Execution text - notification of successful input

Path name - label assigned to identify an object in script

Object name - name of element before path name is assigned

Parameter - adjustable conditions

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 - a controller containing an action or function

Function call- an expression that contains a function argument

6

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

- MAXScript is not case sensitive

- Comments and notes can be added to the script by adding a double-hyphen --

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.

100.00 + 50.00 = 150.00

If the script contains both integers and scripts the default is to floats.

100 + 150.00

7

integers , floats, stringsNames 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.

8

arraysArrays 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.

9

creating primitivesHow 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:20handle objectname parameters

Remember to create a variable name or handle for each object.

mybox=box()

10

transform in scriptUsing the handle the specific objects properties can be accessed easily.

mybox.height 40.0mybox.length 40.0mybox.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

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.* ”

11

move vs. positionHow to apply box transforms:

How to move a box:

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.

12

how to rotate a primitiveRotation has three ways to express values in MAXScript.

1. Euler Angles3 angles introduced by Leonhard Euler used to describe the orientation of a rigid body in 3D space. (X,Y,Z)

2. QuaternionsA number system introduced by William Rowan Hamilton that extends the complex number to calculate 3D rotation.

3. Angle-axisA 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

13

assigning modifiersSome modifiers will require preparation for more complex transformations.

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)

14

15

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 timeMAXScript 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 - GreenEvents (such as on, if, or while) - BlueText strings - Dark RedThe rest of the script remains black.

16

MAXScript Editor Short KeysTo 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 COMMANDSThe 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+NOpens a new MAXScript Editor window for writing a new script.

File > Open, CTRL+OOpens a common File Open dialog for choosing an existing script. A new MAXScript Editor window then displays the selected script.

File > Close, CTRL+WSaves 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+SSaves 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.

File > Evaluate All, CTRL+EEvaluates 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 window’s scroll position does not change.

EDIT COMMANDS

Edit > Undo, CTRL+ZUndoes the last change made to the MAXScript Editor’s content.

Edit > Undo, CTRL+YRedoes the undone changes made to the MAXScript Editor’s content.

Edit > Cut, CTRL+XCopies the selected text to the cut/paste buffer and deletes the text.

Edit > Copy, CTRL+CCopies the selected text to the cut/paste buffer.

Edit > Paste, CTRL+VPlaces 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+ASelects all text in the MAXScript Editor.

17

MAXScript Editor Short KeysSEARCH COMMANDS

Search > Find Next, CTRL+GRepeats the last Search > Find by finding and selecting the next occurrence of the Find What text.

Search > Replace, CTRL+HDisplays 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.

Help > Help Displays the MAXScript Online Reference. Help > About MAXScript Displays About MAXScript dialog.

TAB, CTRL+IIndents 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+Right-Click Displays a pop-up menu of all the utility, structure, user-interface item, function, handler, plug-in, tool, Macro Script, and rcmenu definitions that exist in the current script.

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

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

18

Condition StatementsMAXScript 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.

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.

if mybox.height == 10 thenmybox.width = 20

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

19

FOR Loop StatementsThe 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.

20

WHILE and DO Loop StatementsIn 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 LOOPdo<expr>while<expr>

WHILE LOOPwhile<expr>do<expr> EX.x=10

while x>0 do print (x-=1)

21

creating floating dialog boxesAnother 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.)

To create a floating dialog box, copy and paste this script into the MAXScript editor.

-- USER INTERFACE ITEMSFirstDialog = newRolloutFloater “My First RollOut” 500 500rollout 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 FirstDialogaddrollout SecondRollout FirstDialog

41

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>.