Maxscript Tutorial

8/9/2019 Maxscript Tutorial

1/23

6

TECHNOLOGY:

3dsMAXScript Tutorial


2/23

7

TUTORIAL OUTLINE

what is MAXScript?an introduction

basic object creation and manipulationinterfaceexpressionsbasic scriptingintegers, floats, and stringsarrayscreating primitives

transform 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


3/23

2

3ds MAXScriptthe general-purpose scripting language for

3ds Max. MAXScript is used to automate manytasks, including modeling, animation, material

construction, and rendering. It can also be used to

add custom command-panel roll-outs to the userinterface.


4/23

3

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 hasbeen opened or saved, rendering has been started or stopped, object selection has changed and so on.


5/23

4

interface

Listener window -The MAXScript Listener window is aninteractive interpreter for the MAXScriptlanguage. MAXScript is created bytyping it into the listener window andactivating the command.

Macro Recorder Pane-When Macro recorder pane is active all

activity from listener window appears insequence.

Output Pane -Displays the outputs or errors fromexecuted scripts and commands

Mini listener-also an interactive interpreter, the minilistener is a single line window that

shows script currently being edited orexecuted.

F11


6/23

5

expressions

-PATHNAME

-OBJECT

NAME

-PARAME

TER

-VALUE

-PARAMETER

-VALUE

-PARAMETER

-VALUE

INPUT TEXT:OUTPUT TEXT:

CONTROLLER

INPUT TEXT:ERROR TEXT:

INPUT TEXT:EXECUTION TEXT:

-ACTION/FUNCTION

-NAMED

OBJECT

-PARAMETERS

-[x,y,z]DEFINED

VECTOR

FUNCTION ARGUMENT

FUNCTION

Expressions- an instruction to executesomething that will return a value

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

Output text- result of executed expression

Error text -notification of failed input

Execution text - notification of successfulinput

Path name- label assigned to identify anobject in script

Object name - name of element beforepath name is assigned

Parameter- adjustable conditions

Value- assigned parameter of a condition

Controller- an evaluation of an expression

Action/Function- the type of alteration fora parameter in a function argument

Function argument - a controller containingan action or function

Function call-an expression that containsa function argument


7/23

6

basic scripting

Expressions in MAXScript are similar to mathematicalexpressions, in fact the MAXScript listener works like

an elaborate calculator.

Equations (input text) can be entered in the listenerwindow and executed pressing numerical enter orshift enter.

The result (output text) will then appear in blue.

Conventions do exist for organizing scripts, basic

rules to consider:- statements andexpressions can be broken

over multiple lines

- MAXScript is not case sensitive

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

In MAXScript there exists two different kinds ofnumbers. Floats and Integers

An Integeris a whole number, such as 0, 1, 2, 3

A Floatis floating-point number and contains adecimal point, such as 1.25, 2.5, 3.33333333

If the script performed is only made of integers theresult will be whole numbers.

100 + 50 = 150

If the script contains floats the result may havedecimals.

100.00 + 50.00 = 150.00

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

100 + 150.00


8/23

7

integers , floats, stringsNames and titles can be established byusing to indicate a proper name

A call and response can be programedby establishing values using =

Stringsare sequences of symbols ordigits in computer programming thatare given a value.

A undefined stringin MAXScript is anyinput that is executed without firstassigning value. The output text willread undefined.

To define a string:

joke= Why did the chicken cross theroad?

Now MAXScript understands the outputcommand for the input joke.

Strings can be built upon, can containscripts, expressions, and equations.


9/23

8

arraysArraysare an ordered collection ofvalues in MAXScript used to groupmultiple strings or elements into oneexpression.

Elements contained in arrays can beany type of value and multiple valuetypes can be used in one array.

A basic empty array:

#()#: must start expression followed by(element, element)

There is no limit to the number ofelements contained in an array.


10/23

9

creating primitivesHow to create a 3dsMax standardprimitive with no parameters:primitive()

Ex.sphere()

objectname

This action creates the standard primitivebox at (0,0,0). The empty parentheses ()executes with default parameters.

It is important to name objects or createa handle, as they are created so they canbe referred back to in script later.

mybox = box()handle objectname

To create a standard primitive withparameters specific values must beinserted.

mybox = box length:20 width:20 height:20handle objectname parameters

Remember to create a variablename or handle for each object.

mybox=box()


11/23

10

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

mybox.height40.0

mybox.length40.0mybox.width40.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 additionalparameters that can bemodified MAXScript has a builtin search command.

Finding additional parameters:showclass () will listparameter settings for specifiedobject type

showclass box.*


12/23

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 onthe zmove mybox [10,10,10]

Moving a box is additive, if input 3x box willcontinue to move 2,3,4 unites

It is important to note that you are not movingthe object to , but by the amounts.

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 processso no matter how many times to add it to thelistener it will achieve same result.

*scale and parameters are similar.


13/23

12

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 theorientation of a rigid body in 3D space. (X,Y,Z)

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

3. Angle-axisA way to store 3 elements by multiplying the unit rotation axis bythe rotation angle

In this tutorial Euler Angle rotation will be used.

To apply a rotation transform in MAXScript, the first step is todefine the rotation as a sort of rotation object, and then apply therotation 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


14/23

13

assigning modifiersSome modifiers will require preparation formore complex transformations.How to prepare for more complextransformations:

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 inParameters roll-out.

How to create/assign modifiers:

You use the addModifier command and specifythe name of the modifier you want to use andits appropriate parameters.

addModifier mybox (twist angle:30)


15/23

14


16/23

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


17/23

16

MAXScript Editor Short KeysTo execute a script in the script editor they are not executedupon pressing ENTER. In order to execute the entire script, useEvaluate All

FILE COMMANDSThe following menu bar commands and keyboard shortcuts areavailable in the MAXScript Editor. The edit commands listedbelow are also available in the MAXScript Editor right-clickmenu.

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 existingscript. A new MAXScript Editor window then displays theselected script.

File > Close, CTRL+WSaves the contents of the MAXScript Editor to the currentfile name, and then closes the Editor window. If there is nota current file name (that is, the MAXScript Editor window wasopened with File > New), a common File Save dialog is opened.

File > Save, CTRL+SSaves the contents of the MAXScript Editor to the current filename. If there is not a current file name (that is, the MAXScriptEditor window was opened with File > New), a common FileSave dialog is opened.

File > Save AsOpens a common File Save dialog for choosing a new filename used to store the existing script.

File > Evaluate All, CTRL+EEvaluates the entire contents of the MAXScript Editor. This issimilar to selecting all text, and then pressing SHIFT+ENTER. Ithas the advantage that the windows scroll position does not

change.

EDIT COMMANDS

Edit > Undo, CTRL+ZUndoes the last change made to the MAXScript Editorscontent.

Edit > Undo, CTRL+YRedoes the undone changes made to the MAXScript Editorscontent.

Edit > Cut, CTRL+XCopies the selected text to the cut/paste buffer and deletesthe 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 isselected when executing this command, the selected text isreplaced with the cut/paste buffer contents.

Edit > Delete, DELDeletes the selected text.

Edit > Select All, CTRL+ASelects all text in the MAXScript Editor.


18/23

17

MAXScript Editor Short KeysSEARCH COMMANDSSearch > Find Next, CTRL+GRepeats the last Search > Find by finding and selecting thenext occurrence of the Find What text.

Search > Replace, CTRL+HDisplays Replace dialog. Performs search in the MAXScriptEditor for the Find What text, and replaces the matchingtext with the Replace With text. Search can be restricted tooccurrences that are not part of a larger word, or are theexact combination of uppercase and lowercase letters in thespecified text.

Help > Help

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

TAB, CTRL+IIndents selected lines of text by one tab width.

SHIFT+TAB, SHIFT+CTRL+IUnindents selected lines of text by one tab width.

SHIFT+ENTERA MAXScript Editor can send code selections to Listener forevaluation. Select some text in MAXScript Editor and pressSHIFT+ENTER to send the selected text to Listener. Listenercompiles and evaluates it and prints out the result at theend of the current text in Listener. If you press SHIFT+ENTERwith no text selected, the line containing the cursor is sentto Listener for evaluation. This behavior is similar to usingSHIFT+ENTER in Listener, except that the results of the

evaluations are printed in the Listener, not inserted into theMAXScript Editor text.

CTRL+Right-ClickDisplays 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+BSelects the text in the current bracket. Bracket balancer lets

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

CTRL+DPerforms a simple syntax coloring scheme in the MAXScriptEditor. Each time you press CTRL+D, the window is redrawnwith comments in green, MAXScript reserved words in blue, andstring literals in dark red.

CTRL+RPlaces the cursor at the location where it was previously placedwith a mouse click or a find operation. Consecutive uses ofCTRL+R cycle through the last eight cursor positions. Thisfeature is useful if you edit at one location, move the cursorelsewhere with find or scroll operations, and then want to

return to the edit location.

CTRL+JOpens a modal Go To Line Or Character dialog which lets

you enter a line and/or character position to jump to. Thisfeature could be used for example with the line and characternumbers found in the output of the Debugger or in an errormessage in the Listener in 3ds Max 8 and higher. The defaultvalues 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


19/23

18

Condition StatementsMAXScript is used to create a series of actions and a setof 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 evaluatesyour script. The two most useful groups of commandsare the conditional statements and loop statements.

Conditional statements simply tell MAXScript to performa 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 ifthen statement can be expanded to include an else statement.

In addition to color, MAXScript uses numbered lines tohelp organize scripts. Commands can be broken up overseveral lines and tabs or indentations can also be usedto make functions more clear.

Comments/notes can be added within scripts as longas they appear in quotes

The double equal sign in the last statement, == tellsMAXScript 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


20/23

19

FOR Loop StatementsThe second type of command is a Loop statement.Loops are repetitive operations that tell MAXScript torepeat the execution of a collection of commands, orloop.

Loops are similar to PS scripts and are useful for workingwith large groups of objects, making it possible tochange to many objects with one set of commands.

For example, to make 50 boxes use a loop to executethe created command 50 times, rather than creating theboxes with 50 separate commands.

Loops are also useful for changing the properties ofmultiple objects.

There are several different types of loop. The first to beconsidered are for and while loops.

The for loop iterates through a range of numbers, timevalues, or a sequenced collection of values, such as anarray or object set.

Everything inside of the parentheses makes up a block.All loop statements must be created as a block. Thisstatement executes five times. Each time, a new box iscreated.

A for statement starts with the word for.The line, for i = 1 to 5 tells MAXScript to set thevariable i to the value 1, execute the contents of theloop statement, then set the variable i to 2, execute theloop contents, and so on. The variable i is called the

index for the loop. Each repetition of the loop is calledan iteration.


21/23

20

WHILE and DO Loop StatementsIn the case of WHILE and DO loops, expressions arerepeated until MAXScript evaluates the result as false.

The syntax for WHILE and DO loops:

DO LOOPdowhile

WHILE LOOPwhiledoEX.x=10

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


22/23

21

creating floating dialog boxesAnother use for MAXScript is the act of creatinginterfaces to make modeling more efficient and actionseasier 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 areseparated into two or more roll-out sections.Roll-outs can contain many types of controls: Pickbuttons, Image buttons, Text boxes, Spinners, andButtons. (The instructions in this document use Pickbuttons and Buttons that execute or cancel commands.)

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

-- USER INTERFACE ITEMS

FirstDialog = 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 Stretchmodifier \ 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


23/23

41

Cantrell, Bradley, and Natalie B. Yates. Modeling the Environment: Techniques and Tools for the 3D Illustration of DynamicLandscapes. Hoboken, NJ: Wiley, 2012. Print.

Cantrell, Bradley, and Wes Michaels. Digital Drawing for Landscape Architecture: Contemporary Techniques and Tools for DigitalRepresentation 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 ofLandscape 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 ComparativeMedia Studies, 2008. N.p.: n.p., n.d. Print.

IMAGINE DESIGN CREATE: How Designers, Architects, and Engineers Are Changing Our World [Hardcover]. IMAGINE DESIGNCREATE: How Designers, Architects, and Engineers Are Changing Our World: Tom Wujec: 9781595910660: Amazon.com: Books. N.p.,n.d. Web. 29 Nov. 2012. .

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 ResourcesConservation Service, 09 Nov. 2012. Web. 29 Nov. 2012. .

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

USDA. Wetland Indicator Status. 2012 National Wetland Plant List. United States Department of Agriculture, 2012. Web. 29 Nov.2012. .

Documents

Maxscript Tutorial